@driftengine/core 3.63.0 → 4.1.0

package/dist/render/shaders/network.wgsl.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The one network evaluator the device has, in single or half precision.
+ *
+ * **Every network the engine evaluates on a device goes through this text.** A DriftTexture's
+ * decode interpreter reads its networks from uniform tables; reconstruction's refinement tier and
+ * capture's priors read theirs from storage buffers, in half precision where the device has it.
+ * Those are different bindings and the same arithmetic, so the arithmetic is written once and the
+ * weights are reached through a function the including module defines — the arrangement
+ * `shadow.wgsl.ts` uses for its map. A second evaluator would be a second set of numerical
+ * conventions to keep in step, which `@driftengine/texture`'s `inference.ts` names as the thing this
+ * engine refuses.
+ *
+ * **The reference is `evalNetwork`, and in half precision `evalNetworkHalf`**, operation for
+ * operation: the weighted inputs summed in index order, then the bias, then the rectifier on hidden
+ * layers and nothing on the output. The weights are laid out as `NNET` stores them — each layer's
+ * matrix row by row by output, then its biases.
+ *
+ * **Half precision needs `enable f16;` at the top of the including module** and a device created
+ * with `shader-f16`. It is chosen per network by its consumer, and `activationBound` is what that
+ * consumer asks first: past 65,504 the format has no finite value.
+ *
+ * `scripts/gpu-parity.mjs` runs both instantiations against the references, and
+ * `scripts/wgsl-handwritten.test.mjs` has `naga` validate them without a device.
+ */
+export interface NetworkWgslOptions {
+    /** The prefix every function this defines carries, so a module can include more than one. */
+    readonly name: string;
+    /** The scalar the network computes in. `f16` needs `enable f16;` in the including module. */
+    readonly scalar: 'f32' | 'f16';
+    /** The widest layer, which is the length of the function-scope arrays the layers pass through. */
+    readonly width: number;
+    /** The most hidden layers a network may have here. */
+    readonly hidden: number;
+}
+/**
+ * The evaluator, as text.
+ *
+ * Defines `fn <name>Eval(first, inputs, hidden, widths, outputs, input) -> array<S, width>`:
+ * `first` is where the network's weights start, `widths` its hidden widths, and `input` its first
+ * `inputs` values. The including module defines `fn <name>Weight(index: u32) -> S`.
+ *
+ * **Every count is clamped to what the arrays hold.** A loader refuses a network wider or deeper
+ * than this was instantiated for; the clamps are what keep a malformed one from indexing past a
+ * function-scope array, which the language would otherwise clamp silently and differently.
+ */
+export declare function networkWgsl(options: NetworkWgslOptions): string;
+/** A network's shape, which the fixed form bakes in. The same shape `evalNetwork` takes. */
+export interface FixedNetworkShape {
+    readonly inputs: number;
+    readonly hidden: readonly number[];
+    readonly outputs: number;
+}
+export interface FixedNetworkWgslOptions {
+    /** The prefix every function this defines carries, as for the variable form. */
+    readonly name: string;
+    readonly scalar: 'f32' | 'f16';
+    readonly shape: FixedNetworkShape;
+    /** Where the network's weights start in what `<name>Weight` reads. */
+    readonly first?: number;
+}
+/**
+ * The same evaluator with its shape fixed when the pipeline is built, for a consumer whose network
+ * is known then — reconstruction's refinement tier, capture's priors.
+ *
+ * **Nine to fourteen times faster, measured**, 2026-09-19 on an RX 9070 XT, once per pixel of a
+ * 1280×720 frame: a network of 11-8-3 in 0.031 ms against the variable form's 0.286, and 11-16-16-3
+ * in 0.076 against 1.09 (`tools/recon-train/budget.ts`). The variable form indexes function-scope
+ * arrays with counts it reads at run time, which a compiler cannot keep in registers; with every
+ * count a constant the loops unroll and the arrays are registers. The DriftTexture interpreter keeps
+ * the variable form, because its networks change per material and its pipeline does not.
+ *
+ * **The arithmetic is the variable form's, in the same order** — the weighted inputs summed in index
+ * order, then the bias, then the rectifier on hidden layers and nothing on the output, over weights
+ * laid out as `NNET` stores them — so `evalNetwork` and `evalNetworkHalf` are its references too,
+ * and `gpu-parity.mjs` holds it to them the same way.
+ *
+ * Defines `fn <name>Eval(input: array<S, inputs>) -> array<S, outputs>`. The including module
+ * defines `fn <name>Weight(index: u32) -> S`, as for the variable form.
+ */
+export declare function networkFixedWgsl(options: FixedNetworkWgslOptions): string;
+/**
+ * An entry point that evaluates one fixed-shape network over many inputs, so a harness can hold
+ * the fixed form to `evalNetwork` and `evalNetworkHalf` as it holds the variable one. Inputs and
+ * outputs cross as `f32`, as the variable form's parity entry point has them.
+ */
+export declare function networkFixedParityWgsl(scalar: 'f32' | 'f16', shape: FixedNetworkShape): string;
+/** The widest network the parity entry points evaluate. */
+export declare const NETWORK_PARITY_WIDTH = 16;
+/** The deepest. */
+export declare const NETWORK_PARITY_HIDDEN = 4;
+/** Unsigned words per case: first, inputs, hidden count, outputs, then the hidden widths. */
+export declare const NETWORK_CASE_WORDS: number;
+/**
+ * An entry point that evaluates one network per invocation from storage buffers, so a harness can
+ * compare the device with `evalNetwork` or `evalNetworkHalf`.
+ *
+ * Inputs and outputs cross as `f32` whatever the network computes in: a half-precision network's
+ * inputs are converted on the way in, as `evalNetworkHalf` rounds them, and its outputs widen on
+ * the way out, which loses nothing.
+ */
+export declare function networkParityWgsl(scalar: 'f32' | 'f16'): string;

package/dist/render/shaders/network.wgsl.js

