@driftengine/core 3.61.0

package/dist/input/touchControls.js

@@ -0,0 +1,352 @@
+/** Configurable two-zone mobile controls over raw touch input. */
+import { InputSource } from './input.js';
+import { classifyRightGesture, isTapRelease } from './rightGesture.js';
+/**
+ * Second-zone touches beyond the first, and what they may do.
+ *
+ * The first thumb in the zone owns everything continuous: the look, and the
+ * held form of the primary. Anything after it owns only *edges* — a tap, a
+ * flick — because two fingers contributing look at once is one camera being
+ * dragged in two directions, which is a worse control than the one this fixes.
+ *
+ * They exist at all because the zone used to drop every touch after the first
+ * outright: a player steering through a corner could not jump out of it without
+ * letting go of the corner.
+ */
+const EXTRA_SLOTS = 3;
+const NO_TOUCH = -1;
+/**
+ * A reusable mobile scheme: dynamic stick on the first zone; look plus a
+ * primary tap/hold and secondary downward swipe on the second. The class
+ * reports generic control state. A game decides whether those signals mean
+ * jump, fire, crouch, slide, or anything else.
+ */
+export class TouchControls {
+    moveX = 0;
+    moveY = 0;
+    primaryHeld = false;
+    secondaryHeld = false;
+    onFirstTouch = null;
+    primaryQueued = false;
+    lookDx = 0;
+    lookDy = 0;
+    leftId = null;
+    rightId = null;
+    rightMode = 'pending';
+    rightLastX = 0;
+    rightLastY = 0;
+    /** Greatest distance the owning touch has reached from where it landed. */
+    rightTravel = 0;
+    rightStart = null;
+    firstTouchSeen = false;
+    /*
+     * The extra second-zone touches, as parallel fixed arrays: a touch event
+     * arrives as often as a frame does while a thumb is down, so nothing on this
+     * path may allocate.
+     */
+    extraIds = new Int32Array(EXTRA_SLOTS).fill(NO_TOUCH);
+    extraTravel = new Float32Array(EXTRA_SLOTS);
+    extraSliding = new Uint8Array(EXTRA_SLOTS);
+    /** Whether the owning touch is the one holding the secondary. */
+    ownerSliding = false;
+    stickBase;
+    stickNub;
+    surface;
+    splitRatio;
+    stickRadiusPx;
+    stickDeadzone;
+    gestureMovePx;
+    holdResolveMs;
+    tapMaxMs;
+    fireOnHold;
+    swipeMaxMs;
+    swipeDominance;
+    unsubscribe;
+    constructor(input, second = {}, third, fourth = {}) {
+        /*
+         * **A third argument means the positional form, and nothing about the second is inspected.**
+         *
+         * Sniffing the second argument was tried first and is wrong: `instanceof HTMLElement` needs a
+         * DOM constructor this package is checked without, and duck-typing on `nodeType` reads a
+         * stand-in element as an options object — which this file's own harness supplies, so the first
+         * version silently dropped every option a positional caller passed. The arity carries the
+         * answer without asking what anything is.
+         */
+        const positional = third !== undefined;
+        const options = positional ? fourth : second;
+        this.stickBase = positional ? second : (options.stickBase ?? null);
+        this.stickNub = positional ? (third ?? null) : (options.stickNub ?? null);
+        this.surface = input.target;
+        this.splitRatio = options.splitRatio ?? 0.5;
+        this.stickRadiusPx = options.stickRadiusPx ?? 40;
+        this.stickDeadzone = options.stickDeadzone ?? 0.12;
+        /*
+         * Twenty rather than fourteen: a thumb rolls a little as it lands, and at
+         * fourteen that roll turned a tap into a two-degree camera nudge. Nothing
+         * is lost at the start of a look, because the travel that resolves one is
+         * credited to it (see `onMove`).
+         */
+        this.gestureMovePx = options.gestureMovePx ?? 20;
+        this.holdResolveMs = options.holdResolveMs ?? 90;
+        this.tapMaxMs = options.tapMaxMs ?? 180;
+        this.fireOnHold = options.fireOnHold ?? false;
+        this.swipeMaxMs = options.swipeMaxMs ?? 160;
+        this.swipeDominance = options.swipeDominance ?? 2.4;
+        this.validateOptions();
+        this.unsubscribe = input.subscribe({
+            onTouchStart: (touch) => this.onStart(touch),
+            onTouchMove: (touch) => this.onMove(touch),
+            onTouchEnd: (touch, durationMs) => this.onEnd(touch, durationMs),
+        });
+    }
+    /** Resolve a still second-zone touch into the generic primary hold. */
+    tick(nowMs) {
+        const start = this.rightStart;
+        if (this.rightMode !== 'pending' || start === null)
+            return;
+        if (nowMs - start.startTime >= this.holdResolveMs) {
+            // Held, not fired: see `fireOnHold`. A motionless thumb is somebody deciding
+            // where to look, and firing under it is the bug this exists to prevent.
+            if (this.fireOnHold)
+                this.primaryQueued = true;
+            this.primaryHeld = true;
+            this.rightMode = 'primary-hold';
+        }
+    }
+    /** Consume the primary edge exactly once. */
+    consumePrimaryPress() {
+        const queued = this.primaryQueued;
+        this.primaryQueued = false;
+        return queued;
+    }
+    /** Drain accumulated second-zone look motion into a caller-owned object. */
+    consumeLook(out) {
+        out.dx = this.lookDx;
+        out.dy = this.lookDy;
+        this.lookDx = 0;
+        this.lookDy = 0;
+    }
+    dispose() {
+        this.unsubscribe();
+        if (this.stickBase !== null)
+            this.stickBase.hidden = true;
+        this.moveX = 0;
+        this.moveY = 0;
+        this.primaryHeld = false;
+        this.secondaryHeld = false;
+        this.ownerSliding = false;
+        this.extraIds.fill(NO_TOUCH);
+        this.extraSliding.fill(0);
+    }
+    onStart(touch) {
+        if (!this.firstTouchSeen) {
+            this.firstTouchSeen = true;
+            this.onFirstTouch?.();
+        }
+        const bounds = this.surface.getBoundingClientRect();
+        const splitX = bounds.left + bounds.width * this.splitRatio;
+        if (touch.startX < splitX) {
+            if (this.leftId !== null)
+                return;
+            this.leftId = touch.id;
+            this.showStick(touch.startX, touch.startY);
+            return;
+        }
+        if (this.rightId !== null) {
+            this.claimExtra(touch.id);
+            return;
+        }
+        this.rightId = touch.id;
+        this.rightMode = 'pending';
+        this.rightStart = touch;
+        this.rightTravel = 0;
+        this.rightLastX = touch.x;
+        this.rightLastY = touch.y;
+    }
+    onMove(touch) {
+        if (touch.id === this.leftId) {
+            this.updateStick(touch);
+            return;
+        }
+        if (touch.id !== this.rightId) {
+            this.moveExtra(touch);
+            return;
+        }
+        const dx = touch.x - touch.startX;
+        const dy = touch.y - touch.startY;
+        this.rightTravel = Math.max(this.rightTravel, Math.hypot(dx, dy));
+        if (this.rightMode === 'pending') {
+            const gesture = this.classify(touch, dx, dy);
+            if (gesture === 'secondary') {
+                this.rightMode = 'secondary';
+                this.ownerSliding = true;
+                this.secondaryHeld = true;
+            }
+            else if (gesture === 'look') {
+                this.rightMode = 'look';
+                /*
+                 * Credit the travel that resolved the gesture. Starting the count from
+                 * here instead threw away the first dozen pixels of every drag, which
+                 * is a dead zone at the start of each look and reads as the camera
+                 * being slow to respond rather than as an input being dropped.
+                 */
+                this.lookDx += dx;
+                this.lookDy += dy;
+                this.rightLastX = touch.x;
+                this.rightLastY = touch.y;
+            }
+        }
+        else if (this.rightMode === 'look' || this.rightMode === 'primary-hold') {
+            /*
+             * A held thumb still looks, and keeps holding while it does.
+             *
+             * The hold used to be a terminal state: once a motionless touch resolved
+             * into it, the same thumb could no longer move the camera for the rest of
+             * its life. That is the wrong half of the input to freeze — the held form
+             * is for verbs that last (a glide), and a verb that lasts is exactly the
+             * one you need to steer through.
+             */
+            this.lookDx += touch.x - this.rightLastX;
+            this.lookDy += touch.y - this.rightLastY;
+        }
+        this.rightLastX = touch.x;
+        this.rightLastY = touch.y;
+    }
+    onEnd(touch, durationMs) {
+        if (touch.id === this.leftId) {
+            this.leftId = null;
+            this.moveX = 0;
+            this.moveY = 0;
+            if (this.stickBase !== null)
+                this.stickBase.hidden = true;
+            return;
+        }
+        if (touch.id !== this.rightId) {
+            this.endExtra(touch, durationMs);
+            return;
+        }
+        /*
+         * `primary-hold` counts as a tap here, and that is the fix. It is the state
+         * a still thumb is promoted into after `holdResolveMs`, so the old test —
+         * fire only from `pending` — threw away every tap slower than 90 ms, which
+         * on a phone is most of them. `isTapRelease` decides on travel and duration
+         * instead, which is what a tap actually is.
+         */
+        if ((this.rightMode === 'pending' || this.rightMode === 'primary-hold') &&
+            this.isTap(this.rightTravel, durationMs)) {
+            this.primaryQueued = true;
+        }
+        if (this.rightMode === 'secondary') {
+            this.ownerSliding = false;
+            this.refreshSecondary();
+        }
+        if (this.rightMode === 'primary-hold')
+            this.primaryHeld = false;
+        this.rightId = null;
+        this.rightStart = null;
+        this.rightMode = 'pending';
+        this.rightTravel = 0;
+    }
+    claimExtra(id) {
+        for (let i = 0; i < EXTRA_SLOTS; i++) {
+            if (this.extraIds[i] !== NO_TOUCH)
+                continue;
+            this.extraIds[i] = id;
+            this.extraTravel[i] = 0;
+            this.extraSliding[i] = 0;
+            return;
+        }
+    }
+    extraSlot(id) {
+        for (let i = 0; i < EXTRA_SLOTS; i++) {
+            if (this.extraIds[i] === id)
+                return i;
+        }
+        return -1;
+    }
+    moveExtra(touch) {
+        const slot = this.extraSlot(touch.id);
+        if (slot < 0)
+            return;
+        const dx = touch.x - touch.startX;
+        const dy = touch.y - touch.startY;
+        this.extraTravel[slot] = Math.max(this.extraTravel[slot] ?? 0, Math.hypot(dx, dy));
+        // A flick still reads as one from any finger. A drag does not become a
+        // look: the owning thumb has the camera, and a second one joining it would
+        // make every two-thumb frame a fight over the same axis.
+        if (this.extraSliding[slot] === 0 && this.classify(touch, dx, dy) === 'secondary') {
+            this.extraSliding[slot] = 1;
+            this.secondaryHeld = true;
+        }
+    }
+    endExtra(touch, durationMs) {
+        const slot = this.extraSlot(touch.id);
+        if (slot < 0)
+            return;
+        if (this.isTap(this.extraTravel[slot] ?? 0, durationMs))
+            this.primaryQueued = true;
+        this.extraIds[slot] = NO_TOUCH;
+        this.extraSliding[slot] = 0;
+        this.refreshSecondary();
+    }
+    /** The secondary is held while *any* touch in the zone is holding it. */
+    refreshSecondary() {
+        let held = this.ownerSliding;
+        for (let i = 0; i < EXTRA_SLOTS && !held; i++)
+            held = this.extraSliding[i] === 1;
+        this.secondaryHeld = held;
+    }
+    classify(touch, dx, dy) {
+        return classifyRightGesture(dx, dy, performance.now() - touch.startTime, {
+            gestureMovePx: this.gestureMovePx,
+            swipeMaxMs: this.swipeMaxMs,
+            swipeDominance: this.swipeDominance,
+        });
+    }
+    isTap(travelPx, durationMs) {
+        return isTapRelease(travelPx, durationMs, {
+            gestureMovePx: this.gestureMovePx,
+            tapMaxMs: this.tapMaxMs,
+        });
+    }
+    showStick(x, y) {
+        if (this.stickBase !== null) {
+            this.stickBase.style.left = `${x}px`;
+            this.stickBase.style.top = `${y}px`;
+            this.stickBase.hidden = false;
+        }
+        if (this.stickNub !== null)
+            this.stickNub.style.transform = 'translate3d(0, 0, 0)';
+    }
+    updateStick(touch) {
+        const dx = touch.x - touch.startX;
+        const dy = touch.y - touch.startY;
+        const length = Math.hypot(dx, dy);
+        const strength = Math.min(length / this.stickRadiusPx, 1);
+        if (strength < this.stickDeadzone || length < 1e-6) {
+            this.moveX = 0;
+            this.moveY = 0;
+        }
+        else {
+            this.moveX = (dx / length) * strength;
+            this.moveY = (-dy / length) * strength;
+        }
+        const clampedLength = Math.min(length, this.stickRadiusPx);
+        const nx = length > 1e-6 ? (dx / length) * clampedLength : 0;
+        const ny = length > 1e-6 ? (dy / length) * clampedLength : 0;
+        if (this.stickNub !== null) {
+            this.stickNub.style.transform = `translate3d(${nx}px, ${ny}px, 0)`;
+        }
+    }
+    validateOptions() {
+        if (this.splitRatio <= 0 || this.splitRatio >= 1) {
+            throw new Error(`TouchControls.splitRatio must be between 0 and 1, got ${this.splitRatio}`);
+        }
+        if (this.stickRadiusPx <= 0) {
+            throw new Error(`TouchControls.stickRadiusPx must be positive, got ${this.stickRadiusPx}`);
+        }
+        if (this.stickDeadzone < 0 || this.stickDeadzone >= 1) {
+            throw new Error(`TouchControls.stickDeadzone must be in [0, 1), got ${this.stickDeadzone}`);
+        }
+    }
+}

