@driftengine/core 3.61.0

package/dist/render/passTarget.js

@@ -0,0 +1,121 @@
+import { glSceneDepthFormat } from './depthConvention.js';
+/**
+ * Build one. Called from a pass's `init`, or from its `prepare` when the size has changed.
+ *
+ * **Restores the default framebuffer on WebGL2**, rather than whatever was bound before. Both
+ * points where a pass may call this — `init`, outside a frame, and `prepare`, whose contract is
+ * that the default framebuffer is bound on entry and on exit — have the default bound, so
+ * restoring to it is restoring what was there. Reading the binding back to restore it exactly
+ * would be a synchronous driver query in return for covering a case the contract forbids.
+ *
+ * Fails fast on a size that cannot work, which is the init-time rule: a zero-sized attachment is a
+ * framebuffer that is never complete, and a driver reports that as a black draw rather than an
+ * error.
+ */
+export function createPassAttachment(device, options) {
+    const { width, height } = options;
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 1 || height < 1) {
+        throw new Error(`createPassAttachment: ${width}x${height} is not a size — width and height must be positive integers`);
+    }
+    const wantDepth = options.depth ?? true;
+    const label = options.label ?? 'pass target';
+    const format = options.format ?? 'rgba8';
+    if (device.backend === 'webgpu') {
+        const { device: gpu } = device;
+        /*
+         * The two usage bits by value, which is what this renderer already does at every other
+         * `createTexture`: `GPUTextureUsage` is a global the type definitions declare and Node does
+         * not provide, so naming it here would make this module unimportable in a test that never
+         * touches a GPU.
+         */
+        const RENDER_ATTACHMENT = 0x10;
+        const TEXTURE_BINDING = 0x04;
+        const colour = gpu.createTexture({
+            label: `${label} colour`,
+            size: { width, height },
+            format: format === 'rgba8' ? 'rgba8unorm' : 'rgba16float',
+            usage: RENDER_ATTACHMENT | TEXTURE_BINDING,
+        });
+        /* The frame's own depth format, so a pass may build one pipeline for its target and the
+           frame rather than two that differ in a field it did not choose. */
+        const depth = wantDepth
+            ? gpu.createTexture({
+                label: `${label} depth`,
+                size: { width, height },
+                format: device.depthFormat,
+                usage: RENDER_ATTACHMENT,
+            })
+            : null;
+        return {
+            backend: 'webgpu',
+            width,
+            height,
+            colour,
+            colourView: colour.createView(),
+            depth,
+            depthView: depth === null ? null : depth.createView(),
+            format: colour.format,
+            depthFormat: depth === null ? null : device.depthFormat,
+            dispose() {
+                colour.destroy();
+                depth?.destroy();
+            },
+        };
+    }
+    const { gl } = device;
+    const colour = gl.createTexture();
+    if (colour === null)
+        throw new Error('createPassAttachment: the context refused a texture');
+    gl.bindTexture(gl.TEXTURE_2D, colour);
+    gl.texImage2D(gl.TEXTURE_2D, 0, format === 'rgba8' ? gl.RGBA8 : gl.RGBA16F, width, height, 0, gl.RGBA, format === 'rgba8' ? gl.UNSIGNED_BYTE : gl.HALF_FLOAT, null);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+    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);
+    let depth = null;
+    if (wantDepth) {
+        const sceneDepth = glSceneDepthFormat(gl);
+        depth = gl.createTexture();
+        if (depth === null)
+            throw new Error('createPassAttachment: the context refused a texture');
+        gl.bindTexture(gl.TEXTURE_2D, depth);
+        gl.texImage2D(gl.TEXTURE_2D, 0, sceneDepth.internalFormat, width, height, 0, gl.DEPTH_COMPONENT, sceneDepth.type, null);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        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('createPassAttachment: the context refused a framebuffer');
+    }
+    gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+    gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, colour, 0);
+    if (depth !== null) {
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, depth, 0);
+    }
+    const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    if (status !== gl.FRAMEBUFFER_COMPLETE) {
+        gl.deleteFramebuffer(framebuffer);
+        gl.deleteTexture(colour);
+        if (depth !== null)
+            gl.deleteTexture(depth);
+        throw new Error(`createPassAttachment: framebuffer incomplete (0x${status.toString(16)})`);
+    }
+    return {
+        backend: 'webgl2',
+        width,
+        height,
+        framebuffer,
+        colour,
+        depth,
+        dispose() {
+            gl.deleteFramebuffer(framebuffer);
+            gl.deleteTexture(colour);
+            if (depth !== null)
+                gl.deleteTexture(depth);
+        },
+    };
+}

