@vgai/engine 0.5.0 → 0.5.2

package/dist/runtime/render-control.js

@@ -1,264 +0,0 @@
-/**
- * Render-control runtime seam (I2, `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md`
- * §15 I2). This is the harness a deterministic-capture host (Playwright/CDP,
- * I0/I3/I4) drives: exact-time seeks against the canonical
- * `AnimationClock` (`animation/animation-clock.ts`), and single
- * `preRender`+`render` phase passes across every world on a `Game`
- * (`runtime/game.ts`) — WITHOUT ever advancing gameplay fixed-step substeps
- * (`input`/`prePhysics`/`physics`/`postPhysics`/`gameLogic`/`animation` are
- * never invoked by this seam; `--simulate` (I5) is a different, later, path
- * that deliberately drives `game.runFrame(fixedDt)` instead).
- *
- * This module does NOT reuse `PlayState.step()` (`Game.play.step()`) — that
- * surface only advances the currently-FROZEN (paused) set of roots and is a
- * whole-call no-op while unpaused (see its doc comment in `runtime/game.ts`);
- * the spec review explicitly flagged it as the wrong seam. `renderOnce`
- * instead walks `game.roots` directly and calls each world's own
- * `WorldFrameHooks.runPhase` for exactly two phases.
- *
- * Also does NOT install anything by default — a caller must explicitly call
- * {@link installRenderControlHarness}, and even then it only actually
- * publishes `window.__vgaiRender` when the page's URL opts in via
- * `?vgai-render=1` (AC 4: unavailable/protected in normal production
- * gameplay unless explicitly enabled). See `render-seed.ts` for the
- * matching `Math.random` determinism hardening, which must run BEFORE this
- * module (or any other game module) is even imported.
- *
- * I5 (`--simulate` render, §15 I5) is implemented HERE, alongside `renderOnce`:
- * {@link VgaiRenderHarness.simulateSubsteps} drives `game.runFrame(fixedDt)` a
- * fixed integer number of times — the FULL fixed-step gameplay frame (every
- * phase in `PHASE_ORDER`, including `physics`/`gameLogic`/`animation`), unlike
- * `renderOnce`'s deliberately gameplay-free `preRender`+`render`-only pass.
- * A caller that never invokes `simulateSubsteps` (the default, sequence-
- * controlled render — I4) gets byte-identical behavior to before this method
- * existed: `renderOnce`/`seek`/`seekFrame`/`advanceFrame` are untouched by
- * this addition.
- */
-import { SystemPhase } from '../core/types';
-import { RENDER_MODE_QUERY_PARAM } from './render-seed';
-/** Shared by {@link installRenderControlHarness} and any caller that wants
- *  to check the opt-in flag before doing render-mode-only setup work (e.g.
- *  `render-seed.ts`'s own gate uses the same query param name). */
-export function isRenderModeRequested(location) {
-    return new URLSearchParams(location.search).get(RENDER_MODE_QUERY_PARAM) === '1';
-}
-const RENDER_ONLY_PHASES = [SystemPhase.PRE_RENDER, SystemPhase.RENDER];
-/**
- * Run exactly one `preRender`+`render` phase pass across every host-driven
- * (`!drivesOwnLoop`) world on `game`, then await the GPU/DOM composition
- * fence. This is the ENTIRE frame this call drives — no `input`,
- * `prePhysics`, `physics`, `postPhysics`, `gameLogic`, or `animation` phase
- * is ever touched, which is what makes this safe to call from a paused-or-
- * stopped clock without silently ticking gameplay. Phases are run as global
- * barriers across roots (mirroring `GameInternal.runFrame`'s own phase-then-
- * world nesting in `runtime/game.ts`): every world's `preRender` runs before
- * any world's `render`, in `game.roots` declaration order.
- *
- * Ordering within a phase mirrors `GameInternal.runFrame` EXACTLY (see its
- * doc comment in `runtime/game.ts`): the game-scoped `SystemRunner`
- * (`game.systems`) runs FIRST, before any world's frame hooks. `game.systems`
- * is empty for every game today (nothing registers against it yet), so this
- * is a no-op in practice — but a later slice that registers a Game-scoped
- * `preRender`/`render` system (e.g. a cinematic camera crossfade that must
- * paint once per captured frame) would otherwise be silently MISSED by
- * capture while running fine in live playback, since live playback goes
- * through `runFrame`. Running it here keeps the seam a faithful subset of
- * `runFrame`'s phase pass, not a divergent one.
- *
- * A `drivesOwnLoop` world (self-driven, raw-rAF) has no phase hooks this
- * seam can drive — it is skipped with a loud, once-per-call warning rather
- * than silently omitted, mirroring this file's "fail loudly, never a silent
- * no-op" convention. A host-driven world with no `frame` (an opaque/foreign
- * mount) is skipped the same way — there is no phase hook to call. Both
- * checks happen ONCE, up front (see {@link renderableWorlds}), not per
- * phase — a world unrenderable in `preRender` is unrenderable in `render`
- * too, so warning twice would just be noise.
- */
-async function renderOnce(game) {
-    const roots = renderableWorlds(game);
-    for (const phase of RENDER_ONLY_PHASES) {
-        // Game-scoped systems first, then per-world frame hooks — the SAME order
-        // GameInternal.runFrame uses (runtime/game.ts). See doc comment above.
-        game.systems.runPhase(phase, 0);
-        for (const world of roots) {
-            world.frame.runPhase(phase, 0);
-        }
-    }
-    await compositionFence();
-}
-/** Filter `game.roots` down to the ones {@link renderOnce} can actually
- *  drive (host-driven, with real `WorldFrameHooks`) — see that function's
- *  doc comment for why an excluded world is warned about loudly, not
- *  silently dropped. */
-function renderableWorlds(game) {
-    const result = [];
-    for (const world of game.roots) {
-        if (world.mounted.drivesOwnLoop) {
-            warnUnrenderable(world.id, 'drives its own loop — renderOnce() cannot frame-gate it ' +
-                '(docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §15 I5 names this policy)');
-            continue;
-        }
-        if (!world.frame) {
-            warnUnrenderable(world.id, `(kind: ${world.kind}) has no phase hooks — renderOnce() cannot drive it (opaque/foreign ` +
-                'mount with no frame-gated entry point)');
-            continue;
-        }
-        result.push({ id: world.id, frame: world.frame });
-    }
-    return result;
-}
-function warnUnrenderable(worldLabel, reason) {
-    // biome-ignore lint/suspicious/noConsole: structured, greppable — mirrors runtime/game.ts's own direct console.warn idiom for "cannot gate this world" capability shortfalls.
-    console.warn(`[render-control] world "${worldLabel}" ${reason}.`);
-}
-/**
- * I5 AC 5 policy text for the two conditions {@link renderableWorlds} skips —
- * shared so {@link VgaiRenderHarness.excludedFromDeterminism} names the SAME
- * roots `renderOnce()` warns about, in the SAME words, rather than
- * maintaining a second, driftable description of the same two checks.
- */
-function computeWorldExclusionReasons(game) {
-    const reasons = [];
-    for (const world of game.roots) {
-        if (world.mounted.drivesOwnLoop) {
-            reasons.push(`world "${world.id}" drives its own loop — cannot be frame-gated for deterministic ` +
-                'capture (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §15 I5 names this policy: ' +
-                'FAIL LOUDLY or be excluded only by an explicit declared policy).');
-            continue;
-        }
-        if (!world.frame) {
-            reasons.push(`world "${world.id}" (kind: ${world.kind}) has no phase hooks — an opaque/foreign mount ` +
-                'with no frame-gated entry point cannot participate in deterministic capture.');
-        }
-    }
-    return reasons;
-}
-function nextAnimationFrame() {
-    return new Promise((resolve) => {
-        requestAnimationFrame(() => resolve());
-    });
-}
-/**
- * GPU/DOM composition fence (I2 AC: "waits for GPU/DOM composition
- * (double-rAF fence ... ) rather than an arbitrary sleep"). Two nested
- * `requestAnimationFrame` callbacks: the first fires once the browser has
- * scheduled a new frame after our `render()` calls above; the second fires
- * once THAT frame has itself been produced and composited — by the time the
- * second callback runs, the compositor has committed the frame our render
- * calls painted, so a screenshot taken immediately after this resolves
- * reflects the seeked state, not a stale one. (The CDP screenshot
- * compositor-commit wait itself is the capture host's job — I0/I3 — this
- * fence is the runtime-side half.)
- */
-async function compositionFence() {
-    await nextAnimationFrame();
-    await nextAnimationFrame();
-}
-async function resolveHook(hook) {
-    if (!hook)
-        return { status: 'not-applicable' };
-    try {
-        await hook();
-        return { status: 'ready' };
-    }
-    catch (err) {
-        return { status: 'error', detail: err instanceof Error ? err.message : String(err) };
-    }
-}
-async function checkFontsReady() {
-    if (typeof document === 'undefined' || !document.fonts)
-        return { status: 'not-applicable' };
-    try {
-        await document.fonts.ready;
-        return { status: 'ready' };
-    }
-    catch (err) {
-        return { status: 'error', detail: err instanceof Error ? err.message : String(err) };
-    }
-}
-async function buildReadinessReport(hooks) {
-    const [assets, shaders, fonts, theatre, tone, scene] = await Promise.all([
-        resolveHook(hooks.assets),
-        resolveHook(hooks.shaders),
-        checkFontsReady(),
-        resolveHook(hooks.theatre),
-        resolveHook(hooks.tone),
-        resolveHook(hooks.scene),
-    ]);
-    return { assets, shaders, fonts, theatre, tone, scene };
-}
-/**
- * Build (and, when render mode is actually requested, publish) the
- * `window.__vgaiRender` harness. AC 4 — production protection — lives HERE,
- * not just at the call site: even if a host application calls this
- * unconditionally on every boot, the harness is only ever constructed *and*
- * attached to `target` when `isRenderModeRequested(location)` is true;
- * otherwise this is a no-op that returns `undefined`. A normal production
- * gameplay page therefore never gets `window.__vgaiRender` no matter how
- * this function is wired into its entry point.
- */
-export function installRenderControlHarness(opts) {
-    const location = opts.location ?? window.location;
-    if (!isRenderModeRequested(location))
-        return undefined;
-    const { game, clock, readiness = {} } = opts;
-    const target = opts.target ?? window;
-    const frameAdvancers = opts.frameAdvancers ?? [];
-    const simulateFixedDt = opts.simulateFixedDt ?? 1 / 60;
-    const declaredExclusions = opts.excludedFromDeterminism ?? [];
-    const harness = {
-        seek(t) {
-            clock.seek(t);
-        },
-        seekFrame(n, fps) {
-            clock.seekFrame(n, fps);
-        },
-        advanceFrame(dt) {
-            for (const advancer of frameAdvancers)
-                advancer(dt);
-        },
-        renderOnce() {
-            return renderOnce(game);
-        },
-        ready() {
-            return buildReadinessReport(readiness);
-        },
-        simulateSubsteps(steps) {
-            for (let i = 0; i < steps; i++) {
-                game.runFrame(simulateFixedDt);
-            }
-        },
-        excludedFromDeterminism() {
-            return [...declaredExclusions, ...computeWorldExclusionReasons(game)];
-        },
-        simulateFixedDt() {
-            return simulateFixedDt;
-        },
-    };
-    target['__vgaiRender'] = harness;
-    return harness;
-}
-/**
- * Defensive assertion for the I2 AC "Pixi roots are pinned to the WebGL
- * renderer (not WebGPU) in render mode". In THIS engine that invariant
- * already holds unconditionally — `world2d/pixi-surface.ts`'s
- * `createPixiSurface` hardcodes `preference: 'webgl'` on every
- * `Application.init()` call it makes, and `setup/setup-renderer.ts` never
- * constructs a `WebGPURenderer` for threejs roots either — so there is no
- * live WebGPU code path for a first-party render-mode page to disable.
- * This helper exists for a render-mode installer that mounts a CUSTOM/
- * foreign pixi adapter (`create-runtime.ts`'s `{ module }` pixi path) this
- * engine did not construct itself, to assert the invariant against the
- * live mounted renderer rather than merely trusting it. Duck-typed against
- * pixi.js v8's numeric `RendererType` (`WEBGL = 1`, `WEBGPU = 2`,
- * `CANVAS = 4`) so this file never value-imports `pixi.js` (the same
- * type-only-pixi rule `runtime/game.ts`/`create-runtime.ts` document for
- * themselves).
- */
-export function assertPixiWorldIsWebGL(rendererType, worldId) {
-    const isWebGPU = rendererType === 2 || (typeof rendererType === 'string' && /webgpu/i.test(rendererType));
-    if (isWebGPU) {
-        throw new Error(`[render-control] world "${worldId}": Pixi renderer is WebGPU in render mode — ` +
-            'render-control requires WebGL (docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md §15 I2).');
-    }
-}

