ugly-game 0.1.0 → 0.3.0

package/dist/capture.d.ts

@@ -0,0 +1,27 @@
+export interface CaptureRow {
+    [k: string]: number | string;
+}
+export interface CaptureFrame {
+    tick: number;
+    rows: CaptureRow[];
+}
+export interface CaptureResult {
+    label: string;
+    level: string;
+    from: number;
+    to: number;
+    ticks: number;
+    rows: number;
+    frames: CaptureFrame[];
+}
+/** Emit detail rows for `state` at `tick`, honoring the probe's own level + filter. Return [] to skip. */
+export type Probe<S> = (state: S, tick: number) => CaptureRow[];
+/** Replay a deterministic sim from `init` and capture probe output over the window [from,to). Warms up to
+ *  `from` without probing (cheap), then probes each tick. `step(s, tick)` advances one deterministic tick
+ *  (it may pull `inputs[tick]` from a closure). `clone` protects the caller's state. */
+export declare function captureWindow<S>(init: S, clone: (s: S) => S, step: (s: S, tick: number) => void, from: number, to: number, probe: Probe<S>, opts?: {
+    label?: string;
+    level?: string;
+}): CaptureResult;
+/** Flatten a capture to one row per (tick, entity) — handy for a table / CSV / assertion. */
+export declare function captureRows(r: CaptureResult): CaptureRow[];

package/dist/capture.js

@@ -0,0 +1,35 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// LEVELED, FILTERABLE CAPTURE via REPLAY — the debugging counterpart to the moat. Because a sim is a
+// DETERMINISTIC function of (init, inputs), you record only the cheap stuff LIVE (the input stream + a
+// coarse per-tick hash) and reconstruct ANY level of detail ON DEMAND by replaying a bounded WINDOW and
+// running a PROBE at the chosen level-of-detail + filter. So live capture never overloads the system,
+// yet you can later ask "replay 1 second of belt movement, give me the coords of every belt item" and
+// get frame-exact fine detail — for exactly the ticks / entities / fields you filter to.
+//
+// The three knobs:
+//   • WINDOW  [from,to) — fast-forward to `from` (not captured), probe each tick to `to`. Bounds cost.
+//   • LEVEL   — how much detail the probe emits (coarse counters → per-entity → per-item). Game-defined.
+//   • FILTER  — which entities/region/fields the probe emits. Game-defined, applied inside the probe.
+// The engine owns the replay-window machinery; the game supplies a level+filter-aware probe.
+// ─────────────────────────────────────────────────────────────────────────────
+/** Replay a deterministic sim from `init` and capture probe output over the window [from,to). Warms up to
+ *  `from` without probing (cheap), then probes each tick. `step(s, tick)` advances one deterministic tick
+ *  (it may pull `inputs[tick]` from a closure). `clone` protects the caller's state. */
+export function captureWindow(init, clone, step, from, to, probe, opts) {
+    const s = clone(init);
+    for (let t = 0; t < from; t++)
+        step(s, t); // fast-forward to the window — not captured
+    const frames = [];
+    let rows = 0;
+    for (let t = from; t < to; t++) {
+        step(s, t);
+        const r = probe(s, t);
+        if (r.length) {
+            frames.push({ tick: t, rows: r });
+            rows += r.length;
+        }
+    }
+    return { label: opts?.label ?? 'capture', level: opts?.level ?? 'custom', from, to, ticks: Math.max(0, to - from), rows, frames };
+}
+/** Flatten a capture to one row per (tick, entity) — handy for a table / CSV / assertion. */
+export function captureRows(r) { return r.frames.flatMap((fr) => fr.rows); }

package/dist/determinismProbe.d.ts

@@ -0,0 +1,21 @@
+/** Transcendental probe over the exact math surface the ENGINE uses — Math.sin/cos/hypot
+ *  /sqrt. (We deliberately exclude tan/atan2: the engine doesn't use them, and they differ
+ *  even between V8 *versions*, which would be false-alarm noise.) Isolates whether these
+ *  specific functions agree bit-for-bit across the device's JS engine and the reference. */
+export declare function mathProbe(): string;
+/** Serial ECS sim (Gauss-Seidel) hash over the fixed scenario. */
+export declare function serialProbe(): string;
+/** Parallel-grid scheduler (Jacobi) hash over the fixed scenario. */
+export declare function parallelProbe(): string;
+export declare function runProbes(): {
+    math: string;
+    serial: string;
+    parallel: string;
+};
+/** The Mac / Node (V8, arm64) reference — the baseline every device is compared against.
+ *  Computed by `npx tsx cli/determinismRef.mts`. */
+export declare const REFERENCE: {
+    readonly math: "6502c8d3";
+    readonly serial: "4bffcd3";
+    readonly parallel: "9d2a9612";
+};

