@driftengine/texture 4.0.0

package/dist/inference.js

@@ -0,0 +1,243 @@
+/**
+ * A small network evaluator, and the only one this engine has.
+ *
+ * **Three things use it**: a DriftTexture's decode, reconstruction's refinement tier, and capture's
+ * reconstruction. That is the argument for building it carefully and once — a second inference path
+ * is a second set of numerical conventions to keep in step, and the first symptom of them drifting
+ * is a picture that is slightly wrong everywhere.
+ *
+ * **The constraint that shapes it: WebGPU exposes no hardware matrix units.** The desktop graphics
+ * interfaces reach them through cooperative vectors and the published neural-texture work depends
+ * on that. So the network here has to be small enough that ordinary vector arithmetic suffices,
+ * and its size is decided by measurement against a frame budget rather than by copying an
+ * architecture that assumed hardware this platform does not have.
+ *
+ * **The activation applies to hidden layers and not to the output.** Applying it to the output
+ * clamps every channel into the activation's range, which produces a washed-out picture that a
+ * training loss will not reveal — the network simply learns around it and infers badly.
+ */
+import { fromHalfBits, roundHalf } from './half.js';
+/** How many weights and biases a shape needs, laid out layer by layer. */
+export function networkWeightCount(shape) {
+    let total = 0;
+    let previous = shape.inputs;
+    for (const width of shape.hidden) {
+        total += previous * width + width;
+        previous = width;
+    }
+    return total + previous * shape.outputs + shape.outputs;
+}
+/** Rectified linear, which is what the generated shader will use too. */
+function activate(value) {
+    return value > 0 ? value : 0;
+}
+/**
+ * Evaluate the network, writing `shape.outputs` values into `out`.
+ *
+ * Weights are read in layer order: for each layer, the weight matrix row-major by output, then the
+ * biases. `scratch` must hold at least twice the widest layer and is reused across calls so this
+ * allocates nothing.
+ */
+export function evalNetwork(shape, weights, input, out, scratch) {
+    const widest = Math.max(shape.inputs, shape.outputs, ...shape.hidden, 1);
+    let current = scratch.subarray(0, widest);
+    let next = scratch.subarray(widest, widest * 2);
+    for (let i = 0; i < shape.inputs; i += 1)
+        current[i] = input[i];
+    let at = 0;
+    let previous = shape.inputs;
+    for (const width of shape.hidden) {
+        for (let o = 0; o < width; o += 1) {
+            let sum = 0;
+            for (let i = 0; i < previous; i += 1) {
+                sum += current[i] * weights[at + o * previous + i];
+            }
+            next[o] = activate(sum + weights[at + width * previous + o]);
+        }
+        at += previous * width + width;
+        previous = width;
+        const swap = current;
+        current = next;
+        next = swap;
+    }
+    for (let o = 0; o < shape.outputs; o += 1) {
+        let sum = 0;
+        for (let i = 0; i < previous; i += 1) {
+            sum += current[i] * weights[at + o * previous + i];
+        }
+        /* No activation here. See the header. */
+        out[o] = sum + weights[at + shape.outputs * previous + o];
+    }
+}
+/*
+ * The most one rounding can move a value of this magnitude: half a unit in the last place, which is
+ * 2^-11 of the value for a normal half-precision number and 2^-25 below them. Single precision's
+ * own rounding, which the reference and the device do too, is the same argument at 2^-24.
+ */
+function halfRounding(magnitude) {
+    return Math.max(magnitude * 2 ** -11, 2 ** -25);
+}
+function singleRounding(magnitude) {
+    return Math.max(magnitude * 2 ** -24, 2 ** -150);
+}
+/**
+ * How far the half-precision evaluation of this network, at this input, can sit from the
+ * single-precision one.
+ *
+ * **A bound per network rather than one tolerance for all**, because a sampled tolerance is a claim
+ * about the corpus that sampled it — 2,400 networks put the worst relative error at 0.00213, the
+ * device's own corpus reached 0.0039, and 40,000 reached 0.0066. This carries the error instead:
+ * the weights' and the input's own rounding exactly, then half a unit in the last place for every
+ * product, every partial sum and the bias, through each layer — a rectifier moves no error, since
+ * it is one-Lipschitz. **It holds whichever form a device computes**: every operation rounded, or
+ * each multiply-add contracted into a single rounding, which WGSL permits and this project's
+ * development machine does. It assumes no value overflows, which `activationBound` is for.
+ */
+export function halfPrecisionErrorBound(shape, weights, input) {
+    let value = Array.from({ length: shape.inputs }, (_, i) => input[i]);
+    let error = value.map((x) => Math.abs(roundHalf(x) - x) + singleRounding(Math.abs(x)));
+    let worst = 0;
+    let at = 0;
+    let previous = shape.inputs;
+    const layers = shape.hidden.length + 1;
+    for (let layer = 0; layer < layers; layer += 1) {
+        const width = layer < shape.hidden.length ? shape.hidden[layer] : shape.outputs;
+        const hidden = layer < shape.hidden.length;
+        const nextValue = [];
+        const nextError = [];
+        for (let o = 0; o < width; o += 1) {
+            let exact = 0;
+            let carried = 0;
+            let magnitude = 0;
+            let rounding = 0;
+            for (let i = 0; i < previous; i += 1) {
+                const weight = weights[at + o * previous + i];
+                const drift = Math.abs(roundHalf(weight) - weight);
+                const x = value[i];
+                const e = error[i];
+                exact += x * weight;
+                /* |xh·wh − x·w| ≤ |xh − x|·|wh| + |x|·|wh − w|. */
+                carried += e * (Math.abs(weight) + drift) + Math.abs(x) * drift;
+                const product = (Math.abs(x) + e) * (Math.abs(weight) + drift);
+                magnitude += product + rounding;
+                rounding +=
+                    halfRounding(product) +
+                        halfRounding(magnitude) +
+                        singleRounding(product) +
+                        singleRounding(magnitude);
+            }
+            const bias = weights[at + width * previous + o];
+            const biasDrift = Math.abs(roundHalf(bias) - bias);
+            exact += bias;
+            carried += biasDrift;
+            magnitude += Math.abs(bias) + biasDrift + rounding;
+            rounding += halfRounding(magnitude) + singleRounding(magnitude);
+            const total = carried + rounding;
+            if (hidden) {
+                nextValue.push(Math.max(0, exact));
+                nextError.push(total);
+            }
+            else {
+                worst = Math.max(worst, total);
+            }
+        }
+        at += previous * width + width;
+        previous = width;
+        value = nextValue;
+        error = nextError;
+    }
+    return worst;
+}
+/**
+ * Evaluate the network as a device with `enable f16` would, writing `shape.outputs` values into
+ * `out`.
+ *
+ * **Every multiply and every add is rounded**, because that is what a sixteen-bit adder does, and
+ * the arithmetic is in doubles so the rounding is the only approximation. The order is the
+ * device's: the weighted inputs summed in index order, then the bias, then the rectifier —
+ * `render/shaders/network.wgsl.ts` in `@driftengine/core` is written to match it.
+ *
+ * `weights` are half-precision bits, as `halfWeights` produces and an `NNET` chunk stores. Inputs
+ * are rounded to half precision on the way in. `scratch` holds at least twice the widest layer.
+ */
+export function evalNetworkHalf(shape, weights, input, out, scratch, contract = false) {
+    const widest = Math.max(shape.inputs, shape.outputs, ...shape.hidden, 1);
+    let current = scratch.subarray(0, widest);
+    let next = scratch.subarray(widest, widest * 2);
+    for (let i = 0; i < shape.inputs; i += 1)
+        current[i] = roundHalf(input[i]);
+    let at = 0;
+    let previous = shape.inputs;
+    const layers = shape.hidden.length + 1;
+    for (let layer = 0; layer < layers; layer += 1) {
+        const width = layer < shape.hidden.length ? shape.hidden[layer] : shape.outputs;
+        const hidden = layer < shape.hidden.length;
+        for (let o = 0; o < width; o += 1) {
+            let sum = 0;
+            for (let i = 0; i < previous; i += 1) {
+                const product = current[i] * fromHalfBits(weights[at + o * previous + i]);
+                sum = contract ? roundHalf(sum + product) : roundHalf(sum + roundHalf(product));
+            }
+            sum = roundHalf(sum + fromHalfBits(weights[at + width * previous + o]));
+            const value = hidden ? (sum > 0 ? sum : 0) : sum;
+            if (hidden)
+                next[o] = value;
+            else
+                out[o] = value;
+        }
+        at += previous * width + width;
+        previous = width;
+        const swap = current;
+        current = next;
+        next = swap;
+    }
+}
+/**
+ * The largest magnitude any product, partial sum or output of the network can reach over the given
+ * input box.
+ *
+ * **What a consumer asks before it chooses half precision.** Past 65,504 the format has no finite
+ * value, and a partial sum can pass that on its way to a total that does not — so this bounds each
+ * neuron by its bias plus the sum of every weight times the largest magnitude its input can take,
+ * which covers every prefix of the sum at once. Intervals are carried through the layers, and a
+ * rectifier clips them, which is what keeps the bound from growing without cause.
+ */
+export function activationBound(shape, weights, low, high) {
+    let lower = Array.from({ length: shape.inputs }, (_, i) => low[i]);
+    let upper = Array.from({ length: shape.inputs }, (_, i) => high[i]);
+    let bound = 0;
+    for (let i = 0; i < shape.inputs; i += 1) {
+        bound = Math.max(bound, Math.abs(lower[i]), Math.abs(upper[i]));
+    }
+    let at = 0;
+    let previous = shape.inputs;
+    const layers = shape.hidden.length + 1;
+    for (let layer = 0; layer < layers; layer += 1) {
+        const width = layer < shape.hidden.length ? shape.hidden[layer] : shape.outputs;
+        const hidden = layer < shape.hidden.length;
+        const nextLower = [];
+        const nextUpper = [];
+        for (let o = 0; o < width; o += 1) {
+            const bias = weights[at + width * previous + o];
+            let magnitude = Math.abs(bias);
+            let min = bias;
+            let max = bias;
+            for (let i = 0; i < previous; i += 1) {
+                const weight = weights[at + o * previous + i];
+                const a = weight * lower[i];
+                const b = weight * upper[i];
+                min += Math.min(a, b);
+                max += Math.max(a, b);
+                magnitude += Math.max(Math.abs(a), Math.abs(b));
+            }
+            bound = Math.max(bound, magnitude);
+            nextLower.push(hidden ? Math.max(0, min) : min);
+            nextUpper.push(hidden ? Math.max(0, max) : max);
+        }
+        at += previous * width + width;
+        previous = width;
+        lower = nextLower;
+        upper = nextUpper;
+    }
+    return bound;
+}

