@driftengine/core 3.61.0

package/dist/render/shadowMap.js

@@ -0,0 +1,80 @@
+/**
+ * Single-cascade directional shadow map: one depth texture, one extra draw of
+ * the static world per update.
+ *
+ * Filtering belongs to the receiving material shader, so the depth target can
+ * stay a single-sample texture shared by every mesh pass.
+ *
+ * Note this is a depth *render target*, not an art texture: AGENTS.md's
+ * "zero textures" rule is about the art direction (no image assets in the
+ * payload), and nothing here adds a byte to it.
+ */
+import { DEFAULT_RENDER_QUALITY } from './renderQuality.js';
+export class ShadowMap {
+    size;
+    texture;
+    framebuffer;
+    constructor(gl, size = DEFAULT_RENDER_QUALITY.directionalShadowMapSize) {
+        this.size = size;
+        const texture = gl.createTexture();
+        if (texture === null)
+            throw new Error('ShadowMap: createTexture failed');
+        this.texture = texture;
+        gl.bindTexture(gl.TEXTURE_2D, texture);
+        gl.texStorage2D(gl.TEXTURE_2D, 1, gl.DEPTH_COMPONENT24, size, size);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        // Clamp so anything outside the light frustum samples the border and is
+        // treated as lit, rather than wrapping into a spurious shadow.
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        const framebuffer = gl.createFramebuffer();
+        if (framebuffer === null)
+            throw new Error('ShadowMap: createFramebuffer failed');
+        this.framebuffer = framebuffer;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, texture, 0);
+        // Depth-only: without this WebGL expects a colour attachment.
+        gl.drawBuffers([gl.NONE]);
+        gl.readBuffer(gl.NONE);
+        const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
+        if (status !== gl.FRAMEBUFFER_COMPLETE) {
+            /*
+             * A lost context reports every attachment unusable, and that is not a
+             * misconfiguration the caller can fix — see planarReflection.ts. Init still throws,
+             * because the context cannot be lost before it exists.
+             */
+            if (gl.isContextLost())
+                return;
+            throw new Error(`ShadowMap: framebuffer incomplete (0x${status.toString(16)})`);
+        }
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    /** Bind as the render target and clear. Caller then draws the casters. */
+    begin(gl) {
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+        gl.viewport(0, 0, this.size, this.size);
+        gl.clear(gl.DEPTH_BUFFER_BIT);
+        /*
+         * Store the face nearest the sun. Culling front faces stores the far side
+         * and moves a box or limb through its own thickness, which is exactly the
+         * detached-shadow failure. A small slope-aware raster offset separates the
+         * stored caster from its receiver without moving the receiver differently
+         * on each face; receiver-plane compensation handles the PCF taps.
+         */
+        gl.enable(gl.CULL_FACE);
+        gl.cullFace(gl.BACK);
+        gl.enable(gl.POLYGON_OFFSET_FILL);
+        gl.polygonOffset(1.1, 4);
+    }
+    end(gl) {
+        gl.disable(gl.POLYGON_OFFSET_FILL);
+        gl.cullFace(gl.BACK);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    }
+    dispose(gl) {
+        gl.deleteFramebuffer(this.framebuffer);
+        gl.deleteTexture(this.texture);
+    }
+}

