@driftengine/core 3.62.0 → 4.0.0

package/dist/render/shaders/gpudriven/fog.wgsl.js

@@ -0,0 +1,107 @@
+import { LINEAR_FOG } from '../../fog.js';
+/**
+ * The medium between the camera and a GPU-driven surface, as WGSL.
+ *
+ * **`render/fog.ts` is the reference and this is checked against it**, over generated cases on a
+ * device by `scripts/gpu-parity.mjs` — the pattern `gpudriven/lit.ts` and `gpudriven/alphaTest.ts`
+ * are both written under, and for the reason this file exists at all: the forward path's fog is
+ * GLSL, so the two pipelines cannot share text and can only be held to one another by measurement.
+ *
+ * **Two shaders include this, and neither restates it.** The shading pass fogs an opaque surface
+ * and the blended raster fogs a pane, and a pane at the render edge that did not take the haze
+ * would stand out of it. The previous wave found the weighted-transparency weight written twice
+ * after its gate had been watching the copy, so this one starts shared.
+ *
+ * The including module declares the `fog` block — `frameBlock.wgsl.ts` does, so both readers get
+ * one layout — and every guard and constant below is `render/fog.ts`'s, which is `shaders/fog.ts`'s.
+ */
+export const FOG_WGSL = /* wgsl */ `
+/** What distance converges toward: the day's haze, or the water column. */
+fn mediumColour() -> vec3<f32> {
+  return mix(frame.fogColour.xyz, frame.fogUnderwater.xyz, frame.fogUnderwater.w);
+}
+
+/**
+ * How much of a surface at "pointY", "dist" metres away, is lost to the medium between.
+ * 0 is perfectly clear, 1 is the medium's own colour.
+ */
+fn mediumFog(dist: f32, pointY: f32) -> f32 {
+  let underwaterFactor = frame.fogUnderwater.w;
+  if (frame.fogRange.z == ${LINEAR_FOG}.0) {
+    /*
+     * A consumer asking for a hard cut writes far == near, and the guard is why that is a cut and
+     * not a NaN at the one distance where the quotient is zero over zero.
+     *
+     * **This copy of it is not observable on the machine this was written on**, and the perturbation
+     * says so: removing it changes nothing the parity check can see, because WGSL does not require
+     * NaN to be supported and this device answers 0 for 0.0/0.0 rather than NaN. The guard stays
+     * because render/fog.ts needs it — its own test fails without it — and because a device that
+     * does propagate NaN would paint the fog colour along the cut. The alpha test found the same
+     * shape from the other direction on 2026-09-18: a device may assume NaN never arrives.
+     */
+    let span = max(frame.fogRange.y - frame.fogRange.x, 1e-4);
+    let ramp = clamp((dist - frame.fogRange.x) / span, 0.0, 1.0);
+    if (underwaterFactor <= 0.0) { return ramp; }
+    let wetLinear = frame.fogRange.w * dist;
+    return mix(ramp, 1.0 - exp2(-wetLinear * wetLinear * 1.442695), underwaterFactor);
+  }
+
+  let t = (pointY - frame.fogColour.w) * frame.fogHeight.x;
+  /* (1 - e^-t)/t, which tends to 1 as the ray levels out. Guarded rather than branched: at t = 0
+     the quotient is 0/0, and 1e-4 of a scale height is 8 mm. */
+  var denom = t;
+  if (abs(t) < 1e-4) { denom = 1e-4; }
+  let air = 1.0 - exp(-frame.fogHeight.y * dist * (1.0 - exp(-denom)) / denom);
+  if (underwaterFactor <= 0.0) { return air; }
+  /* Water is its own medium and keeps its own curve, so crossing the surface changes nothing
+     about how the water column reads. */
+  let wet = frame.fogRange.w * dist;
+  return mix(air, 1.0 - exp2(-wet * wet * 1.442695), underwaterFactor);
+}
+`;
+/** Floats a case of the fog check: distance, height, and the ten options. */
+export const FOG_CASE_FLOATS = 16;
+/**
+ * An entry point that does nothing but fog, so `gpu-parity.mjs` can compare the expression above
+ * with `render/fog.ts` directly rather than through a shading pass that writes to a texture.
+ *
+ * **It declares its own `frame` and fills it from the case**, rather than restating the arithmetic:
+ * the whole point is that the function under test is the one the frame draws with, and a second
+ * copy here is a gate watching a copy of what it guards.
+ */
+export const FOG_PARITY_WGSL = /* wgsl */ `
+struct Frame {
+  /** rgb is the haze's colour, w is the eye's height. */
+  fogColour: vec4<f32>,
+  /** rgb is the water's colour, w is how far under it the camera is. */
+  fogUnderwater: vec4<f32>,
+  /** Reciprocal scale height, extinction per metre at the eye, and two spare. */
+  fogHeight: vec4<f32>,
+  /** Linear near and far, the mode, and the water's own density. */
+  fogRange: vec4<f32>,
+}
+
+@group(0) @binding(0) var<storage, read> cases: array<f32>;
+@group(0) @binding(1) var<storage, read_write> results: array<f32>;
+
+var<private> frame: Frame;
+${FOG_WGSL}
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  let at = id.x * ${FOG_CASE_FLOATS}u;
+  if (at + ${FOG_CASE_FLOATS - 1}u >= arrayLength(&cases)) { return; }
+  let dist = cases[at];
+  let pointY = cases[at + 1u];
+  frame.fogColour = vec4<f32>(cases[at + 2u], cases[at + 3u], cases[at + 4u], cases[at + 5u]);
+  frame.fogUnderwater = vec4<f32>(cases[at + 6u], cases[at + 7u], cases[at + 8u], cases[at + 9u]);
+  frame.fogHeight = vec4<f32>(cases[at + 10u], cases[at + 11u], 0.0, 0.0);
+  frame.fogRange = vec4<f32>(cases[at + 12u], cases[at + 13u], cases[at + 14u], cases[at + 15u]);
+
+  let out = id.x * 4u;
+  results[out] = mediumFog(dist, pointY);
+  let colour = mediumColour();
+  results[out + 1u] = colour.x;
+  results[out + 2u] = colour.y;
+  results[out + 3u] = colour.z;
+}
+`;