package/dist/materialArray.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Materials as slices of a few texture arrays, which is what WebGPU can bind.
+ *
+ * **This is the binding design, and it is why this package lands in the same wave as the
+ * GPU-driven pipeline rather than later.** WebGPU has no bindless resource access, which is the
+ * usual way a GPU-driven renderer reaches a thousand materials from one indirect draw. A thousand
+ * materials as six thousand independent textures is unreachable. A thousand materials as a
+ * thousand latent slices in a handful of arrays, indexed by a material identifier read from a
+ * storage buffer, is ordinary.
+ *
+ * **Identical content shares a layer.** The tile index already hashes by content, so two materials
+ * whose latents are the same occupy one layer — which is the deduplication paying for itself a
+ * second time, in binding slots rather than in bytes.
+ */
+export interface MaterialArray {
+    /** Layer per material identifier. */
+    layerOf: Map<number, number>;
+    /** Which content hash each layer holds, so identical latents share one. */
+    layerByHash: Map<string, number>;
+    layerCapacity: number;
+    tileSize: number;
+    used: number;
+}
+export declare function createMaterialArray(layerCapacity: number, tileSize: number): MaterialArray;
+/**
+ * Give this material a layer. Returns it, or -1 when the array is full.
+ *
+ * **Full reports failure rather than evicting.** An eviction here would silently repoint a
+ * material that is still being drawn, which is a texture swap nobody asked for in the middle of a
+ * frame; a caller that runs out needs to know.
+ */
+export declare function assignLayer(array: MaterialArray, materialId: number, contentHash: string): number;
+export declare function layerOf(array: MaterialArray, materialId: number): number;
+/** What a bind group needs to know: how many layers and how large each is. */
+export declare function arrayDescriptor(array: MaterialArray): {
+    layers: number;
+    size: number;
+};

