@driftengine/splats 3.61.0

package/dist/splatSogDecoder.js

@@ -0,0 +1,29 @@
+/**
+ * The ordinary WebP decoder for `.sog` captures, which lives here and not beside the reader.
+ *
+ * **Its own module because it is the reader's only reason to name `@driftengine/core`**, and that
+ * import has two costs worth avoiding: a consumer supplying its own decoder should not pull core
+ * through this path, and `scripts/sog-reader.test.mjs` runs under Node's strip-only mode, where an
+ * import that resolves through a `node_modules` symlink is refused outright — which is the trap
+ * `docs/IMPROVEMENTS.md` records under proving a package from its tarball. The reader itself
+ * imports nothing but its own package, so the test loads it and this file stays out of the way.
+ */
+import { createImageTexelDecoder } from '@driftengine/core';
+/**
+ * The ordinary decoder: `@driftengine/core`'s exact texel read.
+ *
+ * **A thin forward, and the reason it is not implemented here is worth reading before anybody
+ * inlines it.** Every browser API that hands back an image's pixels without a GPU premultiplies
+ * on the way through — a 2D canvas by storing premultiplied, WebCodecs by decoding a WebP with
+ * alpha to a premultiplied `BGRA` frame — so every RGB value comes back through
+ * `round(round(c * a / 255) * 255 / a)`. On the committed fixture that is 3 of 255 out on
+ * `sh0.webp`, whose RGB are *codebook indices* and whose alpha is the opacity: an index several
+ * entries away wherever a Gaussian is transparent. `createImageTexelDecoder` reads the same file
+ * exactly, and it lives in core because it is raw WebGL and `AGENTS.md` allows that only there.
+ *
+ * A consumer with its own decoder passes it instead; that is what the parameter is for.
+ */
+export function browserWebpDecoder() {
+    const decode = createImageTexelDecoder();
+    return async (bytes) => decode(bytes, 'image/webp');
+}

package/dist/splatSort.d.ts