package/dist/render/pickable.d.ts

@@ -0,0 +1,31 @@
+export interface PickableSource {
+    readonly positions: Float32Array;
+    readonly indices: Uint32Array;
+}
+export interface PickHit {
+    handle: number;
+    distance: number;
+    /** Where the ray met it, in world space. Reused between queries; copy to keep it. */
+    readonly point: Float32Array;
+}
+export declare class PickableSet {
+    private readonly entries;
+    private nextHandle;
+    private readonly localOrigin;
+    private readonly localDirection;
+    private readonly hit;
+    add(source: PickableSource, model: Float32Array): number;
+    update(handle: number, model: Float32Array): void;
+    remove(handle: number): void;
+    clear(): void;
+    /** The nearest registered mesh along the ray, or null. */
+    pick(origin: ArrayLike<number>, direction: ArrayLike<number>): PickHit | null;
+    /**
+     * Re-take the model matrix, its inverse and the world-space box.
+     *
+     * The box is the transformed corners' extent rather than the transformed local box,
+     * which for a rotated mesh is looser than tight and tighter than wrong. A loose broad
+     * phase costs triangles; a wrong one loses picks.
+     */
+    private refresh;
+}

package/dist/render/pickable.js

@@ -0,0 +1,172 @@
+/**
+ * What is under a ray, from a set of registered meshes.
+ *
+ * Backend-agnostic on purpose: nothing here touches a context, so one implementation
+ * answers for WebGL2 and WebGPU alike and the tests need neither. Same argument
+ * `textLayout.ts` makes for keeping glyph arithmetic out of the two text renderers.
+ *
+ * **Broad phase then narrow phase.** A world-space box per entry rejects nearly
+ * everything for the cost of six compares, and only survivors pay for their triangles.
+ * Without it a scene of forty pickables would walk every triangle of all of them on every
+ * pointer move.
+ *
+ * **The box is recomputed when a model matrix is set, not when a ray is cast.** A scene
+ * moves a handful of things per frame and casts one ray per pointer move, so the work
+ * belongs on the write.
+ */
+import { rayAabb, rayTriangle } from '../math/intersect.js';
+export class PickableSet {
+    entries = [];
+    nextHandle = 1;
+    /* Reused per query: a pick runs on pointermove and must not allocate. */
+    localOrigin = new Float32Array(3);
+    localDirection = new Float32Array(3);
+    hit = { handle: 0, distance: 0, point: new Float32Array(3) };
+    add(source, model) {
+        const handle = this.nextHandle++;
+        const entry = {
+            handle,
+            source,
+            model: new Float32Array(model),
+            inverse: new Float32Array(16),
+            min: new Float32Array(3),
+            max: new Float32Array(3),
+        };
+        this.entries.push(entry);
+        this.refresh(entry, model);
+        return handle;
+    }
+    update(handle, model) {
+        const entry = this.entries.find((candidate) => candidate.handle === handle);
+        if (entry === undefined)
+            return;
+        this.refresh(entry, model);
+    }
+    remove(handle) {
+        const at = this.entries.findIndex((candidate) => candidate.handle === handle);
+        if (at >= 0)
+            this.entries.splice(at, 1);
+    }
+    clear() {
+        this.entries.length = 0;
+    }
+    /** The nearest registered mesh along the ray, or null. */
+    pick(origin, direction) {
+        let best = Infinity;
+        let bestEntry = null;
+        for (const entry of this.entries) {
+            const broad = rayAabb(origin, direction, entry.min, entry.max);
+            if (broad < 0 || broad > best)
+                continue;
+            transformPoint(this.localOrigin, entry.inverse, origin);
+            transformDirection(this.localDirection, entry.inverse, direction);
+            const { positions, indices } = entry.source;
+            for (let i = 0; i + 2 < indices.length; i += 3) {
+                const distance = rayTriangle(this.localOrigin, this.localDirection, positions, indices[i], indices[i + 1], indices[i + 2]);
+                if (distance >= 0 && distance < best) {
+                    best = distance;
+                    bestEntry = entry;
+                }
+            }
+        }
+        if (bestEntry === null)
+            return null;
+        this.hit.handle = bestEntry.handle;
+        this.hit.distance = best;
+        this.hit.point[0] = origin[0] + direction[0] * best;
+        this.hit.point[1] = origin[1] + direction[1] * best;
+        this.hit.point[2] = origin[2] + direction[2] * best;
+        return this.hit;
+    }
+    /**
+     * Re-take the model matrix, its inverse and the world-space box.
+     *
+     * The box is the transformed corners' extent rather than the transformed local box,
+     * which for a rotated mesh is looser than tight and tighter than wrong. A loose broad
+     * phase costs triangles; a wrong one loses picks.
+     */
+    refresh(entry, model) {
+        entry.model.set(model);
+        invertAffine(entry.inverse, model);
+        const { positions } = entry.source;
+        entry.min.fill(Infinity);
+        entry.max.fill(-Infinity);
+        for (let i = 0; i + 2 < positions.length; i += 3) {
+            for (let axis = 0; axis < 3; axis++) {
+                const value = model[axis] * positions[i] +
+                    model[axis + 4] * positions[i + 1] +
+                    model[axis + 8] * positions[i + 2] +
+                    model[axis + 12];
+                if (value < entry.min[axis])
+                    entry.min[axis] = value;
+                if (value > entry.max[axis])
+                    entry.max[axis] = value;
+            }
+        }
+    }
+}
+/** A point through a 4x4, with the translation. */
+function transformPoint(out, m, p) {
+    for (let axis = 0; axis < 3; axis++) {
+        out[axis] =
+            m[axis] * p[0] +
+                m[axis + 4] * p[1] +
+                m[axis + 8] * p[2] +
+                m[axis + 12];
+    }
+}
+/**
+ * A direction through a 4x4, without the translation, left unnormalised on purpose.
+ *
+ * `localOrigin` and this are both built from the same inverse matrix, so the local ray
+ * `localOrigin + t * localDirection` is `inverse(model)` applied to the world ray
+ * `origin + t * direction` at every `t` — the model's linear part and its inverse cancel.
+ * That makes `t` itself invariant under the transform, scale included, uniform or not, so
+ * the `t` `rayTriangle` finds in local space is already the caller's world-space distance.
+ * Normalising this would break that: it would rescale `t` by this vector's length and
+ * `rayTriangle` would start returning a value that needs converting back, for nothing
+ * gained.
+ */
+function transformDirection(out, m, d) {
+    for (let axis = 0; axis < 3; axis++) {
+        out[axis] =
+            m[axis] * d[0] +
+                m[axis + 4] * d[1] +
+                m[axis + 8] * d[2];
+    }
+}
+/**
+ * The inverse of a model matrix, assuming it is affine.
+ *
+ * Every model matrix this engine produces is translation, rotation and scale, so the
+ * general 4x4 inverse would be arithmetic spent on a bottom row that is always
+ * `0 0 0 1`. Written out rather than reached for from gl-matrix because this is called
+ * whenever anything moves.
+ */
+function invertAffine(out, m) {
+    const a = m[0], b = m[1], c = m[2];
+    const d = m[4], e = m[5], f = m[6];
+    const g = m[8], h = m[9], i = m[10];
+    const A = e * i - f * h;
+    const B = f * g - d * i;
+    const C = d * h - e * g;
+    const determinant = a * A + b * B + c * C;
+    const s = determinant === 0 ? 0 : 1 / determinant;
+    out[0] = A * s;
+    out[1] = (c * h - b * i) * s;
+    out[2] = (b * f - c * e) * s;
+    out[3] = 0;
+    out[4] = B * s;
+    out[5] = (a * i - c * g) * s;
+    out[6] = (c * d - a * f) * s;
+    out[7] = 0;
+    out[8] = C * s;
+    out[9] = (b * g - a * h) * s;
+    out[10] = (a * e - b * d) * s;
+    out[11] = 0;
+    const tx = m[12], ty = m[13], tz = m[14];
+    out[12] = -(out[0] * tx + out[4] * ty + out[8] * tz);
+    out[13] = -(out[1] * tx + out[5] * ty + out[9] * tz);
+    out[14] = -(out[2] * tx + out[6] * ty + out[10] * tz);
+    out[15] = 1;
+}