package/dist/render/shotPlacement.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Where a shot puts the camera, and what it frames.
+ *
+ * Pure: a shot plus a subject pose plus how far into the shot it is, in and a
+ * placement out. No state, no smoothing, no collision — those belong to the rig
+ * (`cinematicCamera.ts`), and keeping them apart is what lets the rig evaluate
+ * the *same* shot at two poses in a frame, which is how it learns the speed its
+ * target is travelling at instead of trailing behind it.
+ *
+ * Game-agnostic, like the rig: a shot is a placement rule and a subject.
+ * Nothing here knows what a character is.
+ */
+export type ShotKind = 'chase' | 'lowWide' | 'orbit' | 'flyby' | 'overhead' | 'lookAt';
+export interface ShotParams {
+    readonly kind: ShotKind;
+    /** How far the camera sits from its subject, in metres. */
+    readonly distance: number;
+    /** How high above it. */
+    readonly height: number;
+    readonly fovDeg: number;
+    /** Radians per second, for `orbit`. */
+    readonly orbitRate?: number;
+    /**
+     * How long this shot is going to hold, in seconds, when the caller knows.
+     *
+     * Only motion *within* a shot needs it, and only to know where the end is so
+     * it can arrive there rather than being cut off mid-travel. An `orbit` given a
+     * hold eases across the whole of it; one without eases in and then keeps its
+     * rate, because inventing a duration would be worse than not having one.
+     */
+    readonly holdSec?: number;
+    /**
+     * A fixed world point. `lookAt` frames it; `flyby` uses it as the station to
+     * shoot from. Ignored by the others.
+     */
+    readonly anchor?: readonly [number, number, number];
+}
+/** Where the subject is and which way it faces. Caller-owned and mutated in place. */
+export interface SubjectPose {
+    x: number;
+    y: number;
+    z: number;
+    yaw: number;
+}
+/** The answer: caller-owned, written in place, never allocated per frame. */
+export interface ShotPlacement {
+    /** Where the shot wants the camera, before smoothing and before collision. */
+    wantX: number;
+    wantY: number;
+    wantZ: number;
+    /** What it wants in the middle of frame. */
+    lookX: number;
+    lookY: number;
+    lookZ: number;
+    fovDeg: number;
+}
+export declare function createShotPlacement(): ShotPlacement;
+/**
+ * The station a `flyby` shoots from, when the shot did not name one.
+ *
+ * Split out because the station is captured once, on the cut, and then held: a
+ * flyby that follows is a chase cam, and the whole point is a camera the world
+ * moves past.
+ */
+export declare function flybyStation(shot: ShotParams, pose: SubjectPose, out: [number, number, number]): void;
+/**
+ * Place `shot` for a subject at `pose`, `ageSec` into the shot.
+ *
+ * `station` is only read by `flyby`; pass the rig's held station.
+ */
+export declare function placeShot(shot: ShotParams, pose: SubjectPose, ageSec: number, station: readonly number[], out: ShotPlacement): void;
+/**
+ * Clamp a shot parameter into something a camera can use.
+ *
+ * Shots are produced by a director working from measured data — a run that
+ * lasted no time, an anchor at the origin — and a NaN reaching a view matrix
+ * blanks the entire frame without raising anything, which is the worst way for a
+ * bad number to fail.
+ */
+export declare function shotParam(value: number | undefined, fallback: number, min: number, max: number): number;

package/dist/render/shotPlacement.js

