@vgai/engine 0.5.0 → 0.5.2

package/dist/runtime/debug-registry.js

@@ -1,513 +0,0 @@
-/**
- * The game-scoped debug/synthetic-player registry (`docs/SYNTHETIC-PLAYER-SPEC.md`
- * §3.1). ONE registry per `Game` root — every world's `ctx.debug` (see
- * `DebugCtxSurface`, `runtime/types.ts`) feeds the SAME registry via
- * {@link DebugRegistry.forWorld}, so a name a game registers is visible (and
- * name-collision-checked) across every world, not just the one that
- * registered it. `createGame` (`runtime/game.ts`) constructs the registry
- * alongside the state bridge and files it in the `Game -> DebugRegistry`
- * WeakMap this module owns; later consumers (the react `useDebugProvider`/
- * `useDebugCommand` hooks, editor panels) reach it via {@link getDebugRegistry}
- * rather than threading it through every call site.
- *
- * Provenance note: a registration's "world" is the MOUNT's adapter id (the
- * `fromSetup(id, ...)` / `VgaiSceneConfig.id` a project already names each
- * world's entry with) rather than the `WorldInstance.id` `registerThreeWorld`
- * assigns — that id isn't known until AFTER `mount()` resolves (`create-
- * runtime.ts` calls `registerThreeWorld` with it only once `mount()` returns),
- * which is after every `setup()`-time registration has already run. For the
- * single-world case (nearly every project today) this is simply `'vgai-scene'`;
- * a multi-world manifest names each world's adapter to match its declared id
- * by convention, so collision messages stay meaningful in practice.
- */
-import { z } from 'zod';
-/** Engine-local error for the debug seam — mirrors the `code` + `data` shape
- *  `packages/vgai-sdk/src/errors.ts` uses (no import: the engine does not
- *  depend on `@vgai/sdk`). `code` is always machine-readable; nothing reading
- *  this error may key off `message` prose. */
-export class DebugError extends Error {
-    code;
-    data;
-    constructor(code, message, data) {
-        super(message);
-        this.name = 'DebugError';
-        this.code = code;
-        this.data = data;
-    }
-}
-const REGISTRATION_HINT = 'ctx.debug.registerStateProvider(name, fn) — see the template example component';
-/** Task 2.2 — how long `invoke()` waits for a `locus: 'server'` command's
- *  `__vgai:debugCommandResult` reply before failing loudly. */
-const SERVER_COMMAND_TIMEOUT_MS = 10_000;
-/** Provenance `worldId` for every registration made through the react door
- *  (`useDebugProvider`/`useDebugCommand`, `packages/engine/src/react/game-
- *  state.tsx`) — react roots have no `setup()`/`ctx.debug` of their own
- *  (spec §3.1's "react-world registration door" paragraph), so all of them
- *  share this one provenance string; a name collision between two DIFFERENT
- *  react components is therefore the same-world "replace + warn once" case,
- *  never the cross-world throw (which is reserved for a GameComponent world
- *  vs. the react door genuinely disagreeing about a name).
- *
- *  Defect 7 fix: this used to be the bare string `'react'`, which collided in
- *  provenance with a manifest world literally named `'react'` (e.g. a
- *  `kind: 'react'` world whose `id` is `"react"`) — `forWorld('react')` and
- *  the react door would then be treated as the SAME world for collision
- *  purposes, which is wrong (they are genuinely different registrants that
- *  happen to share a display name). Namespaced like `'__engine__'` so no
- *  real project world id can ever collide with it. */
-const REACT_WORLD_ID = '__react__';
-function warnOnce(warned, name, kind, worldId) {
-    if (warned.has(name))
-        return;
-    warned.add(name);
-    // biome-ignore lint/suspicious/noConsole: structured, greppable — the debug seam's own duplicate-registration signal (spec §3.1)
-    console.warn(`[debug] ${kind} "${name}" re-registered (world "${worldId}")`);
-}
-/**
- * Construct a fresh game-scoped debug registry. `getTick`/`getSimT` are
- * suppliers (not values) so the built-in `time` provider always reads the
- * CURRENT counters — `createGame` passes closures over its own mutable
- * `tick`/`simT`, incremented in `runFrame`'s tail (T1.2). `getDefaultWorldId`
- * (D15/T-D15.5, optional) resolves the manifest's first/default world id —
- * `createGame` passes `() => (roots.length ? requireDefaultWorld().id :
- * null)`; a bare `createDebugRegistry()` test stand-in with no `Game` behind
- * it omits it (per-world resolution then falls back to "the single
- * registered world" or "whichever registered first" — see
- * `resolveInputWorldId`). `getLoopLiveness` (issue #175, optional) supplies
- * the REAL `GameLoop.liveness` — `createGame` passes `() => opts.loop.
- * liveness`; a bare `createDebugRegistry()` test stand-in with no loop
- * behind it omits it, and the built-in `time` provider reports `null`
- * rather than fabricating `'running'` (this module must never claim health
- * it cannot observe, same rule the loop's own liveness getter documents).
- */
-export function createDebugRegistry(opts) {
-    const providers = new Map();
-    const commands = new Map();
-    const warnedProviders = new Set();
-    const warnedCommands = new Set();
-    const ring = [];
-    const RING_CAP = 500;
-    // Run-4 friction #5 — monotonic, registry-lifetime counter backing
-    // `TickStampedEvent.seq`. Never reset, never shared by two events (unlike
-    // `tick`, which a debug-command emission and a fenced consumer's snapshot
-    // can legitimately collide on — see that field's doc comment in
-    // `adapter/system-adapter.ts`).
-    let seqCounter = 0;
-    let roomDeclared = false;
-    // D15/T-D15.5 — per-world maps (Map preserves insertion order, which
-    // `resolveInputWorldId`'s "whichever registered first" fallback relies on
-    // when no `getDefaultWorldId` is available to disambiguate).
-    const inputActionsSources = new Map();
-    const inputTraceSources = new Map();
-    const virtualInputTargets = new Map();
-    let runTicksTarget = null;
-    let attachedRoom = null;
-    const pendingServerCommands = new Map();
-    let requestCounter = 0;
-    /**
-     * The ONE resolution function every per-world input seam shares (D15
-     * review objection: the debug bridge and the editor relay must never be
-     * able to disagree about which world an unqualified actuation targets).
-     *
-     * - `explicit` given: must be a registered world id, else throws
-     *   `DEBUG_INPUT_WORLD_NOT_FOUND` (a caller mistake — distinct from
-     *   "nothing mounted yet", which returns `null` below instead of throwing).
-     * - `explicit` omitted: the manifest's first/default world id
-     *   (`opts.getDefaultWorldId()`) iff that world has actually registered —
-     *   else (no `Game`/no default resolvable, or the default world never
-     *   wired one — e.g. a foreign/opaque mount) the single registered world,
-     *   or, with more than one and no resolvable default, whichever registered
-     *   FIRST (`Map` insertion order) — the closest analogue to this seam's
-     *   pre-D15.5 single-slot behavior, but now a stable, principled choice
-     *   instead of "whichever mounted last".
-     * - Nothing registered at all: `null`.
-     */
-    function resolveInputWorldId(explicit) {
-        if (explicit !== undefined) {
-            if (!virtualInputTargets.has(explicit)) {
-                throw new DebugError('DEBUG_INPUT_WORLD_NOT_FOUND', `debug: no InputManager wired for world "${explicit}" — registered: ` +
-                    (virtualInputTargets.size ? [...virtualInputTargets.keys()].join(', ') : '(none)'), { worldId: explicit, registered: [...virtualInputTargets.keys()] });
-            }
-            return explicit;
-        }
-        return resolveWorldForSource(virtualInputTargets.keys());
-    }
-    /** The same "default world, else the one registered, else whichever
-     *  registered first" fallback {@link resolveInputWorldId} uses for the
-     *  ACTUATION target, generalized over any per-world registration set
-     *  (`inputActionsSources`/`inputTraceSources` included) — every one of
-     *  these maps is keyed by the same world ids, populated at the same
-     *  per-world mount seed spot, so "the default world" means the same thing
-     *  for all of them. Never throws (no explicit-id case here — the two
-     *  builtin providers that call this have no way to accept a caller-chosen
-     *  worldId today; see their own doc comments). */
-    function resolveWorldForSource(registered) {
-        const ids = [...registered];
-        if (ids.length === 0)
-            return null;
-        const defaultId = opts.getDefaultWorldId?.() ?? null;
-        if (defaultId !== null && ids.includes(defaultId))
-            return defaultId;
-        return ids[0];
-    }
-    providers.set('time', {
-        // `loopLiveness` (issue #175): `null` when no loop is wired behind this
-        // registry (a bare `createDebugRegistry()` test stand-in) — never a
-        // fabricated `'running'`. Every real `Game` (`createGame`) wires this,
-        // so every live play session reports a real value.
-        fn: () => ({
-            simSeconds: opts.getSimT(),
-            tick: opts.getTick(),
-            loopLiveness: opts.getLoopLiveness?.() ?? null,
-        }),
-        tier: 'observable',
-        worldId: '__engine__',
-        builtin: true,
-    });
-    providers.set('input.actions', {
-        // Resolves to the DEFAULT world's action list (see `resolveInputWorldId`)
-        // — deterministic across every world that registers, rather than the
-        // pre-D15.5 "whichever mounted last" behavior.
-        fn: () => {
-            const worldId = resolveWorldForSource(inputActionsSources.keys());
-            return (worldId ? inputActionsSources.get(worldId) : undefined)?.() ?? [];
-        },
-        tier: 'observable',
-        worldId: '__engine__',
-        builtin: true,
-    });
-    // D15/T-D15.5 — the post-gate action-delta trace, readable via a provider.
-    // Absent a wired source (no world mounted yet) reads an empty, correctly-
-    // versioned trace rather than throwing. Same default-world resolution as
-    // `input.actions` immediately above.
-    providers.set('input.trace', {
-        fn: () => {
-            const worldId = resolveWorldForSource(inputTraceSources.keys());
-            return ((worldId ? inputTraceSources.get(worldId) : undefined)?.() ?? {
-                version: 1,
-                seed: null,
-                fixedDt: null,
-                ticks: [],
-            });
-        },
-        tier: 'observable',
-        worldId: '__engine__',
-        builtin: true,
-    });
-    function registerStateProvider(worldId, name, fn, tier, token) {
-        const existing = providers.get(name);
-        if (existing?.builtin) {
-            // Defect 1 fix: a builtin name (`time`, `input.actions`) must never be
-            // silently shadowed — the old `!existing.builtin` guard skipped BOTH
-            // the collision throw and the warn for this case, so
-            // `registerStateProvider('time', ...)` quietly replaced engine truth,
-            // and a later `strip()` deleted it outright (leaving NO `time`
-            // provider at all post-hot-reload). Throw loudly instead; there is no
-            // silent-replace path for a builtin.
-            throw new DebugError('DEBUG_BUILTIN_RESERVED', `debug: "${name}" is a built-in state provider (registered by "${existing.worldId}") — ` +
-                'built-in names cannot be registered over, from a world or the react door', { name, registered: existing.worldId });
-        }
-        if (existing) {
-            if (existing.worldId !== worldId) {
-                throw new DebugError('DEBUG_NAME_COLLISION', `debug: state provider "${name}" is registered by both world "${existing.worldId}" ` +
-                    `and world "${worldId}" — each provider name must be unique across live roots`, { name, roots: [existing.worldId, worldId] });
-            }
-            warnOnce(warnedProviders, name, 'provider', worldId);
-        }
-        providers.set(name, { fn, tier, worldId, builtin: false, token });
-    }
-    function registerCommand(worldId, name, spec, fn, token) {
-        if (spec.locus === undefined && roomDeclared) {
-            throw new DebugError('DEBUG_COMMAND_LOCUS_REQUIRED', "this project declares a Colyseus room — declare locus: 'client' | 'server' so " +
-                'fixtures mutate authoritative state, not client prediction', { name, worldId });
-        }
-        const existing = commands.get(name);
-        if (existing) {
-            if (existing.worldId !== worldId) {
-                throw new DebugError('DEBUG_NAME_COLLISION', `debug: command "${name}" is registered by both world "${existing.worldId}" and ` +
-                    `world "${worldId}" — each command name must be unique across live roots`, { name, roots: [existing.worldId, worldId] });
-            }
-            warnOnce(warnedCommands, name, 'command', worldId);
-        }
-        commands.set(name, {
-            description: spec.description,
-            argsSchema: spec.args,
-            locus: spec.locus,
-            fn,
-            worldId,
-            token,
-        });
-    }
-    function emit(event, detail) {
-        seqCounter += 1;
-        ring.push({ tick: opts.getTick(), simT: opts.getSimT(), event, detail, seq: seqCounter });
-        if (ring.length > RING_CAP)
-            ring.shift();
-    }
-    /** See `DebugAdapter.events`'s doc comment (`adapter/system-adapter.ts`)
-     *  for the full contract — `sinceSeq` (when given) wins over `sinceTick`,
-     *  since it's the unambiguous one. */
-    function events(sinceTick, sinceSeq) {
-        if (sinceSeq !== undefined)
-            return ring.filter((e) => e.seq > sinceSeq);
-        if (sinceTick === undefined)
-            return ring.slice();
-        return ring.filter((e) => e.tick > sinceTick);
-    }
-    /**
-     * Task 2.2 — server-locus command routing (client leg). A `locus: 'server'`
-     * command never calls its own registered `fn` locally: `invoke()` instead
-     * sends the reserved room message `__vgai:debugCommand` and resolves on the
-     * matching `__vgai:debugCommandResult` reply, so a fixture mutates the
-     * AUTHORITATIVE (server) copy of state, not client prediction. Request ids
-     * are a monotonic per-registry counter (`dbg-<n>`), not `Math.random`/
-     * `Date.now`, so two in-flight commands never collide and correlation is
-     * trivially inspectable in logs.
-     */
-    function invokeServerCommand(name, args) {
-        if (!attachedRoom) {
-            throw new DebugError('DEBUG_COMMAND_FAILED', `debug: command "${name}" is locus:'server' but no Colyseus room is attached ` +
-                '(call ctx.debug.attachRoom(room) once your game joins its room)', { reason: 'no room connection' });
-        }
-        const requestId = `dbg-${++requestCounter}`;
-        const room = attachedRoom;
-        return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                pendingServerCommands.delete(requestId);
-                reject(new DebugError('DEBUG_COMMAND_FAILED', `debug: command "${name}" (requestId "${requestId}") timed out waiting for the server`, { reason: 'server timeout' }));
-            }, SERVER_COMMAND_TIMEOUT_MS);
-            pendingServerCommands.set(requestId, { resolve, reject, timer });
-            room.send('__vgai:debugCommand', { name, args, requestId });
-        });
-    }
-    // Defect 8 fix — the live detach() for whatever room is CURRENTLY attached
-    // (or null if none). `attachRoom` calls this itself before attaching a new
-    // room: without it, a second `attachRoom` call (no explicit `detach()` in
-    // between) left the first room's `__vgai:debugCommandResult` subscription
-    // live forever (a leak — the old room keeps getting messages dispatched to
-    // a handler nothing reads anymore) and stranded any of ITS in-flight
-    // commands riding the full 10s timeout with no way to ever be answered.
-    let detachCurrentRoom = null;
-    /** {@link DebugCtxSurface.attachRoom} — shared across every world's ctx
-     *  surface (game-scoped, last-attached room wins — and, since Defect 8,
-     *  actually CLEANS UP the previous attachment rather than merely
-     *  overwriting the pointer). Subscribes to the reserved
-     *  `__vgai:debugCommandResult` reply and resolves/rejects the matching
-     *  in-flight {@link invokeServerCommand} promise by `requestId`. */
-    function attachRoom(room) {
-        // Last-wins, but with cleanup: detach whatever room was attached before
-        // (unsubscribes its listener, rejects ITS in-flight pendings — see
-        // `detach` below) rather than leaking it.
-        detachCurrentRoom?.();
-        attachedRoom = room;
-        const unsubscribe = room.onMessage('__vgai:debugCommandResult', (message) => {
-            const reply = message;
-            const requestId = reply?.requestId;
-            if (requestId === undefined)
-                return;
-            const pending = pendingServerCommands.get(requestId);
-            if (!pending)
-                return;
-            pendingServerCommands.delete(requestId);
-            clearTimeout(pending.timer);
-            if (reply?.ok) {
-                pending.resolve(reply.result);
-            }
-            else {
-                pending.reject(new DebugError('DEBUG_COMMAND_FAILED', `debug: server command failed: ${String(reply?.error)}`, { cause: reply?.error }));
-            }
-        });
-        const detach = () => {
-            // Idempotent, and a no-op if a LATER attachRoom already superseded
-            // this attachment (its own detach ran first via detachCurrentRoom?.()
-            // above) — calling this stale detach again must not clobber the new
-            // attachment's state.
-            if (detachCurrentRoom !== detach)
-                return;
-            detachCurrentRoom = null;
-            if (attachedRoom === room)
-                attachedRoom = null;
-            if (typeof unsubscribe === 'function')
-                unsubscribe();
-            // Defect 8 fix: reject every command still awaiting THIS room's reply
-            // right now, rather than let it silently ride out the full 10s
-            // `SERVER_COMMAND_TIMEOUT_MS` with no room left to ever answer it.
-            for (const [requestId, pending] of pendingServerCommands) {
-                clearTimeout(pending.timer);
-                pending.reject(new DebugError('DEBUG_COMMAND_FAILED', `debug: command (requestId "${requestId}") failed — its room was detached before a reply arrived`, { reason: 'no room connection' }));
-            }
-            pendingServerCommands.clear();
-        };
-        detachCurrentRoom = detach;
-        return detach;
-    }
-    const adapter = {
-        providers() {
-            return [...providers.entries()].map(([name, entry]) => ({ name, tier: entry.tier }));
-        },
-        state(name) {
-            const entry = providers.get(name);
-            if (!entry) {
-                throw new DebugError('STATE_PROVIDER_NOT_FOUND', `debug: no state provider registered under "${name}"`, {
-                    registered: [...providers.keys()],
-                    registrationHint: REGISTRATION_HINT,
-                });
-            }
-            return entry.fn();
-        },
-        stateAll() {
-            const result = {};
-            for (const [name, entry] of providers) {
-                try {
-                    result[name] = entry.fn();
-                }
-                catch (err) {
-                    result[name] = { __error: String(err) };
-                }
-            }
-            return result;
-        },
-        commands() {
-            return [...commands.entries()].map(([name, entry]) => ({
-                name,
-                description: entry.description,
-                argsJsonSchema: entry.argsSchema
-                    ? z.toJSONSchema(entry.argsSchema, { unrepresentable: 'any' })
-                    : undefined,
-                locus: entry.locus ?? 'client',
-            }));
-        },
-        async invoke(name, args) {
-            const entry = commands.get(name);
-            if (!entry) {
-                throw new DebugError('DEBUG_COMMAND_NOT_REGISTERED', `debug: no command registered under "${name}"`, { registered: [...commands.keys()], registrationHint: REGISTRATION_HINT });
-            }
-            let parsedArgs = args;
-            if (entry.argsSchema) {
-                const result = entry.argsSchema.safeParse(args);
-                if (!result.success) {
-                    throw new DebugError('DEBUG_COMMAND_ARGS_INVALID', `debug: command "${name}" received invalid args`, { issues: result.error.issues });
-                }
-                parsedArgs = result.data;
-            }
-            if ((entry.locus ?? 'client') === 'server') {
-                return invokeServerCommand(name, parsedArgs);
-            }
-            try {
-                return await entry.fn(...parsedArgs);
-            }
-            catch (cause) {
-                throw new DebugError('DEBUG_COMMAND_FAILED', `debug: command "${name}" threw`, { cause });
-            }
-        },
-        events(sinceTick, sinceSeq) {
-            return events(sinceTick, sinceSeq);
-        },
-    };
-    return {
-        adapter,
-        forWorld(worldId) {
-            return {
-                registerStateProvider(name, fn, providerOpts) {
-                    registerStateProvider(worldId, name, fn, providerOpts?.tier ?? 'observable');
-                },
-                registerCommand(name, spec, fn) {
-                    // Cast: the public generic (`DebugCtxSurface.registerCommand`,
-                    // `DebugCommandArgs<T>`) exists purely for the CALLER's inference —
-                    // internally, every entry is stored/invoked through the same
-                    // untyped `(...args: unknown[])` shape (`invoke()` parses `args`
-                    // against `argsSchema` at the seam, not at the type level).
-                    registerCommand(worldId, name, spec, fn);
-                },
-                emit(event, detail) {
-                    emit(event, detail);
-                },
-                attachRoom(room) {
-                    return attachRoom(room);
-                },
-            };
-        },
-        emitReact(event, detail) {
-            emit(event, detail);
-        },
-        strip(worldId) {
-            // Defect 2 fix — scoped when `worldId` is given (a single mount's
-            // hot-reload re-seed), global otherwise (the whole game going away, or
-            // a test's blanket teardown). See this method's interface doc comment.
-            for (const [name, entry] of providers) {
-                if (entry.builtin)
-                    continue;
-                if (worldId !== undefined && entry.worldId !== worldId)
-                    continue;
-                providers.delete(name);
-                warnedProviders.delete(name);
-            }
-            for (const [name, entry] of commands) {
-                if (worldId !== undefined && entry.worldId !== worldId)
-                    continue;
-                commands.delete(name);
-                warnedCommands.delete(name);
-            }
-        },
-        setRoomDeclared(declared) {
-            roomDeclared = declared;
-        },
-        setInputActionsSource(worldId, fn) {
-            inputActionsSources.set(worldId, fn);
-        },
-        setInputTraceSource(worldId, fn) {
-            inputTraceSources.set(worldId, fn);
-        },
-        setVirtualInputTarget(worldId, target) {
-            virtualInputTargets.set(worldId, target);
-        },
-        getVirtualInputTarget(worldId) {
-            const resolved = resolveInputWorldId(worldId);
-            return resolved !== null ? (virtualInputTargets.get(resolved) ?? null) : null;
-        },
-        setRunTicksTarget(target) {
-            runTicksTarget = target;
-        },
-        getRunTicksTarget() {
-            return runTicksTarget;
-        },
-        getGameTick() {
-            return opts.getTick();
-        },
-        registerReactProvider(name, fn, providerOpts) {
-            const token = Symbol(name);
-            registerStateProvider(REACT_WORLD_ID, name, fn, providerOpts?.tier ?? 'observable', token);
-            return () => {
-                const entry = providers.get(name);
-                if (entry?.token === token) {
-                    providers.delete(name);
-                    warnedProviders.delete(name);
-                }
-            };
-        },
-        registerReactCommand(name, spec, fn) {
-            const token = Symbol(name);
-            // See the `forWorld().registerCommand` cast above — same reason.
-            registerCommand(REACT_WORLD_ID, name, spec, fn, token);
-            return () => {
-                const entry = commands.get(name);
-                if (entry?.token === token) {
-                    commands.delete(name);
-                    warnedCommands.delete(name);
-                }
-            };
-        },
-    };
-}
-const registryByGame = new WeakMap();
-/** Called once by `createGame`, right after both the registry and the Game
- *  shell object exist, to file the association {@link getDebugRegistry} reads. */
-export function registerDebugRegistry(game, registry) {
-    registryByGame.set(game, registry);
-}
-/** The game-scoped registry backing `game.systemAdapters.debug`, or `null` for
- *  a `Game` built without one (there is always one for every `createGame`
- *  call — `null` only for a `Game`-shaped stand-in a test builds by hand). */
-export function getDebugRegistry(game) {
-    return registryByGame.get(game) ?? null;
-}