package/dist/materialArray.js

@@ -0,0 +1,40 @@
+export function createMaterialArray(layerCapacity, tileSize) {
+    return {
+        layerOf: new Map(),
+        layerByHash: new Map(),
+        layerCapacity,
+        tileSize,
+        used: 0,
+    };
+}
+/**
+ * Give this material a layer. Returns it, or -1 when the array is full.
+ *
+ * **Full reports failure rather than evicting.** An eviction here would silently repoint a
+ * material that is still being drawn, which is a texture swap nobody asked for in the middle of a
+ * frame; a caller that runs out needs to know.
+ */
+export function assignLayer(array, materialId, contentHash) {
+    const existing = array.layerOf.get(materialId);
+    if (existing !== undefined)
+        return existing;
+    const shared = array.layerByHash.get(contentHash);
+    if (shared !== undefined) {
+        array.layerOf.set(materialId, shared);
+        return shared;
+    }
+    if (array.used >= array.layerCapacity)
+        return -1;
+    const layer = array.used;
+    array.used += 1;
+    array.layerByHash.set(contentHash, layer);
+    array.layerOf.set(materialId, layer);
+    return layer;
+}
+export function layerOf(array, materialId) {
+    return array.layerOf.get(materialId) ?? -1;
+}
+/** What a bind group needs to know: how many layers and how large each is. */
+export function arrayDescriptor(array) {
+    return { layers: array.used, size: array.tileSize };
+}