@@ -0,0 +1,137 @@
+/** A counting sort over a sixteen-bit depth key: no comparisons, one pass, far to near, budgeted. */
+/** How many buckets the depth key has. A sixteen-bit key, so 65,536 of them. */
+export declare const SPLAT_SORT_BUCKETS = 65536;
+/**
+ * How many buckets the screen-space size key has.
+ *
+ * The key is the top sixteen bits of a positive float's own bit pattern, which reaches 32,640 for
+ * an infinite ratio — so this is the next power of two above that rather than a number with a
+ * meaning of its own. See `sortSplatsByDepth` for why those bits are a usable key at all.
+ */
+export declare const SPLAT_SIZE_BUCKETS = 32768;
+/**
+ * One sort, as the worker protocol and as the function's own parameter list.
+ *
+ * **One object rather than eleven arguments, and the worker is the reason.** `createSplatSortWorker`
+ * posts this and hands `event.data` straight to the sort, so the message shape and the call shape
+ * cannot disagree — which is the failure the 2026-08-17 rule is about, in the one place here where
+ * a decision genuinely does cross a thread boundary.
+ */
+export interface SplatSortRequest {
+    /** Three per splat, in the capture's own space. */
+    readonly positions: Float32Array;
+    /** One per splat: `SplatData.extents`, the largest sigma. Only read when there is a budget. */
+    readonly extents: Float32Array;
+    readonly count: number;
+    /**
+     * The camera's forward **in the capture's own space**, unit length.
+     *
+     * Not the world-space forward: a batch with a model matrix is looked at from a different
+     * direction in its own frame, and `resolveSplatView` is what converts one to the other. One
+     * sorter therefore serves one batch and two batches need no merged order.
+     */
+    readonly dirX: number;
+    readonly dirY: number;
+    readonly dirZ: number;
+    /**
+     * The camera's position in the capture's own space.
+     *
+     * **Invisible in the order and load-bearing in the budget.** Shifting every splat by the same
+     * amount cannot reorder them, so depth alone never needed this; the size key is `extent` over
+     * the *distance*, and a distance needs a point to measure from.
+     */
+    readonly originX: number;
+    readonly originY: number;
+    readonly originZ: number;
+    /** The most splats to keep. Zero, or anything at or above `count`, keeps all of them. */
+    readonly budget: number;
+    /** The buffer to fill and hand back, so the pair can ping-pong rather than allocate. */
+    readonly out: Uint32Array;
+}
+/**
+ * What a sort answers with: the filled buffer, and how many entries of it are real.
+ *
+ * **The count is not the request's count once a budget bites**, and it comes back rather than
+ * being recomputed, because only the sort knows how its ration of the straddling size bucket
+ * fell out. A caller that assumed the capture's own count would walk off the end of a valid order
+ * into whatever the buffer held before — stale indices drawn as splats, which reads as a corrupt
+ * capture rather than as an off-by-one.
+ */
+export interface SplatSortResult {
+    /** The buffer that was handed in, or the same storage after a worker transferred it twice. */
+    readonly order: Uint32Array;
+    readonly count: number;
+}
+/**
+ * How a sort actually happens.
+ *
+ * **A capability the caller may replace, which is `AGENTS.md`'s rule about platform APIs and not a
+ * convenience.** The shipped default is a worker; a consumer under a strict CSP, in a test, or on
+ * a runtime with no `Worker` at all supplies its own and nothing here has to know.
+ */
+export type SplatSortFn = (request: SplatSortRequest) => Promise<SplatSortResult>;
+/**
+ * The arrays a sort reuses, allocated once by the caller.
+ *
+ * **A sort allocates nothing**, which is the whole reason this is a parameter rather than a local:
+ * the two histograms are 384 KB between them, and a capture re-sorts whenever the view turns. Doing
+ * that in a worker does not make an allocation free — it makes it somebody else's garbage.
+ */
+export interface SplatSortScratch {
+    /** The depth bucket of each splat, carried from the counting pass to the scatter. */
+    readonly keys: Uint16Array;
+    /** The depth histogram, then the prefix sum over it. */
+    readonly counts: Uint32Array;
+    /** The size bucket of each splat, overwritten by the counting pass with whether it survived. */
+    readonly sizes: Uint16Array;
+    /** The size histogram, walked from the top to find the budget's threshold. */
+    readonly sizeCounts: Uint32Array;
+    /**
+     * Two views of one four-byte buffer, for reading a float's bits without allocating a view.
+     *
+     * A pair rather than a `DataView` because this is read once per splat per sort and the typed
+     * pair is one store and one load. It is in the scratch rather than at module scope for the same
+     * reason everything else here is: the sort is stringified into a worker and closes over nothing.
+     */
+    readonly bits: Float32Array;
+    readonly bitsAsUint: Uint32Array;
+}
+export declare function createSplatSortScratch(count: number): SplatSortScratch;
+/**
+ * Order the splats worth drawing far to near, writing indices into `request.out`.
+ *
+ * Returns how many were written, which is `count` unless a budget cut it.
+ *
+ * **Far to near, and the direction is the one thing a test can catch that a screenshot cannot.**
+ * A near-to-far order looks *plausible* — the cloud is still a cloud — and is wrong at every
+ * silhouette, because `over` compositing is not commutative. `dir` is the camera's forward in the
+ * capture's own space, so a larger projection along it is farther away and this sorts descending.
+ *
+ * **A counting sort rather than a comparison sort**, which is what makes it affordable at a
+ * million splats: one pass for the range, one to bucket, one prefix sum, one to scatter, all
+ * linear. `Array.prototype.sort` on a million indices is tens of milliseconds and allocates.
+ *
+ * **Sixteen bits is 65,536 distinct depths across the capture's whole extent.** At a capture ten
+ * metres deep that is 0.15 mm a bucket, far below what any ordering error could show. What it
+ * gives up is exactness: two splats inside one bucket keep their input order rather than their
+ * true order, which is a tie broken arbitrarily and invisible. What would make it wrong is a
+ * capture whose depth range is dominated by one distant outlier, which squeezes everything else
+ * into a handful of buckets — the same failure a histogram always has, and the reason the range
+ * is measured rather than assumed.
+ *
+ * **A budget selects by screen-space size, and taking a prefix of the order instead would be
+ * wrong in a way that looks deliberate.** The order is far to near, so its front is the far end:
+ * `splatBudget.test.ts` measures that, rather than leaving it to be recalled. A prefix therefore
+ * keeps the distant half of a capture and throws away everything close to the camera — the splats
+ * covering the most pixels, and most of what a viewer is looking at. A suffix inverts the mistake
+ * and drops the backdrop. Neither is a budget; both are a capture with a piece missing.
+ *
+ * So the splats kept are the ones largest **on screen**, which is the extent over the distance,
+ * and the ones dropped are by construction smaller than every one kept. What that gives up is
+ * stability: as the camera closes on a capture, splats cross the threshold and appear, which is
+ * a pop bounded by the size of the smallest splat still being drawn — around a pixel at any
+ * budget worth setting, and unmissable at a budget of a few thousand. What would make it wrong is
+ * a capture of very flat splats seen edge-on, where the largest sigma over-estimates the pixels
+ * covered; `SplatData.extents` carries that same caveat, because it is the same approximation.
+ */
+export declare function sortSplatsByDepth(request: SplatSortRequest, scratch: SplatSortScratch): number;

