@driftengine/core 3.63.0 → 4.0.0

package/dist/render/shaders/gi/sampleField.wgsl.d.ts

@@ -0,0 +1,32 @@
+/** Reading the composed field on the device, the way `sampleGlobalField` reads it on the CPU. */
+/**
+ * **One function, included by everything that reads the field, because two spellings drift.**
+ *
+ * `globalField.ts`'s `sampleGlobalField` is the reference: the finest cascade that holds a point
+ * answers, faded into the one outside it across the outer tenth of its extent, and a point past
+ * every cascade takes the outermost clamped at its edge. Every one of those three is a decision a
+ * second implementation would get subtly differently, so this is text rather than a copy — the
+ * march includes it, the parity entry point below includes it, and anything else that needs the
+ * field includes it too.
+ *
+ * **`GLOBAL_FIELD_BLEND` is interpolated in rather than restated**, which is the 2026-08-13 rule
+ * about one number in one place: a fade that is a tenth here and a twelfth there is a seam that
+ * moves with the camera and nothing in either file looks wrong.
+ */
+/** Floats a cascade in the `cascades` buffer: six bounds, the step, and a pad to keep it aligned. */
+export declare const CASCADE_FLOATS = 8;
+/**
+ * The sampler, as WGSL text to include.
+ *
+ * Expects `cascades: array<f32>` and `fields: array<f32>` in scope, and takes the cascade count and
+ * the samples a side as arguments rather than reading them from a third buffer — a function that
+ * reads a global it was not given is one that cannot be moved.
+ */
+export declare const SAMPLE_FIELD_WGSL: string;
+/** Floats in the sampler parity entry point's params: cascade count, samples a side, point count. */
+export declare const SAMPLE_PARAM_FLOATS = 4;
+/**
+ * A compute entry point that does nothing but sample, so `gi-parity.mjs` can compare the function
+ * above against `sampleGlobalField` directly rather than through whatever is using it.
+ */
+export declare const SAMPLE_FIELD_PARITY_WGSL: string;

package/dist/render/shaders/gi/sampleField.wgsl.js

