@driftengine/core 3.63.0 → 4.1.0

package/dist/render/gpudriven/instances.js

@@ -0,0 +1,172 @@
+/**
+ * Whole meshes out of view, dropped before anything reads their clusters.
+ *
+ * **An instance here is a mesh**: every cluster names one through `meshOf`, and the raster and the
+ * shading both place it by `transforms[mesh]`. A mesh wholly outside the view has nothing to
+ * contribute to the frame, and before this every one of its clusters was still cut, tested against
+ * six planes and a cone, and occlusion-tested in phase two — correct, and the cost this stage
+ * removes.
+ *
+ * **The flag is read by the cut**, `LOD_CUT_WGSL`, because that is the one per-cluster stage with
+ * room for it: the cluster cull binds seven storage buffers and the compaction seven, of the eight a
+ * stage may bind by default, and the lookup needs two more (the flags and the cluster's mesh). A
+ * cluster the cut does not select is one the cluster cull then skips without testing and the
+ * compaction never lists — so a hidden mesh costs a lookup per cluster, and so does every cluster
+ * at a level the cut did not choose, which used to be tested for nothing.
+ *
+ * **The spheres are fitted once, at upload**, from the clusters' world spheres `clusterWorld.ts`
+ * already produced, for the reason that file gives: this pipeline's geometry does not move.
+ */
+import { CLUSTER_CULL_FLOATS } from './cullClusters.js';
+import { sphereOutsideFrustum } from './frustum.js';
+import { clusterSelected } from './lodCut.js';
+/** Four floats a mesh: world centre and radius. `CULL_INSTANCES_WGSL` reads this stride. */
+export const INSTANCE_FLOATS = 4;
+/** What the instance cull writes for a mesh wholly outside the view. Zero is everything else. */
+export const INSTANCE_HIDDEN = 1;
+/** Four words a cluster in the uploaded meta: index offset, index count, identifier, mesh. */
+export const CLUSTER_META_WORDS = 4;
+const META_MESH = 3;
+/** Six floats a cluster in the cut's input, as `clusterWorld.ts` lays out `lod`. */
+const LOD_FLOATS = 6;
+/**
+ * Each mesh's world bounding sphere, from the world spheres of its clusters.
+ *
+ * **Held to the numbers the device reads.** The centre is the middle of the clusters' box, stored
+ * in single precision first; the radius is then measured from the *stored* centre and rounded up,
+ * never to nearest — a sphere rounded the wrong way is a few parts in ten million short of a
+ * cluster's far edge, and a cull that is not conservative is a hole in the picture.
+ *
+ * A mesh no cluster names is a point at the origin, which draws nothing whatever the cull says. A
+ * cluster naming a mesh past `meshCount` is refused: it would be bounded by nothing and drawn by a
+ * transform that does not exist.
+ */
+export function instanceBounds(cull, meshOf, count, meshCount) {
+    const low = new Float64Array(meshCount * 3).fill(Infinity);
+    const high = new Float64Array(meshCount * 3).fill(-Infinity);
+    for (let c = 0; c < count; c += 1) {
+        const mesh = meshOf[c];
+        if (!(mesh < meshCount)) {
+            throw new RangeError(`instanceBounds: cluster ${String(c)} names mesh ${String(mesh)} and the scene has ${String(meshCount)} meshes`);
+        }
+        const at = c * CLUSTER_CULL_FLOATS;
+        const radius = cull[at + 3];
+        for (let axis = 0; axis < 3; axis += 1) {
+            const centre = cull[at + axis];
+            low[mesh * 3 + axis] = Math.min(low[mesh * 3 + axis], centre - radius);
+            high[mesh * 3 + axis] = Math.max(high[mesh * 3 + axis], centre + radius);
+        }
+    }
+    const out = new Float32Array(meshCount * INSTANCE_FLOATS);
+    for (let mesh = 0; mesh < meshCount; mesh += 1) {
+        if (!(low[mesh * 3] <= high[mesh * 3]))
+            continue;
+        for (let axis = 0; axis < 3; axis += 1) {
+            out[mesh * INSTANCE_FLOATS + axis] =
+                (low[mesh * 3 + axis] + high[mesh * 3 + axis]) / 2;
+        }
+    }
+    const reach = new Float64Array(meshCount);
+    for (let c = 0; c < count; c += 1) {
+        const mesh = meshOf[c];
+        const at = c * CLUSTER_CULL_FLOATS;
+        const from = mesh * INSTANCE_FLOATS;
+        const distance = Math.hypot(cull[at] - out[from], cull[at + 1] - out[from + 1], cull[at + 2] - out[from + 2]);
+        reach[mesh] = Math.max(reach[mesh], distance + cull[at + 3]);
+    }
+    for (let mesh = 0; mesh < meshCount; mesh += 1) {
+        const wanted = reach[mesh];
+        let radius = Math.fround(wanted);
+        /* Up, not to nearest: one step past the rounding is the smallest sphere that still holds. */
+        if (radius < wanted)
+            radius = Math.fround(wanted * (1 + 2 ** -23));
+        out[mesh * INSTANCE_FLOATS + 3] = radius;
+    }
+    return out;
+}
+/**
+ * One mesh's bounding sphere, from a contiguous run of its clusters' world bounds.
+ *
+ * **A run rather than a `meshOf` scan, because a streamed mesh's clusters are contiguous by
+ * construction** — the allocator hands out a range — so the scan `instanceBounds` does is work a
+ * streaming caller has already done.
+ *
+ * **A mesh with no clusters gets a sphere of zero radius rather than an empty box's arithmetic.**
+ * `Infinity - (-Infinity)` is `-Infinity`, and every comparison against `NaN` is false, which
+ * reads as a mesh that is never culled rather than one that is never drawn.
+ *
+ * The two forms must agree, and `instances.test.ts` is what holds them to it.
+ */
+export function instanceSphereInto(cull, from, count, out, at) {
+    const base = at * INSTANCE_FLOATS;
+    if (count <= 0) {
+        out[base] = 0;
+        out[base + 1] = 0;
+        out[base + 2] = 0;
+        out[base + 3] = 0;
+        return;
+    }
+    const low = [Infinity, Infinity, Infinity];
+    const high = [-Infinity, -Infinity, -Infinity];
+    for (let c = from; c < from + count; c += 1) {
+        const record = c * CLUSTER_CULL_FLOATS;
+        const radius = cull[record + 3];
+        for (let axis = 0; axis < 3; axis += 1) {
+            const centre = cull[record + axis];
+            low[axis] = Math.min(low[axis], centre - radius);
+            high[axis] = Math.max(high[axis], centre + radius);
+        }
+    }
+    for (let axis = 0; axis < 3; axis += 1) {
+        out[base + axis] = (low[axis] + high[axis]) / 2;
+    }
+    /* The reach from that centre, which is what makes the sphere hold every cluster rather than
+       every corner of the box — the same second pass `instanceBounds` makes, for the same reason. */
+    let reach = 0;
+    for (let c = from; c < from + count; c += 1) {
+        const record = c * CLUSTER_CULL_FLOATS;
+        const distance = Math.hypot(cull[record] - out[base], cull[record + 1] - out[base + 1], cull[record + 2] - out[base + 2]);
+        reach = Math.max(reach, distance + cull[record + 3]);
+    }
+    let radius = Math.fround(reach);
+    /* Up, not to nearest: one step past the rounding is the smallest sphere that still holds. */
+    if (radius < reach)
+        radius = Math.fround(reach * (1 + 2 ** -23));
+    out[base + 3] = radius;
+}
+/**
+ * One flag a mesh: `INSTANCE_HIDDEN` where its sphere is wholly outside the view. Returns how many
+ * are. Mirrors `CULL_INSTANCES_WGSL`, which `gpu-parity.mjs` holds to `sphereOutsideFrustum`.
+ */
+export function cullInstances(planes, spheres, count, out) {
+    let hidden = 0;
+    for (let i = 0; i < count; i += 1) {
+        const at = i * INSTANCE_FLOATS;
+        const outside = sphereOutsideFrustum(planes, spheres[at], spheres[at + 1], spheres[at + 2], spheres[at + 3]);
+        out[i] = outside ? INSTANCE_HIDDEN : 0;
+        if (outside)
+            hidden += 1;
+    }
+    return hidden;
+}
+/**
+ * The cut, over every cluster, with the instance flags applied first: one flag a cluster, and how
+ * many were selected. Mirrors `LOD_CUT_WGSL`.
+ */
+export function selectClusters(lod, meta, hidden, screenHeight, fovY, thresholdPixels, eyeX, eyeY, eyeZ, out) {
+    const count = Math.floor(lod.length / LOD_FLOATS);
+    let chosen = 0;
+    for (let i = 0; i < count; i += 1) {
+        const mesh = meta[i * CLUSTER_META_WORDS + META_MESH];
+        if ((hidden[mesh] ?? 0) !== 0) {
+            out[i] = 0;
+            continue;
+        }
+        const at = i * LOD_FLOATS;
+        const selected = clusterSelected(lod[at + 4], lod[at + 5], Math.hypot(lod[at] - eyeX, lod[at + 1] - eyeY, lod[at + 2] - eyeZ), lod[at + 3], screenHeight, fovY, thresholdPixels);
+        out[i] = selected ? 1 : 0;
+        if (selected)
+            chosen += 1;
+    }
+    return chosen;
+}

