@vgai/engine 0.5.21 → 0.5.23

package/dist/canvas-react/index.js

@@ -15,27 +15,20 @@
  * or the Pixi reconciler.
  *
  * Surface:
- *  - `createPixiReactAdapter({ id, content })` — mount a `@pixi/react` tree as
- *    a first-party `surface: "canvas"` root under the host's gated loop.
  *  - `pixiReactRootFactory` / `resolveCanvasEntryAdapter` — what a canvas entry
- *    module MEANS: a default-exported component (or an explicit `adapter`).
+ *    module MEANS: a default-exported component, mounted as a first-party
+ *    `surface: "canvas"` root under the host's gated loop. The world's vgai
+ *    surface is its entry module's static exports
+ *    (`export { debug, systems } from './commands'`), connected by the host at
+ *    mount.
  *  - `PixiPrimitive` / `adoptNow` — the canvas surface's `<primitive object={…}>`:
  *    render a container the game already owns, and place a spawn in the
  *    display tree ahead of the commit that renders it.
- *  - `useGameContext()` — this root's `CanvasGameContext` (`input`, `debug`,
- *    `random`, `clock`, `game`, `roots`) from inside any component in the tree.
- *    Behavior in a canvas world is components + hooks, never a class under a
- *    string key.
- *  - `EngineBridge` / `EngineBridgeValue` — the context contract, exported for
- *    adopters building their own bridge.
  *
  * The Pixi runtime itself is NOT re-exported here. A component reaches the live
  * `Application` (and therefore `stage`, `renderer`, `ticker`) with
  * `@pixi/react`'s own `useApplication()`, ticks with its `useTick()`, and loads
  * assets with Pixi's own `Assets` — the library's API, not a second one.
  */
-export { EngineBridge, useGameContext } from './engine-bridge';
 export { adoptNow, PixiPrimitive } from './pixi-primitive';
-export { createPixiReactAdapter, } from './pixi-react-adapter';
 export { pixiReactRootFactory, resolveCanvasEntryAdapter } from './pixi-react-root-factory';
-export { createCanvasRootContext, DEFAULT_INPUT_MAP_PATH, } from './world-context';

package/dist/canvas-react/pixi-react-root-factory.d.ts

@@ -1,8 +1,6 @@
 /**
  * `pixiReactRootFactory` — mount a `canvas` root whose entry module
- * DEFAULT-EXPORTS a React component.
- *
- * A model asked for a 2D world writes:
+ * DEFAULT-EXPORTS a React component. This is the ONE first-party canvas mount:
  *
  * ```tsx
  * export default function World() {
@@ -10,11 +8,13 @@
  * }
  * ```
  *
- * It does NOT write `export const adapter = createPixiReactAdapter({ id, content })`.
- * That export is vgai ceremony wrapped around a component the author already
- * wrote. The `three` and `dom` roots both settled this convention — read
- * `entryModule.default` and wrap it — and this is the same contract for canvas
- * roots, so all three surfaces answer "what do I export?" the same way.
+ * The world is an ordinary `@pixi/react` app. Everything vgai-shaped stays at
+ * the entry module's STATIC surface (`export { debug, systems } from
+ * './commands'`) and on the host's side of the seam; no vgai runtime context
+ * ever enters the React tree. The host advances Pixi's real (never-started)
+ * ticker on GAME time, wires the game-scoped input seams from outside
+ * (`../runtime/game-input-seams.ts`), and installs `WorldProvider` off the
+ * Game handle so the lib-legal react doors resolve.
  *
  * ## Why this is NOT in `mount-game.ts`
  *
@@ -24,12 +24,28 @@
  * the opt-in module that owns those dependencies, so the factory lives here and
  * a project opts in with `registerAdapter('canvas', pixiReactRootFactory)`.
  *
- * ## Compatibility
+ * ## The loop contract
+ *
+ * `Application` is initialized with `autoStart: false` and `sharedTicker:
+ * false`, so it owns a native Pixi ticker that is NEVER started and therefore
+ * never requests an animation frame. `mounted.update(dt)` is the only thing
+ * that advances that ticker, and it feeds GAME time, not wall time — which is
+ * what makes the world freeze exactly when the host freezes it, and what makes
+ * `game.waitSimTime` work in a hidden tab (a hidden tab has no rAF; the engine
+ * loop's own catch-up still calls `update`, and Pixi has no independent clock
+ * to disagree with it).
  *
- * An `adapter` export still wins, so a game needing full control over its own
- * `RootAdapter<'canvas'>` keeps it.
+ * ## Component catalogue
+ *
+ * `@pixi/react` resolves `<pixiSprite>` etc. through a module-global catalogue
+ * that starts EMPTY — the first intrinsic in an un-extended tree throws
+ * "X is not part of the PIXI namespace! Did you forget to extend?". This
+ * module extends it with the whole `pixi.js` namespace once per mount
+ * (idempotent `Object.assign`). A world that adds its own classes
+ * (`@pixi/tilemap`, a custom `Container` subclass) calls `extend`/`useExtend`
+ * itself.
  */