package/dist/render/shaders/gpudriven/frameBlock.wgsl.d.ts

@@ -0,0 +1,13 @@
+/**
+ * What the frame tells every stage that lights something, declared once.
+ *
+ * **Two stages light a surface now**: the shading pass, which resolves the visibility buffer, and
+ * the blended raster, which shades a transparent fragment where it stands. They read the same
+ * block because they are given the same frame, and a second declaration of it would be twelve
+ * `vec4`s whose *offsets* have to agree — a field inserted in one and not the other does not fail
+ * to compile, it reads the neighbouring one, so a light direction becomes a sky colour.
+ *
+ * `gpuDrivenPass.ts` writes it through the `FRAME_*` offsets beside `FRAME_FLOATS`, which are the
+ * other half of this contract.
+ */
+export declare const FRAME_BLOCK_WGSL = "\nstruct Frame {\n  viewProj: mat4x4<f32>,\n  /*\n   * The light's, corrected for the lookup rather than for the raster: x and y still in -1..1 and\n   * z already in 0..1. gpudriven/shadowCamera.ts carries why those are two different matrices.\n   */\n  lightViewProj: mat4x4<f32>,\n  eye: vec4<f32>,\n  lightDir: vec4<f32>,\n  lightColour: vec4<f32>,\n  sky: vec4<f32>,\n  ground: vec4<f32>,\n  /** width, height, the simulation time, and the latent layer's edge in texels. */\n  size: vec4<f32>,\n  /** The shadow: strength, map size, depth span, the distance it fades over. */\n  shadow: vec4<f32>,\n  /** Its remaining limits: the steepest sun that still casts, the tap count, and two spare. */\n  shadowLimits: vec4<f32>,\n  /** The probe: texels across level 0, the coarsest GGX level, the cosine level, and 1 if bound. */\n  environment: vec4<f32>,\n  /**\n   * How much of the hemispheric ambient the probe's irradiance replaces, the frame's emissive gain\n   * times its night factor, and two spare.\n   */\n  environmentMix: vec4<f32>,\n  /**\n   * The medium, in four blocks, and render/fog.ts is what reads them.\n   *\n   * **A frame that asks for nothing draws nothing**: a density of zero and the medium mode make\n   * mediumFog exactly zero at every distance, which is arithmetically the frame the pipeline drew\n   * before it had a haze at all.\n   */\n  /** rgb is the haze's colour, w is the eye's height. */\n  fogColour: vec4<f32>,\n  /** rgb is the water's colour, w is how far under it the camera is. */\n  fogUnderwater: vec4<f32>,\n  /** Reciprocal scale height, extinction per metre at the eye, and two spare. */\n  fogHeight: vec4<f32>,\n  /** Linear near and far, the mode, and the water's own density. */\n  fogRange: vec4<f32>,\n  /**\n   * The visibility buffer's row in texels \u2014 the width rounded up for the copy's row alignment \u2014\n   * and three spare. A pixel is found by this and placed by size.x, which is the width the raster\n   * drew at; the two differ on every frame whose width is not a multiple of sixty-four. Not\n   * \"target\", which WGSL reserves.\n   */\n  pitch: vec4<f32>,\n}\n";

package/dist/render/shaders/gpudriven/frameBlock.wgsl.js

