@driftengine/core 3.61.0

package/dist/render/translucentQueue.d.ts

@@ -0,0 +1,76 @@
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { TranslucentMeshOptions } from './backend/webgl2/renderer.ts';
+/**
+ * The frame's translucent draws, held so they can be submitted more than once.
+ *
+ * **Order-independent transparency needs the same geometry in two passes** — one accumulating
+ * weighted colour, one multiplying revealage — and they are two blend states, which a single pass
+ * cannot hold without a second fragment output. Writing both from one pass would mean another
+ * `flatFrag` permutation, measured at about 247 KB gzipped and paid by every consumer whether or
+ * not they enable the effect. So the geometry is submitted twice instead, and this is what makes
+ * that possible in a renderer that otherwise draws immediately.
+ *
+ * **Everything a draw carries is copied, and that is the whole correctness of this file.** Callers
+ * build their model matrix into a scratch they reuse — `rings.ts` submits the same `Float32Array` a
+ * thousand times with different contents — so a queue holding the reference would replay every
+ * draw wearing the last transform. That is a plausible picture rather than an obviously broken
+ * one, which is the kind that gets blamed on the blending.
+ *
+ * **Records are pooled and never released.** A translucent set is submitted every frame and
+ * `AGENTS.md` forbids allocating in the frame loop, so `reset` returns the count to zero and keeps
+ * the storage: a steady scene allocates on its first frame and never again.
+ */
+/** One recorded draw. The fields are the arguments `drawTranslucentMesh` was called with. */
+export interface TranslucentDraw {
+    /** The mesh handle, held by reference — the caller does not rebuild one per frame. */
+    mesh: unknown;
+    /** A copy, for the reason this file exists. */
+    readonly model: Float32Array;
+    opacity: number;
+    lit: boolean;
+    fog: boolean;
+    toneMapped: boolean;
+    depthWrite: boolean;
+    depthLayer: number;
+    /** Null where the draw asked for no tint; otherwise a copy, like the matrix. */
+    tint: Float32Array | null;
+    /**
+     * How far this draw bends what is behind it, 0 for not at all.
+     *
+     * **Carried rather than dropped, and that is what this field is for.** Order-independent
+     * transparency replays this set twice; a queue that forgot these would give a pane that refracts
+     * under sorted blending and stands clear under OIT, which reads as a bug in the transparency
+     * mode rather than as a queue that lost a field.
+     */
+    refraction: number;
+    /** What survives one metre of the medium. Null where the draw named none; otherwise a copy. */
+    refractTint: Float32Array | null;
+    thicknessM: number;
+}
+export declare class TranslucentQueue {
+    private readonly pool;
+    private count;
+    /** How many draws this frame has recorded. */
+    get length(): number;
+    /** How many records are pooled, which a test uses to assert a steady scene stops allocating. */
+    get capacity(): number;
+    /**
+     * Take a copy of one draw.
+     *
+     * The defaults match `drawTranslucentMesh`'s own, so a queued draw and an immediate one are the
+     * same draw — a divergence here would be a scene that changes when the effect is switched on for
+     * reasons that have nothing to do with transparency.
+     */
+    record(mesh: unknown, model: ReadonlyMat4, opacity: number, options: TranslucentMeshOptions): void;
+    /**
+     * Walk what was recorded, in the order it arrived.
+     *
+     * **Walkable more than once**, which is the reason this exists: the accumulation and the
+     * revealage are two passes over the same set, and a queue that could only be drained once would
+     * give the second a different set from the first. Order is preserved for determinism rather than
+     * for correctness — the whole point of the effect is that the result does not depend on it.
+     */
+    replay(each: (draw: TranslucentDraw) => void): void;
+    /** Empty it for the next frame, keeping the storage. */
+    reset(): void;
+}

package/dist/render/translucentQueue.js