package/dist/input/typingTarget.d.ts

@@ -0,0 +1,6 @@
+/**
+ * `INPUT` covers buttons and checkboxes too, which do not take text — but a Space on a
+ * focused button is the browser's own "press it", so leaving those alone is right for
+ * the same reason.
+ */
+export declare function isTypingTarget(target: EventTarget | null): boolean;

package/dist/input/typingTarget.js

@@ -0,0 +1,27 @@
+/**
+ * Whether the keystroke belongs to a text field rather than to the game.
+ *
+ * An input layer that swallows keys while somebody is typing is a text field that
+ * silently drops characters. A consumer found this the hard way: it asks for
+ * `Space`, `KeyE` and the arrows to be `preventDefault`ed — reasonably, since Space
+ * scrolls the page and the arrows move it — and a player writing a bug report could
+ * not type a space, an `e`, or move the caret.
+ *
+ * Game-agnostic and deliberately conservative: it asks what the event is *for*, not
+ * what the game wants. A consumer that genuinely wants keys while a field has focus
+ * can read `keys` directly; nothing here stops that.
+ */
+const TYPING_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT']);
+/**
+ * `INPUT` covers buttons and checkboxes too, which do not take text — but a Space on a
+ * focused button is the browser's own "press it", so leaving those alone is right for
+ * the same reason.
+ */
+export function isTypingTarget(target) {
+    if (target === null)
+        return false;
+    const element = target;
+    if (typeof element.tagName === 'string' && TYPING_TAGS.has(element.tagName))
+        return true;
+    return element.isContentEditable === true;
+}