package/dist/determinismProbe.js

@@ -0,0 +1,61 @@
+// Cross-machine / cross-engine determinism probe. The engine's moat (replay, savestate,
+// lockstep) needs bit-exact determinism ACROSS hardware + JS engines. Pure-JS Math.sin/cos
+// etc. are NOT guaranteed identical across V8 (Chrome/Node) vs JavaScriptCore (iOS Safari)
+// vs the x86 vs ARM microcode — so this probe hashes: (1) a transcendental-heavy loop that
+// ISOLATES Math.* divergence, (2) the serial ECS sim, (3) the parallel-grid scheduler.
+// Run the same probe on iOS / Android / Windows-Intel and compare the hashes to the Mac/Node
+// REFERENCE below. Any mismatch localises exactly where determinism breaks (and tells us
+// whether we need fixed-point / a fixed-transcendental library, per GAME.md §5.1).
+import { fnv1a } from './stateTree';
+import { rngFromState, NO_INPUT } from './playSim';
+import { initEcs, ecsStep, ecsHash } from './ecs';
+import { stepScheduledGrid } from './scheduler';
+/** Transcendental probe over the exact math surface the ENGINE uses — Math.sin/cos/hypot
+ *  /sqrt. (We deliberately exclude tan/atan2: the engine doesn't use them, and they differ
+ *  even between V8 *versions*, which would be false-alarm noise.) Isolates whether these
+ *  specific functions agree bit-for-bit across the device's JS engine and the reference. */
+export function mathProbe() {
+    let x = 0.123456789, acc = 0;
+    for (let i = 0; i < 40000; i++) {
+        x = Math.sin(x * 1.30017 + i * 1e-4) * 0.9 + Math.cos(x * 0.7) * 0.3;
+        acc += Math.hypot(x, i * 1e-3) + Math.sqrt(Math.abs(x) + 1);
+    }
+    return fnv1a([x, acc].join(','));
+}
+/** A fixed, deterministic input stream that exercises movement / collision / shoot / spawn / despawn. */
+function scenario() {
+    const out = [];
+    for (let f = 0; f < 400; f++) {
+        const inp = { ...NO_INPUT, mv: f % 4 !== 0 ? 1 : 0, turn: f % 50 < 18 ? 1 : f % 50 < 36 ? -1 : 0 };
+        if (f % 17 === 0)
+            inp.shoot = 1;
+        if (f % 23 === 0)
+            inp.shove = 1;
+        out.push(inp);
+    }
+    return out;
+}
+/** Serial ECS sim (Gauss-Seidel) hash over the fixed scenario. */
+export function serialProbe() {
+    const w = initEcs();
+    const rng = rngFromState(0);
+    const inp = scenario();
+    for (let f = 0; f < inp.length; f++)
+        ecsStep(w, inp[f], rng, f);
+    return ecsHash(w, rng.state);
+}
+/** Parallel-grid scheduler (Jacobi) hash over the fixed scenario. */
+export function parallelProbe() {
+    const w = initEcs();
+    const rng = rngFromState(0);
+    const inp = scenario();
+    for (let f = 0; f < inp.length; f++)
+        stepScheduledGrid(w, inp[f], rng, f, 4);
+    return ecsHash(w, rng.state);
+}
+export function runProbes() {
+    return { math: mathProbe(), serial: serialProbe(), parallel: parallelProbe() };
+}
+/** The Mac / Node (V8, arm64) reference — the baseline every device is compared against.
+ *  Computed by `npx tsx cli/determinismRef.mts`. */
+export const REFERENCE = { math: '6502c8d3', serial: '4bffcd3', parallel: '9d2a9612' };

package/dist/ecs.d.ts