package/dist/render/planarReflection.d.ts

@@ -0,0 +1,59 @@
+/** GPU target and mirrored camera for one horizontal planar reflection. */
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { Vec3 } from '../math/color.ts';
+import { Camera } from './camera.ts';
+export declare class PlanarReflection {
+    /** `RenderQuality.discardResolvedAttachments`, and see `end` for what it decides. */
+    private readonly discardResolved;
+    readonly camera: Camera;
+    readonly clipPlane: Float32Array<ArrayBuffer>;
+    readonly texture: WebGLTexture;
+    private readonly framebuffer;
+    private readonly depth;
+    private readonly scale;
+    private readonly maxTextureSize;
+    private width;
+    private height;
+    /** Refilled per resize rather than allocated; `ensureSize` runs from `Renderer.resize`. */
+    private readonly size;
+    private planeY;
+    private ready;
+    /**
+     * Set once the target proves it cannot be allocated, and never cleared.
+     *
+     * A reflection is an optimisation of appearance, not a requirement: a world without
+     * one still renders, and `WaterRenderer` already has a complete path for water that
+     * has no reflection to sample. So a device that refuses the allocation should lose the
+     * reflection and keep the scene, which is what this makes possible.
+     */
+    private unusable;
+    constructor(gl: WebGL2RenderingContext, scale: number, maxTextureSize: number, 
+    /** `RenderQuality.discardResolvedAttachments`, and see `end` for what it decides. */
+    discardResolved?: boolean);
+    get viewProjection(): ReadonlyMat4;
+    get textureWidth(): number;
+    get textureHeight(): number;
+    /** True only after this target was rendered for the supplied water plane. */
+    isReadyFor(planeY: number): boolean;
+    /** Whether this target can be rendered into at all. See `unusable`. */
+    get usable(): boolean;
+    /** Bind, clear and return the persistent camera mirrored across `planeY`. */
+    begin(gl: WebGL2RenderingContext, canvasWidth: number, canvasHeight: number, source: Camera, planeY: number, clearColor: Vec3): Camera;
+    end(gl: WebGL2RenderingContext): void;
+    dispose(gl: WebGL2RenderingContext): void;
+    /**
+     * Allocate the target now, rather than on the first frame that shows water.
+     *
+     * The target is a full drawing-buffer RGBA8 texture and a depth renderbuffer, so on
+     * a large display it is tens of megabytes. Allocated lazily, that landed in whichever
+     * frame first put water on screen — measured as 28% of a 62 ms frame the first time a
+     * character came within sight of it, which is a stall in the middle of play rather than
+     * during a load.
+     *
+     * The renderer calls this from `resize`, so the cost is paid where every other
+     * allocation of this size is paid: once, at the size the frame is about to be, while
+     * the loading plate is still up.
+     */
+    prepare(gl: WebGL2RenderingContext, canvasWidth: number, canvasHeight: number): void;
+    private ensureSize;
+}