package/dist/math/bounds.d.ts

@@ -0,0 +1,61 @@
+/**
+ * How big a piece of geometry is, and where it sits.
+ *
+ * **Nothing in this engine knew either until now**, which is why there has never been a frustum
+ * test: a renderer cannot decide whether a mesh is on screen without knowing what part of space
+ * it occupies. `CAPABILITIES.md` recorded the consequence — no draw culling at all, only backface
+ * — and every track on the roadmap that wants culling, level of detail, a broadphase or a
+ * bounding gizmo wants this object first.
+ *
+ * Both a box and a sphere, because the two answer different questions cheaply. A sphere survives
+ * an arbitrary transform as a sphere, which makes it the right shape for a per-draw visibility
+ * test; a box is tighter and is what a physics broadphase and an editor's selection want.
+ */
+export interface Bounds {
+    /** The axis-aligned box, in the geometry's own space. */
+    readonly min: Float32Array;
+    readonly max: Float32Array;
+    /** The box's midpoint, which is what the radius is measured from. */
+    readonly centre: Float32Array;
+    /** The furthest vertex from `centre`. See `boundsOfPositions` for why not half the diagonal. */
+    radius: number;
+}
+export declare function createBounds(): Bounds;
+/**
+ * Measure a vertex array, into bounds the caller owns.
+ *
+ * **Two passes, and the second one is the point.** The first finds the box; the second finds the
+ * furthest vertex from the box's midpoint. Half the diagonal would be one pass and would be the
+ * box's circumradius — right for a box, and loose for anything rounded, which is most geometry.
+ * A sphere that reaches the corners of a box the geometry never visits answers every test too
+ * generously, and the cost is a second walk of an array that is already in cache.
+ *
+ * **Measured about the box's centre and never about the origin.** A mesh modelled a kilometre
+ * from the origin gets a kilometre-wide sphere the other way, and culls nothing for the rest of
+ * its life.
+ *
+ * Allocates nothing: `out` is the caller's and is returned for convenience.
+ */
+export declare function boundsOfPositions(positions: Float32Array, out: Bounds): Bounds;
+/**
+ * Bounds for a box the caller names itself, into bounds the caller owns.
+ *
+ * **`boundsOfPositions` was the only way to make one of these, and it demands a vertex array.**
+ * A consumer that wants to ask the renderer about a region rather than about a mesh — a streamed
+ * world testing its squares, a trigger volume, a room — has no vertices to hand it, so making the
+ * object meant filling `centre` and `radius` by hand and getting the sphere's invariant right. A
+ * consumer measured what that costs: with one mesh per material per square, a two-kilometre ring
+ * is 1,618 draws it walks one at a time, where the world itself knows 68 squares it could have
+ * tested instead.
+ *
+ * **Here the radius *is* half the diagonal**, which is the opposite of what `boundsOfPositions`
+ * does and is right for the same reason. That function measures the furthest actual vertex,
+ * because a mesh's corners are usually empty; a named box has no vertices and its corners are
+ * exactly the points it promises to contain, so anything tighter would report a region as off
+ * screen while part of it is on.
+ *
+ * Degenerate is allowed: a flat square gives a real box and a real radius, and a caller that
+ * passes a max below a min gets those values back rather than a silent swap — the box it asked
+ * for is the box it gets, and an inverted one is a bug at the call site.
+ */
+export declare function boundsOfBox(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, out: Bounds): Bounds;

