@driftengine/core 3.61.0

package/dist/render/handleRegistry.js

@@ -0,0 +1,84 @@
+/**
+ * A slot table addressed by generational handles.
+ *
+ * **The handle arithmetic, and nothing about what a handle names.** It came out of `pass.ts`
+ * when a second registry wanted exactly this: two copies of a generation rule are two chances to
+ * get the invalidation wrong, and the failure mode is a handle answering to whoever took its slot
+ * next — a use-after-free that reads as a leak.
+ *
+ * The definition type is a parameter rather than a union of the two kinds it holds. A union would
+ * oblige every caller to narrow a value it already knows the type of, and would make adding a
+ * third kind an edit to this file rather than to the caller that wanted it.
+ */
+/** How many bits of a handle are the slot. 4,096 registered definitions is far past generous. */
+const SLOT_BITS = 12;
+const SLOT_MASK = (1 << SLOT_BITS) - 1;
+export function createHandleRegistry() {
+    return { definitions: [], generations: [], free: [] };
+}
+/**
+ * Take a slot and return the handle that names it.
+ *
+ * Handles start at 1: zero is a generation-0 slot-0 handle and would be indistinguishable from
+ * the number a caller gets from an uninitialised field, so generations start at 1 instead.
+ */
+export function registerIn(registry, definition) {
+    const slot = registry.free.pop() ?? registry.definitions.length;
+    registry.definitions[slot] = definition;
+    registry.generations[slot] ??= 1;
+    return ((registry.generations[slot] ?? 1) << SLOT_BITS) | slot;
+}
+/** The definition a handle names, or `undefined` if it names one that has been released. */
+export function definitionAt(registry, handle) {
+    if (handle <= 0)
+        return undefined;
+    const slot = handle & SLOT_MASK;
+    if (registry.generations[slot] !== handle >>> SLOT_BITS)
+        return undefined;
+    return registry.definitions[slot];
+}
+/**
+ * Release a slot.
+ *
+ * Guarded on the handle still being live, so calling it twice frees the slot once — a slot
+ * pushed onto `free` twice is a slot handed to two different definitions.
+ */
+export function unregisterIn(registry, handle) {
+    const definition = definitionAt(registry, handle);
+    if (definition === undefined)
+        return undefined;
+    const slot = handle & SLOT_MASK;
+    registry.definitions[slot] = undefined;
+    registry.generations[slot] = (registry.generations[slot] ?? 1) + 1;
+    registry.free.push(slot);
+    return definition;
+}
+/**
+ * Release every slot still held, handing each definition to the caller on the way out.
+ *
+ * **Teardown's half of `unregisterIn`, and it was missing.** Both renderers hold registries like
+ * this one and neither emptied one when it was disposed, so a definition kept whatever `init`
+ * built — a pipeline, a bind group, its buffers — for as long as the process lived. A private
+ * field going out of scope is not a GPU object being destroyed. Written here rather than once per
+ * backend for the reason this module exists at all: two copies of a lifetime rule are two chances
+ * to get it wrong, and the one that is wrong is the one nobody reads.
+ *
+ * `release` is the caller's, because the device object a definition must be handed is the only
+ * part of this that is per-backend — and on one of them there is a condition on handing it over
+ * at all.
+ *
+ * Each slot is released *before* its definition is told, so a `release` that reaches back into
+ * this registry finds a slot already gone rather than one it can free twice.
+ */
+export function drainRegistry(registry, release) {
+    for (let slot = 0; slot < registry.definitions.length; slot += 1) {
+        if (registry.definitions[slot] === undefined)
+            continue;
+        /* Rebuilt rather than remembered: the generation bump that invalidates the handles naming
+           this slot is `unregisterIn`'s to make, and making it twice is how a slot is freed twice. */
+        const handle = ((registry.generations[slot] ?? 1) << SLOT_BITS) | slot;
+        const definition = unregisterIn(registry, handle);
+        if (definition !== undefined)
+            release(definition);
+    }
+}

package/dist/render/iesProfile.d.ts