@@ -0,0 +1,80 @@
+import { type Input, type RNG } from './playSim';
+export declare const KIND_OBJ = 0, KIND_PROJ = 1, KIND_FRAG = 2;
+export declare const CAP = 512;
+/** A deferred structural mutation — applied at flush() in insertion order (deterministic). */
+type Cmd = {
+    op: 'spawn';
+    kind: number;
+    x: number;
+    y: number;
+    z: number;
+    vx: number;
+    vy: number;
+    vz: number;
+    r: number;
+    m: number;
+    hp: number;
+    life: number;
+} | {
+    op: 'despawn';
+    slot: number;
+};
+export interface Character {
+    x: number;
+    z: number;
+    heading: number;
+    y: number;
+    vy: number;
+    gait: 0 | 1 | 2;
+    jumpF: number;
+    animRate: number;
+    carrying: number;
+    shootCd: number;
+}
+/** The ECS world: SoA body columns + a character singleton + the allocator + queue. */
+export interface EcsWorld {
+    alive: Uint8Array;
+    id: Float64Array;
+    kind: Float64Array;
+    x: Float64Array;
+    y: Float64Array;
+    z: Float64Array;
+    vx: Float64Array;
+    vy: Float64Array;
+    vz: Float64Array;
+    r: Float64Array;
+    m: Float64Array;
+    hp: Float64Array;
+    life: Float64Array;
+    held: Float64Array;
+    free: Int32Array;
+    freeTop: number;
+    nextId: number;
+    ch: Character;
+    cmds: Cmd[];
+}
+/** Initial world: character + `n` crates on a ring (a representative slice of the sim). */
+export declare function initEcs(): EcsWorld;
+/** Seed a world with specific crates (for tests): each [x, z, r]. */
+export declare function initEcsAt(bodies: [number, number, number][]): EcsWorld;
+/** Seed `n` crates at deterministic pseudo-random positions (dense-scene scale tests). */
+export declare function initEcsDense(n: number, seed?: number): EcsWorld;
+/** Nearest grabbable/shovable body the character is FACING — aim-aware, so grab/shove target
+ *  what you point at, not merely the closest crate. Considers only bodies within a forward cone
+ *  (~78° of the heading); a coincident/touching body counts as in-front. Deterministic (dmath). */
+export declare function nearestBody(w: EcsWorld, cx: number, cz: number, reach: number): number;
+export declare function sysCharacter(w: EcsWorld, inp: Input, frame: number): void;
+export declare function sysInteract(w: EcsWorld, inp: Input): void;
+export declare function flush(w: EcsWorld): void;
+/** Advance the ECS world ONE fixed tick. Pure + deterministic. Matches StepFn<EcsWorld>. */
+export declare function ecsStep(w: EcsWorld, inp: Input, _rng: RNG, frame: number): void;
+export declare function ecsClone(w: EcsWorld): EcsWorld;
+export declare function ecsHash(w: EcsWorld, rngState: number): string;
+export declare const ECS_OPS: {
+    clone: typeof ecsClone;
+    hash: typeof ecsHash;
+};
+/** Count alive bodies of a kind (helpers for tests + detectors). */
+export declare function countKind(w: EcsWorld, kind: number): number;
+export declare function aliveCount(w: EcsWorld): number;
+export {};

package/dist/ecs.js