@@ -0,0 +1,90 @@
+function newRecord() {
+    return {
+        mesh: null,
+        model: new Float32Array(16),
+        opacity: 1,
+        lit: true,
+        fog: true,
+        toneMapped: true,
+        depthWrite: true,
+        depthLayer: 0,
+        tint: null,
+        tintStore: new Float32Array(3),
+        refraction: 0,
+        refractTint: null,
+        thicknessM: 0,
+        refractTintStore: new Float32Array(3),
+    };
+}
+export class TranslucentQueue {
+    pool = [];
+    count = 0;
+    /** How many draws this frame has recorded. */
+    get length() {
+        return this.count;
+    }
+    /** How many records are pooled, which a test uses to assert a steady scene stops allocating. */
+    get capacity() {
+        return this.pool.length;
+    }
+    /**
+     * Take a copy of one draw.
+     *
+     * The defaults match `drawTranslucentMesh`'s own, so a queued draw and an immediate one are the
+     * same draw — a divergence here would be a scene that changes when the effect is switched on for
+     * reasons that have nothing to do with transparency.
+     */
+    record(mesh, model, opacity, options) {
+        let record = this.pool[this.count];
+        if (record === undefined) {
+            record = newRecord();
+            this.pool.push(record);
+        }
+        record.mesh = mesh;
+        record.model.set(model);
+        record.opacity = Math.min(opacity, 1);
+        record.lit = options.lit ?? true;
+        record.fog = options.fog ?? true;
+        record.toneMapped = options.toneMapped ?? true;
+        record.depthWrite = options.depthWrite ?? true;
+        record.depthLayer = options.depthLayer ?? 0;
+        const tint = options.tint ?? null;
+        if (tint === null) {
+            record.tint = null;
+        }
+        else {
+            record.tintStore.set(tint);
+            record.tint = record.tintStore;
+        }
+        record.refraction = options.refraction ?? 0;
+        record.thicknessM = options.thicknessM ?? 0;
+        const refractTint = options.refractTint ?? null;
+        if (refractTint === null) {
+            record.refractTint = null;
+        }
+        else {
+            record.refractTintStore.set(refractTint);
+            record.refractTint = record.refractTintStore;
+        }
+        this.count++;
+    }
+    /**
+     * Walk what was recorded, in the order it arrived.
+     *
+     * **Walkable more than once**, which is the reason this exists: the accumulation and the
+     * revealage are two passes over the same set, and a queue that could only be drained once would
+     * give the second a different set from the first. Order is preserved for determinism rather than
+     * for correctness — the whole point of the effect is that the result does not depend on it.
+     */
+    replay(each) {
+        for (let i = 0; i < this.count; i++) {
+            const record = this.pool[i];
+            if (record !== undefined)
+                each(record);
+        }
+    }
+    /** Empty it for the next frame, keeping the storage. */
+    reset() {
+        this.count = 0;
+    }
+}

package/dist/render/uniformVectorBudget.d.ts