-import type { RootAdapter } from '../adapter/root-adapter';
+import type { RootAdapter } from '../adapter';
 import type { AdapterSurfaceFactory } from '../runtime/mount-game';
 /**
  * What a canvas entry module MEANS, in one place.
@@ -37,20 +53,17 @@ import type { AdapterSurfaceFactory } from '../runtime/mount-game';
  * Two callers need this answer and must never disagree about it: the runtime
  * mount ({@link pixiReactRootFactory}, below) and the EDITOR, which resolves
  * the same entry for play mode and for the design-time layer. When only one
- * side knows about the default-export shape, a world plays fine and shows
- * "(no scene loaded)" in edit mode — the exact split the three lane already
- * paid for.
+ * side knows the shape, a world plays fine and shows "(no scene loaded)" in
+ * edit mode.
  *
- * Returns `null` when the module is neither shape — the callers differ on what
- * to do about that (the factory throws; the editor reports a mount failure on
- * that root's boundary node and leaves every sibling working).
+ * Returns `null` when the module has no default-exported component — the
+ * callers differ on what to do about that (the factory throws; the editor
+ * reports a mount failure on that root's boundary node and leaves every
+ * sibling working).
  */
 export declare function resolveCanvasEntryAdapter(entryModule: unknown, rootId: string): RootAdapter<'canvas'> | null;
 /**
  * Register with `registerAdapter('canvas', pixiReactRootFactory)`.
- *
- * Resolution order mirrors the three lane's (explicit adapter wins) and then
- * accepts the default-exported component.
  */
 export declare const pixiReactRootFactory: AdapterSurfaceFactory;
 //# sourceMappingURL=pixi-react-root-factory.d.ts.map

