@vgai/engine 0.5.21 → 0.5.23

package/dist/core/countdown-timer.js

@@ -0,0 +1,137 @@
+/**
+ * `Countdown` — a restartable interval the CALLER steps, with the two
+ * behaviours under a frame hitch that decide whether a game's event count is
+ * right.
+ *
+ * A respawn delay, a weapon cooldown, a wave spawner, a grace window: each is
+ * "count down from N seconds, tell me, maybe go again, and let me restart or
+ * stop you at any point". `core/sim-clock.ts` schedules a one-shot at an
+ * ABSOLUTE sim time — the right shape for "3 seconds from now, once" and the
+ * wrong one for a live interval that game code re-arms, reads
+ * ({@link Countdown.remaining} is what a HUD ring draws) and cancels.
+ *
+ * That gap used to be papered over in `sim-clock.ts`'s own header, which said
+ * an `after` re-arming itself was "three lines the game owns". Those three
+ * lines are wrong in a way nobody notices: re-arming schedules the next fire
+ * from the moment the callback RAN, so every long frame permanently lengthens
+ * the interval, and a game that hitches ten times has silently slowed its
+ * spawner. That is the drift {@link Countdown} exists to not have.
+ *
+ * ## It owns no clock, and that is the requirement rather than a shortcut
+ *
+ * There is no `setTimeout`, no `setInterval`, no `requestAnimationFrame` and no
+ * subscription anywhere in this module. A countdown advances only inside
+ * {@link Countdown.advance}, from seconds the caller already has — the fixed
+ * loop's own dt. This repo runs a fixed-step sim with display-rate
+ * presentation and can step a game deterministically; a countdown on wall-clock
+ * `setTimeout` would be a second, undeterministic timeline that no care
+ * downstream could re-sync. A countdown nobody advances does not fire —
+ * visibly, rather than drifting.
+ *
+ * ## The frame-hitch contract, which is the whole reason this is a module
+ *
+ * Both rules are about keeping the EVENT COUNT correct when `dt` is larger than
+ * the period, which is exactly when a game is already in trouble:
+ *
+ *  - **Overshoot carries into the next period.** A 0.5 s repeating countdown
+ *    advanced by 0.6 fires once and has 0.4 s left, not 0.5. Resetting to the
+ *    full period instead would make one slow frame lengthen every interval
+ *    after it — the drift above, one layer down.
+ *  - **A single large step fires MORE THAN ONCE.** A 0.1 s countdown advanced
+ *    by 0.35 fires three times and has 0.05 s left. Dropping the extras would
+ *    silently slow a repeating countdown down whenever the frame was long, so a
+ *    wave that should have spawned 3 enemies spawns 1 and the difficulty curve
+ *    quietly depends on frame rate.
+ *
+ * Two consequences a caller must know about, both deliberate: `onElapsed` can
+ * be invoked several times within one `advance` call, and it runs INLINE
+ * (synchronously, inside `advance`) rather than on a microtask — so the caller
+ * always knows exactly which point of its frame the callback ran at.
+ *
+ * A one-shot countdown STOPS ITSELF BEFORE invoking `onElapsed`, so a callback
+ * that calls {@link Countdown.start} re-arms rather than fighting the stop.
+ * A callback that calls {@link Countdown.stop} ends the multi-fire loop
+ * immediately, which is what makes "fire once then disarm from inside the
+ * callback" work.
+ *
+ * ## Resource ownership
+ *
+ * **Owner:** whoever calls {@link createCountdown}. A countdown holds two
+ * numbers, a boolean and the `onElapsed` reference; it registers nothing,
+ * subscribes to nothing, and this module has no module-level state — so there
+ * is deliberately no `dispose()` and dropping the countdown drops everything it
+ * had. **Sharers:** none; a countdown is not shareable, because whoever
+ * advances it decides its timeline. **Teardown:** what DOES need unregistering
+ * is the countdown's slot in whatever set the owner advances each frame, and
+ * that is the owner's — the same way `SceneTree.addTimer` hands back a remover.
+ */
+function assertDuration(value) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new RangeError(`createCountdown: duration must be a finite, positive number of seconds, got ${String(value)}`);
+    }
+}
+/**
+ * Build a countdown.
+ *
+ * ```ts
+ * const wave = createCountdown({ duration: 8, repeats: true, autostart: true, onElapsed: spawnWave });
+ * useFrame((_, dt) => wave.advance(dt));   // the caller owns the step
+ * ```
+ */
+export function createCountdown(options) {
+    const onElapsed = options.onElapsed;
+    const repeats = options.repeats === true;
+    let duration = options.duration ?? 1;
+    let remaining = 0;
+    let running = false;
+    assertDuration(duration);
+    const countdown = {
+        get duration() {
+            return duration;
+        },
+        get repeats() {
+            return repeats;
+        },
+        get remaining() {
+            return running ? remaining : 0;
+        },
+        get running() {
+            return running;
+        },
+        start(newDuration) {
+            if (newDuration !== undefined) {
+                assertDuration(newDuration);
+                duration = newDuration;
+            }
+            remaining = duration;
+            running = true;
+        },
+        stop() {
+            running = false;
+            remaining = 0;
+        },
+        advance(dt) {
+            if (!running)
+                return;
+            remaining -= dt;
+            // The loop is the multi-fire rule; `running` in the condition is what
+            // lets a callback's own stop() end it. Module header, frame-hitch.
+            while (running && remaining <= 0) {
+                if (!repeats) {
+                    // Disarm BEFORE invoking, so a callback that calls start() re-arms
+                    // instead of being immediately stopped by this branch.
+                    running = false;
+                    remaining = 0;
+                    onElapsed();
+                    return;
+                }
+                // Carry the overshoot rather than resetting to the full period.
+                remaining += duration;
+                onElapsed();
+            }
+        },
+    };
+    if (options.autostart === true)
+        countdown.start();
+    return countdown;
+}

