@driftengine/core 3.63.0 → 4.0.0

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

@@ -0,0 +1,72 @@
+/**
+ * A probe's own rays, on the device: `gi/chain.ts` minus its screen level.
+ *
+ * **A probe has no use for screen space, and including it would be a defect rather than a cost.**
+ * The screen level is an accelerator for rays cast from the camera's own view, where the frame
+ * already holds the answer. A probe stands in the world and its rays go everywhere, so most of them
+ * leave the frame — and the few that do not would make a *cached* probe depend on where the camera
+ * happens to be, so a probe would change its contents as the viewer turned and every surface it
+ * lights would shimmer. So the chain is entered with a projector that answers "off screen" for
+ * every point, which makes level 0 contribute exactly nothing and levels 1 and 2 take the whole
+ * ray. The reference stays one function; this is that function with one input pinned.
+ *
+ * **What a field hit is worth comes from the probes**, which is the maintainer's answer of
+ * 2026-09-17 and the reason `GiResources.fieldRadiance` is a function rather than a texture: a
+ * probe traced against radiance that is itself probe radiance converges on several bounces over a
+ * few refreshes. The direction it is read along is back down the ray — the light leaving that
+ * surface *towards* the probe is what the probe is measuring — which the chain's own signature
+ * leaves to the caller because it takes no direction.
+ *
+ * **One core, two modules**, as `shaders/recon/resolve.wgsl.ts` and `network.wgsl.ts` are. The
+ * arithmetic reads the field and the probes through functions the including module defines, so the
+ * production module can read the renderer's own buffers and the parity check can read plain ones of
+ * the same numbers.
+ *
+ * The accessors an including module must define, before including the core:
+ *
+ * ```wgsl
+ * fn probeFieldAt(p: vec3<f32>) -> f32          // the composed field's distance at a world point
+ * fn probeFieldInside(p: vec3<f32>) -> f32      // how far inside the outermost cascade, negative outside
+ * fn probeSurfaceRadiance(p: vec3<f32>, towards: vec3<f32>) -> vec3<f32>
+ * fn probeDistantRadiance(p: vec3<f32>, towards: vec3<f32>) -> vec3<f32>
+ * ```
+ *
+ * **Two, and it used to be one.** A ray that struck a wall and a ray that left the world need
+ * different answers and the single accessor could not tell them apart: what leaves a wall is its
+ * albedo times the light reaching it, and what a ray finds having left is whatever the probe
+ * volume coarsely says is out there. Measured with one accessor, a red wall and a white wall
+ * returned the same colour — `demo/dev/bounce.html`, and `plans/2026-09-17-indirect-light.md`
+ * Task 8.
+ *
+ * and `march: ProbeMarch` as a uniform.
+ */
+/**
+ * Floats in the march block, which is sixteen because of how a uniform aligns rather than how many
+ * numbers it holds: four counts, four lengths, and two `vec3`s that each take a whole four-float row.
+ */
+export declare const PROBE_MARCH_FLOATS = 16;
+/** The workgroup a trace dispatches over: one invocation a direction. */
+export declare const PROBE_TRACE_WORKGROUP = 64;
+export declare const PROBE_MARCH_WGSL = "\nstruct ProbeMarch {\n  /* Steps a ray may take, the cascades it may read, and how many samples a cascade is a side. */\n  steps: u32,\n  levels: u32,\n  side: u32,\n  rayCount: u32,\n  /* How far a ray may travel, how close to a surface counts as arriving, the finest voxel. */\n  reachM: f32,\n  hitEpsilonM: f32,\n  finestStep: f32,\n  coneAngle: f32,\n  /* The outermost cascade's corners, for the confidence the last level is faded by. */\n  outerLow: vec3<f32>,\n  outerHigh: vec3<f32>,\n}\n";
+/**
+ * The march and the two levels, as text.
+ *
+ * Defines `probeIndirect(point, normal, direction, coneAngle) -> vec3<f32>`, which is what one of a
+ * probe's rays is worth.
+ */
+export declare const PROBE_TRACE_CORE_WGSL: string;
+/** `FIELD_MARCH`'s own numbers, so a caller fills the block from one place. */
+export declare const PROBE_MARCH_DEFAULTS: import("../../gi/traceField.ts").FieldMarch;
+/**
+ * The parity module: the core over plain buffers, with a radiance that is a function of position.
+ *
+ * **The radiance is positional on purpose.** A march that lands a voxel away from where the
+ * reference landed would return almost the right answer from a smooth field and exactly the right
+ * one from a constant, so a constant radiance would check the *blend* and nothing about the march.
+ * A steep function of the hit's position turns a wrong hit into a wrong colour.
+ *
+ * `probeRadianceAt` is an accessor by design, so this check is of the march and the level blend
+ * alone; what a probe volume answers is the production module's business and `probeVolume.test.ts`
+ * is what holds that.
+ */
+export declare function probeTraceParityWgsl(): string;

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

