ugly-game 0.1.0

package/dist/input/TouchControls.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from 'react';
+const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
+function Stick({ cfg, backendRef }) {
+    const ref = React.useRef(null);
+    const [knob, setKnob] = React.useState({ x: 0, y: 0 });
+    const active = React.useRef(false);
+    const R = 52;
+    const move = (e) => {
+        if (!active.current)
+            return;
+        const el = ref.current;
+        if (!el)
+            return;
+        const r = el.getBoundingClientRect();
+        const dx = e.clientX - (r.left + r.width / 2), dy = e.clientY - (r.top + r.height / 2);
+        const nx = clamp(dx / R, -1, 1), ny = clamp(dy / R, -1, 1);
+        backendRef.current?.setTouchAxis(cfg.id, nx, ny);
+        setKnob({ x: nx * R, y: ny * R });
+    };
+    const end = (e) => { active.current = false; backendRef.current?.setTouchAxis(cfg.id, 0, 0); setKnob({ x: 0, y: 0 }); e.currentTarget.releasePointerCapture(e.pointerId); };
+    const sideStyle = cfg.side === 'left' ? { left: 22 } : { right: 22 };
+    return (_jsxs("div", { ref: ref, onPointerDown: (e) => { active.current = true; e.currentTarget.setPointerCapture(e.pointerId); move(e); }, onPointerMove: move, onPointerUp: end, onPointerCancel: end, style: { position: 'absolute', bottom: 22, ...sideStyle, width: R * 2, height: R * 2, borderRadius: '50%', background: 'rgba(120,150,190,.12)', border: '1px solid rgba(150,180,220,.4)', touchAction: 'none', userSelect: 'none' }, children: [_jsx("div", { style: { position: 'absolute', left: '50%', top: '50%', width: 46, height: 46, marginLeft: -23, marginTop: -23, transform: `translate(${knob.x}px,${knob.y}px)`, borderRadius: '50%', background: 'rgba(180,205,235,.5)' } }), cfg.label && _jsx("div", { style: { position: 'absolute', bottom: -18, width: '100%', textAlign: 'center', fontSize: 10, color: '#8fa2b5' }, children: cfg.label })] }));
+}
+function Btn({ cfg, backendRef, offset }) {
+    const [down, setDown] = React.useState(false);
+    const set = (v) => (e) => { setDown(v); backendRef.current?.setTouchButton(cfg.id, v); if (v)
+        e.currentTarget.setPointerCapture(e.pointerId); };
+    return (_jsx("div", { onPointerDown: set(true), onPointerUp: set(false), onPointerCancel: set(false), style: { position: 'absolute', bottom: 30 + offset * 62, right: 150, width: 56, height: 56, borderRadius: '50%', display: 'flex', alignItems: 'center', justifyContent: 'center', fontSize: 11, fontWeight: 700, color: down ? '#04160c' : '#dbe5ef', background: down ? 'rgba(120,220,160,.85)' : 'rgba(120,150,190,.16)', border: '1px solid rgba(150,180,220,.4)', touchAction: 'none', userSelect: 'none' }, children: cfg.label }));
+}
+export function TouchControls({ backendRef, sticks = [], buttons = [] }) {
+    return (_jsx("div", { style: { position: 'absolute', inset: 0, pointerEvents: 'none' }, children: _jsxs("div", { style: { position: 'absolute', inset: 0, pointerEvents: 'auto' }, children: [sticks.map((s) => _jsx(Stick, { cfg: s, backendRef: backendRef }, s.id)), buttons.map((b, i) => _jsx(Btn, { cfg: b, backendRef: backendRef, offset: i }, b.id))] }) }));
+}

package/dist/input/browserBackend.d.ts