@@ -0,0 +1,105 @@
+/**
+ * How many lights a build of the lit shader declares room for.
+ *
+ * Two numbers rather than one because they buy different things and cost differently: a point
+ * light is ten uniform arrays with point shadows off and twenty with them on, a rectangle is six
+ * and fourteen. A scene with four lamps and one window wants a different pair from one with
+ * sixteen lamps and no windows, and until this existed neither could ask.
+ */
+export interface LightBudget {
+    /** Slots in every `uLight*` array, and the bound of the light loop. `MAX_LIGHTS` in the source. */
+    readonly maxLights: number;
+    /** Slots in every `uAreaLight*` array. `MAX_AREA_LIGHTS` in the source. */
+    readonly maxAreaLights: number;
+}
+/** What the engine declares when nobody says otherwise, and what the generated WGSL is built at. */
+export declare const FULL_LIGHT_BUDGET: LightBudget;
+/**
+ * What WebGL2 guarantees every conforming implementation offers a fragment shader.
+ *
+ * Not a number to design against on any particular device — a desktop part reports thousands and
+ * an Adreno 740 reports 256 — but the floor beneath all of them, and therefore the only number a
+ * budget can be called *reachable* against. `uniformVectorBudget.test.ts` asserts the ladder's
+ * last rung fits inside it with every feature still compiled in.
+ */
+export declare const GUARANTEED_FRAGMENT_UNIFORM_VECTORS = 224;
+/**
+ * What one build of a shader spends, in rows of the uniform grid, counted from its own source.
+ *
+ * **Counted rather than stated, and that is the whole point of this function.** The alternative is
+ * a constant somebody measured once, and a constant measured once against a shader that moves is a
+ * black screen waiting for the next uniform somebody adds. A consumer that had to work around this
+ * wrote the same counter over its vendored copy of the engine for exactly that reason.
+ *
+ * **It is an upper bound, not the driver's own answer.** GLSL ES 3.00 Appendix A lets an
+ * implementation pack loose scalars and small vectors together — four `float`s can share one row —
+ * and this counts a row each. Arrays are exact, because Appendix A gives an array a whole row per
+ * element whatever its base type, which is why a `float uLightRadius[16]` costs the same sixteen
+ * rows a `vec3` array of sixteen does and why the light arrays dominate everything else here.
+ *
+ * Erring high is the direction that is safe to be wrong in: a build this says fits will link, and a
+ * build this says will not fit may still have linked — which costs one rung of the ladder in a
+ * marginal case and never costs a picture. The driver is the authority either way, which is why
+ * `Renderer` also catches the link failure rather than trusting this number alone.
+ */
+export declare function countUniformVectors(source: string): number;
+/**
+ * Every light budget worth trying, largest first.
+ *
+ * **A ladder rather than arithmetic**, because the numbers are a picture decision and not a
+ * solution to an inequality: halving the lamps a scene can shade is a visible change and the steps
+ * are where somebody thought about it. Each rung roughly halves what the arrays cost, and the last
+ * one fits the whole shader — point shadows, area lights and all — inside
+ * `GUARANTEED_FRAGMENT_UNIFORM_VECTORS`, so there is a rung for every conforming device rather
+ * than a floor the engine cannot reach.
+ */
+export declare const LIGHT_BUDGET_LADDER: readonly LightBudget[];
+/**
+ * The next rung down from a budget, or null when there is nothing smaller to try.
+ *
+ * For the caller that has been refused by the driver rather than by arithmetic: `planLightBudget`
+ * counts an upper bound, so a build it passed can still fail to link, and the only honest answer to
+ * a refusal is to ask for less. A budget between rungs — a consumer's own ceiling — steps to the
+ * largest rung strictly under it.
+ */
+export declare function nextLightBudget(budget: LightBudget): LightBudget | null;
+/** What `planLightBudget` decided, and what it decided it from. */
+export interface PlannedLightBudget {
+    /** The budget to build at. Never larger than the ceiling it was given. */
+    readonly budget: LightBudget;
+    /** That budget's source, already built — the caller compiles this rather than rebuilding it. */
+    readonly source: string;
+    /** What `countUniformVectors` makes of that source. */
+    readonly vectors: number;
+    /** Whether the ceiling itself fits, so a caller knows whether to say anything out loud. */
+    readonly fits: boolean;
+    /**
+     * What the ceiling would have spent, for the sentence a caller prints when it could not have it.
+     *
+     * Carried rather than left to the caller to re-derive, because re-deriving it means building the
+     * whole source a second time — 1.7 ms, measured, on the one path that is already the slow one.
+     */
+    readonly ceilingVectors: number;
+}
+/**
+ * The largest budget at or under `ceiling` whose shader fits this device's fragment uniform grid.
+ *
+ * **Why the engine does this rather than the consumer.** `flat` at the full budget declares 440
+ * rows and an Adreno 740 offers 256, so the program does not link, `new WebGL2Renderer` throws,
+ * and a game that awaited `createRenderer` gets no renderer, no reason and no frame — the page's
+ * background colour for as long as the player is willing to look at it. Reported from outside
+ * exactly that way. The only lever a consumer had was to switch point shadows off, which pays a
+ * whole feature to save 192 of the 184 rows that needed saving, and still cannot reach a
+ * conforming 224-row device: the lit path without point shadows is 248.
+ *
+ * Sizing the arrays instead keeps the feature and fits the part: 8 lights and 2 rectangles is 252
+ * rows **with** point shadows compiled in.
+ *
+ * Walking the ladder costs one shader build and one count per rung — about 1.7 ms each, measured —
+ * and a device with room spends exactly one, because the first rung is the ceiling and it fits.
+ *
+ * Returns the last rung when nothing fits, with `fits: false`. That is not a failure to report
+ * here: this counts an upper bound (see `countUniformVectors`) and the driver may well link what
+ * this says it will not, so the caller tries it and lets the link be the answer.
+ */
+export declare function planLightBudget(limitVectors: number, ceiling: LightBudget, build: (budget: LightBudget) => string): PlannedLightBudget;