@@ -0,0 +1,206 @@
+/**
+ * The one network evaluator the device has, in single or half precision.
+ *
+ * **Every network the engine evaluates on a device goes through this text.** A DriftTexture's
+ * decode interpreter reads its networks from uniform tables; reconstruction's refinement tier and
+ * capture's priors read theirs from storage buffers, in half precision where the device has it.
+ * Those are different bindings and the same arithmetic, so the arithmetic is written once and the
+ * weights are reached through a function the including module defines — the arrangement
+ * `shadow.wgsl.ts` uses for its map. A second evaluator would be a second set of numerical
+ * conventions to keep in step, which `@driftengine/texture`'s `inference.ts` names as the thing this
+ * engine refuses.
+ *
+ * **The reference is `evalNetwork`, and in half precision `evalNetworkHalf`**, operation for
+ * operation: the weighted inputs summed in index order, then the bias, then the rectifier on hidden
+ * layers and nothing on the output. The weights are laid out as `NNET` stores them — each layer's
+ * matrix row by row by output, then its biases.
+ *
+ * **Half precision needs `enable f16;` at the top of the including module** and a device created
+ * with `shader-f16`. It is chosen per network by its consumer, and `activationBound` is what that
+ * consumer asks first: past 65,504 the format has no finite value.
+ *
+ * `scripts/gpu-parity.mjs` runs both instantiations against the references, and
+ * `scripts/wgsl-handwritten.test.mjs` has `naga` validate them without a device.
+ */
+/**
+ * The evaluator, as text.
+ *
+ * Defines `fn <name>Eval(first, inputs, hidden, widths, outputs, input) -> array<S, width>`:
+ * `first` is where the network's weights start, `widths` its hidden widths, and `input` its first
+ * `inputs` values. The including module defines `fn <name>Weight(index: u32) -> S`.
+ *
+ * **Every count is clamped to what the arrays hold.** A loader refuses a network wider or deeper
+ * than this was instantiated for; the clamps are what keep a malformed one from indexing past a
+ * function-scope array, which the language would otherwise clamp silently and differently.
+ */
+export function networkWgsl(options) {
+    const { name, scalar: s, width: w, hidden: h } = options;
+    return /* wgsl */ `
+fn ${name}Eval(
+  first: u32,
+  inputs: u32,
+  hidden: u32,
+  widths: array<u32, ${h}>,
+  outputs: u32,
+  input: array<${s}, ${w}>,
+) -> array<${s}, ${w}> {
+  var current = input;
+  var next: array<${s}, ${w}>;
+  var at = first;
+  var previous = min(inputs, ${w}u);
+  let layers = min(hidden, ${h}u);
+  for (var layer = 0u; layer < layers; layer = layer + 1u) {
+    let width = min(widths[layer], ${w}u);
+    for (var o = 0u; o < width; o = o + 1u) {
+      var total = ${s}(0.0);
+      for (var i = 0u; i < previous; i = i + 1u) {
+        total = total + current[i] * ${name}Weight(at + o * previous + i);
+      }
+      /* Rectified linear on hidden layers and nothing on the output, as inference.ts insists. */
+      next[o] = max(total + ${name}Weight(at + width * previous + o), ${s}(0.0));
+    }
+    at = at + previous * width + width;
+    previous = width;
+    current = next;
+  }
+  var result: array<${s}, ${w}>;
+  let count = min(outputs, ${w}u);
+  for (var o = 0u; o < count; o = o + 1u) {
+    var total = ${s}(0.0);
+    for (var i = 0u; i < previous; i = i + 1u) {
+      total = total + current[i] * ${name}Weight(at + o * previous + i);
+    }
+    result[o] = total + ${name}Weight(at + count * previous + o);
+  }
+  return result;
+}
+`;
+}
+/**
+ * The same evaluator with its shape fixed when the pipeline is built, for a consumer whose network
+ * is known then — reconstruction's refinement tier, capture's priors.
+ *
+ * **Nine to fourteen times faster, measured**, 2026-09-19 on an RX 9070 XT, once per pixel of a
+ * 1280×720 frame: a network of 11-8-3 in 0.031 ms against the variable form's 0.286, and 11-16-16-3
+ * in 0.076 against 1.09 (`tools/recon-train/budget.ts`). The variable form indexes function-scope
+ * arrays with counts it reads at run time, which a compiler cannot keep in registers; with every
+ * count a constant the loops unroll and the arrays are registers. The DriftTexture interpreter keeps
+ * the variable form, because its networks change per material and its pipeline does not.
+ *
+ * **The arithmetic is the variable form's, in the same order** — the weighted inputs summed in index
+ * order, then the bias, then the rectifier on hidden layers and nothing on the output, over weights
+ * laid out as `NNET` stores them — so `evalNetwork` and `evalNetworkHalf` are its references too,
+ * and `gpu-parity.mjs` holds it to them the same way.
+ *
+ * Defines `fn <name>Eval(input: array<S, inputs>) -> array<S, outputs>`. The including module
+ * defines `fn <name>Weight(index: u32) -> S`, as for the variable form.
+ */
+export function networkFixedWgsl(options) {
+    const { name, scalar: s, shape } = options;
+    const layers = [shape.inputs, ...shape.hidden, shape.outputs];
+    let at = options.first ?? 0;
+    let body = '';
+    let previous = 'input';
+    for (let layer = 1; layer < layers.length; layer += 1) {
+        const width = layers[layer];
+        const fanIn = layers[layer - 1];
+        const output = layer === layers.length - 1;
+        const target = output ? 'result' : `layer${layer}`;
+        const bias = at + width * fanIn;
+        const value = output
+            ? `total + ${name}Weight(${bias}u + o)`
+            : `max(total + ${name}Weight(${bias}u + o), ${s}(0.0))`;
+        body += `
+  var ${target}: array<${s}, ${width}>;
+  for (var o = 0u; o < ${width}u; o = o + 1u) {
+    var total = ${s}(0.0);
+    for (var i = 0u; i < ${fanIn}u; i = i + 1u) {
+      total = total + ${previous}[i] * ${name}Weight(${at}u + o * ${fanIn}u + i);
+    }
+    ${target}[o] = ${value};
+  }`;
+        at = bias + width;
+        previous = target;
+    }
+    return /* wgsl */ `
+fn ${name}Eval(input: array<${s}, ${shape.inputs}>) -> array<${s}, ${shape.outputs}> {${body}
+  return result;
+}
+`;
+}
+/**
+ * An entry point that evaluates one fixed-shape network over many inputs, so a harness can hold
+ * the fixed form to `evalNetwork` and `evalNetworkHalf` as it holds the variable one. Inputs and
+ * outputs cross as `f32`, as the variable form's parity entry point has them.
+ */
+export function networkFixedParityWgsl(scalar, shape) {
+    return /* wgsl */ `${scalar === 'f16' ? 'enable f16;\n' : ''}
+@group(0) @binding(0) var<storage, read> weights: array<${scalar}>;
+@group(0) @binding(1) var<storage, read> inputs: array<f32>;
+@group(0) @binding(2) var<storage, read_write> outputs: array<f32>;
+
+fn parityWeight(index: u32) -> ${scalar} {
+  return weights[index];
+}
+${networkFixedWgsl({ name: 'parity', scalar, shape })}
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  let count = arrayLength(&inputs) / ${shape.inputs}u;
+  if (id.x >= count) { return; }
+  var input: array<${scalar}, ${shape.inputs}>;
+  for (var i = 0u; i < ${shape.inputs}u; i = i + 1u) {
+    input[i] = ${scalar}(inputs[id.x * ${shape.inputs}u + i]);
+  }
+  let result = parityEval(input);
+  for (var o = 0u; o < ${shape.outputs}u; o = o + 1u) {
+    outputs[id.x * ${shape.outputs}u + o] = f32(result[o]);
+  }
+}
+`;
+}
+/** The widest network the parity entry points evaluate. */
+export const NETWORK_PARITY_WIDTH = 16;
+/** The deepest. */
+export const NETWORK_PARITY_HIDDEN = 4;
+/** Unsigned words per case: first, inputs, hidden count, outputs, then the hidden widths. */
+export const NETWORK_CASE_WORDS = 4 + NETWORK_PARITY_HIDDEN;
+/**
+ * An entry point that evaluates one network per invocation from storage buffers, so a harness can
+ * compare the device with `evalNetwork` or `evalNetworkHalf`.
+ *
+ * Inputs and outputs cross as `f32` whatever the network computes in: a half-precision network's
+ * inputs are converted on the way in, as `evalNetworkHalf` rounds them, and its outputs widen on
+ * the way out, which loses nothing.
+ */
+export function networkParityWgsl(scalar) {
+    const w = NETWORK_PARITY_WIDTH;
+    return /* wgsl */ `${scalar === 'f16' ? 'enable f16;\n' : ''}
+@group(0) @binding(0) var<storage, read> cases: array<u32>;
+@group(0) @binding(1) var<storage, read> weights: array<${scalar}>;
+@group(0) @binding(2) var<storage, read> inputs: array<f32>;
+@group(0) @binding(3) var<storage, read_write> outputs: array<f32>;
+
+fn parityWeight(index: u32) -> ${scalar} {
+  return weights[index];
+}
+${networkWgsl({ name: 'parity', scalar, width: w, hidden: NETWORK_PARITY_HIDDEN })}
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  let count = arrayLength(&cases) / ${NETWORK_CASE_WORDS}u;
+  if (id.x >= count) { return; }
+  let at = id.x * ${NETWORK_CASE_WORDS}u;
+  var widths: array<u32, ${NETWORK_PARITY_HIDDEN}>;
+  for (var layer = 0u; layer < ${NETWORK_PARITY_HIDDEN}u; layer = layer + 1u) {
+    widths[layer] = cases[at + 4u + layer];
+  }
+  var input: array<${scalar}, ${w}>;
+  for (var i = 0u; i < ${w}u; i = i + 1u) {
+    input[i] = ${scalar}(inputs[id.x * ${w}u + i]);
+  }
+  let result = parityEval(cases[at], cases[at + 1u], cases[at + 2u], widths, cases[at + 3u], input);
+  for (var o = 0u; o < ${w}u; o = o + 1u) {
+    outputs[id.x * ${w}u + o] = f32(result[o]);
+  }
+}
+`;
+}