@@ -0,0 +1,64 @@
+/** Photometric profiles packed into one texture a light can index into. */
+/** What a reader produces, restated structurally so core imports no package. See `readIesProfile`. */
+export interface PhotometricProfile {
+    readonly verticalAngles: Float32Array;
+    readonly horizontalAngles: Float32Array;
+    readonly candela: Float32Array;
+    readonly maxCandela: number;
+}
+/**
+ * Columns across the atlas: one row per profile, sampled by vertical angle.
+ *
+ * **A power of two, and 128 rather than 64 because the interesting part of a real distribution is
+ * narrow.** A spot fixture puts its whole falloff inside a few degrees of the beam edge, and at 64
+ * columns that edge is two texels wide and reads as a step. What a larger number costs is four
+ * kilobytes a profile, which is nothing against the image it replaces.
+ */
+export declare const IES_ATLAS_WIDTH = 128;
+/**
+ * `planes` rows of intensity per profile, normalised to the profile's peak, indexed by angle.
+ *
+ * **Resampled to a regular grid here rather than in the reader**, because that is a decision about
+ * a texture and not about a file: LM-63 is dense where a distribution changes and sparse where it
+ * does not, and a shader cannot sample an irregular table without carrying it.
+ *
+ * **Asymmetric fixtures keep their horizontal planes as of 2026-08-27.** This function flattened
+ * to the first plane and said in its own comment what to reach for instead — "a row per horizontal
+ * plane with the light carrying a plane count" — and that is what this is. A street light and a
+ * wall washer are the fixtures that are not axially symmetric, and they are exactly the fixtures
+ * whose whole point is that they throw more one way than another.
+ *
+ * **One plane count for the atlas rather than one per profile**, and every profile is padded to
+ * it. The shader's row is `profile * planes + plane`; a per-profile count would need a second
+ * number in a light's record to divide by, and a light's record is where space is expensive.
+ * Padding a symmetric profile repeats its single row, which costs `width` floats a plane — half a
+ * kilobyte — against the image an IES profile replaces. **A set with nothing asymmetric in it
+ * comes out at one plane and is bit-identical to what this produced before planes existed**, which
+ * is what keeps the common case free.
+ *
+ * **The planes are resampled onto a regular 0-to-360 arc**, for the reason the vertical angles are
+ * resampled onto a fixed one: the shader maps an azimuth to a plane by arithmetic and carries no
+ * per-profile angle list to search. A file measuring 0 and 180 packed into four planes has its
+ * measured values at planes 0 and 2 and the interpolation between them at 1 and 3, which is what a
+ * fixture symmetric about its own axis actually throws.
+ *
+ * **A profile occupies `planes + 1` rows, and the extra one repeats the first.** That is what lets
+ * the shader do the whole azimuth blend in **one** fetch, with the texture's own linear filter
+ * between adjacent rows: without the wrap row the plane after the last would have to blend back to
+ * the first, which a fractional row cannot express — it would reach into the *next profile's*
+ * first plane instead. The alternative was two explicit fetches and a `mix`, which was written,
+ * measured at **+18,315 gzipped bytes on `core-only`** across the sixteen fragment permutations,
+ * and replaced by this. One row a profile is 512 bytes.
+ *
+ * **Normalised to each profile's own peak** because the shader multiplies it into a light's
+ * colour, which already carries the intensity a consumer chose. A profile that also carried
+ * absolute candela would multiply the two and make every IES light either black or blinding. The
+ * peak is the *profile's*, not the plane's: normalising each plane to itself would make every
+ * plane reach 1 and throw away the asymmetry this exists to carry.
+ */
+export declare function packIesAtlas(profiles: readonly PhotometricProfile[], width?: number): {
+    data: Float32Array;
+    width: number;
+    height: number;
+    planes: number;
+};

package/dist/render/iesProfile.js