package/dist/render/uniformVectorBudget.js

@@ -0,0 +1,201 @@
+/** What a fragment shader's uniforms cost against `MAX_FRAGMENT_UNIFORM_VECTORS`, counted from it. */
+import { MAX_AREA_LIGHTS } from './areaLights.js';
+import { MAX_POINT_LIGHTS } from './lightBudget.js';
+/** What the engine declares when nobody says otherwise, and what the generated WGSL is built at. */
+export const FULL_LIGHT_BUDGET = Object.freeze({
+    maxLights: MAX_POINT_LIGHTS,
+    maxAreaLights: MAX_AREA_LIGHTS,
+});
+/**
+ * What WebGL2 guarantees every conforming implementation offers a fragment shader.
+ *
+ * Not a number to design against on any particular device — a desktop part reports thousands and
+ * an Adreno 740 reports 256 — but the floor beneath all of them, and therefore the only number a
+ * budget can be called *reachable* against. `uniformVectorBudget.test.ts` asserts the ladder's
+ * last rung fits inside it with every feature still compiled in.
+ */
+export const GUARANTEED_FRAGMENT_UNIFORM_VECTORS = 224;
+/**
+ * How many rows of the uniform grid one variable of each type occupies.
+ *
+ * A matrix is one row per column; everything else is one row. Samplers are absent deliberately:
+ * they are opaque handles counted against `MAX_TEXTURE_IMAGE_UNITS`, which `renderer.ts` budgets
+ * separately, and `countUniformVectors` skips them by name rather than by looking here.
+ */
+const ROWS = Object.freeze({
+    float: 1,
+    int: 1,
+    uint: 1,
+    bool: 1,
+    vec2: 1,
+    ivec2: 1,
+    uvec2: 1,
+    bvec2: 1,
+    vec3: 1,
+    ivec3: 1,
+    uvec3: 1,
+    bvec3: 1,
+    vec4: 1,
+    ivec4: 1,
+    uvec4: 1,
+    bvec4: 1,
+    mat2: 2,
+    mat3: 3,
+    mat4: 4,
+    mat2x3: 2,
+    mat2x4: 2,
+    mat3x2: 3,
+    mat3x4: 3,
+    mat4x2: 4,
+    mat4x3: 4,
+});
+/** `uniform [precision] type name[size];`, which is the only form this engine's shaders use. */
+const DECLARATION = /^\s*uniform\s+(?:(?:highp|mediump|lowp)\s+)?([A-Za-z0-9_]+)\s+([A-Za-z0-9_]+)\s*(?:\[\s*([A-Za-z0-9_]+)\s*\])?\s*;/;
+/** `#define NAME 12`, and `#define A B` where B is already known. */
+const DEFINE = /^#define\s+([A-Za-z_][A-Za-z0-9_]*)\s+(.+)$/;
+/**
+ * What one build of a shader spends, in rows of the uniform grid, counted from its own source.
+ *
+ * **Counted rather than stated, and that is the whole point of this function.** The alternative is
+ * a constant somebody measured once, and a constant measured once against a shader that moves is a
+ * black screen waiting for the next uniform somebody adds. A consumer that had to work around this
+ * wrote the same counter over its vendored copy of the engine for exactly that reason.
+ *
+ * **It is an upper bound, not the driver's own answer.** GLSL ES 3.00 Appendix A lets an
+ * implementation pack loose scalars and small vectors together — four `float`s can share one row —
+ * and this counts a row each. Arrays are exact, because Appendix A gives an array a whole row per
+ * element whatever its base type, which is why a `float uLightRadius[16]` costs the same sixteen
+ * rows a `vec3` array of sixteen does and why the light arrays dominate everything else here.
+ *
+ * Erring high is the direction that is safe to be wrong in: a build this says fits will link, and a
+ * build this says will not fit may still have linked — which costs one rung of the ladder in a
+ * marginal case and never costs a picture. The driver is the authority either way, which is why
+ * `Renderer` also catches the link failure rather than trusting this number alone.
+ */
+export function countUniformVectors(source) {
+    const defines = new Map();
+    let total = 0;
+    for (const raw of source.split('\n')) {
+        const line = raw.trim();
+        const define = DEFINE.exec(line);
+        if (define !== null) {
+            const [, name, body] = define;
+            const literal = Number(body.trim());
+            if (Number.isInteger(literal))
+                defines.set(name, literal);
+            else {
+                const alias = defines.get(body.trim());
+                if (alias !== undefined)
+                    defines.set(name, alias);
+            }
+            continue;
+        }
+        const declaration = DECLARATION.exec(raw);
+        if (declaration === null)
+            continue;
+        const [, type, , dimension] = declaration;
+        if (/^[iu]?sampler/.test(type))
+            continue;
+        const rows = ROWS[type];
+        if (rows === undefined)
+            continue;
+        if (dimension === undefined) {
+            total += rows;
+            continue;
+        }
+        const literal = Number(dimension);
+        const size = Number.isInteger(literal) ? literal : defines.get(dimension);
+        /*
+         * An array whose size this cannot resolve is counted as one element rather than skipped.
+         * Undercounting a budget is the failure mode that ends in a refused link, so an unreadable
+         * declaration must still cost something — and every array in this engine's shaders is sized by
+         * a `#define` above it, so reaching this at all would be a shader written in a new shape.
+         */
+        total += rows * (size ?? 1);
+    }
+    return total;
+}
+/**
+ * Every light budget worth trying, largest first.
+ *
+ * **A ladder rather than arithmetic**, because the numbers are a picture decision and not a
+ * solution to an inequality: halving the lamps a scene can shade is a visible change and the steps
+ * are where somebody thought about it. Each rung roughly halves what the arrays cost, and the last
+ * one fits the whole shader — point shadows, area lights and all — inside
+ * `GUARANTEED_FRAGMENT_UNIFORM_VECTORS`, so there is a rung for every conforming device rather
+ * than a floor the engine cannot reach.
+ */
+export const LIGHT_BUDGET_LADDER = Object.freeze([
+    FULL_LIGHT_BUDGET,
+    Object.freeze({ maxLights: 12, maxAreaLights: 3 }),
+    Object.freeze({ maxLights: 8, maxAreaLights: 2 }),
+    Object.freeze({ maxLights: 4, maxAreaLights: 1 }),
+    Object.freeze({ maxLights: 2, maxAreaLights: 1 }),
+]);
+/**
+ * The next rung down from a budget, or null when there is nothing smaller to try.
+ *
+ * For the caller that has been refused by the driver rather than by arithmetic: `planLightBudget`
+ * counts an upper bound, so a build it passed can still fail to link, and the only honest answer to
+ * a refusal is to ask for less. A budget between rungs — a consumer's own ceiling — steps to the
+ * largest rung strictly under it.
+ */
+export function nextLightBudget(budget) {
+    for (const rung of LIGHT_BUDGET_LADDER) {
+        if (rung.maxLights < budget.maxLights || rung.maxAreaLights < budget.maxAreaLights) {
+            return {
+                maxLights: Math.min(rung.maxLights, budget.maxLights),
+                maxAreaLights: Math.min(rung.maxAreaLights, budget.maxAreaLights),
+            };
+        }
+    }
+    return null;
+}
+/**
+ * The largest budget at or under `ceiling` whose shader fits this device's fragment uniform grid.
+ *
+ * **Why the engine does this rather than the consumer.** `flat` at the full budget declares 440
+ * rows and an Adreno 740 offers 256, so the program does not link, `new WebGL2Renderer` throws,
+ * and a game that awaited `createRenderer` gets no renderer, no reason and no frame — the page's
+ * background colour for as long as the player is willing to look at it. Reported from outside
+ * exactly that way. The only lever a consumer had was to switch point shadows off, which pays a
+ * whole feature to save 192 of the 184 rows that needed saving, and still cannot reach a
+ * conforming 224-row device: the lit path without point shadows is 248.
+ *
+ * Sizing the arrays instead keeps the feature and fits the part: 8 lights and 2 rectangles is 252
+ * rows **with** point shadows compiled in.
+ *
+ * Walking the ladder costs one shader build and one count per rung — about 1.7 ms each, measured —
+ * and a device with room spends exactly one, because the first rung is the ceiling and it fits.
+ *
+ * Returns the last rung when nothing fits, with `fits: false`. That is not a failure to report
+ * here: this counts an upper bound (see `countUniformVectors`) and the driver may well link what
+ * this says it will not, so the caller tries it and lets the link be the answer.
+ */
+export function planLightBudget(limitVectors, ceiling, build) {
+    const under = LIGHT_BUDGET_LADDER.filter((rung) => rung.maxLights <= ceiling.maxLights && rung.maxAreaLights <= ceiling.maxAreaLights);
+    /*
+     * The ceiling itself is tried first even when it is not a rung, because a consumer that asked
+     * for 6 lights means 6 and should not be handed 4 by a ladder that has no 6 on it. Compared by
+     * value rather than by identity: a caller that writes the full budget out as a fresh object
+     * means the same thing the frozen constant does, and building that source twice would cost a
+     * rung's worth of work to learn nothing.
+     */
+    const same = (a, b) => a.maxLights === b.maxLights && a.maxAreaLights === b.maxAreaLights;
+    const tried = under[0] !== undefined && same(under[0], ceiling) ? under : [ceiling, ...under];
+    let last = null;
+    let ceilingVectors = 0;
+    for (const budget of tried) {
+        const source = build(budget);
+        const vectors = countUniformVectors(source);
+        /* The first rung tried is the ceiling, by construction above. */
+        if (last === null)
+            ceilingVectors = vectors;
+        if (vectors <= limitVectors) {
+            return { budget, source, vectors, fits: same(budget, ceiling), ceilingVectors };
+        }
+        last = { budget, source, vectors, fits: false, ceilingVectors };
+    }
+    /* `tried` always holds the ceiling, so `last` is set by the time the loop ends. */
+    return last;
+}