package/dist/core/deferred-commands.d.ts

@@ -0,0 +1,127 @@
+/**
+ * `DeferredCommands` — work the caller runs at ONE point it chooses, plus the
+ * subject-keyed disposal that has to land after it.
+ *
+ * The hazard is not exotic and it is not a foreign engine's: it is what a
+ * Rapier world does to anything that mutates it from inside a callback. Disable
+ * a collider while the solver is iterating, or free the node a collision
+ * handler was dispatched ON, and the failure is either a corrupt step or
+ * Rapier's own "recursive use of an object ... unsafe aliasing in rust". The
+ * remedy is always the same shape — write down WHAT to do, do it once the frame
+ * is out of anybody's way — and every caller that needs it was previously
+ * hand-rolling an array.
+ *
+ * ## The one point is the CALLER's, deliberately
+ *
+ * There is no `queueMicrotask`, no `setTimeout(0)`, no `requestAnimationFrame`
+ * and no subscription anywhere in this module. Whoever builds the queue decides
+ * where {@link DeferredCommands.drain} runs — after physics, at the tail of a
+ * world's update, wherever the frame's quiet moment actually is. A queue nobody
+ * drains simply does not run its work, which is a visible failure rather than a
+ * silent reordering onto a timeline the game does not control.
+ *
+ * ## This is NOT `SimClock`, and `after(0)` is not a substitute
+ *
+ * `core/sim-clock.ts` schedules on SIM TIME: `after(0, fn)` scheduled mid-frame
+ * does land in that frame's tail flush (`runtime/game.ts` calls `flush(simT)`
+ * after every phase of every world), so the resemblance is real and worth
+ * naming. Three things make it the wrong tool for deferral:
+ *
+ *  - **A paused world never flushes.** `flush` is inside `runFrameImpl`'s
+ *    `advanced` guard, so a game that pauses between the defer and the drain
+ *    holds the work forever. End-of-frame deferral has to run on the frame,
+ *    not on the clock.
+ *  - **No subject identity.** Deferring destruction needs "this object, once",
+ *    and needs the two questions that fall out of it —
+ *    {@link DeferredCommands.isDisposePending} (a handler must be able to skip
+ *    a subject that is already going away) and
+ *    {@link DeferredCommands.wasDisposed} (an owner sweeping its own indexes
+ *    after the drain). A time-ordered timer set answers neither.
+ *  - **No same-drain re-entry.** A sim timer scheduled during a flush is
+ *    deliberately never due in that flush; a deferred command that defers one
+ *    more command must still land this frame, or the second write arrives a
+ *    frame after the first and the two are no longer atomic.
+ *
+ * ## Ordering, and why disposal goes last
+ *
+ * {@link DeferredCommands.drain} runs every deferred command first, re-draining
+ * until the queue is empty, and only then disposes every pending subject. That
+ * order is not cosmetic: a deferred write to a subject that is ALSO queued for
+ * disposal must still happen — it is what the caller asked for — and disposing
+ * first would make that write operate on a freed handle. A subject queued twice
+ * is disposed once, and the FIRST thunk wins (every caller for one subject
+ * passes the same one).
+ *
+ * The re-drain is bounded by {@link MAX_DRAIN_PASSES}. A command that defers
+ * itself forever is a bug in the caller, and a bounded loop names it in a
+ * millisecond instead of hanging the frame.
+ *
+ * ## Why disposal carries its own thunk
+ *
+ * Disposal is the one thing here that is not surface-neutral. A `PIXI.Container`
+ * ends with `removeFromParent()` + `destroy({ children })`; a `THREE.Object3D`
+ * ends by detaching and disposing the geometries and materials underneath it;
+ * a physics-backed entity has a Rapier body to pull first. This queue does none
+ * of that — it takes the thunk from whoever owns the surface and runs it at the
+ * drain. So the ORDERING lives here once and the surface knowledge stays where
+ * the surface is, which is what lets one queue serve a 2D world and a 3D one.
+ *
+ * ## Resource ownership
+ *
+ * **Owner:** whoever calls {@link createDeferredCommands}, and that owner is
+ * also the only caller of `drain()` — a queue is per-DRAINER, not per-process,
+ * so two mounted games are two queues and neither can see the other's work.
+ * This module registers nothing anywhere: there is no game-scoped slot (unlike
+ * `sim-clock.ts`, which needs one because every world on a Game shares one
+ * clock) and no module-level state at all.
+ * **Sharers:** the queued subjects, by reference, and only until the drain that
+ * disposes them.
+ * **Teardown:** dropping the queue. There is deliberately no `dispose()` —
+ * nothing here holds a handle, a listener or a timer, and a queue dropped with
+ * work still in it has simply not run that work, which is what discarding a
+ * frame means.
+ */
+/**
+ * How many times {@link DeferredCommands.drain} re-drains a queue that keeps
+ * refilling itself before declaring the caller's own logic non-terminating.
+ *
+ * A bound that correct code cannot reach (a deferred command that defers one
+ * more, ten deep) while catching the infinite case immediately.
+ */
+export declare const MAX_DRAIN_PASSES = 16;
+/** The queue. Build one per drainer with {@link createDeferredCommands}. */
+export interface DeferredCommands {
+    /**
+     * Run `command` at the next {@link DeferredCommands.drain}.
+     *
+     * ```ts
+     * // inside a collision handler, where the solver still owns the world:
+     * frame.defer(() => collider.setSensor(true));
+     * ```
+     */
+    defer(command: () => void): void;
+    /**
+     * Dispose `subject` at the next drain, after every deferred command has run.
+     * Queuing the same subject twice disposes it once — the first `dispose`
+     * thunk wins.
+     */
+    deferDispose(subject: object, dispose: () => void): void;
+    /**
+     * Is `subject` queued for disposal and not yet disposed? Read by a handler
+     * that must skip a subject already on its way out.
+     */
+    isDisposePending(subject: object): boolean;
+    /**
+     * Has THIS queue already disposed `subject`? Read after a drain by an owner
+     * sweeping its own indexes (a group, a registry, a spatial bucket) — "am I
+     * destroyed" is a surface-specific question that a plain `Object3D` has no
+     * answer to, so the queue is asked instead.
+     */
+    wasDisposed(subject: object): boolean;
+    /** Run every deferred command (re-draining), then dispose every pending
+     *  subject. Called once per frame, by the owner, at the point it chose. */
+    drain(): void;
+}
+/** Build one queue. See the module header for who owns it and who drains it. */
+export declare function createDeferredCommands(): DeferredCommands;
+//# sourceMappingURL=deferred-commands.d.ts.map