@@ -0,0 +1,62 @@
+/**
+ * What the frame tells every stage that lights something, declared once.
+ *
+ * **Two stages light a surface now**: the shading pass, which resolves the visibility buffer, and
+ * the blended raster, which shades a transparent fragment where it stands. They read the same
+ * block because they are given the same frame, and a second declaration of it would be twelve
+ * `vec4`s whose *offsets* have to agree — a field inserted in one and not the other does not fail
+ * to compile, it reads the neighbouring one, so a light direction becomes a sky colour.
+ *
+ * `gpuDrivenPass.ts` writes it through the `FRAME_*` offsets beside `FRAME_FLOATS`, which are the
+ * other half of this contract.
+ */
+export const FRAME_BLOCK_WGSL = /* wgsl */ `
+struct Frame {
+  viewProj: mat4x4<f32>,
+  /*
+   * The light's, corrected for the lookup rather than for the raster: x and y still in -1..1 and
+   * z already in 0..1. gpudriven/shadowCamera.ts carries why those are two different matrices.
+   */
+  lightViewProj: mat4x4<f32>,
+  eye: vec4<f32>,
+  lightDir: vec4<f32>,
+  lightColour: vec4<f32>,
+  sky: vec4<f32>,
+  ground: vec4<f32>,
+  /** width, height, the simulation time, and the latent layer's edge in texels. */
+  size: vec4<f32>,
+  /** The shadow: strength, map size, depth span, the distance it fades over. */
+  shadow: vec4<f32>,
+  /** Its remaining limits: the steepest sun that still casts, the tap count, and two spare. */
+  shadowLimits: vec4<f32>,
+  /** The probe: texels across level 0, the coarsest GGX level, the cosine level, and 1 if bound. */
+  environment: vec4<f32>,
+  /**
+   * How much of the hemispheric ambient the probe's irradiance replaces, the frame's emissive gain
+   * times its night factor, and two spare.
+   */
+  environmentMix: vec4<f32>,
+  /**
+   * The medium, in four blocks, and render/fog.ts is what reads them.
+   *
+   * **A frame that asks for nothing draws nothing**: a density of zero and the medium mode make
+   * mediumFog exactly zero at every distance, which is arithmetically the frame the pipeline drew
+   * before it had a haze at all.
+   */
+  /** rgb is the haze's colour, w is the eye's height. */
+  fogColour: vec4<f32>,
+  /** rgb is the water's colour, w is how far under it the camera is. */
+  fogUnderwater: vec4<f32>,
+  /** Reciprocal scale height, extinction per metre at the eye, and two spare. */
+  fogHeight: vec4<f32>,
+  /** Linear near and far, the mode, and the water's own density. */
+  fogRange: vec4<f32>,
+  /**
+   * The visibility buffer's row in texels — the width rounded up for the copy's row alignment —
+   * and three spare. A pixel is found by this and placed by size.x, which is the width the raster
+   * drew at; the two differ on every frame whose width is not a multiple of sixty-four. Not
+   * "target", which WGSL reserves.
+   */
+  pitch: vec4<f32>,
+}
+`;