package/dist/render/planarReflection.js

@@ -0,0 +1,194 @@
+/** GPU target and mirrored camera for one horizontal planar reflection. */
+import { Camera } from './camera.js';
+import { mirrorCamera, reflectionClipPlane, reflectionTargetSize, } from './planarReflectionDraw.js';
+export class PlanarReflection {
+    discardResolved;
+    camera = new Camera();
+    clipPlane = new Float32Array(4);
+    texture;
+    framebuffer;
+    depth;
+    scale;
+    maxTextureSize;
+    width = 0;
+    height = 0;
+    /** Refilled per resize rather than allocated; `ensureSize` runs from `Renderer.resize`. */
+    size = { width: 0, height: 0 };
+    planeY = 0;
+    ready = false;
+    /**
+     * Set once the target proves it cannot be allocated, and never cleared.
+     *
+     * A reflection is an optimisation of appearance, not a requirement: a world without
+     * one still renders, and `WaterRenderer` already has a complete path for water that
+     * has no reflection to sample. So a device that refuses the allocation should lose the
+     * reflection and keep the scene, which is what this makes possible.
+     */
+    unusable = false;
+    constructor(gl, scale, maxTextureSize, 
+    /** `RenderQuality.discardResolvedAttachments`, and see `end` for what it decides. */
+    discardResolved = true) {
+        this.discardResolved = discardResolved;
+        this.scale = scale;
+        this.maxTextureSize = maxTextureSize;
+        const texture = gl.createTexture();
+        if (texture === null)
+            throw new Error('PlanarReflection: createTexture failed');
+        this.texture = texture;
+        gl.bindTexture(gl.TEXTURE_2D, texture);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        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 depth = gl.createRenderbuffer();
+        if (depth === null)
+            throw new Error('PlanarReflection: createRenderbuffer failed');
+        this.depth = depth;
+        const framebuffer = gl.createFramebuffer();
+        if (framebuffer === null)
+            throw new Error('PlanarReflection: createFramebuffer failed');
+        this.framebuffer = framebuffer;
+        gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+    get viewProjection() {
+        return this.camera.viewProjection;
+    }
+    get textureWidth() {
+        return this.width;
+    }
+    get textureHeight() {
+        return this.height;
+    }
+    /** True only after this target was rendered for the supplied water plane. */
+    isReadyFor(planeY) {
+        return this.ready && Math.abs(this.planeY - planeY) < 1e-4;
+    }
+    /** Whether this target can be rendered into at all. See `unusable`. */
+    get usable() {
+        return !this.unusable;
+    }
+    /** Bind, clear and return the persistent camera mirrored across `planeY`. */
+    begin(gl, canvasWidth, canvasHeight, source, planeY, clearColor) {
+        this.ensureSize(gl, canvasWidth, canvasHeight);
+        this.planeY = planeY;
+        /* Both chosen in `planarReflectionDraw.ts`, so both backends mirror the same world. */
+        const reflected = this.camera;
+        mirrorCamera(source, planeY, this.width / this.height, reflected);
+        reflectionClipPlane(source.position[1] ?? 0, planeY, this.clipPlane);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+        gl.viewport(0, 0, this.width, this.height);
+        gl.clearColor(clearColor[0], clearColor[1], clearColor[2], 1);
+        gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
+        return reflected;
+    }
+    end(gl) {
+        /*
+         * **The mirror's depth is finished with the moment the mirror is.**
+         *
+         * It is a `DEPTH_COMPONENT24` *renderbuffer*, so no shader can sample it — the same argument
+         * `SceneTarget.resolve` makes about the multisampled pair, and the same one the WebGPU
+         * backend acts on with `depthStoreOp: 'discard'`. This asymmetry between the two backends
+         * was the thing worth finding: one threw the attachment away and the other unbound and left
+         * it, so a tile-based GPU wrote a full drawing-buffer depth attachment out to memory every
+         * frame that reflected, for a reader that cannot exist. At 824x1830 that is 6.0 MB a frame
+         * a mirror, and the consumer draws two.
+         *
+         * **Before the unbind, deliberately.** `invalidateFramebuffer` acts on whatever is bound to
+         * the target it is given, so below the next line it would name the default framebuffer,
+         * which is the frame. `SceneTarget.resolve` carries the same warning for the same reason.
+         */
+        if (this.discardResolved) {
+            gl.invalidateFramebuffer(gl.FRAMEBUFFER, [gl.DEPTH_ATTACHMENT]);
+        }
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        this.ready = true;
+    }
+    dispose(gl) {
+        gl.deleteFramebuffer(this.framebuffer);
+        gl.deleteRenderbuffer(this.depth);
+        gl.deleteTexture(this.texture);
+    }
+    /**
+     * Allocate the target now, rather than on the first frame that shows water.
+     *
+     * The target is a full drawing-buffer RGBA8 texture and a depth renderbuffer, so on
+     * a large display it is tens of megabytes. Allocated lazily, that landed in whichever
+     * frame first put water on screen — measured as 28% of a 62 ms frame the first time a
+     * character came within sight of it, which is a stall in the middle of play rather than
+     * during a load.
+     *
+     * The renderer calls this from `resize`, so the cost is paid where every other
+     * allocation of this size is paid: once, at the size the frame is about to be, while
+     * the loading plate is still up.
+     */
+    prepare(gl, canvasWidth, canvasHeight) {
+        this.ensureSize(gl, canvasWidth, canvasHeight);
+    }
+    ensureSize(gl, canvasWidth, canvasHeight) {
+        // One refusal is enough. Retrying every resize would spend the same memory asking
+        // the same question and would put the warning back in the frame loop.
+        if (this.unusable)
+            return;
+        /* Clamped by one shared factor rather than per axis; see `reflectionTargetSize`. */
+        const { width, height } = reflectionTargetSize(canvasWidth, canvasHeight, this.scale, this.maxTextureSize, this.size);
+        if (width === this.width && height === this.height)
+            return;
+        this.width = width;
+        this.height = height;
+        this.ready = false;
+        gl.bindTexture(gl.TEXTURE_2D, this.texture);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+        gl.bindRenderbuffer(gl.RENDERBUFFER, this.depth);
+        gl.renderbufferStorage(gl.RENDERBUFFER, gl.DEPTH_COMPONENT24, width, height);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.texture, 0);
+        gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.RENDERBUFFER, this.depth);
+        const status = gl.checkFramebufferStatus(gl.FRAMEBUFFER);
+        if (status !== gl.FRAMEBUFFER_COMPLETE) {
+            /*
+             * A lost context reports every attachment as unusable, so this check fires with
+             * FRAMEBUFFER_UNSUPPORTED (0x8CDD) for a reason that is not a programming error
+             * and cannot be fixed by the caller. Throwing there breaks the engine's own rule
+             * that only init fails loudly and the running frame never throws — and it broke it
+             * from `Renderer.resize`, a window listener, so the exception escaped into the
+             * page rather than into anything that could handle it.
+             *
+             * It was reported as an uncaught throw immediately after CONTEXT_LOST_WEBGL.
+             * A genuine misconfiguration still throws; a dead context is simply nothing to do.
+             */
+            if (gl.isContextLost())
+                return;
+            /*
+             * A refused allocation disables the reflection. It does not stop the frame.
+             *
+             * This used to throw, and the throw was reached from `Renderer.resize` — which a
+             * consumer calls every frame. On a device that cannot afford this target the
+             * result was not a missing reflection, it was an exception escaping the middle of
+             * every single frame: nothing after `resize` ran, the canvas kept whatever was
+             * last drawn, and the scene appeared to render as a fragment of itself. Reported
+             * from an iOS webview as a room with only its fire in it, on the one scene in the
+             * project that uses a planar reflection.
+             *
+             * It also broke the rule the block above already states, and states correctly:
+             * only initialisation fails loudly, and a running frame never throws. A driver
+             * refusing tens of megabytes on a memory-constrained device is the same category
+             * as a lost context — not a programming error, and not something the caller can
+             * fix by being more careful.
+             *
+             * Loud in the console, because a genuine misconfiguration must still be findable,
+             * and once rather than sixty times a second.
+             */
+            this.unusable = true;
+            this.ready = false;
+            console.warn(`PlanarReflection: framebuffer incomplete (0x${status.toString(16)}) at ` +
+                `${width}x${height}; reflections are off for the rest of this session.`);
+            gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+            gl.bindRenderbuffer(gl.RENDERBUFFER, null);
+            gl.bindTexture(gl.TEXTURE_2D, null);
+            return;
+        }
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.bindRenderbuffer(gl.RENDERBUFFER, null);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+    }
+}

