@vgai/engine 0.5.4 → 0.5.6

package/dist/runtime/debug-registry.js

@@ -0,0 +1,528 @@
+/**
+ * The game-scoped debug/synthetic-player registry. ONE registry per `Game` root —
+ * every world's `ctx.debug` (see `DebugCtxSurface`, `runtime/types.ts`) feeds the
+ * SAME registry via {@link DebugRegistry.forRoot}, 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, ...)` / `SetupThreeRootConfig.id` a project already names each
+ * world's entry with) rather than the `RootInstance.id` `registerThreeRoot`
+ * assigns — that id isn't known until AFTER `mount()` resolves (`create-
+ * runtime.ts` calls `registerThreeRoot` 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 `'setup-three'`;
+ * 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';
+/** A thrown value flattened to JSON-SAFE fields. Every caller of a debug
+ *  command is on the far side of a JSON boundary — the editor session relay
+ *  (`POST /__editor/command`) and `page.evaluate` both serialize the error's
+ *  `data` bag — and an `Error` stringifies to `{}` there, so a command's own
+ *  refusal text ("no such waypoint") vanished and the developer at
+ *  `vgai eval` saw only `debug: command "x" threw`. The text has to travel as
+ *  plain strings, and in the `message` above all: that is the one field every
+ *  client (`SessionError`, the CLI's own error print) actually surfaces. */
+function describeCause(cause) {
+    if (cause instanceof Error) {
+        const described = { causeName: cause.name, causeMessage: cause.message };
+        return cause.stack === undefined ? described : { ...described, causeStack: cause.stack };
+    }
+    return { causeName: typeof cause, causeMessage: String(cause) };
+}
+/** 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 first-party 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: 'dom'` world whose `id` is `"react"`) — `forRoot('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). `getDefaultRootId`
+ * (D15/T-D15.5, optional) resolves the manifest's first/default world id —
+ * `createGame` passes `() => (roots.length ? requireDefaultRoot().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
+ * `resolveInputRootId`). `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
+    // `resolveInputRootId`'s "whichever registered first" fallback relies on
+    // when no `getDefaultRootId` 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.getDefaultRootId()`) 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 resolveInputRootId(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 resolveRootForSource(virtualInputTargets.keys());
+    }
+    /** The same "default world, else the one registered, else whichever
+     *  registered first" fallback {@link resolveInputRootId} 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 resolveRootForSource(registered) {
+        const ids = [...registered];
+        if (ids.length === 0)
+            return null;
+        const defaultId = opts.getDefaultRootId?.() ?? 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 `resolveInputRootId`)
+        // — deterministic across every world that registers, rather than the
+        // pre-D15.5 "whichever mounted last" behavior.
+        fn: () => {
+            const worldId = resolveRootForSource(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 = resolveRootForSource(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 — `seq` is the ONLY fence (the defective
+     *  `sinceTick` filter was removed). */
+    function events(sinceSeq) {
+        if (sinceSeq === undefined)
+            return ring.slice();
+        return ring.filter((e) => e.seq > sinceSeq);
+    }
+    /**
+     * 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) {
+                // `cause` stays for in-process readers; the flattened fields are what
+                // survive the wire (see `describeCause`).
+                const described = describeCause(cause);
+                throw new DebugError('DEBUG_COMMAND_FAILED', `debug: command "${name}" threw: ${described.causeMessage}`, { cause, ...described });
+            }
+        },
+        events(sinceSeq) {
+            return events(sinceSeq);
+        },
+    };
+    return {
+        adapter,
+        forRoot(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 = resolveInputRootId(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 `forRoot().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/dev-layers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * THE one owner of "are dev layers enabled" (`vgai.project.json`'s `dev: true`
+ * root flag). Every reader that has to answer that question calls
+ * {@link devLayersEnabled}; there is deliberately NO second source of truth —
+ * not a module-level cached boolean, not a `globalThis` flag, not a per-host
+ * copy of the `import.meta.env` read below. A dev GUI that ships to players
+ * because two places disagreed about what "dev" means is exactly the failure
+ * this single owner exists to make impossible.
+ *
+ * Ownership, stated in one place (the build rule):
+ *  - OWNER: this function. It resolves the answer; nothing else derives it.
+ *  - SHARERS: `mountManifestRoots` (the ship gate — a dev root only mounts
+ *    when this returns true). Any future host that mounts manifest roots
+ *    itself calls this too, with its own `override`.
+ *  - TEARDOWN: none. This is a pure predicate over build config and one
+ *    caller-supplied argument — it owns no resource, allocates nothing, and
+ *    has no lifecycle to end.
+ *
+ * The three inputs, highest precedence first:
+ *  1. `override` — the explicit per-mount answer. A headless test, a capture
+ *     harness, or a host that knows better passes `true`/`false` and gets
+ *     exactly that. Passing `undefined` (or omitting it) means "decide for
+ *     me" and falls through.
+ *  2. A dev build — `import.meta.env.DEV`. The ordinary local/editor case:
+ *     dev layers are on.
+ *  3. A production build's EXPLICIT opt-in — `VITE_VGAI_DEV_LAYERS=true`.
+ *     Shipping the dev GUI in a production bundle is a real, legitimate
+ *     choice (an internal playtest build, a QA build), and it must be an
+ *     opt-in someone had to type, never something a default drifts into.
+ *
+ * Anything else — a production build with no opt-in — is `false`.
+ */
+export declare function devLayersEnabled(override?: boolean | undefined): boolean;
+//# sourceMappingURL=dev-layers.d.ts.map