package/dist/mipNdf.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Mip levels for a normal map that get rougher instead of sparkling.
+ *
+ * **Averaging four normals and renormalising throws away how much they disagreed — and that
+ * disagreement *is* roughness at the smaller scale.** What comes back is a distant surface whose
+ * highlight flickers as the camera moves, which reads as an aliasing problem in the renderer and
+ * is a mip chain problem in the asset.
+ *
+ * Every engine can do this and almost none does it by default, because it needs the mip chain to
+ * write roughness as well as normals — which needs the two to live in one object. In a
+ * DriftTexture they do, which is why this is the default here rather than an option.
+ *
+ * **The reduction adds variance and never removes it.** A surface already rough at the finer level
+ * cannot become smoother by being viewed from further away.
+ */
+/**
+ * How much roughness a shortened average normal implies.
+ *
+ * The averaged normal's length falls as the normals it averaged disagree, so `1 - length` is a
+ * direct measure of the variance lost to averaging. Added in variance rather than in roughness,
+ * because variances of independent sources add and roughnesses do not.
+ */
+export declare function toksvigRoughness(normalLength: number, roughness: number): number;
+/**
+ * Reduce a block of normals to one, writing both the direction and the roughness it implies.
+ *
+ * `src` holds `width * height` normals as xyz triples, already unbiased into -1..1.
+ */
+export declare function reduceNormalMip(src: Float32Array, width: number, height: number, outNormal: Float32Array, outRoughness: Float32Array, baseRoughness?: number): void;

package/dist/mipNdf.js

@@ -0,0 +1,53 @@
+/**
+ * Mip levels for a normal map that get rougher instead of sparkling.
+ *
+ * **Averaging four normals and renormalising throws away how much they disagreed — and that
+ * disagreement *is* roughness at the smaller scale.** What comes back is a distant surface whose
+ * highlight flickers as the camera moves, which reads as an aliasing problem in the renderer and
+ * is a mip chain problem in the asset.
+ *
+ * Every engine can do this and almost none does it by default, because it needs the mip chain to
+ * write roughness as well as normals — which needs the two to live in one object. In a
+ * DriftTexture they do, which is why this is the default here rather than an option.
+ *
+ * **The reduction adds variance and never removes it.** A surface already rough at the finer level
+ * cannot become smoother by being viewed from further away.
+ */
+/**
+ * How much roughness a shortened average normal implies.
+ *
+ * The averaged normal's length falls as the normals it averaged disagree, so `1 - length` is a
+ * direct measure of the variance lost to averaging. Added in variance rather than in roughness,
+ * because variances of independent sources add and roughnesses do not.
+ */
+export function toksvigRoughness(normalLength, roughness) {
+    const length = Math.min(1, Math.max(0, normalLength));
+    const added = 1 - length;
+    return Math.sqrt(Math.min(1, roughness * roughness + added));
+}
+/**
+ * Reduce a block of normals to one, writing both the direction and the roughness it implies.
+ *
+ * `src` holds `width * height` normals as xyz triples, already unbiased into -1..1.
+ */
+export function reduceNormalMip(src, width, height, outNormal, outRoughness, baseRoughness = 0) {
+    let x = 0;
+    let y = 0;
+    let z = 0;
+    const count = width * height;
+    for (let i = 0; i < count; i += 1) {
+        x += src[i * 3];
+        y += src[i * 3 + 1];
+        z += src[i * 3 + 2];
+    }
+    x /= count;
+    y /= count;
+    z /= count;
+    /* The length before normalising is the whole signal. Normalising first discards it. */
+    const length = Math.hypot(x, y, z);
+    const k = length > 0 ? 1 / length : 0;
+    outNormal[0] = x * k;
+    outNormal[1] = y * k;
+    outNormal[2] = z * k;
+    outRoughness[0] = toksvigRoughness(length, baseRoughness);
+}