@@ -0,0 +1,183 @@
+import { clamp } from '../math/scalar.js';
+/**
+ * How far a `lookAt` shot's aim may sit from its subject, as a share of the shot's own
+ * camera distance.
+ *
+ * A *share of the gap* was the first attempt and it is wrong for the case that matters:
+ * a subject thirty metres past its anchor, with even a modest share left behind, pulls the
+ * aim further back than the camera stands — so the shot looks the wrong way down its own
+ * axis and the subject is behind the lens. Clamping the offset in metres instead cannot do
+ * that, because it is measured against the distance the camera is placed at.
+ *
+ * At half, the aim is never more than half the camera's distance from the subject, which
+ * keeps them near the middle of frame at any separation. While the two are closer than
+ * that the aim lands on the anchor exactly, which is the composition the shot exists for.
+ */
+const LOOK_AT_ANCHOR_PULL = 0.5;
+export function createShotPlacement() {
+    return { wantX: 0, wantY: 0, wantZ: 0, lookX: 0, lookY: 0, lookZ: 0, fovDeg: 70 };
+}
+/**
+ * How long an orbit with no stated hold spends getting up to speed.
+ *
+ * Long enough to read as a camera being pushed rather than switched on, short
+ * enough that a two-second shot still travels. A stated hold is always better —
+ * it gets an ease at *both* ends — and the director supplies one.
+ */
+const ORBIT_EASE_SEC = 1.2;
+/**
+ * The station a `flyby` shoots from, when the shot did not name one.
+ *
+ * Split out because the station is captured once, on the cut, and then held: a
+ * flyby that follows is a chase cam, and the whole point is a camera the world
+ * moves past.
+ */
+export function flybyStation(shot, pose, out) {
+    const anchor = shot.anchor;
+    if (anchor !== undefined) {
+        out[0] = anchor[0] ?? 0;
+        out[1] = anchor[1] ?? 0;
+        out[2] = anchor[2] ?? 0;
+        return;
+    }
+    const distance = shotParam(shot.distance, 6, 0.5, 400);
+    const height = shotParam(shot.height, 2, -50, 200);
+    out[0] = pose.x + Math.cos(pose.yaw) * distance;
+    out[1] = pose.y + height;
+    out[2] = pose.z + Math.sin(pose.yaw) * distance;
+}
+/**
+ * Place `shot` for a subject at `pose`, `ageSec` into the shot.
+ *
+ * `station` is only read by `flyby`; pass the rig's held station.
+ */
+export function placeShot(shot, pose, ageSec, station, out) {
+    const distance = shotParam(shot.distance, 6, 0.5, 400);
+    const height = shotParam(shot.height, 2, -50, 200);
+    const { x, y, z, yaw } = pose;
+    out.fovDeg = shotParam(shot.fovDeg, 70, 20, 140);
+    out.wantX = x;
+    out.wantY = y + height;
+    out.wantZ = z;
+    out.lookX = x;
+    out.lookY = y;
+    out.lookZ = z;
+    switch (shot.kind) {
+        case 'chase': {
+            // Behind the character's own heading, so the shot reads as following.
+            out.wantX = x - Math.sin(yaw) * distance;
+            out.wantZ = z + Math.cos(yaw) * distance;
+            break;
+        }
+        case 'lowWide': {
+            // Across the line of travel and near the ground, so the character crosses
+            // frame instead of receding — the shot that sells a gap.
+            out.wantX = x + Math.cos(yaw) * distance;
+            out.wantZ = z + Math.sin(yaw) * distance;
+            break;
+        }
+        case 'orbit': {
+            const rate = shotParam(shot.orbitRate, 0.6, -3, 3);
+            const angle = yaw + sweptAngle(rate, ageSec, shot.holdSec);
+            out.wantX = x - Math.sin(angle) * distance;
+            out.wantZ = z + Math.cos(angle) * distance;
+            break;
+        }
+        case 'overhead': {
+            out.wantX = x - Math.sin(yaw) * distance * 0.4;
+            out.wantZ = z + Math.cos(yaw) * distance * 0.4;
+            break;
+        }
+        case 'flyby': {
+            out.wantX = station[0] ?? 0;
+            out.wantY = station[1] ?? 0;
+            out.wantZ = station[2] ?? 0;
+            break;
+        }
+        case 'lookAt': {
+            /*
+             * Frames a fixed point *and* keeps the subject, handing the frame from one to the
+             * other as they separate.
+             *
+             * The fixed point is the reason this shot kind exists — a grapple shot holds on the
+             * ring while the character flies at it, and aiming at the character instead loses the thing
+             * the moment is about. But it aimed at the anchor and *nothing else*, and an anchor is
+             * a place the character arrives at and then leaves. Once they had swung through it they
+             * were simply out of shot, for as long as the cut lasted — reported from a replay
+             * as framing that loses the subject entirely, because the camera stops following
+             * them in that phase.
+             *
+             * So the aim is a point on the line between them, pulled toward the anchor by a
+             * bounded number of metres. While the two are close the aim *is* the anchor, which is
+             * the composition the shot was written for; once the character has flown past, the aim
+             * stays with them and the ring slides out toward the edge of frame rather than the
+             * character leaving it. Nothing needs to know which phase it is in — the geometry says.
+             */
+            const anchor = shot.anchor;
+            if (anchor !== undefined) {
+                const ax = anchor[0] ?? 0;
+                const ay = anchor[1] ?? 0;
+                const az = anchor[2] ?? 0;
+                const gap = Math.hypot(x - ax, y - ay, z - az);
+                /*
+                 * Aim from the *subject* toward the anchor, by at most half the camera's distance.
+                 * Nearer than that and the aim is the anchor itself; further and the anchor slides
+                 * out toward the edge of frame while the subject stays in the middle of it.
+                 */
+                const pull = Math.min(gap, distance * LOOK_AT_ANCHOR_PULL);
+                const k = gap > 1e-6 ? pull / gap : 0;
+                out.lookX = x + (ax - x) * k;
+                out.lookY = y + (ay - y) * k;
+                out.lookZ = z + (az - z) * k;
+            }
+            out.wantX = x - Math.sin(yaw) * distance;
+            out.wantZ = z + Math.cos(yaw) * distance;
+            break;
+        }
+    }
+}
+/**
+ * How far an orbit has swept by `ageSec` — eased, not `age x rate`.
+ *
+ * The linear version was reported, exactly, as looking *straight*: measured at a
+ * dead constant 3.82 m/s from the twentieth frame of the shot to the last one,
+ * still at full speed at the instant the shot was cut away from. A dolly on
+ * rails. Every other shot kind travelled exactly 0.000 m over two seconds with a
+ * still character, so this was the only self-motion in the file and the only place
+ * the complaint could come from.
+ *
+ * The **arc is preserved**: `rate x hold` is what a hold sweeps either way, since
+ * where an orbit starts and finishes is a composition decision and the ease is
+ * only about how it gets there. It peaks half again as fast in the middle, which
+ * is the cost of standing still at both ends.
+ */
+function sweptAngle(rate, ageSec, holdSec) {
+    const hold = holdSec !== undefined && Number.isFinite(holdSec) && holdSec > 0 ? holdSec : 0;
+    if (hold > 0) {
+        const t = clamp(ageSec / hold, 0, 1);
+        return rate * hold * t * t * (3 - 2 * t);
+    }
+    /*
+     * No hold to aim at, so ease in and then keep the rate. This is the integral of
+     * `smoothstep(age / EASE)` — which is why the straight part is offset by half
+     * the ramp rather than starting from zero, and why the two halves meet with the
+     * same speed as well as the same position.
+     */
+    if (ageSec >= ORBIT_EASE_SEC)
+        return rate * (ageSec - ORBIT_EASE_SEC * 0.5);
+    const u = ageSec / ORBIT_EASE_SEC;
+    return rate * ORBIT_EASE_SEC * (u * u * u - 0.5 * u * u * u * u);
+}
+/**
+ * Clamp a shot parameter into something a camera can use.
+ *
+ * Shots are produced by a director working from measured data — a run that
+ * lasted no time, an anchor at the origin — and a NaN reaching a view matrix
+ * blanks the entire frame without raising anything, which is the worst way for a
+ * bad number to fail.
+ */
+export function shotParam(value, fallback, min, max) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return clamp(value, min, max);
+}