@@ -0,0 +1,179 @@
+/** Photometric profiles packed into one texture a light can index into. */
+/**
+ * Columns across the atlas: one row per profile, sampled by vertical angle.
+ *
+ * **A power of two, and 128 rather than 64 because the interesting part of a real distribution is
+ * narrow.** A spot fixture puts its whole falloff inside a few degrees of the beam edge, and at 64
+ * columns that edge is two texels wide and reads as a step. What a larger number costs is four
+ * kilobytes a profile, which is nothing against the image it replaces.
+ */
+export const IES_ATLAS_WIDTH = 128;
+/**
+ * `planes` rows of intensity per profile, normalised to the profile's peak, indexed by angle.
+ *
+ * **Resampled to a regular grid here rather than in the reader**, because that is a decision about
+ * a texture and not about a file: LM-63 is dense where a distribution changes and sparse where it
+ * does not, and a shader cannot sample an irregular table without carrying it.
+ *
+ * **Asymmetric fixtures keep their horizontal planes as of 2026-08-27.** This function flattened
+ * to the first plane and said in its own comment what to reach for instead — "a row per horizontal
+ * plane with the light carrying a plane count" — and that is what this is. A street light and a
+ * wall washer are the fixtures that are not axially symmetric, and they are exactly the fixtures
+ * whose whole point is that they throw more one way than another.
+ *
+ * **One plane count for the atlas rather than one per profile**, and every profile is padded to
+ * it. The shader's row is `profile * planes + plane`; a per-profile count would need a second
+ * number in a light's record to divide by, and a light's record is where space is expensive.
+ * Padding a symmetric profile repeats its single row, which costs `width` floats a plane — half a
+ * kilobyte — against the image an IES profile replaces. **A set with nothing asymmetric in it
+ * comes out at one plane and is bit-identical to what this produced before planes existed**, which
+ * is what keeps the common case free.
+ *
+ * **The planes are resampled onto a regular 0-to-360 arc**, for the reason the vertical angles are
+ * resampled onto a fixed one: the shader maps an azimuth to a plane by arithmetic and carries no
+ * per-profile angle list to search. A file measuring 0 and 180 packed into four planes has its
+ * measured values at planes 0 and 2 and the interpolation between them at 1 and 3, which is what a
+ * fixture symmetric about its own axis actually throws.
+ *
+ * **A profile occupies `planes + 1` rows, and the extra one repeats the first.** That is what lets
+ * the shader do the whole azimuth blend in **one** fetch, with the texture's own linear filter
+ * between adjacent rows: without the wrap row the plane after the last would have to blend back to
+ * the first, which a fractional row cannot express — it would reach into the *next profile's*
+ * first plane instead. The alternative was two explicit fetches and a `mix`, which was written,
+ * measured at **+18,315 gzipped bytes on `core-only`** across the sixteen fragment permutations,
+ * and replaced by this. One row a profile is 512 bytes.
+ *
+ * **Normalised to each profile's own peak** because the shader multiplies it into a light's
+ * colour, which already carries the intensity a consumer chose. A profile that also carried
+ * absolute candela would multiply the two and make every IES light either black or blinding. The
+ * peak is the *profile's*, not the plane's: normalising each plane to itself would make every
+ * plane reach 1 and throw away the asymmetry this exists to carry.
+ */
+export function packIesAtlas(profiles, width = IES_ATLAS_WIDTH) {
+    /*
+     * **One row of ones when there is nothing to pack, rather than a zero-height texture.**
+     *
+     * A sampler declared in the shader must have a complete texture bound whether or not any branch
+     * reads it — the argument `emptyTexture.ts` makes — and a zero-height allocation is an
+     * `INVALID_VALUE` rather than an empty one. Ones rather than zeros because this value multiplies
+     * a light's colour: an all-zero fallback would switch off every light that reached it.
+     */
+    if (profiles.length === 0) {
+        return { data: new Float32Array(width).fill(1), width, height: 1, planes: 1 };
+    }
+    /* The widest fixture decides the grid, so no profile is resampled *down* and loses a lobe. */
+    let planes = 1;
+    for (const profile of profiles) {
+        planes = Math.max(planes, profile?.horizontalAngles.length ?? 1);
+    }
+    /* The wrap row: `planes + 1` per profile, the last repeating the first. See the note above. */
+    const rows = planes + 1;
+    const height = profiles.length * rows;
+    const data = new Float32Array(width * height);
+    for (let index = 0; index < profiles.length; index++) {
+        const profile = profiles[index];
+        for (let row = 0; row < rows; row++) {
+            const at = (index * rows + row) * width;
+            if (profile === undefined) {
+                data.fill(1, at, at + width);
+                continue;
+            }
+            /* Row `planes` is plane 0 again, which is what makes the blend wrap rather than bleed. */
+            packRow(profile, row % planes, planes, data, at, width);
+        }
+    }
+    return { data, width, height, planes };
+}
+/**
+ * Where a plane of the regular grid falls among the angles a file measured, as a pair and a mix.
+ *
+ * **Wrapped rather than clamped at the top**, which is the difference between an azimuth and a
+ * vertical angle: a fixture measured at 0 and 180 is symmetric about its own axis and 270 degrees
+ * is the same as 90, so the plane past the last measurement interpolates back toward the first.
+ * Clamping instead would flatten one whole side of every two-plane fixture.
+ *
+ * A file that measures a full 360 — the last angle equal to the first — is handled by the same
+ * arithmetic, because the wrap lands on that duplicate.
+ */
+function planeSpan(horizontal, plane, planes) {
+    const count = horizontal.length;
+    if (count <= 1)
+        return { lower: 0, upper: 0, mix: 0 };
+    const azimuth = (plane / planes) * 360;
+    let upper = 0;
+    while (upper < count && (horizontal[upper] ?? 0) <= azimuth)
+        upper += 1;
+    if (upper === 0)
+        return { lower: 0, upper: 0, mix: 0 };
+    if (upper >= count) {
+        /* Past the last measured plane: back toward the first, across whatever arc is left. */
+        const last = horizontal[count - 1] ?? 0;
+        const span = 360 - last + (horizontal[0] ?? 0);
+        return {
+            lower: count - 1,
+            upper: 0,
+            mix: span > 0 ? Math.min(1, Math.max(0, (azimuth - last) / span)) : 0,
+        };
+    }
+    const a = horizontal[upper - 1] ?? 0;
+    const b = horizontal[upper] ?? a;
+    return { lower: upper - 1, upper, mix: b > a ? (azimuth - a) / (b - a) : 0 };
+}
+/**
+ * One profile into one row, sampled at `width` even steps across a **fixed 0 to 180 degree arc**.
+ *
+ * **Fixed rather than the profile's own range, and that is what keeps a light's record to one
+ * slot.** A row spanning whatever a file happened to measure would need the light to carry the
+ * first angle and the span as well, so the shader could map an angle back into the row — three
+ * values where the froxel record has exactly one free. Pinning every row to the same arc makes the
+ * lookup `angle / 180`, and the row index is then all a light needs.
+ *
+ * **Outside the measured range a row holds the nearest measured value**, which is correct rather
+ * than merely safe: a downlight measured 0 to 90 emits nothing above the horizontal, and its last
+ * sample is already the near-zero that says so. **What would make it wrong** is a file measured
+ * over a partial arc that does *not* fall to zero at its end — a fixture with a documented cutoff
+ * — where clamping extends its last value across everything beyond. That is a real shape and it is
+ * rare, and the tell is a profile whose final candela is a large fraction of its peak.
+ */
+function packRow(profile, plane, planes, out, offset, width) {
+    const angles = profile.verticalAngles;
+    const count = angles.length;
+    const peak = profile.maxCandela > 0 ? profile.maxCandela : 1;
+    /* The candela grid is horizontal-major: all vertical angles of the first plane, then the next.
+       So a plane is a run of `count` values, and blending two planes is a blend of two runs. */
+    const span = planeSpan(profile.horizontalAngles, plane, planes);
+    const lowerAt = span.lower * count;
+    const upperAt = span.upper * count;
+    for (let column = 0; column < width; column++) {
+        /* Texel centres over the whole arc, so column 0 is 0 degrees and the last is 180. */
+        const angle = width === 1 ? 0 : (column / (width - 1)) * 180;
+        /*
+         * Linear between the two measured angles either side. A nearest-neighbour lookup on a table
+         * that is sparse in the flat regions produces visible steps exactly where the distribution is
+         * smooth, which reads as banding in the light rather than as a sampling choice.
+         */
+        let upper = 1;
+        while (upper < count && (angles[upper] ?? 0) < angle)
+            upper += 1;
+        const lower = Math.max(0, Math.min(upper - 1, count - 1));
+        const top = Math.min(upper, count - 1);
+        const a = angles[lower] ?? 0;
+        const b = angles[top] ?? a;
+        const mix = b > a ? Math.min(1, Math.max(0, (angle - a) / (b - a))) : 0;
+        /*
+         * Two interpolations, and the order is not arbitrary: vertical within each of the two planes
+         * either side, then horizontal between the two results. Blending the planes first and then
+         * sampling would be the same number for a linear grid and is not one for a real fixture,
+         * whose vertical lists are the same but whose lobes are not.
+         */
+        const lowPlane = interpolate(profile.candela, lowerAt, lower, top, mix);
+        const highPlane = span.lower === span.upper ? lowPlane : interpolate(profile.candela, upperAt, lower, top, mix);
+        out[offset + column] = (lowPlane + (highPlane - lowPlane) * span.mix) / peak;
+    }
+}
+/** One plane's value between two vertical samples, at `at` in the horizontal-major grid. */
+function interpolate(candela, at, lower, upper, mix) {
+    const low = candela[at + lower] ?? 0;
+    const high = candela[at + upper] ?? low;
+    return low + (high - low) * mix;
+}

