@driftengine/core 3.61.0

package/dist/render/equirectToCube.js

@@ -0,0 +1,123 @@
+/** An equirectangular image resampled onto the six faces of a cube. */
+/**
+ * The direction a texel stands for, per face.
+ *
+ * `forward` is the face centre, `basisX` steps across a row and `basisY` down a column, matching
+ * `webgpu/probePass.ts`'s `PROBE_FACE_BASIS` exactly — the same table, and it is the same table
+ * because getting one sign wrong mirrors a single face, which projects to a plausible-looking
+ * wrong answer rather than to an error.
+ *
+ * **It lived in `irradianceSh.ts` until the spherical-harmonic path was retired**, and it moved
+ * here rather than being deleted with it: the capture is still a cube, so a loaded environment
+ * still has to know which direction each of its texels stands for. The prefilter's own copy went
+ * with the six-face loop, since an octahedral target has no faces at all.
+ */
+export const FACE_BASIS = [
+    { forward: [1, 0, 0], basisX: [0, 0, -1], basisY: [0, -1, 0] },
+    { forward: [-1, 0, 0], basisX: [0, 0, 1], basisY: [0, -1, 0] },
+    { forward: [0, 1, 0], basisX: [1, 0, 0], basisY: [0, 0, 1] },
+    { forward: [0, -1, 0], basisX: [1, 0, 0], basisY: [0, 0, -1] },
+    { forward: [0, 0, 1], basisX: [1, 0, 0], basisY: [0, -1, 0] },
+    { forward: [0, 0, -1], basisX: [-1, 0, 0], basisY: [0, -1, 0] },
+];
+/**
+ * Resample an equirectangular environment onto six cube faces.
+ *
+ * **Backend-neutral, and it produces exactly what the projection already takes.** The output is the
+ * shape a bake produces — six `size * size * 4` arrays of linear RGBA in
+ * cubemap order — so a loaded environment joins the captured path at the same place a bake does,
+ * and everything downstream of the cube is one implementation rather than two.
+ *
+ * **The face basis is imported rather than restated.** This is the fourth place that table would
+ * have appeared, and its failure mode is the one the 2026-08-17 rule is about: a mirrored face
+ * projects perfectly well onto a wrong answer, and the last time two copies disagreed it took
+ * projecting both backends' cubes onto one shared basis to find a sign in the linear Z band.
+ *
+ * ## The convention, stated because there is no universal one
+ *
+ * - **Row 0 is the zenith.** `v = acos(y) / pi`, so the top of the image is `+Y`. Inverting this
+ *   puts the sky underfoot, and every surface is then lit from below with nothing in the picture
+ *   to say why.
+ * - **The centre column is `-Z`.** `u = 0.5 + atan2(x, -z) / 2pi`, which is the engine's own camera
+ *   convention — yaw 0 looks toward `-Z` and positive yaw turns toward `+X` — so `+X` lands three
+ *   quarters of the way across. Choosing the mirror of this passes every brightness check and
+ *   every sky-is-up check, and shows only as a reflection that turns the wrong way.
+ *
+ * **What it costs** is bilinear sampling per texel of the destination, once, at load. **What would
+ * make it wrong** is a source small enough that the cube is upsampling it — at that point the faces
+ * carry interpolation rather than image, and the honest answer is a smaller cube.
+ */
+export function equirectToCubeFaces(source, size) {
+    if (size <= 0)
+        throw new Error(`equirectToCubeFaces: a ${size}-texel face is not buildable`);
+    if (source.width <= 0 || source.height <= 0) {
+        throw new Error(`equirectToCubeFaces: a ${source.width} by ${source.height} source has nothing to sample`);
+    }
+    const faces = [];
+    for (let face = 0; face < FACE_BASIS.length; face++) {
+        const basis = FACE_BASIS[face];
+        const pixels = new Float32Array(size * size * 4);
+        if (basis === undefined) {
+            faces.push(pixels);
+            continue;
+        }
+        for (let y = 0; y < size; y++) {
+            /* Texel centres in [-1, 1], the same mapping the projection uses, so the two agree exactly. */
+            const v = ((y + 0.5) / size) * 2 - 1;
+            for (let x = 0; x < size; x++) {
+                const u = ((x + 0.5) / size) * 2 - 1;
+                const dx = basis.forward[0] + basis.basisX[0] * u + basis.basisY[0] * v;
+                const dy = basis.forward[1] + basis.basisX[1] * u + basis.basisY[1] * v;
+                const dz = basis.forward[2] + basis.basisX[2] * u + basis.basisY[2] * v;
+                const inverse = 1 / Math.sqrt(dx * dx + dy * dy + dz * dz);
+                sampleEquirect(source, dx * inverse, dy * inverse, dz * inverse, pixels, (y * size + x) * 4);
+            }
+        }
+        faces.push(pixels);
+    }
+    return faces;
+}
+/**
+ * One direction, bilinearly sampled out of the source, written as RGBA at `out`.
+ *
+ * **Wrapped in longitude and clamped in latitude**, which is what the sphere actually does: the
+ * seam at `u = 1` meets `u = 0` and is a real join, while the pole is a point and has no neighbour
+ * above it. Clamping both would put a visible seam down the back of every environment; wrapping
+ * both would sample the far side of the sky at the zenith.
+ */
+function sampleEquirect(source, dx, dy, dz, out, at) {
+    const { width, height, data } = source;
+    const u = 0.5 + Math.atan2(dx, -dz) / (2 * Math.PI);
+    const v = Math.acos(Math.min(1, Math.max(-1, dy))) / Math.PI;
+    /* Texel centres again, so a sample at the exact centre of a texel reads that texel and no other. */
+    const fx = u * width - 0.5;
+    const fy = v * height - 0.5;
+    const x0 = Math.floor(fx);
+    const y0 = Math.floor(fy);
+    const tx = fx - x0;
+    const ty = fy - y0;
+    const xa = wrap(x0, width);
+    const xb = wrap(x0 + 1, width);
+    const ya = clamp(y0, height);
+    const yb = clamp(y0 + 1, height);
+    for (let channel = 0; channel < 3; channel++) {
+        const aa = data[(ya * width + xa) * 3 + channel] ?? 0;
+        const ba = data[(ya * width + xb) * 3 + channel] ?? 0;
+        const ab = data[(yb * width + xa) * 3 + channel] ?? 0;
+        const bb = data[(yb * width + xb) * 3 + channel] ?? 0;
+        const top = aa + (ba - aa) * tx;
+        const bottom = ab + (bb - ab) * tx;
+        out[at + channel] = top + (bottom - top) * ty;
+    }
+    /* One, because a cube sampler reads four channels whatever an environment meant by the fourth. */
+    out[at + 3] = 1;
+}
+/** Longitude wraps: the image's left edge is its right edge. */
+function wrap(value, extent) {
+    const wrapped = value % extent;
+    return wrapped < 0 ? wrapped + extent : wrapped;
+}
+/** Latitude clamps: there is nothing above the zenith to blend with. */
+function clamp(value, extent) {
+    return value < 0 ? 0 : value >= extent ? extent - 1 : value;
+}