package/dist/render/skinPalette.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The joint palette's shape: how wide its texture is, how many joints fit, and which unit it takes.
+ *
+ * **Backend-neutral by the 2026-08-13 rule.** Both backends upload a palette and both need the
+ * same three answers, so the decision lives here and only the binding is per-backend. A helper
+ * that took a `WebGL2RenderingContext` would be a decision the other backend could not reach, and
+ * two implementations of one rule drift.
+ *
+ * **The palette is a texture and not a `uniform mat4[]`, and the rule that would have barred one
+ * does not reach here.** The 2026-08-07 rule governs implicit derivatives in non-uniform control
+ * flow — a *fragment*-stage hazard. A vertex stage computes no derivatives, so `texelFetch` there
+ * is unconditional and that rule has nothing to say about it.
+ *
+ * What a uniform array would have cost is the reason: `MAX_VERTEX_UNIFORM_VECTORS` is 256 on the
+ * WebGL2 floor and `FLAT_VERT` already spends fifteen, so four vectors a matrix caps a rig at
+ * **sixty joints** — under a humanoid with fingers, and on exactly the mid-range hardware the
+ * engine hard-gates 60 fps on.
+ *
+ * What the texture costs is an upload per skinned draw where an array would be a uniform write.
+ * What would make it wrong is a profile showing that upload is the limit at a realistic character
+ * count; the fix is then one texture holding every character's palette with a per-draw row offset,
+ * which is a follow-on rather than a starting point.
+ *
+ * **A palette belongs to a draw, and what it takes to honour that differs per backend.** WebGL2
+ * uploads with `texSubImage2D`, a command in the same stream as the draws around it, so one texture
+ * rewritten between two draws separates them by construction. WebGPU's `queue.writeTexture` is
+ * ordered on the queue timeline and the frame's encoder is submitted after every upload in it, so
+ * the same one texture hands *every* skinned draw of the frame the last palette written — and since
+ * a rig carries its placement in its palette, that is every character standing where the last one
+ * drawn stands. That backend therefore binds a ring of palettes, one slot per palette a frame sets:
+ * `backend/webgpu/skinPaletteRing.ts`. The decision here is one; only the binder differs, per the
+ * 2026-08-13 rule.
+ */
+/**
+ * The palette's texture unit, from the lit pass's own budget.
+ *
+ * Re-exported rather than declared, because a unit number written twice is a collision waiting to
+ * happen and `lightBudget.ts` is where every other unit in this pass is decided. It carries the
+ * reason it is not 0.
+ */
+export { SKIN_PALETTE_TEXTURE_UNIT } from './lightBudget.ts';
+/**
+ * The most joints one palette can hold.
+ *
+ * WebGL2 guarantees `MAX_TEXTURE_SIZE` of 2048 and promises nothing above it, so a single-row
+ * palette holds 2048 / 4 matrices. A humanoid rig is sixty to ninety joints, so this is not a
+ * limit anybody meets by accident — but it is stated, refused at construction and named in the
+ * error, because a limit a consumer discovers is a defect and a limit they read is a
+ * specification.
+ *
+ * What it costs is that a crowd cannot share one palette. What would make it wrong is a rig above
+ * it, and the fix is wrapping onto more rows — which costs one division in the vertex stage and is
+ * why it is not the starting point.
+ */
+export declare const MAX_JOINTS = 512;
+/** How wide the palette texture is for a rig of this many joints. */
+export declare function paletteTextureWidth(jointCount: number): number;
+/**
+ * Refuse a palette that is not whole matrices, naming the length.
+ *
+ * A caller error with exactly one correct outcome, so it throws rather than warns — and it throws
+ * where the palette is handed over rather than where a shader reads a partial matrix and draws a
+ * rig folded in on itself.
+ */
+export declare function validateSkinPalette(palette: Float32Array): void;
+/**
+ * The most morph targets one mesh can carry.
+ *
+ * Bounded by the weight array in the vertex uniform block rather than by the delta texture, which
+ * is why it is small: eight `vec4`-aligned floats is 128 bytes of a block that has fifteen vectors
+ * in it already. Eight is what glTF's own tooling emits and what every exporter defaults to.
+ *
+ * What it costs is a rig wanting nine expressions. What would make it wrong is one, and the fix is
+ * a second weight texture rather than a wider block — the block is per draw and the texture is not.
+ */
+export declare const MAX_MORPH_TARGETS = 8;
+/**
+ * Where one target's delta for one vertex sits in the delta texture.
+ *
+ * Interleaved by vertex rather than by target — every target of a vertex is adjacent — because the
+ * shader reads all of them for one vertex and nothing reads one target across many vertices. That
+ * is one cache line instead of `targetCount` of them.
+ */
+export declare function morphTexelIndex(vertex: number, target: number, targetCount: number): number;
+/** Refuse a weight array that cannot drive the targets a mesh carries, naming both counts. */
+export declare function validateMorph(weights: Float32Array, targetCount: number): void;
+/** How wide the delta texture is for a mesh of this many vertices and targets. */
+export declare function morphTextureWidth(vertexCount: number, targetCount: number): number;
+/** Rows the delta texture needs, given the width above. */
+export declare function morphTextureRows(vertexCount: number, targetCount: number): number;