@@ -0,0 +1,134 @@
+/** Reading the composed field on the device, the way `sampleGlobalField` reads it on the CPU. */
+import { GLOBAL_FIELD_BLEND } from '../../gi/globalField.js';
+/**
+ * **One function, included by everything that reads the field, because two spellings drift.**
+ *
+ * `globalField.ts`'s `sampleGlobalField` is the reference: the finest cascade that holds a point
+ * answers, faded into the one outside it across the outer tenth of its extent, and a point past
+ * every cascade takes the outermost clamped at its edge. Every one of those three is a decision a
+ * second implementation would get subtly differently, so this is text rather than a copy — the
+ * march includes it, the parity entry point below includes it, and anything else that needs the
+ * field includes it too.
+ *
+ * **`GLOBAL_FIELD_BLEND` is interpolated in rather than restated**, which is the 2026-08-13 rule
+ * about one number in one place: a fade that is a tenth here and a twelfth there is a seam that
+ * moves with the camera and nothing in either file looks wrong.
+ */
+/** Floats a cascade in the `cascades` buffer: six bounds, the step, and a pad to keep it aligned. */
+export const CASCADE_FLOATS = 8;
+/**
+ * The sampler, as WGSL text to include.
+ *
+ * Expects `cascades: array<f32>` and `fields: array<f32>` in scope, and takes the cascade count and
+ * the samples a side as arguments rather than reading them from a third buffer — a function that
+ * reads a global it was not given is one that cannot be moved.
+ */
+export const SAMPLE_FIELD_WGSL = /* wgsl */ `
+/* Trilinear read of one cascade, clamped at its own edge. The layout is x fastest, then y, then z. */
+fn cascadeAt(level: u32, side: u32, p: vec3<f32>) -> f32 {
+  let base = level * ${CASCADE_FLOATS}u;
+  let low = vec3<f32>(cascades[base], cascades[base + 1u], cascades[base + 2u]);
+  let step = cascades[base + 6u];
+  let count = f32(side);
+
+  var corner = vec3<f32>(0.0, 0.0, 0.0);
+  var frac = vec3<f32>(0.0, 0.0, 0.0);
+  for (var axis = 0u; axis < 3u; axis = axis + 1u) {
+    let local = (p[axis] - low[axis]) / step;
+    let clamped = clamp(local, 0.0, count - 1.0);
+    /*
+     * **The same line guards different things on the two sides, and only one of them shows.**
+     * Stopping one plane short keeps the pair this interpolates between inside the cascade. Drop it
+     * and the corner at count carries weight zero, so the *value* is identical here — WGSL clamps
+     * an out-of-range storage read and zero times anything is zero — while the TypeScript reads
+     * \`undefined\` out of a \`Float32Array\` past its end and \`undefined * 0\` is NaN. Perturbing it
+     * fails \`globalField.test.ts\` and passes \`gi-parity.mjs\`. It stays because it is what keeps
+     * the read inside this cascade rather than in the next one's samples, which share the buffer.
+     */
+    let index = min(floor(clamped), count - 2.0);
+    corner[axis] = index;
+    frac[axis] = clamped - index;
+  }
+
+  let offset = level * side * side * side;
+  let lx = u32(corner.x);
+  let ly = u32(corner.y);
+  let lz = u32(corner.z);
+  var total = 0.0;
+  for (var cz = 0u; cz < 2u; cz = cz + 1u) {
+    let wz = select(1.0 - frac.z, frac.z, cz == 1u);
+    for (var cy = 0u; cy < 2u; cy = cy + 1u) {
+      let wy = select(1.0 - frac.y, frac.y, cy == 1u);
+      for (var cx = 0u; cx < 2u; cx = cx + 1u) {
+        let wx = select(1.0 - frac.x, frac.x, cx == 1u);
+        let at = lx + cx + side * (ly + cy + side * (lz + cz));
+        total = total + fields[offset + at] * wx * wy * wz;
+      }
+    }
+  }
+  return total;
+}
+
+/* How far inside a cascade a point is, measured to the nearest face. Negative means outside. */
+fn insideBy(level: u32, p: vec3<f32>) -> f32 {
+  let base = level * ${CASCADE_FLOATS}u;
+  let low = vec3<f32>(cascades[base], cascades[base + 1u], cascades[base + 2u]);
+  let high = vec3<f32>(cascades[base + 3u], cascades[base + 4u], cascades[base + 5u]);
+  let gap = min(p - low, high - p);
+  return min(gap.x, min(gap.y, gap.z));
+}
+
+/*
+ * The field at a world point, from the finest cascade that holds it.
+ *
+ * Faded into the cascade outside across the outer tenth of the extent, because every boundary here
+ * moves with the camera — the cascades are centred on it — and a hard switch at a boundary that
+ * moves is a seam sweeping through the picture whenever the camera turns.
+ */
+fn sampleField(levels: u32, side: u32, p: vec3<f32>) -> f32 {
+  let last = levels - 1u;
+  for (var level = 0u; level <= last; level = level + 1u) {
+    let inside = insideBy(level, p);
+    if (inside <= 0.0) {
+      continue;
+    }
+    let value = cascadeAt(level, side, p);
+    if (level == last) {
+      return value;
+    }
+    let base = level * ${CASCADE_FLOATS}u;
+    let band = ${GLOBAL_FIELD_BLEND.toFixed(6)} * (cascades[base + 3u] - cascades[base]);
+    if (inside >= band) {
+      return value;
+    }
+    let outer = cascadeAt(level + 1u, side, p);
+    return mix(outer, value, inside / band);
+  }
+  return cascadeAt(last, side, p);
+}
+`;
+/** Floats in the sampler parity entry point's params: cascade count, samples a side, point count. */
+export const SAMPLE_PARAM_FLOATS = 4;
+/**
+ * A compute entry point that does nothing but sample, so `gi-parity.mjs` can compare the function
+ * above against `sampleGlobalField` directly rather than through whatever is using it.
+ */
+export const SAMPLE_FIELD_PARITY_WGSL = /* wgsl */ `
+@group(0) @binding(0) var<storage, read> params: array<f32>;
+@group(0) @binding(1) var<storage, read> cascades: array<f32>;
+@group(0) @binding(2) var<storage, read> fields: array<f32>;
+@group(0) @binding(3) var<storage, read> points: array<f32>;
+@group(0) @binding(4) var<storage, read_write> out: array<f32>;
+
+${SAMPLE_FIELD_WGSL}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  let count = u32(params[2]);
+  if (id.x >= count) {
+    return;
+  }
+  let p = vec3<f32>(points[id.x * 3u], points[id.x * 3u + 1u], points[id.x * 3u + 2u]);
+  out[id.x] = sampleField(u32(params[0]), u32(params[1]), p);
+}
+`;

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