@@ -0,0 +1,261 @@
+/**
+ * A probe's own rays, on the device: `gi/chain.ts` minus its screen level.
+ *
+ * **A probe has no use for screen space, and including it would be a defect rather than a cost.**
+ * The screen level is an accelerator for rays cast from the camera's own view, where the frame
+ * already holds the answer. A probe stands in the world and its rays go everywhere, so most of them
+ * leave the frame — and the few that do not would make a *cached* probe depend on where the camera
+ * happens to be, so a probe would change its contents as the viewer turned and every surface it
+ * lights would shimmer. So the chain is entered with a projector that answers "off screen" for
+ * every point, which makes level 0 contribute exactly nothing and levels 1 and 2 take the whole
+ * ray. The reference stays one function; this is that function with one input pinned.
+ *
+ * **What a field hit is worth comes from the probes**, which is the maintainer's answer of
+ * 2026-09-17 and the reason `GiResources.fieldRadiance` is a function rather than a texture: a
+ * probe traced against radiance that is itself probe radiance converges on several bounces over a
+ * few refreshes. The direction it is read along is back down the ray — the light leaving that
+ * surface *towards* the probe is what the probe is measuring — which the chain's own signature
+ * leaves to the caller because it takes no direction.
+ *
+ * **One core, two modules**, as `shaders/recon/resolve.wgsl.ts` and `network.wgsl.ts` are. The
+ * arithmetic reads the field and the probes through functions the including module defines, so the
+ * production module can read the renderer's own buffers and the parity check can read plain ones of
+ * the same numbers.
+ *
+ * The accessors an including module must define, before including the core:
+ *
+ * ```wgsl
+ * fn probeFieldAt(p: vec3<f32>) -> f32          // the composed field's distance at a world point
+ * fn probeFieldInside(p: vec3<f32>) -> f32      // how far inside the outermost cascade, negative outside
+ * fn probeSurfaceRadiance(p: vec3<f32>, towards: vec3<f32>) -> vec3<f32>
+ * fn probeDistantRadiance(p: vec3<f32>, towards: vec3<f32>) -> vec3<f32>
+ * ```
+ *
+ * **Two, and it used to be one.** A ray that struck a wall and a ray that left the world need
+ * different answers and the single accessor could not tell them apart: what leaves a wall is its
+ * albedo times the light reaching it, and what a ray finds having left is whatever the probe
+ * volume coarsely says is out there. Measured with one accessor, a red wall and a white wall
+ * returned the same colour — `demo/dev/bounce.html`, and `plans/2026-09-17-indirect-light.md`
+ * Task 8.
+ *
+ * and `march: ProbeMarch` as a uniform.
+ */
+import { GLOBAL_FIELD_BLEND } from '../../gi/globalField.js';
+import { FIELD_MARCH, FIELD_START_VOXELS } from '../../gi/traceField.js';
+import { SAMPLE_FIELD_WGSL } from './sampleField.wgsl.js';
+/**
+ * Floats in the march block, which is sixteen because of how a uniform aligns rather than how many
+ * numbers it holds: four counts, four lengths, and two `vec3`s that each take a whole four-float row.
+ */
+export const PROBE_MARCH_FLOATS = 16;
+/** The workgroup a trace dispatches over: one invocation a direction. */
+export const PROBE_TRACE_WORKGROUP = 64;
+/** A number as WGSL always reads it as a float, so an integer constant is not an `i32`. */
+function f(value) {
+    return Number.isInteger(value) ? value.toFixed(1) : String(value);
+}
+export const PROBE_MARCH_WGSL = /* wgsl */ `
+struct ProbeMarch {
+  /* Steps a ray may take, the cascades it may read, and how many samples a cascade is a side. */
+  steps: u32,
+  levels: u32,
+  side: u32,
+  rayCount: u32,
+  /* How far a ray may travel, how close to a surface counts as arriving, the finest voxel. */
+  reachM: f32,
+  hitEpsilonM: f32,
+  finestStep: f32,
+  coneAngle: f32,
+  /* The outermost cascade's corners, for the confidence the last level is faded by. */
+  outerLow: vec3<f32>,
+  outerHigh: vec3<f32>,
+}
+`;
+/**
+ * The march and the two levels, as text.
+ *
+ * Defines `probeIndirect(point, normal, direction, coneAngle) -> vec3<f32>`, which is what one of a
+ * probe's rays is worth.
+ */
+export const PROBE_TRACE_CORE_WGSL = /* wgsl */ `
+const PROBE_FIELD_START_VOXELS: f32 = ${f(FIELD_START_VOXELS)};
+const PROBE_FIELD_BLEND: f32 = ${f(GLOBAL_FIELD_BLEND)};
+
+struct ProbeFieldHit {
+  hit: bool,
+  point: vec3<f32>,
+}
+
+/* A cone's radius at a distance. Zero angle is a ray, which is what a probe's rays are. */
+fn probeConeRadius(distanceM: f32, coneAngle: f32) -> f32 {
+  return select(0.0, distanceM * tan(coneAngle), coneAngle > 0.0);
+}
+
+/*
+ * March one ray through the composed world field.
+ *
+ * **Lifted along the normal and only along the normal.** Pushing the start along the ray as well
+ * double-counts: a ray leaving along its own normal would begin two offsets out and every distance
+ * it reported would carry the second one. And it does not help the case that needs help — a tangent
+ * ray pushed along itself is still on the surface, because a surface is what tangent means.
+ */
+fn probeTraceField(
+  point: vec3<f32>,
+  normal: vec3<f32>,
+  direction: vec3<f32>,
+  coneAngle: f32,
+) -> ProbeFieldHit {
+  var out: ProbeFieldHit;
+  out.hit = false;
+  out.point = point;
+
+  /* Not named "length": a local of that name shadows the built-in and the next call to it fails. */
+  let reach = length(direction);
+  if (!(reach > 0.0)) { return out; }
+  let unit = direction / reach;
+
+  let start = PROBE_FIELD_START_VOXELS * march.finestStep;
+  let normalLength = length(normal);
+  let lifted = point + select(vec3<f32>(0.0), normal * (start / normalLength), normalLength > 0.0);
+
+  var travelled = 0.0;
+  for (var step = 0u; step < march.steps; step = step + 1u) {
+    let at = lifted + unit * travelled;
+    /*
+     * **Outside the outermost cascade the march stops rather than sampling.** There is no
+     * information out there: the sampler clamps to the edge, which is right for a sample and wrong
+     * for a march — stepping on clamped values converges on the cascade's boundary and reports a
+     * surface made of nothing.
+     */
+    if (probeFieldInside(at) <= 0.0) { return out; }
+
+    let distance = probeFieldAt(at);
+    if (distance <= probeConeRadius(travelled, coneAngle) + march.hitEpsilonM) {
+      out.hit = true;
+      out.point = at;
+      return out;
+    }
+    /*
+     * **Step by the distance, and by at least a quarter of a voxel.** A field whose value is
+     * genuinely tiny beside a surface the cone is not wide enough to accept would otherwise take
+     * ever-smaller steps and spend the whole budget arriving nowhere, which reads as a miss and
+     * costs a fallback anyway. The floor makes that case terminate quickly instead.
+     */
+    travelled = travelled + max(distance, march.finestStep * 0.25);
+    if (travelled > march.reachM) { return out; }
+  }
+  return out;
+}
+
+/*
+ * How much of a field hit is trusted, faded across the outer tenth of the outermost cascade.
+ *
+ * Every boundary in this chain 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 probeFieldConfidence(p: vec3<f32>) -> f32 {
+  let band = PROBE_FIELD_BLEND * (march.outerHigh.x - march.outerLow.x);
+  if (band <= 0.0) { return 1.0; }
+  let gap = min(p - march.outerLow, march.outerHigh - p);
+  return clamp(min(gap.x, min(gap.y, gap.z)) / band, 0.0, 1.0);
+}
+
+/*
+ * One of a probe's rays, as radiance.
+ *
+ * Level 1 answers as much as its distance from the outermost cascade's face allows; level 2 takes
+ * whatever is left without asking, which is what "never wrong and only ever coarse" buys. There is
+ * no case where the probes decline, and no fourth level to fall to.
+ */
+fn probeIndirect(
+  point: vec3<f32>,
+  normal: vec3<f32>,
+  direction: vec3<f32>,
+  coneAngle: f32,
+) -> vec3<f32> {
+  var radiance = vec3<f32>(0.0);
+  var fieldShare = 0.0;
+
+  let hit = probeTraceField(point, normal, direction, coneAngle);
+  if (hit.hit) {
+    fieldShare = probeFieldConfidence(hit.point);
+    if (fieldShare > 0.0) {
+      /* Back down the ray: what this surface sends *towards* the probe is what the probe measures. */
+      radiance = radiance + probeSurfaceRadiance(hit.point, -direction) * fieldShare;
+    }
+  }
+
+  let probes = 1.0 - fieldShare;
+  if (probes > 0.0) {
+    radiance = radiance + probeDistantRadiance(point + direction * march.reachM, -direction) * probes;
+  }
+  return radiance;
+}
+`;
+/** `FIELD_MARCH`'s own numbers, so a caller fills the block from one place. */
+export const PROBE_MARCH_DEFAULTS = FIELD_MARCH;
+/**
+ * The parity module: the core over plain buffers, with a radiance that is a function of position.
+ *
+ * **The radiance is positional on purpose.** A march that lands a voxel away from where the
+ * reference landed would return almost the right answer from a smooth field and exactly the right
+ * one from a constant, so a constant radiance would check the *blend* and nothing about the march.
+ * A steep function of the hit's position turns a wrong hit into a wrong colour.
+ *
+ * `probeRadianceAt` is an accessor by design, so this check is of the march and the level blend
+ * alone; what a probe volume answers is the production module's business and `probeVolume.test.ts`
+ * is what holds that.
+ */
+export function probeTraceParityWgsl() {
+    return /* wgsl */ `
+@group(0) @binding(0) var<storage, read> cascades: array<f32>;
+@group(0) @binding(1) var<storage, read> fields: array<f32>;
+${PROBE_MARCH_WGSL}
+@group(0) @binding(2) var<uniform> march: ProbeMarch;
+/* Seven floats a ray: the point, the normal, the direction. The cone angle is the march's. */
+@group(0) @binding(3) var<storage, read> rays: array<f32>;
+@group(0) @binding(4) var<storage, read_write> radiance: array<f32>;
+${SAMPLE_FIELD_WGSL}
+
+fn probeFieldAt(p: vec3<f32>) -> f32 {
+  return sampleField(march.levels, march.side, p);
+}
+
+fn probeFieldInside(p: vec3<f32>) -> f32 {
+  return insideBy(march.levels - 1u, p);
+}
+
+/* The same expression the harness evaluates, and the reason it is a sine of position. */
+fn probeParityRadiance(p: vec3<f32>) -> vec3<f32> {
+  return vec3<f32>(
+    0.5 + 0.4 * sin(p.x * 1.3),
+    0.5 + 0.4 * sin(p.y * 1.7 + 1.0),
+    0.5 + 0.4 * sin(p.z * 2.3 + 2.0),
+  );
+}
+
+/* One expression for both, so this module keeps checking the march and the blend and nothing else. */
+fn probeSurfaceRadiance(p: vec3<f32>, towards: vec3<f32>) -> vec3<f32> {
+  return probeParityRadiance(p);
+}
+
+fn probeDistantRadiance(p: vec3<f32>, towards: vec3<f32>) -> vec3<f32> {
+  return probeParityRadiance(p);
+}
+${PROBE_TRACE_CORE_WGSL}
+
+@compute @workgroup_size(${PROBE_TRACE_WORKGROUP})
+fn traceMain(@builtin(global_invocation_id) id: vec3<u32>) {
+  if (id.x >= march.rayCount) { return; }
+  let at = id.x * 9u;
+  let point = vec3<f32>(rays[at], rays[at + 1u], rays[at + 2u]);
+  let normal = vec3<f32>(rays[at + 3u], rays[at + 4u], rays[at + 5u]);
+  let direction = vec3<f32>(rays[at + 6u], rays[at + 7u], rays[at + 8u]);
+  let value = probeIndirect(point, normal, direction, march.coneAngle);
+  let out = id.x * 3u;
+  radiance[out] = value.x;
+  radiance[out + 1u] = value.y;
+  radiance[out + 2u] = value.z;
+}
+`;
+}

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

