@driftengine/core 3.61.0

package/src/render/envProbeArray.ts

@@ -0,0 +1,201 @@
+/** Every probe in a grid as one array texture, and the scratch a bake fills it through. */
+
+import { ggxMaxLevelFor, irradianceLevelFor, roughnessForLevel } from './prefilterEnvMap.ts';
+
+/**
+ * What one level of one layer is for, since the chain carries two different integrals.
+ *
+ * Levels up to `ggxMaxLevel` are the reflection, convolved against the GGX lobe at the roughness
+ * `roughnessForLevel` gives them. The level above that is the diffuse ambient, convolved against
+ * the cosine. They are the same pass with a different weight, and telling them apart is a uniform.
+ */
+export type ProbeLevelKind = 'radiance' | 'irradiance';
+
+/**
+ * Every probe of a grid as one `TEXTURE_2D_ARRAY` of octahedral maps.
+ *
+ * **One binding for any number of probes, which is the whole design.** GLSL ES cannot index a
+ * sampler array with a non-constant expression, so a grid of cubes would need a `samplerCube` each
+ * and a branch chain over them — the shape twelve point-shadow cubemaps had before
+ * `pointShadowArray.ts`, and the reason that file exists. A layer index has no such limit.
+ *
+ * **It replaces the `samplerCube` rather than joining it.** Fifteen of WebGL2's guaranteed sixteen
+ * texture units are spent, and `REFRACT_SCENE_TEXTURE_UNIT`'s comment says what the next sampler
+ * has to do about that: fold into an existing binding. This binds where the probe cube used to,
+ * and the irradiance level folds the diffuse term in beside the reflection, so the grid costs no
+ * units at all and unit 15 stays free.
+ *
+ * **The chain stops at the irradiance level.** `texStorage3D` may allocate fewer levels than a
+ * full chain, so there is nothing above it — a 256 edge is six levels rather than nine, and the
+ * levels that would have held one, four and sixteen texels are not allocated at all.
+ */
+export class EnvProbeArray {
+  /** The array the lit pass samples. Octahedral, one layer a probe, gutter included. */
+  readonly texture: WebGLTexture;
+  /** Texels a side, including the one-texel gutter `octInsetUv` insets past. */
+  readonly edge: number;
+  readonly layers: number;
+  /** The coarsest level the reflection reaches, which is `uEnvironmentMaxLod`. */
+  readonly ggxMaxLevel: number;
+  /** The level holding the cosine convolution, one above the reflection's coarsest. */
+  readonly irradianceLevel: number;
+
+  private readonly framebuffer: WebGLFramebuffer;
+  /** One flag a layer, because a grid may be baked a probe at a time across frames. */
+  private readonly baked: Uint8Array;
+  private bakedCount = 0;
+  /**
+   * Set once if the allocation is refused, and never cleared.
+   *
+   * A grid is an improvement to an appearance rather than a requirement, exactly as one probe was:
+   * a device that cannot afford the layers keeps the sky-and-ground gradient and loses nothing
+   * else. Sixty-four layers at the default edge is 43.7 MB, which is affordable on the parts this
+   * engine targets and is not affordable everywhere.
+   */
+  private unusable = false;
+
+  constructor(gl: WebGL2RenderingContext, edge: number, layers: number, floatColor: boolean) {
+    this.edge = edge;
+    this.layers = Math.max(1, Math.trunc(layers));
+    this.ggxMaxLevel = ggxMaxLevelFor(edge);
+    this.irradianceLevel = irradianceLevelFor(edge);
+    this.baked = new Uint8Array(this.layers);
+
+    const texture = gl.createTexture();
+    if (texture === null) throw new Error('EnvProbeArray: createTexture failed');
+    this.texture = texture;
+
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
+    /*
+     * **Drained once before the allocation, because `getError` reports and clears.** Without this
+     * the check below answers for whatever happened earlier in the frame, and a grid would stand
+     * down over somebody else's mistake. One call rather than a loop: a context that answers an
+     * error forever is a context this would never leave.
+     */
+    gl.getError();
+    gl.texStorage3D(
+      gl.TEXTURE_2D_ARRAY,
+      /* Up to and including the irradiance level, and nothing above it. */
+      this.irradianceLevel + 1,
+      floatColor ? gl.RGBA16F : gl.RGBA8,
+      edge,
+      edge,
+      this.layers,
+    );
+    /*
+     * **`LINEAR_MIPMAP_NEAREST`, and the choice is a statement rather than a saving.** A level's
+     * gutter is one texel wide, so its inset in normalised coordinates is `1 / edge` and differs
+     * between levels; hardware trilinear applies one coordinate to both levels it blends, so one
+     * of the two would be read at the wrong inset — by a thirty-second of the map at the top of
+     * the chain. The shader fetches two levels at their own insets and mixes them, so the only
+     * filtering asked of the hardware is bilinear inside one level.
+     */
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    /*
+     * Clamped, and the gutter is what makes that correct. An octahedral map's border is a fold
+     * rather than an edge, so `CLAMP_TO_EDGE` repeating the last real texel would be wrong by
+     * 4.6e-2 in direction; the gutter holds the folded texel and the inset keeps every sample
+     * inside it, which is measured in `octahedral.test.ts`.
+     */
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+
+    if (gl.getError() !== gl.NO_ERROR) {
+      this.unusable = true;
+      console.warn(
+        `[driftengine] this device would not allocate ${this.layers} environment probe layers at ` +
+          `${edge}x${edge}. Reflective surfaces keep the sky-and-ground gradient and diffuse ` +
+          'ambient stays whatever the scene set. Nothing else is affected.',
+      );
+    }
+
+    const framebuffer = gl.createFramebuffer();
+    if (framebuffer === null) throw new Error('EnvProbeArray: createFramebuffer failed');
+    this.framebuffer = framebuffer;
+  }
+
+  /**
+   * Convolve one probe's captured cube into one layer, every level of it.
+   *
+   * **The caller draws, and this owns the target**, which is the split `ReflectionProbe.prefilter`
+   * already makes with the pass that convolves: a probe has no business knowing what a shader is,
+   * and a pass has no business knowing which layer it is filling.
+   *
+   * **One draw a level rather than six.** A cube's convolution runs the triangle once per face per
+   * level; an octahedral map has no faces, so a level is one draw and a probe's convolution is six
+   * times fewer of them than the cube it replaces.
+   *
+   * **The source is a different texture object from the target and that is not tidiness.** WebGL2's
+   * rendering-feedback-loop check is per texture object rather than per image, so a draw that
+   * samples the array while any layer of it is attached is `INVALID_OPERATION` — on a layer it does
+   * not even write. `pointShadowArray.ts` records paying for this on a probe before that file
+   * existed. Here the source is the scratch cube and the target is the array, so it cannot arise.
+   */
+  convolve(
+    gl: WebGL2RenderingContext,
+    layer: number,
+    run: (level: number, roughness: number, kind: ProbeLevelKind) => void,
+  ): void {
+    if (this.unusable) return;
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+    for (let level = 0; level <= this.irradianceLevel; level++) {
+      /* A level is half the width of the one below it, and the viewport has to say so or the
+         triangle covers a quarter of the target and leaves the rest at whatever was there. */
+      const size = Math.max(1, this.edge >> level);
+      gl.viewport(0, 0, size, size);
+      gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, this.texture, level, layer);
+      if (level === 0 && gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
+        this.unusable = true;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        console.warn(
+          '[driftengine] this driver will not render into an environment probe layer, so ' +
+            'reflective surfaces keep the sky-and-ground approximation. Nothing else is affected.',
+        );
+        return;
+      }
+      const irradiance = level === this.irradianceLevel;
+      run(
+        level,
+        irradiance ? 1 : roughnessForLevel(level, this.ggxMaxLevel),
+        irradiance ? 'irradiance' : 'radiance',
+      );
+    }
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    if (this.baked[layer] !== 1) {
+      this.baked[layer] = 1;
+      this.bakedCount++;
+    }
+  }
+
+  /**
+   * Whether the shader may sample this, which needs **every** layer filled.
+   *
+   * A grid baked a probe a frame passes through a state where some layers hold whatever the driver
+   * left in them, and a fragment blending eight corners reads four of those. The gate is therefore
+   * the whole grid rather than any part of it — the same rule one probe already had, where
+   * `uEnvironmentEnabled` stayed at zero until a bake finished, for the same reason: a car
+   * mirroring uninitialised memory is worse than a car mirroring a gradient.
+   */
+  get ready(): boolean {
+    return !this.unusable && this.bakedCount === this.layers;
+  }
+
+  /** How many layers have been convolved, for a caller pacing a bake across frames. */
+  get filled(): number {
+    return this.bakedCount;
+  }
+
+  /** Whether this allocated at all. False means the scene renders without a grid. */
+  get usable(): boolean {
+    return !this.unusable;
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    gl.deleteFramebuffer(this.framebuffer);
+    gl.deleteTexture(this.texture);
+    this.baked.fill(0);
+    this.bakedCount = 0;
+  }
+}