package/dist/render/gpudriven/lit.d.ts

@@ -0,0 +1,165 @@
+/** What the second pipeline's shading pass computes, in TypeScript, so something can disagree. */
+/**
+ * **The lit expression had no reference until 2026-09-16, and that was a gap rather than a policy.**
+ *
+ * `shadeBins.ts` is the reference for the *reconstruction* — screen vertices, perspective-correct
+ * weights, their gradients — and `gpu-parity.mjs` runs it against `SHADE_SURFACE_WGSL` over
+ * generated triangles. The shading pass's header gives the reason and it is a good one: the
+ * interpolation is the only part that differs between the two pipelines, so it is the only part
+ * that can drift.
+ *
+ * That argument holds for a lit expression of four lines. It stops holding the moment the
+ * expression grows a term, and it was never an argument for having *no* reference: nothing in the
+ * tree computed what the shader computed, so nothing could disagree with it. The forward path's own
+ * expression is GLSL and cannot be compared to WGSL by reading them side by side.
+ *
+ * **This is the twin, and it is deliberately not the forward path's whole material.** What the
+ * second pipeline draws is still a subset — no texture, so every property a texel could vary is a
+ * per-material constant — and every term that *is* here matches `flat/main.ts` exactly. Stating
+ * the subset is the point; discovering it from a capture is what this repository keeps refusing.
+ */
+/** A surface, after the visibility buffer has been turned back into one. */
+export interface LitSurface {
+    /** Vertex colour times the material's tint. */
+    readonly albedo: readonly [number, number, number];
+    /** Unit length, in world space. */
+    readonly normal: readonly [number, number, number];
+    /** Unit length, from the surface toward the eye. */
+    readonly toEye: readonly [number, number, number];
+    /** 0 is a mirror, 1 is fully rough. */
+    readonly roughness: number;
+    /** How much of the light the surface returns as a highlight. Zero for a matte one. */
+    readonly specular: number;
+    /** Added as `emissiveColour * emissive`, which is `albedo * emissive` where no map says otherwise. */
+    readonly emissive: number;
+    /**
+     * What the glow is coloured by: flat/main.ts's `emissiveTint * emissiveMapped`, the albedo times
+     * an emissive map. **Defaults to the albedo**, so a surface with no map glows exactly as it did —
+     * and it reaches the glow and nothing else, because a map says where light is emitted rather than
+     * what the surface is made of.
+     */
+    readonly emissiveColour?: readonly [number, number, number];
+    /**
+     * How much of the environment the surface returns, before the angle and the roughness are
+     * accounted for. **Defaults to 0**, so a material that says nothing reflects nothing.
+     */
+    readonly reflectivity?: number;
+    /**
+     * How much of the directional source reaches this surface: 0 in full shadow, 1 in full light.
+     *
+     * **Applied to the diffuse term and the highlight, and to nothing else**, which is where
+     * `flat/main.ts` puts its own `sunShade`. Its comment records what applying it more widely costs:
+     * scale the ambient too and an enclosed face is darkened once for having no sun and again for the
+     * light it should still have received, which a consumer answered by raising a floor constant and
+     * losing the contrast permanently.
+     *
+     * **Defaults to 1**, so a caller that says nothing about occlusion renders exactly the frame this
+     * pipeline rendered before it had a shadow map — the same promise `roughness` and `specular`
+     * make.
+     */
+    readonly shade?: number;
+    /**
+     * 0 is a dielectric and 1 is a metal. **Defaults to 0.**
+     *
+     * `flat/main.ts` reads this per texel from the blue channel of an occlusion-roughness-metallic
+     * image; this pipeline has no textures, so it is one number a material. That is the whole of the
+     * difference — every expression it enters is the forward path's with a constant standing in for
+     * a fetch — and it is four of them: the direct diffuse it removes, the colour it gives the
+     * highlight, the side of the environment blend the highlight is added on, and the `f0` and the
+     * amount `ibl.ts` builds the weight from.
+     */
+    readonly metalness?: number;
+    /**
+     * How much of the surface's light a crevice leaves, from an ORM map's red channel. **Defaults
+     * to 1.**
+     *
+     * **It multiplies the whole result**, highlight, reflection and emissive included, because that
+     * is what `flat/main.ts` does — `lit *= ormOcclusion` — and its comment records the narrower
+     * reading as considered and not taken, with the double count against a cast shadow as the
+     * stated cost.
+     */
+    readonly occlusion?: number;
+}
+/** The frame's one directional light and its hemispheric fill. */
+export interface LitEnvironment {
+    /** Toward the light, unit length, as `Environment.directionalDir` is. */
+    readonly lightDir: readonly [number, number, number];
+    readonly lightColour: readonly [number, number, number];
+    readonly sky: readonly [number, number, number];
+    readonly ground: readonly [number, number, number];
+    /**
+     * The room's diffuse light in the surface's own direction, from a cosine-convolved level.
+     *
+     * **It replaces the hemispheric gradient rather than lifting it**, by `irradianceAmount`, which
+     * is what `flat/main.ts` does and what its own comment records the alternative costing: a mix
+     * *toward* a coarse box-filtered level is a sample of the room rather than an integral over it,
+     * and it rendered a night courtyard black.
+     */
+    readonly irradiance?: readonly [number, number, number];
+    /** How much of the gradient the irradiance replaces. **Defaults to 0**, which keeps it. */
+    readonly irradianceAmount?: number;
+    /**
+     * What the surface sees in the mirror direction, from the chain at its own roughness.
+     *
+     * **It replaces a hemispheric gradient rather than standing alone**, by `radianceAmount`, and the
+     * default matters more here than anywhere else in this interface: a metal's environment weight is
+     * exactly 1 at every angle and every roughness, so a metal with nothing to reflect is **black**.
+     * The gradient is what `flat/main.ts` reflects where a scene has no probe, and computing it here
+     * rather than in the caller is what stops that being something a caller can forget.
+     */
+    readonly radiance?: readonly [number, number, number];
+    /**
+     * How much of the gradient the radiance replaces. **Defaults to 0**, which keeps the gradient —
+     * the same shape and the same default as `irradianceAmount`.
+     */
+    readonly radianceAmount?: number;
+    /**
+     * Whether that radiance came from a GGX-convolved chain. **Defaults to 0.**
+     *
+     * The split sum is the correct share of a *prefiltered* environment and asserts an integral that
+     * was never performed over anything else — `ibl.ts` carries what ignoring that costs.
+     */
+    readonly prefiltered?: number;
+    /**
+     * The frame's emissive gain times its night factor. **Defaults to 1.**
+     *
+     * `flat/main.ts` scales every glow by `uEmissiveGain * uNightFactor`, so a scene whose clock says
+     * it is day has nothing glowing on the forward path. This pipeline added `albedo * emissive` and
+     * nothing else until 2026-09-17, which is a rig that glowed on one pipeline and not the other.
+     */
+    readonly emission?: number;
+}
+/**
+ * How much of the sky a normal sees, against how much of the ground.
+ *
+ * `n.y * 0.5 + 0.5`, which is `flat/main.ts`'s own. Named rather than inlined because two
+ * pipelines disagreeing about it is two pipelines lighting one scene differently, with nothing on
+ * screen to say which is right.
+ */
+export declare function HEMISPHERIC(ny: number): number;
+/**
+ * The normalised GGX distribution, transcribed from `flat/lobes.ts`.
+ *
+ * **It peaks at one whatever the roughness**, and that is what makes a widened lobe broader rather
+ * than brighter — `lobes.ts` records paying for the version that did not. The floor on `a` is what
+ * keeps a mirror from dividing by nothing.
+ */
+export declare function specularLobe(ndh: number, roughness: number): number;
+export declare function newLitColour(): Float32Array;
+/**
+ * The colour the second pipeline writes for one reconstructed surface.
+ *
+ * **The highlight is added on both sides of the environment blend, and which side carries how much
+ * is metalness.** `flat/main.ts` writes it as two lines with the blend between them, and its
+ * comments carry what each is for. The dielectric's share goes in *underneath*, where the blend
+ * dims it by the surface's own reflectance — moving it out "takes a lobe that was correctly dimmed
+ * and puts it back at full strength", which on a near-black glass lens carrying `specular` 1 is a
+ * white blob where there was none. The metal's share goes *over the top*, because on a metal the
+ * blend reaches 1 and a highlight left underneath is multiplied by exactly zero: the surface with
+ * the most reason to show a specular streak is the one guaranteed not to.
+ *
+ * **This file had both shares on the outside until 2026-09-17** and cited the metal argument for
+ * it. Nothing caught it: no material in any rig carries a `specular` and a `reflectivity` at once,
+ * so the two orders had never been asked to differ.
+ */
+export declare function litColour(surface: LitSurface, environment: LitEnvironment, out: Float32Array): Float32Array;