package/dist/runtime/render-seed.d.ts

@@ -1,57 +0,0 @@
-/**
- * Deterministic `Math.random` seeding for render-control mode (I2 AC,
- * `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md` §15 I2: "`Math.random`
- * is deterministically seeded/stubbed page-wide before any game module
- * executes").
- *
- * Deliberately a ZERO-IMPORT module (no `three`, no other engine file) so
- * its own evaluation is instantaneous — a render-mode entry page loads this
- * as its FIRST `<script type="module">` tag, before the tag that pulls in
- * the actual game/runtime modules. Per the HTML module-script ordering
- * rules, sibling `<script type="module">` tags without `async` execute in
- * document order, and each one's own dependency graph (here, empty) is
- * fully evaluated before the browser moves to the next tag — so calling
- * {@link maybeInstallRenderModeRandom} from this module's importer, in a
- * script tag placed before the game's own entry tag, guarantees every
- * subsequent module's top-level code (and everything it does at runtime)
- * observes the seeded generator, never the platform's real
- * cryptographically-random `Math.random`.
- *
- * This module does not decide WHETHER to seed on its own (importing it has
- * no side effect) — the caller decides, by calling
- * {@link maybeInstallRenderModeRandom} (query-param gated) or
- * {@link installDeterministicRandom} (unconditional) from a tiny bootstrap
- * entry. See `packages/engine/e2e/fixture/render-seed-entry.ts` for the
- * worked bootstrap this module is designed to be loaded from.
- */
-/**
- * mulberry32 — a small, fast, deterministic 32-bit PRNG. Not cryptographic;
- * this is explicitly a determinism tool (reproducible capture), not a
- * security primitive. Returns a function with the same call signature as
- * `Math.random` (no arguments, `[0, 1)` float).
- */
-export declare function createMulberry32(seed: number): () => number;
-/**
- * Replace the global `Math.random` with a seeded, deterministic generator.
- * Idempotent to call more than once (each call re-seeds from scratch — the
- * last call wins), which matters for HMR-style re-execution the same way
- * `main.ts`'s `registerAdapterSurface` guard does elsewhere in this runtime.
- */
-export declare function installDeterministicRandom(seed: number): void;
-/** Query-param name that opts a page into render-control mode (I2 AC 4: the
- *  mode must be unavailable/protected in normal production gameplay unless
- *  explicitly enabled). Shared with `render-control.ts`'s own production
- *  guard so both checks agree on the same flag. */
-export declare const RENDER_MODE_QUERY_PARAM = "vgai-render";
-/** Optional query param to pin a specific seed (default below when absent). */
-export declare const RENDER_SEED_QUERY_PARAM = "vgai-seed";
-/**
- * Seed `Math.random` iff the page's URL opts into render mode
- * (`?vgai-render=1`), reading an optional `?vgai-seed=<int>` override.
- * Returns whether it seeded, purely for the caller's own diagnostics/log —
- * the bootstrap entry doesn't need to branch on it.
- */
-export declare function maybeInstallRenderModeRandom(location?: {
-    search: string;
-}): boolean;
-//# sourceMappingURL=render-seed.d.ts.map