package/dist/render/uploadStep.d.ts

@@ -0,0 +1,14 @@
+/**
+ * How much of a mesh one upload step moves, in bytes.
+ *
+ * A quarter of a megabyte. Measured on the interleave, which is the CPU half of the cost and the
+ * half a test can time: on a desktop part, 65,536 floats interleave in 0.14 ms and a whole
+ * 250,000-vertex group in 5.5 ms. A megabyte a step was the first choice and is 2.2 ms here,
+ * which is most of a 4 ms streaming budget before the GPU half is counted and several times that
+ * on a phone. A quarter buys a step small enough that a slow device still fits one.
+ *
+ * The same number bounds the `writeBuffer` beside it, in the same bytes, because the two are one
+ * stop and a consumer's report suspects the queue rather than the arithmetic: a whole square's
+ * geometry landing at once measured 57 ms where this interleave accounts for six.
+ */
+export declare const UPLOAD_BYTES_PER_STEP: number;

package/dist/render/uploadStep.js

@@ -0,0 +1,14 @@
+/**
+ * How much of a mesh one upload step moves, in bytes.
+ *
+ * A quarter of a megabyte. Measured on the interleave, which is the CPU half of the cost and the
+ * half a test can time: on a desktop part, 65,536 floats interleave in 0.14 ms and a whole
+ * 250,000-vertex group in 5.5 ms. A megabyte a step was the first choice and is 2.2 ms here,
+ * which is most of a 4 ms streaming budget before the GPU half is counted and several times that
+ * on a phone. A quarter buys a step small enough that a slow device still fits one.
+ *
+ * The same number bounds the `writeBuffer` beside it, in the same bytes, because the two are one
+ * stop and a consumer's report suspects the queue rather than the arithmetic: a whole square's
+ * geometry landing at once measured 57 ms where this interleave accounts for six.
+ */
+export const UPLOAD_BYTES_PER_STEP = 1 << 18;