package/dist/render/imageTexels.d.ts

@@ -0,0 +1,50 @@
+/**
+ * An image's texels, exactly as they were encoded — which a canvas cannot give you.
+ *
+ * **Every ordinary way of reading an image back in a browser is lossy where alpha varies, and this
+ * was measured rather than assumed.** A 2D canvas stores colour *premultiplied*: `drawImage`
+ * multiplies each channel by the alpha and `getImageData` divides it back out, so every value
+ * round-trips through `round(round(c * a / 255) * 255 / a)`. WebCodecs is no better — Chrome
+ * decodes a WebP with alpha to a premultiplied `BGRA` frame, and `VideoFrame.copyTo` un-premultiplies
+ * it, arriving at the same arithmetic. Both were run against a lossless WebP whose values are known:
+ * worst channel off by **3 of 255**, and every deviation predicted exactly by that expression.
+ *
+ * The one route that is exact is a texture upload with the unpack flag off and a read back, and
+ * that is what this is: 0 of 255 on the same file.
+ *
+ * **For a picture none of this matters and for data it is a corruption.** The case it was found on
+ * is a `.sog` Gaussian capture, whose `sh0` image carries three *codebook indices* in RGB beside an
+ * opacity in alpha — so a premultiplying read lands the index several entries away wherever a
+ * Gaussian is transparent, and the capture's colours come back tied to its own transparency. Any
+ * image used as a lookup rather than as a picture has the same problem.
+ *
+ * **Here rather than in the package that needed it**, because `AGENTS.md` allows raw WebGL only
+ * under `packages/core/src/render/` and this is raw WebGL. `@driftengine/splats` takes a decoder as
+ * a parameter for exactly this reason and a consumer hands it this one.
+ *
+ * **What it costs, stated because the driver says it out loud**: `readPixels` synchronises the
+ * pipeline, and Chrome logs *"GPU stall due to ReadPixels"* once per image. That is the price of
+ * exactness and it is paid at load rather than per frame — five stalls for a Gaussian capture,
+ * none afterwards. Nothing here belongs in a frame, and `AGENTS.md`'s rule about the hot path is
+ * the reason this is a loader and not a per-frame utility.
+ */
+/** One decoded image: 8-bit RGBA, row-major from the top left, unpremultiplied. */
+export interface ImageTexels {
+    readonly width: number;
+    readonly height: number;
+    readonly rgba: Uint8Array;
+}
+/** What turns an encoded image's bytes into texels. */
+export type ImageTexelDecoder = (bytes: Uint8Array, type?: string) => Promise<ImageTexels>;
+/**
+ * A decoder that reads texels back exactly, over a context of its own.
+ *
+ * **One context for every image it decodes**, created on the first call and kept: a WebGL context
+ * is a scarce resource — browsers cap them somewhere around sixteen — and one per image is a
+ * capture that stops decoding partway through with a context-lost warning.
+ *
+ * `preserveDrawingBuffer` is not set and nothing is ever drawn: the texture is attached to a
+ * framebuffer and read, which is the whole pipeline. `antialias: false` and `depth: false` because
+ * neither is allocated for a path that rasterises nothing.
+ */
+export declare function createImageTexelDecoder(): ImageTexelDecoder;