package/dist/render/shaders/gpudriven/materialBin.wgsl.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Binning the frame's pixels by material, in three dispatches.
+ *
+ * **Count, then sum, then scatter**, which is the only arrangement that gives each bin a
+ * contiguous slice without sorting: a pixel cannot know where it belongs until every pixel before
+ * it has been counted, so the count has to finish before the offsets exist and the offsets have to
+ * exist before anything is written.
+ *
+ * **The scatter's order inside a bin is whatever the atomics produced**, and nothing downstream
+ * may depend on it. Shading reads a bin as a set. `scripts/gpu-parity.mjs` compares the bins as
+ * sets for the same reason, and compares the *counts* exactly — which are order-free and are where
+ * a binning defect actually shows.
+ *
+ * **The sentinel test in the count and scatter passes survives perturbation**, and it is kept for
+ * the reason `materialBin.ts` states at length: `VIS_EMPTY`'s cluster field reads as 33,554,431,
+ * so the range test below it refuses the same pixels. The range test is the one a real frame
+ * exercises — a visibility buffer left over from a frame with more geometry in it — and it is
+ * caught.
+ *
+ * Hand-written for the reason `cull.wgsl.ts` gives: WebGL2 has no compute stage, so there is no
+ * GLSL original and nothing this can break by being wrong.
+ */
+/**
+ * Pass one: how many pixels each material owns.
+ *
+ * The counts buffer must be **cleared before this runs**. A count buffer reused across frames
+ * without clearing grows without bound, the offsets then run past the end of the pixel list, and
+ * the shading reads a neighbouring bin — which looks like one material bleeding into another.
+ */
+export declare const MATERIAL_COUNT_WGSL = "\nconst VIS_TRIANGLE_BITS: u32 = 7u;\nconst VIS_EMPTY: u32 = 0xffffffffu;\n\n/** pixelCount, materialCount, groupSize. */\n@group(0) @binding(0) var<storage, read> settings: array<u32, 4>;\n@group(0) @binding(1) var<storage, read> visibility: array<u32>;\n@group(0) @binding(2) var<storage, read> materialOf: array<u32>;\n\n@group(0) @binding(3) var<storage, read_write> counts: array<atomic<u32>>;\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3<u32>) {\n  if (id.x >= settings[0]) { return; }\n  let packed = visibility[id.x];\n  if (packed == VIS_EMPTY) { return; }\n  let cluster = packed >> VIS_TRIANGLE_BITS;\n  if (cluster >= arrayLength(&materialOf)) { return; }\n  let material = materialOf[cluster];\n  if (material >= settings[1]) { return; }\n  atomicAdd(&counts[material], 1u);\n}\n";
+/**
+ * Pass two: the offsets, as an exclusive prefix sum, and the dispatch block for each material.
+ *
+ * **One invocation, deliberately.** A material count is tens, not millions, and a parallel scan
+ * over tens of elements costs more in barriers than the serial loop costs in cycles. The comment
+ * is here because "this is not parallel" reads as an oversight in a compute shader and is a
+ * measurement: the scan would be three barriers against a loop of at most a few hundred adds.
+ *
+ * **Every material gets a block, including an empty one**, whose group count is zero. Dropping it
+ * shifts every later material's arguments and shades the scene with the wrong code. The zero is
+ * the round-up's own answer rather than a branch: a `select` stood here and a perturbation
+ * survived it, because `(0 + n - 1) / n` is already zero.
+ */
+export declare const MATERIAL_OFFSETS_WGSL = "\nconst VIS_TRIANGLE_BITS: u32 = 7u;\nconst VIS_EMPTY: u32 = 0xffffffffu;\n\n/** pixelCount, materialCount, groupSize. */\n@group(0) @binding(0) var<storage, read> settings: array<u32, 4>;\n@group(0) @binding(1) var<storage, read> visibility: array<u32>;\n@group(0) @binding(2) var<storage, read> materialOf: array<u32>;\n\n@group(0) @binding(3) var<storage, read> counts: array<u32>;\n@group(0) @binding(4) var<storage, read_write> offsets: array<u32>;\n@group(0) @binding(5) var<storage, read_write> dispatches: array<u32>;\n\n@compute @workgroup_size(1)\nfn main() {\n  let materials = settings[1];\n  let groupSize = max(1u, settings[2]);\n  var running = 0u;\n  for (var material = 0u; material < materials; material = material + 1u) {\n    offsets[material] = running;\n    let held = counts[material];\n    running = running + held;\n    /* Zero falls out of the division: an empty bin is zero groups with no special case. */\n    let groups = (held + groupSize - 1u) / groupSize;\n    dispatches[material * 3u] = groups;\n    dispatches[material * 3u + 1u] = 1u;\n    dispatches[material * 3u + 2u] = 1u;\n  }\n}\n";
+/**
+ * Pass three: every covered pixel's index into its material's slice.
+ *
+ * `cursors` is a copy of the offsets rather than the offsets themselves, because the offsets have
+ * to survive this pass — they are what tells a shading group where its material's list begins.
+ */
+export declare const MATERIAL_SCATTER_WGSL = "\nconst VIS_TRIANGLE_BITS: u32 = 7u;\nconst VIS_EMPTY: u32 = 0xffffffffu;\n\n/** pixelCount, materialCount, groupSize. */\n@group(0) @binding(0) var<storage, read> settings: array<u32, 4>;\n@group(0) @binding(1) var<storage, read> visibility: array<u32>;\n@group(0) @binding(2) var<storage, read> materialOf: array<u32>;\n\n@group(0) @binding(3) var<storage, read_write> cursors: array<atomic<u32>>;\n@group(0) @binding(4) var<storage, read_write> pixels: array<u32>;\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3<u32>) {\n  if (id.x >= settings[0]) { return; }\n  let packed = visibility[id.x];\n  if (packed == VIS_EMPTY) { return; }\n  let cluster = packed >> VIS_TRIANGLE_BITS;\n  if (cluster >= arrayLength(&materialOf)) { return; }\n  let material = materialOf[cluster];\n  if (material >= settings[1]) { return; }\n  let at = atomicAdd(&cursors[material], 1u);\n  pixels[at] = id.x;\n}\n";

package/dist/render/shaders/gpudriven/materialBin.wgsl.js