package/dist/splatSort.js

@@ -0,0 +1,199 @@
+/** A counting sort over a sixteen-bit depth key: no comparisons, one pass, far to near, budgeted. */
+/** How many buckets the depth key has. A sixteen-bit key, so 65,536 of them. */
+export const SPLAT_SORT_BUCKETS = 65536;
+/**
+ * How many buckets the screen-space size key has.
+ *
+ * The key is the top sixteen bits of a positive float's own bit pattern, which reaches 32,640 for
+ * an infinite ratio — so this is the next power of two above that rather than a number with a
+ * meaning of its own. See `sortSplatsByDepth` for why those bits are a usable key at all.
+ */
+export const SPLAT_SIZE_BUCKETS = 32768;
+export function createSplatSortScratch(count) {
+    const bits = new ArrayBuffer(4);
+    return {
+        keys: new Uint16Array(Math.max(1, count)),
+        counts: new Uint32Array(SPLAT_SORT_BUCKETS),
+        sizes: new Uint16Array(Math.max(1, count)),
+        sizeCounts: new Uint32Array(SPLAT_SIZE_BUCKETS),
+        bits: new Float32Array(bits),
+        bitsAsUint: new Uint32Array(bits),
+    };
+}
+/**
+ * Order the splats worth drawing far to near, writing indices into `request.out`.
+ *
+ * Returns how many were written, which is `count` unless a budget cut it.
+ *
+ * **Far to near, and the direction is the one thing a test can catch that a screenshot cannot.**
+ * A near-to-far order looks *plausible* — the cloud is still a cloud — and is wrong at every
+ * silhouette, because `over` compositing is not commutative. `dir` is the camera's forward in the
+ * capture's own space, so a larger projection along it is farther away and this sorts descending.
+ *
+ * **A counting sort rather than a comparison sort**, which is what makes it affordable at a
+ * million splats: one pass for the range, one to bucket, one prefix sum, one to scatter, all
+ * linear. `Array.prototype.sort` on a million indices is tens of milliseconds and allocates.
+ *
+ * **Sixteen bits is 65,536 distinct depths across the capture's whole extent.** At a capture ten
+ * metres deep that is 0.15 mm a bucket, far below what any ordering error could show. What it
+ * gives up is exactness: two splats inside one bucket keep their input order rather than their
+ * true order, which is a tie broken arbitrarily and invisible. What would make it wrong is a
+ * capture whose depth range is dominated by one distant outlier, which squeezes everything else
+ * into a handful of buckets — the same failure a histogram always has, and the reason the range
+ * is measured rather than assumed.
+ *
+ * **A budget selects by screen-space size, and taking a prefix of the order instead would be
+ * wrong in a way that looks deliberate.** The order is far to near, so its front is the far end:
+ * `splatBudget.test.ts` measures that, rather than leaving it to be recalled. A prefix therefore
+ * keeps the distant half of a capture and throws away everything close to the camera — the splats
+ * covering the most pixels, and most of what a viewer is looking at. A suffix inverts the mistake
+ * and drops the backdrop. Neither is a budget; both are a capture with a piece missing.
+ *
+ * So the splats kept are the ones largest **on screen**, which is the extent over the distance,
+ * and the ones dropped are by construction smaller than every one kept. What that gives up is
+ * stability: as the camera closes on a capture, splats cross the threshold and appear, which is
+ * a pop bounded by the size of the smallest splat still being drawn — around a pixel at any
+ * budget worth setting, and unmissable at a budget of a few thousand. What would make it wrong is
+ * a capture of very flat splats seen edge-on, where the largest sigma over-estimates the pixels
+ * covered; `SplatData.extents` carries that same caveat, because it is the same approximation.
+ */
+export function sortSplatsByDepth(request, scratch) {
+    const { positions, extents, count, dirX, dirY, dirZ, originX, originY, originZ, out } = request;
+    if (count <= 0)
+        return 0;
+    const { keys, counts, sizes, sizeCounts, bits, bitsAsUint } = scratch;
+    /*
+     * **The bucket counts come from the scratch, not from the module constants, and that is what
+     * lets this function be stringified into a worker.** `createSplatSortWorker` ships
+     * `sortSplatsByDepth.toString()` so there is one implementation of the ordering rather than two
+     * — and a stringified function loses its scope, so any module-scope binding it referenced would
+     * be an undefined identifier the moment a bundler renamed or dropped it. Reading `.length`
+     * closes over nothing. `splatSort.test.ts` asserts the source is free of such references.
+     */
+    const buckets = counts.length;
+    /* Normalised to zero, so every test below is against one number rather than against two. */
+    const budget = request.budget > 0 && request.budget < count ? request.budget : 0;
+    let min = Infinity;
+    let max = -Infinity;
+    if (budget > 0)
+        sizeCounts.fill(0);
+    for (let index = 0; index < count; index++) {
+        const p = index * 3;
+        const depth = ((positions[p] ?? 0) - originX) * dirX +
+            ((positions[p + 1] ?? 0) - originY) * dirY +
+            ((positions[p + 2] ?? 0) - originZ) * dirZ;
+        if (depth < min)
+            min = depth;
+        if (depth > max)
+            max = depth;
+        if (budget > 0) {
+            /*
+             * The screen-space radius is the focal length times `extent / depth`, and the focal length
+             * is the same for every splat in a frame — so it drops out of a ranking and this is the
+             * whole key.
+             *
+             * **The key is the top sixteen bits of the ratio's own float bits**, which for a positive
+             * float is exactly monotone: IEEE 754 lays out sign, then exponent, then mantissa, so a
+             * larger positive float has a larger bit pattern, and taking the high half keeps the sign,
+             * all eight exponent bits and seven of the mantissa. That is a logarithmic quantisation —
+             * 128 buckets an octave, so a threshold lands within half a percent of the ideal size cut —
+             * at the cost of one store and one load rather than a `Math.log2` per splat per sort. What
+             * would make it wrong is a negative key, which cannot happen: the guard below sends
+             * everything that is not a positive ratio to bucket zero.
+             *
+             * A splat at or behind the camera has no screen-space size, so `depth <= 0` fails
+             * `ratio > 0` and lands in bucket zero, where the budget drops it first. So does a `NaN`,
+             * because every comparison against one is false — which is the honest answer for a splat
+             * whose size cannot be computed.
+             */
+            const ratio = (extents[index] ?? 0) / depth;
+            let key = 0;
+            if (ratio > 0) {
+                bits[0] = ratio;
+                key = (bitsAsUint[0] ?? 0) >>> 16;
+            }
+            sizes[index] = key;
+            sizeCounts[key] = (sizeCounts[key] ?? 0) + 1;
+        }
+    }
+    /*
+     * The threshold, and the quota that trims the bucket straddling it.
+     *
+     * Walking down from the largest size, `above` is everything strictly bigger than `threshold`
+     * and fits inside the budget by construction. The bucket that would overflow it is *included*
+     * and then rationed: `quota` splats from it are admitted in index order and the rest are not.
+     * Without that ration a capture whose splats are all one size — which is most synthetic ones,
+     * and any capture from a fixed-scale exporter — would put every splat in one bucket and the
+     * threshold alone would answer either everything or nothing. Nothing is a blank screen on
+     * exactly the device the budget exists for.
+     */
+    let threshold = 0;
+    let quota = 0;
+    if (budget > 0) {
+        let above = 0;
+        for (let bucket = sizeCounts.length - 1; bucket >= 0; bucket--) {
+            const howMany = sizeCounts[bucket] ?? 0;
+            threshold = bucket;
+            if (above + howMany > budget)
+                break;
+            above += howMany;
+        }
+        quota = budget - above;
+    }
+    /*
+     * A capture with no depth range at all — one splat, or a plane exactly side-on. Every key would
+     * be a division by zero, so the scale is zero and every splat lands in bucket 0 in input order.
+     * That is a legal answer: with no range there is no ordering to get wrong.
+     *
+     * The range spans every splat rather than only the ones inside the budget, because it is
+     * measured before the threshold is known. What that costs is depth resolution when a budget
+     * discards a distant tail; at 65,536 buckets there is a great deal to spare.
+     */
+    const range = max - min;
+    const scale = range > 0 ? (buckets - 1) / range : 0;
+    counts.fill(0);
+    let admitted = 0;
+    let remaining = quota;
+    for (let index = 0; index < count; index++) {
+        if (budget > 0) {
+            const size = sizes[index] ?? 0;
+            const keep = size > threshold || (size === threshold && remaining > 0);
+            if (keep && size === threshold)
+                remaining--;
+            /* Overwritten with the verdict, so the scatter admits exactly this set without re-running
+               the ration. The size itself is not wanted again. */
+            sizes[index] = keep ? 1 : 0;
+            if (!keep)
+                continue;
+        }
+        const p = index * 3;
+        const depth = ((positions[p] ?? 0) - originX) * dirX +
+            ((positions[p + 1] ?? 0) - originY) * dirY +
+            ((positions[p + 2] ?? 0) - originZ) * dirZ;
+        /*
+         * Inverted, so that an *ascending* bucket walk comes out far to near. Doing it here rather
+         * than by walking the histogram backwards keeps the scatter a plain forward loop, and a
+         * backwards scatter is where a stable sort quietly stops being stable.
+         */
+        const bucket = buckets - 1 - Math.round((depth - min) * scale);
+        keys[index] = bucket;
+        counts[bucket] = (counts[bucket] ?? 0) + 1;
+        admitted++;
+    }
+    /* Prefix sum in place: each bucket becomes where its first splat goes. */
+    let running = 0;
+    for (let bucket = 0; bucket < buckets; bucket++) {
+        const howMany = counts[bucket] ?? 0;
+        counts[bucket] = running;
+        running += howMany;
+    }
+    for (let index = 0; index < count; index++) {
+        if (budget > 0 && sizes[index] === 0)
+            continue;
+        const bucket = keys[index] ?? 0;
+        const at = counts[bucket] ?? 0;
+        out[at] = index;
+        counts[bucket] = at + 1;
+    }
+    return admitted;
+}