package/dist/render/imageTexels.js

@@ -0,0 +1,91 @@
+/**
+ * An image's texels, exactly as they were encoded — which a canvas cannot give you.
+ *
+ * **Every ordinary way of reading an image back in a browser is lossy where alpha varies, and this
+ * was measured rather than assumed.** A 2D canvas stores colour *premultiplied*: `drawImage`
+ * multiplies each channel by the alpha and `getImageData` divides it back out, so every value
+ * round-trips through `round(round(c * a / 255) * 255 / a)`. WebCodecs is no better — Chrome
+ * decodes a WebP with alpha to a premultiplied `BGRA` frame, and `VideoFrame.copyTo` un-premultiplies
+ * it, arriving at the same arithmetic. Both were run against a lossless WebP whose values are known:
+ * worst channel off by **3 of 255**, and every deviation predicted exactly by that expression.
+ *
+ * The one route that is exact is a texture upload with the unpack flag off and a read back, and
+ * that is what this is: 0 of 255 on the same file.
+ *
+ * **For a picture none of this matters and for data it is a corruption.** The case it was found on
+ * is a `.sog` Gaussian capture, whose `sh0` image carries three *codebook indices* in RGB beside an
+ * opacity in alpha — so a premultiplying read lands the index several entries away wherever a
+ * Gaussian is transparent, and the capture's colours come back tied to its own transparency. Any
+ * image used as a lookup rather than as a picture has the same problem.
+ *
+ * **Here rather than in the package that needed it**, because `AGENTS.md` allows raw WebGL only
+ * under `packages/core/src/render/` and this is raw WebGL. `@driftengine/splats` takes a decoder as
+ * a parameter for exactly this reason and a consumer hands it this one.
+ *
+ * **What it costs, stated because the driver says it out loud**: `readPixels` synchronises the
+ * pipeline, and Chrome logs *"GPU stall due to ReadPixels"* once per image. That is the price of
+ * exactness and it is paid at load rather than per frame — five stalls for a Gaussian capture,
+ * none afterwards. Nothing here belongs in a frame, and `AGENTS.md`'s rule about the hot path is
+ * the reason this is a loader and not a per-frame utility.
+ */
+/**
+ * A decoder that reads texels back exactly, over a context of its own.
+ *
+ * **One context for every image it decodes**, created on the first call and kept: a WebGL context
+ * is a scarce resource — browsers cap them somewhere around sixteen — and one per image is a
+ * capture that stops decoding partway through with a context-lost warning.
+ *
+ * `preserveDrawingBuffer` is not set and nothing is ever drawn: the texture is attached to a
+ * framebuffer and read, which is the whole pipeline. `antialias: false` and `depth: false` because
+ * neither is allocated for a path that rasterises nothing.
+ */
+export function createImageTexelDecoder() {
+    let gl = null;
+    let texture = null;
+    let framebuffer = null;
+    return async (bytes, type = 'image/webp') => {
+        const bitmap = await createImageBitmap(new Blob([bytes], { type }), {
+            /* Both off, and both matter. Premultiplying here is the loss this module exists to avoid;
+               a colour-space conversion would rewrite values that are not colours at all. */
+            premultiplyAlpha: 'none',
+            colorSpaceConversion: 'none',
+        });
+        if (gl === null) {
+            const canvas = typeof OffscreenCanvas === 'undefined'
+                ? document.createElement('canvas')
+                : new OffscreenCanvas(1, 1);
+            gl = canvas.getContext('webgl2', {
+                alpha: true,
+                antialias: false,
+                depth: false,
+                stencil: false,
+            });
+            if (gl === null) {
+                bitmap.close();
+                throw new Error('createImageTexelDecoder: no WebGL2 context, and no other browser API reads an ' +
+                    'image back without premultiplying it. Supply a decoder of your own.');
+            }
+            texture = gl.createTexture();
+            framebuffer = gl.createFramebuffer();
+        }
+        const width = bitmap.width;
+        const height = bitmap.height;
+        gl.bindTexture(gl.TEXTURE_2D, texture);
+        gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+        gl.pixelStorei(gl.UNPACK_COLORSPACE_CONVERSION_WEBGL, gl.NONE);
+        gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, gl.RGBA, gl.UNSIGNED_BYTE, bitmap);
+        bitmap.close();
+        gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
+        if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
+            gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+            throw new Error('createImageTexelDecoder: this driver will not read back an RGBA8 texture.');
+        }
+        const rgba = new Uint8Array(width * height * 4);
+        gl.readPixels(0, 0, width, height, gl.RGBA, gl.UNSIGNED_BYTE, rgba);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        return { width, height, rgba };
+    };
+}