@@ -0,0 +1,112 @@
+/**
+ * Binning the frame's pixels by material, in three dispatches.
+ *
+ * **Count, then sum, then scatter**, which is the only arrangement that gives each bin a
+ * contiguous slice without sorting: a pixel cannot know where it belongs until every pixel before
+ * it has been counted, so the count has to finish before the offsets exist and the offsets have to
+ * exist before anything is written.
+ *
+ * **The scatter's order inside a bin is whatever the atomics produced**, and nothing downstream
+ * may depend on it. Shading reads a bin as a set. `scripts/gpu-parity.mjs` compares the bins as
+ * sets for the same reason, and compares the *counts* exactly — which are order-free and are where
+ * a binning defect actually shows.
+ *
+ * **The sentinel test in the count and scatter passes survives perturbation**, and it is kept for
+ * the reason `materialBin.ts` states at length: `VIS_EMPTY`'s cluster field reads as 33,554,431,
+ * so the range test below it refuses the same pixels. The range test is the one a real frame
+ * exercises — a visibility buffer left over from a frame with more geometry in it — and it is
+ * caught.
+ *
+ * Hand-written for the reason `cull.wgsl.ts` gives: WebGL2 has no compute stage, so there is no
+ * GLSL original and nothing this can break by being wrong.
+ */
+/** Shared declarations, so the three entry points cannot disagree about the layout. */
+const BIN_PREAMBLE = `
+const VIS_TRIANGLE_BITS: u32 = 7u;
+const VIS_EMPTY: u32 = 0xffffffffu;
+
+/** pixelCount, materialCount, groupSize. */
+@group(0) @binding(0) var<storage, read> settings: array<u32, 4>;
+@group(0) @binding(1) var<storage, read> visibility: array<u32>;
+@group(0) @binding(2) var<storage, read> materialOf: array<u32>;
+`;
+/**
+ * Pass one: how many pixels each material owns.
+ *
+ * The counts buffer must be **cleared before this runs**. A count buffer reused across frames
+ * without clearing grows without bound, the offsets then run past the end of the pixel list, and
+ * the shading reads a neighbouring bin — which looks like one material bleeding into another.
+ */
+export const MATERIAL_COUNT_WGSL = `${BIN_PREAMBLE}
+@group(0) @binding(3) var<storage, read_write> counts: array<atomic<u32>>;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= settings[0]) { return; }
+  let packed = visibility[id.x];
+  if (packed == VIS_EMPTY) { return; }
+  let cluster = packed >> VIS_TRIANGLE_BITS;
+  if (cluster >= arrayLength(&materialOf)) { return; }
+  let material = materialOf[cluster];
+  if (material >= settings[1]) { return; }
+  atomicAdd(&counts[material], 1u);
+}
+`;
+/**
+ * Pass two: the offsets, as an exclusive prefix sum, and the dispatch block for each material.
+ *
+ * **One invocation, deliberately.** A material count is tens, not millions, and a parallel scan
+ * over tens of elements costs more in barriers than the serial loop costs in cycles. The comment
+ * is here because "this is not parallel" reads as an oversight in a compute shader and is a
+ * measurement: the scan would be three barriers against a loop of at most a few hundred adds.
+ *
+ * **Every material gets a block, including an empty one**, whose group count is zero. Dropping it
+ * shifts every later material's arguments and shades the scene with the wrong code. The zero is
+ * the round-up's own answer rather than a branch: a `select` stood here and a perturbation
+ * survived it, because `(0 + n - 1) / n` is already zero.
+ */
+export const MATERIAL_OFFSETS_WGSL = `${BIN_PREAMBLE}
+@group(0) @binding(3) var<storage, read> counts: array<u32>;
+@group(0) @binding(4) var<storage, read_write> offsets: array<u32>;
+@group(0) @binding(5) var<storage, read_write> dispatches: array<u32>;
+
+@compute @workgroup_size(1)
+fn main() {
+  let materials = settings[1];
+  let groupSize = max(1u, settings[2]);
+  var running = 0u;
+  for (var material = 0u; material < materials; material = material + 1u) {
+    offsets[material] = running;
+    let held = counts[material];
+    running = running + held;
+    /* Zero falls out of the division: an empty bin is zero groups with no special case. */
+    let groups = (held + groupSize - 1u) / groupSize;
+    dispatches[material * 3u] = groups;
+    dispatches[material * 3u + 1u] = 1u;
+    dispatches[material * 3u + 2u] = 1u;
+  }
+}
+`;
+/**
+ * Pass three: every covered pixel's index into its material's slice.
+ *
+ * `cursors` is a copy of the offsets rather than the offsets themselves, because the offsets have
+ * to survive this pass — they are what tells a shading group where its material's list begins.
+ */
+export const MATERIAL_SCATTER_WGSL = `${BIN_PREAMBLE}
+@group(0) @binding(3) var<storage, read_write> cursors: array<atomic<u32>>;
+@group(0) @binding(4) var<storage, read_write> pixels: array<u32>;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= settings[0]) { return; }
+  let packed = visibility[id.x];
+  if (packed == VIS_EMPTY) { return; }
+  let cluster = packed >> VIS_TRIANGLE_BITS;
+  if (cluster >= arrayLength(&materialOf)) { return; }
+  let material = materialOf[cluster];
+  if (material >= settings[1]) { return; }
+  let at = atomicAdd(&cursors[material], 1u);
+  pixels[at] = id.x;
+}
+`;

