@driftengine/core 3.61.0

package/dist/render/compute.d.ts

@@ -0,0 +1,74 @@
+import { type HandleRegistry } from './handleRegistry.ts';
+/**
+ * A compute definition a package contributes, and the two things it is handed.
+ *
+ * **This is `pass.ts` again, for the one stage that only one backend has.** A package that wants
+ * a radix sort, a light binner or a skinning kernel has nowhere to put it: the renderer's verb
+ * surface is fixed and nothing outside `render/` can add to it. `registerPass` answered that for
+ * drawing; this answers it for the stage before drawing.
+ */
+/**
+ * What a registered definition is handed once, at registration, to build its resources.
+ *
+ * **There is no WebGL2 arm, and that absence is the type saying so.** `PassDevice` is a union
+ * because both backends can draw. WebGL2 has no compute shaders — not "not yet", the language has
+ * none — so a second arm would be a shape a contributor could switch on and never reach.
+ * `Renderer.computeSupported` answers `false` there and `registerCompute` refuses in words.
+ *
+ * Tagged all the same, so that a second arm arriving later is a compile error at every
+ * contributor rather than a silent widening, and so this reads as the same shape as `PassDevice`
+ * to somebody who has just read that one.
+ */
+export type ComputeDevice = {
+    readonly backend: 'webgpu';
+    readonly device: GPUDevice;
+};
+/**
+ * What it is handed at each dispatch.
+ *
+ * **The engine opens the pass and hands it over, rather than handing over the command encoder.**
+ * A definition holding the encoder could open a compute pass while a render pass was open, which
+ * WebGPU forbids and which reports itself at `submit` rather than at the call that caused it —
+ * the failure shape the 2026-08-14 rule is about, where the result is no picture from a frame
+ * that recorded correctly. Handing over the pass keeps that invariant in one place instead of in
+ * every contributor.
+ *
+ * A definition that needs an encoder of its own for a readback still has one: it holds `device`
+ * from `init`, and a `copyBufferToBuffer` submitted afterwards sees this dispatch's result,
+ * because submission order is execution order.
+ */
+export type ComputeContext = {
+    readonly backend: 'webgpu';
+    readonly pass: GPUComputePassEncoder;
+};
+export interface ComputeDefinition {
+    /** For diagnostics, and for the label the backend gives the encoder and the pass. */
+    readonly label: string;
+    /** Build pipelines and buffers. Called once, when the definition is registered. */
+    init?(device: ComputeDevice): void;
+    /**
+     * Set a pipeline, set bind groups, and call `dispatchWorkgroups`.
+     *
+     * **The workgroup count is yours and does not cross the surface**, exactly as a contributed
+     * pass issues its own draw calls. The count comes from data the definition owns — a light
+     * count, a cluster count — so a renderer-side `(x, y, z)` would be one fact in two places, and
+     * the renderer's copy would be the one nobody updated.
+     *
+     * **Allocates nothing.** This is a per-frame path and the house rule about them binds a
+     * contributor exactly as it binds the renderer.
+     */
+    dispatch(ctx: ComputeContext): void;
+    /** Release what `init` built. Called on `unregisterCompute` and when the renderer is disposed. */
+    dispose?(device: ComputeDevice): void;
+}
+/**
+ * A registered definition, as the caller holds it.
+ *
+ * A slot and a generation packed into one number, for the reason `PassHandle` explains: a handle
+ * kept past `unregisterCompute` answers nothing rather than answering to whoever took the slot.
+ */
+export type ComputeHandle = number;
+export type ComputeRegistry = HandleRegistry<ComputeDefinition>;
+export declare function createComputeRegistry(): ComputeRegistry;
+/** The definition a handle names, or `undefined` if it names one that has been released. */
+export declare function computeAt(registry: ComputeRegistry, handle: ComputeHandle): ComputeDefinition | undefined;

package/dist/render/compute.js

@@ -0,0 +1,8 @@
+import { createHandleRegistry, definitionAt } from './handleRegistry.js';
+export function createComputeRegistry() {
+    return createHandleRegistry();
+}
+/** The definition a handle names, or `undefined` if it names one that has been released. */
+export function computeAt(registry, handle) {
+    return definitionAt(registry, handle);
+}