package/dist/render/flockGeometry.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A flock's static geometry, held once so both backends draw the same bird.
+ *
+ * Two triangles a bird, a body quad split into two wings, with a per-vertex weight that is 1 at
+ * a wingtip and 0 at the body so only the tips beat. Every bird's path is computed in the vertex
+ * shader from its index and the clock, so this is uploaded once and the frame loop does nothing.
+ *
+ * Shared rather than restated for the reason `waterGrid.ts` was extracted: a second corner table
+ * is a second bird, and a mesh that differs by a wing between backends is not something the
+ * parity gate can attribute.
+ */
+/** Corner positions, in wingspans: tip, body front, body back. */
+export declare const FLOCK_CORNERS: readonly (readonly [number, number])[];
+/** 1 at a wingtip, 0 at the body, so only the tips beat. */
+export declare const FLOCK_WING: readonly number[];
+/** The three static attribute streams a flock is drawn from. */
+export interface FlockGeometry {
+    readonly corners: Float32Array;
+    readonly wings: Float32Array;
+    readonly indices: Float32Array;
+    readonly vertexCount: number;
+}
+export declare function buildFlockGeometry(count: number): FlockGeometry;

package/dist/render/flockGeometry.js

@@ -0,0 +1,43 @@
+/**
+ * A flock's static geometry, held once so both backends draw the same bird.
+ *
+ * Two triangles a bird, a body quad split into two wings, with a per-vertex weight that is 1 at
+ * a wingtip and 0 at the body so only the tips beat. Every bird's path is computed in the vertex
+ * shader from its index and the clock, so this is uploaded once and the frame loop does nothing.
+ *
+ * Shared rather than restated for the reason `waterGrid.ts` was extracted: a second corner table
+ * is a second bird, and a mesh that differs by a wing between backends is not something the
+ * parity gate can attribute.
+ */
+/** Corner positions, in wingspans: tip, body front, body back. */
+export const FLOCK_CORNERS = [
+    [-1, 0],
+    [0, -0.35],
+    [0, 0.35],
+    [1, 0],
+    [0, 0.35],
+    [0, -0.35],
+];
+/** 1 at a wingtip, 0 at the body, so only the tips beat. */
+export const FLOCK_WING = [1, 0, 0, 1, 0, 0];
+export function buildFlockGeometry(count) {
+    if (count <= 0)
+        throw new Error('A flock needs at least one bird.');
+    const perBird = FLOCK_CORNERS.length;
+    const corners = new Float32Array(count * perBird * 2);
+    const wings = new Float32Array(count * perBird);
+    const indices = new Float32Array(count * perBird);
+    let c = 0;
+    let w = 0;
+    for (let bird = 0; bird < count; bird++) {
+        for (let v = 0; v < perBird; v++) {
+            const corner = FLOCK_CORNERS[v];
+            corners[c++] = corner[0];
+            corners[c++] = corner[1];
+            wings[w] = FLOCK_WING[v] ?? 0;
+            indices[w] = bird;
+            w++;
+        }
+    }
+    return { corners, wings, indices, vertexCount: count * perBird };
+}