package/dist/render/shaders/gpudriven/materialTable.wgsl.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The material table's layout, declared once for everything that reads it.
+ *
+ * **Two shaders read this table now and they used to be one.** The shading pass has always read a
+ * material; since the raster gained an alpha test it reads one too, because a pixel learns which
+ * triangle owns it there and a discard any later is a discard after the visibility buffer already
+ * held the leaf. A second copy of the struct would be twenty lanes maintained in two places, which
+ * is the failure `cluster-check.mjs`'s header describes at length: two declarations of one decision
+ * drift invisibly, and the thing that breaks is a scalar read as a program index.
+ *
+ * `gpudriven/materialTable.ts` writes the lanes these fields land on and its own header says why
+ * some of them are written through a `DataView`.
+ */
+/**
+ * How many materials the table holds, and it is a declared ceiling rather than a discovered one.
+ *
+ * A uniform array in WGSL is fixed length, and the table is a uniform rather than a storage buffer
+ * because a compute stage may bind only **eight** storage buffers by default — this pass needed
+ * twelve when it was first written, and the device said so at pipeline creation. Sixty-four
+ * materials is 2 kB of the 64 kB a uniform buffer may hold; a scene wanting more wants a storage
+ * buffer and one of the eight slots back from somewhere.
+ */
+export declare const MATERIAL_SLOTS = 64;
+/** The struct and the sentinel, for any module that binds the table. */
+export declare const MATERIAL_TABLE_WGSL = "\nstruct Material {\n  /** rgb is the tint, w is the emissive gain. */\n  tint: vec4<f32>,\n  /** x is the roughness, y the specular reflectance, z the environment's and w the metalness. */\n  surface: vec4<f32>,\n  /** Base colour, normal, ORM and emissive programs; NO_PROGRAM where there is none. */\n  programs: vec4<u32>,\n  /** u scale, v scale, normal strength, occlusion strength. */\n  maps: vec4<f32>,\n  /** Roughness scale, metallic scale, the alpha cutoff, and non-zero where this one blends. */\n  orm: vec4<f32>,\n  /** The blended opacity, and three spare. */\n  extra: vec4<f32>,\n}\n\nconst NO_PROGRAM: u32 = 4294967295u;\n";

package/dist/render/shaders/gpudriven/materialTable.wgsl.js

@@ -0,0 +1,43 @@
+/**
+ * The material table's layout, declared once for everything that reads it.
+ *
+ * **Two shaders read this table now and they used to be one.** The shading pass has always read a
+ * material; since the raster gained an alpha test it reads one too, because a pixel learns which
+ * triangle owns it there and a discard any later is a discard after the visibility buffer already
+ * held the leaf. A second copy of the struct would be twenty lanes maintained in two places, which
+ * is the failure `cluster-check.mjs`'s header describes at length: two declarations of one decision
+ * drift invisibly, and the thing that breaks is a scalar read as a program index.
+ *
+ * `gpudriven/materialTable.ts` writes the lanes these fields land on and its own header says why
+ * some of them are written through a `DataView`.
+ */
+import { DECODE_NO_PROGRAM } from './decode.wgsl.js';
+/**
+ * How many materials the table holds, and it is a declared ceiling rather than a discovered one.
+ *
+ * A uniform array in WGSL is fixed length, and the table is a uniform rather than a storage buffer
+ * because a compute stage may bind only **eight** storage buffers by default — this pass needed
+ * twelve when it was first written, and the device said so at pipeline creation. Sixty-four
+ * materials is 2 kB of the 64 kB a uniform buffer may hold; a scene wanting more wants a storage
+ * buffer and one of the eight slots back from somewhere.
+ */
+export const MATERIAL_SLOTS = 64;
+/** The struct and the sentinel, for any module that binds the table. */
+export const MATERIAL_TABLE_WGSL = /* wgsl */ `
+struct Material {
+  /** rgb is the tint, w is the emissive gain. */
+  tint: vec4<f32>,
+  /** x is the roughness, y the specular reflectance, z the environment's and w the metalness. */
+  surface: vec4<f32>,
+  /** Base colour, normal, ORM and emissive programs; NO_PROGRAM where there is none. */
+  programs: vec4<u32>,
+  /** u scale, v scale, normal strength, occlusion strength. */
+  maps: vec4<f32>,
+  /** Roughness scale, metallic scale, the alpha cutoff, and non-zero where this one blends. */
+  orm: vec4<f32>,
+  /** The blended opacity, and three spare. */
+  extra: vec4<f32>,
+}
+
+const NO_PROGRAM: u32 = ${DECODE_NO_PROGRAM}u;
+`;