package/dist/render/vertexDefaults.d.ts

@@ -0,0 +1,48 @@
+/**
+ * What a vertex attribute reads as when a mesh does not supply it.
+ *
+ * **One decision, and it was being made twice.** WebGL2 disables the attribute and hands the
+ * driver a constant; WebGPU has no such thing as a disabled attribute, so it reads a
+ * one-element buffer at a stride of zero. Two mechanisms, one question — *what does a mesh that
+ * said nothing about this mean?* — and `AGENTS.md` is explicit that a question both backends
+ * answer belongs in one module and is bound twice.
+ *
+ * **It was not a tidiness problem.** The values had drifted apart and two of them mattered:
+ *
+ * - `emissiveColor` is a **sentinel**, not a colour. `flat.ts` reads
+ *   `vEmissiveColor.r < 0.0 ? albedo : vEmissiveColor`, so −1 means *"glow in my own colour"*
+ *   and 0 means *"glow black"*. WebGPU was filling zeroes, so **every emissive surface whose
+ *   mesh omitted the attribute stopped emitting**. `night-street`'s far windows went dark and
+ *   its near ones only looked right because they were clipped at white already — which is how
+ *   it survived a whole session of being attributed to fog, ambient occlusion and relief.
+ * - `roughness` absent is the engine's long-standing lobe, not a mirror. Zero is the shiniest
+ *   surface expressible, which is the opposite of "unstated".
+ *
+ * The rest are genuinely zero, and are written down here anyway so the next attribute added
+ * has somewhere obvious to state its answer instead of inheriting one by accident.
+ */
+/** The engine's fixed lobe, for geometry that never says how rough it is. */
+export declare const DEFAULT_ROUGHNESS = 0.4277;
+/**
+ * Keyed by the attribute's name in `MeshData`, with one entry per optional attribute.
+ *
+ * Lengths match the attribute's component count; `vertexDefaults.test.ts` pins that, because a
+ * short entry would write a default into the next attribute's slot rather than fail.
+ */
+export declare const ABSENT_ATTRIBUTE: Readonly<Record<string, readonly number[]>>;
+/**
+ * What `uOutputTransform` means, as the shader's own integers.
+ *
+ * Shared because both backends have to agree about which curve a profile named, and because
+ * getting it wrong is invisible: the codes are small integers and every one of them is a legal
+ * value that produces a picture. `flat.ts` reads `0` as none, `1` as sRGB and `2` as ACES.
+ */
+export declare const OUTPUT_TRANSFORM_CODE: Readonly<Record<string, number>>;
+/**
+ * How far the speed rush reaches, and how far a motion-blurred pixel may travel, both in UV.
+ *
+ * Shared because both backends run the same composite shader and a difference here is a
+ * difference in the picture that nothing else would explain. `renderer.ts` held the only copy.
+ */
+export declare const RUSH_REACH_UV = 0.012;
+export declare const MOTION_BLUR_MAX_UV = 0.03;

