@vgai/engine 0.5.0 → 0.5.2

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

@@ -1,257 +0,0 @@
-/**
- * The standalone in-page debug bridge (`docs/SYNTHETIC-PLAYER-SPEC.md` §3.4,
- * D17/D18; Task 2.1 of `docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md`). Query-gated
- * `window.__vgai`, the same production-protection-lives-in-the-installer
- * pattern `render-control.ts`'s `installRenderControlHarness` established for
- * `?vgai-render=1` (production protection lives HERE, not just at whatever
- * call site invokes this — a caller that calls
- * {@link maybeInstallDebugBridge} unconditionally on every boot still only
- * ever gets a handle when the gate below actually passes).
- *
- * D17: this is door (a) of the seam's three doors — the SAME `DebugAdapter`
- * names/JSON the editor relay (door b) and `@vgai/probe` (door c, which
- * drives door (a) itself over Playwright) all read. D18: the bridge installs
- * only when the page opts in (`?vgai-debug=1`) AND is either a dev build
- * (`import.meta.env.DEV`) or the project's manifest explicitly opts a
- * production build in (`manifest.debug.allowInProduction`, the described
- * field whose runtime reader THIS module is).
- */
-import type { DebugAdapter, TickStampedEvent } from '../adapter/system-adapter';
-import type { GameLoopLiveness } from '../core/types';
-import { type DebugRegistry, type RunTicksOptions } from './debug-registry';
-/** Query-param name that opts a standalone page into the debug bridge (D18) —
- *  mirrors `render-seed.ts`'s `RENDER_MODE_QUERY_PARAM` naming/shape, own
- *  const because this is a different call site with a different flag. */
-export declare const DEBUG_MODE_QUERY_PARAM = "vgai-debug";
-/** The subset of `ResolvedGameManifest` the D18 gate reads — typed narrowly
- *  (not imported from `manifest/load.ts`) so this module doesn't need the
- *  full manifest shape, just the one described field it is the runtime
- *  reader for. */
-export interface DebugBridgeManifest {
-    readonly debug?: {
-        readonly allowInProduction: boolean;
-    } | undefined;
-}
-/** The bridge's actuation surface — byte-identical method names to
- *  `InputManager`'s virtual-action primitives (Task 1.4), reached through
- *  `DebugRegistry.getVirtualInputTarget(worldId?)` rather than a direct
- *  import. Every method takes an optional trailing `worldId` (D15/T-D15.5,
- *  the review-objection-2 fix): omitted, it resolves to the SAME default
- *  world the editor relay's `inject-input` case resolves to (one shared
- *  resolution function, `debug-registry.ts`'s `resolveInputWorldId`) — never
- *  "whichever world's `InputManager` happened to register last". An
- *  explicit `worldId` reaches that world's `InputManager` specifically. */
-export interface VgaiDebugInputHandle {
-    setVirtualAction(action: string, value: boolean | number | {
-        x: number;
-        y: number;
-    }, worldId?: string): {
-        delivered: boolean;
-        reason?: string;
-    };
-    tapVirtualAction(action: string, worldId?: string): {
-        delivered: boolean;
-        reason?: string;
-    };
-    clearVirtualActions(worldId?: string): void;
-    /**
-     * D15/T-D15.5 (`docs/D15-DETERMINISM-DESIGN.md` §2.c): schedule a virtual
-     * actuation for a specific tick — applied at the START of that tick's
-     * input phase, composing with `runTicks` (a schedule for tick 500 fires
-     * exactly once the sim has been driven through tick 500, regardless of
-     * burst size). A digital `true` produces a genuine `isJustPressed` edge
-     * exactly at the target tick. Throws `INPUT_ACTION_NOT_FOUND`/a valueType
-     * mismatch (same as `setVirtualAction`) or `TICK_ALREADY_PASSED`
-     * (`data.currentTick`, the NEXT tick to be serviced) for a tick that
-     * already elapsed.
-     *
-     * A scheduled tick whose input phase never runs at all (that world
-     * paused/frozen, or skipped by a multi-tick gap, when the target tick
-     * would have been serviced) DROPS the actuation rather than applying it
-     * late — it is never delivered, and there is no `{delivered: false,
-     * reason}`-shaped result to read here (the call already returned, long
-     * before the drop happens). The only observable trace is an
-     * `'input.schedule.dropped'` debug event (`{tick, action}`), readable via
-     * `state()`/`stateAll()`'s `events` or `snapshot().events`.
-     */
-    scheduleActionAtTick(tick: number, action: string, value: boolean | number | {
-        x: number;
-        y: number;
-    }, worldId?: string): void;
-    /** Start (or restart) recording the post-gate action-delta trace, readable
-     *  back via `state('input.trace')`/`stateAll()` (a built-in provider —
-     *  itself resolved against the DEFAULT world only; see that provider's own
-     *  doc comment in `debug-registry.ts`). */
-    startRecording(worldId?: string): void;
-    /** Stop recording — the trace accumulated so far stays readable. */
-    stopRecording(worldId?: string): void;
-    /** Whether a recording is currently active. */
-    isRecording(worldId?: string): boolean;
-    /** Accumulate a synthetic pointer delta for a named test source — mirrors
-     *  `InputManager.injectPointerDelta` (the "injected test input" seam):
-     *  multiple calls within the same frame SUM, and the accumulator clears
-     *  each frame (`endFrame`). Bindings with `valueType: 'pointerDelta'`
-     *  reading this source (`{ type: 'test_pointer_delta', sourceId }`) see the
-     *  accumulated value via `getPointerDelta`. */
-    injectPointerDelta(sourceId: string, delta: {
-        x: number;
-        y: number;
-    }, worldId?: string): void;
-    /** Set a synthetic absolute pointer position for a named test source —
-     *  mirrors `InputManager.injectPointerPosition`: LAST-WRITE-WINS across
-     *  contributing sources on read, and persists until changed. Bindings with
-     *  `valueType: 'pointerPosition'` reading this source (`{ type:
-     *  'test_pointer_position', sourceId }`) see it via `getPointerPosition`. */
-    injectPointerPosition(sourceId: string, value: {
-        x: number;
-        y: number;
-    }, worldId?: string): void;
-}
-/** `snapshot()`'s return shape — ONE synchronous pass over the registry, so
- *  every field reflects the exact same instant (AC-B1.2's batched-read
- *  primitive: a probe polling this never sees `time` from one tick and
- *  `state` from another). */
-export interface VgaiDebugSnapshot {
-    /** `loopLiveness` (issue #175): the REAL `GameLoop.liveness` behind this
-     *  session — `'hidden-paused'` while the T2.1 idle throttle has stopped
-     *  the loop (tab hidden), `null` only when no loop is wired at all (a
-     *  bare debug-registry test stand-in with no real `Game`). Never a
-     *  fabricated `'running'`. */
-    time: {
-        simSeconds: number;
-        tick: number;
-        loopLiveness: GameLoopLiveness | null;
-    };
-    state: Record<string, unknown>;
-    events: TickStampedEvent[];
-    pageErrors: string[];
-}
-/** The frozen `window.__vgai` shape (D18/spec §3.4) — version it if it ever
- *  needs a breaking change; `providers`/`state`/`stateAll`/`commands`/`events`
- *  are straight off the game's `DebugAdapter`, `invoke` re-checks D18 gating
- *  (belt-and-braces, AC-A1.7), and `input`/`snapshot` are bridge-only. */
-export interface VgaiDebugHandle {
-    readonly version: 1;
-    providers: DebugAdapter['providers'];
-    state: DebugAdapter['state'];
-    stateAll: DebugAdapter['stateAll'];
-    commands: DebugAdapter['commands'];
-    invoke(name: string, args: unknown[]): Promise<unknown>;
-    events: DebugAdapter['events'];
-    input: VgaiDebugInputHandle;
-    /** See `DebugAdapter.events`'s doc comment for `sinceTick`/`sinceSeq`'s
-     *  contract (run-4 friction #5) — `snapshot`'s `events` member is filtered
-     *  the exact same way, just batched with `time`/`state`/`pageErrors` into
-     *  one synchronous read. */
-    snapshot(sinceTick?: number, sinceSeq?: number): VgaiDebugSnapshot;
-    /**
-     * D15/T-D15.4 door (a) (`docs/D15-DETERMINISM-DESIGN.md` §2.b): synchronously
-     * drive `n` fixed gameplay ticks via the live `Game`'s `GameInternal.runTicks`
-     * (`runtime/game.ts`) — reached through `DebugRegistry.getRunTicksTarget()`,
-     * the SAME target the editor relay's `run-ticks` case (→ `play.runTicks`,
-     * door b) calls, so behavior is byte-identical across every door (D17).
-     * Throws `DEBUG_RUN_TICKS_UNAVAILABLE` if no `Game` has wired a target yet
-     * (no world mounted); throws whatever `runTicks` itself throws otherwise
-     * (e.g. `RUN_TICKS_PAUSED`) — never a silent no-op.
-     */
-    runTicks(n: number, opts?: RunTicksOptions): void;
-    /**
-     * Collapses `input.setVirtualAction(action, true)` → wait `simSeconds` of
-     * REAL sim time (real ticks — deliberately NOT `runTicks`/fast-forward;
-     * this is the honest human-input-path proof) → `input.clearVirtualActions()`
-     * into ONE async bridge call, as a TOP-LEVEL method (not under `input`)
-     * because it needs the sim clock, not just the input target. Was 15+
-     * transport round trips over the editor relay (`@vgai/probe`'s old
-     * `GameInput.hold`: set → a 150ms-interval `waitSimTime` snapshot poll loop
-     * → clear); now one `page.evaluate`/relay call that runs the wait
-     * in-process on the page.
-     *
-     * Resolves the world's input target exactly like the other `input.*`
-     * methods (`worldId` omitted → the same default-world resolution every
-     * door on this seam shares). A gated actuation (the initial
-     * `setVirtualAction` reports `delivered:false`) clears immediately and
-     * resolves that SAME `{delivered:false, reason}` shape WITHOUT waiting —
-     * matching `setVirtualAction`'s own gated-result contract. If the live
-     * game's sim clock stalls while waiting (play stopped/paused mid-hold),
-     * the action is still cleared (never left stuck) and this resolves
-     * `{delivered:false, reason:'play stopped during hold'}` instead of
-     * hanging forever. Throws `DEBUG_INPUT_UNAVAILABLE`/
-     * `DEBUG_INPUT_WORLD_NOT_FOUND` up front, same as `input.setVirtualAction`,
-     * when no target is wired/resolvable at all.
-     */
-    holdFor(action: string, simSeconds: number, worldId?: string): Promise<{
-        delivered: boolean;
-        reason?: string;
-    }>;
-    /**
-     * Defect 5 fix — undo everything THIS install did: remove the
-     * `error`/`unhandledrejection` window listeners it added, and delete
-     * `window.__vgai` so the registry is no longer reachable from the page.
-     * Idempotent (a second call is a harmless no-op). `mountManifestWorlds`
-     * wires this into its session's `stop()`; a caller mounting more
-     * directly (a hand-rolled host) should call it on its own teardown path.
-     */
-    uninstall(): void;
-}
-/** Structural `window` surface this module needs — just enough to publish
- *  the handle and listen for page errors, typed narrowly (no `any`, no DOM
- *  lib dependency beyond what every other runtime module already assumes). */
-export interface DebugBridgeWindowTarget {
-    addEventListener?(type: 'error' | 'unhandledrejection', listener: (event: {
-        message?: string;
-        error?: unknown;
-        reason?: unknown;
-    }) => void): void;
-    /** Defect 5 fix — the installer's `uninstall()` calls this (when present)
-     *  to remove the exact listener references it added via `addEventListener`
-     *  above. Optional, like `addEventListener`, so a minimal test/host stub
-     *  that never needs to uninstall can omit it. */
-    removeEventListener?(type: 'error' | 'unhandledrejection', listener: (event: {
-        message?: string;
-        error?: unknown;
-        reason?: unknown;
-    }) => void): void;
-    [key: string]: unknown;
-}
-export interface MaybeInstallDebugBridgeOptions {
-    /** The game-scoped registry (`getDebugRegistry(session.game)`) — its
-     *  `.adapter` backs every read/invoke method on the published handle, and
-     *  its `getVirtualInputTarget()` backs `input.*`. */
-    readonly registry: DebugRegistry;
-    readonly manifest: DebugBridgeManifest;
-    /** Where to read `?vgai-debug=1` from. Defaults to `window.location` when a
-     *  real `window` exists; a headless caller with no `window` at all (and no
-     *  override) gets no bridge — there's nowhere to read a URL from. */
-    readonly url?: {
-        readonly search: string;
-    } | undefined;
-    /** Where to publish the handle and install the page-error listeners.
-     *  Defaults to the real `window`; override in a unit test to avoid
-     *  touching (or requiring) the global object. */
-    readonly window?: DebugBridgeWindowTarget | undefined;
-}
-/** Resolves once `simSeconds` of sim time has elapsed since the call (normal
- *  host-loop ticks while visible; deterministic `runTicks` through the same
- *  game phases when the host loop reports `hidden-paused`), or once the tick
- *  has stopped changing for
- *  `HOLD_FOR_STALL_POLL_LIMIT` consecutive polls (`stalled: true` — the loop
- *  driving ticks stopped, e.g. play was stopped/paused). Never rejects.
- *  Exported (not just used by `holdFor` below) so the editor relay's
- *  `command-listener.ts` `holdFor` case can share the EXACT same
- *  poll/stall/hidden-drive logic against its own `DebugAdapter` (reached via
- *  `getActiveSystems().debug` rather than a `DebugRegistry`) — D17:
- *  byte-identical behavior across doors, not two hand-copies that can
- *  silently drift apart. */
-export declare function waitForHoldBudget(adapter: DebugAdapter, simSeconds: number, driveHiddenTicks?: (n: number) => void): Promise<{
-    stalled: boolean;
-}>;
-/**
- * Install `window.__vgai` iff the page opted in (`?vgai-debug=1`) AND D18's
- * gate passes (dev build, or manifest `debug.allowInProduction`). When the
- * param is present but the gate fails, warns once (this single call IS the
- * "once" — there is exactly one install attempt per boot) and installs
- * nothing. Returns the installed handle (mostly useful for tests), or
- * `undefined` when nothing was installed.
- */
-export declare function maybeInstallDebugBridge(opts: MaybeInstallDebugBridgeOptions): VgaiDebugHandle | undefined;
-//# sourceMappingURL=debug-bridge.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"debug-bridge.d.ts","sourceRoot":"","sources":["../../src/runtime/debug-bridge.ts"],"names":[],"mappings":"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"}