package/dist/render/contextLoss.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Notice a lost drawing context, notice it coming back, and ask the browser for it.
+ *
+ * The engine owns the GL context, so it owns noticing both halves. A game reaching for
+ * `renderer.canvas.addEventListener('webglcontextlost')` would be the game reaching into
+ * the engine's internals.
+ *
+ * `preventDefault` is not politeness: it is the browser's signal that the page intends to
+ * restore rather than to die. Without it the context is gone for good and the player is
+ * looking at a black canvas that nothing will ever repaint.
+ *
+ * **The restore is a separate sink, and that is the point.** Routing it to `onLost` would
+ * report a fault at the moment the fault ended, which reads in a bug report as a device
+ * that lost its context twice. `NFD6QQ` is the report that proved the restore half was
+ * missing altogether: the promise `preventDefault` makes was made 29 s into a session on
+ * an Adreno 619, and nothing in either repository had ever been listening to keep it.
+ *
+ * Restoring is *not* the same as redrawing. Every resource the renderer holds is created
+ * in its constructor and `readonly` thereafter — the same reason a quality change is
+ * construction-time — so a listener that wants pixels again has to take the page through
+ * a reload. This function only makes the moment observable.
+ */
+/**
+ * Returns a detach function, which a renderer that can be torn down has to call.
+ *
+ * The listeners used to be anonymous and therefore unremovable. That is invisible in a
+ * game whose renderer lives as long as its page, and a leak in one that does not: a game
+ * embedded in a website is mounted and unmounted every time the player enters and leaves
+ * it, and each mount left a pair of listeners holding the previous renderer alive through
+ * their closures.
+ */
+export declare function attachContextLoss(canvas: HTMLCanvasElement, onLost: () => void, onRestored: () => void): () => void;

package/dist/render/contextLoss.js

@@ -0,0 +1,46 @@
+/**
+ * Notice a lost drawing context, notice it coming back, and ask the browser for it.
+ *
+ * The engine owns the GL context, so it owns noticing both halves. A game reaching for
+ * `renderer.canvas.addEventListener('webglcontextlost')` would be the game reaching into
+ * the engine's internals.
+ *
+ * `preventDefault` is not politeness: it is the browser's signal that the page intends to
+ * restore rather than to die. Without it the context is gone for good and the player is
+ * looking at a black canvas that nothing will ever repaint.
+ *
+ * **The restore is a separate sink, and that is the point.** Routing it to `onLost` would
+ * report a fault at the moment the fault ended, which reads in a bug report as a device
+ * that lost its context twice. `NFD6QQ` is the report that proved the restore half was
+ * missing altogether: the promise `preventDefault` makes was made 29 s into a session on
+ * an Adreno 619, and nothing in either repository had ever been listening to keep it.
+ *
+ * Restoring is *not* the same as redrawing. Every resource the renderer holds is created
+ * in its constructor and `readonly` thereafter — the same reason a quality change is
+ * construction-time — so a listener that wants pixels again has to take the page through
+ * a reload. This function only makes the moment observable.
+ */
+/**
+ * Returns a detach function, which a renderer that can be torn down has to call.
+ *
+ * The listeners used to be anonymous and therefore unremovable. That is invisible in a
+ * game whose renderer lives as long as its page, and a leak in one that does not: a game
+ * embedded in a website is mounted and unmounted every time the player enters and leaves
+ * it, and each mount left a pair of listeners holding the previous renderer alive through
+ * their closures.
+ */
+export function attachContextLoss(canvas, onLost, onRestored) {
+    const lost = (event) => {
+        event.preventDefault();
+        onLost();
+    };
+    const restored = () => {
+        onRestored();
+    };
+    canvas.addEventListener('webglcontextlost', lost);
+    canvas.addEventListener('webglcontextrestored', restored);
+    return () => {
+        canvas.removeEventListener('webglcontextlost', lost);
+        canvas.removeEventListener('webglcontextrestored', restored);
+    };
+}

package/dist/render/debugLines.d.ts