package/dist/render/flockRenderer.d.ts

@@ -0,0 +1,37 @@
+import type { FrameView } from './frameView.ts';
+import type { Vec3 } from '../math/color.ts';
+/**
+ * Ambient sky life. Entirely GPU-side: the geometry is uploaded once and every
+ * bird's path is computed in the vertex shader from its index and the clock.
+ *
+ * Deliberately not a simulation. Flocking behaviour would be CPU work every
+ * frame, forever, for something nobody looks at directly — and the thing it
+ * actually buys, a world that carries on without the player, comes from motion
+ * and silhouette rather than from correct boids.
+ */
+export interface FlockParams {
+    center: Vec3;
+    radius: number;
+    height: number;
+    count: number;
+    /** Metres per second along the orbit. */
+    speed: number;
+    /**
+     * Half the wingspan, in metres: a bird measures `2 * scale` from tip to tip.
+     *
+     * It said "wingspan, roughly", and it is out by a factor of two, which is not roughly.
+     * The corner table below puts the tips at plus and minus one before this multiplies
+     * them, so a caller asking for a 1.5 m bird is handed a 3 m one.
+     */
+    scale: number;
+}
+export declare class FlockRenderer {
+    private readonly program;
+    private readonly uniforms;
+    private readonly vao;
+    private readonly buffers;
+    private readonly vertexCount;
+    constructor(gl: WebGL2RenderingContext, count: number);
+    draw(gl: WebGL2RenderingContext, camera: FrameView, timeSeconds: number, params: FlockParams, tint: Vec3, windX?: number, windZ?: number): void;
+    dispose(gl: WebGL2RenderingContext): void;
+}