package/dist/runtime/debug-bridge.js

@@ -1,224 +0,0 @@
-/**
- * The standalone in-page debug bridge (`docs/SYNTHETIC-PLAYER-SPEC.md` §3.4,
- * D17/D18; Task 2.1 of `docs/ACCEPTANCE-DRIVER-BUILD-PLAN.md`). Query-gated
- * `window.__vgai`, the same production-protection-lives-in-the-installer
- * pattern `render-control.ts`'s `installRenderControlHarness` established for
- * `?vgai-render=1` (production protection lives HERE, not just at whatever
- * call site invokes this — a caller that calls
- * {@link maybeInstallDebugBridge} unconditionally on every boot still only
- * ever gets a handle when the gate below actually passes).
- *
- * D17: this is door (a) of the seam's three doors — the SAME `DebugAdapter`
- * names/JSON the editor relay (door b) and `@vgai/probe` (door c, which
- * drives door (a) itself over Playwright) all read. D18: the bridge installs
- * only when the page opts in (`?vgai-debug=1`) AND is either a dev build
- * (`import.meta.env.DEV`) or the project's manifest explicitly opts a
- * production build in (`manifest.debug.allowInProduction`, the described
- * field whose runtime reader THIS module is).
- */
-import { DebugError } from './debug-registry';
-/** Query-param name that opts a standalone page into the debug bridge (D18) —
- *  mirrors `render-seed.ts`'s `RENDER_MODE_QUERY_PARAM` naming/shape, own
- *  const because this is a different call site with a different flag. */
-export const DEBUG_MODE_QUERY_PARAM = 'vgai-debug';
-const PAGE_ERROR_CAP = 100;
-/** `holdFor`'s in-process poll interval — this loop never leaves the page
- *  (no transport round trip per poll, unlike `@vgai/probe`'s old
- *  `waitSimTime`), so it can afford to be tighter than that loop's 150ms. */
-const HOLD_FOR_POLL_MS = 50;
-/** Consecutive `HOLD_FOR_POLL_MS` polls with the tick unchanged before
- *  `holdFor` gives up waiting and treats the game as stopped — mirrors
- *  `@vgai/probe`'s `WAIT_FOR_STALL_POLL_LIMIT` reasoning (`wait-for.ts`:
- *  a genuinely frozen sim clock must never poll forever), scaled to this
- *  faster in-process interval so the wall-clock grace period (~5s) lands in
- *  the same neighborhood. */
-const HOLD_FOR_STALL_POLL_LIMIT = 100;
-/** Resolves once `simSeconds` of sim time has elapsed since the call (normal
- *  host-loop ticks while visible; deterministic `runTicks` through the same
- *  game phases when the host loop reports `hidden-paused`), or once the tick
- *  has stopped changing for
- *  `HOLD_FOR_STALL_POLL_LIMIT` consecutive polls (`stalled: true` — the loop
- *  driving ticks stopped, e.g. play was stopped/paused). Never rejects.
- *  Exported (not just used by `holdFor` below) so the editor relay's
- *  `command-listener.ts` `holdFor` case can share the EXACT same
- *  poll/stall/hidden-drive logic against its own `DebugAdapter` (reached via
- *  `getActiveSystems().debug` rather than a `DebugRegistry`) — D17:
- *  byte-identical behavior across doors, not two hand-copies that can
- *  silently drift apart. */
-export function waitForHoldBudget(adapter, simSeconds, driveHiddenTicks) {
-    return new Promise((resolve) => {
-        const start = adapter.state('time');
-        let lastTick = start.tick;
-        let lastPollWallMs = Date.now();
-        let stalledPolls = 0;
-        const poll = () => {
-            const current = adapter.state('time');
-            if (current.simSeconds - start.simSeconds >= simSeconds) {
-                resolve({ stalled: false });
-                return;
-            }
-            if (current.loopLiveness === 'hidden-paused' && driveHiddenTicks) {
-                const now = Date.now();
-                const ticks = Math.max(1, Math.min(30, Math.round((now - lastPollWallMs) / (1000 / 60))));
-                lastPollWallMs = now;
-                driveHiddenTicks(ticks);
-                setTimeout(poll, HOLD_FOR_POLL_MS);
-                return;
-            }
-            lastPollWallMs = Date.now();
-            stalledPolls = current.tick === lastTick ? stalledPolls + 1 : 0;
-            lastTick = current.tick;
-            if (stalledPolls >= HOLD_FOR_STALL_POLL_LIMIT) {
-                resolve({ stalled: true });
-                return;
-            }
-            setTimeout(poll, HOLD_FOR_POLL_MS);
-        };
-        setTimeout(poll, HOLD_FOR_POLL_MS);
-    });
-}
-function hasRealWindow() {
-    return typeof window !== 'undefined';
-}
-function isDebugModeRequested(url) {
-    return new URLSearchParams(url.search).get(DEBUG_MODE_QUERY_PARAM) === '1';
-}
-/** D18's gate: a dev build, or a production build the manifest explicitly
- *  opted in. Read fresh on every call (not cached at install time) so
- *  `invoke()`'s belt-and-braces re-check (AC-A1.7) is a genuine second
- *  evaluation, not a rubber stamp of a value computed once at install. */
-function isDebugAllowed(manifest) {
-    return Boolean(import.meta.env?.DEV) || manifest.debug?.allowInProduction === true;
-}
-function buildDebugHandle(opts) {
-    const { registry, manifest } = opts;
-    const adapter = registry.adapter;
-    const pageErrors = [];
-    function pushPageError(message) {
-        pageErrors.push(message);
-        if (pageErrors.length > PAGE_ERROR_CAP)
-            pageErrors.shift();
-    }
-    // Named (not inline-anonymous) so `uninstall()` below can pass the exact
-    // same reference to `removeEventListener` (Defect 5 fix).
-    const onWindowError = (event) => {
-        pushPageError(event.message || String(event.error));
-    };
-    const onWindowRejection = (event) => {
-        pushPageError(`Unhandled promise rejection: ${String(event.reason)}`);
-    };
-    opts.window.addEventListener?.('error', onWindowError);
-    opts.window.addEventListener?.('unhandledrejection', onWindowRejection);
-    function requireInputTarget(method, worldId) {
-        const target = registry.getVirtualInputTarget(worldId);
-        if (!target) {
-            throw new DebugError('DEBUG_INPUT_UNAVAILABLE', `debug bridge: ${method}() has no virtual-input target wired — no default threejs ` +
-                "world has mounted yet, or this project's mount path never wired one");
-        }
-        return target;
-    }
-    return {
-        version: 1,
-        // None of these `DebugAdapter` methods reference `this` (they close over
-        // the registry's own private maps) — passing the references directly is
-        // safe and avoids five redundant wrapper closures.
-        providers: adapter.providers,
-        state: adapter.state,
-        stateAll: adapter.stateAll,
-        commands: adapter.commands,
-        events: adapter.events,
-        async invoke(name, args) {
-            // Belt-and-braces D18 re-check (AC-A1.7): the outer install gate
-            // already required this to be true, but a caller could hold onto this
-            // handle across an environment/manifest change — refuse loudly rather
-            // than trust a decision made once at install time.
-            if (!isDebugAllowed(manifest)) {
-                throw new DebugError('DEBUG_COMMANDS_UNSUPPORTED', `debug: command "${name}" invocation refused — production build without ` +
-                    'debug.allowInProduction (D18)', { name });
-            }
-            return adapter.invoke(name, args);
-        },
-        input: {
-            setVirtualAction: (action, value, worldId) => requireInputTarget('setVirtualAction', worldId).setVirtualAction(action, value),
-            tapVirtualAction: (action, worldId) => requireInputTarget('tapVirtualAction', worldId).tapVirtualAction(action),
-            clearVirtualActions: (worldId) => requireInputTarget('clearVirtualActions', worldId).clearVirtualActions(),
-            scheduleActionAtTick: (tick, action, value, worldId) => requireInputTarget('scheduleActionAtTick', worldId).scheduleActionAtTick(tick, action, value),
-            startRecording: (worldId) => requireInputTarget('startRecording', worldId).startInputRecording(),
-            stopRecording: (worldId) => requireInputTarget('stopRecording', worldId).stopInputRecording(),
-            isRecording: (worldId) => requireInputTarget('isRecording', worldId).isInputRecording(),
-            injectPointerDelta: (sourceId, delta, worldId) => requireInputTarget('injectPointerDelta', worldId).injectPointerDelta(sourceId, delta),
-            injectPointerPosition: (sourceId, value, worldId) => requireInputTarget('injectPointerPosition', worldId).injectPointerPosition(sourceId, value),
-        },
-        snapshot(sinceTick, sinceSeq) {
-            // One synchronous pass — see VgaiDebugSnapshot's doc comment.
-            return {
-                time: adapter.state('time'),
-                state: adapter.stateAll(),
-                events: adapter.events(sinceTick, sinceSeq),
-                pageErrors: pageErrors.slice(),
-            };
-        },
-        runTicks(n, runTicksOpts) {
-            const target = registry.getRunTicksTarget();
-            if (!target) {
-                throw new DebugError('DEBUG_RUN_TICKS_UNAVAILABLE', 'debug bridge: runTicks() has no run-ticks target wired — no Game has mounted yet');
-            }
-            target.runTicks(n, runTicksOpts);
-        },
-        async holdFor(action, simSeconds, worldId) {
-            const target = requireInputTarget('holdFor', worldId);
-            const setResult = target.setVirtualAction(action, true);
-            if (!setResult.delivered) {
-                target.clearVirtualActions();
-                // `exactOptionalPropertyTypes`: don't write an explicit `reason:
-                // undefined` when the gate itself didn't supply one — omit the key
-                // entirely rather than assign `undefined` into an optional `string`
-                // property.
-                return setResult.reason !== undefined
-                    ? { delivered: false, reason: setResult.reason }
-                    : { delivered: false };
-            }
-            const runTicksTarget = registry.getRunTicksTarget();
-            const { stalled } = await waitForHoldBudget(adapter, simSeconds, runTicksTarget ? (n) => runTicksTarget.runTicks(n, { render: 'last' }) : undefined);
-            target.clearVirtualActions();
-            return stalled
-                ? { delivered: false, reason: 'play stopped during hold' }
-                : { delivered: true };
-        },
-        uninstall() {
-            opts.window.removeEventListener?.('error', onWindowError);
-            opts.window.removeEventListener?.('unhandledrejection', onWindowRejection);
-            delete opts.window['__vgai'];
-        },
-    };
-}
-/**
- * Install `window.__vgai` iff the page opted in (`?vgai-debug=1`) AND D18's
- * gate passes (dev build, or manifest `debug.allowInProduction`). When the
- * param is present but the gate fails, warns once (this single call IS the
- * "once" — there is exactly one install attempt per boot) and installs
- * nothing. Returns the installed handle (mostly useful for tests), or
- * `undefined` when nothing was installed.
- */
-export function maybeInstallDebugBridge(opts) {
-    const url = opts.url ?? (hasRealWindow() ? window.location : undefined);
-    if (!url)
-        return undefined;
-    if (!isDebugModeRequested(url))
-        return undefined;
-    const windowTarget = opts.window ?? (hasRealWindow() ? window : undefined);
-    if (!windowTarget)
-        return undefined;
-    if (!isDebugAllowed(opts.manifest)) {
-        // biome-ignore lint/suspicious/noConsole: structured, greppable D18 signal — mirrors debug-registry.ts's own console.warn idiom.
-        console.warn('[debug] ?vgai-debug=1 ignored: production build without debug.allowInProduction (D18)');
-        return undefined;
-    }
-    const handle = buildDebugHandle({
-        registry: opts.registry,
-        manifest: opts.manifest,
-        window: windowTarget,
-    });
-    windowTarget['__vgai'] = handle;
-    return handle;
-}