@@ -0,0 +1,26 @@
+export declare const BLEND_RASTER_WGSL: string;
+/**
+ * The two targets composited over what the opaque half drew.
+ *
+ * **`resolveOit` in `render/orderIndependent.ts`, transcribed**, and the division's guard is that
+ * file's: a pixel no fragment touched has a weighted alpha of zero, and its revealage of one
+ * discards whatever this produced anyway.
+ *
+ * **Premultiplied, where the forward path's composite is a lerp**, and the difference is what the
+ * alpha channel means on each side. `renderer.ts` resolves over a scene target whose alpha is not a
+ * coverage mask; this pipeline's colour target has one, because the blit reads it to decide whether
+ * the pass drew a pixel at all. Writing `average * (1 - reveal)` with `1 - reveal` in alpha and
+ * blending `(one, one-minus-src-alpha)` gives both at once: the colour is the same lerp, and the
+ * coverage becomes `1 - (1 - covered) * reveal` — so a pane over empty sky marks the pixel as
+ * drawn, which a lerp would not have.
+ */
+export declare const BLEND_RESOLVE_WGSL = "\n@group(0) @binding(0) var accumMap: texture_2d<f32>;\n@group(0) @binding(1) var revealMap: texture_2d<f32>;\n\nfn oitWeight(viewDepth: f32, alpha: f32) -> f32 {\n  let z = max(viewDepth, 0.0) / 200.0;\n  let falloff = 0.03 / (1e-5 + z * z * z * z);\n  return alpha * clamp(falloff, 1e-2, 3e3);\n}\n\n/* Premultiplied and weighted, against a blend of \"one, one\": the target holds the two sums. */\nfn oitAccumulate(colour: vec3<f32>, alpha: f32, weight: f32) -> vec4<f32> {\n  return vec4<f32>(colour * alpha * weight, alpha * weight);\n}\n\n/*\n * The two targets, as a premultiplied fragment to lay over what is behind them.\n *\n * The weighted sum divided by the weighted alpha is the average colour the layers make, and the\n * revealage says how much of the background still shows. The division is guarded because a pixel no\n * fragment touched has a weighted alpha of zero \u2014 and its revealage of one discards whatever this\n * produces anyway.\n */\nfn oitResolved(accum: vec4<f32>, reveal: f32) -> vec4<f32> {\n  let average = accum.xyz / max(accum.w, 1e-5);\n  let covered = 1.0 - reveal;\n  return vec4<f32>(average * covered, covered);\n}\n\n\nstruct Corner {\n  @builtin(position) position: vec4<f32>,\n}\n\n@vertex\nfn resolveVert(@builtin(vertex_index) vertex: u32) -> Corner {\n  /* One triangle covering the target, which needs no vertex buffer and no clip correction. */\n  var out: Corner;\n  let x = f32((vertex << 1u) & 2u) * 2.0 - 1.0;\n  let y = f32(vertex & 2u) * 2.0 - 1.0;\n  out.position = vec4<f32>(x, y, 0.0, 1.0);\n  return out;\n}\n\n@fragment\nfn resolveFrag(in: Corner) -> @location(0) vec4<f32> {\n  let at = vec2<u32>(in.position.xy);\n  let accum = textureLoad(accumMap, at, 0);\n  let reveal = textureLoad(revealMap, at, 0).x;\n  return oitResolved(accum, reveal);\n}\n";
+/**
+ * The weight and the resolve alone, as a dispatch, so both can be checked against the reference.
+ *
+ * **What a picture cannot show is whether the weight is the forward path's.** Two panes blended by
+ * a weight twice as steep still look like two panes; what it changes is how much a far layer keeps,
+ * and nothing about the frame says so. So the arithmetic is lifted out and compared against
+ * `oitWeight` and `resolveOit` over generated cases.
+ */
+export declare const BLEND_OIT_PARITY_WGSL = "\n/** Six floats a case: depth, alpha, colour, and the background behind it. */\n@group(0) @binding(0) var<storage, read> cases: array<f32>;\n/** Four out: the weight, and the three resolved channels. */\n@group(0) @binding(1) var<storage, read_write> results: array<f32>;\n\nfn oitWeight(viewDepth: f32, alpha: f32) -> f32 {\n  let z = max(viewDepth, 0.0) / 200.0;\n  let falloff = 0.03 / (1e-5 + z * z * z * z);\n  return alpha * clamp(falloff, 1e-2, 3e3);\n}\n\n/* Premultiplied and weighted, against a blend of \"one, one\": the target holds the two sums. */\nfn oitAccumulate(colour: vec3<f32>, alpha: f32, weight: f32) -> vec4<f32> {\n  return vec4<f32>(colour * alpha * weight, alpha * weight);\n}\n\n/*\n * The two targets, as a premultiplied fragment to lay over what is behind them.\n *\n * The weighted sum divided by the weighted alpha is the average colour the layers make, and the\n * revealage says how much of the background still shows. The division is guarded because a pixel no\n * fragment touched has a weighted alpha of zero \u2014 and its revealage of one discards whatever this\n * produces anyway.\n */\nfn oitResolved(accum: vec4<f32>, reveal: f32) -> vec4<f32> {\n  let average = accum.xyz / max(accum.w, 1e-5);\n  let covered = 1.0 - reveal;\n  return vec4<f32>(average * covered, covered);\n}\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3<u32>) {\n  if (id.x * 8u + 7u >= arrayLength(&cases)) { return; }\n  let at = id.x * 8u;\n  let depth = cases[at];\n  let alpha = cases[at + 1u];\n  let colour = vec3<f32>(cases[at + 2u], cases[at + 3u], cases[at + 4u]);\n  let background = vec3<f32>(cases[at + 5u], cases[at + 6u], cases[at + 7u]);\n\n  let weight = oitWeight(depth, alpha);\n  /* One fragment folded in, which is the anchor: for a single layer this reduces to \"over\". */\n  let accum = oitAccumulate(colour, alpha, weight);\n  let reveal = 1.0 - alpha;\n  /*\n   * The resolve's own fragment, then the blend state applied by hand: the pipeline lays it over\n   * the target with \"one, one-minus-src-alpha\", so the background keeps the revealage.\n   */\n  let over = oitResolved(accum, reveal);\n  let resolved = over.xyz + background * (1.0 - over.w);\n\n  let out = id.x * 4u;\n  results[out] = weight;\n  results[out + 1u] = resolved.x;\n  results[out + 2u] = resolved.y;\n  results[out + 3u] = resolved.z;\n}\n";

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

