feat(layers): shared static and RAD SplatLayer scenes

[charlieforward9]

Add sorted Cartesian scenes to the public Composite SplatLayer: URL/Blob/static/RAD assets, off-thread workers, shared deck/device source residency, global per-view/domain ordering, affine/SH instance handling, owner picking and host-pass presentation. Prepared weighted inputs retain their existing wind, material and shadow path.

Stack: master (#807 landed) → #794 → #806 → #808 → #809 → #814 → #815. Base: #809. Scene APIs remain independent of TreeLayer APIs; the linear landing order resolves overlapping exports, docs, schemas and CI before merge.

Scene submission follows Deck's ancestor/root filters, actual picking pass and cull rectangle. Query-only candidates remain staged until that pass; incompatible picking buffers retire per viewport. Source caching follows data and explicit update triggers. Multi-depth picking excludes whole owners and restores them after the query; prepared-only globe/wrapped-view guards run after scene routing so filtered sibling views cannot block scene initialization. Unsupported projections report recoverable layer/view errors before allocation, preserving supported sibling layers/views. RAD refinement requires perspective Cartesian views; static/prepared sorted scenes also support orthographic views. Drawing and picking share the same physical-pixel ratio, including the device-context fallback.

Hiding every scene owner discards completed hidden selections and queued decoded uploads, releases transient pins after all in-flight selectors settle, and preserves root/presented coverage. Late decode, GPU admission and worker acknowledgement follow the same cleanup; returning views request fresh refinement. Initial root loading still completes while hidden.

A terminal RAD failure stops queued work and releases unused traversal/admission pins only after every view selection settles. Root and presented/per-view frontiers remain protected, including when an upload finishes after failure.

The final parent also includes Farm’s bounded GPU-drain/remount fixture. That fixture changes no production code; the scene lifecycle repairs are described above.

Validation:

• Root yarn, repository build, strict public consumer types, final yarn lint-fix and diff check.
• 150 Node files: 1,290 passed, 10 skipped. Focused regressions reproduced projection, picking and hidden-resource defects before the corresponding fixes; coverage includes orthographic OrbitView, mixed views, data-change recovery and omitted-context DPR 2 picking. Seven hidden-owner regressions cover staged/in-flight selections, queued/late uploads, admission acknowledgements and initial root loading. Five terminal-error regressions also cover sibling selections, queued/late uploads and unrelated source failures. Six real browser regressions reproduce and verify deep owner picking and filtered globe/repeated-map siblings on both backends.
• Integrated real software WebGL2/WebGPU: 24 Tree/prepared/scene checks passed, no skips. All 54 example Node tests pass; standalone Tree Lab/Farm types passed on the same source stack.
• Website workspace yarn/build: 191 pages. Native adversarial source review and fresh hosted checks must pass on the final head.

Publication hold: upstream luma #3398 is merged, but published @luma.gl/splats 9.4.2 still needs the repository compatibility patch. Publish community scene packages after a compatible luma release, patch removal and packaged-consumer verification. Sorted geospatial/globe and RAD orthographic views, hard byte accounting, shared best-first selection across independent RAD hierarchies and scalable WebGL2 ordering remain explicit limits. Software rendering checks do not establish hardware performance.

---

Note

High Risk
Large new GPU/rendering pipeline with workers, shared runtime budgets, and projection/view constraints (RAD perspective-only); errors in residency or ordering could affect frame stability and picking.

Overview
Adds sorted Cartesian scene rendering to public SplatLayer, beyond the existing weighted prepared path. Scene URLs/Blobs/RAD/static descriptors route through a new SplatSceneLayer and shared SplatSceneRuntime effect that owns per-view/sortDomain global ordering, shared source residency, budgets with prepared layers, and owner picking.

Loading and refinement run off-thread via RAD and static workers (PageScheduler, RADScene, worker-side RADSelectionEngine), with GPU upload pacing, multi-view selection, and status callbacks (onStatusChange). WebGPU uses luma’s paged renderer; WebGL2 uses CPU-sorted SplatCPUSceneRenderer. transparency defaults to auto (weighted prepared vs sorted scenes); new props include maxResidentSplats, maxConcurrentLoads, sortDomain, and workerFactory.

Package wiring adds loaders/luma splats deps, worker sideEffects and export paths, an esbuild worker build script, expanded API/docs/upgrade notes, and CI includes splat-scene.browser.spec.ts. Publication still depends on an upstream luma 9.4 host-pass release (repo patch today).

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

[github-actions]

Coverage

Stmts: 40.90% ▲+4.72% | Branch: 31.79% ▲+5.42% | Funcs: 34.51% ▲+3.51% | Lines: 40.50% ▲+4.47%

Test Files 150 passed (150)

[cursor]

Stale Bugbot comment from a previous run.

[greptile-apps]

Confidence Score: 5/5

[High impact] The reviewed changes appear safe to merge; the hidden-scene cleanup finding is fixed.

Summary

SplatLayer adds shared sorted Cartesian scenes for static and RAD assets, with workers, shared source memory, owner picking, and per-view ordering.

• Since the previous review, hidden RAD scenes release completed refinement pins and discard cancelled decoded uploads.
• Root and last-visible coverage remain available when owners return.
• The numbered previous finding is fixed. No new actionable issues were found.
• Earlier threads manually resolved without explanatory replies were checked against the current diff; their fixes remain present.
• Package publication remains on hold until a compatible luma release replaces the repository patch.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Owners become hidden] --> B[Cancel page demand]
  B --> C[Discard queued decoded uploads]
  B --> D{Selection has settled?}
  D -- No --> E[Keep temporary page pins]
  E --> F[Worker replies finish]
  D -- Yes --> G[Release unused page pins]
  F --> G
  G --> H[Keep root and last-visible coverage]
  H --> I[Owners return]
  I --> J[Request fresh selection]

Loading

_{Reviews (20) · Last reviewed commit: "fix(layers): settle hidden RAD refinemen..." · 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 shared scene/runtime boundary, URL/Blob descriptors, source/worker lifecycle, RAD paging/admission/selection, per-view/domain ordering, owner picking, prepared/scene routing and shared budget integration.

Fit: SplatLayer should remain the single public facade; format decoding belongs to loaders.gl, GPU paging/sorting to luma.gl, and host/view/accessor integration here. Sharing source identity and residency across owners avoids embedding Coit- or Tree-specific behavior in the runtime.

Publication gate: this implementation relies on the repository's @luma.gl/splats patch. Publish only after a compatible released luma 9.4 package includes the host/RAD APIs and the development patch is removed; verify an external consumer of the packaged ESM/CJS builds and workers.

API follow-ups: document which render settings are shared within a sortDomain, and keep maxActiveSplats visibly a compatibility alias for maxSplats rather than a second independent quota. A requested maxConcurrentLoads change should have an explicit runtime contract.

Approved against #807. Hosted checks pass; no unresolved inline threads at review time. No local suites rerun.