package/dist/render/shaders/gpudriven/meshTransform.wgsl.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Placing a mesh's vertex in the world, for every stage of the pipeline that has to.
+ *
+ * **Three stages do it now and each had its own copy of it.** The visibility raster called it
+ * `transformed`, the shading pass called it `worldOf`, and the two bodies were the same nine
+ * multiplies; the blended raster would have been a third. What the copies would drift about is not
+ * the arithmetic but the *layout* — which four floats are the translation — and a stage that reads
+ * the translation from the wrong column draws a mesh somewhere else entirely while every test that
+ * builds its scene at the origin passes.
+ *
+ * **Column major, so the translation is floats 12 to 14.** `clusterWorld.ts` writes the bounds
+ * through the same convention and `sceneShadowBounds` reads them, which is what keeps a cluster's
+ * bounding sphere over the geometry it bounds.
+ *
+ * The including module declares `transforms` — sixteen floats a mesh — at whichever binding it has
+ * room for.
+ */
+export declare const MESH_TRANSFORM_WGSL = "\nfn worldOf(mesh: u32, p: vec3<f32>) -> vec3<f32> {\n  let m = mesh * 16u;\n  return vec3<f32>(\n    transforms[m] * p.x + transforms[m + 4u] * p.y + transforms[m + 8u] * p.z + transforms[m + 12u],\n    transforms[m + 1u] * p.x + transforms[m + 5u] * p.y + transforms[m + 9u] * p.z + transforms[m + 13u],\n    transforms[m + 2u] * p.x + transforms[m + 6u] * p.y + transforms[m + 10u] * p.z + transforms[m + 14u],\n  );\n}\n\n/* Upper three-by-three only: a direction has no translation. See the header on non-uniform scale. */\nfn rotatedOf(mesh: u32, n: vec3<f32>) -> vec3<f32> {\n  let m = mesh * 16u;\n  return vec3<f32>(\n    transforms[m] * n.x + transforms[m + 4u] * n.y + transforms[m + 8u] * n.z,\n    transforms[m + 1u] * n.x + transforms[m + 5u] * n.y + transforms[m + 9u] * n.z,\n    transforms[m + 2u] * n.x + transforms[m + 6u] * n.y + transforms[m + 10u] * n.z,\n  );\n}\n";

package/dist/render/shaders/gpudriven/meshTransform.wgsl.js

@@ -0,0 +1,37 @@
+/**
+ * Placing a mesh's vertex in the world, for every stage of the pipeline that has to.
+ *
+ * **Three stages do it now and each had its own copy of it.** The visibility raster called it
+ * `transformed`, the shading pass called it `worldOf`, and the two bodies were the same nine
+ * multiplies; the blended raster would have been a third. What the copies would drift about is not
+ * the arithmetic but the *layout* — which four floats are the translation — and a stage that reads
+ * the translation from the wrong column draws a mesh somewhere else entirely while every test that
+ * builds its scene at the origin passes.
+ *
+ * **Column major, so the translation is floats 12 to 14.** `clusterWorld.ts` writes the bounds
+ * through the same convention and `sceneShadowBounds` reads them, which is what keeps a cluster's
+ * bounding sphere over the geometry it bounds.
+ *
+ * The including module declares `transforms` — sixteen floats a mesh — at whichever binding it has
+ * room for.
+ */
+export const MESH_TRANSFORM_WGSL = /* wgsl */ `
+fn worldOf(mesh: u32, p: vec3<f32>) -> vec3<f32> {
+  let m = mesh * 16u;
+  return vec3<f32>(
+    transforms[m] * p.x + transforms[m + 4u] * p.y + transforms[m + 8u] * p.z + transforms[m + 12u],
+    transforms[m + 1u] * p.x + transforms[m + 5u] * p.y + transforms[m + 9u] * p.z + transforms[m + 13u],
+    transforms[m + 2u] * p.x + transforms[m + 6u] * p.y + transforms[m + 10u] * p.z + transforms[m + 14u],
+  );
+}
+
+/* Upper three-by-three only: a direction has no translation. See the header on non-uniform scale. */
+fn rotatedOf(mesh: u32, n: vec3<f32>) -> vec3<f32> {
+  let m = mesh * 16u;
+  return vec3<f32>(
+    transforms[m] * n.x + transforms[m + 4u] * n.y + transforms[m + 8u] * n.z,
+    transforms[m + 1u] * n.x + transforms[m + 5u] * n.y + transforms[m + 9u] * n.z,
+    transforms[m + 2u] * n.x + transforms[m + 6u] * n.y + transforms[m + 10u] * n.z,
+  );
+}
+`;