package/dist/canvas-react/pixi-react-root-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pixi-react-root-factory.d.ts","sourceRoot":"","sources":["../../src/canvas-react/pixi-react-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAUnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,OAAO,EACpB,MAAM,EAAE,MAAM,GACb,WAAW,CAAC,QAAQ,CAAC,GAAG,IAAI,CAc9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,qBAQlC,CAAC"}
+{"version":3,"file":"pixi-react-root-factory.d.ts","sourceRoot":"","sources":["../../src/canvas-react/pixi-react-root-factory.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAMH,OAAO,KAAK,EAAsC,WAAW,EAAE,MAAM,YAAY,CAAC;AAKlF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAuQnE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,OAAO,EACpB,MAAM,EAAE,MAAM,GACb,WAAW,CAAC,QAAQ,CAAC,GAAG,IAAI,CAI9B;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,qBAOlC,CAAC"}

package/dist/canvas-react/pixi-react-root-factory.js

@@ -1,8 +1,6 @@
 /**
  * `pixiReactRootFactory` — mount a `canvas` root whose entry module
- * DEFAULT-EXPORTS a React component.
- *
- * A model asked for a 2D world writes:
+ * DEFAULT-EXPORTS a React component. This is the ONE first-party canvas mount:
  *
  * ```tsx
  * export default function World() {
@@ -10,11 +8,13 @@
  * }
  * ```
  *
- * It does NOT write `export const adapter = createPixiReactAdapter({ id, content })`.
- * That export is vgai ceremony wrapped around a component the author already
- * wrote. The `three` and `dom` roots both settled this convention — read
- * `entryModule.default` and wrap it — and this is the same contract for canvas
- * roots, so all three surfaces answer "what do I export?" the same way.
+ * The world is an ordinary `@pixi/react` app. Everything vgai-shaped stays at
+ * the entry module's STATIC surface (`export { debug, systems } from
+ * './commands'`) and on the host's side of the seam; no vgai runtime context
+ * ever enters the React tree. The host advances Pixi's real (never-started)
+ * ticker on GAME time, wires the game-scoped input seams from outside
+ * (`../runtime/game-input-seams.ts`), and installs `WorldProvider` off the
+ * Game handle so the lib-legal react doors resolve.
  *
  * ## Why this is NOT in `mount-game.ts`
  *
@@ -24,54 +24,292 @@
  * the opt-in module that owns those dependencies, so the factory lives here and
  * a project opts in with `registerAdapter('canvas', pixiReactRootFactory)`.
  *
- * ## Compatibility
+ * ## The loop contract
+ *
+ * `Application` is initialized with `autoStart: false` and `sharedTicker:
+ * false`, so it owns a native Pixi ticker that is NEVER started and therefore
+ * never requests an animation frame. `mounted.update(dt)` is the only thing
+ * that advances that ticker, and it feeds GAME time, not wall time — which is
+ * what makes the world freeze exactly when the host freezes it, and what makes
+ * `game.waitSimTime` work in a hidden tab (a hidden tab has no rAF; the engine
+ * loop's own catch-up still calls `update`, and Pixi has no independent clock
+ * to disagree with it).
+ *
+ * ## Component catalogue
  *
- * An `adapter` export still wins, so a game needing full control over its own
- * `RootAdapter<'canvas'>` keeps it.
+ * `@pixi/react` resolves `<pixiSprite>` etc. through a module-global catalogue
+ * that starts EMPTY — the first intrinsic in an un-extended tree throws
+ * "X is not part of the PIXI namespace! Did you forget to extend?". This
+ * module extends it with the whole `pixi.js` namespace once per mount
+ * (idempotent `Object.assign`). A world that adds its own classes
+ * (`@pixi/tilemap`, a custom `Container` subclass) calls `extend`/`useExtend`
+ * itself.
+ */
+import { createRoot, extend } from '@pixi/react';
+import * as PIXI from 'pixi.js';
+import { createElement, Fragment, useEffect, useLayoutEffect } from 'react';
+import { WorldProvider } from '../react/world-state';
+import { getDebugRegistry } from '../runtime/debug-registry';
+import { DEFAULT_INPUT_MAP_PATH, wireGameInputSeams } from '../runtime/game-input-seams';
+/** How long `mount()` waits for the tree's first commit before failing loudly
+ *  rather than hanging (and wedging every root declared after this one, since
+ *  roots mount sequentially). */
+const FIRST_COMMIT_TIMEOUT_MS = 10_000;
+/**
+ * `@pixi/react` keys its reconciler roots off the canvas element in a
+ * module-global map, and its own unmount path (which would clear that key) is
+ * not exported. So a canvas this lane has already mounted must never be handed
+ * to a second mount: `createRoot` would silently hand back the FIRST root,
+ * whose `Application` this lane already destroyed. Every host in this repo
+ * builds a fresh canvas per mount, so this only ever fires on a genuine bug —
+ * and it fires as a named error rather than as a dead world.
  */
-import { createElement } from 'react';
-import { createPixiReactAdapter } from './pixi-react-adapter';
+const MOUNTED_CANVASES = new WeakSet();
+/**
+ * Build the `RootAdapter<'canvas'>` for one default-exported Pixi world.
+ * Mounts through `@pixi/react`, gated entirely by the host's own loop and
+ * rendering into the host's own canvas — never a second canvas, never a
+ * second `requestAnimationFrame` loop.
+ */
+function canvasWorldAdapter(id, component) {
+    const content = createElement(component);
+    return {
+        id,
+        async mount(host) {
+            // THE HOST WIRES THIS GAME'S INPUT FROM OUTSIDE THE TREE — the project's
+            // declared map (conventional path, optional: a brand-new project
+            // declares no actions yet) and this root's `game.input.*` seams on the
+            // debug registry. Actions must exist before any component's first tick
+            // reads them — wait for the (never-rejecting) load before the first
+            // commit.
+            const registry = host.game ? getDebugRegistry(host.game) : null;
+            if (registry) {
+                await wireGameInputSeams(host, registry, {
+                    id,
+                    inputMapPath: DEFAULT_INPUT_MAP_PATH,
+                    optionalInputMap: true,
+                });
+            }
+            const canvas = host.canvas;
+            if (MOUNTED_CANVASES.has(canvas)) {
+                throw new Error(`canvas world "${id}": this lane has already mounted this canvas. @pixi/react keys ` +
+                    'its reconciler roots off the canvas element, so re-using one would resurrect a ' +
+                    'root whose Application is destroyed. Hand each mount a fresh canvas (every vgai ' +
+                    'host already does).');
+            }
+            MOUNTED_CANVASES.add(canvas);
+            // The catalogue is module-global and starts empty; this is idempotent.
+            extend(PIXI);
+            let resolveCommitted;
+            const committed = new Promise((resolve) => {
+                resolveCommitted = resolve;
+            });
+            let resolveEffectsReady;
+            const effectsReady = new Promise((resolve) => {
+                resolveEffectsReady = resolve;
+            });
+            let resolveUnmounted;
+            const unmounted = new Promise((resolve) => {
+                resolveUnmounted = resolve;
+            });
+            /**
+             * Signals the tree's FIRST COMMIT and its LAST. A layout effect,
+             * deliberately, and rendered as the LAST child, deliberately:
+             *
+             *  - mount: layout effects run synchronously inside the commit, before
+             *    any passive effect and before any tick can be scheduled;
+             *  - unmount: React commits deletion effects in tree order, each node
+             *    before its own children, so the LAST sibling's cleanup is the last
+             *    to run. That is what makes this a reliable "every component has
+             *    finished tearing down" signal — and it is load-bearing, because
+             *    `useTick`'s own cleanup calls `ticker.remove()`. Destroying the
+             *    Application before that cleanup lands throws inside React's commit
+             *    on every teardown of any world with a tick hook.
+             */
+            function Lifecycle() {
+                useLayoutEffect(() => {
+                    resolveCommitted();
+                    return resolveUnmounted;
+                }, []);
+                // This component is the last sibling. Reaching its passive effect
+                // means the initial tree's provider/command effects have registered,
+                // so mount() can truthfully back Play's ack.
+                useEffect(resolveEffectsReady, []);
+                return null;
+            }
+            // `WorldProvider` rides `host.game` — the React seam every dom root
+            // already has, and the only way a capability hook can reach the ONE
+            // game-scoped registry the editor/`vgai eval` read. `host.game` is
+            // genuinely absent in bare/foreign hosts, so the provider is
+            // conditional and those hooks stay the inert no-ops they already
+            // document themselves to be.
+            const game = host.game;
+            const world = createElement(Fragment, null, content, createElement(Lifecycle));
+            const element = game ? createElement(WorldProvider, { game }, world) : world;
+            const root = createRoot(canvas);
+            // The host owns size, dpr, transparency and capture cost; the loop
+            // contract owns `autoStart`/`sharedTicker`.
+            const initOptions = {
+                antialias: true,
+                width: host.width,
+                height: host.height,
+                resolution: host.dpr ?? globalThis.devicePixelRatio ?? 1,
+                autoDensity: true,
+                // Stacked ABOVE a sibling root -> clear with alpha 0 so the layer below
+                // shows through (COMPOSITION-DESIGN D5 §1).
+                backgroundAlpha: host.transparent ? 0 : 1,
+                preserveDrawingBuffer: host.preserveDrawingBuffer ?? false,
+                autoStart: false,
+                sharedTicker: false,
+            };
+            // Install the reconcile-error listener BEFORE `root.render`: Pixi hands
+            // the Application back after `init()` but React can already have thrown
+            // during that same turn. Attaching after the await loses the real error
+            // and turns it into a misleading ten-second timeout.
+            let reportReconcileFailure;
+            const reconcileFailure = new Promise((resolve) => {
+                reportReconcileFailure = resolve;
+            });
+            const onError = (event) => {
+                reportReconcileFailure(`the Pixi tree crashed before its first commit — ${event.message} ` +
+                    '(mount() fails loudly instead of hanging)');
+            };
+            globalThis.addEventListener?.('error', onError);
+            let app;
+            let timer;
+            try {
+                // `root.render` is async: it awaits `Application.init()` (which is what
+                // creates the renderer) and only then hands the tree to the reconciler.
+                // A crash inside init rejects here, which is the loud failure we want.
+                const renderedApp = await root.render(element, initOptions);
+                app = renderedApp;
+                // A reconcile-time crash (e.g. an un-extended component) surfaces as
+                // an uncaught window error and the first commit never lands. Race that
+                // exact signal against the commit and the last-resort ceiling.
+                const timeout = new Promise((resolve) => {
+                    timer = setTimeout(() => resolve(`no first commit within ${FIRST_COMMIT_TIMEOUT_MS / 1000}s ` +
+                        '(mount() fails loudly instead of hanging)'), FIRST_COMMIT_TIMEOUT_MS);
+                });
+                const failure = await Promise.race([
+                    Promise.all([committed, effectsReady]).then(() => null),
+                    reconcileFailure,
+                    timeout,
+                ]);
+                if (failure !== null) {
+                    throw new Error(`canvas world "${id}": ${failure}`);
+                }
+            }
+            catch (error) {
+                try {
+                    app?.destroy(false, { children: true });
+                }
+                catch {
+                    /* the world never fully came up; teardown failure must not mask why */
+                }
+                throw error;
+            }
+            finally {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                globalThis.removeEventListener?.('error', onError);
+            }
+            // `app` is assigned before the first-commit race. Reaching here proves
+            // both initialization and commit succeeded, so narrow once for the live
+            // mounted-root methods below.
+            if (app === undefined) {
+                throw new Error(`canvas world "${id}": initialized without an Application`);
+            }
+            const mountedApp = app;
+            // Pin the ticker's clock to GAME time. `Ticker.lastTime` starts at -1, so
+            // without this the first `update()` would report a 1ms phantom delta on
+            // top of the real one. From here every `deltaMS` a `useTick` callback
+            // sees is exactly the `dt` the host handed us — no wall clock anywhere,
+            // which is what makes a paused world's resume frame ordinary rather than
+            // one giant catch-up step.
+            mountedApp.ticker.lastTime = 0;
+            let elapsedMs = 0;
+            let disposed = false;
+            // Adapter surface: the host's shared debug registry. The game's own
+            // capabilities arrive as the entry module's declared `systems`.
+            const systemAdapters = registry ? { debug: registry.adapter } : {};
+            const disposeComplete = unmounted.then(() => {
+                mountedApp.destroy(false, { children: true });
+            });
+            return {
+                kind: 'canvas',
+                // The reconciler's real root container — the same `PIXI.Container`
+                // `RootInstance.pixiStage()` hands the editor.
+                stage: mountedApp.stage,
+                drivesOwnLoop: false,
+                systems: systemAdapters,
+                disposeComplete,
+                update(dt) {
+                    if (disposed)
+                        return;
+                    elapsedMs += dt * 1000;
+                    // The real Pixi ticker remains the one scheduler `useTick` observes;
+                    // the host only gates/advances it.
+                    mountedApp.ticker.update(elapsedMs);
+                },
+                resize(width, height) {
+                    if (disposed)
+                        return;
+                    // `autoDensity: true` makes Pixi re-stamp `canvas.style.width`/
+                    // `.height` from this call, so the on-screen box follows the logical
+                    // size with no explicit CSS write from the host.
+                    mountedApp.renderer.resize(width, height);
+                },
+                dispose() {
+                    if (disposed)
+                        return;
+                    disposed = true;
+                    // Pixi's EventSystem owns document.pointermove + window.pointerup
+                    // (and its event ticker's global listener). React's deletion commit
+                    // is asynchronous, so waiting to destroy the Application leaves
+                    // those listeners live when the host audits this game realm. Detach
+                    // the input target synchronously; the later Application.destroy()
+                    // repeats this idempotently after every useTick cleanup has landed.
+                    mountedApp.renderer.events.setTargetElement(null);
+                    // Rendering `null` children is the only unmount path `@pixi/react`
+                    // exposes publicly (its `unmountRoot` helper is internal), and React
+                    // commits that deletion on its own schedule — NOT synchronously. So
+                    // the Application is destroyed on the `Lifecycle` cleanup signal
+                    // instead of inline: `useTick`'s cleanup calls `ticker.remove()`, and
+                    // a ticker destroyed before it lands throws inside React's commit.
+                    // `removeView` stays false — the canvas belongs to the HOST.
+                    void root.render(null, initOptions);
+                },
+            };
+        },
+    };
+}
 /**
  * What a canvas entry module MEANS, in one place.
  *
  * Two callers need this answer and must never disagree about it: the runtime
  * mount ({@link pixiReactRootFactory}, below) and the EDITOR, which resolves
  * the same entry for play mode and for the design-time layer. When only one
- * side knows about the default-export shape, a world plays fine and shows
- * "(no scene loaded)" in edit mode — the exact split the three lane already
- * paid for.
+ * side knows the shape, a world plays fine and shows "(no scene loaded)" in
+ * edit mode.
  *
- * Returns `null` when the module is neither shape — the callers differ on what
- * to do about that (the factory throws; the editor reports a mount failure on
- * that root's boundary node and leaves every sibling working).
+ * Returns `null` when the module has no default-exported component — the
+ * callers differ on what to do about that (the factory throws; the editor
+ * reports a mount failure on that root's boundary node and leaves every
+ * sibling working).
  */
 export function resolveCanvasEntryAdapter(entryModule, rootId) {
     const mod = entryModule;
-    if (mod?.adapter)
-        return mod.adapter;
-    if (typeof mod?.default === 'function') {
-        return createPixiReactAdapter({
-            id: rootId,
-            content: createElement(mod.default),
-            // The supported Canvas portfolio still consumes the compatibility
-            // context. Removing it belongs to the tracked component-root migration;
-            // disabling it here first made every current default-exported game fail
-            // to mount before that migration had happened.
-        });
-    }
+    if (typeof mod?.default === 'function')
+        return canvasWorldAdapter(rootId, mod.default);
     return null;
 }
 /**
  * Register with `registerAdapter('canvas', pixiReactRootFactory)`.
- *
- * Resolution order mirrors the three lane's (explicit adapter wins) and then
- * accepts the default-exported component.
  */
 export const pixiReactRootFactory = (root, ctx) => {
     const adapter = resolveCanvasEntryAdapter(ctx.entryModule, root.id);
     if (adapter)
         return { kind: 'canvas', adapter };
     throw new Error(`pixiReactRootFactory: entry module "${root.entry ?? '(none)'}" for root "${root.id}" must ` +
-        'default-export a React component (`export default function World() { … }`) — or export ' +
-        'an `adapter` for full control.');
+        'default-export a React component (`export default function World() { … }`).');
 };