@@ -0,0 +1,40 @@
+import { type RawInputFrame } from './resolve';
+export interface BrowserBackendOpts {
+    target: HTMLElement;
+    pointerLock?: boolean;
+}
+export declare class BrowserRawBackend {
+    private keysDown;
+    private edges;
+    private pdx;
+    private pdy;
+    private pwheel;
+    private ppx;
+    private ppy;
+    private pdragx;
+    private pdragy;
+    private ppinch;
+    private ptwist;
+    private pointerButtons;
+    private touches;
+    private gPrev;
+    private touchAxes;
+    private touchButtons;
+    private prevPadButtons;
+    private disposers;
+    private target;
+    private pointerLock;
+    private paused;
+    constructor(opts: BrowserBackendOpts);
+    setPaused(p: boolean): void;
+    private on;
+    private cursor;
+    private gesture;
+    private attach;
+    setTouchAxis(id: string, x: number, y: number): void;
+    clearTouchAxis(id: string): void;
+    setTouchButton(id: string, down: boolean): void;
+    private pollGamepads;
+    beginFrame(): RawInputFrame;
+    dispose(): void;
+}

package/dist/input/browserBackend.js

@@ -0,0 +1,205 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// BrowserRawBackend — the web-fallback of the `input.*` channel (design §9.1, §11).
+// Samples keyboard + pointer (pointer-lock deltas, absolute cursor, drag/pan) + wheel +
+// MULTI-TOUCH GESTURES (two-finger pan / pinch-zoom / twist-rotate) + Gamepad API +
+// on-screen touch widgets into one RawInputFrame per render frame. CLIENT-ONLY (touches
+// DOM/Gamepad) — deliberately OUTSIDE the determinism-linted shared/ set; its sole output
+// is the plain RawInputFrame the pure resolver consumes.
+//
+// Hybrid sampling: event-driven ACCUMULATORS for sub-frame sources (keydown/up, pointer
+// motion, wheel, gestures, edges), POLLED gamepads (read late in beginFrame()).
+//   • mouse: left/right/middle buttons; middle-drag pans; wheel zooms; click = edge.
+//   • touch: one finger = cursor (tap = place edge); two fingers = pan + pinch-zoom + twist.
+// ─────────────────────────────────────────────────────────────────────────────
+import { emptyFrame } from './resolve';
+export class BrowserRawBackend {
+    keysDown = new Set();
+    edges = new Set();
+    pdx = 0;
+    pdy = 0;
+    pwheel = 0; // lock look delta + wheel
+    ppx = 0.5;
+    ppy = 0.5; // absolute cursor 0..1
+    pdragx = 0;
+    pdragy = 0;
+    ppinch = 0;
+    ptwist = 0; // pan / pinch / twist
+    pointerButtons = new Set();
+    touches = new Map();
+    gPrev = null;
+    touchAxes = {};
+    touchButtons = new Set();
+    prevPadButtons = [];
+    disposers = [];
+    target;
+    pointerLock;
+    paused = false; // while a menu is open: suspend gameplay input + don't grab pointer lock
+    constructor(opts) { this.target = opts.target; this.pointerLock = opts.pointerLock ?? false; this.attach(); }
+    setPaused(p) { this.paused = p; }
+    on(el, type, fn, o) {
+        const handler = fn;
+        el.addEventListener(type, handler, o);
+        this.disposers.push(() => { el.removeEventListener(type, handler, o); });
+    }
+    cursor(clientX, clientY) {
+        const r = this.target.getBoundingClientRect();
+        this.ppx = Math.max(0, Math.min(1, (clientX - r.left) / Math.max(1, r.width)));
+        this.ppy = Math.max(0, Math.min(1, (clientY - r.top) / Math.max(1, r.height)));
+    }
+    gesture() {
+        const [a, b] = [...this.touches.values()];
+        return { cx: (a.x + b.x) / 2, cy: (a.y + b.y) / 2, dist: Math.hypot(b.x - a.x, b.y - a.y), ang: Math.atan2(b.y - a.y, b.x - a.x) };
+    }
+    attach() {
+        this.on(window, 'keydown', (e) => { if (!this.keysDown.has(e.code))
+            this.edges.add('key:' + e.code); this.keysDown.add(e.code); });
+        this.on(window, 'keyup', (e) => { this.keysDown.delete(e.code); });
+        this.on(window, 'blur', () => { this.keysDown.clear(); this.touches.clear(); this.pointerButtons.clear(); });
+        this.on(this.target, 'wheel', (e) => { this.pwheel += e.deltaY; e.preventDefault(); }, { passive: false });
+        this.on(this.target, 'contextmenu', (e) => { e.preventDefault(); });
+        this.on(this.target, 'pointerdown', (e) => {
+            if (this.paused)
+                return; // menu open → let clicks reach the UI, don't grab pointer lock
+            this.cursor(e.clientX, e.clientY);
+            const el = this.target;
+            if (e.pointerType === 'touch') {
+                this.touches.set(e.pointerId, { x: e.clientX, y: e.clientY, moved: 0 });
+                this.gPrev = this.touches.size === 2 ? this.gesture() : null;
+                if (!document.pointerLockElement)
+                    el.setPointerCapture(e.pointerId); // track gestures that leave the canvas
+            }
+            else {
+                if (!this.pointerButtons.has(e.button))
+                    this.edges.add(`ptr:${e.button}`); // mouse: immediate click edge
+                this.pointerButtons.add(e.button);
+                // Pointer LOCK and pointer CAPTURE are mutually-exclusive ways to route pointer input. Calling capture
+                // while lock is engaged/pending throws InvalidStateError (Firefox then never locks → no mouselook;
+                // Chrome logs it on every click while locked). So when the game wants mouselook use ONLY pointer lock;
+                // otherwise capture so a drag keeps tracking off-canvas. `document.pointerLockElement` is the guard that
+                // makes capture valid by construction — no try/catch needed.
+                if (this.pointerLock) {
+                    if (!document.pointerLockElement)
+                        void Promise.resolve(el.requestPointerLock()).catch(() => { });
+                }
+                else if (!document.pointerLockElement) {
+                    el.setPointerCapture(e.pointerId);
+                }
+            }
+        });
+        this.on(window, 'pointermove', (e) => {
+            if (document.pointerLockElement) {
+                this.pdx += e.movementX;
+                this.pdy += e.movementY;
+            } // mouselook whenever locked (any mode)
+            if (e.pointerType === 'touch') {
+                const t = this.touches.get(e.pointerId);
+                if (!t)
+                    return;
+                t.moved += Math.abs(e.movementX) + Math.abs(e.movementY);
+                t.x = e.clientX;
+                t.y = e.clientY;
+                if (this.touches.size === 2) {
+                    const g = this.gesture();
+                    this.cursor(g.cx, g.cy);
+                    if (this.gPrev) {
+                        const r = this.target.getBoundingClientRect();
+                        this.pdragx += g.cx - this.gPrev.cx;
+                        this.pdragy += g.cy - this.gPrev.cy;
+                        this.ppinch += (g.dist - this.gPrev.dist) / Math.max(1, r.height);
+                        let d = g.ang - this.gPrev.ang;
+                        if (d > Math.PI)
+                            d -= 2 * Math.PI;
+                        if (d < -Math.PI)
+                            d += 2 * Math.PI;
+                        this.ptwist += d;
+                    }
+                    this.gPrev = g;
+                }
+                else {
+                    this.cursor(e.clientX, e.clientY);
+                } // one finger = cursor only
+            }
+            else {
+                this.cursor(e.clientX, e.clientY);
+                if (this.pointerButtons.has(1)) {
+                    this.pdragx += e.movementX;
+                    this.pdragy += e.movementY;
+                } // middle-drag pans
+            }
+        });
+        this.on(window, 'pointerup', (e) => {
+            if (e.pointerType === 'touch') {
+                const t = this.touches.get(e.pointerId);
+                if (t && this.touches.size === 1 && t.moved < 10)
+                    this.edges.add('ptr:0'); // single-finger tap = place
+                this.touches.delete(e.pointerId);
+                this.gPrev = this.touches.size === 2 ? this.gesture() : null;
+            }
+            else
+                this.pointerButtons.delete(e.button);
+        });
+    }
+    setTouchAxis(id, x, y) { this.touchAxes[id] = { x, y }; }
+    clearTouchAxis(id) { this.touchAxes[id] = { x: 0, y: 0 }; }
+    setTouchButton(id, down) {
+        if (down) {
+            if (!this.touchButtons.has(id))
+                this.edges.add('touch:' + id);
+            this.touchButtons.add(id);
+        }
+        else
+            this.touchButtons.delete(id);
+    }
+    pollGamepads() {
+        const pads = [];
+        const edges = [];
+        const src = navigator.getGamepads();
+        for (let i = 0; i < src.length; i++) {
+            const gp = src[i];
+            if (!gp)
+                continue;
+            pads[i] = { axes: gp.axes.slice(), buttons: gp.buttons.map((b) => b.value) };
+            const prev = this.prevPadButtons[i] ?? [];
+            for (let b = 0; b < gp.buttons.length; b++)
+                if (gp.buttons[b].pressed && !prev[b])
+                    edges.push(`gp${i}:b${b}`);
+            this.prevPadButtons[i] = gp.buttons.map((b) => b.pressed);
+        }
+        return { pads, edges };
+    }
+    beginFrame() {
+        if (this.paused) {
+            this.edges.clear();
+            this.pdx = 0;
+            this.pdy = 0;
+            this.pwheel = 0;
+            this.pdragx = 0;
+            this.pdragy = 0;
+            this.ppinch = 0;
+            this.ptwist = 0;
+            return emptyFrame();
+        }
+        const { pads, edges: padEdges } = this.pollGamepads();
+        const frame = emptyFrame();
+        frame.keysDown = new Set(this.keysDown);
+        frame.pressedEdges = new Set(this.edges);
+        for (const e of padEdges)
+            frame.pressedEdges.add(e);
+        frame.pointer = { dx: this.pdx, dy: this.pdy, wheel: this.pwheel, px: this.ppx, py: this.ppy, dragx: this.pdragx, dragy: this.pdragy, pinch: this.ppinch, twist: this.ptwist };
+        frame.pointerButtons = new Set(this.pointerButtons);
+        frame.touchAxes = { ...this.touchAxes };
+        frame.touchButtons = new Set(this.touchButtons);
+        frame.gamepads = pads;
+        this.edges.clear();
+        this.pdx = 0;
+        this.pdy = 0;
+        this.pwheel = 0;
+        this.pdragx = 0;
+        this.pdragy = 0;
+        this.ppinch = 0;
+        this.ptwist = 0;
+        return frame;
+    }
+    dispose() { for (const d of this.disposers)
+        d(); this.disposers = []; }
+}