@@ -0,0 +1,49 @@
+/**
+ * What the probe grid answers at a world point, on the device.
+ *
+ * **This is the fourth spelling of one idea and the file says so rather than hoping.**
+ * `probeGrid.ts` holds the eight-probe trilinear blend in TypeScript, `octahedral.ts` holds the
+ * mapping in TypeScript and again in GLSL, and `shaders/flat/probeGrid.ts` holds both together in
+ * the GLSL the lit pass uses. This is WGSL, because a hand-written compute shader cannot include a
+ * generated one — and `scripts/probe-bake-parity.mjs` is what holds it to the others rather than
+ * a reader's confidence that four copies of an expression say the same thing.
+ *
+ * **Why a probe reads the grid at all**: the maintainer's answer of 2026-09-17 is that what a field
+ * hit is worth comes from the probes, so a probe traced against radiance that is itself probe
+ * radiance converges on several bounces over a few refreshes. That is what makes this the multi-
+ * bounce half of Wave 4A rather than a single-bounce approximation of it.
+ *
+ * **No visibility term here, deliberately.** `visibleProbes` exists to stop light reaching a
+ * *surface* through a wall it is behind, and it is what `gridIrradiance` applies when shading. A
+ * probe asking "what is the radiance out there" is a different question with a different failure:
+ * crushing a blind probe's weight would make the bounce darker than the room, and the reference
+ * this is checked against — `indirect-parity.mjs` — enters the chain with `visibility: null` for
+ * exactly this reason.
+ *
+ * The accessor an including module must define, before including the core:
+ *
+ * ```wgsl
+ * fn probeLayerSample(layer: u32, uv: vec2<f32>) -> vec3<f32>       // at the radiance level
+ * fn probeLayerIrradiance(layer: u32, uv: vec2<f32>) -> vec3<f32>   // at the irradiance level
+ * ```
+ *
+ * and `volume: ProbeVolume` as a uniform. Production samples a texture; the parity module reads a
+ * plain buffer of the same numbers.
+ */
+/**
+ * Floats in the volume block, and where each field starts.
+ *
+ * Named offsets for the reason `probeBake.wgsl.ts` gives and paid for: an `f32` after a `vec3<f32>`
+ * fills the vec3's padding rather than starting a new row, so `edge` is float **11**.
+ */
+export declare const VOLUME_ORIGIN = 0;
+export declare const VOLUME_INV_SPACING = 4;
+export declare const VOLUME_COUNTS = 8;
+export declare const VOLUME_EDGE = 11;
+export declare const VOLUME_LEVEL = 12;
+export declare const VOLUME_RADIANCE_EDGE = 13;
+export declare const VOLUME_RADIANCE_LEVEL = 14;
+/** Fifty-two bytes of fields rounded up to the struct's own sixteen-byte alignment. */
+export declare const PROBE_VOLUME_FLOATS = 16;
+export declare const PROBE_VOLUME_STRUCT_WGSL = "\nstruct ProbeVolume {\n  /* Where the grid's first probe stands, and one over the step between them. */\n  origin: vec3<f32>,\n  invSpacing: vec3<f32>,\n  /* How many probes along each axis. Whole numbers carried as floats. */\n  counts: vec3<f32>,\n  /* Texels across the level being sampled, gutter included. */\n  edge: f32,\n  /* Which mip of the probe array that level is. */\n  level: f32,\n  /* And the level that holds *radiance* rather than irradiance, with its own edge. */\n  radianceEdge: f32,\n  radianceLevel: f32,\n  padA: f32,\n}\n";
+export declare const PROBE_VOLUME_CORE_WGSL = "\n/* The octahedral encode, matching \"octEncode\" in \"shaders/octahedral.ts\". */\nfn probeOctEncode(d: vec3<f32>) -> vec2<f32> {\n  let n = d / (abs(d.x) + abs(d.y) + abs(d.z));\n  var p = n.xy;\n  if (n.z < 0.0) {\n    p = (1.0 - abs(vec2<f32>(n.y, n.x))) *\n      vec2<f32>(select(-1.0, 1.0, n.x >= 0.0), select(-1.0, 1.0, n.y >= 0.0));\n  }\n  return p * 0.5 + 0.5;\n}\n\n/*\n * Where to sample a direction in a map whose outer ring is a gutter.\n *\n * The inner region is \"edge - 2\" texels offset by one, so a direction at the very border of the\n * octahedral square lands on the last real texel and the tap that interpolates past it reads the\n * gutter \u2014 which the bake filled with the folded direction.\n */\nfn probeOctInsetUv(d: vec3<f32>, edge: f32) -> vec2<f32> {\n  return (probeOctEncode(d) * (edge - 2.0) + 1.0) / edge;\n}\n\n/*\n * One axis of the lookup: which probe is below the point, and how far past it the point is.\n *\n * **The index is integer arithmetic and the fraction is not**, which is the distinction row 139 of\n * the resume file is about. A world position divided by a spacing is a genuine float division and\n * its floor is a genuine floor; what must never be written in floats is a *lattice* \u2014 an index\n * decomposed out of a layer number \u2014 because a device may implement that division as a\n * multiplication by a reciprocal and answer 3 for 3.0 % 3.0.\n *\n * The lower index stops one short of the last probe so the pair \"index\" and \"index + 1\" is always\n * inside the grid, and a single-probe axis has no pair at all \u2014 both corners are probe zero and\n * the fraction is zero, so that axis multiplies every weight by one.\n */\nstruct ProbeCell {\n  index: u32,\n  fraction: f32,\n}\n\nfn probeCell(value: f32, origin: f32, invSpacing: f32, count: u32) -> ProbeCell {\n  var out: ProbeCell;\n  out.index = 0u;\n  out.fraction = 0.0;\n  if (count <= 1u) { return out; }\n  let local = (value - origin) * invSpacing;\n  let span = f32(count - 1u);\n  let clamped = clamp(local, 0.0, span);\n  let index = min(u32(floor(clamped)), count - 2u);\n  out.index = index;\n  out.fraction = clamped - f32(index);\n  return out;\n}\n\n/*\n * The layer a probe at whole lattice coordinates occupies. x fastest, then y, then z.\n *\n * **Not clamped, and \"ProbeGrid.layerAt\" is** \u2014 the difference is who may call them. \"layerAt\" is a\n * public method whose contract is that it accepts anything, so it clamps; this is reached from one\n * place, under two guarantees that together make the clamp unreachable. \"probeCell\" returns an\n * index no greater than \"count - 2\", so \"index + 1\" is inside; and on an axis only one probe wide\n * it returns index 0 with fraction 0, so the far corner's weight is zero and the caller skips it\n * before asking. A clamp here would be a line no perturbation can make fail, which this session\n * has already had to remove twice.\n */\nfn probeLayerAt(ix: u32, iy: u32, iz: u32, counts: vec3<u32>) -> u32 {\n  return ix + counts.x * (iy + counts.y * iz);\n}\n\n/*\n * What has already bounced onto a surface facing the normal at a point, from the level this writes.\n *\n * **One shared direction, and that is right here where a per-corner one is right for radiance.**\n * An irradiance map is indexed by the *normal of the surface being lit*, not by where the light\n * came from, so every probe is asked the same question: what reaches a surface facing this way.\n * Reading it at the level the bake writes is what closes the loop \u2014 the second bounce is the first\n * one read back.\n */\nfn probeVolumeIrradianceAt(p: vec3<f32>, n: vec3<f32>) -> vec3<f32> {\n  let counts = vec3<u32>(\n    max(1u, u32(volume.counts.x)),\n    max(1u, u32(volume.counts.y)),\n    max(1u, u32(volume.counts.z)),\n  );\n  let cx = probeCell(p.x, volume.origin.x, volume.invSpacing.x, counts.x);\n  let cy = probeCell(p.y, volume.origin.y, volume.invSpacing.y, counts.y);\n  let cz = probeCell(p.z, volume.origin.z, volume.invSpacing.z, counts.z);\n  let uv = probeOctInsetUv(n, volume.edge);\n\n  var sum = vec3<f32>(0.0);\n  for (var oz = 0u; oz < 2u; oz = oz + 1u) {\n    let wz = select(1.0 - cz.fraction, cz.fraction, oz == 1u);\n    for (var oy = 0u; oy < 2u; oy = oy + 1u) {\n      let wy = select(1.0 - cy.fraction, cy.fraction, oy == 1u);\n      for (var ox = 0u; ox < 2u; ox = ox + 1u) {\n        let wx = select(1.0 - cx.fraction, cx.fraction, ox == 1u);\n        let weight = wx * wy * wz;\n        if (weight <= 0.0) { continue; }\n        let layer = probeLayerAt(cx.index + ox, cy.index + oy, cz.index + oz, counts);\n        sum = sum + probeLayerIrradiance(layer, uv) * weight;\n      }\n    }\n  }\n  return sum;\n}\n\n/* Where a layer's probe stands, which a parallax read needs and the lattice above decides. */\nfn probeVolumeProbeAt(layer: u32, counts: vec3<u32>) -> vec3<f32> {\n  let x = layer % counts.x;\n  let y = (layer / counts.x) % counts.y;\n  let z = layer / (counts.x * counts.y);\n  let spacing = vec3<f32>(\n    select(0.0, 1.0 / volume.invSpacing.x, volume.invSpacing.x != 0.0),\n    select(0.0, 1.0 / volume.invSpacing.y, volume.invSpacing.y != 0.0),\n    select(0.0, 1.0 / volume.invSpacing.z, volume.invSpacing.z != 0.0),\n  );\n  return volume.origin + vec3<f32>(f32(x), f32(y), f32(z)) * spacing;\n}\n\n/*\n * The radiance leaving a world point, as the grid saw it.\n *\n * **A ray needs radiance and the first version read irradiance**, which is what\n * \"demo/dev/bounce.html\" measured as a bounce dimmer and greyer than the rasterised grid it was\n * meant to replace. Irradiance is light *arriving* at a point, already cosine-convolved over a\n * hemisphere; what a ray that struck a wall needs is the light *leaving* that wall towards it. The\n * two differ by the surface's albedo \u2014 so a red wall and a white wall at the same irradiance\n * returned the same colour, and the red never travelled.\n *\n * **Level 0 of the probe array is that radiance**, and it needs no albedo because it is a\n * rasterised capture of the shaded room: the red wall is red in it. \u00A76.4 of the design names\n * \"envProbeArray.ts\" as this track's starting point and leaves how much of it to reuse to\n * measurement, which is this.\n *\n * **Each corner is read along its own direction to the point**, which is what makes this a\n * position lookup rather than a direction one. Eight probes sampled along one shared direction\n * answer \"what is over there from roughly here\"; eight probes each sampled towards \"p\" answer\n * \"what is at \"p\"\", and the difference is the parallax that a marched hit exists to provide. It is\n * also why no direction is passed in: deriving it removes the reversed-direction mistake that\n * \"probe-bake-parity.mjs\" records being unable to see.\n */\nfn probeVolumeRadianceAt(p: vec3<f32>) -> vec3<f32> {\n  let counts = vec3<u32>(\n    max(1u, u32(volume.counts.x)),\n    max(1u, u32(volume.counts.y)),\n    max(1u, u32(volume.counts.z)),\n  );\n  let cx = probeCell(p.x, volume.origin.x, volume.invSpacing.x, counts.x);\n  let cy = probeCell(p.y, volume.origin.y, volume.invSpacing.y, counts.y);\n  let cz = probeCell(p.z, volume.origin.z, volume.invSpacing.z, counts.z);\n\n  var sum = vec3<f32>(0.0);\n  for (var oz = 0u; oz < 2u; oz = oz + 1u) {\n    let wz = select(1.0 - cz.fraction, cz.fraction, oz == 1u);\n    for (var oy = 0u; oy < 2u; oy = oy + 1u) {\n      let wy = select(1.0 - cy.fraction, cy.fraction, oy == 1u);\n      for (var ox = 0u; ox < 2u; ox = ox + 1u) {\n        let wx = select(1.0 - cx.fraction, cx.fraction, ox == 1u);\n        let weight = wx * wy * wz;\n        if (weight <= 0.0) { continue; }\n        let layer = probeLayerAt(cx.index + ox, cy.index + oy, cz.index + oz, counts);\n        /*\n         * From that probe towards the point, which is the parallax. A probe standing exactly on\n         * the point has no direction to offer and takes its own zeroth texel, which is as good an\n         * answer as exists for a point inside a probe.\n         */\n        let offset = p - probeVolumeProbeAt(layer, counts);\n        let reach = length(offset);\n        let towards = select(vec3<f32>(0.0, 0.0, 1.0), offset / reach, reach > 0.0);\n        let uv = probeOctInsetUv(towards, volume.radianceEdge);\n        sum = sum + probeLayerSample(layer, uv) * weight;\n      }\n    }\n  }\n  return sum;\n}\n";

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