package/dist/runtime/render-seed.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"render-seed.d.ts","sourceRoot":"","sources":["../../src/runtime/render-seed.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,MAAM,CAS3D;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAE7D;AAED;;;mDAGmD;AACnD,eAAO,MAAM,uBAAuB,gBAAgB,CAAC;AACrD,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,cAAc,CAAC;AAGnD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,GAAE;IAAE,MAAM,EAAE,MAAM,CAAA;CAAoB,GAC7C,OAAO,CAOT"}

package/dist/runtime/render-seed.js

@@ -1,74 +0,0 @@
-/**
- * Deterministic `Math.random` seeding for render-control mode (I2 AC,
- * `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md` §15 I2: "`Math.random`
- * is deterministically seeded/stubbed page-wide before any game module
- * executes").
- *
- * Deliberately a ZERO-IMPORT module (no `three`, no other engine file) so
- * its own evaluation is instantaneous — a render-mode entry page loads this
- * as its FIRST `<script type="module">` tag, before the tag that pulls in
- * the actual game/runtime modules. Per the HTML module-script ordering
- * rules, sibling `<script type="module">` tags without `async` execute in
- * document order, and each one's own dependency graph (here, empty) is
- * fully evaluated before the browser moves to the next tag — so calling
- * {@link maybeInstallRenderModeRandom} from this module's importer, in a
- * script tag placed before the game's own entry tag, guarantees every
- * subsequent module's top-level code (and everything it does at runtime)
- * observes the seeded generator, never the platform's real
- * cryptographically-random `Math.random`.
- *
- * This module does not decide WHETHER to seed on its own (importing it has
- * no side effect) — the caller decides, by calling
- * {@link maybeInstallRenderModeRandom} (query-param gated) or
- * {@link installDeterministicRandom} (unconditional) from a tiny bootstrap
- * entry. See `packages/engine/e2e/fixture/render-seed-entry.ts` for the
- * worked bootstrap this module is designed to be loaded from.
- */
-/**
- * mulberry32 — a small, fast, deterministic 32-bit PRNG. Not cryptographic;
- * this is explicitly a determinism tool (reproducible capture), not a
- * security primitive. Returns a function with the same call signature as
- * `Math.random` (no arguments, `[0, 1)` float).
- */
-export function createMulberry32(seed) {
-    let state = seed >>> 0;
-    return function mulberry32() {
-        state = (state + 0x6d2b79f5) | 0;
-        let t = state;
-        t = Math.imul(t ^ (t >>> 15), t | 1);
-        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
-        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-    };
-}
-/**
- * Replace the global `Math.random` with a seeded, deterministic generator.
- * Idempotent to call more than once (each call re-seeds from scratch — the
- * last call wins), which matters for HMR-style re-execution the same way
- * `main.ts`'s `registerAdapterSurface` guard does elsewhere in this runtime.
- */
-export function installDeterministicRandom(seed) {
-    Math.random = createMulberry32(seed);
-}
-/** Query-param name that opts a page into render-control mode (I2 AC 4: the
- *  mode must be unavailable/protected in normal production gameplay unless
- *  explicitly enabled). Shared with `render-control.ts`'s own production
- *  guard so both checks agree on the same flag. */
-export const RENDER_MODE_QUERY_PARAM = 'vgai-render';
-/** Optional query param to pin a specific seed (default below when absent). */
-export const RENDER_SEED_QUERY_PARAM = 'vgai-seed';
-const DEFAULT_RENDER_SEED = 0x9e3779b9; // golden-ratio constant — an arbitrary but fixed default
-/**
- * Seed `Math.random` iff the page's URL opts into render mode
- * (`?vgai-render=1`), reading an optional `?vgai-seed=<int>` override.
- * Returns whether it seeded, purely for the caller's own diagnostics/log —
- * the bootstrap entry doesn't need to branch on it.
- */
-export function maybeInstallRenderModeRandom(location = window.location) {
-    const params = new URLSearchParams(location.search);
-    if (params.get(RENDER_MODE_QUERY_PARAM) !== '1')
-        return false;
-    const seedParam = params.get(RENDER_SEED_QUERY_PARAM);
-    const seed = seedParam !== null && seedParam !== '' ? Number(seedParam) : DEFAULT_RENDER_SEED;
-    installDeterministicRandom(Number.isFinite(seed) ? seed : DEFAULT_RENDER_SEED);
-    return true;
-}