package/dist/input/resolve.d.ts

@@ -0,0 +1,98 @@
+export interface RawGamepad {
+    axes: number[];
+    buttons: number[];
+}
+export interface RawInputFrame {
+    keysDown: Set<string>;
+    pressedEdges: Set<string>;
+    pointer: {
+        dx: number;
+        dy: number;
+        wheel: number;
+        px: number;
+        py: number;
+        dragx: number;
+        dragy: number;
+        pinch: number;
+        twist: number;
+    };
+    pointerButtons: Set<number>;
+    touchAxes: Record<string, {
+        x: number;
+        y: number;
+    }>;
+    touchButtons: Set<string>;
+    gamepads: RawGamepad[];
+}
+export declare function emptyFrame(): RawInputFrame;
+export type RawControlRef = {
+    dev: 'key';
+    code: string;
+} | {
+    dev: 'gpAxis';
+    pad?: number;
+    axis: number;
+} | {
+    dev: 'gpButton';
+    pad?: number;
+    button: number;
+} | {
+    dev: 'pointer';
+    axis: 'dx' | 'dy' | 'wheel' | 'px' | 'py' | 'dragx' | 'dragy' | 'pinch' | 'twist';
+} | {
+    dev: 'pointerButton';
+    button: number;
+} | {
+    dev: 'touchAxis';
+    id: string;
+    comp: 'x' | 'y';
+} | {
+    dev: 'touchButton';
+    id: string;
+};
+export interface Binding {
+    field: string;
+    src: RawControlRef;
+    sign?: 1 | -1;
+    scale?: number;
+    deadzone?: number;
+}
+export type Carry = 'level' | 'edge' | 'accumulate';
+export interface FieldSpec {
+    carry: Carry;
+    range?: [number, number];
+}
+export interface InputMode<I> {
+    id: string;
+    base: I;
+    fields: Record<string, FieldSpec>;
+    bindings: Binding[];
+}
+export declare class InputDriver<I extends object> {
+    private mode;
+    private byField;
+    private level;
+    private pendEdge;
+    private pendAcc;
+    constructor(mode: InputMode<I>);
+    beginFrame(raw: RawInputFrame): void;
+    inputForSubstep(sub: number): I;
+    endFrame(consumedSubsteps: number): void;
+}
+export declare function edgeControlId(ref: RawControlRef): string;
+export declare function extendMode<I>(base: InputMode<I>, ext: {
+    fields?: Record<string, FieldSpec>;
+    bindings?: Binding[];
+}): InputMode<I>;
+export type Device = 'desktop' | 'gamepad' | 'touch';
+export interface ControlDesc {
+    field: string;
+    carry: Carry;
+    range?: [number, number] | undefined;
+    label: string;
+    bindings: RawControlRef[];
+}
+/** Machine-readable control descriptor for a mode: each semantic field, how it's driven on every device, its
+ *  carry/range, and a human label. Feeds both the on-screen ControlHints and window.__game.controls (so the
+ *  IR/AI harness knows every action the game exposes and how to drive it). */
+export declare function describeControls(mode: InputMode<unknown>, labels?: Record<string, string>, order?: string[]): ControlDesc[];