package/dist/render/flockRenderer.js

@@ -0,0 +1,70 @@
+import { compileProgram, uniformLocations } from './shader.js';
+import { FLOCK_FRAG, FLOCK_VERT } from './shaders/flock.js';
+import { buildFlockGeometry } from './flockGeometry.js';
+export class FlockRenderer {
+    program;
+    uniforms;
+    vao;
+    buffers = [];
+    vertexCount;
+    constructor(gl, count) {
+        this.program = compileProgram(gl, FLOCK_VERT, FLOCK_FRAG, 'flock');
+        this.uniforms = uniformLocations(gl, this.program, 'flockRenderer');
+        /* Built in `flockGeometry.ts`, which is also where the count is validated. */
+        const geometry = buildFlockGeometry(count);
+        const { corners, wings, indices } = geometry;
+        this.vertexCount = geometry.vertexCount;
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('FlockRenderer: createVertexArray failed');
+        this.vao = vao;
+        gl.bindVertexArray(vao);
+        const attach = (data, location, size) => {
+            const buffer = gl.createBuffer();
+            if (buffer === null)
+                throw new Error('FlockRenderer: createBuffer failed');
+            this.buffers.push(buffer);
+            gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+            gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);
+            gl.enableVertexAttribArray(location);
+            gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+        };
+        attach(corners, 0, 2);
+        attach(wings, 1, 1);
+        attach(indices, 2, 1);
+        gl.bindVertexArray(null);
+    }
+    draw(gl, camera, timeSeconds, params, tint, windX = 0, windZ = 0) {
+        const u = this.uniforms;
+        gl.useProgram(this.program);
+        gl.uniformMatrix4fv(u['uViewProj'] ?? null, false, camera.viewProjection);
+        /*
+         * No `uCameraPos` here, and the shader no longer declares one. It fed the banking that
+         * turned a wing plane toward the viewer, and that was reverted with the rest of the flock
+         * work when the shape being reported turned out to be the lighthouse beam rather than a
+         * bird. What was left behind was a declaration nothing read and an upload every frame to a
+         * location that had stopped existing. See AGENTS.md, 2026-08-10.
+         */
+        gl.uniform3fv(u['uCenter'] ?? null, params.center);
+        gl.uniform1f(u['uRadius'] ?? null, params.radius);
+        gl.uniform1f(u['uHeight'] ?? null, params.height);
+        gl.uniform1f(u['uSpeed'] ?? null, params.speed);
+        gl.uniform1f(u['uCount'] ?? null, params.count);
+        gl.uniform1f(u['uScale'] ?? null, params.scale);
+        gl.uniform1f(u['uTime'] ?? null, timeSeconds);
+        gl.uniform3fv(u['uTint'] ?? null, tint);
+        gl.uniform2f(u['uWind'] ?? null, windX, windZ);
+        // Birds are flat and seen from both sides as they bank.
+        gl.disable(gl.CULL_FACE);
+        gl.bindVertexArray(this.vao);
+        gl.drawArrays(gl.TRIANGLES, 0, this.vertexCount);
+        gl.bindVertexArray(null);
+        gl.enable(gl.CULL_FACE);
+    }
+    dispose(gl) {
+        for (const buffer of this.buffers)
+            gl.deleteBuffer(buffer);
+        gl.deleteVertexArray(this.vao);
+        gl.deleteProgram(this.program);
+    }
+}