@@ -0,0 +1,339 @@
+import { GPU_DRIVEN_VERTEX_FLOATS } from '../../gpudriven/sceneUpload.js';
+import { DECODE_WGSL, decodeResourcesWgsl } from './decode.wgsl.js';
+import { ENVIRONMENT_WGSL } from './environment.wgsl.js';
+import { FOG_WGSL } from './fog.wgsl.js';
+import { FRAME_BLOCK_WGSL } from './frameBlock.wgsl.js';
+import { MATERIAL_SLOTS, MATERIAL_TABLE_WGSL } from './materialTable.wgsl.js';
+import { MESH_TRANSFORM_WGSL } from './meshTransform.wgsl.js';
+import { SHADE_LIGHTING_WGSL } from './shade.wgsl.js';
+/**
+ * The transparent half: one indirect draw, blended, shaded in the fragment stage.
+ *
+ * **A visibility buffer stores one surface a pixel and therefore cannot hold a blend at all.** That
+ * is architecture rather than an omission: the whole saving of the opaque path is that shading
+ * happens once per pixel, after the frame knows which triangle won, and a pane of glass has no
+ * winner. So the transparent set skips the visibility buffer and is drawn again here, shading where
+ * it stands, with the divergence that implies — exactly as every fragment on the forward path does.
+ *
+ * **What it reuses is the pipeline's front half.** `instanceCull` and the cut answer "which
+ * clusters, at which level of detail", and that question is the same for a pane as for a wall, so
+ * they run a second time over the other half of the scene rather than being written again. The
+ * material's blend flag is what the cut filters on; `cull.wgsl.ts` carries the filter.
+ *
+ * **It includes `SHADE_LIGHTING_WGSL` rather than restating it**, so the expression a pane of glass
+ * is lit by is the expression a wall is lit by, character for character. That is why the lighting
+ * was packaged as an includable function in the first place, and `scripts/gpu-parity.mjs` holds
+ * both to `gpudriven/lit.ts`.
+ *
+ * **Two targets and two blend states, both of which commute.** The accumulation sums weighted
+ * colour and the revealage multiplies what each layer let through, so the frame stops depending on
+ * which surface was submitted first. `orderIndependent.ts` is the arithmetic on the CPU and says
+ * what it approximates; `flatPass.ts`'s `oitTarget` is the same pair of blend states on the forward
+ * path. The weight is `oitWeight`, which both paths share.
+ *
+ * **Depth attached read-only.** A pane behind a wall is rejected at the wall, and nothing here
+ * writes depth, so two panes do not hide each other and there is something left to blend.
+ *
+ * **A transparent surface is not shadowed here**, which is the one place it is lit differently from
+ * an opaque one. `shadowFactor` wants a receiver plane, the shading pass derives one from
+ * barycentric gradients because a compute invocation has no neighbours, and a fragment stage would
+ * have to derive it another way — a second expression for a term whose whole point is that there is
+ * one. `docs/IMPROVEMENTS.md` carries the row. A pane in shadow therefore reads as a pane in
+ * sunlight, which is visible on a bright scene and is stated rather than hidden.
+ */
+/**
+ * The weighted-transparency arithmetic, declared once for the three things that need it.
+ *
+ * **The blended raster, the resolve and the parity entry point are three readers of one rule**, and
+ * the first version of this file gave each of them its own copy. It was caught by the audit the
+ * plan asks for rather than by anything failing: perturbing the weight broke the check while the
+ * shader that draws the frame went on using the old one, which is the exact shape of a gate that
+ * watches a copy of the thing it is guarding.
+ *
+ * `render/orderIndependent.ts` is the reference all of this is written against — `oitWeight` and
+ * `resolveOit`, where both clamps are argued and the algebra is asserted against numbers — and
+ * `flat/main.ts` computes the same weight on the forward path.
+ */
+const OIT_WGSL = /* wgsl */ `
+fn oitWeight(viewDepth: f32, alpha: f32) -> f32 {
+  let z = max(viewDepth, 0.0) / 200.0;
+  let falloff = 0.03 / (1e-5 + z * z * z * z);
+  return alpha * clamp(falloff, 1e-2, 3e3);
+}
+
+/* Premultiplied and weighted, against a blend of "one, one": the target holds the two sums. */
+fn oitAccumulate(colour: vec3<f32>, alpha: f32, weight: f32) -> vec4<f32> {
+  return vec4<f32>(colour * alpha * weight, alpha * weight);
+}
+
+/*
+ * The two targets, as a premultiplied fragment to lay over what is behind them.
+ *
+ * The weighted sum divided by the weighted alpha is the average colour the layers make, and the
+ * revealage says how much of the background still shows. The division is guarded because a pixel no
+ * fragment touched has a weighted alpha of zero — and its revealage of one discards whatever this
+ * produces anyway.
+ */
+fn oitResolved(accum: vec4<f32>, reveal: f32) -> vec4<f32> {
+  let average = accum.xyz / max(accum.w, 1e-5);
+  let covered = 1.0 - reveal;
+  return vec4<f32>(average * covered, covered);
+}
+`;
+export const BLEND_RASTER_WGSL = /* wgsl */ `
+struct BlendVarying {
+  @builtin(position) position: vec4<f32>,
+  @location(0) world: vec3<f32>,
+  @location(1) normal: vec3<f32>,
+  @location(2) colour: vec3<f32>,
+  @location(3) uv: vec2<f32>,
+  @location(4) @interpolate(flat) material: u32,
+  /* The vertex's own glow, added to the material's in the fragment as the shading pass adds it. */
+  @location(5) emissive: f32,
+}
+${MATERIAL_TABLE_WGSL}
+${FRAME_BLOCK_WGSL}
+@group(0) @binding(0) var<storage, read> viewProj: array<f32, 16>;
+/** The compacted list of blended clusters, from the cut's second run. */
+@group(0) @binding(1) var<storage, read> blendList: array<u32>;
+@group(0) @binding(2) var<storage, read> clusterMeta: array<u32>;
+@group(0) @binding(3) var<storage, read> indices: array<u32>;
+@group(0) @binding(4) var<storage, read> vertices: array<f32>;
+@group(0) @binding(5) var<storage, read> transforms: array<f32>;
+@group(0) @binding(6) var<storage, read> materialOf: array<u32>;
+@group(0) @binding(7) var<uniform> materials: array<Material, ${MATERIAL_SLOTS}>;
+@group(0) @binding(8) var<uniform> frame: Frame;
+@group(0) @binding(9) var environmentMap: texture_2d_array<f32>;
+@group(0) @binding(10) var environmentSampler: sampler;
+${decodeResourcesWgsl({ group: 0, latents: 11, clampSampler: 12, repeatSampler: 13, nodes: 14, weights: 15 })}
+fn decodeLatentSize() -> f32 {
+  return frame.size.w;
+}
+
+${DECODE_WGSL}
+/*
+ * **Layer 0, which is this pipeline reading one probe of a grid**, and the same fetch
+ * shade.wgsl.ts makes for the same reason: what this pipeline owns is a fixed cluster set a few
+ * metres across, where a grid would pop as a surface crossed a cell.
+ */
+fn environmentSample(uv: vec2<f32>, level: f32) -> vec3<f32> {
+  return textureSampleLevel(environmentMap, environmentSampler, uv, 0, level).rgb;
+}
+${ENVIRONMENT_WGSL}
+${MESH_TRANSFORM_WGSL}
+${SHADE_LIGHTING_WGSL}
+${FOG_WGSL}
+${OIT_WGSL}
+
+const NO_PROGRAM_HERE: u32 = ${0xffffffff}u;
+
+/*
+ * The same fetch the visibility raster does, keeping the attributes instead of an identifier.
+ *
+ * **"metaAt", because "meta" is a reserved word in WGSL** — the visibility raster's own comment
+ * records that, and this shader indexes the same buffer the same way.
+ */
+@vertex
+fn blendVert(
+  @builtin(vertex_index) vertex: u32,
+  @builtin(instance_index) slot: u32,
+) -> BlendVarying {
+  var out: BlendVarying;
+  out.world = vec3<f32>(0.0);
+  out.normal = vec3<f32>(0.0, 1.0, 0.0);
+  out.colour = vec3<f32>(0.0);
+  out.uv = vec2<f32>(0.0);
+  out.material = 0u;
+  out.emissive = 0.0;
+  let cluster = blendList[slot];
+  let metaAt = cluster * 4u;
+  let indexOffset = clusterMeta[metaAt];
+  let indexCount = clusterMeta[metaAt + 1u];
+  let mesh = clusterMeta[metaAt + 3u];
+
+  let triangle = vertex / 3u;
+  /* Past this cluster's triangles: collapse to a point, which covers no pixel. */
+  if (triangle * 3u >= indexCount) {
+    out.position = vec4<f32>(0.0, 0.0, 0.0, 0.0);
+    return out;
+  }
+
+  let index = indices[indexOffset + vertex];
+  let at = index * ${GPU_DRIVEN_VERTEX_FLOATS}u;
+  let local = vec3<f32>(vertices[at], vertices[at + 1u], vertices[at + 2u]);
+  let world = worldOf(mesh, local);
+
+  out.world = world;
+  out.normal = rotatedOf(mesh, vec3<f32>(vertices[at + 3u], vertices[at + 4u], vertices[at + 5u]));
+  out.colour = vec3<f32>(vertices[at + 6u], vertices[at + 7u], vertices[at + 8u]);
+  out.uv = vec2<f32>(vertices[at + 9u], vertices[at + 10u]);
+  out.emissive = vertices[at + 11u];
+  out.material = materialOf[cluster];
+  out.position = vec4<f32>(
+    viewProj[0] * world.x + viewProj[4] * world.y + viewProj[8] * world.z + viewProj[12],
+    viewProj[1] * world.x + viewProj[5] * world.y + viewProj[9] * world.z + viewProj[13],
+    viewProj[2] * world.x + viewProj[6] * world.y + viewProj[10] * world.z + viewProj[14],
+    viewProj[3] * world.x + viewProj[7] * world.y + viewProj[11] * world.z + viewProj[15],
+  );
+  return out;
+}
+
+struct BlendTargets {
+  @location(0) accum: vec4<f32>,
+  @location(1) reveal: vec4<f32>,
+}
+
+@fragment
+fn blendFrag(in: BlendVarying) -> BlendTargets {
+  var out: BlendTargets;
+  let entry = materials[min(in.material, ${MATERIAL_SLOTS - 1}u)];
+  let uv = in.uv * entry.maps.xy;
+  let lod = 0.0;
+
+  var baseColour = vec4<f32>(1.0);
+  if (entry.programs.x != NO_PROGRAM_HERE) {
+    baseColour = decodeProgram(entry.programs.x, uv, lod, frame.size.z);
+  }
+  /* The material's own opacity times whatever its base-colour map said about this texel. */
+  let alpha = clamp(entry.extra.x * baseColour.w, 0.0, 1.0);
+  let toEye = normalize(frame.eye.xyz - in.world);
+
+  var surface: LitSurface;
+  surface.albedo = in.colour * entry.tint.xyz * baseColour.xyz;
+  surface.normal = normalize(in.normal);
+  surface.toEye = toEye;
+  surface.roughness = entry.surface.x;
+  surface.specular = entry.surface.y;
+  surface.emissive = entry.tint.w + in.emissive;
+  /* Where the pane glows, as the shading pass decides it: the albedo times the emissive map. */
+  var emissiveMapped = vec3<f32>(1.0);
+  if (entry.programs.w != NO_PROGRAM_HERE) {
+    emissiveMapped = decodeProgram(entry.programs.w, uv, lod, frame.size.z).xyz;
+  }
+  surface.emissiveColour = surface.albedo * emissiveMapped;
+  /* Unshadowed, and the header says why and what it costs. */
+  surface.shade = 1.0;
+  surface.reflectivity = entry.surface.z;
+  surface.metalness = entry.surface.w;
+  surface.occlusion = 1.0;
+
+  var room: LitEnvironment;
+  room.lightDir = frame.lightDir.xyz;
+  room.lightColour = frame.lightColour.xyz;
+  room.sky = frame.sky.xyz;
+  room.ground = frame.ground.xyz;
+  let probeBound = frame.environment.w;
+  let edge = frame.environment.x;
+  let maxLod = frame.environment.y;
+  room.radiance = probeRadianceAt(reflect(-toEye, surface.normal), edge, clamp(entry.surface.x * maxLod, 0.0, maxLod), maxLod);
+  room.radianceAmount = probeBound;
+  room.irradiance = probeIrradianceAt(surface.normal, edge, frame.environment.z);
+  room.irradianceAmount = frame.environmentMix.x;
+  room.prefiltered = probeBound;
+  room.emission = frame.environmentMix.y;
+
+  /*
+   * **The haze multiplies the colour and not the alpha.** A pane at the render edge should take the
+   * haze's colour, not become more transparent: fogging its alpha would make distant glass vanish
+   * where it ought to grey out, and the two read completely differently across a large view
+   * distance — which is the whole reason this pipeline gained a fog.
+   */
+  let toward = distance(in.world, frame.eye.xyz);
+  let colour = mix(litColour(surface, room), mediumColour(), mediumFog(toward, in.world.y));
+
+  /*
+   * **The distance to the eye, not the clip-space depth**, because that is what oitWeight's falloff
+   * is written in metres against — render/orderIndependent.ts divides by 200 and flat/main.ts takes
+   * "distance(vWorldPos, uCameraPos)". A weight fed a 0-to-1 depth instead would put every layer of
+   * every scene inside the first hundredth of the falloff.
+   */
+  let weight = oitWeight(toward, alpha);
+  out.accum = oitAccumulate(colour, alpha, weight);
+  /* One channel, and it multiplies: what this layer let through. See the blend state. */
+  out.reveal = vec4<f32>(alpha, 0.0, 0.0, alpha);
+  return out;
+}
+`;
+/**
+ * The two targets composited over what the opaque half drew.
+ *
+ * **`resolveOit` in `render/orderIndependent.ts`, transcribed**, and the division's guard is that
+ * file's: a pixel no fragment touched has a weighted alpha of zero, and its revealage of one
+ * discards whatever this produced anyway.
+ *
+ * **Premultiplied, where the forward path's composite is a lerp**, and the difference is what the
+ * alpha channel means on each side. `renderer.ts` resolves over a scene target whose alpha is not a
+ * coverage mask; this pipeline's colour target has one, because the blit reads it to decide whether
+ * the pass drew a pixel at all. Writing `average * (1 - reveal)` with `1 - reveal` in alpha and
+ * blending `(one, one-minus-src-alpha)` gives both at once: the colour is the same lerp, and the
+ * coverage becomes `1 - (1 - covered) * reveal` — so a pane over empty sky marks the pixel as
+ * drawn, which a lerp would not have.
+ */
+export const BLEND_RESOLVE_WGSL = /* wgsl */ `
+@group(0) @binding(0) var accumMap: texture_2d<f32>;
+@group(0) @binding(1) var revealMap: texture_2d<f32>;
+${OIT_WGSL}
+
+struct Corner {
+  @builtin(position) position: vec4<f32>,
+}
+
+@vertex
+fn resolveVert(@builtin(vertex_index) vertex: u32) -> Corner {
+  /* One triangle covering the target, which needs no vertex buffer and no clip correction. */
+  var out: Corner;
+  let x = f32((vertex << 1u) & 2u) * 2.0 - 1.0;
+  let y = f32(vertex & 2u) * 2.0 - 1.0;
+  out.position = vec4<f32>(x, y, 0.0, 1.0);
+  return out;
+}
+
+@fragment
+fn resolveFrag(in: Corner) -> @location(0) vec4<f32> {
+  let at = vec2<u32>(in.position.xy);
+  let accum = textureLoad(accumMap, at, 0);
+  let reveal = textureLoad(revealMap, at, 0).x;
+  return oitResolved(accum, reveal);
+}
+`;
+/**
+ * The weight and the resolve alone, as a dispatch, so both can be checked against the reference.
+ *
+ * **What a picture cannot show is whether the weight is the forward path's.** Two panes blended by
+ * a weight twice as steep still look like two panes; what it changes is how much a far layer keeps,
+ * and nothing about the frame says so. So the arithmetic is lifted out and compared against
+ * `oitWeight` and `resolveOit` over generated cases.
+ */
+export const BLEND_OIT_PARITY_WGSL = /* wgsl */ `
+/** Six floats a case: depth, alpha, colour, and the background behind it. */
+@group(0) @binding(0) var<storage, read> cases: array<f32>;
+/** Four out: the weight, and the three resolved channels. */
+@group(0) @binding(1) var<storage, read_write> results: array<f32>;
+${OIT_WGSL}
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x * 8u + 7u >= arrayLength(&cases)) { return; }
+  let at = id.x * 8u;
+  let depth = cases[at];
+  let alpha = cases[at + 1u];
+  let colour = vec3<f32>(cases[at + 2u], cases[at + 3u], cases[at + 4u]);
+  let background = vec3<f32>(cases[at + 5u], cases[at + 6u], cases[at + 7u]);
+
+  let weight = oitWeight(depth, alpha);
+  /* One fragment folded in, which is the anchor: for a single layer this reduces to "over". */
+  let accum = oitAccumulate(colour, alpha, weight);
+  let reveal = 1.0 - alpha;
+  /*
+   * The resolve's own fragment, then the blend state applied by hand: the pipeline lays it over
+   * the target with "one, one-minus-src-alpha", so the background keeps the revealage.
+   */
+  let over = oitResolved(accum, reveal);
+  let resolved = over.xyz + background * (1.0 - over.w);
+
+  let out = id.x * 4u;
+  results[out] = weight;
+  results[out + 1u] = resolved.x;
+  results[out + 2u] = resolved.y;
+  results[out + 3u] = resolved.z;
+}
+`;

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