package/dist/render/skinPalette.js

@@ -0,0 +1,136 @@
+/**
+ * The joint palette's shape: how wide its texture is, how many joints fit, and which unit it takes.
+ *
+ * **Backend-neutral by the 2026-08-13 rule.** Both backends upload a palette and both need the
+ * same three answers, so the decision lives here and only the binding is per-backend. A helper
+ * that took a `WebGL2RenderingContext` would be a decision the other backend could not reach, and
+ * two implementations of one rule drift.
+ *
+ * **The palette is a texture and not a `uniform mat4[]`, and the rule that would have barred one
+ * does not reach here.** The 2026-08-07 rule governs implicit derivatives in non-uniform control
+ * flow — a *fragment*-stage hazard. A vertex stage computes no derivatives, so `texelFetch` there
+ * is unconditional and that rule has nothing to say about it.
+ *
+ * What a uniform array would have cost is the reason: `MAX_VERTEX_UNIFORM_VECTORS` is 256 on the
+ * WebGL2 floor and `FLAT_VERT` already spends fifteen, so four vectors a matrix caps a rig at
+ * **sixty joints** — under a humanoid with fingers, and on exactly the mid-range hardware the
+ * engine hard-gates 60 fps on.
+ *
+ * What the texture costs is an upload per skinned draw where an array would be a uniform write.
+ * What would make it wrong is a profile showing that upload is the limit at a realistic character
+ * count; the fix is then one texture holding every character's palette with a per-draw row offset,
+ * which is a follow-on rather than a starting point.
+ *
+ * **A palette belongs to a draw, and what it takes to honour that differs per backend.** WebGL2
+ * uploads with `texSubImage2D`, a command in the same stream as the draws around it, so one texture
+ * rewritten between two draws separates them by construction. WebGPU's `queue.writeTexture` is
+ * ordered on the queue timeline and the frame's encoder is submitted after every upload in it, so
+ * the same one texture hands *every* skinned draw of the frame the last palette written — and since
+ * a rig carries its placement in its palette, that is every character standing where the last one
+ * drawn stands. That backend therefore binds a ring of palettes, one slot per palette a frame sets:
+ * `backend/webgpu/skinPaletteRing.ts`. The decision here is one; only the binder differs, per the
+ * 2026-08-13 rule.
+ */
+/**
+ * The palette's texture unit, from the lit pass's own budget.
+ *
+ * Re-exported rather than declared, because a unit number written twice is a collision waiting to
+ * happen and `lightBudget.ts` is where every other unit in this pass is decided. It carries the
+ * reason it is not 0.
+ */
+export { SKIN_PALETTE_TEXTURE_UNIT } from './lightBudget.js';
+/** Four `rgba32float` texels hold one column-major 4x4. */
+const TEXELS_PER_JOINT = 4;
+/**
+ * The most joints one palette can hold.
+ *
+ * WebGL2 guarantees `MAX_TEXTURE_SIZE` of 2048 and promises nothing above it, so a single-row
+ * palette holds 2048 / 4 matrices. A humanoid rig is sixty to ninety joints, so this is not a
+ * limit anybody meets by accident — but it is stated, refused at construction and named in the
+ * error, because a limit a consumer discovers is a defect and a limit they read is a
+ * specification.
+ *
+ * What it costs is that a crowd cannot share one palette. What would make it wrong is a rig above
+ * it, and the fix is wrapping onto more rows — which costs one division in the vertex stage and is
+ * why it is not the starting point.
+ */
+export const MAX_JOINTS = 512;
+/** How wide the palette texture is for a rig of this many joints. */
+export function paletteTextureWidth(jointCount) {
+    if (!Number.isInteger(jointCount) || jointCount < 1) {
+        throw new Error(`skin palette: a rig needs at least one joint, got ${jointCount}`);
+    }
+    if (jointCount > MAX_JOINTS) {
+        throw new Error(`skin palette: ${jointCount} joints exceeds the ${MAX_JOINTS} a single-row palette holds. ` +
+            `WebGL2 guarantees a texture width of 2048 and four texels carry one matrix, so this is ` +
+            `the floor rather than this machine's limit.`);
+    }
+    return jointCount * TEXELS_PER_JOINT;
+}
+/**
+ * Refuse a palette that is not whole matrices, naming the length.
+ *
+ * A caller error with exactly one correct outcome, so it throws rather than warns — and it throws
+ * where the palette is handed over rather than where a shader reads a partial matrix and draws a
+ * rig folded in on itself.
+ */
+export function validateSkinPalette(palette) {
+    if (palette.length % 16 !== 0) {
+        throw new Error(`skin palette: ${palette.length} floats is not a whole number of 4x4 matrices (16 each)`);
+    }
+    const joints = palette.length / 16;
+    if (joints < 1 || joints > MAX_JOINTS) {
+        throw new Error(`skin palette: ${joints} joints, which is outside 1 to ${MAX_JOINTS}. See MAX_JOINTS.`);
+    }
+}
+/* --- Morph targets, on the same mechanism --- */
+/**
+ * The most morph targets one mesh can carry.
+ *
+ * Bounded by the weight array in the vertex uniform block rather than by the delta texture, which
+ * is why it is small: eight `vec4`-aligned floats is 128 bytes of a block that has fifteen vectors
+ * in it already. Eight is what glTF's own tooling emits and what every exporter defaults to.
+ *
+ * What it costs is a rig wanting nine expressions. What would make it wrong is one, and the fix is
+ * a second weight texture rather than a wider block — the block is per draw and the texture is not.
+ */
+export const MAX_MORPH_TARGETS = 8;
+/**
+ * Where one target's delta for one vertex sits in the delta texture.
+ *
+ * Interleaved by vertex rather than by target — every target of a vertex is adjacent — because the
+ * shader reads all of them for one vertex and nothing reads one target across many vertices. That
+ * is one cache line instead of `targetCount` of them.
+ */
+export function morphTexelIndex(vertex, target, targetCount) {
+    return vertex * targetCount + target;
+}
+/** Refuse a weight array that cannot drive the targets a mesh carries, naming both counts. */
+export function validateMorph(weights, targetCount) {
+    if (targetCount < 1 || targetCount > MAX_MORPH_TARGETS) {
+        throw new Error(`morph targets: ${targetCount} is outside 1 to ${MAX_MORPH_TARGETS}. See MAX_MORPH_TARGETS.`);
+    }
+    if (weights.length < targetCount) {
+        throw new Error(`morph targets: ${weights.length} weights for ${targetCount} targets. Every target needs ` +
+            `one, or the ones past the end read as zero and that target silently never applies.`);
+    }
+}
+/** How wide the delta texture is for a mesh of this many vertices and targets. */
+export function morphTextureWidth(vertexCount, targetCount) {
+    const texels = vertexCount * targetCount;
+    if (texels < 1)
+        throw new Error('morph targets: a mesh needs at least one vertex and one target');
+    /*
+     * One row while it fits, then as many rows as it takes. WebGL2 guarantees a texture width of
+     * 2048 and nothing more, and a mesh times its targets passes that at 256 vertices with eight
+     * targets — which is a small mesh, so unlike the palette this is the ordinary case rather than
+     * the edge one.
+     */
+    return Math.min(texels, MORPH_TEXTURE_WIDTH);
+}
+/** Rows the delta texture needs, given the width above. */
+export function morphTextureRows(vertexCount, targetCount) {
+    return Math.ceil((vertexCount * targetCount) / MORPH_TEXTURE_WIDTH);
+}
+/** WebGL2's guaranteed `MAX_TEXTURE_SIZE`, which is the only width that is safe everywhere. */
+const MORPH_TEXTURE_WIDTH = 2048;