package/dist/input/resolve.js

@@ -0,0 +1,141 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// ugly-game control system — the device-agnostic resolver (Tier 2/3).
+//
+// Turns a per-frame RawInputFrame (every device this frame) into the game's
+// serializable per-tick `Input` via a declared InputMode (bindings + carry policy).
+// PURE and determinism-safe: uses only abs/min/max (never sin/cos/random/Date), so
+// it may live in shared/. Its ONLY output is the plain `Input` the sim/IR record
+// verbatim — the determinism firewall (see design/input-system.md §2). Device I/O
+// (DOM/Gamepad sampling) lives in client/input/browserBackend.ts, NOT here.
+//
+// The recorded artifact is the RESOLVED semantic value, never raw events — so a
+// replay is device-agnostic: `mv` produced from a W key and from a gamepad stick
+// record and replay identically. That is what makes clean capture + re-test work.
+// ─────────────────────────────────────────────────────────────────────────────
+export function emptyFrame() {
+    return { keysDown: new Set(), pressedEdges: new Set(), pointer: { dx: 0, dy: 0, wheel: 0, px: 0.5, py: 0.5, dragx: 0, dragy: 0, pinch: 0, twist: 0 }, pointerButtons: new Set(), touchAxes: {}, touchButtons: new Set(), gamepads: [] };
+}
+// ── Raw reads ────────────────────────────────────────────────────────────────
+function controlId(ref) {
+    switch (ref.dev) {
+        case 'key': return 'key:' + ref.code;
+        case 'gpButton': return `gp${ref.pad ?? 0}:b${ref.button}`;
+        case 'pointerButton': return `ptr:${ref.button}`;
+        case 'touchButton': return 'touch:' + ref.id;
+        default: return ''; // axes/pointer-motion have no edge id
+    }
+}
+function readLevel(raw, ref) {
+    switch (ref.dev) {
+        case 'key': return raw.keysDown.has(ref.code) ? 1 : 0;
+        case 'gpAxis': return raw.gamepads[ref.pad ?? 0]?.axes[ref.axis] ?? 0;
+        case 'gpButton': return raw.gamepads[ref.pad ?? 0]?.buttons[ref.button] ?? 0;
+        case 'pointer': return raw.pointer[ref.axis];
+        case 'pointerButton': return raw.pointerButtons.has(ref.button) ? 1 : 0;
+        case 'touchAxis': return raw.touchAxes[ref.id]?.[ref.comp] ?? 0;
+        case 'touchButton': return raw.touchButtons.has(ref.id) ? 1 : 0;
+    }
+}
+function proc(v, b) {
+    if (b.deadzone && Math.abs(v) < b.deadzone)
+        v = 0;
+    return v * (b.scale ?? 1) * (b.sign ?? 1);
+}
+function clamp(v, r) {
+    if (!r)
+        return v;
+    return v < r[0] ? r[0] : v > r[1] ? r[1] : v;
+}
+function bindingsByField(bindings) {
+    const m = new Map();
+    for (const b of bindings) {
+        const list = m.get(b.field) ?? [];
+        list.push(b);
+        m.set(b.field, list);
+    }
+    return m;
+}
+// ── The driver: RawInputFrame → per-tick Input, carry-policy correct ─────────
+//
+// beginFrame(raw) once per RENDER frame; inputForSubstep(sub) per FIXED sub-step
+// (sub 0 carries edges + accumulated deltas, sub>0 gets level-only); endFrame(n)
+// clears consumed edges/deltas. Edges/deltas PERSIST across a 0-sub-step frame
+// (a fast click/flick between ticks is never dropped) and never double-apply
+// across ≥2 sub-steps — the two rules PlayPage hand-rolls (design §9.3).
+export class InputDriver {
+    mode;
+    byField;
+    level = {};
+    pendEdge = {};
+    pendAcc = {};
+    constructor(mode) {
+        this.mode = mode;
+        this.byField = bindingsByField(mode.bindings);
+    }
+    beginFrame(raw) {
+        this.level = {};
+        for (const field in this.mode.fields) {
+            const spec = this.mode.fields[field];
+            const binds = this.byField.get(field) ?? [];
+            if (spec.carry === 'level') {
+                let v = 0;
+                for (const b of binds)
+                    v += proc(readLevel(raw, b.src), b);
+                this.level[field] = clamp(v, spec.range);
+            }
+            else if (spec.carry === 'edge') {
+                for (const b of binds)
+                    if (raw.pressedEdges.has(controlId(b.src)))
+                        this.pendEdge[field] = 1;
+            }
+            else { // accumulate
+                let v = 0;
+                for (const b of binds)
+                    v += proc(readLevel(raw, b.src), b);
+                if (v !== 0)
+                    this.pendAcc[field] = (this.pendAcc[field] ?? 0) + v;
+            }
+        }
+    }
+    inputForSubstep(sub) {
+        const inp = { ...this.mode.base };
+        for (const field in this.mode.fields) {
+            const spec = this.mode.fields[field];
+            let val;
+            if (spec.carry === 'level')
+                val = this.level[field] ?? 0;
+            else if (spec.carry === 'edge')
+                val = sub === 0 ? (this.pendEdge[field] ? 1 : 0) : 0;
+            else
+                val = sub === 0 ? (this.pendAcc[field] ?? 0) : 0;
+            inp[field] = val;
+        }
+        return inp;
+    }
+    endFrame(consumedSubsteps) {
+        if (consumedSubsteps > 0) {
+            this.pendEdge = {};
+            this.pendAcc = {};
+        }
+    }
+}
+// Canonical control ids a backend must emit into `pressedEdges` for edge fields.
+export function edgeControlId(ref) { return controlId(ref); }
+// ── Control registry (controls are DERIVED from bindings) ────────────────────
+// A game "registers" custom actions by extending a base mode with extra fields + bindings. The on-screen
+// control hints AND the IR/AI descriptor both read the resulting bindings, so a new binding (e.g. G → flip)
+// shows up in the UI on every device AND tells the harness a new semantic field exists — one source of
+// truth, no hand-maintained control lists.
+export function extendMode(base, ext) {
+    return { ...base, fields: { ...base.fields, ...(ext.fields ?? {}) }, bindings: [...base.bindings, ...(ext.bindings ?? [])] };
+}
+/** Machine-readable control descriptor for a mode: each semantic field, how it's driven on every device, its
+ *  carry/range, and a human label. Feeds both the on-screen ControlHints and window.__game.controls (so the
+ *  IR/AI harness knows every action the game exposes and how to drive it). */
+export function describeControls(mode, labels = {}, order) {
+    const fields = order ?? Object.keys(mode.fields);
+    return fields.filter((f) => mode.fields[f]).map((f) => ({
+        field: f, carry: mode.fields[f].carry, range: mode.fields[f].range, label: labels[f] ?? f,
+        bindings: mode.bindings.filter((b) => b.field === f).map((b) => b.src),
+    }));
+}