@@ -0,0 +1,75 @@
+import type { LineSegments } from './linePoints.ts';
+import type { MeshData } from './mesh.ts';
+import type { ConvexShape } from '@driftengine/physics';
+import type { PhysicsWorld } from '@driftengine/physics';
+/**
+ * Debug geometry, as line segments the renderer already knows how to draw.
+ *
+ * **This is the generator and not a pass**, and that is the whole reason it is small: `drawLines`
+ * has shipped on both backends since the polyline batch landed, with a world-space width and a
+ * pixel floor so a distant line does not strobe. What was missing was anything that turns what you
+ * want to *see* — a mesh's normals, the colliders a body actually carries — into segments, so every
+ * consumer who wanted a normals key wrote the geometry themselves or, far more often, did not.
+ *
+ * **What its absence has cost, measured rather than supposed.** One consumer wrote geometry with
+ * downward normals four separate times: their roads, their ditch banks, their roof planes, and
+ * every building in their world lit inside out. Each was found by looking at a screenshot and
+ * wondering why tarmac was black at midday, because a flipped normal near a lamp is a dimmer
+ * surface rather than an absent one and only a directional light makes it plain. A key that draws
+ * normals turns each of those into a ten-second job.
+ *
+ * **Nothing here throws and nothing here allocates after construction.** A debug drawer that threw
+ * when it ran out of room would take the frame with it at exactly the moment somebody was trying to
+ * see what was wrong, which is the opposite of its job; so a segment past capacity is counted in
+ * `dropped` and discarded, and a consumer who cares reads that number and builds a bigger one.
+ */
+export declare class DebugLines {
+    readonly segments: LineSegments;
+    private overflow;
+    constructor(capacity: number);
+    /** Segments asked for since the last `clear` that there was no room for. */
+    get dropped(): number;
+    clear(): void;
+    segment(ax: number, ay: number, az: number, bx: number, by: number, bz: number): void;
+    /**
+     * A spike out of every vertex along its normal.
+     *
+     * `stride` skips vertices, because a mesh of a hundred thousand vertices is a hundred thousand
+     * segments and a screen with nothing legible on it. The default draws them all, which is right
+     * for the small piece of geometry somebody is actually staring at.
+     *
+     * **A mesh built from flat faces has four coincident normals per quad**, so what appears is one
+     * spike per corner rather than one per face, and that is the honest picture: the attribute is per
+     * vertex and this draws the attribute.
+     */
+    normals(mesh: MeshData, length?: number, stride?: number): void;
+    /** The twelve edges of a world-axis box. */
+    box(cx: number, cy: number, cz: number, hx: number, hy: number, hz: number): void;
+    /** Three great circles, which is a sphere as far as an eye looking for one is concerned. */
+    sphere(cx: number, cy: number, cz: number, radius: number, points?: number): void;
+    /**
+     * A closed ring of `points` segments, in the plane the two unit vectors span.
+     *
+     * The basis is passed in rather than derived from an axis because every caller here already has
+     * one, and deriving a perpendicular from an axis has a degenerate case that a caller with a real
+     * basis does not need to think about.
+     */
+    circle(cx: number, cy: number, cz: number, radius: number, ux: number, uy: number, uz: number, vx: number, vy: number, vz: number, points?: number): void;
+    /**
+     * One collider, placed by a body's position and orientation.
+     *
+     * **Dispatched on what the shape *is* rather than on a stored kind**, which is the same
+     * discrimination the narrow phase makes: a `sideRadius` is a cylinder, a `triangles` is a mesh, a
+     * `radius` over one point is a sphere and over two is a capsule, and anything with faces is a
+     * polytope drawn along its own face loops. A shape that grows a new representation appears here
+     * as its polytope hull rather than as nothing, which is the failure worth having.
+     */
+    shape(shape: ConvexShape, px: number, py: number, pz: number, qx?: number, qy?: number, qz?: number, qw?: number): void;
+    /**
+     * Every body's collider in a world, where it is this tick.
+     *
+     * The other half of the key the report asked for. Bodies with no shape are skipped rather than
+     * refused: a world may hold one for a frame while it is being built.
+     */
+    colliders(world: PhysicsWorld): void;
+}

package/dist/render/debugLines.js