package/dist/render/frame/arena.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Where a frame's draws are recorded, without allocating.
+ *
+ * A recorder is exactly the shape that wants an object per draw, and `AGENTS.md` forbids
+ * allocating while a frame is running. So a node is six integers in one `Int32Array` and a
+ * draw writes into it and returns: nothing constructed, nothing captured by a closure.
+ * `InstanceData` and the particle pools already work this way, so the pattern is established
+ * here rather than imported.
+ *
+ * Growth happens, and it happens where allocation is legal. A frame that records past
+ * capacity must not silently drop a draw — that is the failure this is designed against — so
+ * it grows, records `highWater`, and the next frame starts large enough for what the last one
+ * needed.
+ */
+export declare const NODE_STRIDE = 6;
+export interface Arena {
+    nodes: Int32Array;
+    count: number;
+    /** The most nodes any frame has recorded, so growth converges instead of repeating. */
+    highWater: number;
+}
+export declare function createArena(capacity: number): Arena;
+/** Empty the arena for a new frame. Keeps the storage; that is the whole point. */
+export declare function resetArena(arena: Arena): void;
+export declare function nodeCount(arena: Arena): number;
+/** Record one node and return its index. */
+export declare function recordNode(arena: Arena, verb: number, reads: number, writes: number, state: number, matrix: number): number;
+export declare function nodeVerb(arena: Arena, at: number): number;
+export declare function nodeReads(arena: Arena, at: number): number;
+export declare function nodeWrites(arena: Arena, at: number): number;
+export declare function nodeState(arena: Arena, at: number): number;
+export declare function nodeMatrix(arena: Arena, at: number): number;

package/dist/render/frame/arena.js

@@ -0,0 +1,65 @@
+/**
+ * Where a frame's draws are recorded, without allocating.
+ *
+ * A recorder is exactly the shape that wants an object per draw, and `AGENTS.md` forbids
+ * allocating while a frame is running. So a node is six integers in one `Int32Array` and a
+ * draw writes into it and returns: nothing constructed, nothing captured by a closure.
+ * `InstanceData` and the particle pools already work this way, so the pattern is established
+ * here rather than imported.
+ *
+ * Growth happens, and it happens where allocation is legal. A frame that records past
+ * capacity must not silently drop a draw — that is the failure this is designed against — so
+ * it grows, records `highWater`, and the next frame starts large enough for what the last one
+ * needed.
+ */
+export const NODE_STRIDE = 6;
+const VERB = 0;
+const READS = 1;
+const WRITES = 2;
+const STATE = 3;
+const MATRIX = 4;
+export function createArena(capacity) {
+    return { nodes: new Int32Array(capacity * NODE_STRIDE), count: 0, highWater: 0 };
+}
+/** Empty the arena for a new frame. Keeps the storage; that is the whole point. */
+export function resetArena(arena) {
+    arena.count = 0;
+}
+export function nodeCount(arena) {
+    return arena.count;
+}
+/** Record one node and return its index. */
+export function recordNode(arena, verb, reads, writes, state, matrix) {
+    const at = arena.count;
+    const need = (at + 1) * NODE_STRIDE;
+    if (need > arena.nodes.length) {
+        const grown = new Int32Array(Math.max(need, arena.nodes.length * 2));
+        grown.set(arena.nodes);
+        arena.nodes = grown;
+    }
+    const base = at * NODE_STRIDE;
+    arena.nodes[base + VERB] = verb;
+    arena.nodes[base + READS] = reads;
+    arena.nodes[base + WRITES] = writes;
+    arena.nodes[base + STATE] = state;
+    arena.nodes[base + MATRIX] = matrix;
+    arena.count = at + 1;
+    if (arena.count > arena.highWater)
+        arena.highWater = arena.count;
+    return at;
+}
+export function nodeVerb(arena, at) {
+    return arena.nodes[at * NODE_STRIDE + VERB] ?? 0;
+}
+export function nodeReads(arena, at) {
+    return arena.nodes[at * NODE_STRIDE + READS] ?? 0;
+}
+export function nodeWrites(arena, at) {
+    return arena.nodes[at * NODE_STRIDE + WRITES] ?? 0;
+}
+export function nodeState(arena, at) {
+    return arena.nodes[at * NODE_STRIDE + STATE] ?? 0;
+}
+export function nodeMatrix(arena, at) {
+    return arena.nodes[at * NODE_STRIDE + MATRIX] ?? 0;
+}