package/dist/render/ssrPass.d.ts

@@ -0,0 +1,59 @@
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { ReflectionQueue } from './screenSpaceReflection.ts';
+/**
+ * Screen-space reflection on WebGL2: a scissored trace per surface, then one composite.
+ *
+ * **The trace writes into a target of its own and that is not an optimisation.** It samples the
+ * finished scene colour to find out what a ray hit, so writing into the scene would be a feedback
+ * loop — `GL_INVALID_OPERATION` once per draw and undefined rasterisation, which `OitPass` records
+ * paying for. One extra full-frame attachment buys the separation, and it also makes several
+ * reflective surfaces accumulate as premultiplied layers rather than as independent guesses.
+ *
+ * **Two passes, and the second is one fetch.** The composite is done by the blend state:
+ * `(ONE, ONE_MINUS_SRC_ALPHA)` against premultiplied texels is `over`, so the resolve never samples
+ * the colour it is compositing onto either.
+ */
+export declare class SsrPass {
+    private readonly gl;
+    /**
+     * Whether the scene it reflects is a float target.
+     *
+     * The reflection buffer matches it. A half-float scene composited through an eight-bit
+     * reflection would clip every highlight the reflection carries, which is exactly the part of a
+     * scene that shows in a wet floor.
+     */
+    private readonly floatColor;
+    private readonly trace;
+    private readonly traceUniforms;
+    private readonly resolve;
+    private readonly resolveUniforms;
+    private readonly vao;
+    private reflection;
+    private framebuffer;
+    private width;
+    private height;
+    /** `inverse(viewProjection) * DEPTH_01_TO_CLIP`, rebuilt once a frame rather than per surface. */
+    private readonly depthToWorld;
+    private readonly scissor;
+    constructor(gl: WebGL2RenderingContext, 
+    /**
+     * Whether the scene it reflects is a float target.
+     *
+     * The reflection buffer matches it. A half-float scene composited through an eight-bit
+     * reflection would clip every highlight the reflection carries, which is exactly the part of a
+     * scene that shows in a wet floor.
+     */
+    floatColor: boolean);
+    private ensureSize;
+    /**
+     * March every recorded surface into the reflection buffer.
+     *
+     * `viewProjection` is the **raw** camera matrix. `DEPTH_01_TO_CLIP` turns a stored depth back
+     * into the clip space that matrix was built in, and the trace projects its samples back through
+     * the same matrix — pairing either with the clip-corrected one applies the remap twice.
+     */
+    traceReflections(queue: ReflectionQueue, scene: WebGLTexture, depth: WebGLTexture, viewProjection: ReadonlyMat4, eye: ArrayLike<number>, width: number, height: number, edgeFade: number): void;
+    /** Composite what the trace found over whatever framebuffer is bound. */
+    resolveReflections(): void;
+    dispose(): void;
+}