package/dist/render/planarReflectionDraw.d.ts

@@ -0,0 +1,31 @@
+import type { Camera } from './camera.ts';
+/**
+ * Stand the camera on the other side of the plane, looking back.
+ *
+ * A mirror across a horizontal plane negates height about it and negates pitch, and leaves yaw
+ * and the lens alone. **The aspect is the target's rather than the canvas's**: a reflection is
+ * rendered at a scale, and projecting it at the canvas's aspect stretches the mirror against
+ * the surface it is sampled onto.
+ */
+export declare function mirrorCamera(source: Camera, planeY: number, aspect: number, out: Camera): void;
+/**
+ * The half-space the mirrored pass may draw, as `dot(vec4(worldPos, 1), plane) >= 0`.
+ *
+ * **A mirror reflects the scene on the viewer's side of the plane**, so which side that is
+ * follows the camera: above water it keeps y ≥ plane, below it keeps y ≤ plane. Deciding it
+ * from a constant instead is a reflection that inverts the moment a swimmer's head goes under.
+ */
+export declare function reflectionClipPlane(sourceY: number, planeY: number, out: Float32Array): void;
+/** How large a reflection target may be, given the drawing buffer and the device's ceiling. */
+export interface ReflectionSize {
+    width: number;
+    height: number;
+}
+/**
+ * Size the target, clamped by **one shared factor** rather than per axis.
+ *
+ * Clamping each axis independently squashes the reflection on a drawing buffer wider than the
+ * GPU's texture limit, because the mirror is then rendered at one aspect and sampled at
+ * another. Scaling both by the tighter of the two ratios keeps it square and merely smaller.
+ */
+export declare function reflectionTargetSize(canvasWidth: number, canvasHeight: number, scale: number, maxTextureSize: number, out: ReflectionSize): ReflectionSize;