package/dist/render/frame/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The frame graph's pure half: what a frame touches, how a draw is recorded, and how records
+ * become passes.
+ *
+ * Nothing here imports WebGL or WebGPU. The scheduler is arithmetic, which is what lets the
+ * only novel logic in the design be proven by assertion before any renderer is rewritten
+ * around it.
+ *
+ * Deliberately not on the package barrel. Nothing outside `render/` may reach these yet;
+ * Phase B is what decides their public shape.
+ */
+export type { FrameResource } from './resources.ts';
+export { FRAME_RESOURCES, RESOURCE_COUNT, maskOf, namesIn, resourceBit } from './resources.ts';
+export type { Arena } from './arena.ts';
+export { NODE_STRIDE, createArena, nodeCount, nodeMatrix, nodeReads, nodeState, nodeVerb, nodeWrites, recordNode, resetArena, } from './arena.ts';
+export type { ScheduledPass } from './schedule.ts';
+export { schedule } from './schedule.ts';
+export { keptNodes, scratchFor } from './replay.ts';

package/dist/render/frame/index.js

@@ -0,0 +1,4 @@
+export { FRAME_RESOURCES, RESOURCE_COUNT, maskOf, namesIn, resourceBit } from './resources.js';
+export { NODE_STRIDE, createArena, nodeCount, nodeMatrix, nodeReads, nodeState, nodeVerb, nodeWrites, recordNode, resetArena, } from './arena.js';
+export { schedule } from './schedule.js';
+export { keptNodes, scratchFor } from './replay.js';

package/dist/render/frame/replay.d.ts

@@ -0,0 +1,34 @@
+import type { ScheduledPass } from './schedule.ts';
+/**
+ * The nodes a schedule kept, in the order they are to be replayed.
+ *
+ * **Separate from the executor because it is the part with an answer to check.** A pass the
+ * scheduler dropped writes something nothing reads, and replaying its nodes anyway is what made
+ * every capture in the verb migration unable to fail — but no real frame drops a pass today, so
+ * the behaviour has nowhere to be observed from inside a renderer test. Here it has.
+ *
+ * Order inside a pass is the caller's order and is never changed, for the reason `schedule`
+ * gives: blending and depth make *after* different from *before*.
+ *
+ * Allocates nothing. `out` is the caller's, sized with the arena, and the return value says how
+ * many of its entries were filled.
+ */
+export declare function keptNodes(passes: ScheduledPass[], count: number, out: Int32Array): number;
+/**
+ * A scratch array big enough for `needed` nodes, reusing the one given where it already fits.
+ *
+ * **`keptNodes` says the caller's array is "sized with the arena", and this is what makes that
+ * true.** It was not: the renderer sized its scratch with `MAX_DRAWS_PER_FRAME` while the arena
+ * it reads reallocates at twice its capacity whenever a frame outgrows it. `keptNodes` then
+ * stopped at `out.length` and the tail of the frame's passes was never replayed — no warning, no
+ * error, and a plausible picture missing whatever those passes drew.
+ *
+ * It was reachable with the draw ring nowhere near full, because a node is recorded per **verb**
+ * rather than per draw: overlays, scatter, plumes and text each record one.
+ *
+ * **What it costs** is a single allocation on the frame that first outgrows the scratch and none
+ * afterwards, because the caller keeps what comes back. **What would make it wrong** is a caller
+ * that discards the result and calls this again per frame, which is an allocation in a hot path;
+ * the arena's own doubling is what keeps the growth finite rather than per-frame.
+ */
+export declare function scratchFor(scratch: Int32Array, needed: number): Int32Array;