@@ -0,0 +1,29 @@
+/**
+ * Three flag buffers into one list, and the block that draws it.
+ *
+ * **Hand-written WGSL for the reason `cull.wgsl.ts` gives**: there is no GLSL original, because
+ * WebGL2 has neither a compute stage nor an indirect draw. What keeps it honest is
+ * `scripts/gpu-parity.mjs`, which runs it against `gpudriven/compact.ts` over generated flags.
+ *
+ * **The atomic is the whole of it and it is on the draw block rather than on a counter beside
+ * it.** `instanceCount` is the number of clusters this phase draws; incrementing it *is* claiming
+ * a slot in the list, so a separate counter would be the same number in two places and the block
+ * would be written by whoever remembered. The other three words never change — the vertex count is
+ * a cluster's index cap and the two firsts are zero — so a caller writes them once at creation and
+ * clears the one word a frame.
+ *
+ * **Which phase is a setting rather than two shaders.** The two differ only in which side of the
+ * history they take, and a second entry point would be a second place for the cut and the cull to
+ * be applied — which is the half that must be identical in both. See `compact.ts` for the
+ * invariant this is obeying: the history decides which phase a cluster is judged in and never
+ * whether it is judged.
+ */
+/**
+ * One invocation a cluster.
+ *
+ * `settings` is the phase — 0 for the half the history holds, 1 for the rest — and the cluster
+ * count. `drawn` is next frame's history and **only phase two writes it**, for every cluster it
+ * keeps whichever half judged it, because only phase two's cull has seen this frame's pyramid; see
+ * `compactPhase` in `compact.ts`. A caller clears it once a frame.
+ */
+export declare const COMPACT_CLUSTERS_WGSL = "\n/** phase, clusterCount. */\n@group(0) @binding(0) var<storage, read> settings: array<u32, 2>;\n@group(0) @binding(1) var<storage, read> selected: array<u32>;\n@group(0) @binding(2) var<storage, read> keep: array<u32>;\n@group(0) @binding(3) var<storage, read> history: array<u32>;\n@group(0) @binding(4) var<storage, read_write> list: array<u32>;\n@group(0) @binding(5) var<storage, read_write> drawn: array<u32>;\n/** A four-word non-indexed draw block. Only word one is touched here; see the header. */\n@group(0) @binding(6) var<storage, read_write> args: array<atomic<u32>>;\n\n@compute @workgroup_size(64)\nfn main(@builtin(global_invocation_id) id: vec3<u32>) {\n  if (id.x >= settings[1]) { return; }\n\n  let seen = history[id.x] != 0u;\n  let phaseOne = settings[0] == 0u;\n  let visible = selected[id.x] != 0u && keep[id.x] != 0u;\n  /* Next frame's history is phase two's answer, for the clusters phase one drew as well. */\n  if (!phaseOne && visible) { drawn[id.x] = 1u; }\n\n  /* The history decides which half judges this cluster, never whether one does. */\n  if (seen != phaseOne || !visible) { return; }\n\n  /* Claiming the slot and counting the instance are one operation, which is why the atomic is on\n     the draw block. The order slots are handed out in is the scheduler's and is not an answer. */\n  let slot = atomicAdd(&args[1], 1u);\n  list[slot] = id.x;\n}\n";

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