package/dist/render/shaders/gpudriven/present.wgsl.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Putting the GPU-driven pipeline's colour into the frame it was invited to draw in.
+ *
+ * **A contributed pass cannot write into the frame's attachment directly and should not want
+ * to.** `pass.ts` refuses a declared write-set for a reason it states at length; what a pass gets
+ * instead is a target of its own and a draw call at the point the caller put it. So the pipeline
+ * fills a storage texture in `prepare` and this puts it on the screen in `draw` — one triangle, no
+ * sampler, and `textureLoad` at the fragment's own pixel.
+ *
+ * **`textureLoad` rather than a sampler, because there is nothing to filter.** The target is the
+ * frame's own size and the mapping is one texel to one pixel; a sampler would add a filtering mode
+ * to choose and a half-pixel offset to get wrong, in exchange for nothing. It also means the
+ * texture needs no `filterable` sample type, which `rgba16float` has but which a future `r32float`
+ * would not.
+ *
+ * **It writes linear light.** The output transform is the composite's, for the reason
+ * `PassContext` gives: with a composite the resolve grades and a pass that also graded would apply
+ * the curve twice. A frame without one is refused in words rather than papered over — see the
+ * pass's `draw`.
+ */
+export declare const GPU_DRIVEN_BLIT_WGSL = "\nstruct Varying {\n  @builtin(position) position: vec4<f32>,\n}\n\n@group(0) @binding(0) var source: texture_2d<f32>;\n\n@vertex\nfn vertexMain(@builtin(vertex_index) vertex: u32) -> Varying {\n  /* One triangle covering the frame rather than two: no shared edge, no diagonal seam, and the\n     third of the area outside the viewport costs nothing. */\n  var corners = array<vec2<f32>, 3>(\n    vec2<f32>(-1.0, -1.0),\n    vec2<f32>(3.0, -1.0),\n    vec2<f32>(-1.0, 3.0),\n  );\n  var out: Varying;\n  out.position = vec4<f32>(corners[vertex], 0.0, 1.0);\n  return out;\n}\n\n@fragment\nfn fragmentMain(in: Varying) -> @location(0) vec4<f32> {\n  /* The fragment's own pixel. Clamped rather than trusted: a frame larger than the pass's target\n     is a caller that did not resize, and reading out of bounds is a zero this would draw as a\n     black band nobody could place. */\n  let size = textureDimensions(source);\n  let at = min(vec2<u32>(in.position.xy), size - vec2<u32>(1u, 1u));\n  let texel = textureLoad(source, at, 0);\n  /*\n   * **Nothing was drawn here, so nothing is written \u2014 and that is a cost, not a correctness\n   * guard.** The target is cleared to zero and a zero laid over anything premultiplied is that\n   * thing, so the pixel would come out the same either way; this spares every pixel the pipeline\n   * did not cover a blend. Removing it left \"depth-share-check.mjs\" green on 2026-09-18, which is\n   * what says so. Alpha is the coverage: the shading writes one and a blended surface adds its own.\n   *\n   * **Returned as it is, premultiplied, and the pipeline blends it over.** Where the visibility\n   * buffer covered the pixel the coverage is one and over is a plain write. Where only a pane did,\n   * it is the pane's coverage, and the frame behind it \u2014 the sky \u2014 has to show through by the rest.\n   * This used to discard below a half and write the colour as opaque, which painted a heavy pane\n   * over black and dropped a light one altogether.\n   */\n  if (texel.a <= 0.0) { discard; }\n  return texel;\n}\n";
+/**
+ * The same blit, handing the frame the pass's depth as well as its colour.
+ *
+ * **Two pipelines in one frame need one depth buffer.** The blit above presents colour and nothing
+ * else, which is right for a consumer whose whole scene is this pipeline — and wrong for one that
+ * draws its own geometry beside it, because then a forward-path mesh behind GPU-driven geometry has
+ * nothing to be hidden by. No ordering fixes that: drawn before the blit it is painted over, drawn
+ * after it floats in front of a hill.
+ *
+ * **The formats already agree.** The pass's depth texture and the frame's both take `DEPTH_FORMAT`
+ * and `DEPTH_COMPARE` from `depthConvention.ts`, so this is the same format and the same reversed
+ * convention and there is no conversion to get wrong. `gpuDrivenPass.ts` asserts that rather than
+ * trusting it, because a backend that ever differed would produce a depth test that is silently
+ * inverted instead of one that fails.
+ *
+ * **A pixel the pipeline did not cover is discarded before it writes**, exactly as above, so the
+ * sky keeps the depth the frame already had rather than being pushed to the near plane. A pixel
+ * only a pane covered writes the depth the pass cleared to, which is the frame's own clear — the
+ * pipeline compares "or equal" so that it passes over the sky, and what it writes there is the
+ * value already there.
+ */
+export declare const GPU_DRIVEN_BLIT_DEPTH_WGSL = "\nstruct Varying {\n  @builtin(position) position: vec4<f32>,\n}\n\nstruct Presented {\n  @location(0) colour: vec4<f32>,\n  @builtin(frag_depth) depth: f32,\n}\n\n@group(0) @binding(0) var source: texture_2d<f32>;\n@group(0) @binding(1) var sourceDepth: texture_depth_2d;\n\n@vertex\nfn vertexMain(@builtin(vertex_index) vertex: u32) -> Varying {\n  var corners = array<vec2<f32>, 3>(\n    vec2<f32>(-1.0, -1.0),\n    vec2<f32>(3.0, -1.0),\n    vec2<f32>(-1.0, 3.0),\n  );\n  var out: Varying;\n  out.position = vec4<f32>(corners[vertex], 0.0, 1.0);\n  return out;\n}\n\n@fragment\nfn fragmentMain(in: Varying) -> Presented {\n  let size = textureDimensions(source);\n  let at = min(vec2<u32>(in.position.xy), size - vec2<u32>(1u, 1u));\n  let texel = textureLoad(source, at, 0);\n  /* A cost here too: the depth the pass cleared to passes only where the frame holds that same\n     clear, so the write would change nothing. The colour blit above says how that was measured. */\n  if (texel.a <= 0.0) { discard; }\n  var out: Presented;\n  out.colour = texel;\n  /* The depth this pixel was rastered at, so the frame tests against the surface it can see. */\n  out.depth = textureLoad(sourceDepth, at, 0);\n  return out;\n}\n";