package/dist/render/frame/replay.js

@@ -0,0 +1,48 @@
+/**
+ * The nodes a schedule kept, in the order they are to be replayed.
+ *
+ * **Separate from the executor because it is the part with an answer to check.** A pass the
+ * scheduler dropped writes something nothing reads, and replaying its nodes anyway is what made
+ * every capture in the verb migration unable to fail — but no real frame drops a pass today, so
+ * the behaviour has nowhere to be observed from inside a renderer test. Here it has.
+ *
+ * Order inside a pass is the caller's order and is never changed, for the reason `schedule`
+ * gives: blending and depth make *after* different from *before*.
+ *
+ * Allocates nothing. `out` is the caller's, sized with the arena, and the return value says how
+ * many of its entries were filled.
+ */
+export function keptNodes(passes, count, out) {
+    let at = 0;
+    for (let i = 0; i < count; i += 1) {
+        const pass = passes[i];
+        if (pass === undefined)
+            break;
+        const end = pass.first + pass.count;
+        for (let node = pass.first; node < end && at < out.length; node += 1) {
+            out[at] = node;
+            at += 1;
+        }
+    }
+    return at;
+}
+/**
+ * A scratch array big enough for `needed` nodes, reusing the one given where it already fits.
+ *
+ * **`keptNodes` says the caller's array is "sized with the arena", and this is what makes that
+ * true.** It was not: the renderer sized its scratch with `MAX_DRAWS_PER_FRAME` while the arena
+ * it reads reallocates at twice its capacity whenever a frame outgrows it. `keptNodes` then
+ * stopped at `out.length` and the tail of the frame's passes was never replayed — no warning, no
+ * error, and a plausible picture missing whatever those passes drew.
+ *
+ * It was reachable with the draw ring nowhere near full, because a node is recorded per **verb**
+ * rather than per draw: overlays, scatter, plumes and text each record one.
+ *
+ * **What it costs** is a single allocation on the frame that first outgrows the scratch and none
+ * afterwards, because the caller keeps what comes back. **What would make it wrong** is a caller
+ * that discards the result and calls this again per frame, which is an allocation in a hot path;
+ * the arena's own doubling is what keeps the growth finite rather than per-frame.
+ */
+export function scratchFor(scratch, needed) {
+    return scratch.length >= needed ? scratch : new Int32Array(needed);
+}

package/dist/render/frame/resources.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Every attachment a frame can read or write, as a fixed table.
+ *
+ * Fixed rather than allocated, because this frame's composition is fixed: the same shadow
+ * cascades, the same scene target, the same bloom chain, every frame. The transient allocator
+ * and resource aliasing a frame graph is famous for would be machinery with no case here to
+ * serve.
+ *
+ * A mask is a `number` and not a bitset object. Thirty-one bits is more than the table needs,
+ * a number compares and combines in one instruction, and the scheduler does this per node.
+ */
+export declare const FRAME_RESOURCES: readonly ['sceneColor', 'sceneDepth', 'canvas', 'cascade0', 'cascade1', 'cascade2', 'pointShadows', 'probeCube', 'mirrorColor', 'mirrorDepth', 'bloomChain', 'aoTarget', 'depthSnapshot', 'inset'];
+export type FrameResource = (typeof FRAME_RESOURCES)[number];
+export declare const RESOURCE_COUNT: 14;
+/** The single bit that stands for one resource. */
+export declare function resourceBit(name: FrameResource): number;
+/** A mask of the named resources, for declaring what a node reads or writes. */
+export declare function maskOf(...names: FrameResource[]): number;
+/**
+ * The resources a mask names.
+ *
+ * For diagnostics and tests rather than for the frame: it allocates an array, so nothing on
+ * the per-frame path may call it.
+ */
+export declare function namesIn(mask: number): FrameResource[];

package/dist/render/frame/resources.js

