@vgai/engine 0.5.4 → 0.5.6

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

@@ -0,0 +1,73 @@
+/**
+ * `pixiReactRootFactory` — mount a `canvas` root whose entry module
+ * DEFAULT-EXPORTS a React component.
+ *
+ * A model asked for a 2D world writes:
+ *
+ * ```tsx
+ * export default function World() {
+ *   return <pixiContainer><pixiSprite texture={Texture.WHITE} /></pixiContainer>;
+ * }
+ * ```
+ *
+ * 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.
+ *
+ * ## Why this is NOT in `mount-game.ts`
+ *
+ * The kind registry beside `mount-game.ts` is deliberately dependency-free:
+ * registering a canvas factory there would make `pixi.js` + `@pixi/react`
+ * unconditional for every game, including three-only ones. `canvas-react` is
+ * the opt-in module that owns those dependencies, so the factory lives here and
+ * a project opts in with `registerAdapter('canvas', pixiReactRootFactory)`.
+ *
+ * ## Compatibility
+ *
+ * An `adapter` export still wins, so a game needing full control over its own
+ * `RootAdapter<'canvas'>` keeps it.
+ */
+import { createElement } from 'react';
+import { createPixiReactAdapter } from './pixi-react-adapter';
+/**
+ * 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.
+ *
+ * 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).
+ */
+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),
+        });
+    }
+    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.');
+};

package/dist/canvas-react/world-context.d.ts

@@ -0,0 +1,88 @@
+/**
+ * `createCanvasRootContext` — the ENGINE runtime a canvas world owns, split out
+ * of `./pixi-react-adapter.tsx` so it stays react-free and headlessly
+ * unit-testable (`test/canvas-react-context-parity.test.tsx`).
+ *
+ * This is the canvas surface's answer to the same question
+ * `world3d-react/world-context.ts` answers for three: what does a component
+ * inside the world tree reach when it asks the engine for something?
+ *
+ *  1. **`ctx.debug` / `ctx.random` / `ctx.game` / `ctx.roots` are wired** from
+ *     the ONE game-scoped registry (`getDebugRegistry(host.game)`), so a
+ *     component's effect can `ctx.debug.registerStateProvider(...)` and be
+ *     visible to `vgai eval`/the editor's debug panels.
+ *  2. **`ctx.input` is the game-owned `InputManager`** (`host.game.input` — the
+ *     same instance every sibling root shares), and this module registers the
+ *     per-world debug-registry seams (`setVirtualInputTarget`/
+ *     `setInputActionsSource`/`setInputTraceSource`) that make `game.input.*`
+ *     (the bot-input doctrine) resolve instead of throwing
+ *     `DEBUG_INPUT_UNAVAILABLE`. The project's input map loads through
+ *     `Game.loadInputMap` (the game-owned, load-once path every root shares).
+ *     A missing/unparseable map degrades LOUDLY without failing the mount — a
+ *     canvas world with no declared actions is legal.
+ *  3. **Absent subsystems fail loudly at the ctx surface.** A canvas world
+ *     builds no THREE scene/camera, no Rapier world, no composer, no first-party
+ *     audio/particles/debug-draw, and is handed no `AssetCache` (the canvas host
+ *     context carries none — see `adapter/host-context.ts`). Reading those
+ *     `ctx` fields yields a throwing getter naming the limitation and the
+ *     sanctioned alternative, never a silent `undefined`.
+ *
+ * The Pixi handles themselves are deliberately NOT re-exposed here: a component
+ * reaches the live `Application` (and therefore `app.stage`, `app.renderer`,
+ * `app.ticker`) through `@pixi/react`'s own `useApplication()`, and its assets
+ * through Pixi's own `Assets`. Re-publishing them on `ctx` would be a wrapper
+ * standing between the author and the library.
+ */
+import type { Application } from 'pixi.js';
+import type { CanvasHostContext } from '../adapter';
+import type { SystemAdapters } from '../adapter/system-adapter';
+import { createSystemRunner } from '../core/system-runner';
+import type { GameContext } from '../runtime/types';
+/** The conventional input-map location every scaffolded project ships. Shared
+ *  verbatim with the three lane — a project has ONE input map, whatever surface
+ *  reads it. */
+export declare const DEFAULT_INPUT_MAP_PATH = "/inputmaps/default.inputmap.json";
+export interface CanvasRootContextOptions {
+    /** World id — provenance for every debug-registry registration (matches the
+     *  manifest root id). */
+    readonly id: string;
+    /**
+     * Input map to load through `Game.loadInputMap` (game-owned, load-once —
+     * several roots asking for the SAME path share one load; competing paths
+     * throw there). Defaults to {@link DEFAULT_INPUT_MAP_PATH}. Pass `null` to
+     * skip loading (a world with no actions). Ignored when no `host.game` is
+     * present.
+     */
+    readonly inputMapPath?: string | null | undefined;
+}
+/** What {@link createCanvasRootContext} returns — the engine runtime one canvas
+ *  world owns, plus the wiring hooks the adapter's `mount()` drives. */
+export interface CanvasRootRuntime {
+    /** The (partial, loud-on-absence) `GameContext` this world's components read
+     *  through `useGameContext`. See this module's header for what is present. */
+    readonly ctx: GameContext;
+    /** The world-local phase runner `mount().update(dt)` ticks. */
+    readonly systems: ReturnType<typeof createSystemRunner>;
+    /** The mounted world's `SystemAdapters` bag (`mounted.systems`) —
+     *  `ctx.registerSystemAdapter` writes into it; `debug` is pre-seeded. */
+    readonly systemAdapters: SystemAdapters;
+    /** Resolves once the input map load settles (immediately when skipped).
+     *  Never rejects — a failed load reports loudly and resolves. */
+    readonly inputMapReady: Promise<void>;
+    /** Backfill the live `Application` once `@pixi/react` has initialized it —
+     *  before any tick can run. Read back via {@link CanvasRootRuntime.app}. */
+    setApplication(app: Application): void;
+    /** The live `Application`, or `null` before the first commit resolves it. */
+    readonly app: Application | null;
+    /** Strip this world's debug registrations (scoped, so sibling roots and
+     *  react-door registrations are untouched when a Game hosts this world) and
+     *  dispose a clock this mount created. */
+    dispose(): void;
+}
+/**
+ * Build the engine runtime for one canvas world from a `CanvasHostContext`.
+ * React-free on purpose: everything here is plain engine wiring the adapter
+ * threads into the `@pixi/react` tree through `EngineBridge`.
+ */
+export declare function createCanvasRootContext(host: CanvasHostContext, options: CanvasRootContextOptions): CanvasRootRuntime;
+//# sourceMappingURL=world-context.d.ts.map