package/dist/render/gpudriven/lit.js

@@ -0,0 +1,165 @@
+/** What the second pipeline's shading pass computes, in TypeScript, so something can disagree. */
+import { EMISSIVE_SHADOW_SHARE, MIN_LOBE_ALPHA } from '../shaders/flat/lobes.js';
+import { environmentWeight } from './ibl.js';
+/**
+ * How much of the sky a normal sees, against how much of the ground.
+ *
+ * `n.y * 0.5 + 0.5`, which is `flat/main.ts`'s own. Named rather than inlined because two
+ * pipelines disagreeing about it is two pipelines lighting one scene differently, with nothing on
+ * screen to say which is right.
+ */
+export function HEMISPHERIC(ny) {
+    return ny * 0.5 + 0.5;
+}
+/**
+ * The normalised GGX distribution, transcribed from `flat/lobes.ts`.
+ *
+ * **It peaks at one whatever the roughness**, and that is what makes a widened lobe broader rather
+ * than brighter — `lobes.ts` records paying for the version that did not. The floor on `a` is what
+ * keeps a mirror from dividing by nothing.
+ */
+/*
+ * **Two floors, and only one of them can be seen in the output.** The denominator's is what keeps
+ * a near-mirror's peak finite, and deleting it is worth 256 times the highlight at roughness 0.05 —
+ * `gpu-parity.mjs` catches that, now that a fifth of its corpus sits on the peak. The floor on `a`
+ * cannot be caught, because the denominator's already prevents the division by zero it guards
+ * against: at roughness zero the whole term is a ten-thousandth with it and zero without, and both
+ * round to nothing beside a lit surface. It is kept because it is what `flat/lobes.ts` has, and two
+ * spellings of one lobe differing by a guard is the drift this pair exists to prevent.
+ */
+export function specularLobe(ndh, roughness) {
+    const a = Math.max(roughness * roughness, MIN_LOBE_ALPHA);
+    const a2 = a * a;
+    const d = ndh * ndh * (a2 - 1) + 1;
+    return (a2 * a2) / Math.max(d * d, 1e-8);
+}
+export function newLitColour() {
+    return new Float32Array(3);
+}
+/** Scratch, because this is per pixel in the reference as well as on the device. */
+const HALFWAY = new Float32Array(3);
+/**
+ * The colour the second pipeline writes for one reconstructed surface.
+ *
+ * **The highlight is added on both sides of the environment blend, and which side carries how much
+ * is metalness.** `flat/main.ts` writes it as two lines with the blend between them, and its
+ * comments carry what each is for. The dielectric's share goes in *underneath*, where the blend
+ * dims it by the surface's own reflectance — moving it out "takes a lobe that was correctly dimmed
+ * and puts it back at full strength", which on a near-black glass lens carrying `specular` 1 is a
+ * white blob where there was none. The metal's share goes *over the top*, because on a metal the
+ * blend reaches 1 and a highlight left underneath is multiplied by exactly zero: the surface with
+ * the most reason to show a specular streak is the one guaranteed not to.
+ *
+ * **This file had both shares on the outside until 2026-09-17** and cited the metal argument for
+ * it. Nothing caught it: no material in any rig carries a `specular` and a `reflectivity` at once,
+ * so the two orders had never been asked to differ.
+ */
+export function litColour(surface, environment, out) {
+    const [nx, ny, nz] = surface.normal;
+    const [lx, ly, lz] = environment.lightDir;
+    const ndl = Math.max(nx * lx + ny * ly + nz * lz, 0);
+    const fill = HEMISPHERIC(ny);
+    /* The half vector between the light and the eye, which is where a highlight is brightest. */
+    HALFWAY[0] = lx + surface.toEye[0];
+    HALFWAY[1] = ly + surface.toEye[1];
+    HALFWAY[2] = lz + surface.toEye[2];
+    const length = Math.hypot(HALFWAY[0], HALFWAY[1], HALFWAY[2]);
+    let ndh = 0;
+    let voh = 0;
+    if (length > 0) {
+        ndh = Math.max((nx * HALFWAY[0] + ny * HALFWAY[1] + nz * HALFWAY[2]) /
+            length, 0);
+        voh = Math.max((surface.toEye[0] * HALFWAY[0] +
+            surface.toEye[1] * HALFWAY[1] +
+            surface.toEye[2] * HALFWAY[2]) /
+            length, 0);
+    }
+    /*
+     * **Computed whether or not the surface is shiny, and multiplied by zero where it is not.** A
+     * branch on a material's specular would be a branch on a value read from a table, which is what
+     * the shading pass's own header refuses for the same reason the forward path does: it is not
+     * provably uniform control flow.
+     */
+    const lobe = specularLobe(ndh, surface.roughness);
+    /* One number for both direct terms: the sun being occluded is one fact about one source. */
+    const shade = surface.shade ?? 1;
+    const metal = surface.metalness ?? 0;
+    const occlusion = surface.occlusion ?? 1;
+    /*
+     * **A glow is scaled by the frame and dimmed by a share of the sun's shadow**, which is
+     * flat/main.ts's `mix(1, min(lightShade, sunShade), EMISSIVE_SHADOW_SHARE)` with no lamps: a lit
+     * inlay in a deck that is itself in shade, rather than a lamp head blacked out by a passer-by.
+     */
+    const glow = surface.emissive * (environment.emission ?? 1) * (1 + (shade - 1) * EMISSIVE_SHADOW_SHARE);
+    /*
+     * **A metal's highlight goes white at a grazing angle, and that is most of what reads as
+     * polished.** Schlick's reflectance climbs to 1 at the edge whatever the material is, so a red
+     * metal shows a red highlight face-on and a white one along every panel edge. Scaled by
+     * metalness, so `specColour + (1 - specColour) * 0` is `specColour` exactly on a dielectric.
+     */
+    const facing = 1 - voh;
+    const edge = facing * facing * facing * facing * facing * metal;
+    /*
+     * **How much of the room the surface returns, computed once rather than per channel.** It is a
+     * function of the angle, the roughness and the material alone — `ibl.ts` carries both halves of
+     * the split sum and why the selector between them is exactly 0 or exactly 1.
+     */
+    const nv = nx * surface.toEye[0] +
+        ny * surface.toEye[1] +
+        nz * surface.toEye[2];
+    const ndv = Math.max(nv, 0);
+    const weight = environmentWeight(ndv, surface.roughness, surface.reflectivity ?? 0, environment.prefiltered ?? 0, metal);
+    const irradianceAmount = environment.irradianceAmount ?? 0;
+    const radianceAmount = environment.radianceAmount ?? 0;
+    /*
+     * **The mirror direction, and what a surface sees along it with no probe bound.** `reflect(-v, n)`
+     * written out: the two-colour gradient the ambient comes from, sampled in the direction the
+     * surface is reflecting rather than the one it faces. That distinction is the whole of what makes
+     * a curved dielectric read as curved with no environment in the scene at all.
+     *
+     * **The unclamped dot, not `ndv`.** `reflect` takes the facing term as it is; clamping it at zero
+     * would fold the mirror direction back on itself for a surface seen from behind — which happens
+     * on every silhouette where interpolated normals turn past the eye — and reflect the sky where
+     * the ground belongs. The weight below clamps because a negative Fresnel is not a reflectance;
+     * the two uses are different questions about one dot product.
+     */
+    const mirroredY = 2 * nv * ny - surface.toEye[1];
+    for (let channel = 0; channel < 3; channel += 1) {
+        const albedo = surface.albedo[channel];
+        const hemispheric = environment.ground[channel] +
+            (environment.sky[channel] - environment.ground[channel]) * fill;
+        const room = environment.irradiance?.[channel] ?? 0;
+        const ambient = hemispheric + (room - hemispheric) * irradianceAmount;
+        /*
+         * **A metal's highlight takes its own colour and a dielectric's takes the light's**, which is
+         * why gold under a white lamp reads as gold rather than as beige plastic with a white dot on
+         * it. `specular` is this engine's dielectric reflectance — a look control rather than an `f0` —
+         * so the blend runs from it to the albedo rather than from 0.04.
+         */
+        const specColour = surface.specular + (albedo - surface.specular) * metal;
+        const sunSpec = specColour + (1 - specColour) * edge;
+        const highlight = environment.lightColour[channel] * lobe * sunSpec * shade;
+        /*
+         * **A metal keeps its ambient and loses its direct diffuse**, written as one term because the
+         * honest two cancel: a metal's reduced diffuse plus the ambient floor that stops a rough one
+         * going black once its diffuse is gone sum to `albedo * ambient` exactly.
+         */
+        const base = albedo *
+            (ambient + environment.lightColour[channel] * ndl * shade * (1 - metal)) +
+            highlight * (1 - metal);
+        /*
+         * **What a metal reflects is the room through itself**, which is the other half of "a metal is
+         * nothing but its reflection". `mix(1, albedo, 0)` is exactly 1, so a dielectric reflects the
+         * room's own colour as it always did.
+         */
+        const gradient = environment.ground[channel] +
+            (environment.sky[channel] - environment.ground[channel]) *
+                HEMISPHERIC(mirroredY);
+        const seen = gradient + ((environment.radiance?.[channel] ?? 0) - gradient) * radianceAmount;
+        const reflected = seen * (1 + (albedo - 1) * metal);
+        const glowColour = surface.emissiveColour?.[channel] ?? albedo;
+        out[channel] =
+            (base + (reflected - base) * weight + highlight * metal + glowColour * glow) * occlusion;
+    }
+    return out;
+}