package/dist/splatSortWorker.d.ts

@@ -0,0 +1,14 @@
+/** The shipped sort capability: a worker built from a Blob, falling back to the main thread aloud. */
+import type { SplatSortFn } from './splatSort.ts';
+/**
+ * Build the default sort capability.
+ *
+ * **Falls back to the main thread aloud, once.** A strict CSP without `worker-src blob:` refuses
+ * the construction, and so does any runtime with no `Worker` at all. A capture that stutters is
+ * better than one that does not draw — and a *silent* fallback is what `capabilityClamp` exists to
+ * prevent, because the symptom is then a frame rate nobody can attribute.
+ *
+ * The sort's source is passed in rather than imported here so this module has no opinion about
+ * where the function lives; `createDefaultSplatSort` supplies it.
+ */
+export declare function createSplatSortWorker(sortSource: string): SplatSortFn;

package/dist/splatSortWorker.js

@@ -0,0 +1,137 @@
+/** The shipped sort capability: a worker built from a Blob, falling back to the main thread aloud. */
+import { sortOnMainThread } from './splatSorter.js';
+import { SPLAT_SIZE_BUCKETS, SPLAT_SORT_BUCKETS } from './splatSort.js';
+/**
+ * The sort, as source, for a worker that has no module graph to import from.
+ *
+ * **Stringified rather than a second file, and that is the no-build-step contract.** This engine
+ * ships TypeScript source and consumers bundle it; `new Worker(new URL('./x.ts', import.meta.url))`
+ * asks every consumer's bundler to know about a worker entry point, which is a build step by
+ * another name. A `Blob` needs nothing of anybody.
+ *
+ * **What it costs is a copy of the sort that no test can reach**, so the two could drift — which is
+ * exactly what the 2026-08-17 rule is about. It does not drift here because it is not written
+ * twice: `sortSplatsByDepth.toString()` is interpolated below, so the worker runs the same
+ * function the main thread does, and a change to that function changes both. What would make it
+ * wrong is that function closing over a module-scope binding, since a stringified closure loses
+ * its scope — which is why it takes its scratch as a parameter and its bucket counts as part of it.
+ *
+ * **The capture is cached in the worker and re-sent only when it changes.** Positions are twelve
+ * bytes a splat and extents four, so posting them with every sort would structured-clone sixteen
+ * megabytes for a million-splat capture — several times a second while a viewer turns, on the
+ * device this whole arrangement exists for. The sender omits them when the capture is the one the
+ * worker already holds, and `null` is what says so.
+ */
+function workerSource(sortSource) {
+    return `
+const SPLAT_SORT_BUCKETS = ${SPLAT_SORT_BUCKETS};
+const SPLAT_SIZE_BUCKETS = ${SPLAT_SIZE_BUCKETS};
+const sortSplatsByDepth = ${sortSource};
+let scratch = null;
+let positions = null;
+let extents = null;
+self.onmessage = (event) => {
+  const request = event.data;
+  if (request.positions !== null) positions = request.positions;
+  if (request.extents !== null) extents = request.extents;
+  const count = request.count;
+  if (scratch === null || scratch.keys.length < count) {
+    const bits = new ArrayBuffer(4);
+    scratch = {
+      keys: new Uint16Array(Math.max(1, count)),
+      counts: new Uint32Array(SPLAT_SORT_BUCKETS),
+      sizes: new Uint16Array(Math.max(1, count)),
+      sizeCounts: new Uint32Array(SPLAT_SIZE_BUCKETS),
+      bits: new Float32Array(bits),
+      bitsAsUint: new Uint32Array(bits),
+    };
+  }
+  request.positions = positions;
+  request.extents = extents;
+  const kept = sortSplatsByDepth(request, scratch);
+  /* Transferred back, so the pair ping-pongs rather than allocating a result a frame. */
+  self.postMessage({ order: request.out, count: kept }, [request.out.buffer]);
+};
+`;
+}
+/**
+ * Build the default sort capability.
+ *
+ * **Falls back to the main thread aloud, once.** A strict CSP without `worker-src blob:` refuses
+ * the construction, and so does any runtime with no `Worker` at all. A capture that stutters is
+ * better than one that does not draw — and a *silent* fallback is what `capabilityClamp` exists to
+ * prevent, because the symptom is then a frame rate nobody can attribute.
+ *
+ * The sort's source is passed in rather than imported here so this module has no opinion about
+ * where the function lives; `createDefaultSplatSort` supplies it.
+ */
+export function createSplatSortWorker(sortSource) {
+    let worker = null;
+    let warned = false;
+    const fallback = (reason) => {
+        if (!warned) {
+            warned = true;
+            console.warn(`splats: sorting on the main thread — ${reason}. A capture will stutter while the view ` +
+                'turns. Supply your own `sort` capability to put it somewhere else.');
+        }
+        return sortOnMainThread;
+    };
+    try {
+        if (typeof Worker === 'undefined' ||
+            typeof Blob === 'undefined' ||
+            typeof URL === 'undefined') {
+            return fallback('this runtime has no Worker');
+        }
+        const url = URL.createObjectURL(new Blob([workerSource(sortSource)], { type: 'text/javascript' }));
+        worker = new Worker(url);
+        /* The blob is referenced by the live worker; the URL is only the handle. */
+        URL.revokeObjectURL(url);
+    }
+    catch (error) {
+        return fallback(String(error.message ?? error));
+    }
+    const live = worker;
+    /* Identity, not a copy: `SplatData` owns these arrays for its lifetime, so the same reference
+       arriving twice is exactly the statement that the worker's copy is still current. */
+    let sentPositions = null;
+    let sentExtents = null;
+    return (request) => new Promise((resolve, reject) => {
+        const onMessage = (event) => {
+            live.removeEventListener('message', onMessage);
+            live.removeEventListener('error', onError);
+            resolve(event.data);
+        };
+        const onError = (event) => {
+            live.removeEventListener('message', onMessage);
+            live.removeEventListener('error', onError);
+            /* The worker never learned this capture, so the next attempt must send it again. */
+            sentPositions = null;
+            sentExtents = null;
+            reject(new Error(`splats: the sort worker failed — ${event.message}`));
+        };
+        live.addEventListener('message', onMessage);
+        live.addEventListener('error', onError);
+        const positions = request.positions === sentPositions ? null : request.positions;
+        const extents = request.extents === sentExtents ? null : request.extents;
+        sentPositions = request.positions;
+        sentExtents = request.extents;
+        /*
+         * `out` is transferred and the capture is copied at most once. Copying rather than
+         * transferring the capture is the price of not owning it: the positions belong to the
+         * `SplatData` and the main thread reads them for a fallback sort.
+         */
+        live.postMessage({
+            positions,
+            extents,
+            count: request.count,
+            dirX: request.dirX,
+            dirY: request.dirY,
+            dirZ: request.dirZ,
+            originX: request.originX,
+            originY: request.originY,
+            originZ: request.originZ,
+            budget: request.budget,
+            out: request.out,
+        }, [request.out.buffer]);
+    });
+}