package/dist/overlay/journal.d.ts

@@ -0,0 +1,78 @@
+/**
+ * A scorch mark is in the input log, so a replay burns the same wall.
+ *
+ * **Runtime-mutable textures normally break replay.** The marks are not part of the simulation and
+ * nothing records them, so a recording plays back a world where the walls are clean — and the
+ * failure has the worst possible shape: nothing goes wrong at the time, everything looks right, and
+ * the recording is wrong forever. Anybody who later debugs from it is debugging a session that did
+ * not happen.
+ *
+ * Here a write is recorded in the same log the input goes into, so replaying a session reproduces
+ * the exact mark in the exact place — and the same mechanism means a rollback un-draws what the
+ * rolled-back frames drew, because rolling back an overlay *is* rebuilding it from the journal up
+ * to the frame you rolled back to. An overlay cannot be snapshotted the way the world is: it is
+ * sparse and unbounded, and a snapshot per frame of something that grows is the cost the sparseness
+ * was for.
+ *
+ * **Applying does not clear, and rewinding does.** A replay that always cleared could not be used
+ * to catch up frame by frame, which is what a live session does. `rewindOverlay` is the one that
+ * puts the world back, and it says so in its name.
+ *
+ * **The journal is truncated on rollback, and forgetting that is the bug.** Re-simulating after a
+ * rollback records its writes again; the frames that did not happen must not still be in the log,
+ * or a replay from the start draws both the mark that happened and the one that was undone.
+ */
+import { type Overlay } from './sparse.ts';
+/** Bytes an entry takes on the wire: two `u32` and four `f32`. */
+export declare const JOURNAL_ENTRY_BYTES = 24;
+/** `"DOVJ"`, little-endian, as every other record in this package spells its magic. */
+export declare const JOURNAL_MAGIC = 1247170372;
+export declare const JOURNAL_VERSION = 1;
+export interface OverlayJournal {
+    /** One frame number an entry. */
+    frames: Int32Array;
+    /** One channel index an entry. */
+    channels: Int32Array;
+    /** Four values an entry: u, v, radius, value. */
+    values: Float32Array;
+    count: number;
+}
+export declare function createOverlayJournal(capacity?: number): OverlayJournal;
+/**
+ * Record a write. Stored as `f32`, which is what makes the encoding round-trip exactly.
+ *
+ * A journal of `f64` written out as `f32` reproduces a *nearly* identical mark, and "nearly" in a
+ * replay is a divergence that appears at the worst moment — the fingerprint that no longer matches
+ * a recording, for a reason nobody would look for in a texture.
+ */
+export declare function recordOverlayWrite(journal: OverlayJournal, frame: number, u: number, v: number, radius: number, channel: number, value: number): void;
+export declare function journalLength(journal: OverlayJournal): number;
+/**
+ * Forget every entry from `frame` onward. What a rollback owes the journal.
+ *
+ * Entries are recorded in frame order, so this is a truncation rather than a filter — and where
+ * they are not, the scan below still removes exactly the right ones.
+ */
+export declare function truncateJournalFrom(journal: OverlayJournal, frame: number): number;
+/** Apply every entry up to and including `upToFrame`, onto whatever the overlay already holds. */
+export declare function applyOverlayJournal(overlay: Overlay, journal: OverlayJournal, upToFrame: number): number;
+/** Throw away every written tile. The overlay keeps its shape and holds nothing. */
+export declare function clearOverlay(overlay: Overlay): void;
+/**
+ * Put the overlay back to how it was at `upToFrame`: clear, then replay.
+ *
+ * Rebuilt rather than undone, because a write is not invertible — two marks on one texel leave no
+ * record of what was underneath, and an overlay that tried to undo would need a history per texel,
+ * which is the dense layer the whole design exists to avoid.
+ */
+export declare function rewindOverlay(overlay: Overlay, journal: OverlayJournal, upToFrame: number): number;
+/** An overlay with the same shape as `like` and nothing written. What a replay starts from. */
+export declare function emptyLike(like: Overlay): Overlay;
+export declare function encodeOverlayJournal(journal: OverlayJournal): Uint8Array;
+/**
+ * Read a journal back. Null where the bytes are not one.
+ *
+ * Null rather than a partial journal: a replay against half a log is a session that diverges partway
+ * through for no visible reason, which is worse than one that refuses to start.
+ */
+export declare function decodeOverlayJournal(bytes: Uint8Array): OverlayJournal | null;