@@ -0,0 +1,281 @@
+import { createLineSegments } from './linePoints.js';
+/**
+ * Debug geometry, as line segments the renderer already knows how to draw.
+ *
+ * **This is the generator and not a pass**, and that is the whole reason it is small: `drawLines`
+ * has shipped on both backends since the polyline batch landed, with a world-space width and a
+ * pixel floor so a distant line does not strobe. What was missing was anything that turns what you
+ * want to *see* — a mesh's normals, the colliders a body actually carries — into segments, so every
+ * consumer who wanted a normals key wrote the geometry themselves or, far more often, did not.
+ *
+ * **What its absence has cost, measured rather than supposed.** One consumer wrote geometry with
+ * downward normals four separate times: their roads, their ditch banks, their roof planes, and
+ * every building in their world lit inside out. Each was found by looking at a screenshot and
+ * wondering why tarmac was black at midday, because a flipped normal near a lamp is a dimmer
+ * surface rather than an absent one and only a directional light makes it plain. A key that draws
+ * normals turns each of those into a ten-second job.
+ *
+ * **Nothing here throws and nothing here allocates after construction.** A debug drawer that threw
+ * when it ran out of room would take the frame with it at exactly the moment somebody was trying to
+ * see what was wrong, which is the opposite of its job; so a segment past capacity is counted in
+ * `dropped` and discarded, and a consumer who cares reads that number and builds a bigger one.
+ */
+export class DebugLines {
+    segments;
+    overflow = 0;
+    constructor(capacity) {
+        if (!(capacity > 0))
+            throw new Error(`DebugLines: capacity must be positive, got ${capacity}`);
+        this.segments = createLineSegments(capacity);
+    }
+    /** Segments asked for since the last `clear` that there was no room for. */
+    get dropped() {
+        return this.overflow;
+    }
+    clear() {
+        this.segments.count = 0;
+        this.overflow = 0;
+    }
+    segment(ax, ay, az, bx, by, bz) {
+        const at = this.segments.count;
+        if (at >= this.segments.capacity) {
+            this.overflow++;
+            return;
+        }
+        this.segments.from[at * 3] = ax;
+        this.segments.from[at * 3 + 1] = ay;
+        this.segments.from[at * 3 + 2] = az;
+        this.segments.to[at * 3] = bx;
+        this.segments.to[at * 3 + 1] = by;
+        this.segments.to[at * 3 + 2] = bz;
+        this.segments.count = at + 1;
+    }
+    /**
+     * A spike out of every vertex along its normal.
+     *
+     * `stride` skips vertices, because a mesh of a hundred thousand vertices is a hundred thousand
+     * segments and a screen with nothing legible on it. The default draws them all, which is right
+     * for the small piece of geometry somebody is actually staring at.
+     *
+     * **A mesh built from flat faces has four coincident normals per quad**, so what appears is one
+     * spike per corner rather than one per face, and that is the honest picture: the attribute is per
+     * vertex and this draws the attribute.
+     */
+    normals(mesh, length = 0.25, stride = 1) {
+        const count = mesh.positions.length / 3;
+        for (let v = 0; v < count; v += stride) {
+            const x = mesh.positions[v * 3] ?? 0;
+            const y = mesh.positions[v * 3 + 1] ?? 0;
+            const z = mesh.positions[v * 3 + 2] ?? 0;
+            this.segment(x, y, z, x + (mesh.normals[v * 3] ?? 0) * length, y + (mesh.normals[v * 3 + 1] ?? 0) * length, z + (mesh.normals[v * 3 + 2] ?? 0) * length);
+        }
+    }
+    /** The twelve edges of a world-axis box. */
+    box(cx, cy, cz, hx, hy, hz) {
+        for (const [a, b] of BOX_EDGES) {
+            this.segment(cx + hx * (a[0] ?? 0), cy + hy * (a[1] ?? 0), cz + hz * (a[2] ?? 0), cx + hx * (b[0] ?? 0), cy + hy * (b[1] ?? 0), cz + hz * (b[2] ?? 0));
+        }
+    }
+    /** Three great circles, which is a sphere as far as an eye looking for one is concerned. */
+    sphere(cx, cy, cz, radius, points = 24) {
+        this.circle(cx, cy, cz, radius, 1, 0, 0, 0, 0, 1, points);
+        this.circle(cx, cy, cz, radius, 1, 0, 0, 0, 1, 0, points);
+        this.circle(cx, cy, cz, radius, 0, 1, 0, 0, 0, 1, points);
+    }
+    /**
+     * A closed ring of `points` segments, in the plane the two unit vectors span.
+     *
+     * The basis is passed in rather than derived from an axis because every caller here already has
+     * one, and deriving a perpendicular from an axis has a degenerate case that a caller with a real
+     * basis does not need to think about.
+     */
+    circle(cx, cy, cz, radius, ux, uy, uz, vx, vy, vz, points = 24) {
+        let px = cx + ux * radius;
+        let py = cy + uy * radius;
+        let pz = cz + uz * radius;
+        for (let i = 1; i <= points; i++) {
+            const angle = (i / points) * Math.PI * 2;
+            const c = Math.cos(angle) * radius;
+            const s = Math.sin(angle) * radius;
+            const nx = cx + ux * c + vx * s;
+            const ny = cy + uy * c + vy * s;
+            const nz = cz + uz * c + vz * s;
+            this.segment(px, py, pz, nx, ny, nz);
+            px = nx;
+            py = ny;
+            pz = nz;
+        }
+    }
+    /**
+     * One collider, placed by a body's position and orientation.
+     *
+     * **Dispatched on what the shape *is* rather than on a stored kind**, which is the same
+     * discrimination the narrow phase makes: a `sideRadius` is a cylinder, a `triangles` is a mesh, a
+     * `radius` over one point is a sphere and over two is a capsule, and anything with faces is a
+     * polytope drawn along its own face loops. A shape that grows a new representation appears here
+     * as its polytope hull rather than as nothing, which is the failure worth having.
+     */
+    shape(shape, px, py, pz, qx = 0, qy = 0, qz = 0, qw = 1) {
+        const points = shape.vertices.length / 3;
+        const at = (i, out) => {
+            rotate(shape.vertices[i * 3] ?? 0, shape.vertices[i * 3 + 1] ?? 0, shape.vertices[i * 3 + 2] ?? 0, qx, qy, qz, qw, out);
+            out[0] = (out[0] ?? 0) + px;
+            out[1] = (out[1] ?? 0) + py;
+            out[2] = (out[2] ?? 0) + pz;
+        };
+        const mesh = shape.triangles;
+        if (mesh !== undefined) {
+            for (let t = 0; t < mesh.triangleCount; t++) {
+                for (let e = 0; e < 3; e++) {
+                    const i = mesh.indices[t * 3 + e] ?? 0;
+                    const j = mesh.indices[t * 3 + ((e + 1) % 3)] ?? 0;
+                    /* Each interior edge belongs to two triangles; drawing it once is the same picture at
+                       half the segments, which matters when the capacity is what stops the drawing. */
+                    if (i > j)
+                        continue;
+                    rotate(mesh.positions[i * 3] ?? 0, mesh.positions[i * 3 + 1] ?? 0, mesh.positions[i * 3 + 2] ?? 0, qx, qy, qz, qw, A);
+                    rotate(mesh.positions[j * 3] ?? 0, mesh.positions[j * 3 + 1] ?? 0, mesh.positions[j * 3 + 2] ?? 0, qx, qy, qz, qw, B);
+                    this.segment((A[0] ?? 0) + px, (A[1] ?? 0) + py, (A[2] ?? 0) + pz, (B[0] ?? 0) + px, (B[1] ?? 0) + py, (B[2] ?? 0) + pz);
+                }
+            }
+            return;
+        }
+        if (points === 1) {
+            at(0, A);
+            this.sphere(A[0] ?? 0, A[1] ?? 0, A[2] ?? 0, shape.radius);
+            return;
+        }
+        if (points === 2 && (shape.radius > 0 || shape.sideRadius > 0)) {
+            at(0, A);
+            at(1, B);
+            const round = shape.sideRadius > 0 ? shape.sideRadius : shape.radius;
+            basis(A, B, U, V);
+            if (shape.sideRadius > 0) {
+                /* A cylinder: two flat caps and a straight side, with a sharp rim between them. */
+                this.circle(A[0] ?? 0, A[1] ?? 0, A[2] ?? 0, round, U[0] ?? 0, U[1] ?? 0, U[2] ?? 0, V[0] ?? 0, V[1] ?? 0, V[2] ?? 0);
+                this.circle(B[0] ?? 0, B[1] ?? 0, B[2] ?? 0, round, U[0] ?? 0, U[1] ?? 0, U[2] ?? 0, V[0] ?? 0, V[1] ?? 0, V[2] ?? 0);
+            }
+            else {
+                /* A capsule: a ball at each end, which is what its rounding actually is. */
+                this.sphere(A[0] ?? 0, A[1] ?? 0, A[2] ?? 0, round);
+                this.sphere(B[0] ?? 0, B[1] ?? 0, B[2] ?? 0, round);
+            }
+            for (const [sx, sy] of SIDE_ANGLES) {
+                const ox = (U[0] ?? 0) * sx * round + (V[0] ?? 0) * sy * round;
+                const oy = (U[1] ?? 0) * sx * round + (V[1] ?? 0) * sy * round;
+                const oz = (U[2] ?? 0) * sx * round + (V[2] ?? 0) * sy * round;
+                this.segment((A[0] ?? 0) + ox, (A[1] ?? 0) + oy, (A[2] ?? 0) + oz, (B[0] ?? 0) + ox, (B[1] ?? 0) + oy, (B[2] ?? 0) + oz);
+            }
+            return;
+        }
+        const faces = shape.faceVertexStart.length - 1;
+        for (let f = 0; f < faces; f++) {
+            const start = shape.faceVertexStart[f] ?? 0;
+            const end = shape.faceVertexStart[f + 1] ?? 0;
+            for (let k = start; k < end; k++) {
+                const i = shape.faceVertexIndices[k] ?? 0;
+                const j = shape.faceVertexIndices[k + 1 === end ? start : k + 1] ?? 0;
+                /* Every edge is in two face loops, once each way round. Keeping the ascending one draws it
+                   exactly once. */
+                if (i > j)
+                    continue;
+                at(i, A);
+                at(j, B);
+                this.segment(A[0] ?? 0, A[1] ?? 0, A[2] ?? 0, B[0] ?? 0, B[1] ?? 0, B[2] ?? 0);
+            }
+        }
+    }
+    /**
+     * Every body's collider in a world, where it is this tick.
+     *
+     * The other half of the key the report asked for. Bodies with no shape are skipped rather than
+     * refused: a world may hold one for a frame while it is being built.
+     */
+    colliders(world) {
+        const bodies = world.bodies;
+        for (let i = 0; i < bodies.count; i++) {
+            const shape = bodies.shape[i];
+            if (shape === undefined)
+                continue;
+            this.shape(shape, bodies.posX[i] ?? 0, bodies.posY[i] ?? 0, bodies.posZ[i] ?? 0, bodies.rotX[i] ?? 0, bodies.rotY[i] ?? 0, bodies.rotZ[i] ?? 0, bodies.rotW[i] ?? 1);
+        }
+    }
+}
+/** Scratch, at module scope because a debug frame draws thousands of these. */
+const A = [0, 0, 0];
+const B = [0, 0, 0];
+const U = [0, 0, 0];
+const V = [0, 0, 0];
+/** Where the four side lines of a capsule or cylinder sit around its axis. */
+const SIDE_ANGLES = [
+    [1, 0],
+    [0, 1],
+    [-1, 0],
+    [0, -1],
+];
+const BOX_EDGES = (() => {
+    const corners = [];
+    for (const x of [-1, 1])
+        for (const y of [-1, 1])
+            for (const z of [-1, 1])
+                corners.push([x, y, z]);
+    const edges = [];
+    for (let i = 0; i < corners.length; i++) {
+        for (let j = i + 1; j < corners.length; j++) {
+            const a = corners[i];
+            const b = corners[j];
+            let differing = 0;
+            for (let k = 0; k < 3; k++)
+                if (a[k] !== b[k])
+                    differing++;
+            if (differing === 1)
+                edges.push([a, b]);
+        }
+    }
+    return edges;
+})();
+/** `q * v * q⁻¹`, the standard two-cross form, into `out`. */
+function rotate(x, y, z, qx, qy, qz, qw, out) {
+    const tx = 2 * (qy * z - qz * y);
+    const ty = 2 * (qz * x - qx * z);
+    const tz = 2 * (qx * y - qy * x);
+    out[0] = x + qw * tx + (qy * tz - qz * ty);
+    out[1] = y + qw * ty + (qz * tx - qx * tz);
+    out[2] = z + qw * tz + (qx * ty - qy * tx);
+}
+/**
+ * Two unit vectors perpendicular to the segment `a → b`, and to each other.
+ *
+ * The perpendicular is taken against whichever world axis the segment points along least, which is
+ * what stops the cross product collapsing for an axis-aligned shape — and every capsule and
+ * cylinder anybody builds is axis-aligned, so the degenerate case is the common one rather than the
+ * exotic one.
+ */
+function basis(a, b, u, v) {
+    let ax = (b[0] ?? 0) - (a[0] ?? 0);
+    let ay = (b[1] ?? 0) - (a[1] ?? 0);
+    let az = (b[2] ?? 0) - (a[2] ?? 0);
+    const length = Math.hypot(ax, ay, az) || 1;
+    ax /= length;
+    ay /= length;
+    az /= length;
+    const absX = Math.abs(ax);
+    const absY = Math.abs(ay);
+    const absZ = Math.abs(az);
+    const px = absX <= absY && absX <= absZ ? 1 : 0;
+    const py = absY < absX && absY <= absZ ? 1 : 0;
+    const pz = px === 0 && py === 0 ? 1 : 0;
+    let ux = ay * pz - az * py;
+    let uy = az * px - ax * pz;
+    let uz = ax * py - ay * px;
+    const ulength = Math.hypot(ux, uy, uz) || 1;
+    ux /= ulength;
+    uy /= ulength;
+    uz /= ulength;
+    u[0] = ux;
+    u[1] = uy;
+    u[2] = uz;
+    v[0] = ay * uz - az * uy;
+    v[1] = az * ux - ax * uz;
+    v[2] = ax * uy - ay * ux;
+}