package/dist/render/gpudriven/lodCut.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Choosing which level of the cluster graph to draw, per cluster, independently.
+ *
+ * **Independently is the whole point.** A cluster asks only about its own error and its parent's,
+ * never about its neighbours — and the graph's monotonic-error guarantee is what makes the result
+ * crack-free anyway. That is why this can run per cluster on the device with no communication.
+ *
+ * **Both halves of the rule are needed.** "Draw it if its own error is small enough" alone draws
+ * every ancestor as well; "draw it if its parent's error is too large" alone draws nothing at the
+ * root, where the parent error is infinite and therefore always too large — which is exactly the
+ * case that makes the coarsest level appear and never disappear.
+ */
+/**
+ * How large a geometric error appears on screen, in pixels.
+ *
+ * Distance is clamped below by the cluster's own radius, so a cluster the camera is inside reports
+ * an enormous error rather than dividing by something near zero — which is the difference between
+ * "always use the finest level here" and a non-finite number reaching a comparison.
+ */
+export declare function projectedError(error: number, distance: number, radius: number, screenHeight: number, fovY: number): number;
+export declare function distanceTo(cx: number, cy: number, cz: number, ex: number, ey: number, ez: number): number;
+/**
+ * Whether this cluster is the one to draw.
+ *
+ * True when its own error is acceptable and its parent's is not — see the header for why both
+ * halves are required.
+ */
+export declare function clusterSelected(ownError: number, parentError: number, distance: number, radius: number, screenHeight: number, fovY: number, thresholdPixels: number): boolean;

