@displayxr/inline3d 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ entry points (`.`, `./three`) are frozen for 1.x, while the **scene subpaths** (
 `./splat`, `./model`) are a preview tier whose options may change in any release. Entries below say
 which tier they touch, because that is what tells you whether an upgrade can move your pixels.
 
+## 1.9.0 — 2026-09-23
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). Additive: nothing changes for
+Spark callers or for flat `.sog` files.
+
+### Added
+
+- **Streamed SOG on the PlayCanvas backend** (epic #36 P2).
+  - Pass the URL of the `lod-meta.json`, or of the directory holding it. Bytes of a
+    `lod-meta.json`, or a streamed URL with `engine: 'spark'`, throw at call time with a message
+    saying what to pass instead.
+  - `splatBudget` is **per tile, all views included**: one engine camera renders every view, so
+    both eyes share one budget. It defaults to **600k** on a Streamed SOG when unset, and
+    `perf: false` keeps the engine's 1M.
+  - New `perf` keys pass through: `lodMode`, `lodUpdateDistance`, `lodUpdateAngle`,
+    `lodUnderfillLimit` (unset = engine default).
+  - New **`handle.stats()`**: `resident`, `peakResident`, `budget`, `numSplats`, `views`,
+    `lodLevels`, `files`, `filesLoaded`, `firstFrameMs`.
+  - Framed from its octree leaf boxes, not the root bound. The `camera` block is read from the
+    top level of `lod-meta.json`.
+  - Measured on a 5.88M-gaussian captured scene (M1 Pro): first frame 2.9 s against 20.8 s flat
+    at 100 Mbit/s, and 9.6 ms against 117 ms for two 1080p views. It is not a byte saving at a
+    close framing. Recipe and tables: [`docs/playcanvas-adapter.md`](docs/playcanvas-adapter.md)
+    §Streamed SOG.
+
 ## 1.8.0 — 2026-09-22
 
 Touches the **preview tier** (`./splat`, plus one additive `./three` export). **Existing callers get

package/README.md

@@ -51,6 +51,15 @@ optional peer `playcanvas` (`>=2.22.3 <3`) and reads `.sog`, `.ply` and a Stream
 Bundlers: the engine is a literal `import('playcanvas')`; its sort workers are Blob URLs (CSP
 `worker-src blob:`), and esbuild needs `node:worker_threads` marked external.
 
+**Large scenes stream (preview).** On `engine: 'playcanvas'`, a Streamed SOG streams: pass the URL
+of its `lod-meta.json` (or of its directory), not its bytes. The engine fetches only the chunks
+the view needs and draws at most `perf.splatBudget` of them. That budget is per tile and shared
+by every view of the tile; it defaults to 600k on a Streamed SOG. `handle.stats()` reports what
+is resident. This is for big captured scenes, several million gaussians and up. A photo lift is
+one dense sheet that is fully on screen, so it gains nothing from streaming. How to produce, serve
+and budget one, with measurements:
+[`docs/playcanvas-adapter.md` §Streamed SOG](docs/playcanvas-adapter.md#streamed-sog-p2).
+
 Stability & what's covered by semver (and the deferred N-view / web-components / CSS-native roadmap
 that is intentionally **not** in 1.0): [`docs/sdk-stability.md`](docs/sdk-stability.md).
 

package/js/inline3d-splat-perf.js

@@ -269,8 +269,9 @@ export function splatPerfMeshOptions(perf) {
 // | `lod`, `lodSplat*`, `maxPixelRadius`, `falloff`, `alphaFloor` | none | Spark-only; ignored with one warning. The engine's splat-count lever is `splatBudget` (below) |
 //
 // Engine-native keys may be passed in an options object as well and win over the mapping:
-// `alphaClipForward`, `minPixelSize`, `splatBudget` (a global splat count, per app = per tile),
-// `antiAlias` (only for AA-trained assets).
+// `alphaClipForward`, `minPixelSize`, `splatBudget` (a splat count per tile, all views included —
+// SPLAT_BUDGET_MODEL), `antiAlias` (only for AA-trained assets), and the Streamed-SOG knobs
+// `lodMode`, `lodUpdateDistance`, `lodUpdateAngle`, `lodUnderfillLimit` (PC_LOD_NUMERIC below).
 //
 // `minPixelSize` IS THE ONE DEFAULT CHANGED. The engine drops every splat whose quad is under
 // 2 px by default; Spark keeps them (its `minPixelRadius` default is 0). On a lifted photograph
@@ -284,6 +285,100 @@ export const PLAYCANVAS_QUAD_SIGMA = Math.sqrt(8);
 /** Knobs that are engine-native and pass straight through to `app.scene.gsplat`. */
 const PC_NATIVE = ['alphaClipForward', 'minPixelSize', 'splatBudget'];
 
+/**
+ * The Streamed-SOG (`lod-meta.json`) knobs, engine-native, passed straight through. Each one is
+ * its own kill switch: UNSET means the engine's default, never a value of ours. Numbers only,
+ * except `lodMode`, which the engine accepts as `'distance'` or `'error'` and silently ignores
+ * otherwise (so it is validated here, loudly).
+ *
+ * | key | engine default (2.22.3) | what it does |
+ * |---|---|---|
+ * | `lodMode` | `'distance'` | how a node's LOD is chosen: camera distance, or the per-chunk error table |
+ * | `lodUpdateDistance` | `1` (world units = the file's own units) | camera travel before LOD is re-evaluated |
+ * | `lodUpdateAngle` | `0` (off) | camera rotation, in degrees, before LOD is re-evaluated |
+ * | `lodUnderfillLimit` | `0` (off) | how many coarser levels may stand in while a finer one streams |
+ *
+ * None of them does anything on a flat `.sog`/`.ply` — there is no octree to choose in.
+ */
+const PC_LOD_NUMERIC = ['lodUpdateDistance', 'lodUpdateAngle', 'lodUnderfillLimit'];
+const PC_LOD_MODES = ['distance', 'error'];
+
+/**
+ * The splat budget a Streamed SOG gets when the caller did not name one: 600k splats **per tile,
+ * all views included** (see SPLAT_BUDGET_MODEL). The engine's own default is 1M.
+ *
+ * Why 600k and not the engine's 1M: the budget is ONE count for every view of a tile, and a 3D
+ * tile draws that set TWICE (two eyes, two passes over the same work buffer). Measured on an M1
+ * Pro with no other GPU client, two views at 3840×1080 (docs/playcanvas-adapter.md §Streamed
+ * SOG): a 5.88M-gaussian captured castle ran 9.6 ms median / 12.9 ms p90 at 600k and
+ * 10.9 / 13.3 at 1M; Trogir (45.7M) 8.3 / 11.1 and 10.3 / 11.9. So on that GPU 1M fits a 60 Hz
+ * stereo frame too. 600k is chosen for HEADROOM, not because 1M failed: it keeps the M1 at ~60 %
+ * of a 16.7 ms frame for the weaker GPUs a 3D display ships with (Windows iGPUs, Android
+ * tablets — not measured yet). Only 600k and 1M were measured, so it is a safe default, not a
+ * tuned optimum. A caller-set `splatBudget` always wins, and `perf: false` leaves the engine's
+ * 1M untouched.
+ *
+ * The budget has a FLOOR the engine cannot go under: a chunk is never drawn coarser than its
+ * coarsest level, so the resident count bottoms out at the sum of every visible chunk's coarsest
+ * level (367k on the castle's 5-level pyramid, above a 300k budget).
+ */
+export const STREAMED_SPLAT_BUDGET = 600000;
+
+/**
+ * THE BUDGET MODEL, pinned (a test holds these values):
+ *
+ * - `scope: 'tile'` — every tile is its own `AppBase`, so its own scene, its own
+ *   `scene.gsplat.splatBudget`, its own gsplat manager. Two tiles on a page = two budgets.
+ * - `views: 'shared'` — the engine keys its gsplat managers by CAMERA (`GSplatDirector.camerasMap`
+ *   → one `GSplatManager` per camera × layer), and this adapter renders every view of a tile
+ *   through ONE camera with N `RenderView`s. So one manager, one LOD pass, one budget, one work
+ *   buffer for all N views — a 600k budget is 600k splats per tile whether the tile is mono or
+ *   two-view. (Measured on the castle at 600k: 1 camera, 1 manager, 588,879 resident in mono
+ *   and 590,331 with two views; docs/playcanvas-adapter.md §Streamed SOG.)
+ * - `fallbackDivides: true` — the N-camera fallback path (`playcanvasViewPath: 'cameras'`) makes
+ *   N managers, each reading the SAME scene budget, which would be N× the budget per tile. The
+ *   adapter divides the budget by N on that path to keep the per-tile contract — subject to the
+ *   per-manager coarsest-level floor above (measured: 2 managers × 300k on the castle resident
+ *   734,764 = 2 × its 367,382 coarsest level).
+ * - LOD distance is measured from the camera NODE, which sits on the first view's eye; every
+ *   view uses the LOD it picked (one pass). The eyes are ~63 mm apart, so the difference is
+ *   below `lodUpdateDistance` by construction.
+ */
+export const SPLAT_BUDGET_MODEL = Object.freeze({
+  scope: 'tile',
+  views: 'shared',
+  fallbackDivides: true,
+  lodCamera: 'first-view',
+});
+
+/**
+ * The scene-level budget one engine manager must be given so that a TILE spends `tileBudget`.
+ * RenderView path: one manager for all views, so the tile budget as is. N-camera fallback: one
+ * manager per view, so the tile budget split N ways (floored, never below 1).
+ */
+export function budgetPerManager(tileBudget, viewPath, views) {
+  if (!(tileBudget > 0)) return tileBudget;
+  if (viewPath !== 'cameras') return tileBudget;
+  const n = Math.max(1, Math.floor(views) || 1);
+  return Math.max(1, Math.floor(tileBudget / n));
+}
+
+/**
+ * The tile's budget for a resolved perf profile on a source of this kind: the caller's
+ * `splatBudget` if set, else STREAMED_SPLAT_BUDGET on a Streamed SOG, else unset (engine default).
+ * `perf: false` resolves to `settings: {}`, which is why it never gets the streamed default.
+ *
+ * @param {{settings:object, applied:object|null}} resolved  playcanvasPerfSettings()'s result.
+ * @param {'flat'|'streamed'|null} kind
+ * @returns {number|undefined}
+ */
+export function tileSplatBudget(resolved, kind) {
+  const s = resolved?.settings || {};
+  if (isNum(s.splatBudget)) return s.splatBudget;
+  if (kind === 'streamed' && resolved?.applied) return STREAMED_SPLAT_BUDGET;
+  return undefined;
+}
+
 /** Spark knobs with no engine equivalent — named once in a warning, then ignored. */
 const PC_UNMAPPED = ['lod', 'lodSplatCount', 'lodSplatScale', 'lodRenderScale', 'maxPixelRadius', 'falloff', 'alphaFloor'];
 
@@ -333,6 +428,16 @@ export function playcanvasPerfSettings(perf) {
     }
     if (profile.alphaRadius !== undefined) applied.alphaRadius = 'native';
     for (const key of PC_NATIVE) if (isNum(profile[key])) s[key] = profile[key];
+    for (const key of PC_LOD_NUMERIC) if (isNum(profile[key]) && profile[key] >= 0) s[key] = profile[key];
+    if (profile.lodMode !== undefined) {
+      if (PC_LOD_MODES.includes(profile.lodMode)) s.lodMode = profile.lodMode;
+      else {
+        console.warn(
+          `[inline3d/splat] perf.lodMode "${profile.lodMode}" is not one of ${PC_LOD_MODES.join(', ')} — ` +
+            "ignored (the engine's default, 'distance', stays).",
+        );
+      }
+    }
     if (typeof profile.antiAlias === 'boolean') s.antiAlias = profile.antiAlias;
     for (const key of PC_UNMAPPED) if (profile[key] !== undefined) out.ignored.push(key);
     if (out.ignored.length) {

package/js/inline3d-splat-playcanvas.js

@@ -43,7 +43,12 @@ import {
   FRAME_SAMPLE_CAP,
 } from './inline3d-splat-rig.js';
 import { readSogMeta, sogCameraFromMeta } from './inline3d-sog.js';
-import { playcanvasPerfSettings, patchPlayCanvasQuadExtent } from './inline3d-splat-perf.js';
+import {
+  playcanvasPerfSettings,
+  patchPlayCanvasQuadExtent,
+  tileSplatBudget,
+  budgetPerManager,
+} from './inline3d-splat-perf.js';
 import { boundsFromPositions } from './inline3d-viewer.js';
 import { cameraRigFromPose } from './inline3d-three.js';
 import {
@@ -76,6 +81,7 @@ import {
   captureVerticalFovDeg,
   engineFormatFor,
   pathOf,
+  streamedBytesError,
 } from './inline3d-splat-shared.js';
 
 /** The engine release this adapter was built and measured against (npm peer floor). */
@@ -385,7 +391,20 @@ export function pickViewPath(pc, forced) {
 
 // Source routing lives in ./inline3d-splat-shared.js (./splat also needs it, synchronously, to
 // refuse a format this engine cannot read at call time); re-exported for the tests.
-export { engineFormatFor } from './inline3d-splat-shared.js';
+export { engineFormatFor, isStreamedUrl, streamedBytesError } from './inline3d-splat-shared.js';
+
+/**
+ * The URL the engine loads for a streamed source: a directory URL gets `lod-meta.json` appended
+ * (before any query/hash, which are kept); a `lod-meta.json` URL is returned as is. The engine
+ * resolves every chunk relative to this URL's directory, so it must name the file itself.
+ */
+export function streamedEntryUrl(src) {
+  if (typeof src !== 'string') return src;
+  const m = /^([^?#]*)(.*)$/.exec(src);
+  const path = m[1];
+  const tail = m[2];
+  return path.endsWith('/') ? `${path}lod-meta.json${tail}` : src;
+}
 
 /**
  * The pick fallback on flat arrays: the gaussian whose CENTRE is nearest the ray — by angle,
@@ -521,6 +540,16 @@ export class PlayCanvasSplatViewer {
     this._viewPath = null;
     this._frustumKey = '';
 
+    // Per-frame splat accounting (handle.stats()). `resident` is what the engine put in the
+    // tile's work buffer on the LAST tick — the budget-enforced, LOD-selected set every view of
+    // the tile draws from (before per-view frustum culling). `firstFrameAt` is performance.now()
+    // (ms since navigation start) of the first tick that drew a non-empty set.
+    this.resident = 0;
+    this.peakResident = 0;
+    this.firstFrameAt = null;
+    this._tileBudget = undefined; // undefined = the engine's own default
+    this._budgetViews = 1;
+
     this._onResize = () => this._scheduleResize();
     this._ro = typeof ResizeObserver === 'function' ? new ResizeObserver(this._onResize) : null;
     if (this._ro) this._ro.observe(canvas);
@@ -810,7 +839,12 @@ export class PlayCanvasSplatViewer {
         );
       }
     }
-    for (const [k, v] of Object.entries(perf?.settings || {})) app.scene.gsplat[k] = v;
+    for (const [k, v] of Object.entries(perf?.settings || {})) {
+      if (k !== 'splatBudget') app.scene.gsplat[k] = v;
+    }
+    // The budget goes through setTileBudget: it is a PER-TILE contract, and the N-camera
+    // fallback has to split it (SPLAT_BUDGET_MODEL).
+    this.setTileBudget(perf?.settings?.splatBudget);
 
     // EVERY Entity gets its app EXPLICITLY. The constructor's default is the engine's global
     // "current app" (`getApplication()`), which is whichever AppBase last init'ed or ticked — so
@@ -895,6 +929,35 @@ export class PlayCanvasSplatViewer {
     this._feather.mat.setParameter('dxrFeatherFy', Math.min(0.5, this.featherPx / Math.max(1, h)));
   }
 
+  /**
+   * The tile's splat budget, all views included (SPLAT_BUDGET_MODEL). `undefined` leaves the
+   * engine's own default alone. On the RenderView path it is the scene budget as is (one manager
+   * for all views); on the N-camera fallback it is split across the N per-camera managers.
+   */
+  setTileBudget(budget) {
+    this._tileBudget = Number.isFinite(budget) && budget > 0 ? Math.floor(budget) : undefined;
+    this._applyBudget();
+  }
+
+  get tileBudget() {
+    if (this._tileBudget !== undefined) return this._tileBudget;
+    return this.app ? this.app.scene.gsplat.splatBudget : undefined;
+  }
+
+  _applyBudget() {
+    if (!this.app || this._tileBudget === undefined) return;
+    const per = budgetPerManager(this._tileBudget, this._viewPath, this._budgetViews);
+    if (this.app.scene.gsplat.splatBudget !== per) this.app.scene.gsplat.splatBudget = per;
+  }
+
+  /** Read back what the tick just did. Cheap: two numbers off the renderer. */
+  _afterTick() {
+    const n = this.app?.renderer?._gsplatCount ?? 0;
+    this.resident = n;
+    if (n > this.peakResident) this.peakResident = n;
+    if (n > 0 && this.firstFrameAt === null) this.firstFrameAt = now();
+  }
+
   /** A camera entity under the rig node. Tonemapping OFF: splat colours are already display-referred. */
   _makeCamera(name, rect) {
     const pc = this.pc;
@@ -1025,6 +1088,11 @@ export class PlayCanvasSplatViewer {
         cams.push(cam);
       }
       for (let i = 0; i < cams.length; i++) cams[i].enabled = i < entries.length;
+      if (this._budgetViews !== entries.length) {
+        // One manager per enabled camera here, each reading the scene budget: split it.
+        this._budgetViews = entries.length;
+        this._applyBudget();
+      }
       const W = el.width || 1;
       const H = el.height || 1;
       for (let i = 0; i < entries.length; i++) {
@@ -1042,6 +1110,7 @@ export class PlayCanvasSplatViewer {
     }
     this._updateFeather(entries[0].width * sx, entries[0].height * sy);
     app.tick(now());
+    this._afterTick();
     return true;
   }
 
@@ -1361,18 +1430,86 @@ export async function readCloud(resource) {
   return { xyz, opacity, alpha8, total, stride, sourceTotal };
 }
 
+/**
+ * A point sample standing in for a Streamed SOG's cloud, from its octree alone: every leaf node
+ * contributes points in proportion to its finest-level splat count, spread deterministically
+ * through its box. That is enough for the SAME percentile framing a flat source gets
+ * (boundsFromPositions), which the octree's root bound cannot give — the root is the raw
+ * container of every chunk, sky shells and floaters included (a captured castle: 391×821×390 m
+ * root against 65×25×76 m measured on the flat file; a museum room: ±240 m around a 2 m statue).
+ *
+ * Coarse by construction (a node is a box, not its splats), so framing lands within a node size
+ * of the flat measurement, not on it. Nothing is downloaded: lod-meta.json already lists every
+ * node's box and count.
+ *
+ * @param {Array<{min:number[], max:number[], count:number}>} nodes
+ * @param {number} [cap]  points to emit in total (default 20k).
+ * @returns {Float32Array|null} xyz, model space.
+ */
+export function octreeSample(nodes, cap = 20000) {
+  if (!Array.isArray(nodes) || !nodes.length) return null;
+  let total = 0;
+  for (const n of nodes) total += n.count > 0 ? n.count : 0;
+  if (!(total > 0)) return null;
+  const pts = [];
+  let seed = 0x9e3779b9;
+  const rnd = () => {
+    // xorshift32: deterministic, so a test (and a reload) frames the same way every time.
+    seed ^= seed << 13; seed >>>= 0;
+    seed ^= seed >>> 17;
+    seed ^= seed << 5; seed >>>= 0;
+    return seed / 4294967296;
+  };
+  let carry = 0;
+  for (const n of nodes) {
+    if (!(n.count > 0)) continue;
+    carry += (n.count / total) * cap;
+    const k = Math.floor(carry);
+    carry -= k;
+    for (let i = 0; i < k; i++) {
+      pts.push(
+        n.min[0] + (n.max[0] - n.min[0]) * rnd(),
+        n.min[1] + (n.max[1] - n.min[1]) * rnd(),
+        n.min[2] + (n.max[2] - n.min[2]) * rnd(),
+      );
+    }
+  }
+  return pts.length ? Float32Array.from(pts) : null;
+}
+
+/** The engine octree's leaf nodes as octreeSample() input. */
+function octreeNodes(res) {
+  const nodes = res?.octree?.nodes;
+  if (!Array.isArray(nodes)) return [];
+  const out = [];
+  for (const n of nodes) {
+    const b = n?.bounds;
+    const c = n?.lods?.[0]?.count ?? 0;
+    if (!b || !b.center || !b.halfExtents || !(c > 0)) continue;
+    out.push({
+      min: [b.center.x - b.halfExtents.x, b.center.y - b.halfExtents.y, b.center.z - b.halfExtents.z],
+      max: [b.center.x + b.halfExtents.x, b.center.y + b.halfExtents.y, b.center.z + b.halfExtents.z],
+      count: c,
+    });
+  }
+  return out;
+}
+
 /**
  * What kind of resource the engine handed back, and what can be known about it without a cloud.
  *
  * A Streamed SOG (`lod-meta.json`) loads as a `GSplatOctreeResource`: no `centers`, no
- * `gsplatData`, splats arriving by LOD as the camera asks. Its framing falls back to the octree's
- * root bound (`resource.aabb`, the lod-meta `tree.bound` — the engine nulls `data.tree` after
- * reading it), its camera block to the top level of lod-meta.json, and its count to the octree's
- * finest level (`numSplats`; lod-meta's `count` sums every level). Full streaming behaviour
- * (budget per tile, pick on resident LODs) is P2.
+ * `gsplatData`, splats arriving by LOD as the camera asks. Its framing comes from the octree's
+ * leaf boxes (octreeSample → the same percentile bounds a flat cloud gets), else from the root
+ * bound (`resource.aabb`, the lod-meta `tree.bound` — the engine nulls `data.tree` after
+ * reading it); its camera block from the top level of lod-meta.json; its count from the octree's
+ * finest level (`numSplats`; lod-meta's `count` sums every level). What is on screen in a given
+ * frame is `handle.stats().resident`, capped by the tile budget (SPLAT_BUDGET_MODEL); `pick`
+ * searches the chunks currently resident.
  *
  * @returns {{kind:'flat'|'streamed'|null, numSplats:number, meta:object|null,
- *            bounds:{center:number[],extent:number[]}|null}}  bounds in MODEL space.
+ *            bounds:{center:number[],extent:number[]}|null, boundsSource?:string,
+ *            rootBounds?:object|null}}  bounds in MODEL space.
  */
 export function describeResource(res) {
   if (!res) return { kind: null, numSplats: 0, meta: null, bounds: null };
@@ -1391,7 +1528,16 @@ export function describeResource(res) {
     } catch {
       n = 0;
     }
-    return { kind: 'streamed', numSplats: n || res.data?.count || 0, meta: res.data || null, bounds };
+    const sample = octreeSample(octreeNodes(res));
+    const sampled = sample ? boundsFromPositions(sample) : null;
+    return {
+      kind: 'streamed',
+      numSplats: n || res.data?.count || 0,
+      meta: res.data || null,
+      bounds: sampled || bounds,
+      boundsSource: sampled ? 'octree-sample' : bounds ? 'octree-root' : null,
+      rootBounds: bounds,
+    };
   }
   return { kind: 'flat', numSplats: res.gsplatData?.numSplats ?? 0, meta: res.gsplatData?.meta || null, bounds: null };
 }
@@ -1528,6 +1674,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     },
     exclude: (el) => handle?.exclude(el),
     unexclude: (el) => handle?.unexclude(el),
+    stats: () => splatStats(),
   });
   // `onFocusChange` is a plain data property of the handle, read at CALL time — so a callback
   // assigned before this module loaded (on the stub ./splat returned) is the one that fires.
@@ -1598,6 +1745,25 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   // captureFit 'cover' re-crops on resize, which changes the rig's vertical FOV: re-declare it.
   viewer.onCaptureFov = () => pushViewRig(true);
 
+  // ── stats ──
+  function splatStats() {
+    const c = current;
+    const oct = c?.kind === 'streamed' ? c.res?.octree : null;
+    const budget = viewer.tileBudget;
+    return {
+      kind: c?.kind ?? null,
+      resident: viewer.resident,
+      peakResident: viewer.peakResident,
+      budget: Number.isFinite(budget) ? budget : null,
+      numSplats: out.mesh?.numSplats ?? 0,
+      views: viewer._lastGood && viewer.is3D ? viewer._lastGood.entries.length : 1,
+      lodLevels: oct ? oct.lodLevels : null,
+      files: oct ? oct.files.length : null,
+      filesLoaded: oct ? oct.fileResources.size : null,
+      firstFrameMs: viewer.firstFrameAt,
+    };
+  }
+
   // ── pick ──
   /** The ray under a client point, in MODEL space (through the inverse pivot and the flip). */
   function modelRay(clientX, clientY) {
@@ -1678,6 +1844,12 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       const buf = source instanceof Blob ? await source.arrayBuffer() : source;
       bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf);
     }
+    if (bytes) {
+      // Also caught synchronously by ./splat for Uint8Array/ArrayBuffer; a Blob, and setSource,
+      // only arrive here.
+      const streamedErr = streamedBytesError(bytes, opts.fileName);
+      if (streamedErr) throw new Error(`[inline3d/splat] ${streamedErr}`);
+    }
     const fmt = engineFormatFor(source, bytes, opts.fileName, opts.fileType);
     if (!fmt) {
       throw new Error(
@@ -1689,10 +1861,14 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     let camera = null;
     if (bytes && rig !== 'display') camera = sogCameraFromMeta(await readSogMeta(bytes));
 
-    const url = bytes ? `inline3d-bytes-${++byteSeq}-${++byteSeqLocal}.${fmt.ext}` : source;
+    const url = bytes
+      ? `inline3d-bytes-${++byteSeq}-${++byteSeqLocal}.${fmt.ext}`
+      : fmt.streamed
+        ? streamedEntryUrl(source)
+        : source;
     const file = bytes
       ? { url, filename: url, contents: new Response(bytes) }
-      : { url, filename: pathOf(source).split('/').pop() || url };
+      : { url, filename: pathOf(url).split('/').pop() || url };
     const asset = new pc.Asset(url, 'gsplat', file);
     app.assets.add(asset);
     await new Promise((resolve, reject) => {
@@ -1718,9 +1894,19 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     const walk = cloud ? centresVisitor(cloud.xyz, cloud.opacity, cloud.total) : null;
     const local = walk ? boundsFromPositions(sampleCloudCentres(cloud.total, walk) || []) : null;
     const lift = (b) => ({ center: modelToContent(b.center), extent: b.extent.slice(0, 3) });
-    // Measured first; a Streamed SOG's octree bound next (raw min/max); the caller's `frame`
-    // last — the Spark path's order (a supplied frame is only a fallback there too).
-    const bounds = local ? lift(local) : desc.bounds ? lift(desc.bounds) : frame ? lift(frame) : null;
+    // Measured first — the Spark path's order (a supplied frame is only a fallback there too).
+    // A Streamed SOG has no cloud: there a caller's `frame` beats the octree-derived bounds
+    // (describeResource: a count-weighted sample of the leaf boxes, else the raw root bound),
+    // because both are coarser than a real measurement.
+    const bounds = local
+      ? lift(local)
+      : desc.kind === 'streamed' && frame
+        ? lift(frame)
+        : desc.bounds
+          ? lift(desc.bounds)
+          : frame
+            ? lift(frame)
+            : null;
 
     const sample =
       !rigNeedsCloud(loaded.camera)
@@ -1740,6 +1926,13 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     out.camera = loaded.camera;
     out.rig = resolved;
     out.frame = bounds;
+    // The tile budget, now that the kind is known: the caller's, else the streamed default on a
+    // Streamed SOG, else the engine's (STREAMED_SPLAT_BUDGET, SPLAT_BUDGET_MODEL).
+    const budget = tileSplatBudget(perfResolved, desc.kind);
+    viewer.setTileBudget(budget);
+    if (perfResolved.applied) {
+      out.perf = budget !== undefined ? { ...perfResolved.applied, splatBudget: budget } : perfResolved.applied;
+    }
 
     // The strided pick fallback (used only if the engine releases its full centre set).
     let pickCentres = null;

package/js/inline3d-splat-shared.js

@@ -175,12 +175,57 @@ export function engineFormatFor(src, bytes, fileName, fileType) {
     const e = extOf(fileName);
     return e === 'sog' || e === 'ply' ? { ext: e, streamed: false } : null;
   }
+  if (isStreamedUrl(src)) return { ext: 'json', streamed: true };
   const e = extOf(src);
   if (e === 'sog' || e === 'ply') return { ext: e, streamed: false };
-  if (e === 'json') return { ext: 'json', streamed: /lod-meta\.json$/i.test(pathOf(src)) };
+  if (e === 'json') return { ext: 'json', streamed: false };
   return null;
 }
 
+/**
+ * Is this URL a Streamed SOG? Either its `lod-meta.json` or the DIRECTORY that holds one (a path
+ * ending in `/`), with or without a query or hash. Here, not in the adapter, because both engines
+ * need the answer synchronously: the PlayCanvas backend streams it, and the Spark path must refuse
+ * it by name (Spark has no reader for it).
+ */
+export function isStreamedUrl(src) {
+  if (typeof src !== 'string') return false;
+  const p = pathOf(src);
+  return /(^|\/)lod-meta\.json$/i.test(p) || (p.length > 0 && p.endsWith('/'));
+}
+
+/** The error a Spark page gets for a Streamed SOG URL. */
+export const STREAMED_NEEDS_PLAYCANVAS =
+  "a Streamed SOG (lod-meta.json) is read only by engine:'playcanvas' (the default); Spark has no " +
+  'reader for it. Drop engine:\'spark\', or load a flat .sog.';
+
+/**
+ * A Streamed SOG handed over as BYTES — refuse it, with the reason. A Streamed SOG is a
+ * directory: `lod-meta.json` names hundreds of chunk files by RELATIVE path, and bytes carry no
+ * base URL to resolve them against. Detected by the file name the caller gave (`fileName`), or by
+ * sniffing a JSON object that has the lod-meta keys (`lodLevels` + `filenames`) in its first 4 KB.
+ *
+ * @returns {string|null} the error message, or null when the bytes are not a lod-meta.
+ */
+export function streamedBytesError(bytes, fileName) {
+  let hit = typeof fileName === 'string' && /(^|\/)lod-meta\.json$/i.test(pathOf(fileName));
+  if (!hit && bytes && bytes.length) {
+    let i = 0;
+    while (i < bytes.length && i < 64 && (bytes[i] === 0x20 || bytes[i] === 0x0a || bytes[i] === 0x0d || bytes[i] === 0x09 || bytes[i] === 0xef || bytes[i] === 0xbb || bytes[i] === 0xbf)) i++;
+    if (bytes[i] === 0x7b) {
+      const head = new TextDecoder().decode(bytes.subarray(0, Math.min(bytes.length, 4096)));
+      hit = /"lodLevels"\s*:/.test(head) && /"filenames"\s*:/.test(head);
+    }
+  }
+  if (!hit) return null;
+  return (
+    'a Streamed SOG (lod-meta.json) cannot be passed as bytes: it is a directory of chunk files ' +
+    'that lod-meta.json names by relative path, and bytes have no base URL to resolve them ' +
+    "against. Pass its URL instead — addSplat(wall, canvas, 'https://…/scene/lod-meta.json') " +
+    "(a URL ending in '/' works too)."
+  );
+}
+
 // ── ORBIT: the PlayCanvas backend's built-in drag (tilt-and-relax) ──────────────────────────
 //
 // SceneViewer (the Spark path) still turns the subject cumulatively (DRAG_DEG_PER_TILE); switching
@@ -257,7 +302,11 @@ export function captureVerticalFovDeg(K, aspect, near, captureFit = 'height') {
 export function playcanvasCannotRead(src, { fileType, fileName } = {}) {
   let bytes = null;
   if (src instanceof Uint8Array) bytes = src;
-  else if (src instanceof ArrayBuffer) bytes = new Uint8Array(src, 0, Math.min(8, src.byteLength));
+  else if (src instanceof ArrayBuffer) bytes = new Uint8Array(src, 0, Math.min(4096, src.byteLength));
+  if (bytes) {
+    const streamed = streamedBytesError(bytes, fileName);
+    if (streamed) return streamed;
+  }
   if (typeof src !== 'string' && !bytes && fileType === undefined) return null; // a Blob: known at load
   if (typeof src === 'string' && fileType === undefined && !extOf(src)) return null;
   if (engineFormatFor(typeof src === 'string' ? src : null, bytes, fileName, fileType)) return null;

package/js/inline3d-splat.js

@@ -32,6 +32,8 @@ import {
   captureVerticalFovDeg,
   CAPTURE_FITS,
   playcanvasCannotRead,
+  isStreamedUrl,
+  STREAMED_NEEDS_PLAYCANVAS,
 } from './inline3d-splat-shared.js';
 import {
   resolveRig,
@@ -172,6 +174,10 @@ export function addSplat(wall, canvas, src, opts = {}) {
     return addSplatDeferred(wall, canvas, src, opts);
   }
 
+  // A Streamed SOG on Spark is a page bug (Spark has no lod-meta.json reader): say so now, by
+  // name, rather than let Spark fail on an "unknown file type" that reads like a corrupt asset.
+  if (isStreamedUrl(src)) throw new Error(`@displayxr/inline3d/splat: ${STREAMED_NEEDS_PLAYCANVAS}`);
+
   // Fail here, synchronously, and not through `ready`: a peer too old is an install-time mistake
   // in the page's dependencies, not a condition of this asset, and it will be true of every call.
   // Surfacing it as a load rejection would let a caller render an "asset unavailable" placeholder
@@ -632,6 +638,8 @@ function addSplatDeferred(wall, canvas, src, opts) {
     // line after addSplat — before the module has loaded — is the one that fires.
     onFocusChange: null,
     pick: () => null,
+    // Splat accounting (resident / budget / first frame); null until the adapter has loaded.
+    stats: () => null,
     remove: queue('remove'),
     exclude: queue('exclude'),
     unexclude: queue('unexclude'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Turn any HTML <canvas> into a glasses-free-3D window on a DisplayXR display, inside an ordinary web page. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",

package/splat.d.ts

@@ -36,9 +36,25 @@ export interface SplatPerfOptions {
   lodRenderScale?: number;
   /**
    * `engine: 'playcanvas'` only — engine-native knobs, passed straight to `app.scene.gsplat`
-   * (and winning over the Spark-knob mapping). `splatBudget` is a global splat count per tile.
+   * (and winning over the Spark-knob mapping).
+   *
+   * `splatBudget` is a splat count **per tile, all views included**: every view of a tile is
+   * drawn through one engine camera, so one budget covers both eyes of a 3D tile. It only acts
+   * on a Streamed SOG (a flat `.sog` draws every splat). Unset on a Streamed SOG = 600k
+   * (`STREAMED_SPLAT_BUDGET`); unset on anything else, or `perf: false` = the engine's 1M.
    */
   splatBudget?: number;
+  /**
+   * `engine: 'playcanvas'`, Streamed SOG only: how a chunk's LOD is chosen. Unset = the engine's
+   * `'distance'`.
+   */
+  lodMode?: 'distance' | 'error';
+  /** Streamed SOG only: camera travel (in the file's own units) before LOD re-evaluates. Engine default 1. */
+  lodUpdateDistance?: number;
+  /** Streamed SOG only: camera rotation in degrees before LOD re-evaluates. Engine default 0 (off). */
+  lodUpdateAngle?: number;
+  /** Streamed SOG only: how many coarser levels may stand in while a finer one streams. Engine default 0. */
+  lodUnderfillLimit?: number;
   /** `engine: 'playcanvas'` only: cull splats whose quad DIAMETER is under this many px. */
   minPixelSize?: number;
   /** `engine: 'playcanvas'` only: the forward-pass alpha floor (engine default 1/255). */
@@ -158,6 +174,11 @@ export interface SplatOptions {
    * Which renderer. `'spark'` (the default) is three.js + Spark. `'playcanvas'` is the PlayCanvas
    * engine (optional peer `playcanvas >=2.22.3 <3`, loaded by dynamic import only when asked):
    * same handle, reads `.sog` / `.ply` / a Streamed-SOG `lod-meta.json`. Anything else throws.
+   *
+   * A Streamed SOG is loaded BY URL only — its `lod-meta.json`, or the directory holding it (a
+   * URL ending in `/`). It is a directory of chunk files named by relative path, so bytes of a
+   * `lod-meta.json` throw at call time with a message giving the URL form, and so does a streamed
+   * URL with `engine: 'spark'`.
    */
   engine?: 'spark' | 'playcanvas';
   /**
@@ -269,6 +290,34 @@ export interface SplatOptions {
   observe?: Element;
 }
 
+/** `handle.stats()` on `engine: 'playcanvas'`. */
+export interface SplatStats {
+  /** `'streamed'` for a `lod-meta.json`, `'flat'` for `.sog`/`.ply`, null before load. */
+  kind: 'flat' | 'streamed' | null;
+  /**
+   * Splats the engine placed in this tile's work buffer on the LAST frame: after LOD selection
+   * and the budget, before per-view frustum culling. Every view of the tile draws from this set.
+   */
+  resident: number;
+  /** The largest `resident` seen so far. */
+  peakResident: number;
+  /** The tile's splat budget (all views included), or null. */
+  budget: number | null;
+  /** The asset's own count: every splat of a flat source, the finest level of a Streamed SOG. */
+  numSplats: number;
+  /** Views drawn last frame (1 in mono, the runtime's view count in 3D). */
+  views: number;
+  /** Streamed SOG only (null otherwise): LOD levels, chunk files, chunk files currently loaded. */
+  lodLevels: number | null;
+  files: number | null;
+  filesLoaded: number | null;
+  /**
+   * `performance.now()` (ms since navigation start) of the first frame that drew a non-empty
+   * set — the page's time to first splat. Null until then.
+   */
+  firstFrameMs: number | null;
+}
+
 /** What {@link addSplat} returns: a TileHandle plus the objects behind it. */
 export interface SplatHandle {
   /**
@@ -354,6 +403,11 @@ export interface SplatHandle {
    * raycast, falling back to the nearest centre.
    */
   pick(clientX: number, clientY: number): number[] | null;
+  /**
+   * `engine: 'playcanvas'` only: splat accounting for this tile. Null until the backend module
+   * has loaded.
+   */
+  stats?(): SplatStats | null;
 
   /** Close this window and release its GPU resources. */
   remove(): void;