package/dist/core/deferred-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred-commands.d.ts","sourceRoot":"","sources":["../../src/core/deferred-commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkFG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC,4EAA4E;AAC5E,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;OAOG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACzD;;;OAGG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3C;;;;;OAKG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACtC;+EAC2E;IAC3E,KAAK,IAAI,IAAI,CAAC;CACf;AAED,gFAAgF;AAChF,wBAAgB,sBAAsB,IAAI,gBAAgB,CA6CzD"}

package/dist/core/deferred-commands.js

@@ -0,0 +1,132 @@
+/**
+ * `DeferredCommands` — work the caller runs at ONE point it chooses, plus the
+ * subject-keyed disposal that has to land after it.
+ *
+ * The hazard is not exotic and it is not a foreign engine's: it is what a
+ * Rapier world does to anything that mutates it from inside a callback. Disable
+ * a collider while the solver is iterating, or free the node a collision
+ * handler was dispatched ON, and the failure is either a corrupt step or
+ * Rapier's own "recursive use of an object ... unsafe aliasing in rust". The
+ * remedy is always the same shape — write down WHAT to do, do it once the frame
+ * is out of anybody's way — and every caller that needs it was previously
+ * hand-rolling an array.
+ *
+ * ## The one point is the CALLER's, deliberately
+ *
+ * There is no `queueMicrotask`, no `setTimeout(0)`, no `requestAnimationFrame`
+ * and no subscription anywhere in this module. Whoever builds the queue decides
+ * where {@link DeferredCommands.drain} runs — after physics, at the tail of a
+ * world's update, wherever the frame's quiet moment actually is. A queue nobody
+ * drains simply does not run its work, which is a visible failure rather than a
+ * silent reordering onto a timeline the game does not control.
+ *
+ * ## This is NOT `SimClock`, and `after(0)` is not a substitute
+ *
+ * `core/sim-clock.ts` schedules on SIM TIME: `after(0, fn)` scheduled mid-frame
+ * does land in that frame's tail flush (`runtime/game.ts` calls `flush(simT)`
+ * after every phase of every world), so the resemblance is real and worth
+ * naming. Three things make it the wrong tool for deferral:
+ *
+ *  - **A paused world never flushes.** `flush` is inside `runFrameImpl`'s
+ *    `advanced` guard, so a game that pauses between the defer and the drain
+ *    holds the work forever. End-of-frame deferral has to run on the frame,
+ *    not on the clock.
+ *  - **No subject identity.** Deferring destruction needs "this object, once",
+ *    and needs the two questions that fall out of it —
+ *    {@link DeferredCommands.isDisposePending} (a handler must be able to skip
+ *    a subject that is already going away) and
+ *    {@link DeferredCommands.wasDisposed} (an owner sweeping its own indexes
+ *    after the drain). A time-ordered timer set answers neither.
+ *  - **No same-drain re-entry.** A sim timer scheduled during a flush is
+ *    deliberately never due in that flush; a deferred command that defers one
+ *    more command must still land this frame, or the second write arrives a
+ *    frame after the first and the two are no longer atomic.
+ *
+ * ## Ordering, and why disposal goes last
+ *
+ * {@link DeferredCommands.drain} runs every deferred command first, re-draining
+ * until the queue is empty, and only then disposes every pending subject. That
+ * order is not cosmetic: a deferred write to a subject that is ALSO queued for
+ * disposal must still happen — it is what the caller asked for — and disposing
+ * first would make that write operate on a freed handle. A subject queued twice
+ * is disposed once, and the FIRST thunk wins (every caller for one subject
+ * passes the same one).
+ *
+ * The re-drain is bounded by {@link MAX_DRAIN_PASSES}. A command that defers
+ * itself forever is a bug in the caller, and a bounded loop names it in a
+ * millisecond instead of hanging the frame.
+ *
+ * ## Why disposal carries its own thunk
+ *
+ * Disposal is the one thing here that is not surface-neutral. A `PIXI.Container`
+ * ends with `removeFromParent()` + `destroy({ children })`; a `THREE.Object3D`
+ * ends by detaching and disposing the geometries and materials underneath it;
+ * a physics-backed entity has a Rapier body to pull first. This queue does none
+ * of that — it takes the thunk from whoever owns the surface and runs it at the
+ * drain. So the ORDERING lives here once and the surface knowledge stays where
+ * the surface is, which is what lets one queue serve a 2D world and a 3D one.
+ *
+ * ## Resource ownership
+ *
+ * **Owner:** whoever calls {@link createDeferredCommands}, and that owner is
+ * also the only caller of `drain()` — a queue is per-DRAINER, not per-process,
+ * so two mounted games are two queues and neither can see the other's work.
+ * This module registers nothing anywhere: there is no game-scoped slot (unlike
+ * `sim-clock.ts`, which needs one because every world on a Game shares one
+ * clock) and no module-level state at all.
+ * **Sharers:** the queued subjects, by reference, and only until the drain that
+ * disposes them.
+ * **Teardown:** dropping the queue. There is deliberately no `dispose()` —
+ * nothing here holds a handle, a listener or a timer, and a queue dropped with
+ * work still in it has simply not run that work, which is what discarding a
+ * frame means.
+ */
+/**
+ * How many times {@link DeferredCommands.drain} re-drains a queue that keeps
+ * refilling itself before declaring the caller's own logic non-terminating.
+ *
+ * A bound that correct code cannot reach (a deferred command that defers one
+ * more, ten deep) while catching the infinite case immediately.
+ */
+export const MAX_DRAIN_PASSES = 16;
+/** Build one queue. See the module header for who owns it and who drains it. */
+export function createDeferredCommands() {
+    let commands = [];
+    const doomed = new Map();
+    const disposed = new WeakSet();
+    return {
+        defer(command) {
+            commands.push(command);
+        },
+        deferDispose(subject, dispose) {
+            if (!doomed.has(subject))
+                doomed.set(subject, dispose);
+        },
+        isDisposePending(subject) {
+            return doomed.has(subject);
+        },
+        wasDisposed(subject) {
+            return disposed.has(subject);
+        },
+        drain() {
+            let passes = 0;
+            while (commands.length > 0) {
+                if (++passes > MAX_DRAIN_PASSES) {
+                    throw new Error(`DeferredCommands.drain: still queueing more work after ${MAX_DRAIN_PASSES} passes. ` +
+                        'Something passed to defer() defers itself, so this drain would never terminate.');
+                }
+                const batch = commands;
+                commands = [];
+                for (const command of batch)
+                    command();
+            }
+            // Subjects last, and only after every deferred command has run — see the
+            // module header's ordering section.
+            for (const [subject, dispose] of doomed) {
+                dispose();
+                disposed.add(subject);
+            }
+            doomed.clear();
+        },
+    };
+}