package/dist/render/gpudriven/lodCut.js

@@ -0,0 +1,38 @@
+/**
+ * Choosing which level of the cluster graph to draw, per cluster, independently.
+ *
+ * **Independently is the whole point.** A cluster asks only about its own error and its parent's,
+ * never about its neighbours — and the graph's monotonic-error guarantee is what makes the result
+ * crack-free anyway. That is why this can run per cluster on the device with no communication.
+ *
+ * **Both halves of the rule are needed.** "Draw it if its own error is small enough" alone draws
+ * every ancestor as well; "draw it if its parent's error is too large" alone draws nothing at the
+ * root, where the parent error is infinite and therefore always too large — which is exactly the
+ * case that makes the coarsest level appear and never disappear.
+ */
+/**
+ * How large a geometric error appears on screen, in pixels.
+ *
+ * Distance is clamped below by the cluster's own radius, so a cluster the camera is inside reports
+ * an enormous error rather than dividing by something near zero — which is the difference between
+ * "always use the finest level here" and a non-finite number reaching a comparison.
+ */
+export function projectedError(error, distance, radius, screenHeight, fovY) {
+    const safe = Math.max(distance, radius, 1e-4);
+    const scale = screenHeight / (2 * Math.tan(fovY / 2));
+    return (error * scale) / safe;
+}
+export function distanceTo(cx, cy, cz, ex, ey, ez) {
+    return Math.hypot(cx - ex, cy - ey, cz - ez);
+}
+/**
+ * Whether this cluster is the one to draw.
+ *
+ * True when its own error is acceptable and its parent's is not — see the header for why both
+ * halves are required.
+ */
+export function clusterSelected(ownError, parentError, distance, radius, screenHeight, fovY, thresholdPixels) {
+    const own = projectedError(ownError, distance, radius, screenHeight, fovY);
+    const parent = projectedError(parentError, distance, radius, screenHeight, fovY);
+    return own <= thresholdPixels && parent > thresholdPixels;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Grouping the frame's pixels by the material that has to shade them.
+ *
+ * **A visibility buffer defers the shading and does not organise it.** Neighbouring pixels can
+ * hold triangles from different meshes with different materials, so shading it in place means
+ * every invocation branching on a material it cannot know until it has read the buffer — which on
+ * a wide machine is every lane in a group taking every branch. Binning first turns that into one
+ * dispatch per material, each of which shades pixels that all want the same code.
+ *
+ * **A material with no pixels gets a zero-length bin and a zero-workgroup dispatch, never an
+ * absent one.** The arguments are indexed by material identifier, so dropping an empty one shifts
+ * every later material's block and the scene shades with the wrong code — a picture that is
+ * plausible, entirely wrong, and correlates with nothing a consumer changed. `binsPresent` is the
+ * separate question of how many materials actually appear, which is a number to report rather
+ * than a length to index by.
+ *
+ * **Offsets are a prefix sum and the cursors are a copy of it.** The scatter needs somewhere to
+ * count from that is not the offsets themselves, or the second pixel of a bin overwrites the
+ * first's offset and every later bin starts in the wrong place.
+ */
+/** Invocations a shading group covers. One pixel each; the bins are lists, not rectangles. */
+export declare const BIN_GROUP_SIZE = 64;
+/** Words in one material's dispatch block, so a caller can size the buffer. */
+export declare const BIN_DISPATCH_WORDS = 3;
+/**
+ * Which material a pixel wants, or -1 where nothing covered it.
+ *
+ * **The sentinel test survives perturbation and is kept**, which is worth the sentence because it
+ * looks like the load-bearing line and is not. `VIS_EMPTY` is `0xffffffff`, so its cluster field
+ * reads as 33,554,431 — and the range test one line down refuses any cluster past the table, which
+ * every real table is far smaller than. Deleting either check alone therefore changes no answer
+ * this repository can produce. What the sentinel test decides is a table sized to the full
+ * twenty-five bits, which is 134 MB and nothing allocates; what the range test decides is a
+ * visibility buffer left over from a frame with more geometry in it, which is a real case and is
+ * the one `gpu-parity.mjs` generates. Both are kept because they answer different questions and
+ * one of them is cheap insurance against the other's assumption.
+ */
+export declare function materialAt(visibility: Uint32Array, materialOf: Uint32Array, pixel: number): number;
+/**
+ * How many pixels each material owns, and how many pixels were covered at all.
+ *
+ * `counts` is cleared here rather than by the caller, because a count buffer reused across frames
+ * without clearing grows without bound and the bins then run off the end of the pixel list —
+ * which appears as the shading reading a neighbouring bin's pixels.
+ */
+export declare function countBins(visibility: Uint32Array, materialOf: Uint32Array, counts: Uint32Array): number;
+/** Where each material's pixels begin: the exclusive prefix sum of the counts. */
+export declare function binOffsets(counts: Uint32Array, offsets: Uint32Array): number;
+/**
+ * Write every covered pixel's index into its material's slice of `pixels`.
+ *
+ * `cursors` starts as a copy of `offsets` and is advanced as the scatter runs, so `offsets` stays
+ * readable afterwards — which the shading dispatch needs, because it is what tells a group where
+ * its material's list starts.
+ */
+export declare function fillBins(visibility: Uint32Array, materialOf: Uint32Array, offsets: Uint32Array, cursors: Uint32Array, pixels: Uint32Array): void;
+/** One dispatch block per **declared** material, zero groups where the bin is empty. */
+export declare function binDispatchArgs(counts: Uint32Array, out: Uint32Array, groupSize?: number): void;
+/** How many materials the frame actually contains, which is not how many it declares. */
+export declare function binsPresent(counts: Uint32Array): number;