package/dist/mat4.d.ts

@@ -0,0 +1,17 @@
+export type Mat4 = Float64Array;
+export type Vec3 = readonly [number, number, number];
+export declare function perspective(fovY: number, aspect: number, near: number, far: number): Mat4;
+export declare function lookAt(eye: Vec3, target: Vec3, up: Vec3): Mat4;
+export declare function mul(a: Mat4, b: Mat4): Mat4;
+/** camera view-projection = perspective · lookAt (world → clip). */
+export declare function viewProjection(eye: Vec3, target: Vec3, fovY: number, aspect: number, near?: number, far?: number): Mat4;
+/** Orthographic projection, WebGPU clip z ∈ [0,1] (for shadow-map light views). */
+export declare function ortho(l: number, r: number, b: number, t: number, n: number, f: number): Mat4;
+/** A directional light's view-projection: an ortho box `extent` wide, `depth` deep,
+ *  looking along `dir` at the scene `center`. World → light clip (for shadow mapping). */
+export declare function lightViewProjection(dir: Vec3, center: Vec3, extent: number, depth: number): Mat4;
+export type Plane = readonly [number, number, number, number];
+/** Extract + normalize the 6 frustum planes from a column-major view-proj (Gribb-Hartmann). */
+export declare function frustumPlanes(m: Mat4): Plane[];
+/** Sphere vs frustum: false only if the sphere is fully outside any plane. */
+export declare function sphereVisible(planes: Plane[], x: number, y: number, z: number, radius: number): boolean;