package/dist/runtime/dev-layers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-layers.d.ts","sourceRoot":"","sources":["../../src/runtime/dev-layers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,GAAG,OAAO,CAOxE"}

package/dist/runtime/dev-layers.js

@@ -0,0 +1,40 @@
+/**
+ * THE one owner of "are dev layers enabled" (`vgai.project.json`'s `dev: true`
+ * root flag). Every reader that has to answer that question calls
+ * {@link devLayersEnabled}; there is deliberately NO second source of truth —
+ * not a module-level cached boolean, not a `globalThis` flag, not a per-host
+ * copy of the `import.meta.env` read below. A dev GUI that ships to players
+ * because two places disagreed about what "dev" means is exactly the failure
+ * this single owner exists to make impossible.
+ *
+ * Ownership, stated in one place (the build rule):
+ *  - OWNER: this function. It resolves the answer; nothing else derives it.
+ *  - SHARERS: `mountManifestRoots` (the ship gate — a dev root only mounts
+ *    when this returns true). Any future host that mounts manifest roots
+ *    itself calls this too, with its own `override`.
+ *  - TEARDOWN: none. This is a pure predicate over build config and one
+ *    caller-supplied argument — it owns no resource, allocates nothing, and
+ *    has no lifecycle to end.
+ *
+ * The three inputs, highest precedence first:
+ *  1. `override` — the explicit per-mount answer. A headless test, a capture
+ *     harness, or a host that knows better passes `true`/`false` and gets
+ *     exactly that. Passing `undefined` (or omitting it) means "decide for
+ *     me" and falls through.
+ *  2. A dev build — `import.meta.env.DEV`. The ordinary local/editor case:
+ *     dev layers are on.
+ *  3. A production build's EXPLICIT opt-in — `VITE_VGAI_DEV_LAYERS=true`.
+ *     Shipping the dev GUI in a production bundle is a real, legitimate
+ *     choice (an internal playtest build, a QA build), and it must be an
+ *     opt-in someone had to type, never something a default drifts into.
+ *
+ * Anything else — a production build with no opt-in — is `false`.
+ */
+export function devLayersEnabled(override) {
+    if (override !== undefined)
+        return override;
+    const env = import.meta.env;
+    if (env?.DEV === true)
+        return true;
+    return env?.VITE_VGAI_DEV_LAYERS === 'true';
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Pure, react-free frame-version cache (T7.4 slice 1).
+ * `useWorldState` (`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`/`useWorldState`. 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 `useWorldState` 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

@@ -0,0 +1 @@
+{"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"}