package/dist/canvas-react/world-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"world-context.d.ts","sourceRoot":"","sources":["../../src/canvas-react/world-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAOhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAM3D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;gBAEgB;AAChB,eAAO,MAAM,sBAAsB,qCAAqC,CAAC;AAEzE,MAAM,WAAW,wBAAwB;IACvC;6BACyB;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CACnD;AAED;wEACwE;AACxE,MAAM,WAAW,iBAAiB;IAChC;kFAC8E;IAC9E,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;IACxD;6EACyE;IACzE,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC;qEACiE;IACjE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;gFAC4E;IAC5E,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IACvC,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC;;8CAE0C;IAC1C,OAAO,IAAI,IAAI,CAAC;CACjB;AA4BD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,wBAAwB,GAChC,iBAAiB,CAoMnB"}

package/dist/canvas-react/world-context.js

@@ -0,0 +1,212 @@
+/**
+ * `createCanvasRootContext` — the ENGINE runtime a canvas world owns, split out
+ * of `./pixi-react-adapter.tsx` so it stays react-free and headlessly
+ * unit-testable (`test/canvas-react-context-parity.test.tsx`).
+ *
+ * This is the canvas surface's answer to the same question
+ * `world3d-react/world-context.ts` answers for three: what does a component
+ * inside the world tree reach when it asks the engine for something?
+ *
+ *  1. **`ctx.debug` / `ctx.random` / `ctx.game` / `ctx.roots` are wired** from
+ *     the ONE game-scoped registry (`getDebugRegistry(host.game)`), so a
+ *     component's effect can `ctx.debug.registerStateProvider(...)` and be
+ *     visible to `vgai eval`/the editor's debug panels.
+ *  2. **`ctx.input` is the game-owned `InputManager`** (`host.game.input` — the
+ *     same instance every sibling root shares), and this module registers the
+ *     per-world debug-registry seams (`setVirtualInputTarget`/
+ *     `setInputActionsSource`/`setInputTraceSource`) that make `game.input.*`
+ *     (the bot-input doctrine) resolve instead of throwing
+ *     `DEBUG_INPUT_UNAVAILABLE`. The project's input map loads through
+ *     `Game.loadInputMap` (the game-owned, load-once path every root shares).
+ *     A missing/unparseable map degrades LOUDLY without failing the mount — a
+ *     canvas world with no declared actions is legal.
+ *  3. **Absent subsystems fail loudly at the ctx surface.** A canvas world
+ *     builds no THREE scene/camera, no Rapier world, no composer, no first-party
+ *     audio/particles/debug-draw, and is handed no `AssetCache` (the canvas host
+ *     context carries none — see `adapter/host-context.ts`). Reading those
+ *     `ctx` fields yields a throwing getter naming the limitation and the
+ *     sanctioned alternative, never a silent `undefined`.
+ *
+ * The Pixi handles themselves are deliberately NOT re-exposed here: a component
+ * reaches the live `Application` (and therefore `app.stage`, `app.renderer`,
+ * `app.ticker`) through `@pixi/react`'s own `useApplication()`, and its assets
+ * through Pixi's own `Assets`. Re-publishing them on `ctx` would be a wrapper
+ * standing between the author and the library.
+ */
+import { createSeededRandom, DEFAULT_SEEDED_RANDOM_SEED, getSeededRandom, } from '../core/seeded-random';
+import { createSimClock, getSimClock } from '../core/sim-clock';
+import { createSystemRunner } from '../core/system-runner';
+import { createDebugRegistry, getDebugRegistry, } from '../runtime/debug-registry';
+/** The conventional input-map location every scaffolded project ships. Shared
+ *  verbatim with the three lane — a project has ONE input map, whatever surface
+ *  reads it. */
+export const DEFAULT_INPUT_MAP_PATH = '/inputmaps/default.inputmap.json';
+/** Install a throwing getter for a `GameContext` field this world genuinely
+ *  does not build — a component reaching for it fails LOUDLY at its own call
+ *  site, naming the limitation, instead of reading `undefined` and breaking
+ *  somewhere downstream. Non-enumerable so spreads/serialization of the ctx
+ *  never trip it. */
+function defineAbsentCtxField(target, worldId, key, why) {
+    Object.defineProperty(target, key, {
+        configurable: true,
+        enumerable: false,
+        get() {
+            throw new Error(`canvas world "${worldId}": ctx.${key} is not available — ${why} ` +
+                '(A canvas world ctx provides: input, systems, clock, debug, random, game, roots, ' +
+                "registerSystemAdapter. The Pixi runtime itself comes from @pixi/react's " +
+                'useApplication() — app.stage, app.renderer, app.ticker — and assets from Pixi`s own ' +
+                'Assets.)');
+        },
+    });
+}
+/**
+ * Build the engine runtime for one canvas world from a `CanvasHostContext`.
+ * React-free on purpose: everything here is plain engine wiring the adapter
+ * threads into the `@pixi/react` tree through `EngineBridge`.
+ */
+export function createCanvasRootContext(host, options) {
+    const { id, inputMapPath = DEFAULT_INPUT_MAP_PATH } = options;
+    // Same observer threading as the three lane — this world's phases show up
+    // under the shared game profiler when hosted.
+    const systems = createSystemRunner(host.game?.profiler.systemObserver, 'canvas');
+    // The mounted world's adapter surface (`mounted.systems`) — declared before
+    // ctx so `ctx.registerSystemAdapter` can close over it (a game-owned
+    // capability like networking registers here from component code).
+    const systemAdapters = {};
+    let app = null;
+    const ctxRaw = {
+        systems,
+        registerSystemAdapter: (kind, adapter) => {
+            // biome-ignore lint/suspicious/noExplicitAny: same per-key record write the three lane performs; correct by construction
+            systemAdapters[kind] = adapter;
+            host.game?.notifySystemAdaptersChanged();
+        },
+    };
+    const ctx = ctxRaw;
+    if (host.game) {
+        ctx.game = host.game;
+        ctx.roots = host.game.roots;
+        ctx.playtest = host.game.playtest ?? null;
+    }
+    // --- ctx.debug — the ONE registry per Game root, shared across every world
+    // mounted onto it; a bare mount with no Game shell gets a private,
+    // mount-local registry instead. ---
+    const debugRegistry = (host.game ? getDebugRegistry(host.game) : null) ??
+        createDebugRegistry({ getTick: () => 0, getSimT: () => 0 });
+    systemAdapters.debug = debugRegistry.adapter;
+    ctx.debug = debugRegistry.forRoot(id);
+    ctx.random =
+        (host.game ? getSeededRandom(host.game) : null) ??
+            createSeededRandom(DEFAULT_SEEDED_RANDOM_SEED);
+    // --- ctx.clock — a REAL value, never a throwing getter: every world has a
+    // sim clock. A bare mount with no Game shell gets a private, mount-local one.
+    // `SimClock.disposeAfter` takes a THREE.Object3D, so the mount-local
+    // fallback's disposer is a loud refusal rather than a fabricated no-op: a
+    // canvas world's debris is a `PIXI.Container`, destroyed with its own
+    // `container.destroy()`.
+    const gameClock = host.game ? getSimClock(host.game) : null;
+    const clock = gameClock ??
+        createSimClock({
+            dispose: () => {
+                throw new Error(`canvas world "${id}": clock.disposeAfter() disposes a THREE.Object3D and has no ` +
+                    'meaning in a canvas world — destroy a display object with its own ' +
+                    '`container.destroy({ children: true })`, scheduled with `clock.after(seconds, ...)`.');
+            },
+        });
+    ctx.clock = clock;
+    // --- ctx.input + the debug-registry input seams — the game-owned
+    // InputManager, polled by the game-scoped runner each frame; this world
+    // registers the per-world seams so `game.input.*` (virtual input) and the
+    // built-in `input.actions`/`input.trace` providers resolve to it. ---
+    let inputMapReady = Promise.resolve();
+    if (host.game) {
+        const game = host.game;
+        const input = game.input;
+        ctxRaw['input'] = input;
+        debugRegistry.setInputActionsSource(id, () => input.actionNames().map((name) => ({ name, valueType: input.getActionValueType(name) })));
+        debugRegistry.setInputTraceSource(id, () => {
+            const raw = input.getInputTrace();
+            return {
+                version: raw.version,
+                seed: getSeededRandom(game)?.seed ?? null,
+                fixedDt: game.loop.fixedDt,
+                ticks: raw.ticks,
+            };
+        });
+        debugRegistry.setVirtualInputTarget(id, {
+            setVirtualAction: (action, value) => input.setVirtualAction(action, value),
+            tapVirtualAction: (action) => input.tapVirtualAction(action),
+            clearVirtualActions: () => input.clearVirtualActions(),
+            scheduleActionAtTick: (tick, action, value) => input.scheduleActionAtTick(tick, action, value),
+            startInputRecording: () => input.startInputRecording(),
+            stopInputRecording: () => input.stopInputRecording(),
+            isInputRecording: () => input.isInputRecording(),
+            injectAxis: (sourceId, value) => input.injectAxis(sourceId, value),
+            injectVector2: (sourceId, value) => input.injectVector2(sourceId, value),
+            injectPointerDelta: (sourceId, delta) => input.injectPointerDelta(sourceId, delta),
+            injectPointerPosition: (sourceId, value) => input.injectPointerPosition(sourceId, value),
+        });
+        if (!host.headless && inputMapPath !== null) {
+            // Load-once through the game-owned path (competing paths across roots
+            // throw THERE, loudly). A FAILED load must not fail this mount: a canvas
+            // world with no declared actions is legal. It degrades loudly instead.
+            inputMapReady = game.loadInputMap(inputMapPath).catch((err) => {
+                // biome-ignore lint/suspicious/noConsole: deliberate loud degrade — the documented alternative to failing the mount
+                console.error(`canvas world "${id}": failed to load input map "${inputMapPath}" — declared input ` +
+                    'actions and `game.input.*` (bot/virtual input) will not work until a valid map ' +
+                    'loads. Ship one at the conventional path or pass `inputMapPath` to ' +
+                    `createPixiReactAdapter (null to opt out). Cause: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }
+    }
+    else {
+        defineAbsentCtxField(ctxRaw, id, 'input', 'input is game-owned and this mount has no Game host (host.game is absent — bare ' +
+            'harness/foreign host); mount through the vgai host to get the shared InputManager.');
+    }
+    // --- Loud absence for everything a canvas world genuinely does not build. ---
+    const threeWhy = 'a canvas world renders through PixiJS and owns no THREE scene graph; the world root is ' +
+        "the Pixi stage, reached with @pixi/react's useApplication().app.stage.";
+    defineAbsentCtxField(ctxRaw, id, 'scene', threeWhy);
+    defineAbsentCtxField(ctxRaw, id, 'camera', threeWhy);
+    defineAbsentCtxField(ctxRaw, id, 'sceneIndex', 'the live scene index walks a THREE.Scene; a canvas world has none (walk the Pixi display ' +
+        'tree from useApplication().app.stage instead).');
+    const rapierWhy = 'canvas worlds do not build the first-party Rapier runtime; drive physics from inside the ' +
+        'tree with the 2D physics library of your choice.';
+    defineAbsentCtxField(ctxRaw, id, 'rapierWorld', rapierWhy);
+    defineAbsentCtxField(ctxRaw, id, 'rapier', rapierWhy);
+    defineAbsentCtxField(ctxRaw, id, 'physics', rapierWhy);
+    defineAbsentCtxField(ctxRaw, id, 'collisions', rapierWhy);
+    defineAbsentCtxField(ctxRaw, id, 'assets', 'the canvas host context carries no AssetCache (that cache is a GLTF/texture loader ' +
+        "resolving THREE objects); load textures/spritesheets with Pixi's own `Assets`.");
+    defineAbsentCtxField(ctxRaw, id, 'composer', 'a canvas world has no postprocessing EffectComposer; use Pixi filters on a Container.');
+    defineAbsentCtxField(ctxRaw, id, 'audio', 'canvas worlds build no first-party audio context; use Web Audio directly (or @pixi/sound).');
+    defineAbsentCtxField(ctxRaw, id, 'particles', 'canvas worlds build no three.quarks particle runtime; use a Pixi particle container.');
+    defineAbsentCtxField(ctxRaw, id, 'debugDraw', 'canvas worlds build no debug-draw helper; draw into a Pixi `Graphics` in the tree.');
+    return {
+        ctx,
+        systems,
+        systemAdapters,
+        inputMapReady,
+        get app() {
+            return app;
+        },
+        setApplication(next) {
+            app = next;
+        },
+        dispose() {
+            // Same ownership rule the three lane follows: dispose ONLY a clock this
+            // mount created. The game-scoped one belongs to `GameInternal.dispose()`
+            // — killing it here would freeze sim time and cancel every SIBLING
+            // world's timers.
+            if (!gameClock)
+                clock.dispose();
+            app = null;
+            // Scoped strip when a Game hosts this world (sibling roots stay live);
+            // a bare standalone mount owns its private registry and clears it all.
+            if (host.game)
+                debugRegistry.strip(id);
+            else
+                debugRegistry.strip();
+        },
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Node-loadable engine APIs used while a project's Vite configuration is
+ * evaluated. The package build emits this entry as ordinary JavaScript, so
+ * project config remains package-native without asking Node to execute raw
+ * TypeScript or reach into an adjacent checkout.
+ */
+export { type DataRef, dataRef, getRef } from './data/data-ref';
+export { type VgaiDataCheckOptions, vgaiDataCheck } from './data/vite-plugin-data';
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,KAAK,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,EAAE,KAAK,oBAAoB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/config.js

@@ -0,0 +1,8 @@
+/**
+ * Node-loadable engine APIs used while a project's Vite configuration is
+ * evaluated. The package build emits this entry as ordinary JavaScript, so
+ * project config remains package-native without asking Node to execute raw
+ * TypeScript or reach into an adjacent checkout.
+ */
+export { dataRef, getRef } from './data/data-ref';
+export { vgaiDataCheck } from './data/vite-plugin-data';

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

@@ -0,0 +1,90 @@
+/**
+ * Frame pacing — the accumulator/alpha arithmetic of the fixed-timestep loop,
+ * extracted PURE (WO-P13, `docs/WORK.md` §2 P13).
+ *
+ * `core/game-loop.ts` owns the browser side (rAF, `visibilitychange`,
+ * `performance.now`); this module owns the arithmetic, so the interesting
+ * cases — a display frame that consumes zero substeps, a frame that hits the
+ * substep ceiling, the spiral-of-death clamp, alpha's monotonic march across a
+ * substep gap — are testable without stubbing a single global.
+ *
+ * The substep half is byte-for-byte the pacing the loop has always used
+ * (clamp the raw frame gap, scale by `timeScale`, clamp the accumulator, then
+ * consume up to `maxSubSteps` whole steps). The addition is `alpha`: the
+ * fraction of a fixed step the accumulator is holding AFTER those substeps
+ * were consumed, which is what lets a renderer present between two fixed
+ * states instead of only at them.
+ */
+/** The two constants that define a loop's fixed cadence. */
+export interface FramePacingLimits {
+    /** Seconds per fixed substep (the loop's `fixedTimestep`). */
+    readonly fixedDt: number;
+    /** Substep ceiling per display frame — also the accumulator's hard ceiling. */
+    readonly maxSubSteps: number;
+}
+/** What one display frame's worth of wall time resolves to. */
+export interface PacedFrame {
+    /** Whole fixed substeps this display frame should consume (0..maxSubSteps). */
+    readonly steps: number;
+    /** The accumulator AFTER those substeps were consumed. */
+    readonly accumulator: number;
+    /**
+     * Interpolation alpha in `[0, 1]` — `accumulator / fixedDt`, i.e. how far
+     * the presentation clock sits past the last completed fixed state. `0` means
+     * "exactly on the last fixed state"; `0.5` means "halfway to the next one".
+     */
+    readonly alpha: number;
+    /**
+     * The display frame's own delta in seconds, clamped and `timeScale`d exactly
+     * like the time fed to the accumulator. This is the delta a per-display-frame
+     * consumer (post-processing, particles, a `RenderStepped`-shaped callback)
+     * should integrate against — NOT `fixedDt`, which is a sim quantity.
+     */
+    readonly displayDt: number;
+}
+/**
+ * `accumulator / fixedDt`, clamped to `[0, 1]`.
+ *
+ * Clamped rather than asserted because the accumulator can legitimately still
+ * hold a whole step when a frame hits the `maxSubSteps` ceiling; presenting
+ * "all the way at the next fixed state" is the only honest answer there, and a
+ * NaN/negative/zero-`fixedDt` degenerate resolves to `0` (present the last
+ * fixed state) rather than poisoning every transform downstream.
+ */
+export declare function interpolationAlpha(accumulator: number, fixedDt: number): number;
+/**
+ * The one legal range for `GameLoop.timeScale`, and therefore the range any
+ * instrument that DRIVES it must offer (`dev/instruments.ts`'s Time-scale
+ * slider reads exactly this — a second copy of `[0, 8]` in a control's bounds
+ * is how a slider ends up able to request a value the loop then silently
+ * refuses).
+ */
+export declare const TIME_SCALE_RANGE: {
+    readonly min: 0;
+    readonly max: 8;
+};
+/**
+ * Clamp a requested time scale into {@link TIME_SCALE_RANGE}. Extracted from
+ * `core/game-loop.ts`'s `set timeScale` (which still owns the out-of-range
+ * console warning — this function only computes) so the loop and every reader
+ * of the range agree by construction.
+ *
+ * A NON-FINITE request resolves to `min`, not to itself: `Math.min(8,
+ * Math.max(0, NaN))` is `NaN`, and a `NaN` time scale poisons the accumulator
+ * permanently — every frame afterwards consumes zero substeps and no warning
+ * ever repeats. Freezing (loudly, via the setter's warning) is recoverable;
+ * a silently `NaN`-ed loop is not.
+ */
+export declare function clampTimeScale(value: number): number;
+/**
+ * Resolve one display frame: how many fixed substeps it consumes, what the
+ * accumulator holds afterwards, and the alpha/displayDt the render pass should
+ * present with.
+ *
+ * @param accumulator unconsumed sim time carried in from the previous frame
+ * @param rawDt       wall-clock seconds since the previous frame
+ * @param timeScale   the loop's live time scale (already clamped to [0, 8] by
+ *                    its setter — this function does not re-clamp it)
+ */
+export declare function paceFrame(accumulator: number, rawDt: number, timeScale: number, limits: FramePacingLimits): PacedFrame;
+//# sourceMappingURL=frame-pacing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frame-pacing.d.ts","sourceRoot":"","sources":["../../src/core/frame-pacing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAK/E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;;;CAA8B,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGpD;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,iBAAiB,GACxB,UAAU,CAqBZ"}

package/dist/core/frame-pacing.js

@@ -0,0 +1,89 @@
+/**
+ * Frame pacing — the accumulator/alpha arithmetic of the fixed-timestep loop,
+ * extracted PURE (WO-P13, `docs/WORK.md` §2 P13).
+ *
+ * `core/game-loop.ts` owns the browser side (rAF, `visibilitychange`,
+ * `performance.now`); this module owns the arithmetic, so the interesting
+ * cases — a display frame that consumes zero substeps, a frame that hits the
+ * substep ceiling, the spiral-of-death clamp, alpha's monotonic march across a
+ * substep gap — are testable without stubbing a single global.
+ *
+ * The substep half is byte-for-byte the pacing the loop has always used
+ * (clamp the raw frame gap, scale by `timeScale`, clamp the accumulator, then
+ * consume up to `maxSubSteps` whole steps). The addition is `alpha`: the
+ * fraction of a fixed step the accumulator is holding AFTER those substeps
+ * were consumed, which is what lets a renderer present between two fixed
+ * states instead of only at them.
+ */
+/**
+ * `accumulator / fixedDt`, clamped to `[0, 1]`.
+ *
+ * Clamped rather than asserted because the accumulator can legitimately still
+ * hold a whole step when a frame hits the `maxSubSteps` ceiling; presenting
+ * "all the way at the next fixed state" is the only honest answer there, and a
+ * NaN/negative/zero-`fixedDt` degenerate resolves to `0` (present the last
+ * fixed state) rather than poisoning every transform downstream.
+ */
+export function interpolationAlpha(accumulator, fixedDt) {
+    if (!Number.isFinite(accumulator) || !Number.isFinite(fixedDt) || fixedDt <= 0)
+        return 0;
+    if (accumulator <= 0)
+        return 0;
+    const alpha = accumulator / fixedDt;
+    return alpha >= 1 ? 1 : alpha;
+}
+/**
+ * The one legal range for `GameLoop.timeScale`, and therefore the range any
+ * instrument that DRIVES it must offer (`dev/instruments.ts`'s Time-scale
+ * slider reads exactly this — a second copy of `[0, 8]` in a control's bounds
+ * is how a slider ends up able to request a value the loop then silently
+ * refuses).
+ */
+export const TIME_SCALE_RANGE = { min: 0, max: 8 };
+/**
+ * Clamp a requested time scale into {@link TIME_SCALE_RANGE}. Extracted from
+ * `core/game-loop.ts`'s `set timeScale` (which still owns the out-of-range
+ * console warning — this function only computes) so the loop and every reader
+ * of the range agree by construction.
+ *
+ * A NON-FINITE request resolves to `min`, not to itself: `Math.min(8,
+ * Math.max(0, NaN))` is `NaN`, and a `NaN` time scale poisons the accumulator
+ * permanently — every frame afterwards consumes zero substeps and no warning
+ * ever repeats. Freezing (loudly, via the setter's warning) is recoverable;
+ * a silently `NaN`-ed loop is not.
+ */
+export function clampTimeScale(value) {
+    if (!Number.isFinite(value))
+        return TIME_SCALE_RANGE.min;
+    return Math.min(TIME_SCALE_RANGE.max, Math.max(TIME_SCALE_RANGE.min, value));
+}
+/**
+ * Resolve one display frame: how many fixed substeps it consumes, what the
+ * accumulator holds afterwards, and the alpha/displayDt the render pass should
+ * present with.
+ *
+ * @param accumulator unconsumed sim time carried in from the previous frame
+ * @param rawDt       wall-clock seconds since the previous frame
+ * @param timeScale   the loop's live time scale (already clamped to [0, 8] by
+ *                    its setter — this function does not re-clamp it)
+ */
+export function paceFrame(accumulator, rawDt, timeScale, limits) {
+    const { fixedDt, maxSubSteps } = 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.
+    const displayDt = Math.min(rawDt, maxAccumulator) * timeScale;
+    let next = accumulator + displayDt;
+    // Spiral-of-death guard: bound the accumulator regardless of timeScale or
+    // frame-gap size. Time that can't possibly be caught up on is dropped, never
+    // carried forward.
+    if (next > maxAccumulator)
+        next = maxAccumulator;
+    let steps = 0;
+    while (next >= fixedDt && steps < maxSubSteps) {
+        next -= fixedDt;
+        steps++;
+    }
+    return { steps, accumulator: next, alpha: interpolationAlpha(next, fixedDt), displayDt };
+}

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

@@ -0,0 +1,62 @@
+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).
+ *
+ * Per real (rAF) frame:
+ *
+ *  1. the accumulator absorbs the frame gap (clamped, `timeScale`d) and
+ *     `config.update(fixedDt)` runs once per WHOLE fixed substep it can
+ *     consume, up to `maxSubSteps` — unchanged, and still the only thing that
+ *     advances gameplay, physics, `tick`/`simT` and the sim clock;
+ *  2. `config.render(alpha, displayDt)` runs EXACTLY ONCE, whatever step 1
+ *     did — including zero times. `alpha` is `accumulator / fixedDt` after
+ *     step 1 (see `core/frame-pacing.ts`): how far presentation sits past the
+ *     last completed fixed state, in `[0, 1]`.
+ *
+ * So a 120 Hz display draws 120 frames a second off a 60 Hz simulation, and a
+ * frame that consumes zero substeps still presents — which is the whole point:
+ * before this, motion presented at SIM rate, so half of every 120 Hz display's
+ * frames were duplicates and there was nowhere at all to host
+ * `RenderStepped`-shaped per-display-frame code (camera polish, procedural
+ * sway). `Game.onRenderStep` (`runtime/game.ts`) is that host, driven from
+ * this callback.
+ *
+ * `config.render` is OPTIONAL, and the hosts that don't pass it keep the old
+ * shape exactly: the `render` phase then still runs inside `config.update` as
+ * the last phase of `PHASE_ORDER` (`runtime/game.ts` only skips the render
+ * phases when its caller asks it to). That is deliberate, because two paths
+ * must stay frame-exact and neither goes through the rAF arm at all:
+ * `externalDrive` capture/offline export (see `GameLoopConfig.externalDrive`)
+ * and `Game.runTicks`, which drives `runFrame` directly.
+ */
+export declare function createGameLoop(config: GameLoopConfig): {
+    start(): void;
+    stop(): void;
+    readonly isRunning: boolean;
+    /**
+     * Truthful liveness (issue #175 — see `GameLoopLiveness`'s doc comment
+     * in `core/types.ts` for the full contract). Unlike `isRunning` above,
+     * this DISTINGUISHES a hidden-tab pause from an actually-stopped loop:
+     * `hiddenPaused` is only ever set by `handleVisibilityChange` (T2.1's
+     * idle throttle) and cleared by `start()`/`stop()`/visibility-restore,
+     * so it can never be true at the same time `running` is true. An
+     * `externalDrive` loop never installs the visibility listener at all
+     * (see `start()` above), so `hiddenPaused` stays permanently `false` for
+     * it — it only ever reports `'running'` or `'stopped'`.
+     */
+    readonly liveness: GameLoopLiveness;
+    timeScale: number;
+    /**
+     * The fixed substep timestep (seconds) this loop's accumulator consumes
+     * per `config.update()` call (`config.fixedTimestep ?? 1/60`) — read by
+     * `Game.runTicks` (D15, `runtime/game.ts`) so a synchronous fast-forward
+     * burst drives `game.runFrame` with the SAME `fixedDt` this loop's own
+     * rAF-driven accumulator would have used, without exposing (or
+     * `runTicks` needing) any other internal loop state.
+     */
+    readonly fixedDt: number;
+};
+//# sourceMappingURL=game-loop.d.ts.map

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

@@ -0,0 +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;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc;;;;IA6HjD;;;;;;;;;;OAUG;uBACa,gBAAgB;eAKX,MAAM;IAe3B;;;;;;;OAOG;;EAKN"}