package/dist/render/instancedMesh.d.ts

@@ -0,0 +1,48 @@
+import type { MeshData } from './mesh.ts';
+/**
+ * One base mesh drawn many times in a single call.
+ *
+ * A field of grass is tens of thousands of copies of the same few triangles.
+ * Submitted individually that is tens of thousands of draw calls, which is the
+ * one thing a browser renderer cannot absorb; as instances it is one call and
+ * the GPU does the rest. This is what makes "dress the world" affordable at all.
+ *
+ * Per-instance attributes advance once per instance rather than once per vertex
+ * (`vertexAttribDivisor`), so the base mesh is uploaded once and never again.
+ */
+export interface InstanceData {
+    /** 3 floats each: world position. */
+    readonly positions: Float32Array;
+    /** 2 floats each: uniform scale, then yaw in radians. */
+    readonly scaleAndYaw: Float32Array;
+    /** 3 floats each: multiplied into the base mesh's colour. */
+    readonly tints: Float32Array;
+    /**
+     * 3 floats each: how far this instance bends, how much the gust moves it,
+     * and a phase offset.
+     *
+     * Per instance rather than global so a field does not sway in lockstep —
+     * uniform motion is the single clearest sign that foliage is a texture with
+     * an animation on it rather than many separate plants.
+     */
+    readonly windResponse: Float32Array;
+    readonly capacity: number;
+    /** How many instances are live; the rest of the buffer is ignored. */
+    count: number;
+}
+export declare function createInstanceData(capacity: number): InstanceData;
+export declare function writeInstance(data: InstanceData, index: number, x: number, y: number, z: number, scale: number, yaw: number, tintR: number, tintG: number, tintB: number, bend: number, flutter: number, phase: number): void;
+export declare class InstancedMesh {
+    private readonly vao;
+    private readonly buffers;
+    private readonly indexCount;
+    private readonly positionBuffer;
+    private readonly scaleBuffer;
+    private readonly tintBuffer;
+    private readonly windBuffer;
+    constructor(gl: WebGL2RenderingContext, base: MeshData, capacity: number);
+    /** Upload placement. Called at load; scatter does not move once placed. */
+    upload(gl: WebGL2RenderingContext, data: InstanceData): void;
+    draw(gl: WebGL2RenderingContext, count: number): void;
+    dispose(gl: WebGL2RenderingContext): void;
+}

