feat(layers): unify TreeLayer array and streamed inventory APIs

[charlieforward9]

Use one TreeLayer for supplied rows and bounded geographic inventories through getTileData. Both paths share top-level tree traits, seasons, wind, crops, picking and submission budgets. WorldTreeLayer remains a deprecated compatibility wrapper.

Base: #794. Remaining merge order: #794 → #806 → #808 → #809; #807 has landed on master. The scene extension and Coit follow #809 in the landing stack (#814 → #815); the tree API has no scene-runtime prerequisite.

Geographic sources return bounded individual rows and source-built distant crowns. Abortable requests, finite frontiers, decoded cache statistics, replacement coverage and frame-time feedback retain nearby detail without constructing a global inventory. Coverage floors and cache eviction targets are documented; no hardware frame-rate guarantee is claimed.

Review repairs preserve inline getTreeKey batches according to deck.gl update triggers, apply numeric layer coverage and distant overrides to aggregate crowns, retain the source sublayer when clearing hover highlights, and preserve distant-crown child color accessors with their matching update triggers. Removing a color override restores the parent accessor and trigger. The migration guide covers the flat API and compatibility defaults.

Validation: root Yarn install, all-package build, strict consumers, 145 Node files (1,199 passed; 9 skipped), five required-WebGPU tree/inventory browser checks, website workspace install/build (193 Markdown pages), and final lint-fix. Browser regressions read zero distant-crown pixels and picks at coverage zero, restore them at one, and verify identity regrouping/transitions. Fresh hosted CI must pass on this restacked head.

---

Note

Medium Risk
Adds a large composite streaming path (tile loading, budgets, transitions) on top of TreeLayer/SplatLayer; behavior and performance depend on host getTileData contracts and MapView/Web Mercator assumptions, though WorldTreeLayer preserves backward compatibility.

Overview
TreeLayer now supports the same public API for in-memory rows and geographic streaming via optional getTileData, with tree accessors (getHeight, getSeason, wind, etc.) at the top level and getDistantCanopyColor for coarse crown clusters. Supplying both nonempty data and getTileData throws; streaming mode delegates to a new internal TreeTileLayer that tiles the viewport, validates page payloads, crossfades coverage on zoom/pan, and exposes streamingStats.

Streaming adds TreeTileset (bounded tile frontier), TreeCoverageTransition (optical page replacement), TreeFrameBudget / deck TreeBudgetEffect (hysteretic Gaussian budget scaling from frame times), and shared Gaussian distant-crown templates. Near trees still render through TreeLayer; distant groups use SplatLayer.

WorldTreeLayer remains exported as a deprecated thin wrapper over the tile path (legacy treeProps / budget defaults). Docs, what's-new, package exports, playground Zod schemas, and registry tests are updated so JSON configs expose the flat inventory API without internal tile hooks.

^{Reviewed by Cursor Bugbot for commit a1858de. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Coverage

Stmts: 39.03% ▲+2.85% | Branch: 29.62% ▲+3.25% | Funcs: 32.68% ▲+1.68% | Lines: 38.66% ▲+2.63%

Test Files 145 passed (145)

[greptile-apps]

Confidence Score: 5/5

[High impact] The changes since the previous review appear safe to merge.

Summary

TreeLayer supports supplied rows and bounded geographic inventories through one flat API. WorldTreeLayer remains a deprecated wrapper.

• Since the previous review, distant crowns now honor child color overrides.
• Added tests check the override and the return to parent colors after removal.
• No new actionable issues were found in these changes.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[TreeLayer] --> B{Input}
  B -->|data| C[Individual trees]
  B -->|getTileData| D[TreeTileLayer]
  E[WorldTreeLayer compatibility wrapper] --> D
  D --> C
  D --> F[Distant crowns]
  C --> G[Shared Gaussian budgets]
  F --> G

Loading

_{Reviews (24) · Last reviewed commit: "fix(layers): honor distant crown color o..." · Reviewed by Greptile}

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[cursor]

Stale Bugbot comment from a previous run.

[ibgreen]

Reviewed the supplied-row/streamed TreeLayer routing, internal tile traversal, coverage transitions, deduplication, picking metadata, statistics and schemas.

Fit: one public TreeLayer with flat accessors and a private tile component is preferable to parallel public renderers. WorldTreeLayer is appropriately retained as a deprecated compatibility wrapper. Geographic inventory traversal should stay separate from Cartesian RAD selection.

Confirmed remaining issues in TreeTileLayer:

• The inventory splatBudgetGroup never receives the inherited _splatBudgetGroup as parent, so streamed trees can escape a shared sibling/ancestor allowance.
• renderLayers applies getSubLayerProps and then overwrites maxCanopySplats/maxShadowSplats/maxCanopyPixels, defeating lower host child overrides. Preserve lower child caps while retaining the parent allowance.
• Distant crowns hard-code foveationStrength: 1 instead of honoring the authored public setting.

The older strict-schema thread appears addressed by the added streaming props; verify and close that stale thread separately. The budget/focus threads still need fixes and focused contracts.

Hosted checks pass. Approval submitted as requested by the maintainer; these actionable issues still need resolution before landing. No local suites rerun.

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit a1858de. Configure here.}