package/dist/mat4.js

@@ -0,0 +1,99 @@
+// Minimal column-major mat4 + frustum extraction for the render IR's culling. Uses
+// dmath (deterministic) for trig so the CPU cull reference is bit-stable and can be a
+// test oracle for the GPU compute-cull backend. Only what the render IR needs.
+import { dtan } from './dmath';
+export function perspective(fovY, aspect, near, far) {
+    const f = 1 / dtan(fovY / 2), nf = 1 / (near - far);
+    const m = new Float64Array(16);
+    m[0] = f / aspect;
+    m[5] = f;
+    m[10] = (far + near) * nf;
+    m[11] = -1;
+    m[14] = 2 * far * near * nf;
+    return m;
+}
+export function lookAt(eye, target, up) {
+    let zx = eye[0] - target[0], zy = eye[1] - target[1], zz = eye[2] - target[2];
+    let l = Math.sqrt(zx * zx + zy * zy + zz * zz) || 1;
+    zx /= l;
+    zy /= l;
+    zz /= l;
+    let xx = up[1] * zz - up[2] * zy, xy = up[2] * zx - up[0] * zz, xz = up[0] * zy - up[1] * zx;
+    l = Math.sqrt(xx * xx + xy * xy + xz * xz) || 1;
+    xx /= l;
+    xy /= l;
+    xz /= l;
+    const yx = zy * xz - zz * xy, yy = zz * xx - zx * xz, yz = zx * xy - zy * xx;
+    const m = new Float64Array(16);
+    m[0] = xx;
+    m[1] = yx;
+    m[2] = zx;
+    m[4] = xy;
+    m[5] = yy;
+    m[6] = zy;
+    m[8] = xz;
+    m[9] = yz;
+    m[10] = zz;
+    m[12] = -(xx * eye[0] + xy * eye[1] + xz * eye[2]);
+    m[13] = -(yx * eye[0] + yy * eye[1] + yz * eye[2]);
+    m[14] = -(zx * eye[0] + zy * eye[1] + zz * eye[2]);
+    m[15] = 1;
+    return m;
+}
+export function mul(a, b) {
+    const o = new Float64Array(16);
+    for (let c = 0; c < 4; c++)
+        for (let r = 0; r < 4; r++) {
+            let s = 0;
+            for (let k = 0; k < 4; k++)
+                s += a[k * 4 + r] * b[c * 4 + k];
+            o[c * 4 + r] = s;
+        }
+    return o;
+}
+/** camera view-projection = perspective · lookAt (world → clip). */
+export function viewProjection(eye, target, fovY, aspect, near = 0.1, far = 1000) {
+    return mul(perspective(fovY, aspect, near, far), lookAt(eye, target, [0, 1, 0]));
+}
+/** Orthographic projection, WebGPU clip z ∈ [0,1] (for shadow-map light views). */
+export function ortho(l, r, b, t, n, f) {
+    const m = new Float64Array(16);
+    m[0] = 2 / (r - l);
+    m[12] = -(r + l) / (r - l);
+    m[5] = 2 / (t - b);
+    m[13] = -(t + b) / (t - b);
+    m[10] = 1 / (n - f);
+    m[14] = n / (n - f);
+    m[15] = 1;
+    return m;
+}
+/** A directional light's view-projection: an ortho box `extent` wide, `depth` deep,
+ *  looking along `dir` at the scene `center`. World → light clip (for shadow mapping). */
+export function lightViewProjection(dir, center, extent, depth) {
+    let dx = dir[0], dy = dir[1], dz = dir[2];
+    const l = Math.sqrt(dx * dx + dy * dy + dz * dz) || 1;
+    dx /= l;
+    dy /= l;
+    dz /= l;
+    const eye = [center[0] - dx * depth * 0.5, center[1] - dy * depth * 0.5, center[2] - dz * depth * 0.5];
+    const up = Math.abs(dy) > 0.99 ? [0, 0, 1] : [0, 1, 0];
+    return mul(ortho(-extent, extent, -extent, extent, 0.1, depth), lookAt(eye, center, up));
+}
+/** Extract + normalize the 6 frustum planes from a column-major view-proj (Gribb-Hartmann). */
+export function frustumPlanes(m) {
+    const row = (r) => [m[r], m[4 + r], m[8 + r], m[12 + r]];
+    const r0 = row(0), r1 = row(1), r2 = row(2), r3 = row(3);
+    const combine = (a, b, sign) => {
+        const p = [a[0] + sign * b[0], a[1] + sign * b[1], a[2] + sign * b[2], a[3] + sign * b[3]];
+        const l = Math.sqrt(p[0] * p[0] + p[1] * p[1] + p[2] * p[2]) || 1;
+        return [p[0] / l, p[1] / l, p[2] / l, p[3] / l];
+    };
+    return [combine(r3, r0, 1), combine(r3, r0, -1), combine(r3, r1, 1), combine(r3, r1, -1), combine(r3, r2, 1), combine(r3, r2, -1)];
+}
+/** Sphere vs frustum: false only if the sphere is fully outside any plane. */
+export function sphereVisible(planes, x, y, z, radius) {
+    for (const p of planes)
+        if (p[0] * x + p[1] * y + p[2] * z + p[3] < -radius)
+            return false;
+    return true;
+}