package/dist/render/decalPass.d.ts

@@ -0,0 +1,34 @@
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { DecalQueue } from './decalQueue.ts';
+/**
+ * Drawn decals on WebGL2: one scissored triangle per mark, multiplied into the finished scene.
+ *
+ * **The whole pass is a blend state and a rectangle.** There is no geometry, no vertex buffer and
+ * no depth test: the mark is decided per pixel from the depth copy, so the only thing the
+ * rasteriser is asked for is coverage of the part of the screen the projector box can possibly
+ * reach. `decalScissor` computes that from the box's eight corners, which is what stands in for
+ * drawing the box as a mesh and is argued there.
+ *
+ * **`(ZERO, SRC_COLOR)` is the effect.** The result is `dst * src`, so a fragment writing white
+ * changes nothing and one writing the mark's colour tints what is under it — including the
+ * receiver's lighting, which is the reason to multiply and is stated at length in the shader.
+ */
+export declare class DecalPass {
+    private readonly gl;
+    private readonly program;
+    private readonly uniforms;
+    private readonly vao;
+    /** `inverse(viewProjection) * DEPTH_01_TO_CLIP`, rebuilt once a frame rather than per mark. */
+    private readonly depthToWorld;
+    private readonly scissor;
+    constructor(gl: WebGL2RenderingContext);
+    /**
+     * Mark the bound framebuffer with everything the queue recorded.
+     *
+     * `viewProjection` is the **raw** camera matrix, not the clip-corrected one: `DEPTH_01_TO_CLIP`
+     * turns a stored depth back into the clip space that matrix was built in, and pairing it with
+     * the corrected one applies the remap twice. `lightVolumeDraw.ts` carries that derivation.
+     */
+    drawDecals(queue: DecalQueue, depth: WebGLTexture, viewProjection: ReadonlyMat4, eye: ArrayLike<number>, width: number, height: number): void;
+    dispose(): void;
+}