@@ -0,0 +1,338 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// A minimal DETERMINISTIC SoA ECS — the real engine's simulation core, in embryo.
+// This is the engine-build-plan.md "next step": move the moat (deterministic
+// replay + savestate + AI exploration) off the hand-written demo struct and onto a
+// real Structure-of-Arrays ECS, WITHOUT losing bit-exact determinism.
+//
+// Design that makes the moat survive here:
+//   • Components are numeric COLUMNS (typed arrays) indexed by a body slot — SoA, the
+//     layout the real engine needs (GAME.md §4.1: "the enemy is boundary crossings").
+//   • Entities are slots with a DETERMINISTIC free-slot allocator + monotonic stable
+//     ids — allocation order is part of the determinism contract.
+//   • Structural mutations (spawn/despawn/fragment) go through an ORDERED COMMAND
+//     QUEUE applied at a barrier (flush), so mid-tick iteration never mutates the set
+//     and the apply order is deterministic (GAME.md §9's command-queue requirement).
+//   • The whole world snapshots to owned copies → the StateTree/replay/exploration run
+//     on it UNCHANGED (StateTree is generic; ecsClone/ecsHash are the injected ops).
+//
+// The character is a singleton (physics-vs-logic split); bodies are the ECS entities.
+// Constants are owned here (this is the engine core) and match physics.ts/playSim.ts.
+// See design/engine-build-plan.md §4, design/search-based-testing.md.
+// ─────────────────────────────────────────────────────────────────────────────
+import { FIXED_DT, SPEED, CLIP_BASE, mulberry32 } from './playSim';
+import { fnv1a } from './stateTree';
+import { dsin, dcos, dhypot, dhypot3 } from './dmath';
+export const KIND_OBJ = 0, KIND_PROJ = 1, KIND_FRAG = 2;
+export const CAP = 512; // max concurrent body entities
+// character-motion constants (match playSim)
+const TURN = 1.8, GRAV_CH = 26, JUMP_V0 = 8.5, RIM = 14;
+// body-physics constants (match physics.ts)
+const GRAV = 20, PROJ_SPEED = 22, PROJ_DMG = 1, HARD_IMPACT = 9, REST_FRICTION = 0.82, AIR_DAMP = 0.992;
+function blankWorld() {
+    const free = new Int32Array(CAP);
+    for (let i = 0; i < CAP; i++)
+        free[i] = CAP - 1 - i; // pop order: slot 0,1,2,… (deterministic)
+    return {
+        alive: new Uint8Array(CAP), id: new Float64Array(CAP), kind: new Float64Array(CAP),
+        x: new Float64Array(CAP), y: new Float64Array(CAP), z: new Float64Array(CAP),
+        vx: new Float64Array(CAP), vy: new Float64Array(CAP), vz: new Float64Array(CAP),
+        r: new Float64Array(CAP), m: new Float64Array(CAP), hp: new Float64Array(CAP), life: new Float64Array(CAP), held: new Float64Array(CAP),
+        free, freeTop: CAP, nextId: 1,
+        ch: { x: 0, z: 0, heading: 0, y: 0, vy: 0, gait: 0, jumpF: -1, animRate: 1, carrying: -1, shootCd: 0 },
+        cmds: [],
+    };
+}
+/** Allocate a body immediately (used by init + by flush). Deterministic slot + id. */
+function alloc(w, kind, x, y, z, vx, vy, vz, r, m, hp, life) {
+    if (w.freeTop === 0)
+        return -1; // at capacity — deterministic drop
+    const slot = w.free[--w.freeTop];
+    w.alive[slot] = 1;
+    w.id[slot] = w.nextId++;
+    w.kind[slot] = kind;
+    w.x[slot] = x;
+    w.y[slot] = y;
+    w.z[slot] = z;
+    w.vx[slot] = vx;
+    w.vy[slot] = vy;
+    w.vz[slot] = vz;
+    w.r[slot] = r;
+    w.m[slot] = m;
+    w.hp[slot] = hp;
+    w.life[slot] = life;
+    w.held[slot] = 0;
+    return slot;
+}
+function freeSlot(w, slot) { if (!w.alive[slot])
+    return; w.alive[slot] = 0; w.free[w.freeTop++] = slot; }
+/** Initial world: character + `n` crates on a ring (a representative slice of the sim). */
+export function initEcs() {
+    const w = blankWorld();
+    // crates at r≈0.9 so a muzzle-height projectile (y≈1.4) actually hits them
+    const seeds = [[3, 3], [-3.5, 4], [4.5, -1], [-2, 5], [1.5, 6]];
+    for (const [cx, cz] of seeds)
+        alloc(w, KIND_OBJ, cx, 0.9, cz, 0, 0, 0, 0.9, 1, 3, -1);
+    return w;
+}
+/** Seed a world with specific crates (for tests): each [x, z, r]. */
+export function initEcsAt(bodies) {
+    const w = blankWorld();
+    for (const [x, z, r] of bodies)
+        alloc(w, KIND_OBJ, x, r, z, 0, 0, 0, r, 1, 3, -1);
+    return w;
+}
+/** Seed `n` crates at deterministic pseudo-random positions (dense-scene scale tests). */
+export function initEcsDense(n, seed = 0x1234) {
+    const rng = mulberry32(seed);
+    const b = [];
+    for (let k = 0; k < n; k++)
+        b.push([(rng() - 0.5) * 24, (rng() - 0.5) * 24, 0.3 + rng() * 0.6]);
+    return initEcsAt(b);
+}
+/** Nearest grabbable/shovable body the character is FACING — aim-aware, so grab/shove target
+ *  what you point at, not merely the closest crate. Considers only bodies within a forward cone
+ *  (~78° of the heading); a coincident/touching body counts as in-front. Deterministic (dmath). */
+export function nearestBody(w, cx, cz, reach) {
+    const fx = dsin(w.ch.heading), fz = dcos(w.ch.heading);
+    let best = -1, bestD = reach;
+    for (let s = 0; s < CAP; s++) {
+        if (!w.alive[s] || w.kind[s] !== KIND_OBJ || w.held[s])
+            continue;
+        const dx = w.x[s] - cx, dz = w.z[s] - cz, d = dhypot(dx, dz);
+        if (d >= bestD)
+            continue; // only closer-than-best candidates
+        const fwd = d > 1e-6 ? (dx * fx + dz * fz) / d : 1; // cos(angle to facing); coincident ⇒ in front
+        if (fwd < 0.2)
+            continue; // must be within ~78° of where you face
+        bestD = d;
+        best = s;
+    }
+    return best;
+}
+// ── systems (fixed order over the columns) ── (exported for the parallel scheduler)
+export function sysCharacter(w, inp, frame) {
+    const c = w.ch;
+    c.heading += inp.turn * TURN * FIXED_DT;
+    c.gait = inp.mv !== 0 ? (inp.run ? 2 : 1) : 0;
+    const sp = SPEED[c.gait] * (inp.mv < 0 ? -1 : 1) * (inp.mv !== 0 ? 1 : 0);
+    c.x += dsin(c.heading) * sp * FIXED_DT;
+    c.z += dcos(c.heading) * sp * FIXED_DT;
+    const rr = dhypot(c.x, c.z);
+    if (rr > RIM) {
+        c.x *= RIM / rr;
+        c.z *= RIM / rr;
+    }
+    c.animRate = c.gait > 0 ? SPEED[c.gait] / CLIP_BASE[c.gait] : 1;
+    if (inp.jump && c.jumpF < 0 && c.y <= 0.001) {
+        c.jumpF = frame;
+        c.vy = JUMP_V0;
+    }
+    c.vy -= GRAV_CH * FIXED_DT;
+    c.y += c.vy * FIXED_DT;
+    if (c.y <= 0) {
+        c.y = 0;
+        c.vy = 0;
+        if (c.jumpF >= 0)
+            c.jumpF = -1;
+    }
+}
+export function sysInteract(w, inp) {
+    const c = w.ch;
+    if (inp.shove) {
+        const n = nearestBody(w, c.x, c.z, 1.9);
+        if (n >= 0) {
+            w.vx[n] += dsin(c.heading) * 11;
+            w.vz[n] += dcos(c.heading) * 11;
+        }
+    }
+    if (inp.grab) {
+        if (c.carrying < 0) {
+            const n = nearestBody(w, c.x, c.z, 1.6);
+            if (n >= 0) {
+                w.held[n] = 1;
+                c.carrying = w.id[n];
+            }
+        }
+        else {
+            for (let s = 0; s < CAP; s++)
+                if (w.alive[s] && w.id[s] === c.carrying) {
+                    w.held[s] = 0;
+                    w.vx[s] = dsin(c.heading) * 8;
+                    w.vz[s] = dcos(c.heading) * 8;
+                    w.vy[s] = 3;
+                }
+            c.carrying = -1;
+        }
+    }
+    if (c.shootCd > 0)
+        c.shootCd -= 1;
+    if (inp.shoot && c.shootCd <= 0) {
+        const fx = dsin(c.heading), fz = dcos(c.heading);
+        w.cmds.push({ op: 'spawn', kind: KIND_PROJ, x: c.x + fx * 1.15, y: 1.4, z: c.z + fz * 1.15, vx: fx * PROJ_SPEED, vy: 0.5, vz: fz * PROJ_SPEED, r: 0.16, m: 0.3, hp: 1, life: 90 });
+        c.shootCd = 10;
+    }
+}
+function sysPhysics(w, dt) {
+    const c = w.ch;
+    for (let s = 0; s < CAP; s++) {
+        if (!w.alive[s])
+            continue;
+        if (w.life[s] > 0)
+            w.life[s] -= 1;
+        if (w.held[s]) {
+            w.x[s] = c.x + dsin(c.heading) * (0.6 + w.r[s] + 0.1);
+            w.z[s] = c.z + dcos(c.heading) * (0.6 + w.r[s] + 0.1);
+            w.y[s] = 1.7;
+            w.vx[s] = 0;
+            w.vy[s] = 0;
+            w.vz[s] = 0;
+            continue;
+        }
+        w.vy[s] -= GRAV * dt;
+        w.x[s] += w.vx[s] * dt;
+        w.y[s] += w.vy[s] * dt;
+        w.z[s] += w.vz[s] * dt;
+        if (w.y[s] < w.r[s]) {
+            w.y[s] = w.r[s];
+            if (w.vy[s] < 0)
+                w.vy[s] = -w.vy[s] * 0.2;
+            w.vx[s] *= REST_FRICTION;
+            w.vz[s] *= REST_FRICTION;
+        }
+        const rr = dhypot(w.x[s], w.z[s]);
+        if (rr > RIM) {
+            w.x[s] *= RIM / rr;
+            w.z[s] *= RIM / rr;
+            w.vx[s] *= -0.3;
+            w.vz[s] *= -0.3;
+        }
+        w.vx[s] *= AIR_DAMP;
+        w.vz[s] *= AIR_DAMP;
+    }
+    // body↔body (alive slots, i<j) — projectile damage + hard-impact hp + separation
+    for (let i = 0; i < CAP; i++) {
+        if (!w.alive[i] || w.held[i])
+            continue;
+        for (let j = i + 1; j < CAP; j++) {
+            if (!w.alive[j] || w.held[j])
+                continue;
+            const dx = w.x[j] - w.x[i], dy = w.y[j] - w.y[i], dz = w.z[j] - w.z[i];
+            const d = dhypot3(dx, dy, dz) || 1e-6;
+            const ov = w.r[i] + w.r[j] - d;
+            if (ov <= 0)
+                continue;
+            const nx = dx / d, ny = dy / d, nz = dz / d;
+            const iProj = w.kind[i] === KIND_PROJ, jProj = w.kind[j] === KIND_PROJ;
+            if (iProj !== jProj) {
+                const p = iProj ? i : j, o = iProj ? j : i;
+                if (w.kind[o] === KIND_OBJ) {
+                    w.hp[o] -= PROJ_DMG;
+                    w.vx[o] += w.vx[p] * 0.06;
+                    w.vz[o] += w.vz[p] * 0.06;
+                    w.life[p] = 0;
+                    continue;
+                }
+            }
+            const push = ov * 0.5;
+            w.x[i] -= nx * push;
+            w.y[i] -= ny * push;
+            w.z[i] -= nz * push;
+            w.x[j] += nx * push;
+            w.y[j] += ny * push;
+            w.z[j] += nz * push;
+            const rvn = (w.vx[j] - w.vx[i]) * nx + (w.vy[j] - w.vy[i]) * ny + (w.vz[j] - w.vz[i]) * nz;
+            if (rvn < 0) {
+                const imp = rvn * 0.5;
+                w.vx[i] += imp * nx;
+                w.vy[i] += imp * ny;
+                w.vz[i] += imp * nz;
+                w.vx[j] -= imp * nx;
+                w.vy[j] -= imp * ny;
+                w.vz[j] -= imp * nz;
+                if (-rvn > HARD_IMPACT) {
+                    if (w.kind[i] === KIND_OBJ)
+                        w.hp[i] -= 1;
+                    if (w.kind[j] === KIND_OBJ)
+                        w.hp[j] -= 1;
+                }
+            }
+        }
+    }
+    // character cylinder push (planar)
+    for (let s = 0; s < CAP; s++) {
+        if (!w.alive[s] || w.held[s] || w.kind[s] !== KIND_OBJ || w.y[s] > 2.2)
+            continue;
+        const dx = w.x[s] - c.x, dz = w.z[s] - c.z;
+        const d = dhypot(dx, dz) || 1e-6;
+        const ov = 0.6 + w.r[s] - d;
+        if (ov > 0) {
+            const nx = dx / d, nz = dz / d;
+            w.x[s] += nx * ov;
+            w.z[s] += nz * ov;
+            w.vx[s] += nx * ov * 9;
+            w.vz[s] += nz * ov * 9;
+        }
+    }
+}
+function sysLifecycle(w) {
+    for (let s = 0; s < CAP; s++) {
+        if (!w.alive[s])
+            continue;
+        const expired = (w.kind[s] === KIND_PROJ || w.kind[s] === KIND_FRAG) && w.life[s] <= 0;
+        const broken = w.kind[s] === KIND_OBJ && w.hp[s] <= 0 && !w.held[s];
+        if (broken)
+            for (let k = 0; k < 5; k++) {
+                const a = (Math.PI * 2 * k) / 5, off = w.r[s] * 0.6;
+                w.cmds.push({ op: 'spawn', kind: KIND_FRAG, x: w.x[s] + dcos(a) * off, y: w.y[s] + 0.1, z: w.z[s] + dsin(a) * off, vx: dcos(a) * 4, vy: 4, vz: dsin(a) * 4, r: w.r[s] * 0.25, m: 0.2, hp: 1, life: 48 });
+            }
+        if (expired || broken) {
+            if (w.ch.carrying === w.id[s])
+                w.ch.carrying = -1;
+            w.cmds.push({ op: 'despawn', slot: s });
+        }
+    }
+}
+export function flush(w) {
+    for (const cmd of w.cmds) {
+        if (cmd.op === 'despawn')
+            freeSlot(w, cmd.slot);
+        else
+            alloc(w, cmd.kind, cmd.x, cmd.y, cmd.z, cmd.vx, cmd.vy, cmd.vz, cmd.r, cmd.m, cmd.hp, cmd.life);
+    }
+    w.cmds.length = 0;
+}
+/** Advance the ECS world ONE fixed tick. Pure + deterministic. Matches StepFn<EcsWorld>. */
+export function ecsStep(w, inp, _rng, frame) {
+    sysCharacter(w, inp, frame);
+    sysInteract(w, inp);
+    sysPhysics(w, FIXED_DT);
+    sysLifecycle(w);
+    flush(w); // deterministic structural barrier — cmds empty at the tick boundary
+}
+// ── the moat's injected ops (clone + content-hash) — so StateTree runs on the ECS ──
+export function ecsClone(w) {
+    return {
+        alive: w.alive.slice(), id: w.id.slice(), kind: w.kind.slice(),
+        x: w.x.slice(), y: w.y.slice(), z: w.z.slice(), vx: w.vx.slice(), vy: w.vy.slice(), vz: w.vz.slice(),
+        r: w.r.slice(), m: w.m.slice(), hp: w.hp.slice(), life: w.life.slice(), held: w.held.slice(),
+        free: w.free.slice(), freeTop: w.freeTop, nextId: w.nextId,
+        ch: { ...w.ch }, cmds: w.cmds.map((c) => ({ ...c })),
+    };
+}
+export function ecsHash(w, rngState) {
+    const p = [w.freeTop, w.nextId, rngState, w.ch.x, w.ch.z, w.ch.heading, w.ch.y, w.ch.vy, w.ch.gait, w.ch.jumpF, w.ch.carrying, w.ch.shootCd];
+    for (let s = 0; s < CAP; s++) {
+        if (!w.alive[s])
+            continue;
+        p.push(s, w.id[s], w.kind[s], w.x[s], w.y[s], w.z[s], w.vx[s], w.vy[s], w.vz[s], w.r[s], w.hp[s], w.life[s], w.held[s]);
+    }
+    return fnv1a(p.join(','));
+}
+export const ECS_OPS = { clone: ecsClone, hash: ecsHash };
+/** Count alive bodies of a kind (helpers for tests + detectors). */
+export function countKind(w, kind) { let n = 0; for (let s = 0; s < CAP; s++)
+    if (w.alive[s] && w.kind[s] === kind)
+        n++; return n; }
+export function aliveCount(w) { let n = 0; for (let s = 0; s < CAP; s++)
+    if (w.alive[s])
+        n++; return n; }