package/dist/core/countdown-timer.d.ts

@@ -0,0 +1,118 @@
+/**
+ * `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.
+ */
+/** A restartable countdown. Build one with {@link createCountdown}. */
+export interface Countdown {
+    /** Seconds it counts from. Reflects the last {@link Countdown.start} that
+     *  passed a duration. */
+    readonly duration: number;
+    /** Does it re-arm itself after firing, or stop? */
+    readonly repeats: boolean;
+    /** Seconds left, or 0 when it is not running. */
+    readonly remaining: number;
+    /** Is it counting? */
+    readonly running: boolean;
+    /**
+     * Start, or RESTART a running countdown from the top. Passing `duration`
+     * overwrites {@link Countdown.duration} for this and every later start.
+     *
+     * @throws RangeError if `duration` is not a finite positive number of
+     * seconds. A non-positive period cannot fire and reads as a hung game
+     * rather than a misconfigured one, so it refuses at the call site.
+     */
+    start(duration?: number): void;
+    /** Stop counting. Invokes nothing. */
+    stop(): void;
+    /**
+     * Advance by `dt` SECONDS, invoking `onElapsed` once per completed period —
+     * possibly several times in one call. See the module header's frame-hitch
+     * contract.
+     */
+    advance(dt: number): void;
+}
+/** What {@link createCountdown} needs. */
+export interface CountdownOptions {
+    /** Seconds to count from. Default 1. */
+    readonly duration?: number;
+    /** Re-arm after firing instead of stopping. Default `false` (one-shot). */
+    readonly repeats?: boolean;
+    /** Begin counting immediately instead of waiting for a `start()`. Default
+     *  `false`. */
+    readonly autostart?: boolean;
+    /** Invoked inline, once per completed period. */
+    readonly onElapsed: () => void;
+}
+/**
+ * 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 declare function createCountdown(options: CountdownOptions): Countdown;
+//# sourceMappingURL=countdown-timer.d.ts.map

package/dist/core/countdown-timer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"countdown-timer.d.ts","sourceRoot":"","sources":["../../src/core/countdown-timer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAEH,uEAAuE;AACvE,MAAM,WAAW,SAAS;IACxB;6BACyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sBAAsB;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,sCAAsC;IACtC,IAAI,IAAI,IAAI,CAAC;IACb;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,0CAA0C;AAC1C,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B;mBACe;IACf,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;CAChC;AAUD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,SAAS,CA4DpE"}