package/dist/runtime/frame-selector-cache.d.ts

@@ -1,41 +0,0 @@
-/**
- * Pure, react-free frame-version cache (T7.4 slice 1 — `docs/
- * REACT-STATE-BRIDGE.md` §3). `useGameState` (`packages/editor/template/src/
- * ui/game-state.tsx`) is a thin `useSyncExternalStore` wrapper
- * around this: `getSnapshot` re-runs the selector once per `frameVersion`
- * bump (`GameStateBridge`, `runtime/state-bridge.ts`), caches by version,
- * and returns the PREVIOUS reference when `equals` holds against the fresh
- * result — that reference stability is what lets `useSyncExternalStore`
- * (and thus React) bail out of a re-render.
- *
- * Extracted to its own react-free module (no react import here, or anywhere
- * under `runtime/`) so this cache/equality logic — the part of the hook
- * that has real branching to get wrong — is unit-testable headlessly under
- * `packages/engine/test/`, without needing a react test harness (none
- * exists in this repo today; see `test/frame-selector-cache.test.ts`).
- */
-/** Equality comparator for `FrameSelectorCache`/`useGameState`. Defaults to
- *  `Object.is` (T7.4 §3); pass {@link shallow} for tuples/plain objects. */
-export type Equals<T> = (a: T, b: T) => boolean;
-/**
- * One-level shallow-equality helper (own enumerable keys, `Object.is` per
- * value) — the opt-in equality for selectors that return a fresh
- * object/array/tuple every call. Two non-object values fall back to
- * `Object.is`; a non-object compared against an object is never equal.
- */
-export declare function shallow<T>(a: T, b: T): boolean;
-export interface FrameSelectorCache<T> {
-    /**
-     * Return the cached value for `frameVersion` if it's the SAME version as
-     * the last call (selector not re-run at all). Otherwise call `compute()`
-     * once: if the fresh result is `equals` to the previously cached value,
-     * the PREVIOUS reference is returned (and re-tagged with this
-     * `frameVersion`, so the next same-version call also short-circuits);
-     * otherwise the fresh value is cached and returned.
-     */
-    get(frameVersion: number, compute: () => T): T;
-}
-/** Construct a fresh per-subscriber cache. One per `useGameState` call site
- *  (a fresh cache each mount — see the hook). */
-export declare function createFrameSelectorCache<T>(equals?: Equals<T>): FrameSelectorCache<T>;
-//# sourceMappingURL=frame-selector-cache.d.ts.map