package/dist/runtime/state-bridge.d.ts

@@ -1,61 +0,0 @@
-/**
- * Frame-versioned game state bridge (T7.4 slice 1 — `docs/REACT-STATE-BRIDGE.md`
- * §2, the D7 remainder). Components mutate state on `this` freely during
- * ticks — there is no proxy, no dirty tracking, no event per mutation (Track
- * A: no mirror, no sync layer). So the unit of change a subscriber can
- * observe is the FRAME: `GameInternal.runFrame` bumps `frameVersion` and
- * notifies subscribers at most once, at its tail, AFTER every phase of every
- * world and every world's `endFrame` hook has run (see the wiring in
- * `runtime/game.ts`) — mirroring the D7 "from `gameLogic` onward, every
- * world's post-step state is readable" guarantee, extended to "after the
- * frame, ALL state is readable".
- *
- * This file is plain, react-free TypeScript any consumer could use — no
- * react import here, or anywhere under `runtime/` (the react-facing
- * `useGameState` hook, which DOES import React, lives at
- * `packages/engine/src/react/game-state.tsx`).
- *
- * SECOND trigger for `bump()` (`Game.registerWorld`, `runtime/game.ts`): the
- * `roots` list is also state a `useGameState` selector can read
- * (`g.roots.map(...)`, the T6.2 two-world-compose gate), and it changes
- * OUTSIDE the frame loop — `registerWorld` is called as each world finishes
- * mounting, which can happen well before the host's loop has ticked even
- * once. Without an immediate notification here, a selector that first reads
- * `g.roots` before every world has registered stays stuck on that stale
- * snapshot until the next completed frame — which, on a slow/contended host
- * or a backgrounded tab, may be arbitrarily delayed. See `registerWorld`'s
- * own doc comment for the concrete CI failure this closes.
- */
-/** Frame-versioned, react-free subscription surface — `docs/REACT-STATE-BRIDGE.md` §2. */
-export interface GameStateBridge {
-    /** Monotonic; bumped once per completed `runFrame`, AND once per
-     *  `Game.registerWorld` call (world-list changes are observable state too
-     *  — see this file's module doc comment). Starts at 0 before the first of
-     *  either has happened. Never treat this as a literal frame COUNT — only
-     *  "did it change" is a contract any consumer may rely on. */
-    readonly frameVersion: number;
-    /** Notified at most once per frame, after ALL phases of ALL roots (and
-     *  their `endFrame` hooks) have run. Returns an unsubscribe function. */
-    subscribe(onFrame: () => void): () => void;
-}
-/** Host-internal extension of {@link GameStateBridge}: adds `bump`, called
- *  both by `GameInternal.runFrame` at its tail AND by `Game.registerWorld`
- *  when the world list changes (see this file's module doc comment). NOT
- *  part of the game-facing `Game.state` surface (typed as the narrower
- *  `GameStateBridge` there) — games/components/hooks never call `bump`
- *  directly; only the frame executor and the world registry do. */
-export interface GameStateBridgeInternal extends GameStateBridge {
-    /** Bump `frameVersion` by one and notify every current subscriber, in
-     *  subscription order. Subscriber errors are isolated (per-subscriber
-     *  try/catch, loud `console.error`, never swallowed silently) — mirrors
-     *  the error-isolation idiom in `ecs/component-manager.ts`'s per-component
-     *  `update()` calls: one offending subscriber must not stop its siblings
-     *  from being notified, and must not break the frame loop. */
-    bump(): void;
-}
-/**
- * Construct a fresh bridge. One per `Game` (created alongside the other
- * game-scoped state in `createGame`, `runtime/game.ts`).
- */
-export declare function createStateBridge(): GameStateBridgeInternal;
-//# sourceMappingURL=state-bridge.d.ts.map