package/dist/render/shaders/recon/motion.wgsl.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Where a drawn surface was last frame, written into the reconstruction's motion target.
+ *
+ * **A pass of its own rather than a second output on every material.** The alternative is a second
+ * colour attachment on every generated fragment stage, which `ARCHITECTURE.md` §1 prices at 196,910
+ * gzipped bytes for one flag — and it would be paid by every consumer, including the ones who never
+ * reconstruct anything. This draws only the meshes a caller said had moved, with one small shader
+ * over the position buffer alone.
+ *
+ * **What a pixel carries**: the offset from where it is now to where its surface was, in the uv the
+ * resolve measures in; the view depth it had then, which is what the disocclusion compares against
+ * last frame's depth; and a flag. `recon/resolve.ts`'s `historyWeight` is the reader, and a texel
+ * this pass did not write is a zero flag, which means *derive the camera's motion from the depth* —
+ * so a scene that says nothing about its movers is exactly the scene this pass never ran for.
+ *
+ * **The rasterisation matrix is handed over whole, and that is deliberate.** The scene is drawn by
+ * shaders `naga` generated, every one of which ends its vertex stage with `gl_Position.y = -y`, and
+ * `CLIP_CORRECTION` carries a negation to cancel it — §3 rows 56 and 57. This shader is hand
+ * written and has no such negation, so rather than reason about halves of that pair per draw, the
+ * renderer multiplies the two together once a frame and passes the product. The vertex stage then
+ * has one job: put the position exactly where the scene put it, so the depth test compares like
+ * with like.
+ *
+ * **The motion itself is measured from the *unjittered* matrices**, which is the whole of §3 row
+ * 121: the history stands for a picture of the scene as it would have been drawn with no jitter, so
+ * a motion vector that carried the jitter difference would move every sample by a fraction of a
+ * pixel in a pattern that repeats with the jitter period — shimmer, diagnosed as anything but its
+ * cause.
+ */
+/** Floats in the per-frame block: three matrices. */
+export declare const MOTION_FRAME_FLOATS = 48;
+/**
+ * Bytes a draw's own block takes.
+ *
+ * Two matrices is 128, and a dynamic uniform offset must be a multiple of 256 — the same alignment
+ * §3 row 50's neighbours are about. So each draw takes a whole 256 and half of it is padding, which
+ * is the cheaper half of the trade against a bind group per draw inside the frame loop.
+ */
+export declare const MOTION_DRAW_STRIDE = 256;
+/** Floats a draw actually writes inside that stride. */
+export declare const MOTION_DRAW_FLOATS = 32;
+/** The motion target's format. Half float holds a uv to a hundredth of a pixel and a view depth. */
+export declare const MOTION_TARGET_FORMAT: GPUTextureFormat;
+export declare const RECON_MOTION_WGSL = "\nstruct MotionFrame {\n  /* The scene's own clip transform, with the generated shaders' y negation already folded in. */\n  raster: mat4x4<f32>,\n  /* This frame's and last frame's view-projections, unjittered, in the matrices' own convention. */\n  viewProj: mat4x4<f32>,\n  previousViewProj: mat4x4<f32>,\n}\n\nstruct MotionDraw {\n  model: mat4x4<f32>,\n  previousModel: mat4x4<f32>,\n}\n\n@group(0) @binding(0) var<uniform> frame: MotionFrame;\n@group(0) @binding(1) var<uniform> draw: MotionDraw;\n\nstruct Varyings {\n  @builtin(position) clip: vec4<f32>,\n  /* Clip positions rather than uv: an interpolator divides by w for us, so dividing these by their\n     own interpolated w in the fragment stage is the perspective-correct answer at every pixel. */\n  @location(0) now: vec4<f32>,\n  @location(1) was: vec4<f32>,\n}\n\n@vertex\nfn motionVert(@location(0) position: vec3<f32>) -> Varyings {\n  let world = draw.model * vec4<f32>(position, 1.0);\n  let wasWorld = draw.previousModel * vec4<f32>(position, 1.0);\n  var out: Varyings;\n  out.clip = frame.raster * world;\n  out.now = frame.viewProj * world;\n  out.was = frame.previousViewProj * wasWorld;\n  return out;\n}\n\n/* Normalised device coordinates to the uv the resolve measures in: v increases upward, as the\n   references' images do, and the accessor that reads this target is what flips the texture's rows. */\nfn motionUv(clip: vec4<f32>) -> vec2<f32> {\n  return clip.xy / clip.w * 0.5 + vec2<f32>(0.5);\n}\n\n@fragment\nfn motionFrag(in: Varyings) -> @location(0) vec4<f32> {\n  /*\n   * A surface behind last frame's eye has a w that is not positive, and there is no uv for it. The\n   * flag stays set: the disocclusion refuses a depth that is not positive, so the resolve drops the\n   * history rather than reading it from wherever a divide by a negative w would have pointed.\n   */\n  let offset = select(vec2<f32>(0.0), motionUv(in.was) - motionUv(in.now), in.was.w > 0.0);\n  return vec4<f32>(offset, in.was.w, 1.0);\n}\n";