package/dist/math/bounds.js

@@ -0,0 +1,121 @@
+export function createBounds() {
+    return {
+        min: new Float32Array(3),
+        max: new Float32Array(3),
+        centre: new Float32Array(3),
+        radius: 0,
+    };
+}
+/**
+ * Measure a vertex array, into bounds the caller owns.
+ *
+ * **Two passes, and the second one is the point.** The first finds the box; the second finds the
+ * furthest vertex from the box's midpoint. Half the diagonal would be one pass and would be the
+ * box's circumradius — right for a box, and loose for anything rounded, which is most geometry.
+ * A sphere that reaches the corners of a box the geometry never visits answers every test too
+ * generously, and the cost is a second walk of an array that is already in cache.
+ *
+ * **Measured about the box's centre and never about the origin.** A mesh modelled a kilometre
+ * from the origin gets a kilometre-wide sphere the other way, and culls nothing for the rest of
+ * its life.
+ *
+ * Allocates nothing: `out` is the caller's and is returned for convenience.
+ */
+export function boundsOfPositions(positions, out) {
+    /* Whole vertices only. A trailing partial one has no third component and cannot be placed;
+       reading it as a zero would drag the box to the origin. */
+    const vertices = Math.floor(positions.length / 3);
+    if (vertices === 0) {
+        out.min.fill(0);
+        out.max.fill(0);
+        out.centre.fill(0);
+        out.radius = 0;
+        return out;
+    }
+    let minX = Infinity;
+    let minY = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let maxZ = -Infinity;
+    for (let i = 0; i < vertices; i += 1) {
+        const x = positions[i * 3] ?? 0;
+        const y = positions[i * 3 + 1] ?? 0;
+        const z = positions[i * 3 + 2] ?? 0;
+        if (x < minX)
+            minX = x;
+        if (y < minY)
+            minY = y;
+        if (z < minZ)
+            minZ = z;
+        if (x > maxX)
+            maxX = x;
+        if (y > maxY)
+            maxY = y;
+        if (z > maxZ)
+            maxZ = z;
+    }
+    out.min[0] = minX;
+    out.min[1] = minY;
+    out.min[2] = minZ;
+    out.max[0] = maxX;
+    out.max[1] = maxY;
+    out.max[2] = maxZ;
+    const cx = (minX + maxX) * 0.5;
+    const cy = (minY + maxY) * 0.5;
+    const cz = (minZ + maxZ) * 0.5;
+    out.centre[0] = cx;
+    out.centre[1] = cy;
+    out.centre[2] = cz;
+    let furthest = 0;
+    for (let i = 0; i < vertices; i += 1) {
+        const dx = (positions[i * 3] ?? 0) - cx;
+        const dy = (positions[i * 3 + 1] ?? 0) - cy;
+        const dz = (positions[i * 3 + 2] ?? 0) - cz;
+        const squared = dx * dx + dy * dy + dz * dz;
+        if (squared > furthest)
+            furthest = squared;
+    }
+    out.radius = Math.sqrt(furthest);
+    return out;
+}
+/**
+ * Bounds for a box the caller names itself, into bounds the caller owns.
+ *
+ * **`boundsOfPositions` was the only way to make one of these, and it demands a vertex array.**
+ * A consumer that wants to ask the renderer about a region rather than about a mesh — a streamed
+ * world testing its squares, a trigger volume, a room — has no vertices to hand it, so making the
+ * object meant filling `centre` and `radius` by hand and getting the sphere's invariant right. A
+ * consumer measured what that costs: with one mesh per material per square, a two-kilometre ring
+ * is 1,618 draws it walks one at a time, where the world itself knows 68 squares it could have
+ * tested instead.
+ *
+ * **Here the radius *is* half the diagonal**, which is the opposite of what `boundsOfPositions`
+ * does and is right for the same reason. That function measures the furthest actual vertex,
+ * because a mesh's corners are usually empty; a named box has no vertices and its corners are
+ * exactly the points it promises to contain, so anything tighter would report a region as off
+ * screen while part of it is on.
+ *
+ * Degenerate is allowed: a flat square gives a real box and a real radius, and a caller that
+ * passes a max below a min gets those values back rather than a silent swap — the box it asked
+ * for is the box it gets, and an inverted one is a bug at the call site.
+ */
+export function boundsOfBox(minX, minY, minZ, maxX, maxY, maxZ, out) {
+    out.min[0] = minX;
+    out.min[1] = minY;
+    out.min[2] = minZ;
+    out.max[0] = maxX;
+    out.max[1] = maxY;
+    out.max[2] = maxZ;
+    const cx = (minX + maxX) * 0.5;
+    const cy = (minY + maxY) * 0.5;
+    const cz = (minZ + maxZ) * 0.5;
+    out.centre[0] = cx;
+    out.centre[1] = cy;
+    out.centre[2] = cz;
+    const dx = maxX - cx;
+    const dy = maxY - cy;
+    const dz = maxZ - cz;
+    out.radius = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    return out;
+}