@@ -0,0 +1,55 @@
+/**
+ * Every attachment a frame can read or write, as a fixed table.
+ *
+ * Fixed rather than allocated, because this frame's composition is fixed: the same shadow
+ * cascades, the same scene target, the same bloom chain, every frame. The transient allocator
+ * and resource aliasing a frame graph is famous for would be machinery with no case here to
+ * serve.
+ *
+ * A mask is a `number` and not a bitset object. Thirty-one bits is more than the table needs,
+ * a number compares and combines in one instruction, and the scheduler does this per node.
+ */
+export const FRAME_RESOURCES = [
+    'sceneColor',
+    'sceneDepth',
+    'canvas',
+    'cascade0',
+    'cascade1',
+    'cascade2',
+    /*
+     * The twelve point-shadow cubes are one bit, not twelve. They are baked together and
+     * sampled together, and nothing in the frame reads one without the others, so twelve bits
+     * would be twelve ways to express one fact — and twelve chances for a node to declare a
+     * subset that does not correspond to anything the renderer can actually do.
+     */
+    'pointShadows',
+    'probeCube',
+    'mirrorColor',
+    'mirrorDepth',
+    'bloomChain',
+    'aoTarget',
+    'depthSnapshot',
+    'inset',
+];
+export const RESOURCE_COUNT = FRAME_RESOURCES.length;
+const BITS = new Map(FRAME_RESOURCES.map((name, i) => [name, 1 << i]));
+/** The single bit that stands for one resource. */
+export function resourceBit(name) {
+    return BITS.get(name) ?? 0;
+}
+/** A mask of the named resources, for declaring what a node reads or writes. */
+export function maskOf(...names) {
+    let mask = 0;
+    for (const name of names)
+        mask |= resourceBit(name);
+    return mask;
+}
+/**
+ * The resources a mask names.
+ *
+ * For diagnostics and tests rather than for the frame: it allocates an array, so nothing on
+ * the per-frame path may call it.
+ */
+export function namesIn(mask) {
+    return FRAME_RESOURCES.filter((_, i) => (mask & (1 << i)) !== 0);
+}

package/dist/render/frame/schedule.d.ts

@@ -0,0 +1,37 @@
+import type { Arena } from './arena.ts';
+/**
+ * One render pass: a contiguous run of nodes sharing a write-set, and what happens to the
+ * attachments at each end of it.
+ */
+export interface ScheduledPass {
+    /** The resources this pass writes. */
+    writes: number;
+    /** Index of the first node in the run. */
+    first: number;
+    /** How many nodes the run holds. */
+    count: number;
+    /** Resources this pass clears rather than loads. */
+    clear: number;
+    /** Resources safe to discard at the end, because nothing later in the frame reads them. */
+    discard: number;
+}
+/**
+ * Group a frame's nodes into passes, and derive what happens to each attachment.
+ *
+ * **The order is the caller's and is never changed.** Blending and depth make *after*
+ * different from *before*, so an immediate-mode API's draw order carries meaning no
+ * dependency analysis may override. All this does is group adjacent compatible nodes and work
+ * out load and store from the reads that follow.
+ *
+ * **`liveOut` is what must survive this schedule**, and it is a parameter rather than a
+ * constant because the scheduler does not necessarily see the whole frame. During the
+ * migration a flush schedules only what has accumulated, so a resource written here may be
+ * read after the next flush — invisible from inside this call. The caller knows what is still
+ * live; this cannot work it out. The canvas belongs in it always, because nothing ever reads
+ * the canvas (it is presented, not sampled) and a purely read-driven rule would conclude it
+ * is safe to throw away.
+ *
+ * Allocates nothing: `out` is supplied by the caller and reused across frames, and the return
+ * value says how many of its entries were filled.
+ */
+export declare function schedule(arena: Arena, clearMask: number, liveOut: number, out: ScheduledPass[]): number;