package/dist/render/shaders/recon/motion.wgsl.js

@@ -0,0 +1,96 @@
+/**
+ * Where a drawn surface was last frame, written into the reconstruction's motion target.
+ *
+ * **A pass of its own rather than a second output on every material.** The alternative is a second
+ * colour attachment on every generated fragment stage, which `ARCHITECTURE.md` §1 prices at 196,910
+ * gzipped bytes for one flag — and it would be paid by every consumer, including the ones who never
+ * reconstruct anything. This draws only the meshes a caller said had moved, with one small shader
+ * over the position buffer alone.
+ *
+ * **What a pixel carries**: the offset from where it is now to where its surface was, in the uv the
+ * resolve measures in; the view depth it had then, which is what the disocclusion compares against
+ * last frame's depth; and a flag. `recon/resolve.ts`'s `historyWeight` is the reader, and a texel
+ * this pass did not write is a zero flag, which means *derive the camera's motion from the depth* —
+ * so a scene that says nothing about its movers is exactly the scene this pass never ran for.
+ *
+ * **The rasterisation matrix is handed over whole, and that is deliberate.** The scene is drawn by
+ * shaders `naga` generated, every one of which ends its vertex stage with `gl_Position.y = -y`, and
+ * `CLIP_CORRECTION` carries a negation to cancel it — §3 rows 56 and 57. This shader is hand
+ * written and has no such negation, so rather than reason about halves of that pair per draw, the
+ * renderer multiplies the two together once a frame and passes the product. The vertex stage then
+ * has one job: put the position exactly where the scene put it, so the depth test compares like
+ * with like.
+ *
+ * **The motion itself is measured from the *unjittered* matrices**, which is the whole of §3 row
+ * 121: the history stands for a picture of the scene as it would have been drawn with no jitter, so
+ * a motion vector that carried the jitter difference would move every sample by a fraction of a
+ * pixel in a pattern that repeats with the jitter period — shimmer, diagnosed as anything but its
+ * cause.
+ */
+/** Floats in the per-frame block: three matrices. */
+export const MOTION_FRAME_FLOATS = 48;
+/**
+ * Bytes a draw's own block takes.
+ *
+ * Two matrices is 128, and a dynamic uniform offset must be a multiple of 256 — the same alignment
+ * §3 row 50's neighbours are about. So each draw takes a whole 256 and half of it is padding, which
+ * is the cheaper half of the trade against a bind group per draw inside the frame loop.
+ */
+export const MOTION_DRAW_STRIDE = 256;
+/** Floats a draw actually writes inside that stride. */
+export const MOTION_DRAW_FLOATS = 32;
+/** The motion target's format. Half float holds a uv to a hundredth of a pixel and a view depth. */
+export const MOTION_TARGET_FORMAT = 'rgba16float';
+export const RECON_MOTION_WGSL = /* wgsl */ `
+struct MotionFrame {
+  /* The scene's own clip transform, with the generated shaders' y negation already folded in. */
+  raster: mat4x4<f32>,
+  /* This frame's and last frame's view-projections, unjittered, in the matrices' own convention. */
+  viewProj: mat4x4<f32>,
+  previousViewProj: mat4x4<f32>,
+}
+
+struct MotionDraw {
+  model: mat4x4<f32>,
+  previousModel: mat4x4<f32>,
+}
+
+@group(0) @binding(0) var<uniform> frame: MotionFrame;
+@group(0) @binding(1) var<uniform> draw: MotionDraw;
+
+struct Varyings {
+  @builtin(position) clip: vec4<f32>,
+  /* Clip positions rather than uv: an interpolator divides by w for us, so dividing these by their
+     own interpolated w in the fragment stage is the perspective-correct answer at every pixel. */
+  @location(0) now: vec4<f32>,
+  @location(1) was: vec4<f32>,
+}
+
+@vertex
+fn motionVert(@location(0) position: vec3<f32>) -> Varyings {
+  let world = draw.model * vec4<f32>(position, 1.0);
+  let wasWorld = draw.previousModel * vec4<f32>(position, 1.0);
+  var out: Varyings;
+  out.clip = frame.raster * world;
+  out.now = frame.viewProj * world;
+  out.was = frame.previousViewProj * wasWorld;
+  return out;
+}
+
+/* Normalised device coordinates to the uv the resolve measures in: v increases upward, as the
+   references' images do, and the accessor that reads this target is what flips the texture's rows. */
+fn motionUv(clip: vec4<f32>) -> vec2<f32> {
+  return clip.xy / clip.w * 0.5 + vec2<f32>(0.5);
+}
+
+@fragment
+fn motionFrag(in: Varyings) -> @location(0) vec4<f32> {
+  /*
+   * A surface behind last frame's eye has a w that is not positive, and there is no uv for it. The
+   * flag stays set: the disocclusion refuses a depth that is not positive, so the resolve drops the
+   * history rather than reading it from wherever a divide by a negative w would have pointed.
+   */
+  let offset = select(vec2<f32>(0.0), motionUv(in.was) - motionUv(in.now), in.was.w > 0.0);
+  return vec4<f32>(offset, in.was.w, 1.0);
+}
+`;