package/dist/runtime/state-bridge.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"state-bridge.d.ts","sourceRoot":"","sources":["../../src/runtime/state-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,0FAA0F;AAC1F,MAAM,WAAW,eAAe;IAC9B;;;;kEAI8D;IAC9D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;6EACyE;IACzE,SAAS,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5C;AAED;;;;;mEAKmE;AACnE,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D;;;;;kEAK8D;IAC9D,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,uBAAuB,CA8B3D"}

package/dist/runtime/state-bridge.js

@@ -1,63 +0,0 @@
-/**
- * Frame-versioned game state bridge (T7.4 slice 1 — `docs/REACT-STATE-BRIDGE.md`
- * §2, the D7 remainder). Components mutate state on `this` freely during
- * ticks — there is no proxy, no dirty tracking, no event per mutation (Track
- * A: no mirror, no sync layer). So the unit of change a subscriber can
- * observe is the FRAME: `GameInternal.runFrame` bumps `frameVersion` and
- * notifies subscribers at most once, at its tail, AFTER every phase of every
- * world and every world's `endFrame` hook has run (see the wiring in
- * `runtime/game.ts`) — mirroring the D7 "from `gameLogic` onward, every
- * world's post-step state is readable" guarantee, extended to "after the
- * frame, ALL state is readable".
- *
- * This file is plain, react-free TypeScript any consumer could use — no
- * react import here, or anywhere under `runtime/` (the react-facing
- * `useGameState` hook, which DOES import React, lives at
- * `packages/engine/src/react/game-state.tsx`).
- *
- * SECOND trigger for `bump()` (`Game.registerWorld`, `runtime/game.ts`): the
- * `roots` list is also state a `useGameState` selector can read
- * (`g.roots.map(...)`, the T6.2 two-world-compose gate), and it changes
- * OUTSIDE the frame loop — `registerWorld` is called as each world finishes
- * mounting, which can happen well before the host's loop has ticked even
- * once. Without an immediate notification here, a selector that first reads
- * `g.roots` before every world has registered stays stuck on that stale
- * snapshot until the next completed frame — which, on a slow/contended host
- * or a backgrounded tab, may be arbitrarily delayed. See `registerWorld`'s
- * own doc comment for the concrete CI failure this closes.
- */
-/**
- * Construct a fresh bridge. One per `Game` (created alongside the other
- * game-scoped state in `createGame`, `runtime/game.ts`).
- */
-export function createStateBridge() {
-    let frameVersion = 0;
-    const subscribers = new Set();
-    return {
-        get frameVersion() {
-            return frameVersion;
-        },
-        subscribe(onFrame) {
-            subscribers.add(onFrame);
-            return () => {
-                subscribers.delete(onFrame);
-            };
-        },
-        bump() {
-            frameVersion++;
-            // Snapshot before iterating (same idiom as ComponentManager's
-            // per-phase `list = byPhase.get(phase)!.slice()`): a subscriber that
-            // subscribes/unsubscribes from WITHIN a notification must not affect
-            // which of ITS SIBLINGS get notified this same bump.
-            const notified = Array.from(subscribers);
-            for (const onFrame of notified) {
-                try {
-                    onFrame();
-                }
-                catch (err) {
-                    console.error('[state-bridge] subscriber threw:', err);
-                }
-            }
-        },
-    };
-}