package/dist/runtime/frame-selector-cache.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"frame-selector-cache.d.ts","sourceRoot":"","sources":["../../src/runtime/frame-selector-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;4EAC4E;AAC5E,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;AAEhD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,GAAG,OAAO,CAa9C;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC;;;;;;;OAOG;IACH,GAAG,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;CAChD;AAED;iDACiD;AACjD,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAwBhG"}

package/dist/runtime/frame-selector-cache.js

@@ -1,65 +0,0 @@
-/**
- * Pure, react-free frame-version cache (T7.4 slice 1 — `docs/
- * REACT-STATE-BRIDGE.md` §3). `useGameState` (`packages/editor/template/src/
- * ui/game-state.tsx`) is a thin `useSyncExternalStore` wrapper
- * around this: `getSnapshot` re-runs the selector once per `frameVersion`
- * bump (`GameStateBridge`, `runtime/state-bridge.ts`), caches by version,
- * and returns the PREVIOUS reference when `equals` holds against the fresh
- * result — that reference stability is what lets `useSyncExternalStore`
- * (and thus React) bail out of a re-render.
- *
- * Extracted to its own react-free module (no react import here, or anywhere
- * under `runtime/`) so this cache/equality logic — the part of the hook
- * that has real branching to get wrong — is unit-testable headlessly under
- * `packages/engine/test/`, without needing a react test harness (none
- * exists in this repo today; see `test/frame-selector-cache.test.ts`).
- */
-/**
- * One-level shallow-equality helper (own enumerable keys, `Object.is` per
- * value) — the opt-in equality for selectors that return a fresh
- * object/array/tuple every call. Two non-object values fall back to
- * `Object.is`; a non-object compared against an object is never equal.
- */
-export function shallow(a, b) {
-    if (Object.is(a, b))
-        return true;
-    if (typeof a !== 'object' || a === null || typeof b !== 'object' || b === null) {
-        return false;
-    }
-    const aKeys = Object.keys(a);
-    const bKeys = Object.keys(b);
-    if (aKeys.length !== bKeys.length)
-        return false;
-    const bRecord = b;
-    for (const key of aKeys) {
-        if (!Object.is(a[key], bRecord[key]))
-            return false;
-    }
-    return true;
-}
-/** Construct a fresh per-subscriber cache. One per `useGameState` call site
- *  (a fresh cache each mount — see the hook). */
-export function createFrameSelectorCache(equals = Object.is) {
-    let hasValue = false;
-    let cachedVersion = -1;
-    let cachedValue;
-    return {
-        get(frameVersion, compute) {
-            if (hasValue && frameVersion === cachedVersion) {
-                return cachedValue;
-            }
-            const next = compute();
-            if (hasValue && equals(cachedValue, next)) {
-                // Bail-out: keep the PREVIOUS reference, but remember we're current
-                // as of this frameVersion so a repeat call at the same version
-                // doesn't even re-run `compute`.
-                cachedVersion = frameVersion;
-                return cachedValue;
-            }
-            cachedValue = next;
-            cachedVersion = frameVersion;
-            hasValue = true;
-            return cachedValue;
-        },
-    };
-}