package/dist/math/color.d.ts

@@ -0,0 +1,8 @@
+/** RGB triplet, each channel in [0, 1]. Mutable tuple for direct uniform upload. */
+export type Vec3 = [number, number, number];
+/** hue in degrees (any range), saturation/lightness in [0, 1]. */
+export declare function hslToRgb(hue: number, saturation: number, lightness: number): Vec3;
+export declare function mixColor(a: Vec3, b: Vec3, t: number): Vec3;
+/** In-place `mixColor` for per-frame use — allocating here would be a hot-path bug. */
+export declare function mixColorInto(out: Vec3, a: Vec3, b: Vec3, t: number): void;
+export declare function scaleColor(color: Vec3, factor: number): Vec3;

package/dist/math/color.js

@@ -0,0 +1,35 @@
+/** hue in degrees (any range), saturation/lightness in [0, 1]. */
+export function hslToRgb(hue, saturation, lightness) {
+    const h = ((hue % 360) + 360) % 360;
+    const c = (1 - Math.abs(2 * lightness - 1)) * saturation;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const m = lightness - c / 2;
+    let r = 0;
+    let g = 0;
+    let b = 0;
+    if (h < 60)
+        [r, g, b] = [c, x, 0];
+    else if (h < 120)
+        [r, g, b] = [x, c, 0];
+    else if (h < 180)
+        [r, g, b] = [0, c, x];
+    else if (h < 240)
+        [r, g, b] = [0, x, c];
+    else if (h < 300)
+        [r, g, b] = [x, 0, c];
+    else
+        [r, g, b] = [c, 0, x];
+    return [r + m, g + m, b + m];
+}
+export function mixColor(a, b, t) {
+    return [a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t, a[2] + (b[2] - a[2]) * t];
+}
+/** In-place `mixColor` for per-frame use — allocating here would be a hot-path bug. */
+export function mixColorInto(out, a, b, t) {
+    out[0] = a[0] + (b[0] - a[0]) * t;
+    out[1] = a[1] + (b[1] - a[1]) * t;
+    out[2] = a[2] + (b[2] - a[2]) * t;
+}
+export function scaleColor(color, factor) {
+    return [color[0] * factor, color[1] * factor, color[2] * factor];
+}