package/dist/render/instancedMesh.js

@@ -0,0 +1,127 @@
+export function createInstanceData(capacity) {
+    return {
+        positions: new Float32Array(capacity * 3),
+        scaleAndYaw: new Float32Array(capacity * 2),
+        tints: new Float32Array(capacity * 3),
+        windResponse: new Float32Array(capacity * 3),
+        capacity,
+        count: 0,
+    };
+}
+export function writeInstance(data, index, x, y, z, scale, yaw, tintR, tintG, tintB, bend, flutter, phase) {
+    if (index < 0 || index >= data.capacity) {
+        throw new Error(`Instance ${index} is outside capacity ${data.capacity}`);
+    }
+    const p = index * 3;
+    data.positions[p] = x;
+    data.positions[p + 1] = y;
+    data.positions[p + 2] = z;
+    const s = index * 2;
+    data.scaleAndYaw[s] = scale;
+    data.scaleAndYaw[s + 1] = yaw;
+    data.tints[p] = tintR;
+    data.tints[p + 1] = tintG;
+    data.tints[p + 2] = tintB;
+    data.windResponse[p] = bend;
+    data.windResponse[p + 1] = flutter;
+    data.windResponse[p + 2] = phase;
+}
+export class InstancedMesh {
+    vao;
+    buffers = [];
+    indexCount;
+    positionBuffer;
+    scaleBuffer;
+    tintBuffer;
+    windBuffer;
+    constructor(gl, base, capacity) {
+        /*
+         * **Refused rather than dropped.** The per-vertex channel sits at location 13, which this path
+         * spends on `aInstanceModel2` — eleven base attributes plus five per-instance is exactly the
+         * sixteen WebGL2 guarantees, so there is nothing left to put it in. Drawing the mesh anyway
+         * would read the absent-attribute constant and produce a plausible picture: leaves that never
+         * move, a cave face at full sun, a pane at full opacity, with nothing anywhere saying why.
+         * That is the silent no-op `AGENTS.md` forbids, so it throws at construction instead.
+         *
+         * **The escape hatch is written down and untaken**: the instance tint could ride in the `w`
+         * lanes of the four model columns, which an affine matrix leaves unused, freeing location 15
+         * — at the cost of narrowing instance transforms to affine and making a projective one
+         * silently wrong. Not paid for yet, because the obvious instanced case for sway is a field of
+         * vegetation and `ScatterBatch` already draws that with wind of its own. A consumer filing
+         * instanced geometry that needs a lane is what reverses it.
+         */
+        if (base.channel !== undefined) {
+            throw new Error('InstancedMesh: this mesh carries a per-vertex channel, which needs attribute location ' +
+                '13, and an instanced draw already spends 11 through 15 on its transform and tint. ' +
+                'Draw it as an ordinary mesh, or drop the channel — the sway, sky and alpha lanes ' +
+                'cannot reach an instanced pipeline.');
+        }
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('InstancedMesh: createVertexArray failed');
+        this.vao = vao;
+        gl.bindVertexArray(vao);
+        const make = () => {
+            const buffer = gl.createBuffer();
+            if (buffer === null)
+                throw new Error('InstancedMesh: createBuffer failed');
+            this.buffers.push(buffer);
+            return buffer;
+        };
+        // Base mesh: divisor 0, so these advance per vertex as usual.
+        const attach = (data, location, size) => {
+            gl.bindBuffer(gl.ARRAY_BUFFER, make());
+            gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);
+            gl.enableVertexAttribArray(location);
+            gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+        };
+        attach(base.positions, 0, 3);
+        attach(base.normals, 1, 3);
+        attach(base.colors, 2, 3);
+        const indexBuffer = make();
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
+        gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, base.indices, gl.STATIC_DRAW);
+        this.indexCount = base.indices.length;
+        // Per-instance: divisor 1, so each advances once per copy rather than once
+        // per vertex. Sized to capacity now and rewritten later, because resizing a
+        // buffer mid-frame is a stall.
+        const instanced = (location, size) => {
+            const buffer = make();
+            gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+            gl.bufferData(gl.ARRAY_BUFFER, capacity * size * 4, gl.DYNAMIC_DRAW);
+            gl.enableVertexAttribArray(location);
+            gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+            gl.vertexAttribDivisor(location, 1);
+            return buffer;
+        };
+        this.positionBuffer = instanced(3, 3);
+        this.scaleBuffer = instanced(4, 2);
+        this.tintBuffer = instanced(5, 3);
+        this.windBuffer = instanced(6, 3);
+        gl.bindVertexArray(null);
+    }
+    /** Upload placement. Called at load; scatter does not move once placed. */
+    upload(gl, data) {
+        const put = (buffer, values, perInstance) => {
+            gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+            gl.bufferSubData(gl.ARRAY_BUFFER, 0, values.subarray(0, data.count * perInstance));
+        };
+        put(this.positionBuffer, data.positions, 3);
+        put(this.scaleBuffer, data.scaleAndYaw, 2);
+        put(this.tintBuffer, data.tints, 3);
+        put(this.windBuffer, data.windResponse, 3);
+        gl.bindBuffer(gl.ARRAY_BUFFER, null);
+    }
+    draw(gl, count) {
+        if (count <= 0)
+            return;
+        gl.bindVertexArray(this.vao);
+        gl.drawElementsInstanced(gl.TRIANGLES, this.indexCount, gl.UNSIGNED_INT, 0, count);
+        gl.bindVertexArray(null);
+    }
+    dispose(gl) {
+        for (const buffer of this.buffers)
+            gl.deleteBuffer(buffer);
+        gl.deleteVertexArray(this.vao);
+    }
+}