package/dist/render/shaders/recon/resolve.wgsl.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The parameters one resolve reads, as `ResolveFrame` minus its images.
+ *
+ * `hasHistory` is a `u32` because a uniform buffer has no `bool`. The three matrices are the
+ * unjittered ones, in the same convention as the depths the accessors return.
+ */
+export declare const RECON_PARAMS_WGSL = "\nstruct ReconParams {\n  renderSize: vec2<u32>,\n  outputSize: vec2<u32>,\n  jitter: vec2<f32>,\n  previousJitter: vec2<f32>,\n  inverseViewProj: mat4x4<f32>,\n  previousViewProj: mat4x4<f32>,\n  previousInverseViewProj: mat4x4<f32>,\n  eye: vec4<f32>,\n  previousEye: vec4<f32>,\n  alpha: f32,\n  sharpenAmount: f32,\n  clampGamma: f32,\n  hasHistory: u32,\n  depthTolerance: f32,\n  motionScale: f32,\n  normalFloor: f32,\n  normalCeiling: f32,\n}\n";
+/** Floats in `ReconParams`, which is what a caller sizes its uniform buffer by. */
+export declare const RECON_PARAM_FLOATS = 72;
+/** `SAMPLE_SPREAD` and `CONFIDENT_WEIGHT`, which the reference exports and this must not restate. */
+export declare const RECON_SAMPLE_SPREAD = 0.47;
+export declare const RECON_CONFIDENT_WEIGHT = 1;
+/** The workgroup edge both entry points dispatch over. */
+export declare const RECON_WORKGROUP = 8;
+/**
+ * What the histories and the shown picture are stored in.
+ *
+ * **Half float, and the alpha carries a weight rather than an opacity.** The gathered weight is
+ * capped at `(1 - alpha) / alpha` plus one frame's gathering — about twelve at the default — and
+ * eleven bits of mantissa hold that to a part in two thousand, which is far inside what the
+ * disocclusion smoothstep can tell apart. Filterable, which the five-tap Catmull-Rom needs and no
+ * 32-bit float format offers, and storage-capable, which the dispatch writing it needs.
+ */
+export declare const RECON_HISTORY_FORMAT: GPUTextureFormat;
+/**
+ * The arithmetic, as text. Defines `reconResolvePixel(ox, oy) -> vec4<f32>` — the next history's
+ * colour and the weight it has gathered — and `reconSharpenAt(ox, oy) -> vec3<f32>`, the picture
+ * shown, which reads the history the first has already written.
+ */
+export declare const RECON_RESOLVE_CORE_WGSL = "\nconst RECON_SAMPLE_SPREAD: f32 = 0.47;\nconst RECON_CONFIDENT_WEIGHT: f32 = 1.0;\n\nfn reconClampTexel(value: i32, size: i32) -> i32 {\n  return clamp(value, 0, size - 1);\n}\n\n/* JavaScript's Math.round, which is not WGSL's round: a half goes up, not to even. */\nfn reconRound(value: f32) -> f32 {\n  return floor(value + 0.5);\n}\n\n/* Written out rather than the built-in, whose result is undefined where the edges are equal. */\nfn reconSmoothstep(edge0: f32, edge1: f32, x: f32) -> f32 {\n  let t = clamp((x - edge0) / (edge1 - edge0), 0.0, 1.0);\n  return t * t * (3.0 - 2.0 * t);\n}\n\nfn reconWeightAt(dx: f32, dy: f32) -> f32 {\n  return exp(-(dx * dx + dy * dy) / (2.0 * RECON_SAMPLE_SPREAD * RECON_SAMPLE_SPREAD));\n}\n\nfn reconToYCoCg(c: vec3<f32>) -> vec3<f32> {\n  return vec3<f32>(\n    c.r * 0.25 + c.g * 0.5 + c.b * 0.25,\n    c.r * 0.5 - c.b * 0.5,\n    -c.r * 0.25 + c.g * 0.5 - c.b * 0.25,\n  );\n}\n\nfn reconFromYCoCg(c: vec3<f32>) -> vec3<f32> {\n  let base = c.x - c.z;\n  return vec3<f32>(base + c.y, c.x + c.z, base - c.y);\n}\n\nstruct ReconBox {\n  low: vec3<f32>,\n  high: vec3<f32>,\n}\n\n/*\n * Each channel's mean plus or minus gamma of its standard deviation \u2014 and a channel whose nine\n * samples all agree is that value exactly, because a mean of nine equal floats is not always one\n * of them and a box a rounding wide lets a history through by a rounding.\n */\nfn reconVarianceBox(samples: array<vec3<f32>, 9>, gamma: f32) -> ReconBox {\n  var s = samples;\n  var box: ReconBox;\n  for (var c = 0u; c < 3u; c = c + 1u) {\n    let first = s[0][c];\n    var same = true;\n    var sum = 0.0;\n    for (var i = 0u; i < 9u; i = i + 1u) {\n      let value = s[i][c];\n      sum = sum + value;\n      if (value != first) { same = false; }\n    }\n    if (same) {\n      box.low[c] = first;\n      box.high[c] = first;\n      continue;\n    }\n    let mean = sum / 9.0;\n    var spread = 0.0;\n    for (var i = 0u; i < 9u; i = i + 1u) {\n      let d = s[i][c] - mean;\n      spread = spread + d * d;\n    }\n    let deviation = sqrt(spread / 9.0);\n    box.low[c] = mean - gamma * deviation;\n    box.high[c] = mean + gamma * deviation;\n  }\n  return box;\n}\n\n/*\n * The history pulled towards the box's centre until it is inside, by one ratio for all three\n * channels \u2014 a clamp per channel would land it on a corner and change its hue, which is coloured\n * fringing on every moving edge. A channel with no extent bounds anything that differs from it\n * infinitely, so such a history collapses onto the centre.\n */\nfn reconClipToBox(history: vec3<f32>, low: vec3<f32>, high: vec3<f32>) -> vec3<f32> {\n  let centre = (low + high) * 0.5;\n  var offset = history - centre;\n  var extent = (high - low) * 0.5;\n  var ratio = 0.0;\n  var infinite = false;\n  for (var c = 0u; c < 3u; c = c + 1u) {\n    if (extent[c] > 1e-7) {\n      ratio = max(ratio, abs(offset[c]) / extent[c]);\n    } else if (abs(offset[c]) > 1e-7) {\n      infinite = true;\n    }\n  }\n  if (!infinite && !(ratio > 1.0)) { return history; }\n  var scale = 0.0;\n  if (!infinite) { scale = 1.0 / ratio; }\n  return centre + offset * scale;\n}\n\nfn reconAccumulate(current: vec3<f32>, history: vec3<f32>, weight: f32, alpha: f32) -> vec3<f32> {\n  let kept = clamp(weight, 0.0, 1.0) * (1.0 - clamp(alpha, 0.0, 1.0));\n  return current * (1.0 - kept) + history * kept;\n}\n\nfn reconCatmullRom(t: f32) -> vec4<f32> {\n  let t2 = t * t;\n  let t3 = t2 * t;\n  return vec4<f32>(\n    -0.5 * t3 + t2 - 0.5 * t,\n    1.5 * t3 - 2.5 * t2 + 1.0,\n    -1.5 * t3 + 2.0 * t2 + 0.5 * t,\n    0.5 * t3 - 0.5 * t2,\n  );\n}\n\n/*\n * Five bilinear taps standing for the sixteen-texel Catmull-Rom: each axis's middle pair folded\n * into one tap placed between them, the corners dropped, the five weights renormalised. It is the\n * five-tap form because the taps are the expensive part \u2014 which is only true while the bilinear is\n * the sampler's, so the production module's accessor is a filtered sample and the check's is the\n * reference's own arithmetic over loaded texels.\n */\nstruct ReconTaps {\n  at0: vec2<f32>,\n  at1: vec2<f32>,\n  at2: vec2<f32>,\n  at3: vec2<f32>,\n  at4: vec2<f32>,\n  weights: array<f32, 5>,\n  total: f32,\n}\n\nfn reconBicubicTaps(x: f32, y: f32) -> ReconTaps {\n  let x1 = floor(x);\n  let y1 = floor(y);\n  let wx = reconCatmullRom(x - x1);\n  let wy = reconCatmullRom(y - y1);\n  let wx12 = wx[1] + wx[2];\n  let wy12 = wy[1] + wy[2];\n  let x12 = x1 + wx[2] / wx12;\n  let y12 = y1 + wy[2] / wy12;\n  var taps: ReconTaps;\n  taps.at0 = vec2<f32>(x12, y1 - 1.0);\n  taps.at1 = vec2<f32>(x1 - 1.0, y12);\n  taps.at2 = vec2<f32>(x12, y12);\n  taps.at3 = vec2<f32>(x1 + 2.0, y12);\n  taps.at4 = vec2<f32>(x12, y1 + 2.0);\n  taps.weights[0] = wx12 * wy[0];\n  taps.weights[1] = wx[0] * wy12;\n  taps.weights[2] = wx12 * wy12;\n  taps.weights[3] = wx[3] * wy12;\n  taps.weights[4] = wx12 * wy[3];\n  taps.total =\n    taps.weights[0] + taps.weights[1] + taps.weights[2] + taps.weights[3] + taps.weights[4];\n  return taps;\n}\n\n/* A colour cannot be negative, and Catmull-Rom's negative lobes undershoot beside a bright edge. */\nfn reconSceneBicubic5(x: f32, y: f32) -> vec3<f32> {\n  let taps = reconBicubicTaps(x, y);\n  var sum = reconSceneBilinear(taps.at0) * taps.weights[0];\n  sum = sum + reconSceneBilinear(taps.at1) * taps.weights[1];\n  sum = sum + reconSceneBilinear(taps.at2) * taps.weights[2];\n  sum = sum + reconSceneBilinear(taps.at3) * taps.weights[3];\n  sum = sum + reconSceneBilinear(taps.at4) * taps.weights[4];\n  return max(sum / taps.total, vec3<f32>(0.0));\n}\n\nfn reconHistoryBicubic5(x: f32, y: f32) -> vec4<f32> {\n  let taps = reconBicubicTaps(x, y);\n  var sum = reconHistoryBilinear(taps.at0) * taps.weights[0];\n  sum = sum + reconHistoryBilinear(taps.at1) * taps.weights[1];\n  sum = sum + reconHistoryBilinear(taps.at2) * taps.weights[2];\n  sum = sum + reconHistoryBilinear(taps.at3) * taps.weights[3];\n  sum = sum + reconHistoryBilinear(taps.at4) * taps.weights[4];\n  return max(sum / taps.total, vec4<f32>(0.0));\n}\n\nstruct ReconWorld {\n  ok: bool,\n  position: vec3<f32>,\n}\n\n/* The world position a clip depth stands for, and nothing where the matrix has no answer there. */\nfn reconWorldFromDepth(m: mat4x4<f32>, u: f32, v: f32, clipDepth: f32) -> ReconWorld {\n  var out: ReconWorld;\n  out.position = vec3<f32>(0.0);\n  out.ok = false;\n  let x = u * 2.0 - 1.0;\n  let y = v * 2.0 - 1.0;\n  let w = m[0][3] * x + m[1][3] * y + m[2][3] * clipDepth + m[3][3];\n  if (!(abs(w) > 1e-12)) { return out; }\n  let p = m * vec4<f32>(x, y, clipDepth, 1.0);\n  out.position = p.xyz / w;\n  out.ok = all(abs(out.position) < vec3<f32>(3.4e38));\n  return out;\n}\n\nstruct ReconNormal {\n  ok: bool,\n  normal: vec3<f32>,\n}\n\n/* Turned to face the eye, so the answer is the same whichever way the target's rows run. */\nfn reconNormalFrom(\n  centre: vec3<f32>,\n  right: vec3<f32>,\n  up: vec3<f32>,\n  eye: vec3<f32>,\n) -> ReconNormal {\n  var out: ReconNormal;\n  out.normal = vec3<f32>(0.0);\n  out.ok = false;\n  let a = right - centre;\n  let b = up - centre;\n  let n = cross(a, b);\n  let length2 = dot(n, n);\n  let scale2 = dot(a, a) * dot(b, b);\n  if (!(length2 > 1e-12 * scale2)) { return out; }\n  let toEye = dot(n, eye - centre);\n  var sign = 1.0;\n  if (toEye < 0.0) { sign = -1.0; }\n  out.normal = n * (sign / sqrt(length2));\n  out.ok = true;\n  return out;\n}\n\nfn reconDisocclusion(\n  currDepth: f32,\n  histDepth: f32,\n  motionLength: f32,\n  normalDot: f32,\n) -> f32 {\n  if (!(currDepth > 0.0) || !(histDepth > 0.0) || !(motionLength >= 0.0)) { return 0.0; }\n  let disagreement = abs(currDepth - histDepth) / currDepth;\n  let tolerance = recon.depthTolerance + recon.motionScale * motionLength;\n  let depth = 1.0 - reconSmoothstep(tolerance, 2.0 * tolerance, disagreement);\n  let normal = reconSmoothstep(recon.normalFloor, recon.normalCeiling, normalDot);\n  return depth * normal;\n}\n\nstruct ReconAt {\n  depth: f32,\n  position: vec3<f32>,\n}\n\n/* A texel's world position at its unjittered uv, and the view depth it stands at, or zero. */\nfn reconWorldAt(previous: bool, x: i32, y: i32) -> ReconAt {\n  let w = i32(recon.renderSize.x);\n  let h = i32(recon.renderSize.y);\n  let tx = reconClampTexel(x, w);\n  let ty = reconClampTexel(y, h);\n  var jitter = recon.jitter;\n  var m = recon.inverseViewProj;\n  var z = reconDepth(tx, ty);\n  if (previous) {\n    jitter = recon.previousJitter;\n    m = recon.previousInverseViewProj;\n    z = reconPreviousDepth(tx, ty);\n  }\n  let u = (f32(tx) + 0.5 - jitter.x) / f32(w);\n  let v = (f32(ty) + 0.5 - jitter.y) / f32(h);\n  var out: ReconAt;\n  out.depth = 0.0;\n  out.position = vec3<f32>(0.0);\n  let world = reconWorldFromDepth(m, u, v, z);\n  if (!world.ok) { return out; }\n  out.position = world.position;\n  /* The view depth is the clip w, which the inverse's w is the reciprocal of. */\n  let cw = m[0][3] * (u * 2.0 - 1.0) + m[1][3] * (v * 2.0 - 1.0) + m[2][3] * z + m[3][3];\n  out.depth = 1.0 / cw;\n  return out;\n}\n\n/* The neighbour on the inside of the border, so the edge texels have a normal too. */\nfn reconNormalAt(previous: bool, x: i32, y: i32) -> ReconNormal {\n  var out: ReconNormal;\n  out.normal = vec3<f32>(0.0);\n  out.ok = false;\n  let w = i32(recon.renderSize.x);\n  let h = i32(recon.renderSize.y);\n  let centre = reconWorldAt(previous, x, y);\n  if (!(centre.depth > 0.0)) { return out; }\n  var dx = -1;\n  if (x + 1 < w) { dx = 1; }\n  var dy = -1;\n  if (y + 1 < h) { dy = 1; }\n  let right = reconWorldAt(previous, x + dx, y);\n  if (!(right.depth > 0.0)) { return out; }\n  let up = reconWorldAt(previous, x, y + dy);\n  if (!(up.depth > 0.0)) { return out; }\n  var eye = recon.eye.xyz;\n  if (previous) { eye = recon.previousEye.xyz; }\n  return reconNormalFrom(centre.position, right.position, up.position, eye);\n}\n\nstruct ReconHistory {\n  weight: f32,\n  colour: vec4<f32>,\n}\n\n/*\n * The weight a pixel's history still deserves: none on the first frame, none where the surface was\n * behind last frame's eye or off its picture, and otherwise what it gathered, scaled by whether it\n * is the same surface.\n */\nfn reconHistoryWeight(u: f32, v: f32, dx: i32, dy: i32) -> ReconHistory {\n  var out: ReconHistory;\n  out.weight = 0.0;\n  out.colour = vec4<f32>(0.0);\n  if (recon.hasHistory == 0u) { return out; }\n  let rw = f32(recon.renderSize.x);\n  let rh = f32(recon.renderSize.y);\n  let motion = reconMotion(dx, dy);\n  var mu = 0.0;\n  var mv = 0.0;\n  var expected = 0.0;\n  if (motion.w > 0.5) {\n    mu = motion.x;\n    mv = motion.y;\n    expected = motion.z;\n  } else {\n    let here = reconWorldAt(false, dx, dy);\n    if (!(here.depth > 0.0)) { return out; }\n    let clip = recon.previousViewProj * vec4<f32>(here.position, 1.0);\n    /*\n     * A surface behind last frame's eye has a w that is not positive: the disocclusion trusts no\n     * such depth, so it needs no refusal of its own here.\n     */\n    expected = clip.w;\n    let du = (f32(dx) + 0.5 - recon.jitter.x) / rw;\n    let dv = (f32(dy) + 0.5 - recon.jitter.y) / rh;\n    mu = (clip.x / expected) * 0.5 + 0.5 - du;\n    mv = (clip.y / expected) * 0.5 + 0.5 - dv;\n  }\n\n  let pu = u + mu;\n  let pv = v + mv;\n  if (!(pu >= 0.0 && pu <= 1.0 && pv >= 0.0 && pv <= 1.0)) { return out; }\n  out.colour = reconHistoryBicubic5(\n    pu * f32(recon.outputSize.x) - 0.5,\n    pv * f32(recon.outputSize.y) - 0.5,\n  );\n  let px = reconClampTexel(i32(reconRound(pu * rw + recon.previousJitter.x - 0.5)), i32(rw));\n  let py = reconClampTexel(i32(reconRound(pv * rh + recon.previousJitter.y - 0.5)), i32(rh));\n  let held = reconWorldAt(true, px, py).depth;\n  var normalDot = 1.0;\n  let here = reconNormalAt(false, dx, dy);\n  let there = reconNormalAt(true, px, py);\n  if (here.ok && there.ok) { normalDot = dot(here.normal, there.normal); }\n  let trust = reconDisocclusion(expected, held, length(vec2<f32>(mu, mv)), normalDot);\n  out.weight = out.colour.w * trust;\n  return out;\n}\n\n/* One output pixel: the history's next colour, before sharpening, and the weight it has gathered. */\nfn reconResolvePixel(ox: i32, oy: i32) -> vec4<f32> {\n  let rw = i32(recon.renderSize.x);\n  let rh = i32(recon.renderSize.y);\n  let ow = i32(recon.outputSize.x);\n  let oh = i32(recon.outputSize.y);\n  let u = (f32(ox) + 0.5) / f32(ow);\n  let v = (f32(oy) + 0.5) / f32(oh);\n  let jx = recon.jitter.x;\n  let jy = recon.jitter.y;\n\n  /* Where this frame observed the pixel, and the render read there for the gaps. */\n  let rx = u * f32(rw) + jx - 0.5;\n  let ry = v * f32(rh) + jy - 0.5;\n  let sample = reconSceneBicubic5(rx, ry);\n  let nx = reconClampTexel(i32(reconRound(rx)), rw);\n  let ny = reconClampTexel(i32(reconRound(ry)), rh);\n\n  /* Each texel around: its weight, its colour in the box, and its depth. */\n  var nearest = reconDepth(nx, ny);\n  var dx = nx;\n  var dy = ny;\n  var gathered = 0.0;\n  var accum = vec3<f32>(0.0);\n  var neighbours: array<vec3<f32>, 9>;\n  for (var j = -1; j <= 1; j = j + 1) {\n    for (var i = -1; i <= 1; i = i + 1) {\n      let tx = reconClampTexel(nx + i, rw);\n      let ty = reconClampTexel(ny + j, rh);\n      let colour = reconScene(tx, ty);\n      let weight = reconWeightAt(\n        ((f32(tx) + 0.5 - jx) / f32(rw)) * f32(ow) - (f32(ox) + 0.5),\n        ((f32(ty) + 0.5 - jy) / f32(rh)) * f32(oh) - (f32(oy) + 0.5),\n      );\n      gathered = gathered + weight;\n      accum = accum + colour * weight;\n      neighbours[(j + 1) * 3 + (i + 1)] = reconToYCoCg(colour);\n      let z = reconDepth(tx, ty);\n      if (z < nearest) {\n        nearest = z;\n        dx = tx;\n        dy = ty;\n      }\n    }\n  }\n  let box = reconVarianceBox(neighbours, recon.clampGamma);\n  accum = accum / gathered;\n\n  /* The history, and the weight it still deserves; a tenth of each frame is always new. */\n  let cap = (1.0 - recon.alpha) / recon.alpha;\n  let history = reconHistoryWeight(u, v, dx, dy);\n  let kept = min(cap, history.weight);\n\n  let total = kept + gathered;\n  var mixed = accum;\n  if (kept > 0.0) {\n    let clipped = reconClipToBox(reconToYCoCg(history.colour.xyz), box.low, box.high);\n    mixed = reconAccumulate(accum, reconFromYCoCg(clipped), 1.0, gathered / total);\n  }\n  let known = min(1.0, total / RECON_CONFIDENT_WEIGHT);\n  return vec4<f32>(sample * (1.0 - known) + mixed * known, total);\n}\n\n/*\n * The centre pushed away from its four neighbours' mean, and held inside the range of the five \u2014\n * the halo a plain unsharp mask draws beside every edge is a value outside that range.\n */\nfn reconSharpenAt(ox: i32, oy: i32) -> vec3<f32> {\n  let ow = i32(recon.outputSize.x);\n  let oh = i32(recon.outputSize.y);\n  let centre = reconHistory(reconClampTexel(ox, ow), reconClampTexel(oy, oh)).xyz;\n  var offsets = array<vec2<i32>, 4>(\n    vec2<i32>(-1, 0),\n    vec2<i32>(1, 0),\n    vec2<i32>(0, -1),\n    vec2<i32>(0, 1),\n  );\n  var low = centre;\n  var high = centre;\n  var sum = vec3<f32>(0.0);\n  for (var n = 0; n < 4; n = n + 1) {\n    let at = offsets[n];\n    let value = reconHistory(\n      reconClampTexel(ox + at.x, ow),\n      reconClampTexel(oy + at.y, oh),\n    ).xyz;\n    sum = sum + value;\n    low = min(low, value);\n    high = max(high, value);\n  }\n  let pushed = centre + recon.sharpenAmount * (centre - sum / 4.0);\n  return min(high, max(low, pushed));\n}\n";
+/**
+ * The parity module: the core over plain float textures written in the reference's own row order,
+ * doing its own bilinear so the comparison is arithmetic rather than a tolerance on the device's
+ * sampler.
+ *
+ * Two entry points over one set of bindings. `resolveMain` writes four floats a pixel — the next
+ * history — and `sharpenMain` reads that history back at binding 4 and writes three.
+ */
+export declare function reconResolveParityWgsl(): string;
+/**
+ * The production module: the core over the renderer's own attachments.
+ *
+ * **Three things differ from the check, and all three are in the accessors.** The depth textures
+ * hold the renderer's reversed depth, which `wgslSceneDepthToNdc` turns into the sense the matrices
+ * were built for — the resolve picks the *nearest* of nine depths, and under reversed-Z the nearest
+ * is the largest, so an unconverted accessor would dilate the motion of the furthest surface at
+ * every silhouette. A texture's row 0 is the top one and the reference's images run from `v = 0`
+ * upward, so every accessor mirrors the row. And the bilinear reads are the sampler's, which is
+ * what makes the five-tap form cheaper than the sixteen.
+ */
+export declare function reconResolveWgsl(): string;