@@ -0,0 +1,242 @@
+/**
+ * What the probe grid answers at a world point, on the device.
+ *
+ * **This is the fourth spelling of one idea and the file says so rather than hoping.**
+ * `probeGrid.ts` holds the eight-probe trilinear blend in TypeScript, `octahedral.ts` holds the
+ * mapping in TypeScript and again in GLSL, and `shaders/flat/probeGrid.ts` holds both together in
+ * the GLSL the lit pass uses. This is WGSL, because a hand-written compute shader cannot include a
+ * generated one — and `scripts/probe-bake-parity.mjs` is what holds it to the others rather than
+ * a reader's confidence that four copies of an expression say the same thing.
+ *
+ * **Why a probe reads the grid at all**: the maintainer's answer of 2026-09-17 is that what a field
+ * hit is worth comes from the probes, so a probe traced against radiance that is itself probe
+ * radiance converges on several bounces over a few refreshes. That is what makes this the multi-
+ * bounce half of Wave 4A rather than a single-bounce approximation of it.
+ *
+ * **No visibility term here, deliberately.** `visibleProbes` exists to stop light reaching a
+ * *surface* through a wall it is behind, and it is what `gridIrradiance` applies when shading. A
+ * probe asking "what is the radiance out there" is a different question with a different failure:
+ * crushing a blind probe's weight would make the bounce darker than the room, and the reference
+ * this is checked against — `indirect-parity.mjs` — enters the chain with `visibility: null` for
+ * exactly this reason.
+ *
+ * The accessor an including module must define, before including the core:
+ *
+ * ```wgsl
+ * fn probeLayerSample(layer: u32, uv: vec2<f32>) -> vec3<f32>       // at the radiance level
+ * fn probeLayerIrradiance(layer: u32, uv: vec2<f32>) -> vec3<f32>   // at the irradiance level
+ * ```
+ *
+ * and `volume: ProbeVolume` as a uniform. Production samples a texture; the parity module reads a
+ * plain buffer of the same numbers.
+ */
+/**
+ * Floats in the volume block, and where each field starts.
+ *
+ * Named offsets for the reason `probeBake.wgsl.ts` gives and paid for: an `f32` after a `vec3<f32>`
+ * fills the vec3's padding rather than starting a new row, so `edge` is float **11**.
+ */
+export const VOLUME_ORIGIN = 0;
+export const VOLUME_INV_SPACING = 4;
+export const VOLUME_COUNTS = 8;
+export const VOLUME_EDGE = 11;
+export const VOLUME_LEVEL = 12;
+export const VOLUME_RADIANCE_EDGE = 13;
+export const VOLUME_RADIANCE_LEVEL = 14;
+/** Fifty-two bytes of fields rounded up to the struct's own sixteen-byte alignment. */
+export const PROBE_VOLUME_FLOATS = 16;
+export const PROBE_VOLUME_STRUCT_WGSL = /* wgsl */ `
+struct ProbeVolume {
+  /* Where the grid's first probe stands, and one over the step between them. */
+  origin: vec3<f32>,
+  invSpacing: vec3<f32>,
+  /* How many probes along each axis. Whole numbers carried as floats. */
+  counts: vec3<f32>,
+  /* Texels across the level being sampled, gutter included. */
+  edge: f32,
+  /* Which mip of the probe array that level is. */
+  level: f32,
+  /* And the level that holds *radiance* rather than irradiance, with its own edge. */
+  radianceEdge: f32,
+  radianceLevel: f32,
+  padA: f32,
+}
+`;
+export const PROBE_VOLUME_CORE_WGSL = /* wgsl */ `
+/* The octahedral encode, matching "octEncode" in "shaders/octahedral.ts". */
+fn probeOctEncode(d: vec3<f32>) -> vec2<f32> {
+  let n = d / (abs(d.x) + abs(d.y) + abs(d.z));
+  var p = n.xy;
+  if (n.z < 0.0) {
+    p = (1.0 - abs(vec2<f32>(n.y, n.x))) *
+      vec2<f32>(select(-1.0, 1.0, n.x >= 0.0), select(-1.0, 1.0, n.y >= 0.0));
+  }
+  return p * 0.5 + 0.5;
+}
+
+/*
+ * Where to sample a direction in a map whose outer ring is a gutter.
+ *
+ * The inner region is "edge - 2" texels offset by one, so a direction at the very border of the
+ * octahedral square lands on the last real texel and the tap that interpolates past it reads the
+ * gutter — which the bake filled with the folded direction.
+ */
+fn probeOctInsetUv(d: vec3<f32>, edge: f32) -> vec2<f32> {
+  return (probeOctEncode(d) * (edge - 2.0) + 1.0) / edge;
+}
+
+/*
+ * One axis of the lookup: which probe is below the point, and how far past it the point is.
+ *
+ * **The index is integer arithmetic and the fraction is not**, which is the distinction row 139 of
+ * the resume file is about. A world position divided by a spacing is a genuine float division and
+ * its floor is a genuine floor; what must never be written in floats is a *lattice* — an index
+ * decomposed out of a layer number — because a device may implement that division as a
+ * multiplication by a reciprocal and answer 3 for 3.0 % 3.0.
+ *
+ * The lower index stops one short of the last probe so the pair "index" and "index + 1" is always
+ * inside the grid, and a single-probe axis has no pair at all — both corners are probe zero and
+ * the fraction is zero, so that axis multiplies every weight by one.
+ */
+struct ProbeCell {
+  index: u32,
+  fraction: f32,
+}
+
+fn probeCell(value: f32, origin: f32, invSpacing: f32, count: u32) -> ProbeCell {
+  var out: ProbeCell;
+  out.index = 0u;
+  out.fraction = 0.0;
+  if (count <= 1u) { return out; }
+  let local = (value - origin) * invSpacing;
+  let span = f32(count - 1u);
+  let clamped = clamp(local, 0.0, span);
+  let index = min(u32(floor(clamped)), count - 2u);
+  out.index = index;
+  out.fraction = clamped - f32(index);
+  return out;
+}
+
+/*
+ * The layer a probe at whole lattice coordinates occupies. x fastest, then y, then z.
+ *
+ * **Not clamped, and "ProbeGrid.layerAt" is** — the difference is who may call them. "layerAt" is a
+ * public method whose contract is that it accepts anything, so it clamps; this is reached from one
+ * place, under two guarantees that together make the clamp unreachable. "probeCell" returns an
+ * index no greater than "count - 2", so "index + 1" is inside; and on an axis only one probe wide
+ * it returns index 0 with fraction 0, so the far corner's weight is zero and the caller skips it
+ * before asking. A clamp here would be a line no perturbation can make fail, which this session
+ * has already had to remove twice.
+ */
+fn probeLayerAt(ix: u32, iy: u32, iz: u32, counts: vec3<u32>) -> u32 {
+  return ix + counts.x * (iy + counts.y * iz);
+}
+
+/*
+ * What has already bounced onto a surface facing the normal at a point, from the level this writes.
+ *
+ * **One shared direction, and that is right here where a per-corner one is right for radiance.**
+ * An irradiance map is indexed by the *normal of the surface being lit*, not by where the light
+ * came from, so every probe is asked the same question: what reaches a surface facing this way.
+ * Reading it at the level the bake writes is what closes the loop — the second bounce is the first
+ * one read back.
+ */
+fn probeVolumeIrradianceAt(p: vec3<f32>, n: vec3<f32>) -> vec3<f32> {
+  let counts = vec3<u32>(
+    max(1u, u32(volume.counts.x)),
+    max(1u, u32(volume.counts.y)),
+    max(1u, u32(volume.counts.z)),
+  );
+  let cx = probeCell(p.x, volume.origin.x, volume.invSpacing.x, counts.x);
+  let cy = probeCell(p.y, volume.origin.y, volume.invSpacing.y, counts.y);
+  let cz = probeCell(p.z, volume.origin.z, volume.invSpacing.z, counts.z);
+  let uv = probeOctInsetUv(n, volume.edge);
+
+  var sum = vec3<f32>(0.0);
+  for (var oz = 0u; oz < 2u; oz = oz + 1u) {
+    let wz = select(1.0 - cz.fraction, cz.fraction, oz == 1u);
+    for (var oy = 0u; oy < 2u; oy = oy + 1u) {
+      let wy = select(1.0 - cy.fraction, cy.fraction, oy == 1u);
+      for (var ox = 0u; ox < 2u; ox = ox + 1u) {
+        let wx = select(1.0 - cx.fraction, cx.fraction, ox == 1u);
+        let weight = wx * wy * wz;
+        if (weight <= 0.0) { continue; }
+        let layer = probeLayerAt(cx.index + ox, cy.index + oy, cz.index + oz, counts);
+        sum = sum + probeLayerIrradiance(layer, uv) * weight;
+      }
+    }
+  }
+  return sum;
+}
+
+/* Where a layer's probe stands, which a parallax read needs and the lattice above decides. */
+fn probeVolumeProbeAt(layer: u32, counts: vec3<u32>) -> vec3<f32> {
+  let x = layer % counts.x;
+  let y = (layer / counts.x) % counts.y;
+  let z = layer / (counts.x * counts.y);
+  let spacing = vec3<f32>(
+    select(0.0, 1.0 / volume.invSpacing.x, volume.invSpacing.x != 0.0),
+    select(0.0, 1.0 / volume.invSpacing.y, volume.invSpacing.y != 0.0),
+    select(0.0, 1.0 / volume.invSpacing.z, volume.invSpacing.z != 0.0),
+  );
+  return volume.origin + vec3<f32>(f32(x), f32(y), f32(z)) * spacing;
+}
+
+/*
+ * The radiance leaving a world point, as the grid saw it.
+ *
+ * **A ray needs radiance and the first version read irradiance**, which is what
+ * "demo/dev/bounce.html" measured as a bounce dimmer and greyer than the rasterised grid it was
+ * meant to replace. Irradiance is light *arriving* at a point, already cosine-convolved over a
+ * hemisphere; what a ray that struck a wall needs is the light *leaving* that wall towards it. The
+ * two differ by the surface's albedo — so a red wall and a white wall at the same irradiance
+ * returned the same colour, and the red never travelled.
+ *
+ * **Level 0 of the probe array is that radiance**, and it needs no albedo because it is a
+ * rasterised capture of the shaded room: the red wall is red in it. §6.4 of the design names
+ * "envProbeArray.ts" as this track's starting point and leaves how much of it to reuse to
+ * measurement, which is this.
+ *
+ * **Each corner is read along its own direction to the point**, which is what makes this a
+ * position lookup rather than a direction one. Eight probes sampled along one shared direction
+ * answer "what is over there from roughly here"; eight probes each sampled towards "p" answer
+ * "what is at "p"", and the difference is the parallax that a marched hit exists to provide. It is
+ * also why no direction is passed in: deriving it removes the reversed-direction mistake that
+ * "probe-bake-parity.mjs" records being unable to see.
+ */
+fn probeVolumeRadianceAt(p: vec3<f32>) -> vec3<f32> {
+  let counts = vec3<u32>(
+    max(1u, u32(volume.counts.x)),
+    max(1u, u32(volume.counts.y)),
+    max(1u, u32(volume.counts.z)),
+  );
+  let cx = probeCell(p.x, volume.origin.x, volume.invSpacing.x, counts.x);
+  let cy = probeCell(p.y, volume.origin.y, volume.invSpacing.y, counts.y);
+  let cz = probeCell(p.z, volume.origin.z, volume.invSpacing.z, counts.z);
+
+  var sum = vec3<f32>(0.0);
+  for (var oz = 0u; oz < 2u; oz = oz + 1u) {
+    let wz = select(1.0 - cz.fraction, cz.fraction, oz == 1u);
+    for (var oy = 0u; oy < 2u; oy = oy + 1u) {
+      let wy = select(1.0 - cy.fraction, cy.fraction, oy == 1u);
+      for (var ox = 0u; ox < 2u; ox = ox + 1u) {
+        let wx = select(1.0 - cx.fraction, cx.fraction, ox == 1u);
+        let weight = wx * wy * wz;
+        if (weight <= 0.0) { continue; }
+        let layer = probeLayerAt(cx.index + ox, cy.index + oy, cz.index + oz, counts);
+        /*
+         * From that probe towards the point, which is the parallax. A probe standing exactly on
+         * the point has no direction to offer and takes its own zeroth texel, which is as good an
+         * answer as exists for a point inside a probe.
+         */
+        let offset = p - probeVolumeProbeAt(layer, counts);
+        let reach = length(offset);
+        let towards = select(vec3<f32>(0.0, 0.0, 1.0), offset / reach, reach > 0.0);
+        let uv = probeOctInsetUv(towards, volume.radianceEdge);
+        sum = sum + probeLayerSample(layer, uv) * weight;
+      }
+    }
+  }
+  return sum;
+}
+`;