package/src/render/equirectToCube.ts

@@ -0,0 +1,160 @@
+/** 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: readonly {
+  readonly forward: readonly [number, number, number];
+  readonly basisX: readonly [number, number, number];
+  readonly basisY: readonly [number, number, number];
+}[] = [
+  { 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] },
+];
+
+/** What a decoded `.hdr` looks like, restated structurally so this imports no package. */
+export interface EquirectSource {
+  readonly width: number;
+  readonly height: number;
+  /** `width * height * 3` linear values, row-major from the top. */
+  readonly data: Float32Array;
+}
+
+/**
+ * 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: EquirectSource, size: number): Float32Array[] {
+  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: Float32Array[] = [];
+  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: EquirectSource,
+  dx: number,
+  dy: number,
+  dz: number,
+  out: Float32Array,
+  at: number,
+): void {
+  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: number, extent: number): number {
+  const wrapped = value % extent;
+  return wrapped < 0 ? wrapped + extent : wrapped;
+}
+
+/** Latitude clamps: there is nothing above the zenith to blend with. */
+function clamp(value: number, extent: number): number {
+  return value < 0 ? 0 : value >= extent ? extent - 1 : value;
+}

package/src/render/flockGeometry.ts

@@ -0,0 +1,53 @@
+/**
+ * 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: readonly (readonly [number, number])[] = [
+  [-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: readonly number[] = [1, 0, 0, 1, 0, 0];
+
+/** 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 function buildFlockGeometry(count: number): FlockGeometry {
+  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] as readonly [number, number];
+      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/src/render/flockRenderer.ts

@@ -0,0 +1,111 @@
+import type { FrameView } from './frameView.ts';
+import type { Vec3 } from '../math/color.ts';
+import { compileProgram, uniformLocations } from './shader.ts';
+import { FLOCK_FRAG, FLOCK_VERT } from './shaders/flock.ts';
+import { buildFlockGeometry } from './flockGeometry.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 class FlockRenderer {
+  private readonly program: WebGLProgram;
+  private readonly uniforms: Record<string, WebGLUniformLocation>;
+  private readonly vao: WebGLVertexArrayObject;
+  private readonly buffers: WebGLBuffer[] = [];
+  private readonly vertexCount: number;
+
+  constructor(gl: WebGL2RenderingContext, count: number) {
+    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: Float32Array, location: number, size: number): void => {
+      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: WebGL2RenderingContext,
+    camera: FrameView,
+    timeSeconds: number,
+    params: FlockParams,
+    tint: Vec3,
+    windX = 0,
+    windZ = 0,
+  ): void {
+    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: WebGL2RenderingContext): void {
+    for (const buffer of this.buffers) gl.deleteBuffer(buffer);
+    gl.deleteVertexArray(this.vao);
+    gl.deleteProgram(this.program);
+  }
+}

package/src/render/frame/arena.ts

@@ -0,0 +1,93 @@
+/**
+ * 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;
+/*
+ * Slot 5 is reserved for the handle slice the executor will need. It is written as zero
+ * until then so the stride does not change when it is used, and every offset above stays
+ * where it is.
+ */
+
+export interface Arena {
+  nodes: Int32Array;
+  count: number;
+  /** The most nodes any frame has recorded, so growth converges instead of repeating. */
+  highWater: number;
+}
+
+export function createArena(capacity: number): Arena {
+  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): void {
+  arena.count = 0;
+}
+
+export function nodeCount(arena: Arena): number {
+  return arena.count;
+}
+
+/** Record one node and return its index. */
+export function recordNode(
+  arena: Arena,
+  verb: number,
+  reads: number,
+  writes: number,
+  state: number,
+  matrix: number,
+): number {
+  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: Arena, at: number): number {
+  return arena.nodes[at * NODE_STRIDE + VERB] ?? 0;
+}
+
+export function nodeReads(arena: Arena, at: number): number {
+  return arena.nodes[at * NODE_STRIDE + READS] ?? 0;
+}
+
+export function nodeWrites(arena: Arena, at: number): number {
+  return arena.nodes[at * NODE_STRIDE + WRITES] ?? 0;
+}
+
+export function nodeState(arena: Arena, at: number): number {
+  return arena.nodes[at * NODE_STRIDE + STATE] ?? 0;
+}
+
+export function nodeMatrix(arena: Arena, at: number): number {
+  return arena.nodes[at * NODE_STRIDE + MATRIX] ?? 0;
+}

package/src/render/frame/index.ts

@@ -0,0 +1,29 @@
+/**
+ * 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';