package/dist/render/vertexDefaults.js

@@ -0,0 +1,111 @@
+/**
+ * What a vertex attribute reads as when a mesh does not supply it.
+ *
+ * **One decision, and it was being made twice.** WebGL2 disables the attribute and hands the
+ * driver a constant; WebGPU has no such thing as a disabled attribute, so it reads a
+ * one-element buffer at a stride of zero. Two mechanisms, one question — *what does a mesh that
+ * said nothing about this mean?* — and `AGENTS.md` is explicit that a question both backends
+ * answer belongs in one module and is bound twice.
+ *
+ * **It was not a tidiness problem.** The values had drifted apart and two of them mattered:
+ *
+ * - `emissiveColor` is a **sentinel**, not a colour. `flat.ts` reads
+ *   `vEmissiveColor.r < 0.0 ? albedo : vEmissiveColor`, so −1 means *"glow in my own colour"*
+ *   and 0 means *"glow black"*. WebGPU was filling zeroes, so **every emissive surface whose
+ *   mesh omitted the attribute stopped emitting**. `night-street`'s far windows went dark and
+ *   its near ones only looked right because they were clipped at white already — which is how
+ *   it survived a whole session of being attributed to fog, ambient occlusion and relief.
+ * - `roughness` absent is the engine's long-standing lobe, not a mirror. Zero is the shiniest
+ *   surface expressible, which is the opposite of "unstated".
+ *
+ * The rest are genuinely zero, and are written down here anyway so the next attribute added
+ * has somewhere obvious to state its answer instead of inheriting one by accident.
+ */
+/** The engine's fixed lobe, for geometry that never says how rough it is. */
+export const DEFAULT_ROUGHNESS = 0.4277;
+/**
+ * Keyed by the attribute's name in `MeshData`, with one entry per optional attribute.
+ *
+ * Lengths match the attribute's component count; `vertexDefaults.test.ts` pins that, because a
+ * short entry would write a default into the next attribute's slot rather than fail.
+ */
+export const ABSENT_ATTRIBUTE = {
+    /** No highlight, for geometry that never claimed one. */
+    specular: [0],
+    uvs: [0, 0],
+    /** The sentinel `flat.ts` tests for: inherit the albedo. Never a colour. */
+    emissiveColor: [-1, -1, -1],
+    roughness: [DEFAULT_ROUGHNESS],
+    /**
+     * No grain and no relief at all, and that is the point of these attributes rather than a
+     * default chosen for convenience: a surface that never says it is mineral is not mineral.
+     * `mesh.ts` records that the two versions which inferred it were both wrong.
+     */
+    grain: [0],
+    relief: [0],
+    /**
+     * A usable frame rather than zero, for the reason `generateTangents` gives about degenerate
+     * UVs: a zero tangent normalises to a NaN in any shader that eventually reads one, and a NaN
+     * in a fragment takes the pixel with it. `(1, 0, 0)` with a right-handed bitangent is
+     * arbitrary and finite, and arbitrary is the honest answer for geometry that has no texture
+     * to be oriented against in the first place.
+     */
+    tangents: [1, 0, 0, 1],
+    /**
+     * All four influences on joint 0, for a mesh a skinned pipeline draws without a rig.
+     *
+     * Zero is a trap here rather than a neutral value: four zero weights build a zero matrix, and a
+     * zero matrix collapses every vertex it touches onto the origin — so the mesh would not shade
+     * oddly, it would vanish. The identity influence is one and three zeroes, which for a mesh with
+     * no rig leaves every vertex where it already was.
+     *
+     * What it costs is nothing; a mesh with joints never reads these. What would make it wrong is a
+     * palette whose entry 0 is not identity, which is a rig the importer sorted incorrectly rather
+     * than a case to defend against here.
+     */
+    joints: [0, 0, 0, 0],
+    weights: [1, 0, 0, 0],
+    /**
+     * The four-lane channel: planted, fully sunlit, opaque, and a reserved lane.
+     *
+     * **Two of these are ones and that is load bearing.** Zero for `skyDirect` would take the
+     * directional light off every mesh in the engine that has never heard of this attribute, and
+     * zero for `alpha` would make all of them invisible — so the wrong default here is not a subtle
+     * shading difference, it is the whole world going dark or vanishing. `vertexDefaults.test.ts`
+     * pins the tuple for that reason.
+     *
+     * Sway is the one honest zero: geometry that never said it bends does not bend.
+     *
+     * **The fourth lane was 0 while it was reserved and is 1 now that it carries thickness**, and the
+     * difference is not cosmetic. It multiplies the thickness a refracting draw states, so a zero
+     * makes the path length zero, `pow(tint, 0)` one, and a pane of coloured glass absorb nothing at
+     * all — a draw naming a tint and a thickness would bend the scene behind it and take no colour
+     * out of it. Every lane here is a multiplier or an amount, and the identity for a multiplier is
+     * one.
+     *
+     * It survived as 0 because the lane was declared and unread, and because the check that exercises
+     * refraction supplies a channel array on every subject it draws — so the absent case was never
+     * the thing being measured.
+     */
+    channel: [0, 1, 1, 1],
+};
+/**
+ * What `uOutputTransform` means, as the shader's own integers.
+ *
+ * Shared because both backends have to agree about which curve a profile named, and because
+ * getting it wrong is invisible: the codes are small integers and every one of them is a legal
+ * value that produces a picture. `flat.ts` reads `0` as none, `1` as sRGB and `2` as ACES.
+ */
+export const OUTPUT_TRANSFORM_CODE = {
+    none: 0,
+    srgb: 1,
+    aces: 2,
+};
+/**
+ * How far the speed rush reaches, and how far a motion-blurred pixel may travel, both in UV.
+ *
+ * Shared because both backends run the same composite shader and a difference here is a
+ * difference in the picture that nothing else would explain. `renderer.ts` held the only copy.
+ */
+export const RUSH_REACH_UV = 0.012;
+export const MOTION_BLUR_MAX_UV = 0.03;