package/dist/math/exact.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Transcendentals that give the same bits on every JavaScript engine.
+ *
+ * **Not more accurate than `Math`, and that is not what they are for.** These are within a couple
+ * of units in the last place of correctly rounded, which is about what a platform `sin` gives you.
+ * What they are is *reproducible*: ECMAScript declines to specify `sin`, `cos`, `exp`, `acos` and
+ * eighteen more, so two engines may differ by an ulp, and an ulp is enough to make two peers running
+ * the same simulation disagree — first invisibly, then completely.
+ *
+ * `scripts/determinism.mjs` is the gate that refuses the unspecified ones inside the simulation set
+ * and names the twenty-two. Its header carries the other half of the argument: `+ - * /` are IEEE
+ * 754 operations by specification, JavaScript permits no fused-multiply-add contraction, and
+ * `Math.sqrt` is required correctly rounded and is *not* on that list. **So everything below uses
+ * only those five operations**, which is the whole design: reproducibility by construction rather
+ * than by hoping two engines chose the same algorithm.
+ *
+ * ---
+ *
+ * ## What is here, and what is deliberately not
+ *
+ * `exactSin`, `exactCos`, `exactExp`, `exactAcos`. Four, because four is what the engine and its
+ * first consumer actually reach for: the terrain binding's slope angle needs `acos`, a lockstep
+ * fixture rotating anything needs `sin` and `cos`, and exponential decay needs `exp`.
+ *
+ * **`atan2` is absent.** It is the obvious fifth and nothing here needs one: `shape.ts` sorts by a
+ * comparison key computed from two in-plane axes rather than by an angle, and `joints.ts` compares
+ * a quaternion component against a half-angle's sine. *Reversed by* a site that genuinely needs a
+ * signed angle from two components, at which point it arrives with its own golden vectors.
+ *
+ * ## Nothing in core imports these
+ *
+ * Deliberately. `core-only` is the one size figure in this repository that every consumer pays, and
+ * a module reachable from `createRenderer` is in it whether anybody calls it or not. These are
+ * reached by the script bindings and by consumers who ask for them, so tree-shaking keeps them out
+ * of a bundle that does not, which is measured rather than assumed.
+ *
+ * ## The coefficients
+ *
+ * The polynomial and rational coefficients are fdlibm's, which is the ancestor of most platform
+ * libms and is public domain. They are written as literals: **a literal is the same number on
+ * every engine, which is the only property being bought.** Their provenance matters less than their
+ * fixity — a coefficient somebody re-derived to one more digit is a different function, and
+ * `exact.test.ts`'s golden bit patterns are what would catch that.
+ */
+/** `Math.sin`, reproducibly. NaN in, NaN out; an infinity answers NaN, as `Math.sin` does. */
+export declare function exactSin(x: number): number;
+/** `Math.cos`, reproducibly. */
+export declare function exactCos(x: number): number;
+/**
+ * `Math.exp`, reproducibly.
+ *
+ * Reduce by a multiple of ln 2 into [-ln2/2, ln2/2], sum the Taylor series there, and scale by a
+ * power of two. **A degree-14 series and not a shorter minimax**, because on that interval the
+ * fifteenth term is about 4e-20 — below the precision of a double — so the series is exact to the
+ * representation and there is nothing a fitted polynomial would buy.
+ */
+export declare function exactExp(x: number): number;
+/**
+ * `Math.acos`, reproducibly. Outside [-1, 1] this answers NaN, as `Math.acos` does.
+ *
+ * Three branches rather than one, and the split at ±0.5 is the reason it is accurate near the ends:
+ * `acos` has infinite derivative at ±1, so a polynomial in `x` loses its footing there. Substituting
+ * `s = sqrt((1 ∓ x)/2)` moves the awkward point to zero, where a polynomial is comfortable — which
+ * is also why `sqrt` being exactly rounded matters here rather than being a convenience.
+ */
+export declare function exactAcos(x: number): number;