@@ -0,0 +1,58 @@
+/**
+ * Three flag buffers into one list, and the block that draws it.
+ *
+ * **Hand-written WGSL for the reason `cull.wgsl.ts` gives**: there is no GLSL original, because
+ * WebGL2 has neither a compute stage nor an indirect draw. What keeps it honest is
+ * `scripts/gpu-parity.mjs`, which runs it against `gpudriven/compact.ts` over generated flags.
+ *
+ * **The atomic is the whole of it and it is on the draw block rather than on a counter beside
+ * it.** `instanceCount` is the number of clusters this phase draws; incrementing it *is* claiming
+ * a slot in the list, so a separate counter would be the same number in two places and the block
+ * would be written by whoever remembered. The other three words never change — the vertex count is
+ * a cluster's index cap and the two firsts are zero — so a caller writes them once at creation and
+ * clears the one word a frame.
+ *
+ * **Which phase is a setting rather than two shaders.** The two differ only in which side of the
+ * history they take, and a second entry point would be a second place for the cut and the cull to
+ * be applied — which is the half that must be identical in both. See `compact.ts` for the
+ * invariant this is obeying: the history decides which phase a cluster is judged in and never
+ * whether it is judged.
+ */
+/**
+ * One invocation a cluster.
+ *
+ * `settings` is the phase — 0 for the half the history holds, 1 for the rest — and the cluster
+ * count. `drawn` is next frame's history and **only phase two writes it**, for every cluster it
+ * keeps whichever half judged it, because only phase two's cull has seen this frame's pyramid; see
+ * `compactPhase` in `compact.ts`. A caller clears it once a frame.
+ */
+export const COMPACT_CLUSTERS_WGSL = `
+/** phase, clusterCount. */
+@group(0) @binding(0) var<storage, read> settings: array<u32, 2>;
+@group(0) @binding(1) var<storage, read> selected: array<u32>;
+@group(0) @binding(2) var<storage, read> keep: array<u32>;
+@group(0) @binding(3) var<storage, read> history: array<u32>;
+@group(0) @binding(4) var<storage, read_write> list: array<u32>;
+@group(0) @binding(5) var<storage, read_write> drawn: array<u32>;
+/** A four-word non-indexed draw block. Only word one is touched here; see the header. */
+@group(0) @binding(6) var<storage, read_write> args: array<atomic<u32>>;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= settings[1]) { return; }
+
+  let seen = history[id.x] != 0u;
+  let phaseOne = settings[0] == 0u;
+  let visible = selected[id.x] != 0u && keep[id.x] != 0u;
+  /* Next frame's history is phase two's answer, for the clusters phase one drew as well. */
+  if (!phaseOne && visible) { drawn[id.x] = 1u; }
+
+  /* The history decides which half judges this cluster, never whether one does. */
+  if (seen != phaseOne || !visible) { return; }
+
+  /* Claiming the slot and counting the instance are one operation, which is why the atomic is on
+     the draw block. The order slots are handed out in is the scheduler's and is not an answer. */
+  let slot = atomicAdd(&args[1], 1u);
+  list[slot] = id.x;
+}
+`;