package/dist/render/decalPass.js

@@ -0,0 +1,103 @@
+import { mat4 } from 'gl-matrix';
+import { decalScissor } from './decalProjector.js';
+import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.js';
+import { compileProgram, uniformLocations } from './shader.js';
+import { DECAL_PROJECT_FRAG } from './shaders/decalProject.js';
+import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
+/**
+ * Drawn decals on WebGL2: one scissored triangle per mark, multiplied into the finished scene.
+ *
+ * **The whole pass is a blend state and a rectangle.** There is no geometry, no vertex buffer and
+ * no depth test: the mark is decided per pixel from the depth copy, so the only thing the
+ * rasteriser is asked for is coverage of the part of the screen the projector box can possibly
+ * reach. `decalScissor` computes that from the box's eight corners, which is what stands in for
+ * drawing the box as a mesh and is argued there.
+ *
+ * **`(ZERO, SRC_COLOR)` is the effect.** The result is `dst * src`, so a fragment writing white
+ * changes nothing and one writing the mark's colour tints what is under it — including the
+ * receiver's lighting, which is the reason to multiply and is stated at length in the shader.
+ */
+export class DecalPass {
+    gl;
+    program;
+    uniforms;
+    vao;
+    /** `inverse(viewProjection) * DEPTH_01_TO_CLIP`, rebuilt once a frame rather than per mark. */
+    depthToWorld = new Float32Array(16);
+    scissor = new Int32Array(4);
+    constructor(gl) {
+        this.gl = gl;
+        this.program = compileProgram(gl, FULLSCREEN_VERT, DECAL_PROJECT_FRAG, 'decalProject');
+        this.uniforms = uniformLocations(gl, this.program, 'decalPass');
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('DecalPass: createVertexArray failed');
+        this.vao = vao;
+    }
+    /**
+     * Mark the bound framebuffer with everything the queue recorded.
+     *
+     * `viewProjection` is the **raw** camera matrix, not the clip-corrected one: `DEPTH_01_TO_CLIP`
+     * turns a stored depth back into the clip space that matrix was built in, and pairing it with
+     * the corrected one applies the remap twice. `lightVolumeDraw.ts` carries that derivation.
+     */
+    drawDecals(queue, depth, viewProjection, eye, width, height) {
+        if (queue.length === 0)
+            return;
+        const { gl } = this;
+        const u = this.uniforms;
+        mat4.invert(this.depthToWorld, viewProjection);
+        mat4.multiply(this.depthToWorld, this.depthToWorld, DEPTH_01_TO_CLIP);
+        gl.useProgram(this.program);
+        gl.bindVertexArray(this.vao);
+        gl.disable(gl.DEPTH_TEST);
+        gl.depthMask(false);
+        gl.disable(gl.CULL_FACE);
+        gl.enable(gl.BLEND);
+        gl.blendFunc(gl.ZERO, gl.SRC_COLOR);
+        gl.enable(gl.SCISSOR_TEST);
+        /* Unit 0, chosen rather than inherited: `bindTexture` binds to whichever unit is active, and
+           the renderer leaves that wherever its last pass finished. `OitPass` records what leaving it
+           there cost. */
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, depth);
+        gl.uniform1i(u['uDecalDepth'] ?? null, 0);
+        gl.uniformMatrix4fv(u['uDecalDepthToWorld'] ?? null, false, this.depthToWorld);
+        gl.uniform3f(u['uDecalEye'] ?? null, eye[0] ?? 0, eye[1] ?? 0, eye[2] ?? 0);
+        queue.replay((decal) => {
+            /* False when the box is off-screen or wholly behind the eye, and then this mark costs a
+               matrix multiply and no fragments at all. */
+            if (!decalScissor(viewProjection, decal.decalToWorld, width, height, false, this.scissor)) {
+                return;
+            }
+            gl.scissor(this.scissor[0] ?? 0, this.scissor[1] ?? 0, this.scissor[2] ?? 0, this.scissor[3] ?? 0);
+            gl.uniformMatrix4fv(u['uWorldToDecal'] ?? null, false, decal.worldToDecal);
+            gl.uniform3fv(u['uDecalAxis'] ?? null, decal.axis);
+            gl.uniform3fv(u['uDecalColor'] ?? null, decal.color);
+            gl.uniform1f(u['uDecalOpacity'] ?? null, decal.opacity);
+            gl.uniform1f(u['uDecalFacingCos'] ?? null, decal.facingCos);
+            gl.uniform1f(u['uDecalSoftness'] ?? null, decal.softness);
+            gl.drawArrays(gl.TRIANGLES, 0, 3);
+        });
+        gl.disable(gl.SCISSOR_TEST);
+        /* And the whole viewport back, so a later `enable` inherits a rectangle that is not one mark's
+           corner of the screen. */
+        gl.scissor(0, 0, width, height);
+        gl.bindVertexArray(null);
+        /*
+         * **Released, and `OitPass` says why at length.** A binding outlives the frame it was made in,
+         * so unit 0 would keep the depth copy — which a later pass attaches as its own target while a
+         * program still declares a sampler on that unit. That is a feedback loop: reported once per
+         * draw and rasterising something undefined.
+         */
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        gl.disable(gl.BLEND);
+        gl.depthMask(true);
+        gl.enable(gl.DEPTH_TEST);
+    }
+    dispose() {
+        const { gl } = this;
+        gl.deleteProgram(this.program);
+        gl.deleteVertexArray(this.vao);
+    }
+}