package/dist/render/planarReflectionDraw.js

@@ -0,0 +1,65 @@
+/**
+ * What a planar reflection *is*, before any of it touches a device.
+ *
+ * Three decisions, none of which is a binding: where the mirrored camera stands, which half of
+ * the world it may draw, and how large the target may be. A second copy of any of them is a
+ * mirror that disagrees with itself — a reflection shot from a slightly different place, or one
+ * that leaks the near bank of a pool into the water in front of it — and every one of those
+ * reads as a shading problem rather than as a camera one. That is the 2026-08-13 rule in
+ * `AGENTS.md`, applied to the pass with the most arithmetic in it.
+ */
+/**
+ * Keeps fragments crossing the resting plane from opening a hairline seam.
+ *
+ * The clip is a plane test on a *displaced* surface, so geometry that touches the waterline
+ * lands on both sides of it by a fraction of a millimetre depending on the wave. Three
+ * centimetres of tolerance keeps the shoreline welded; more than that starts showing the
+ * underside of things standing in the water.
+ */
+const CLIP_TOLERANCE = 0.03;
+/**
+ * Stand the camera on the other side of the plane, looking back.
+ *
+ * A mirror across a horizontal plane negates height about it and negates pitch, and leaves yaw
+ * and the lens alone. **The aspect is the target's rather than the canvas's**: a reflection is
+ * rendered at a scale, and projecting it at the canvas's aspect stretches the mirror against
+ * the surface it is sampled onto.
+ */
+export function mirrorCamera(source, planeY, aspect, out) {
+    out.position[0] = source.position[0] ?? 0;
+    out.position[1] = planeY * 2 - (source.position[1] ?? 0);
+    out.position[2] = source.position[2] ?? 0;
+    out.yaw = source.yaw;
+    out.pitch = -source.pitch;
+    out.fovYDeg = source.fovYDeg;
+    out.near = source.near;
+    out.far = source.far;
+    out.updateMatrices(aspect);
+}
+/**
+ * The half-space the mirrored pass may draw, as `dot(vec4(worldPos, 1), plane) >= 0`.
+ *
+ * **A mirror reflects the scene on the viewer's side of the plane**, so which side that is
+ * follows the camera: above water it keeps y ≥ plane, below it keeps y ≤ plane. Deciding it
+ * from a constant instead is a reflection that inverts the moment a swimmer's head goes under.
+ */
+export function reflectionClipPlane(sourceY, planeY, out) {
+    const side = sourceY >= planeY ? 1 : -1;
+    out[0] = 0;
+    out[1] = side;
+    out[2] = 0;
+    out[3] = -side * planeY + CLIP_TOLERANCE;
+}
+/**
+ * Size the target, clamped by **one shared factor** rather than per axis.
+ *
+ * Clamping each axis independently squashes the reflection on a drawing buffer wider than the
+ * GPU's texture limit, because the mirror is then rendered at one aspect and sampled at
+ * another. Scaling both by the tighter of the two ratios keeps it square and merely smaller.
+ */
+export function reflectionTargetSize(canvasWidth, canvasHeight, scale, maxTextureSize, out) {
+    const targetScale = Math.min(scale, maxTextureSize / Math.max(canvasWidth, 1), maxTextureSize / Math.max(canvasHeight, 1));
+    out.width = Math.max(Math.round(canvasWidth * targetScale), 1);
+    out.height = Math.max(Math.round(canvasHeight * targetScale), 1);
+    return out;
+}