package/dist/overlay/journal.js

@@ -0,0 +1,171 @@
+/**
+ * A scorch mark is in the input log, so a replay burns the same wall.
+ *
+ * **Runtime-mutable textures normally break replay.** The marks are not part of the simulation and
+ * nothing records them, so a recording plays back a world where the walls are clean — and the
+ * failure has the worst possible shape: nothing goes wrong at the time, everything looks right, and
+ * the recording is wrong forever. Anybody who later debugs from it is debugging a session that did
+ * not happen.
+ *
+ * Here a write is recorded in the same log the input goes into, so replaying a session reproduces
+ * the exact mark in the exact place — and the same mechanism means a rollback un-draws what the
+ * rolled-back frames drew, because rolling back an overlay *is* rebuilding it from the journal up
+ * to the frame you rolled back to. An overlay cannot be snapshotted the way the world is: it is
+ * sparse and unbounded, and a snapshot per frame of something that grows is the cost the sparseness
+ * was for.
+ *
+ * **Applying does not clear, and rewinding does.** A replay that always cleared could not be used
+ * to catch up frame by frame, which is what a live session does. `rewindOverlay` is the one that
+ * puts the world back, and it says so in its name.
+ *
+ * **The journal is truncated on rollback, and forgetting that is the bug.** Re-simulating after a
+ * rollback records its writes again; the frames that did not happen must not still be in the log,
+ * or a replay from the start draws both the mark that happened and the one that was undone.
+ */
+import { createOverlay, writeOverlay } from './sparse.js';
+/** Bytes an entry takes on the wire: two `u32` and four `f32`. */
+export const JOURNAL_ENTRY_BYTES = 24;
+/** `"DOVJ"`, little-endian, as every other record in this package spells its magic. */
+export const JOURNAL_MAGIC = 0x4a564f44;
+export const JOURNAL_VERSION = 1;
+export function createOverlayJournal(capacity = 256) {
+    const size = Math.max(1, Math.floor(capacity));
+    return {
+        frames: new Int32Array(size),
+        channels: new Int32Array(size),
+        values: new Float32Array(size * 4),
+        count: 0,
+    };
+}
+function grow(journal) {
+    if (journal.count < journal.frames.length)
+        return;
+    const size = journal.frames.length * 2;
+    const frames = new Int32Array(size);
+    const channels = new Int32Array(size);
+    const values = new Float32Array(size * 4);
+    frames.set(journal.frames);
+    channels.set(journal.channels);
+    values.set(journal.values);
+    journal.frames = frames;
+    journal.channels = channels;
+    journal.values = values;
+}
+/**
+ * Record a write. Stored as `f32`, which is what makes the encoding round-trip exactly.
+ *
+ * A journal of `f64` written out as `f32` reproduces a *nearly* identical mark, and "nearly" in a
+ * replay is a divergence that appears at the worst moment — the fingerprint that no longer matches
+ * a recording, for a reason nobody would look for in a texture.
+ */
+export function recordOverlayWrite(journal, frame, u, v, radius, channel, value) {
+    grow(journal);
+    const at = journal.count;
+    journal.frames[at] = frame;
+    journal.channels[at] = channel;
+    journal.values[at * 4] = u;
+    journal.values[at * 4 + 1] = v;
+    journal.values[at * 4 + 2] = radius;
+    journal.values[at * 4 + 3] = value;
+    journal.count += 1;
+}
+export function journalLength(journal) {
+    return journal.count;
+}
+/**
+ * Forget every entry from `frame` onward. What a rollback owes the journal.
+ *
+ * Entries are recorded in frame order, so this is a truncation rather than a filter — and where
+ * they are not, the scan below still removes exactly the right ones.
+ */
+export function truncateJournalFrom(journal, frame) {
+    let kept = 0;
+    for (let at = 0; at < journal.count; at += 1) {
+        if (journal.frames[at] >= frame)
+            continue;
+        if (kept !== at) {
+            journal.frames[kept] = journal.frames[at];
+            journal.channels[kept] = journal.channels[at];
+            for (let c = 0; c < 4; c += 1) {
+                journal.values[kept * 4 + c] = journal.values[at * 4 + c];
+            }
+        }
+        kept += 1;
+    }
+    const dropped = journal.count - kept;
+    journal.count = kept;
+    return dropped;
+}
+/** Apply every entry up to and including `upToFrame`, onto whatever the overlay already holds. */
+export function applyOverlayJournal(overlay, journal, upToFrame) {
+    let applied = 0;
+    for (let at = 0; at < journal.count; at += 1) {
+        if (journal.frames[at] > upToFrame)
+            continue;
+        writeOverlay(overlay, journal.values[at * 4], journal.values[at * 4 + 1], journal.values[at * 4 + 2], journal.channels[at], journal.values[at * 4 + 3]);
+        applied += 1;
+    }
+    return applied;
+}
+/** Throw away every written tile. The overlay keeps its shape and holds nothing. */
+export function clearOverlay(overlay) {
+    overlay.tiles.clear();
+}
+/**
+ * Put the overlay back to how it was at `upToFrame`: clear, then replay.
+ *
+ * Rebuilt rather than undone, because a write is not invertible — two marks on one texel leave no
+ * record of what was underneath, and an overlay that tried to undo would need a history per texel,
+ * which is the dense layer the whole design exists to avoid.
+ */
+export function rewindOverlay(overlay, journal, upToFrame) {
+    clearOverlay(overlay);
+    return applyOverlayJournal(overlay, journal, upToFrame);
+}
+/** An overlay with the same shape as `like` and nothing written. What a replay starts from. */
+export function emptyLike(like) {
+    return createOverlay(like.tileSize, {
+        tilesAcross: like.tilesAcross,
+        addressMode: like.addressMode,
+    });
+}
+export function encodeOverlayJournal(journal) {
+    const bytes = new Uint8Array(12 + journal.count * JOURNAL_ENTRY_BYTES);
+    const view = new DataView(bytes.buffer);
+    view.setUint32(0, JOURNAL_MAGIC, true);
+    view.setUint32(4, JOURNAL_VERSION, true);
+    view.setUint32(8, journal.count, true);
+    for (let at = 0; at < journal.count; at += 1) {
+        const base = 12 + at * JOURNAL_ENTRY_BYTES;
+        view.setInt32(base, journal.frames[at], true);
+        view.setInt32(base + 4, journal.channels[at], true);
+        for (let c = 0; c < 4; c += 1) {
+            view.setFloat32(base + 8 + c * 4, journal.values[at * 4 + c], true);
+        }
+    }
+    return bytes;
+}
+/**
+ * Read a journal back. Null where the bytes are not one.
+ *
+ * Null rather than a partial journal: a replay against half a log is a session that diverges partway
+ * through for no visible reason, which is worse than one that refuses to start.
+ */
+export function decodeOverlayJournal(bytes) {
+    if (bytes.byteLength < 12)
+        return null;
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(0, true) !== JOURNAL_MAGIC)
+        return null;
+    if (view.getUint32(4, true) !== JOURNAL_VERSION)
+        return null;
+    const count = view.getUint32(8, true);
+    if (bytes.byteLength !== 12 + count * JOURNAL_ENTRY_BYTES)
+        return null;
+    const journal = createOverlayJournal(Math.max(1, count));
+    for (let at = 0; at < count; at += 1) {
+        const base = 12 + at * JOURNAL_ENTRY_BYTES;
+        recordOverlayWrite(journal, view.getInt32(base, true), view.getFloat32(base + 8, true), view.getFloat32(base + 12, true), view.getFloat32(base + 16, true), view.getInt32(base + 4, true), view.getFloat32(base + 20, true));
+    }
+    return journal;
+}