feat(layers): prepared Composite SplatLayer and shared budgets

[charlieforward9]

Introduce the public Composite SplatLayer for prepared assets and owner rows, with shared local/parent/frame budgets, spatial selection, materials, wind and projected shadows. Preserve legacy source/hierarchy input alongside direct prepared-data input.

Retained shadow selections track replacement asset offsets and new geographic origins, including refill after an empty inventory. Camera and light error use each owner's local metric scale. Budget allocation skips dominated levels in nonmonotonic supplied hierarchies, retaining coverage without overcharging refinement.

Base: master. The shared scene runtime in #814 builds on this PR independently of TreeLayer.

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.

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: 35.90% ▲+2.45% | Branch: 26.40% ▲+2.20% | Funcs: 30.15% ▲+2.11% | Lines: 35.60% ▲+2.22%

Test Files 122 passed (122)

[greptile-apps]

Confidence Score: 5/5

[Medium risk] Adds a new rendering layer for Gaussian splats.

The PR appears safe to merge; the three numbered previous findings are addressed and no new blocking issue was found.

What we checked:

• Detail jumps keep valid levels: nextLevel stops at the requested level. The allocator restores a blend only when it reaches that exact level.
• Shadow rebuilds use current owners: updateState installs the new hierarchy before refreshing shadow selection. Publishing demand does not run an allocation callback during that refresh.

Summary

Adds public SplatLayer support for prepared assets and owner rows, shared detail budgets, deformation, picking, and optical shadows.

• The latest changes fix all three numbered findings from the previous review.
• Budget selection can skip expensive supplied intermediate levels.
• Camera and shadow detail estimates use owner-local metre scales.
• Rebuilt owners are available before shadow selection computes its origin.
• No new actionable issues were found.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A["Prepared asset or owner rows"] --> B["Resolve sources and hierarchies"]
  B --> C["Prepare owner transforms and bounds"]
  C --> D["Camera selection"]
  C --> E["Light-space selection"]
  D --> F["Shared budgets"]
  E --> F
  F --> G["Retained optical fades"]
  G --> H["Weighted camera rendering"]
  G --> I["Host optical shadow pass"]

Loading

_{Reviews (7) · Last reviewed commit: "Refine supplied splats at owner-local sc..." · Reviewed by Greptile}

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

[ibgreen]

Reviewed the prepared-source/input API, CompositeLayer/primitive boundary, shared selection budgets, immutable source caching, refinement/coverage behavior, shadows and owner picking.

Fit: the generic SplatLayer belongs in layers, with botany and example-specific logic kept out. The prepared asset descriptor and per-owner getSource API provide reusable composition for TreeLayer and other consumers. Internal source/hierarchy/budget helpers are suitably separated.

API follow-ups: make the distinction between settled submission caps, coverage floors, transition headroom and hard GPU-memory limits prominent; users should not interpret maxSplats/maxTotalSplats as hard memory caps. Keep the legacy source/hierarchy path documented as compatibility input and prefer prepared descriptors in new examples.

Hosted lint, Node, headless and website checks pass, and no unresolved inline threads were present. The final mergeability recheck reports conflicts with master; rebase/reconcile and revalidate before landing.

Approved with that merge gate. This was source/diff and hosted-CI review; no local suites rerun.