package/dist/frameProbe.d.ts

@@ -0,0 +1,22 @@
+export interface FrameStats {
+    meanLum: number;
+    minLum: number;
+    maxLum: number;
+    contrast: number;
+}
+export interface FrameResult {
+    stats: FrameStats;
+    sig: number[];
+}
+export declare class FrameProbe {
+    private device;
+    constructor(device: GPUDevice);
+    /** Render via `render(enc, colorView, depthView)` to a 256² rgba8 target, read it back, and
+     *  return sanity stats + an 8×8 luminance signature. Deterministic for a pinned scene. */
+    capture(render: (enc: GPUCommandEncoder, colorView: GPUTextureView, depthView: GPUTextureView) => void): Promise<FrameResult>;
+}
+/** Compare a signature to a golden: max per-cell diff + count of cells over a small threshold. */
+export declare function sigDiff(a: number[], b: number[]): {
+    maxCell: number;
+    overCount: number;
+};

package/dist/frameProbe.js

@@ -0,0 +1,56 @@
+// FULL-FRAME visual-regression harness: render a pinned deterministic scene to an offscreen
+// target, READ THE WHOLE FRAMEBUFFER BACK, and reduce it to (a) sanity stats and (b) a small
+// perceptual SIGNATURE that can be compared to a committed golden. This is how the eyeballed
+// render demos become actual regression tests — a broken render (all-black, blown-out, changed)
+// fails automatically instead of needing a human to notice. Pairs with shaderProbe.ts (which
+// checks material values); this checks a whole rendered frame.
+const SIZE = 256, GRID = 8; // 256×256 render (bytesPerRow = 1024, 256-aligned); 8×8 signature
+export class FrameProbe {
+    device;
+    constructor(device) { this.device = device; }
+    /** Render via `render(enc, colorView, depthView)` to a 256² rgba8 target, read it back, and
+     *  return sanity stats + an 8×8 luminance signature. Deterministic for a pinned scene. */
+    async capture(render) {
+        const d = this.device, w = SIZE, h = SIZE, bpr = w * 4;
+        const color = d.createTexture({ size: [w, h], format: 'rgba8unorm', usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC | GPUTextureUsage.TEXTURE_BINDING });
+        const depth = d.createTexture({ size: [w, h], format: 'depth24plus', usage: GPUTextureUsage.RENDER_ATTACHMENT });
+        const readBuf = d.createBuffer({ size: bpr * h, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });
+        const enc = d.createCommandEncoder();
+        render(enc, color.createView(), depth.createView());
+        enc.copyTextureToBuffer({ texture: color }, { buffer: readBuf, bytesPerRow: bpr, rowsPerImage: h }, [w, h]);
+        d.queue.submit([enc.finish()]);
+        await readBuf.mapAsync(GPUMapMode.READ);
+        const px = new Uint8Array(readBuf.getMappedRange().slice(0));
+        readBuf.unmap();
+        color.destroy();
+        depth.destroy();
+        readBuf.destroy();
+        // stats over every pixel
+        let sum = 0, mn = 255, mx = 0;
+        const cell = new Float64Array(GRID * GRID), cellN = w / GRID;
+        for (let y = 0; y < h; y++)
+            for (let x = 0; x < w; x++) {
+                const o = (y * w + x) * 4, lum = 0.299 * px[o] + 0.587 * px[o + 1] + 0.114 * px[o + 2];
+                sum += lum;
+                if (lum < mn)
+                    mn = lum;
+                if (lum > mx)
+                    mx = lum;
+                cell[Math.floor(y / cellN) * GRID + Math.floor(x / cellN)] += lum;
+            }
+        const n = w * h, sig = Array.from(cell, (c) => Math.round(c / (cellN * cellN)));
+        return { stats: { meanLum: +(sum / n).toFixed(2), minLum: mn, maxLum: mx, contrast: mx - mn }, sig };
+    }
+}
+/** Compare a signature to a golden: max per-cell diff + count of cells over a small threshold. */
+export function sigDiff(a, b) {
+    let maxCell = 0, overCount = 0;
+    for (let i = 0; i < a.length; i++) {
+        const dd = Math.abs(a[i] - (b[i] ?? 0));
+        if (dd > maxCell)
+            maxCell = dd;
+        if (dd > 8)
+            overCount++;
+    }
+    return { maxCell, overCount };
+}