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

[charlieforward9]

Use one public TreeLayer for supplied rows or geographic getTileData inventory streaming with the same top-level accessors. An internal tile component owns traversal, cache/request limits and covered replacement. WorldTreeLayer remains a deprecated wrapper for existing treeProps callers.

Retain parent coverage until children are ready and preserve original owner picking across merged batches. Distant-crown picks include tile/source-tile metadata. Public streamingStats distinguish inventory residency from canopy/shadow submissions. Shared parent quotas retain each child's local caps.

Reject simultaneous nonempty data and getTileData; mode changes rebuild the renderer without recursive traversal or duplicate IDs. Interrupted replacements retime connected coverage contributors while independent neighboring fades finish on schedule. Numeric coverage accessors invalidate tree attributes without manual triggers. Strict playground schemas expose the same flat public inventory API.

Base: #794. Coit depends directly on #814 and does not require this PR. Geographic inventory traversal and Cartesian RAD hierarchy selection keep their own source contracts.

Final integration validation: immutable install, lint, package build, strict public/example types, production example bundles and website build pass. All 1,128 Node tests and 22 renderer browser contracts pass. All 28 Tree Lab, Citrus, forest and world application cases pass across the full-suite and focused final-fixture reruns. Renderer tests require software WebGPU and exercise both sorted backends.

The inventory browser fixture waits for the destination camera pages before asserting that coverage-only edits retain row-array identity.

Stack graph:

flowchart TD
  M[master] --> A["#807 prepared Composite SplatLayer"]
  A --> B["#814 shared static/RAD scenes"]
  B --> C["#794 native TreeLayer"]
  C --> D["#806 unified inventories"]
  D --> E["#808 tree examples"]
  E --> F["#809 migration / three removal"]
  B --> G["#815 independent Coit"]
  L["luma 9.4-release"] --> H["luma #3398 host/RAD support"]
  H -. compatible release .-> B

Loading

Full stack record.

[github-actions]

Coverage

Stmts: 40.21% ▲+6.76% | Branch: 31.30% ▲+7.10% | Funcs: 33.52% ▲+5.48% | Lines: 39.71% ▲+6.33%

Test Files 136 passed (136)

[greptile-apps]

Confidence Score: 2/5

[Medium risk] Adds geographic streaming mode to the tree rendering layer.

The PR still needs fixes for the registry completeness check, lower child caps, and inherited shared budgets before merging.

Findings

1.  Playground rejects streamed trees ▶
2.  Child budgets are ignored ▶
3.  Streamed trees escape shared limits ▶
4.  Distant crowns ignore focus settings ▶

Summary

TreeLayer supports supplied rows and geographic streaming through one public API. WorldTreeLayer remains a deprecated wrapper.

• Adds bounded tile requests, page fades, shared rendering budgets, and streaming counters.
• Adds flat streaming props to playground schemas and documents the source contract.
• Since the last review, only the browser test changed. It now waits for destination pages before checking coverage-only edits.
• No new findings were accepted.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[TreeLayer] --> B{Input}
  B -->|data| C[Tree renderer]
  B -->|getTileData| D[TreeTileLayer]
  E[WorldTreeLayer compatibility wrapper] --> D
  D --> F[Bounded geographic tiles]
  F --> G[Page coverage fades]
  G --> C
  G --> H[Distant crown splats]

Loading

_{Reviews (18) · Last reviewed commit: "test(layers): wait for destination tree ..." · 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.

[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 34b2bd2. Configure here.}

[greptile-apps]

Playground rejects streamed trees

TreeLayer now accepts getTileData and inherits streaming defaults, but TreeLayerPropsSchema still lists only row-mode props. Playground rejects documents using the recommended streaming API because defineLayer makes the schema strict. The registry completeness test also fails on new defaults such as transitionDuration and maxVisibleTiles.

Add the public streaming props to TreeLayerPropsSchema and exclude internal-only defaults from the completeness check.

Knowledge Base Used: Playground and template workflow

[greptile-apps]

Child budgets are ignored

When a host supplies lower limits through _subLayerProps.trees, getSubLayerProps applies them first. These later assignments replace maxCanopySplats, maxShadowSplats, and maxCanopyPixels with the inventory-wide values. Nearby trees therefore ignore the host's lower limits, despite the documented promise that nested tree caps remain effective.

Keep the shared parent budget, but preserve a lower child cap.

[greptile-apps]

Streamed trees escape shared limits

When a host supplies _splatBudgetGroup to share a rendering limit across sibling layers, a streamed TreeLayer stops honoring that limit. The public layer forwards the group, but TreeTileLayer creates its own group without connecting its parent. Near trees and distant crowns can therefore spend their own allowance on top of the siblings' work.

Set the inventory group's parent from the inherited group, and refresh that link when props change.

[greptile-apps]

Distant crowns ignore focus settings

TreeLayer exposes foveationStrength in streaming mode, but distant crowns always receive 1. Setting it to 0 disables the preference for central detail on nearby trees but not distant crowns. Forward the authored value so hosts can control detail consistently across both representations.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!