package/dist/splatSorter.d.ts

@@ -0,0 +1,112 @@
+/** The scheduler: one sort in flight, newest view wins, and the worker is a default not a mechanism. */
+import type { SplatSortFn, SplatSortRequest, SplatSortResult } from './splatSort.ts';
+import type { SplatData } from './splatData.ts';
+import type { SplatViewLocal } from './splatView.ts';
+export interface SplatSorterOptions {
+    /** The capture. Its positions, extents and bounds are all read; its packed texels are not. */
+    readonly splats: SplatData;
+    /** Defaults to a `Blob` worker, falling back to the main thread. See `createDefaultSplatSort`. */
+    readonly sort?: SplatSortFn;
+    /**
+     * The most splats to draw. Zero, or anything at or above the capture's count, draws all of them.
+     *
+     * `defaultSplatBudget` is what a consumer that has no number of its own should pass.
+     */
+    readonly budget?: number;
+    /** Overrides `RESORT_MOVE_FRACTION`. Only consulted when there is a budget. */
+    readonly moveFraction?: number;
+    /**
+     * How many of the capture's splats have actually arrived. Defaults to all of them.
+     *
+     * **A capability rather than a number, because it changes while a capture streams.** A
+     * `SplatCapture` is allocated at its final count and filled block by block, so its unarrived
+     * tail is zeroed — every phantom splat sitting at the origin with no size. Sorting those would
+     * order a cloud of them into the middle of the capture and draw them, which reads as a corrupt
+     * file rather than as a load in progress. Pass `() => capture.ready` and this follows the load.
+     */
+    readonly ready?: () => number;
+}
+export declare function sortOnMainThread(request: SplatSortRequest): Promise<SplatSortResult>;
+/**
+ * The shipped capability: a worker over the same sort this module runs on the main thread.
+ *
+ * `sortSplatsByDepth.toString()` is what goes into the worker, so there is one implementation of
+ * the decision and not two — the 2026-08-17 rule, which is about exactly this. It works because
+ * that function closes over nothing: its scratch and its two bucket counts all arrive as
+ * arguments.
+ */
+export declare function createDefaultSplatSort(): SplatSortFn;
+/**
+ * Hold the newest order, ask for a new one when the view has changed enough, and never queue.
+ *
+ * **At most one sort in flight, and a request while one is running is dropped rather than
+ * queued.** The newest view is the only one worth sorting for: a queue would sort for a camera
+ * position the player has already left, and then sort again, so it converts a busy moment into a
+ * backlog that never catches up.
+ *
+ * **Two buffers, ping-ponged.** One is being filled by the sorter and the other is what the pass
+ * draws from, so a sort landing mid-frame never rewrites the order under a draw call.
+ */
+export declare class SplatSorter {
+    private readonly splats;
+    private readonly sort;
+    private readonly budget;
+    private readonly moveFraction;
+    private readonly ready;
+    /** How many splats the standing order was computed over, so an arrival is a reason to re-sort. */
+    private sortedReady;
+    /** Half the diagonal of the capture's own bounds. The scale the move gate is a fraction of. */
+    private readonly radius;
+    private readonly buffers;
+    /** Which buffer the sorter owns. The other is the one a caller may read. */
+    private filling;
+    private inFlight;
+    /** The view the standing order was computed for. Meaningless until `hasSorted`. */
+    private sortedDirX;
+    private sortedDirY;
+    private sortedDirZ;
+    private sortedOriginX;
+    private sortedOriginY;
+    private sortedOriginZ;
+    private hasSorted;
+    /** How many indices the standing order actually holds, which a budget makes smaller. */
+    private kept;
+    /** Bumped by every sort that lands, so a caller can tell a new order from the one it has. */
+    private generation;
+    constructor(options: SplatSorterOptions);
+    /** The standing order, or null until the first sort lands. */
+    get order(): Uint32Array | null;
+    /** How many entries of `order` are real. Below the capture's count when a budget bit. */
+    get drawCount(): number;
+    /** How many orders have landed. A caller uploads when this changes and not otherwise. */
+    get version(): number;
+    /**
+     * Whether a sort is in flight.
+     *
+     * **What a measuring page waits on, and it has to wait on more than `version`.** With a budget
+     * the sort chooses *which* splats are drawn and not merely their order, so a capture
+     * photographed at the first landed sort is a capture photographed at whichever sort the worker
+     * happened to finish — and two backends that reach the held frame at different wall-clock times
+     * then draw different splats. A held camera is settled when this is false and the standing
+     * `version` has been uploaded: at a fixed direction `frame` asks for nothing further, so that
+     * state is reached and then keeps.
+     */
+    get sorting(): boolean;
+    /**
+     * Offer the current view, in the capture's own space. Starts a sort if one is wanted.
+     *
+     * `resolveSplatView` is what turns a camera and a model matrix into this. `force` is for the
+     * first frame and for a capture whose transform moved, where the view in its own space may be
+     * unchanged and the order is stale anyway.
+     *
+     * **Turning always matters; moving only matters when there is a budget.** Depth is measured
+     * along the view axis, so translating the camera shifts every splat's depth by the same amount
+     * and leaves the ordering exactly as it was — which is why this gate did not exist until a
+     * budget did. A budget keeps the splats largest on screen, which is the extent over the
+     * *distance*, so a camera that walks across a capture without turning changes which splats are
+     * drawn. What that costs is a sort every tenth of a capture-radius while a viewer moves; what
+     * would make it wrong is a budget so generous that nothing is ever dropped, where the gate spends
+     * sorts to reach the same answer.
+     */
+    frame(local: SplatViewLocal, force?: boolean): void;
+}