@displayxr/inline3d 1.6.1 → 1.7.0

package/CHANGELOG.md

@@ -5,6 +5,104 @@ 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.7.0 — 2026-09-19
+
+Touches the **preview tier** (`./splat`) only, and additively: `addSplat` with no new options
+renders exactly as it did in 1.6.1 — every Spark default stays where Spark put it and the display
+rig with its auto-frame is still what an asset without a `camera` block gets.
+
+### Added
+
+- **`addSplat({ perf })` — cut a splat's overdraw** (preview tier). A splat scene's cost is the
+  per-fragment composite, and splat COUNT is the weakest axis on it: decimating the reference
+  1.18M-gaussian capture to 25 % breaks it visibly while removing less cost than these settings,
+  which remove none of the picture. Two presets (`'balanced'`, `'aggressive'`) or an object of your
+  own over Spark's `minAlpha` / `maxStdDev` / `minPixelRadius` / `maxPixelRadius` / `falloff` and
+  its LOD budget, plus two of this SDK's own:
+  - **`alphaRadius`** shrinks each splat's quad to the radius where its own alpha reaches
+    `minAlpha`. Spark's fragment shader already discards everything past that radius, so this
+    removes work and not pixels — **bit-exact**, measured: 457 of 3,686,400 channel bytes differ
+    at 1280×720, every one of them by exactly 1. Spark 2.1.0 has no option for it (`maxStdDev` is
+    one global uniform), so the SDK patches Spark's splat vertex shader through its supported
+    `vertexShader` surface, rewriting Spark's OWN source off the live material rather than shipping
+    a copy — a Spark upgrade brings its shader fixes along, and if the lines stop matching the
+    patch declines with one warning and everything still renders.
+  - **`alphaFloor`** moves that cut up: each tail is dropped where IT reaches the floor rather than
+    where an 8-bit framebuffer stops representing it — the per-splat version of turning
+    `maxStdDev` down.
+
+  Two results from measuring it that are worth more than the options themselves, because both are
+  the opposite of the obvious move (M1 Pro, Chrome/ANGLE-Metal, GPU timer queries, configs
+  interleaved frame by frame):
+  - **Decimating the asset buys nothing.** 50 % and 25 % decimations measured within noise of the
+    full 1.18M-gaussian scene. Decimation drops the small gaussians and the few huge ones that
+    cover the frame survive it. A decimated `.sog` is a download win, not a render-cost win.
+  - **The bit-exact shrink buys little on a lifted photograph**, because 86 % of its gaussians are
+    near-opaque and an opaque splat's own 1/255 radius is already wider than the σ Spark draws it
+    at. It is exact and it stays — the scene it was built for is large low-alpha haze — but the
+    preset that pays on the web (`'balanced'`, −5…−20 %) tightens the quad extent instead.
+
+  `handle.perf` reports what was applied, and `applySplatPerf(spark, perf)` is exported for pages
+  that build their own `SparkRenderer` — the knobs are live, so a quality menu can call it at any
+  time. Measured numbers, and which knob is worth which pixels, are in
+  [docs/authoring-inline-3d.md](docs/authoring-inline-3d.md#gaussian-splats-performance-and-the-camera-block).
+
+- **A `.sog`'s `camera` block now picks the view rig, and a WATERFALL fills in the rest**
+  (preview tier). A splat viewer needs BOTH rigs and the same call site loads both kinds of asset
+  — a product hero wants the display rig and its auto-frame, while a photograph lifted into 3D
+  wants the camera it was taken with. Nothing in the page can tell them apart; the file can.
+  `addSplat` reads the `camera` block out of the `.sog` (a PKZip — ~40 bytes of central directory,
+  never the webp planes, and only on the BYTES path) and resolves three questions from it:
+
+  | | 1st | 2nd | 3rd | last |
+  |---|---|---|---|---|
+  | **rig** | caller | the block's `rig` | a block at all ⇒ camera | display |
+  | **intrinsics** | the block | caller | **estimated from the cloud** | 28 mm-eq |
+  | **focus** | caller | the block's `focus.point` | **median disparity** | 2 m ahead |
+
+  Each resolved value carries the step that produced it (`handle.rig.focusSource`,
+  `intrinsicsSource`, `typeSource`), because a number from a lower step is not a wrong number, it
+  is a wrong SOURCE, and that is invisible in the picture.
+
+  The block is now a **v2 superset**: `rig`, `focus` (one point that is the orbit centre, the pivot
+  plane AND the convergence) and `dxr` (the camera rig's absolute scalars) join it, `intrinsics`
+  becomes optional, and a v1 block still reads. `rig: "display"` beside a `rest` is meaningful —
+  *a display rig, opened at this viewpoint*.
+
+  **Estimating the lens** works because a capture's gaussians only exist where its camera could see
+  them: P1/P99 of `x/z` and `y/z` about the rest camera ARE the frustum that made it, principal
+  point included. Measured against a capture whose true half-tangents are ±0.857 and ±0.482:
+  0.8635 and 0.4827, +0.75 % and +0.12 %. The implied 35 mm-equivalent focal is gated to
+  [14, 85] mm, outside which the cloud is describing something that is not a camera. It matters
+  because a splat rendered through the wrong focal is drawn at the wrong SIZE and nothing else —
+  no artefact, just a picture that feels zoomed out.
+
+  **Estimating the focus** is the median of 1/z, inverted — not of z. On the reference capture that
+  is 2.17 m against the gallery's own 2.14 m; the centre of the measured bounds, which this
+  replaced, was 39.8 m, because an open scene's percentile bounds are 128 m wide.
+
+  On the camera path the subject is not reframed, the turntable is off, the mono camera is posed
+  and lensed as the capture, and the rig is **declared** with `cameraRigFromCamera` — the off-axis
+  projection stays in the runtime.
+
+- **Pointing the window: double-click, Space and `handle.setFocus(point|null)`** (preview tier).
+  The focus is one point — the orbit centre, the pivot plane and the convergence — and it is now
+  something a viewer can move. Double-click focuses what was clicked (Spark's own
+  `SplatMesh.raycast`, ~57 ms over 1.18M gaussians, with a nearest-gaussian-to-the-ray fallback
+  documented as the approximation it is); Space returns to the resolved value; both ease at 0.18
+  per frame, and while the ease runs a camera rig re-declares its convergence every frame. What
+  moves depends on the rig and only on that: a camera rig moves the rotation centre and leaves the
+  capture where it was placed, a display rig brings the focused point to the middle of the tile.
+  `focusInput: false` turns the gestures off for a page that owns them itself, and
+  `handle.pick(x, y)` exposes the raycast.
+
+  New on the handle: **`handle.camera`** (the raw block), **`handle.rig`** (the resolved waterfall),
+  `handle.viewRig`, `handle.perf`, `handle.setFocus`, `handle.pick`. New exports from `./splat`:
+  `readSogCamera(bytes)`, `readSogMeta(bytes)`, `resolveRig`, `applySplatPerf`,
+  `SPLAT_PERF_PRESETS`. **`SceneViewer` gains `setFocus` / `getFocus` / `onFocusChange` / `onTick`**
+  (`./viewer`), and `fitTo` now goes through the focus, so a refit cannot leave the orbit turning
+  about somewhere the framing has moved away from.
+
 ## 1.6.1 — 2026-09-09
 
 Touches the **core tier** (`.`) with a behaviour fix only — no API changes — and the **preview tier**

package/README.md

@@ -113,6 +113,7 @@ js/
   inline3d-viewer.js  experimental: SceneViewer — framing, orbit, idle turntable, mono fallback,
                       and the placement readback (getSubjectBounds / getPose / depthOffset)
   inline3d-splat.js   experimental: addSplat() — a Gaussian splat window via Spark
+                      (`perf` cuts overdraw; a `.sog`'s `camera` block picks the view rig)
   inline3d-model.js   experimental: addModel() — a glTF/GLB window; wires Draco / meshopt / KTX2
                       from what the asset declares (you serve the decoder files — see the guide)
 docs/

package/js/inline3d-sog.js

@@ -0,0 +1,295 @@
+// inline3d-sog.js — read the `meta.json` out of a `.sog`, and the optional `camera` block in it.
+//
+// EXPERIMENTAL. Internal to `./splat`, which re-exports `readSogCamera`. Not covered by the SDK's
+// 1.x semver promise — see docs/sdk-stability.md.
+//
+// WHY A ZIP READER IS IN THIS SDK AT ALL. A `.sog` from `splat-transform` is a PKZip of webp
+// planes plus a `meta.json`, and Spark reads exactly the fields it needs to build splats out of
+// it — it neither surfaces the rest of the file nor hands back the parsed metadata. But whether a
+// splat is an OBJECT (a product hero, a scan, a turntable subject) or a PHOTOGRAPH LIFTED INTO 3D
+// is not a rendering detail: it decides which VIEW RIG the window should be on, and getting that
+// wrong is the difference between a picture you can lean into and an arbitrary cloud framed by a
+// bounding box. The `camera` block records the recording camera so the viewer can conserve it.
+//
+// So the choice is between asking every page to parse its own assets and reading ~40 bytes of
+// central directory here. The reader below does the second: it is deliberately the smallest thing
+// that can find ONE named entry in a zip, and it never touches the webp planes (which are
+// megabytes, and Spark's business).
+//
+// It is BYTES-ONLY on purpose. The gallery hands the SDK bytes rather than a URL (Spark infers a
+// splat's format from the URL path, so an extension-less `blob:` URL fails inside a worker), and
+// those same bytes are the ones this reads — one download, no second fetch, no range request, and
+// no chance of reading metadata from a different build of the asset than the one on screen.
+
+/** `PK\x05\x06` — end of central directory. */
+const EOCD_SIG = 0x06054b50;
+/** `PK\x01\x02` — a central-directory file header. */
+const CEN_SIG = 0x02014b50;
+/** `PK\x03\x04` — a local file header. */
+const LOC_SIG = 0x04034b50;
+
+/** EOCD is 22 bytes plus a comment of at most 64 KiB. */
+const EOCD_MAX_BACK = 22 + 0xffff;
+
+/**
+ * A `meta.json` this large is not a `meta.json`. The guard is against a malformed/hostile
+ * central directory, not against real assets: the largest one seen is ~4 KB.
+ */
+const META_MAX_BYTES = 4 << 20;
+
+/** Locate the end-of-central-directory record, scanning backwards. */
+function findEocd(dv) {
+  const len = dv.byteLength;
+  if (len < 22) return -1;
+  const stop = Math.max(0, len - EOCD_MAX_BACK);
+  for (let i = len - 22; i >= stop; i--) {
+    if (dv.getUint32(i, true) === EOCD_SIG) return i;
+  }
+  return -1;
+}
+
+/** Inflate a raw deflate stream. Returns null where the platform has no DecompressionStream. */
+async function inflateRaw(slice) {
+  if (typeof DecompressionStream !== 'function') return null;
+  const ds = new DecompressionStream('deflate-raw');
+  const stream = new Blob([slice]).stream().pipeThrough(ds);
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+
+/**
+ * Read one named entry out of a PKZip, as bytes.
+ *
+ * Handles the two compression methods a `.sog` actually uses — 0 (stored) and 8 (deflate) — and
+ * returns null for anything else rather than guessing. Zip64 is refused the same way: a `.sog`
+ * big enough to need it would have to be over 4 GB.
+ *
+ * @param {Uint8Array} bytes  the whole archive.
+ * @param {string} name  exact entry name, e.g. `meta.json`.
+ * @returns {Promise<Uint8Array|null>}
+ */
+export async function readZipEntry(bytes, name) {
+  if (!bytes || bytes.byteLength < 22) return null;
+  const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const eocd = findEocd(dv);
+  if (eocd < 0) return null;
+
+  const count = dv.getUint16(eocd + 10, true);
+  let p = dv.getUint32(eocd + 16, true);
+  // 0xffffffff in either field is the zip64 escape; we do not follow it (see above).
+  if (p === 0xffffffff || p >= dv.byteLength) return null;
+
+  const dec = new TextDecoder();
+  for (let i = 0; i < count; i++) {
+    if (p + 46 > dv.byteLength || dv.getUint32(p, true) !== CEN_SIG) return null;
+    const method = dv.getUint16(p + 10, true);
+    const compSize = dv.getUint32(p + 20, true);
+    const rawSize = dv.getUint32(p + 24, true);
+    const nameLen = dv.getUint16(p + 28, true);
+    const extraLen = dv.getUint16(p + 30, true);
+    const commentLen = dv.getUint16(p + 32, true);
+    const localOff = dv.getUint32(p + 42, true);
+    const entry = dec.decode(bytes.subarray(p + 46, p + 46 + nameLen));
+    p += 46 + nameLen + extraLen + commentLen;
+    if (entry !== name) continue;
+
+    if (compSize === 0xffffffff || rawSize === 0xffffffff || localOff === 0xffffffff) return null;
+    if (rawSize > META_MAX_BYTES) return null;
+    // The central directory's sizes are authoritative; the LOCAL header's may be zeroed (a
+    // streaming writer defers them to a data descriptor). Only its two length fields are read.
+    if (localOff + 30 > dv.byteLength || dv.getUint32(localOff, true) !== LOC_SIG) return null;
+    const lNameLen = dv.getUint16(localOff + 26, true);
+    const lExtraLen = dv.getUint16(localOff + 28, true);
+    const start = localOff + 30 + lNameLen + lExtraLen;
+    if (start + compSize > dv.byteLength) return null;
+    const slice = bytes.subarray(start, start + compSize);
+    if (method === 0) return slice;
+    if (method === 8) return inflateRaw(slice);
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Parse a `.sog`'s `meta.json`.
+ *
+ * @param {Uint8Array|ArrayBuffer} bytes
+ * @returns {Promise<object|null>} the parsed object, or null if this is not a `.sog`, has no
+ *          `meta.json`, or the entry cannot be read on this platform.
+ */
+export async function readSogMeta(bytes) {
+  const u8 = bytes instanceof Uint8Array ? bytes : bytes ? new Uint8Array(bytes) : null;
+  if (!u8 || u8.length < 4) return null;
+  // PK\x03\x04 — cheap reject before the backwards scan, so a `.ply`/`.spz`/`.splat` costs
+  // four byte comparisons.
+  if (!(u8[0] === 0x50 && u8[1] === 0x4b && u8[2] === 0x03 && u8[3] === 0x04)) return null;
+  let raw;
+  try {
+    raw = await readZipEntry(u8, 'meta.json');
+  } catch {
+    return null;
+  }
+  if (!raw) return null;
+  try {
+    return JSON.parse(new TextDecoder().decode(raw));
+  } catch {
+    return null;
+  }
+}
+
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);
+
+/**
+ * Validate the `camera` block of a `.sog` `meta.json`.
+ *
+ * THE BLOCK IS THE RIG SWITCH — present means "this splat was lifted from a photograph, and here
+ * is the camera that took it"; absent means "this is an object", which is the display rig and the
+ * behaviour every existing page already has. That is the whole contract, and it is why this is
+ * strict: a half-parsed block that silently keeps some defaults would put a photo scene on a
+ * plausible-looking rig that is not the capture, which is indistinguishable from a framing bug.
+ *
+ * Shape (`meta.json`, top level, right after `count`; `version` stays 2). v2 is a SUPERSET of
+ * v1 — every key below except `convention` is optional, and a v1 block still reads:
+ *
+ *     "camera": {
+ *       "convention": "opencv",
+ *       "rig":        "camera",                        // v2: which rig this asset wants
+ *       "rest":       { "position": [0,0,0], "rotation": [0,0,0,1] },
+ *       "intrinsics": { "fx":…, "fy":…, "cx":…, "cy":…, "width":…, "height":… },
+ *       "stereo":     { "baseline_m": 0.063 },
+ *       "focus":      { "point": [0,0,1.68], "subject_m":…, "near_m":…, "far_m":…,
+ *                       "source": "convergence|manual|auto" },   // v2
+ *       "dxr":        { "ipd_factor": 1.0, "parallax_factor": 1.0 }   // v2
+ *     }
+ *
+ * `intrinsics` BECAME OPTIONAL IN v2, which is the change with teeth: a block can now say "this
+ * is a camera rig, open it at this viewpoint" without claiming a lens, and the consumer is
+ * expected to estimate one. So this returns a descriptor with null intrinsics rather than
+ * refusing the block — refusing it would silently demote a camera-rig asset to the display rig,
+ * which is the failure this whole mechanism exists to prevent.
+ *
+ * `focus.point` is THE point: the orbit centre, the pivot plane and the convergence distance,
+ * which are one thing and are stored once.
+ *
+ * `convention` is REQUIRED to be `opencv` (+x right, +y DOWN, +z forward, pixel (0,0) at the top
+ * left) rather than defaulted: it is the frame the intrinsics are expressed in, and a reader that
+ * assumed it would mis-sign the principal-point offset on any other convention — a wrong answer
+ * with no error, which is the one failure mode a metadata block must not have.
+ *
+ * @param {object|null} meta  a parsed `meta.json`.
+ * @returns {object|null} a normalised camera descriptor, or null.
+ */
+export function sogCameraFromMeta(meta) {
+  const c = meta && typeof meta === 'object' ? meta.camera : null;
+  if (!c || typeof c !== 'object') return null;
+  if (c.convention !== 'opencv') {
+    console.warn(
+      `[inline3d/splat] .sog camera block has convention "${c.convention}" — only "opencv" is ` +
+        'understood, so the block is IGNORED and this asset stays on the display rig.',
+    );
+    return null;
+  }
+  const i = c.intrinsics;
+  let intrinsics = null;
+  if (i && typeof i === 'object') {
+    const fx = num(i.fx);
+    const fy = num(i.fy);
+    const cx = num(i.cx);
+    const cy = num(i.cy);
+    const width = num(i.width);
+    const height = num(i.height);
+    if (!(fx > 0) || !(fy > 0) || !(width > 0) || !(height > 0) || cx === null || cy === null) {
+      // Half-believing a lens is worse than having none: with intrinsics optional in v2 there is
+      // a well-defined thing to do instead, which is estimate one from the cloud.
+      console.warn(
+        '[inline3d/splat] .sog camera block has unusable intrinsics — they are DROPPED and the ' +
+          'lens is estimated from the cloud instead; the rest of the block still applies.',
+        i,
+      );
+    } else {
+      intrinsics = { fx, fy, cx, cy, width, height };
+    }
+  }
+  const pos = Array.isArray(c.rest?.position) ? c.rest.position.map((v) => num(v) ?? 0) : [0, 0, 0];
+  const rot = Array.isArray(c.rest?.rotation) ? c.rest.rotation.map((v) => num(v) ?? 0) : [0, 0, 0, 1];
+  const baseline = num(c.stereo?.baseline_m);
+
+  // v2 `rig`. Anything unrecognised is dropped rather than guessed at — the waterfall's next
+  // step (a block means a camera) is a better answer than a typo taken literally.
+  let rig = null;
+  if (c.rig === 'camera' || c.rig === 'display') rig = c.rig;
+  else if (c.rig !== undefined) {
+    console.warn(`[inline3d/splat] .sog camera block has rig "${c.rig}" — ignored`, c.rig);
+  }
+
+  // v2 `focus`. The point is the only required part; the three distances are advisory and are
+  // carried through untouched for a host page that wants them (a depth budget, a HUD).
+  let focus = null;
+  const fp = c.focus?.point;
+  if (Array.isArray(fp) && fp.length >= 3 && fp.every((v) => num(v) !== null)) {
+    focus = {
+      point: [fp[0], fp[1], fp[2]],
+      subject_m: num(c.focus.subject_m),
+      near_m: num(c.focus.near_m),
+      far_m: num(c.focus.far_m),
+      source: typeof c.focus.source === 'string' ? c.focus.source : null,
+    };
+  } else if (c.focus !== undefined) {
+    console.warn('[inline3d/splat] .sog camera block has an unusable focus — ignored', c.focus);
+  }
+
+  // v2 `dxr`. These are the camera rig's ABSOLUTE scalars, and they stay absolute: normalising
+  // them against the convergence distance would make the scene's depth breathe every time the
+  // viewer re-focused.
+  const ipdFactor = num(c.dxr?.ipd_factor);
+  const parallaxFactor = num(c.dxr?.parallax_factor);
+
+  return {
+    convention: 'opencv',
+    rig,
+    focus,
+    dxr: {
+      ipdFactor: ipdFactor !== null && ipdFactor >= 0 ? ipdFactor : null,
+      parallaxFactor: parallaxFactor !== null && parallaxFactor >= 0 ? parallaxFactor : null,
+    },
+    rest: {
+      position: [pos[0] ?? 0, pos[1] ?? 0, pos[2] ?? 0],
+      rotation: [rot[0] ?? 0, rot[1] ?? 0, rot[2] ?? 0, rot[3] ?? 1],
+    },
+    intrinsics,
+    stereo: baseline > 0 ? { baseline_m: baseline } : null,
+    /**
+     * Derived, because every consumer needs them and each is one line to get subtly wrong.
+     *
+     * Null when the block carried no usable intrinsics (legal in v2) — the caller estimates a
+     * lens from the cloud instead.
+     *
+     * `verticalFov` is the FULL vertical angle the capture subtends, in RADIANS — the unit an
+     * XRViewRigInit wants (three's `camera.fov` is the same angle in degrees).
+     *
+     * `principalOffset` is the principal point's offset from the frame centre as a fraction of
+     * the frame, x rightwards and **y upwards** — i.e. already out of OpenCV's y-down frame and
+     * into the GL/three one, so a consumer never has to remember which way `cy` grows. A
+     * rectified stereo pair carries its deconvergence here: shifting the principal point is what
+     * "deconverging" DOES to a pair, so a non-zero x is the capture's zero-disparity plane
+     * expressed as a lens shift rather than as a distance.
+     */
+    verticalFov: intrinsics ? 2 * Math.atan(intrinsics.height / (2 * intrinsics.fy)) : null,
+    principalOffset: intrinsics
+      ? {
+          x: (intrinsics.cx - intrinsics.width / 2) / intrinsics.width,
+          y: -(intrinsics.cy - intrinsics.height / 2) / intrinsics.height,
+        }
+      : null,
+  };
+}
+
+/**
+ * Read the `camera` block straight out of `.sog` bytes. Convenience over
+ * {@link readSogMeta} + {@link sogCameraFromMeta}.
+ *
+ * @param {Uint8Array|ArrayBuffer} bytes
+ * @returns {Promise<object|null>}
+ */
+export async function readSogCamera(bytes) {
+  return sogCameraFromMeta(await readSogMeta(bytes));
+}

package/js/inline3d-splat-perf.js

@@ -0,0 +1,255 @@
+// inline3d-splat-perf.js — cut a Gaussian splat's OVERDRAW, for `./splat`.
+//
+// EXPERIMENTAL. Internal to `./splat`, which re-exports `applySplatPerf` and takes `perf` as an
+// option. Not covered by the SDK's 1.x semver promise — see docs/sdk-stability.md.
+//
+// WHAT COSTS WHAT. On a 1.18M-gaussian photo-lifted scene the per-fragment composite is 75–85 %
+// of the frame (measured natively on an M1 Pro, one eye at 1920×1080), and it is OVERDRAW, not
+// resolution: a handful of enormous, nearly transparent sky splats cover the frame many times
+// over. Splat COUNT is the axis everyone reaches for first and it is the wrong one — decimating
+// this asset to 25 % breaks it visibly (bright stipple on near lit surfaces) while removing far
+// less fill than the two changes below, which remove none of the picture at all.
+//
+// The two that matter, in the native renderer's words: **shrink each splat's quad to the radius
+// where its alpha falls below 1/255**, instead of a fixed 3σ, and **cull gaussians whose peak
+// opacity is already below 1/255**. This module is both of those on Spark.
+//
+// WHY THE FIRST ONE IS FREE. Spark draws every splat as a quad of `maxStdDev` σ (default √8 ≈
+// 2.83σ) and its fragment shader then discards any fragment whose alpha has fallen under
+// `minAlpha` — so for a splat of peak alpha `a` every fragment beyond
+//
+//     r = sqrt(2 · ln(a / minAlpha))
+//
+// is ALREADY being discarded. It is rasterised, interpolated, shaded, and thrown away. Shrinking
+// the quad to exactly that radius therefore removes fragments that contributed nothing: the
+// output is bit-identical (see `alphaRadius` below for the two conditions), and the saving is
+// biggest on exactly the splats that dominate the cost — a haze splat of a = 0.02 needs 1.81σ,
+// not 2.83σ, which is 2.4× fewer fragments for the same pixels.
+//
+// Spark 2.1.0 has no option for that (`maxStdDev` is ONE global uniform, and nothing in the
+// shader derives a radius from alpha), so this patches the vertex shader — through the supported
+// `vertexShader` surface, and by REWRITING SPARK'S OWN SOURCE off the live material rather than
+// shipping a copy of it, so a Spark upgrade brings its shader fixes with it instead of silently
+// pinning this SDK to a fork of a 2.1.0 file. If the anchors ever stop matching, the patch
+// declines with one warning and everything still renders.
+
+/**
+ * Where a splat's alpha has to fall before its quad may be cut, as a fraction of full opacity.
+ *
+ * 1/255 is the native renderer's threshold and the point below which an 8-bit framebuffer cannot
+ * represent the contribution at all. Note Spark's own `minAlpha` default is HALF of this
+ * (0.5/255) — deliberately, so its discard is a shade conservative — which is why `minAlpha` is
+ * a knob here and not an assumption.
+ */
+const ALPHA_FLOOR = 1 / 255;
+
+/**
+ * Presets — chosen from measurements on this exact asset class, not from first principles.
+ *
+ * What the measurement said (1.18M-gaussian SHARP capture, M1 Pro, Chrome/ANGLE-Metal, GPU timer
+ * queries, configs interleaved PER FRAME so clock drift cannot bias one against another; full
+ * table in docs/authoring-inline-3d.md):
+ *
+ *   - **Splat COUNT is not the cost.** 50 % and 25 % decimations of the same scene measured
+ *     within noise of the full one (+5 %, +1 % at 1920×1080). Decimation drops the small
+ *     gaussians; the few enormous ones that cover the frame survive it, and they are the bill.
+ *     A decimated asset is a download and memory win, not a render-cost win.
+ *   - **Quad extent is the cost.** `maxStdDev` √8→√6 is −5…−20 % and √8→√4 is −22 %.
+ *   - **The bit-exact `alphaRadius` buys ~nothing HERE**, because it has nothing to shrink: 86 %
+ *     of this asset's gaussians are near-opaque (mean peak alpha 0.86; Spark doubles the stored
+ *     alpha on top), and an opaque splat's own 1/255 radius is 3.53σ, wider than the √8 ≈ 2.83σ
+ *     it is already drawn at. It stays available and stays exact — a scene of large, low-alpha
+ *     haze is exactly where it pays, and that is the scene the native renderer was tuned on.
+ *
+ * So the presets are honest about which axis works, and nothing is applied unless a caller asks:
+ * `addSplat` with no `perf` leaves every Spark default exactly where Spark put it.
+ */
+export const SPLAT_PERF_PRESETS = {
+  /**
+   * The bit-exact one. No measurable win on a mostly-opaque capture; real on a scene whose cost is
+   * large low-alpha splats. Costs a little vertex ALU, so on a scene with nothing to shrink it can
+   * read as a wash or a shade slower.
+   */
+  exact: {
+    alphaRadius: true,
+    minAlpha: ALPHA_FLOOR,
+  },
+  /** −5…−20 % measured. Truncates every splat's tail at 2.45σ instead of 2.83σ. */
+  balanced: {
+    minAlpha: ALPHA_FLOOR,
+    maxStdDev: Math.sqrt(6),
+  },
+  /** −22 % measured. 2σ, plus the sub-pixel cull. For a phone, not for a hero. */
+  aggressive: {
+    minAlpha: ALPHA_FLOOR,
+    maxStdDev: 2,
+    // Both eigenaxes under a pixel. On the reference capture at 1280×720 and 1920×1080 this
+    // changed ZERO channel bytes — a quad that small usually covers no sample point at all — but
+    // it is framing-dependent by nature, so it is here and not in `balanced`.
+    minPixelRadius: 1,
+  },
+};
+
+/** Fields that are plain properties on SparkRenderer, copied into uniforms every frame. */
+const SPARK_FIELDS = [
+  'minAlpha',
+  'maxStdDev',
+  'minPixelRadius',
+  'maxPixelRadius',
+  'falloff',
+  // LOD budget knobs. Live, but inert unless the MESH was loaded with LOD data — see
+  // splatPerfMeshOptions().
+  'lodSplatCount',
+  'lodSplatScale',
+  'lodRenderScale',
+];
+
+// The two anchors the shader patch needs, quoted from Spark 2.1.0's `splatVertex.glsl`.
+//
+//   `vRgba.a = rgba.a;` is the line AFTER the anti-aliasing blur has been folded into the alpha
+//   (`rgba.a *= blurAdjust`) — so at that point `rgba.a` is exactly the alpha the fragment shader
+//   will interpolate, which is what makes the derived radius exact rather than approximate. It is
+//   also after the eigen-decomposition's inputs are final and BEFORE `scale1`/`scale2` are taken
+//   from `adjustedStdDev`, which is the only window where writing it has any effect.
+const ANCHOR_ALPHA = '    vRgba.a = rgba.a;\n';
+const ANCHOR_UNIFORM = 'uniform float minAlpha;\n';
+
+/**
+ * Rewrite Spark's splat vertex shader so each quad is only as big as its own alpha justifies.
+ *
+ * `falloff` is read (not assumed) because the whole argument rests on the fragment shader's
+ * `a·exp(−z²/2)` decay: at `falloff < 1` the alpha does NOT decay across the quad, nothing is
+ * being discarded, and cutting the quad would cut the picture. The uniform is shared between the
+ * two stages, so the vertex shader only has to declare it.
+ *
+ * @returns {boolean} whether the patch went in.
+ */
+function patchAlphaRadius(material) {
+  const src = material?.vertexShader;
+  if (typeof src !== 'string') return false;
+  if (src.includes('dxrAlphaRadius')) return true; // idempotent — a shared material, or a re-apply
+  if (!src.includes(ANCHOR_ALPHA) || !src.includes(ANCHOR_UNIFORM)) {
+    console.warn(
+      '[inline3d/splat] perf.alphaRadius: this build of Spark does not have the shader lines ' +
+        'this patch rewrites, so the quad-shrink is SKIPPED (everything else still applies, and ' +
+        'the picture is unchanged). Report the Spark version — the anchors are versioned in ' +
+        'js/inline3d-splat-perf.js.',
+    );
+    return false;
+  }
+  material.vertexShader = src
+    .replace(
+      ANCHOR_UNIFORM,
+      `${ANCHOR_UNIFORM}uniform float falloff;\nuniform bool dxrAlphaRadius;\nuniform float dxrAlphaFloor;\n`,
+    )
+    .replace(
+      ANCHOR_ALPHA,
+      `${ANCHOR_ALPHA}
+    // @displayxr/inline3d: shrink the quad to where this splat's own alpha reaches minAlpha.
+    // Every fragment outside that radius is discarded by the fragment shader anyway, so this
+    // removes work and not pixels. Guarded on falloff == 1, which is what makes that true.
+    if (dxrAlphaRadius && (falloff == 1.0) && (rgba.a <= 1.0)) {
+        float floorA = max(dxrAlphaFloor > 0.0 ? dxrAlphaFloor : minAlpha, 1e-6);
+        adjustedStdDev = min(adjustedStdDev, sqrt(max(0.0, 2.0 * log(rgba.a / floorA))));
+        vSplatUv = position.xy * adjustedStdDev;
+    }
+`,
+    );
+  material.uniforms.dxrAlphaRadius = { value: true };
+  // 0 means "use minAlpha", which is the bit-exact cut. See `alphaFloor`.
+  material.uniforms.dxrAlphaFloor = { value: 0 };
+  material.needsUpdate = true;
+  return true;
+}
+
+/**
+ * Apply a perf profile to a live `SparkRenderer`.
+ *
+ * Exported for pages that build their own Spark renderer instead of going through `addSplat`
+ * — the knobs are all live, so this can be called at any time (a quality menu, a battery-saver
+ * toggle) and takes effect on the next frame.
+ *
+ * | option | default (Spark 2.1.0) | effect | safety |
+ * |---|---|---|---|
+ * | `alphaRadius` | — (no such thing) | quad shrunk to the splat's own `alphaFloor` radius | **bit-exact** at the default floor, see below |
+ * | `alphaFloor` | — (= `minAlpha`) | the alpha the tail may be cut at, PER SPLAT | lossy above `minAlpha`, and gently: it spends radius where the splat is opaque and takes it where it is not |
+ * | `minAlpha` | `0.5/255` | splats and fragments under this alpha are dropped | lossy under 1 LSB |
+ * | `maxStdDev` | `√8` | quad extent in σ, globally | lossy: truncates opaque tails |
+ * | `minPixelRadius` | `0` | drop splats under this size in px | lossy: drops fine grain |
+ * | `maxPixelRadius` | `512` | clamp on quad size in px | lossy, and it SQUASHES: the profile is compressed into the smaller quad, not clipped |
+ * | `falloff` | `1` | 1 = Gaussian, 0 = flat | NOT a perf knob — 0 makes the fragment discard stop firing, which costs MORE |
+ *
+ * BIT-EXACT, and the two conditions on that word. `alphaRadius` only removes fragments the
+ * fragment shader was already discarding, so the composited image does not change — provided
+ * `falloff` is 1 (the shader guards this itself) and `minPixelRadius` is 0. With a non-zero
+ * `minPixelRadius` the shrunken quad can fall under it and the splat is then dropped outright,
+ * which is a real (small) change; that is why `balanced` leaves it at 0. At the discard boundary
+ * itself the two sides can disagree by one float ULP, where the fragment's own contribution is
+ * below 1/255 by construction — invisible in 8 bits, but "bit-exact" is stated with that caveat
+ * rather than without it.
+ *
+ * @param {object} spark  a SparkRenderer.
+ * @param {true|'balanced'|'aggressive'|object} perf
+ * @returns {object|null} the profile actually applied.
+ */
+export function applySplatPerf(spark, perf) {
+  if (!spark || !perf) return null;
+  let profile;
+  if (perf === true) profile = SPLAT_PERF_PRESETS.balanced;
+  else if (typeof perf === 'string') profile = SPLAT_PERF_PRESETS[perf];
+  else if (typeof perf === 'object') profile = perf;
+  if (!profile) {
+    console.warn(
+      `[inline3d/splat] unknown perf preset "${perf}" — ignored. ` +
+        `Known: ${Object.keys(SPLAT_PERF_PRESETS).join(', ')}, or an options object.`,
+    );
+    return null;
+  }
+
+  const applied = {};
+  for (const key of SPARK_FIELDS) {
+    if (typeof profile[key] === 'number' && Number.isFinite(profile[key])) {
+      spark[key] = profile[key];
+      applied[key] = profile[key];
+    }
+  }
+  // `alphaFloor` is meaningless on its own — it is the floor the shrink cuts at — so asking for
+  // one asks for the shrink, unless the caller said otherwise in the same breath.
+  const wantRadius = profile.alphaRadius ?? (profile.alphaFloor !== undefined ? true : undefined);
+  if (wantRadius) patchAlphaRadius(spark.material);
+  const u = spark.material?.uniforms;
+  if (u?.dxrAlphaRadius && wantRadius !== undefined) {
+    // Set the value every time rather than relying on the patch: the patch is idempotent, so a
+    // second call asking to turn it back ON would otherwise return early and leave it off.
+    u.dxrAlphaRadius.value = !!wantRadius;
+    applied.alphaRadius = !!wantRadius;
+  }
+  if (u?.dxrAlphaFloor && profile.alphaFloor !== undefined) {
+    u.dxrAlphaFloor.value = Number.isFinite(profile.alphaFloor) ? profile.alphaFloor : 0;
+    applied.alphaFloor = u.dxrAlphaFloor.value;
+  }
+  return applied;
+}
+
+/**
+ * The half of a perf profile that has to go into the `SplatMesh` CONSTRUCTOR rather than onto the
+ * renderer — Spark builds level-of-detail data at load time or not at all.
+ *
+ * LOD is the splat-COUNT axis: Spark keeps a merged, decimated pyramid and picks a level against
+ * a budget (2.5M splats on desktop, 1M on Android) and a minimum on-screen splat size. It is
+ * genuinely lossy — it substitutes merged splats — and it is inert unless the mesh was loaded
+ * with it, which is why it cannot be switched on later from `applySplatPerf`.
+ *
+ * @param {object} perf
+ * @returns {object} extra SplatMesh options (empty when LOD was not asked for).
+ */
+export function splatPerfMeshOptions(perf) {
+  const profile =
+    perf === true
+      ? SPLAT_PERF_PRESETS.balanced
+      : typeof perf === 'string'
+        ? SPLAT_PERF_PRESETS[perf]
+        : perf;
+  if (!profile || !profile.lod) return {};
+  return { lod: profile.lod === 'quality' ? 'quality' : true };
+}