package/dist/core/frame-pacing.d.ts

@@ -1,6 +1,6 @@
 /**
  * Frame pacing — the accumulator/alpha arithmetic of the fixed-timestep loop,
- * extracted PURE (WO-P13, `docs/WORK.md` §2 P13).
+ * extracted PURE.
  *
  * `core/game-loop.ts` owns the browser side (rAF, `visibilitychange`,
  * `performance.now`); this module owns the arithmetic, so the interesting

package/dist/core/frame-pacing.js

@@ -1,6 +1,6 @@
 /**
  * Frame pacing — the accumulator/alpha arithmetic of the fixed-timestep loop,
- * extracted PURE (WO-P13, `docs/WORK.md` §2 P13).
+ * extracted PURE.
  *
  * `core/game-loop.ts` owns the browser side (rAF, `visibilitychange`,
  * `performance.now`); this module owns the arithmetic, so the interesting
@@ -72,7 +72,7 @@ export function paceFrame(accumulator, rawDt, timeScale, limits) {
     // Also the accumulator's hard ceiling (see the spiral-of-death clamp below).
     const maxAccumulator = fixedDt * maxSubSteps;
     // Clamp large frame gaps (a slow frame, a debugger pause) BEFORE scaling by
-    // timeScale — unchanged from the pre-WO-P13 loop.
+    // timeScale.
     const displayDt = Math.min(rawDt, maxAccumulator) * timeScale;
     let next = accumulator + displayDt;
     // Spiral-of-death guard: bound the accumulator regardless of timeScale or

package/dist/core/game-loop.d.ts

@@ -1,9 +1,7 @@
 import type { GameLoopConfig, GameLoopLiveness } from './types';
 /**
  * Fixed-timestep game loop with accumulator pattern — SIM at a fixed rate,
- * PRESENTATION at the display's rate (WO-P13, `docs/WORK.md` §2 P13, which
- * flipped the former D1 "render is fixed-rate too" decision this comment used
- * to state).
+ * PRESENTATION at the display's rate.
  *
  * Per real (rAF) frame:
  *

package/dist/core/game-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"game-loop.d.ts","sourceRoot":"","sources":["../../src/core/game-loop.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAQhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc;;;;IAuIjD;;;;;;;;;;;;OAYG;uBACa,gBAAgB;eASX,MAAM;IAe3B;;;;;;;OAOG;;EAKN"}
+{"version":3,"file":"game-loop.d.ts","sourceRoot":"","sources":["../../src/core/game-loop.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAQhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc;;;;IAuIjD;;;;;;;;;;;;OAYG;uBACa,gBAAgB;eASX,MAAM;IAe3B;;;;;;;OAOG;;EAKN"}

package/dist/core/game-loop.js

@@ -6,9 +6,7 @@ import { clampTimeScale, paceFrame, TIME_SCALE_RANGE } from './frame-pacing';
 const LOOP_STARVATION_MS = 1_000;
 /**
  * Fixed-timestep game loop with accumulator pattern — SIM at a fixed rate,
- * PRESENTATION at the display's rate (WO-P13, `docs/WORK.md` §2 P13, which
- * flipped the former D1 "render is fixed-rate too" decision this comment used
- * to state).
+ * PRESENTATION at the display's rate.
  *
  * Per real (rAF) frame:
  *

package/dist/core/seeded-random.d.ts

@@ -36,7 +36,7 @@ export declare const GAMEPLAY_STREAM = "gameplay";
  *  `determinism.seededRandom` is declared, per T4.1's "no dead field" rule). */
 export declare const DEFAULT_SEEDED_RANDOM_SEED = 2654435769;
 /**
- * The `ctx.random` surface (`GameContext.random`, `runtime/types.ts`).
+ * A game-scoped random surface.
  * Callable (draws from the `'gameplay'` stream), plus:
  * - `stream(name)` — an independent named generator, `[0, 1)` floats, same
  *   call signature as `Math.random`/the bare `SeededRandom` call itself.

package/dist/core/sim-clock.d.ts

@@ -93,10 +93,9 @@
  * controller cancels everything a `setup()` scheduled:
  *
  * ```ts
- * export async function setup(ctx: GameContext): Promise<GameCleanup> {
- *   const ac = new AbortController();
- *   ctx.clock.after(3, () => spawnWave(), { signal: ac.signal });
- *   return { dispose: () => ac.abort() }; // cancels timers AND listeners
+ * const ac = new AbortController();
+ * clock.after(3, () => spawnWave(), { signal: ac.signal });
+ * // on dispose: ac.abort() — cancels timers AND listeners
  * }
  * ```
  *
@@ -105,8 +104,20 @@
  *
  * ## Deliberately absent
  *
- *  - **No `every`/`repeat`/interval.** Nothing needs one, and `after`
- *    re-arming itself is three lines the game owns.
+ *  - **No `every`/`repeat`/interval — that is `core/countdown-timer.ts`.**
+ *    This header used to say an `after` re-arming itself was "three lines the
+ *    game owns"; it is three lines that DRIFT, because re-arming schedules the
+ *    next fire from the moment the callback ran, so every long frame
+ *    permanently lengthens the interval. A repeating interval needs
+ *    overshoot carry and multi-fire on a big step to keep its event count
+ *    right, and it is stepped by its owner rather than by the clock. Both
+ *    belong to a countdown object, not to a sim-time one-shot.
+ *  - **No end-of-frame command queue — that is
+ *    `core/deferred-commands.ts`.** `after(0, fn)` looks like one (the flush
+ *    below does run at the tail of the frame that scheduled it) and is not:
+ *    it holds the work forever across a pause, it has no subject identity, and
+ *    a command it schedules during a flush waits a whole extra frame. See that
+ *    module's header for all three.
  *  - **No fiber kernel, no coroutine emulation, no `task.spawn`.** Calling an
  *    `async function` *is* `task.spawn` — the language already has it.
  *  - **No wall clock.** This module reads no system timer and creates no
@@ -152,7 +163,7 @@ export interface SimClock {
 /**
  * The runtime-facing half — NOT for game code. Split off the public
  * {@link SimClock} the same way `runtime/game.ts` splits `GameInternal` off
- * `Game`: `GameContext.clock` is typed as `SimClock`, so game code cannot
+ * `Game`: game code only ever sees the public `SimClock`, so it cannot
  * reach `flush`/`dispose`.
  */
 export interface SimClockInternal extends SimClock {
@@ -193,7 +204,7 @@ export declare function registerSimClock(owner: object, clock: SimClockInternal)
  *  Returns the INTERNAL view because this registry is engine-only — but a
  *  caller that RESOLVES a clock here is not its owner and must not call
  *  `dispose()` on it (module header, ownership). Game code never reaches it at
- *  all: `GameContext.clock` is typed as the public {@link SimClock}, which has
+ *  all: it only ever sees the public {@link SimClock}, which has
  *  neither `flush` nor `dispose`, the same way `Game` hides `GameInternal`. */
 export declare function getSimClock(owner: object): SimClockInternal | null;
 //# sourceMappingURL=sim-clock.d.ts.map

package/dist/core/sim-clock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sim-clock.d.ts","sourceRoot":"","sources":["../../src/core/sim-clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiHG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAGpC,sFAAsF;AACtF,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AAED,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,wEAAwE;IACxE,GAAG,IAAI,MAAM,CAAC;IACd,2EAA2E;IAC3E,OAAO,IAAI,MAAM,CAAC;IAClB;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,cAAc,CAAC;IAClF;;;;;OAKG;IACH,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC;CACpE;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,QAAQ;IAChD;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC;CACjD;AAyBD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,gBAAgB,CAiJzE;AAWD,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAE7E;AAED;;;;;;;;+EAQ+E;AAC/E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAElE"}
+{"version":3,"file":"sim-clock.d.ts","sourceRoot":"","sources":["../../src/core/sim-clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4HG;AAEH,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAGpC,sFAAsF;AACtF,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,MAAM,IAAI,IAAI,CAAC;CAChB;AAED,iDAAiD;AACjD,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAC3C;AAED,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,wEAAwE;IACxE,GAAG,IAAI,MAAM,CAAC;IACd,2EAA2E;IAC3E,OAAO,IAAI,MAAM,CAAC;IAClB;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,cAAc,CAAC;IAClF;;;;;OAKG;IACH,YAAY,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC;CACpE;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,QAAQ;IAChD;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,KAAK,CAAC,QAAQ,KAAK,IAAI,CAAC;CACjD;AAyBD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,gBAAgB,CAiJzE;AAWD,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI,CAE7E;AAED;;;;;;;;+EAQ+E;AAC/E,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAElE"}

package/dist/core/sim-clock.js

@@ -93,10 +93,9 @@
  * controller cancels everything a `setup()` scheduled:
  *
  * ```ts
- * export async function setup(ctx: GameContext): Promise<GameCleanup> {
- *   const ac = new AbortController();
- *   ctx.clock.after(3, () => spawnWave(), { signal: ac.signal });
- *   return { dispose: () => ac.abort() }; // cancels timers AND listeners
+ * const ac = new AbortController();
+ * clock.after(3, () => spawnWave(), { signal: ac.signal });
+ * // on dispose: ac.abort() — cancels timers AND listeners
  * }
  * ```
  *
@@ -105,8 +104,20 @@
  *
  * ## Deliberately absent
  *
- *  - **No `every`/`repeat`/interval.** Nothing needs one, and `after`
- *    re-arming itself is three lines the game owns.
+ *  - **No `every`/`repeat`/interval — that is `core/countdown-timer.ts`.**
+ *    This header used to say an `after` re-arming itself was "three lines the
+ *    game owns"; it is three lines that DRIFT, because re-arming schedules the
+ *    next fire from the moment the callback ran, so every long frame
+ *    permanently lengthens the interval. A repeating interval needs
+ *    overshoot carry and multi-fire on a big step to keep its event count
+ *    right, and it is stepped by its owner rather than by the clock. Both
+ *    belong to a countdown object, not to a sim-time one-shot.
+ *  - **No end-of-frame command queue — that is
+ *    `core/deferred-commands.ts`.** `after(0, fn)` looks like one (the flush
+ *    below does run at the tail of the frame that scheduled it) and is not:
+ *    it holds the work forever across a pause, it has no subject identity, and
+ *    a command it schedules during a flush waits a whole extra frame. See that
+ *    module's header for all three.
  *  - **No fiber kernel, no coroutine emulation, no `task.spawn`.** Calling an
  *    `async function` *is* `task.spawn` — the language already has it.
  *  - **No wall clock.** This module reads no system timer and creates no
@@ -285,7 +296,7 @@ export function registerSimClock(owner, clock) {
  *  Returns the INTERNAL view because this registry is engine-only — but a
  *  caller that RESOLVES a clock here is not its owner and must not call
  *  `dispose()` on it (module header, ownership). Game code never reaches it at
- *  all: `GameContext.clock` is typed as the public {@link SimClock}, which has
+ *  all: it only ever sees the public {@link SimClock}, which has
  *  neither `flush` nor `dispose`, the same way `Game` hides `GameInternal`. */
 export function getSimClock(owner) {
     return clockByOwner.get(owner) ?? null;

package/dist/core/types.d.ts

@@ -56,9 +56,7 @@ export interface GameLoopConfig {
      */
     update: (dt: number) => void;
     /**
-     * Called EXACTLY ONCE per real (rAF) frame — the PRESENTATION half
-     * (WO-P13, `docs/WORK.md` §2 P13; this is the callback whose absence the
-     * former D1 decision recorded).
+     * Called EXACTLY ONCE per real (rAF) frame — the PRESENTATION half.
      *
      * - `alpha` — `accumulator / fixedDt` after this frame's substeps were
      *   consumed, in `[0, 1]`: how far presentation sits past the last

package/dist/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;CASd,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAE7E,+BAA+B;AAC/B,eAAO,MAAM,WAAW,EAAE,eAAe,EASxC,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,QAAQ,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACvE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACtE;AAED,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,KAAK,EAAE,eAAe,CAAC;IACvB,4EAA4E;IAC5E,IAAI,CAAC,IAAI,IAAI,CAAC;IACd,uBAAuB;IACvB,MAAM,EAAE,QAAQ,CAAC;IACjB,8DAA8D;IAC9D,OAAO,CAAC,IAAI,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,WAAW;;;;;;;;;CASd,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,OAAO,WAAW,CAAC,CAAC;AAE7E,+BAA+B;AAC/B,eAAO,MAAM,WAAW,EAAE,eAAe,EASxC,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,QAAQ,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACvE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACtE;AAED,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,KAAK,EAAE,eAAe,CAAC;IACvB,4EAA4E;IAC5E,IAAI,CAAC,IAAI,IAAI,CAAC;IACd,uBAAuB;IACvB,MAAM,EAAE,QAAQ,CAAC;IACjB,8DAA8D;IAC9D,OAAO,CAAC,IAAI,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;OAUG;IACH,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACpD;;;;;;;;;;OAUG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,CAAC"}

package/dist/defaults.d.ts

@@ -1,20 +1,12 @@
 /**
  * Single source of truth for default values the engine's factories read.
  *
- * WO-8 deleted SEVEN groups — `transform`, `entity`, `audio`, `shadow`,
- * `animation`, `fog`, `environment` — because every one of their readers was a
- * `.vscn.json` consumer (`entity-factory.ts`, `scene-loader.ts`,
- * `scene-sync.ts`, `scene-serializer.ts`, the per-section inspectors) and
- * `defaults-source-scan.test.ts` reported them with ZERO `DEFAULTS.<group>`
- * readers anywhere in engine/editor src or tests. That guard offers two remedies
- * — wire the group to the factory that reads it, or delete it if truly unused —
- * and there is no surviving factory to wire these to: `transform` restated
- * THREE's own Object3D constructor values, `entity.locked`/ `pivot` were
- * descriptor-only fields, and `fog`/`environment.envMapIntensity`/ `shadow` were
- * the `.vscn` `environment` block that `render-env.ts` explicitly did NOT carry
- * forward. Keeping them would have been exactly the dead documentation T1.13
- * created this guard to prevent.
- *
+ * A group belongs here only while a FACTORY reads it. A default with no
+ * reader is dead documentation: it looks authoritative, nothing consults it,
+ * and it drifts from the value the code actually uses. Restating a library's
+ * own constructor values (THREE's `Object3D` transform, say) is the same
+ * mistake in a different shape — the library is already the source of truth.
+ * So when a factory goes, its group goes with it.
  */
 export declare const DEFAULTS: {
     readonly material: {

package/dist/defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gDAkB0B,CAAC,MAAM,EAAE,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;kCA6BjB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6E5D,CAAC"}
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gDAkB0B,CAAC,MAAM,EAAE,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;kCA6BjB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6E5D,CAAC"}