@vgai/live 0.5.22 → 0.5.24

package/dist/{session.js → vgai-live/src/session.js}

@@ -47,6 +47,7 @@
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { EDITOR_SESSION_DISCOVERY_TIMEOUT_MS, HttpEditorTransport, withTimeout, } from '@vgai/sdk';
+import { servedProjectAnswer } from '../../vgai-sdk/src/editor/session-registry-format';
 /**
  * Lifted verbatim from `packages/vgai-cli/src/project-root.ts` (see this
  * module's doc comment above for why it's duplicated rather than imported).
@@ -106,13 +107,6 @@ function readProjectSession(projectRoot) {
  * but none open this project)" — sending the operator to start an editor that
  * was already running, with the real defect (their own manifest) never named.
  */
-function servedProject(body) {
-    const b = body;
-    return {
-        path: b.project?.path ?? b.serving?.path ?? null,
-        manifestError: b.project ? null : (b.serving?.error ?? null),
-    };
-}
 /**
  * What the server on `port` says it serves — `undefined` when it did not
  * answer at all. One probe: the manifest failure arrives with the path, so
@@ -125,7 +119,7 @@ async function probeServedProject(port) {
         });
         if (!response.ok)
             return undefined;
-        return servedProject(await response.json());
+        return servedProjectAnswer(await response.json());
     }
     catch {
         return undefined;
@@ -154,6 +148,50 @@ function manifestRefusal(projectRoot, manifestError) {
  * silently attaches to an unrelated project's session — see the module doc
  * above) when no vgai.project.json is found, or no live session covers it.
  */
+/**
+ * THE REFUSAL WHEN NOTHING MATCHED — and it says WHICH nothing.
+ *
+ * "No live editor session found … run `vgai edit`" used to be the answer to
+ * four different states, only one of which it described. The other three sent
+ * the operator to start an editor that was already running:
+ *
+ *  - discovery FAILED (a probe timeout under load) — nothing was learned, so
+ *    "no session is running" is not a fact anyone established;
+ *  - the registry was read and is genuinely empty — the one case the old text
+ *    was right about;
+ *  - sessions exist, but every one resolves to a different canonical path. In
+ *    a repo worked through git worktrees this is the ORDINARY miss: two
+ *    checkouts of the same project differ only in a path prefix, and a
+ *    symlinked worktree's `realpath` diverges from the path the caller typed.
+ *    Naming both sides is what makes it a two-second diagnosis instead of a
+ *    hunt.
+ *
+ * Each branch prescribes only what its own state supports.
+ */
+function noMatchingSessionRefusal(projectRoot, canon, sessions, discoveryFailure) {
+    if (discoveryFailure !== null) {
+        return new Error(`@vgai/live: could not READ the editor session registry while looking for ${projectRoot} — ` +
+            `${discoveryFailure}. This is not the answer "no editor is running": the question went ` +
+            'unanswered, so nothing is known about what is live. Retry (a probe can time out while ' +
+            'the box is loaded); if it keeps failing, `vgai sessions` asks the same question directly.');
+    }
+    if (sessions.length === 0) {
+        return new Error(`@vgai/live: the editor session registry is readable and lists NO live sessions, so none ` +
+            `covers ${projectRoot}. @vgai/live only attaches to an already-running session — it ` +
+            'never starts one — so run `vgai edit` in that project first, then retry.');
+    }
+    const listed = sessions
+        .map((s) => `    port ${s.port} → ${s.project === null ? '(no project)' : s.project}`)
+        .join('\n');
+    return new Error(`@vgai/live: ${sessions.length} live editor session(s) are running, but none of them opens ` +
+        `${projectRoot}. @vgai/live never silently attaches to a different project.\n` +
+        `  looking for (resolved): ${canon}\n` +
+        `  live sessions:\n${listed}\n` +
+        '  If one of those is meant to be this project, the two paths differ after resolution — ' +
+        'the usual cause is a git worktree or a symlink, where the session was opened through a ' +
+        'different path to the same files. Run `vgai edit` from THIS path, or use the path the ' +
+        'session lists.');
+}
 export async function resolveSession(projectDir = process.cwd(), deps = {}) {
     const findRoot = deps.findProjectRootFrom ?? findProjectRootFrom;
     const transport = deps.transport ?? new HttpEditorTransport();
@@ -187,24 +225,23 @@ export async function resolveSession(projectDir = process.cwd(), deps = {}) {
         }
     }
     let sessions;
+    // A FAILED discovery is not an empty one. Collapsing the two into `[]` is
+    // what made this door answer "no live editor session found" — and prescribe
+    // `vgai edit` — for a probe that merely timed out under load, sending the
+    // operator to start an editor that was already running while the real defect
+    // went unnamed. The same collapse the manifest refusal above was added for.
+    let discoveryFailure = null;
     try {
         sessions = await withTimeout(transport.listSessions(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS), EDITOR_SESSION_DISCOVERY_TIMEOUT_MS, 'editor session discovery');
     }
-    catch {
+    catch (err) {
         sessions = [];
+        discoveryFailure = err instanceof Error ? err.message : String(err);
     }
     const canon = canonicalPath(projectRoot);
     const match = sessions.find((s) => s.project !== null && canonicalPath(s.project) === canon);
-    if (!match) {
-        const otherCount = sessions.length;
-        throw new Error(`@vgai/live: no live editor session found for ${projectRoot}. @vgai/live only attaches to ` +
-            'an already-running session — it never starts one — so run `vgai edit` in that project ' +
-            'first, then retry.' +
-            (otherCount > 0
-                ? ` (${otherCount} other live session(s) found, but none open this project — @vgai/live ` +
-                    'never silently attaches to a different project.)'
-                : ''));
-    }
+    if (!match)
+        throw noMatchingSessionRefusal(projectRoot, canon, sessions, discoveryFailure);
     if (match.manifestError != null)
         throw manifestRefusal(projectRoot, match.manifestError);
     return { port: match.port, projectRoot };

package/dist/{tools.d.ts → vgai-live/src/tools.d.ts}

@@ -12,7 +12,7 @@ export declare class LiveTools {
      *
      * `instance` names WHICH mounted instance the tool should drive when several
      * are live (multiplayer authoring) — it reaches the tool as `ctx.instance`,
-     * and a tool that drives the game (e.g. `project.autoplay`) binds
+     * and a tool that drives the game binds
      * `game.instance(ctx.instance)` from it. Omitted is the single-instance case;
      * the tool then targets the sole live instance, exactly as before.
      */

package/dist/{tools.js → vgai-live/src/tools.js}

@@ -19,7 +19,7 @@ export class LiveTools {
      *
      * `instance` names WHICH mounted instance the tool should drive when several
      * are live (multiplayer authoring) — it reaches the tool as `ctx.instance`,
-     * and a tool that drives the game (e.g. `project.autoplay`) binds
+     * and a tool that drives the game binds
      * `game.instance(ctx.instance)` from it. Omitted is the single-instance case;
      * the tool then targets the sole live instance, exactly as before.
      */

package/dist/vgai-sdk/src/editor/session-registry-format.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `~/.vgai/editor-sessions.json` — the ONE spelling of the editor-session
+ * registry contract, and the shared machinery every reader was hand-copying.
+ *
+ * The registry's WRITE half stays with its owner
+ * (`packages/editor/server/session-registry.ts`); this module owns the
+ * FORMAT: the entry shape, the shape guards, the file path, the
+ * liveness-filtered read, the `/__editor/project` answer parser, and the
+ * deterministic session-selection core. It existed as FOUR drifting copies
+ * (server registry, the CLI, and both vgai-sdk transports) held together by
+ * a "the CLI has no editor dependency" premise that had stopped being true —
+ * and the drift was already real: one copy's `/__editor/project` parser
+ * dropped `manifestError`, reporting a degraded session as belonging to no
+ * project.
+ */
+/** One registry entry, exactly as the server's write half records it. */
+export interface EditorSessionEntry {
+    /** Canonical project root currently open, or null when none. */
+    project: string | null;
+    port: number;
+    /** PID of the dev-server process. */
+    pid: number;
+    /** ISO timestamp of server start. */
+    startedAt: string;
+    sessionId: string | null;
+    /** Private loopback control credential — never returned by an editor HTTP
+     *  route; exists only in this user-private registry. */
+    controlSecret?: string | null;
+    repositoryId: string | null;
+    worktreeId: string | null;
+    worktreeRoot: string | null;
+    projectRelativePath: string | null;
+    branch: string | null;
+    headCommit: string | null;
+    baseCommit: string | null;
+}
+export declare const EDITOR_SESSIONS_REGISTRY_FILE: string;
+export declare function isEditorSessionEntry(v: unknown): v is EditorSessionEntry;
+export declare function normalizeEditorSessionEntry(session: EditorSessionEntry): EditorSessionEntry;
+export declare function pidAlive(pid: number): boolean;
+/** The registry's live entries — shape-validated and PID-liveness-filtered. */
+export declare function readLiveRegisteredSessions(): EditorSessionEntry[];
+/**
+ * WHICH PROJECT a `/__editor/project` body says its server is serving.
+ *
+ * `serving` is that server's own statement of "I AM serving this project, I
+ * just cannot describe it" (its manifest is unparseable or fails strict
+ * validation) — added to the route precisely because a bare
+ * `{ project: null }` is indistinguishable from "no project open". Reading
+ * only `project.path` collapses the two, and the cost is that every
+ * project-matched command loses a live session the moment a save breaks its
+ * manifest, reporting it as belonging to no project rather than as this
+ * project's degraded session.
+ */
+export declare function servedProjectAnswer(body: unknown): {
+    path: string | null;
+    manifestError: string | null;
+};
+/**
+ * Deterministic session selection — the ONE precedence order every surface
+ * follows: explicit `ctx.editorUrl` probe > port match against the listing >
+ * `ctx.projectRoot` match > lowest live port > not-running. Generic over the
+ * session shape so the editor and play transports (whose probe results
+ * differ) share the algorithm rather than a copy of it.
+ */
+export declare function resolveRegisteredSession<T extends {
+    port: number;
+    project: string | null;
+    url?: string;
+}>(ctx: {
+    editorUrl?: string | undefined;
+    projectRoot?: string | undefined;
+}, transport: {
+    listSessions(timeoutMs: number): Promise<T[]>;
+    probeSessionUrl?: ((url: string, timeoutMs: number) => Promise<T | null | undefined>) | undefined;
+}, options: {
+    probeTimeoutMs: number;
+    discoveryTimeoutMs: number;
+    withTimeout: <V>(work: Promise<V>, timeoutMs: number, what: string) => Promise<V>;
+    notRunning: () => never;
+}): Promise<T>;

package/dist/vgai-sdk/src/editor/session-registry-format.js

@@ -0,0 +1,158 @@
+/**
+ * `~/.vgai/editor-sessions.json` — the ONE spelling of the editor-session
+ * registry contract, and the shared machinery every reader was hand-copying.
+ *
+ * The registry's WRITE half stays with its owner
+ * (`packages/editor/server/session-registry.ts`); this module owns the
+ * FORMAT: the entry shape, the shape guards, the file path, the
+ * liveness-filtered read, the `/__editor/project` answer parser, and the
+ * deterministic session-selection core. It existed as FOUR drifting copies
+ * (server registry, the CLI, and both vgai-sdk transports) held together by
+ * a "the CLI has no editor dependency" premise that had stopped being true —
+ * and the drift was already real: one copy's `/__editor/project` parser
+ * dropped `manifestError`, reporting a degraded session as belonging to no
+ * project.
+ */
+import { readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+export const EDITOR_SESSIONS_REGISTRY_FILE = join(homedir(), '.vgai', 'editor-sessions.json');
+export function isEditorSessionEntry(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const s = v;
+    const optionalIdentity = (value) => value === undefined || value === null || typeof value === 'string';
+    return ((typeof s['project'] === 'string' || s['project'] === null) &&
+        typeof s['port'] === 'number' &&
+        typeof s['pid'] === 'number' &&
+        typeof s['startedAt'] === 'string' &&
+        optionalIdentity(s['sessionId']) &&
+        optionalIdentity(s['controlSecret']) &&
+        optionalIdentity(s['repositoryId']) &&
+        optionalIdentity(s['worktreeId']) &&
+        optionalIdentity(s['worktreeRoot']) &&
+        optionalIdentity(s['projectRelativePath']) &&
+        optionalIdentity(s['branch']) &&
+        optionalIdentity(s['headCommit']) &&
+        optionalIdentity(s['baseCommit']));
+}
+export function normalizeEditorSessionEntry(session) {
+    return {
+        ...session,
+        sessionId: session.sessionId ?? null,
+        controlSecret: session.controlSecret ?? null,
+        repositoryId: session.repositoryId ?? null,
+        worktreeId: session.worktreeId ?? null,
+        worktreeRoot: session.worktreeRoot ?? null,
+        projectRelativePath: session.projectRelativePath ?? null,
+        branch: session.branch ?? null,
+        headCommit: session.headCommit ?? null,
+        baseCommit: session.baseCommit ?? null,
+    };
+}
+export function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The registry's live entries — shape-validated and PID-liveness-filtered. */
+export function readLiveRegisteredSessions() {
+    try {
+        const raw = JSON.parse(readFileSync(EDITOR_SESSIONS_REGISTRY_FILE, 'utf8'));
+        return Array.isArray(raw)
+            ? raw
+                .filter(isEditorSessionEntry)
+                .map(normalizeEditorSessionEntry)
+                .filter((s) => pidAlive(s.pid))
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * WHICH PROJECT a `/__editor/project` body says its server is serving.
+ *
+ * `serving` is that server's own statement of "I AM serving this project, I
+ * just cannot describe it" (its manifest is unparseable or fails strict
+ * validation) — added to the route precisely because a bare
+ * `{ project: null }` is indistinguishable from "no project open". Reading
+ * only `project.path` collapses the two, and the cost is that every
+ * project-matched command loses a live session the moment a save breaks its
+ * manifest, reporting it as belonging to no project rather than as this
+ * project's degraded session.
+ */
+export function servedProjectAnswer(body) {
+    const b = body;
+    return {
+        path: b.project?.path ?? b.serving?.path ?? null,
+        manifestError: b.project ? null : (b.serving?.error ?? null),
+    };
+}
+/** Canonical (realpathed when possible) absolute form of a project path. */
+function canonicalizeProjectPath(p) {
+    const absolute = resolve(p);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+/** Extract the port from an `http(s)://host:port` URL, or undefined if unparseable. */
+function portOfUrl(url) {
+    try {
+        const port = new URL(url).port;
+        return port ? Number(port) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Deterministic session selection — the ONE precedence order every surface
+ * follows: explicit `ctx.editorUrl` probe > port match against the listing >
+ * `ctx.projectRoot` match > lowest live port > not-running. Generic over the
+ * session shape so the editor and play transports (whose probe results
+ * differ) share the algorithm rather than a copy of it.
+ */
+export async function resolveRegisteredSession(ctx, transport, options) {
+    const editorUrl = ctx.editorUrl;
+    if (editorUrl !== undefined && transport.probeSessionUrl) {
+        try {
+            const session = await options.withTimeout(transport.probeSessionUrl(editorUrl, options.probeTimeoutMs), options.probeTimeoutMs, 'explicit editor URL probe');
+            if (session)
+                return session;
+        }
+        catch { }
+        return options.notRunning();
+    }
+    let sessions;
+    try {
+        sessions = await options.withTimeout(transport.listSessions(options.discoveryTimeoutMs), options.discoveryTimeoutMs, 'editor session discovery');
+    }
+    catch {
+        return options.notRunning();
+    }
+    if (sessions.length === 0)
+        return options.notRunning();
+    if (editorUrl !== undefined) {
+        const port = portOfUrl(editorUrl);
+        const match = sessions.find((s) => s.port === port);
+        if (!match)
+            return options.notRunning();
+        return { ...match, url: editorUrl.replace(/\/+$/, '') };
+    }
+    if (ctx.projectRoot !== undefined) {
+        const canon = canonicalizeProjectPath(ctx.projectRoot);
+        const match = sessions.find((s) => s.project !== null && canonicalizeProjectPath(s.project) === canon);
+        if (!match)
+            return options.notRunning();
+        return match;
+    }
+    return [...sessions].sort((a, b) => a.port - b.port)[0];
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/live",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.22",
+  "version": "0.5.24",
   "type": "module",
   "repository": {
     "type": "git",
@@ -32,8 +32,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@vgai/editor-sdk": "0.5.22",
-    "@vgai/sdk": "0.5.22"
+    "@vgai/editor-sdk": "0.5.24",
+    "@vgai/sdk": "0.5.24"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.58.2 <2"

package/src/editor.ts

@@ -1,14 +1,14 @@
 /**
  * `LiveEditor` — the editor-control half of `@vgai/live`'s `{ editor, game,
- * page }` (Wave 2). Methods are named after the
+ * page }`. Methods are named after the
  * ACTION, not the CLI flag spelling (e.g. `select('all')` rather than a
  * separate `selectAll`, `showPanel('viewport-play')` rather than
  * `vgai show viewport play`'s two-token shape) — see each method's own doc
  * comment for the exact CLI verb / `EditorClient` call it mirrors.
  *
  * Every method reuses `@vgai/editor-sdk`'s `EditorClient` — this module never
- * hand-rolls a `fetch` to `/__editor/command` itself. (WO-8 removed the one
- * exception, `applyDiff`, which was FILE mode rather than a live wire command.)
+ * hand-rolls a `fetch` to `/__editor/command` itself, and has no FILE-mode
+ * escape hatch: every method goes over the wire.
  */
 
 import type {
@@ -103,11 +103,8 @@ export class LiveEditor {
 
   /**
    * The active authoring adapter's persistence destination — where a save would
-   * land (`status().savePath`).
-   *
-   * WO-8: this also took a `path` and OPENED that scene through
-   * `EditorClient.openScene` -> the `open-scene` relay verb. That verb now rejects
-   * (the `.vscn.json` format is deleted), so only the read remains.
+   * land (`status().savePath`). A read only: a three root has no scene document
+   * to open, and its root is activated instead.
    */
   async scene(): Promise<string | null> {
     const state = await this.#client.getState();
@@ -133,14 +130,6 @@ export class LiveEditor {
     return this.#client.captureActiveDocument(size);
   }
 
-  /*
-   * `applyDiff` lived here. It dispatched `project.scene.apply`, one of the
-   * twelve `.vscn` document tools deleted with the format, so there is nothing
-   * left for it to call. `ApplyDiffInput` / `ApplyDiffResult` went with it, and
-   * so did `projectRoot` — this was the ONE method that used it (every other
-   * method goes over the wire).
-   */
-
   async play(opts?: { seed?: number }): Promise<void> {
     await this.#client.play(opts);
   }

package/src/game-client/bridge-transport.ts

@@ -51,7 +51,7 @@ export interface BridgeTransport {
    *  blank/corrupt file. */
   screenshot(path: string): Promise<CaptureNotes>;
   /**
-   * Wave-2 "one dialect, full capability" — runs a UI-automation step
+   * One dialect, full capability — runs a UI-automation step
    * written as a literal `async (page) => {...}` (`GameClient.page()`,
    * `client.ts`). `src` is `step.toString()`; `step` is the ORIGINAL
    * function, wrapped so its own parameter type is erased to `unknown` (only
@@ -75,6 +75,19 @@ export interface BridgeTransport {
    * serialized — inline every value the step needs.
    */
   runPageScript(src: string, step: (page: unknown) => unknown): Promise<BridgeCallOutcome>;
+  /**
+   * THE MODULE LANE — run a step INSIDE the editor page against
+   * `{ page, modules, instanceId }`, where `modules(path)` imports the
+   * RUNNING mount's own instance of a project module (never a phantom
+   * second copy). Same serialization contract as `runPageScript`: the
+   * step's source travels as text, closures do not survive, and the return
+   * value must be plain data. `instance` scopes multi-instance sessions.
+   */
+  runGameScript(
+    src: string,
+    step: (scope: unknown) => unknown,
+    instance?: string,
+  ): Promise<BridgeCallOutcome>;
   /**
    * P20 — reload the document showing the game, resolving only once the page
    * is BACK and taking commands again.

package/src/game-client/client.ts

@@ -141,7 +141,7 @@ export class PageTransport implements BridgeTransport {
     return {};
   }
 
-  /** Wave-2: the ONE transport that runs a `game.page()` step against a REAL
+  /** The ONE transport that runs a `game.page()` step against a REAL
    *  Playwright `Page` — no serialization, so `step`'s own closures work
    *  here (see `bridge-transport.ts`'s `runPageScript` doc comment for the
    *  full honesty-boundary contract; `src` is unused on this leg, kept only
@@ -158,6 +158,41 @@ export class PageTransport implements BridgeTransport {
     }
   }
 
+  /** THE MODULE LANE under a real Playwright host: the step's source is
+   *  evaluated INSIDE the editor page via the same in-page handler the relay
+   *  op uses (`window.__vgaiGameEval`), because `modules()` only means
+   *  anything in the page's own module space — a Node-side call could never
+   *  hand back the running mount's instances. Same serialization contract
+   *  as the relay leg. */
+  async runGameScript(
+    src: string,
+    _step: (scope: unknown) => unknown,
+    instance?: string,
+  ): Promise<BridgeCallOutcome> {
+    try {
+      const result = await this.page.evaluate(
+        async (args: { src: string; instance?: string }) => {
+          const hook = (window as unknown as Record<string, unknown>)['__vgaiGameEval'] as
+            | ((src: string, instance?: string) => Promise<unknown>)
+            | undefined;
+          if (typeof hook !== 'function') {
+            throw new Error(
+              'game-eval: this page has no __vgaiGameEval hook — is the editor page loaded?',
+            );
+          }
+          return hook(args.src, args.instance);
+        },
+        { src, ...(instance === undefined ? {} : { instance }) },
+      );
+      return { ok: true, result };
+    } catch (err) {
+      return {
+        ok: false,
+        error: { code: undefined, message: err instanceof Error ? err.message : String(err) },
+      };
+    }
+  }
+
   /** Playwright's own reload already waits for the new document's `load`
    *  event, which is exactly the completion signal this method's contract
    *  asks for — nothing to reconstruct on this leg. */
@@ -528,6 +563,9 @@ export class GameClient {
   /** Per-test tick-rate samples, fed by every `snapshot()` read (a poll the
    *  client was making anyway — zero extra page.evaluate round trips). */
   readonly #tps = new TpsAccumulator();
+  /** True after the settled run-ticks door proved absent on this page (an older exported
+   *  game's engine) — see `fastForward`'s `runTicksBatch`. */
+  #legacyRunTicksDoor = false;
   /** Hidden-tab recovery (hollowstone field lesson: the engine hard-stops
    *  while `document.hidden`). Client-lifetime state so `bringToFront()`
    *  fires at most once per test, across ALL waitFor/waitSimTime loops. */
@@ -619,7 +657,29 @@ export class GameClient {
     // names neither the method nor the shape).
     assertValidWaitForBudget(budget, 'fastForward');
     const clock: FastForwardClock = {
-      runTicksBatch: (n, render) => this.callBridgeVoid('runTicks', n, { render }),
+      // The SETTLED door (`runTicksSettled`, an async bridge method): ticks never race a scene
+      // remount's async commit, so which tick first runs a freshly reloaded world is
+      // deterministic (see engine/runtime/run-ticks-settled.ts — measured: without it, one
+      // drive script produced 7 or 8 post-respawn walked ticks depending on wall timing).
+      // Falls back ONCE to the plain sync door for a page whose engine predates the method
+      // (an older exported game), and remembers the verdict for the rest of the burst.
+      runTicksBatch: async (n, render) => {
+        if (this.#legacyRunTicksDoor) {
+          await this.callBridgeVoid('runTicks', n, { render });
+          return;
+        }
+        try {
+          await this.callBridgeAsync<void>('runTicksSettled', n, { render });
+        } catch (error) {
+          const code = (error as { code?: string }).code;
+          const message = error instanceof Error ? error.message : String(error);
+          const doorAbsent =
+            code === 'UNKNOWN_BRIDGE_METHOD' || /is not a function|undefined/i.test(message);
+          if (!doorAbsent) throw error;
+          this.#legacyRunTicksDoor = true;
+          await this.callBridgeVoid('runTicks', n, { render });
+        }
+      },
       readTime: async () => {
         // Raw bridge read — deliberately NOT `this.snapshot()`, which would
         // feed the TpsAccumulator (see fast-forward.ts's module doc, point 2).
@@ -651,7 +711,7 @@ export class GameClient {
           snapshot: () => this.snapshot(),
           now: () => Date.now(),
           sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
-          // Fixture heartbeat (Wave-6 findings ledger) — real stdout, the
+          // Fixture heartbeat — real stdout, the
           // same channel a caller watching stdout already treats as
           // liveness (see wait-for.ts's module doc for the emission
           // invariant `maybeHeartbeat` enforces).
@@ -688,7 +748,7 @@ export class GameClient {
     const start = await this.snapshot();
     let lastTick: number | null = null;
     let stalledPolls = 0;
-    // Fixture heartbeat (Wave-6 findings ledger) — same invariant as
+    // Fixture heartbeat — same invariant as
     // `wait-for.ts`'s `runWaitFor`: a heartbeat requires BOTH 60s of wall
     // silence AND the tick having advanced since the last one emitted, so a
     // genuinely stalled sim clock (caught by `stalledPolls` above, ~30s)
@@ -770,10 +830,8 @@ export class GameClient {
    * `events.expect`'s failure path each shoot a frame on their own
    * (`toSessionFailure`, `GameEvents.expect`), and a route's `whileHeld`
    * observer may shoot one from inside a callback the driver never sees. The
-   * only place that sees ALL of them is here, which is why an autoplay run
-   * stamps its captures by listening rather than by intercepting
-   * (`src/tools/route-context.ts` in a scaffolded project is the shipped
-   * listener).
+   * only place that sees ALL of them is here, which is why a driving tool
+   * stamps its captures by listening rather than by intercepting.
    */
   onCapture(listener: CaptureListener): () => void {
     this.#captureListeners.add(listener);
@@ -783,7 +841,7 @@ export class GameClient {
   }
 
   /**
-   * Wave-2 "one dialect, full capability" — runs a UI-automation step
+   * One dialect, full capability — runs a UI-automation step
    * written as a literal Playwright `async (page) => {...}` (interface
    * doctrine §3.2/§4 rung 4: "the AI should think it is basically just
    * executing Playwright"). Under `PageTransport` this drives the REAL
@@ -804,6 +862,37 @@ export class GameClient {
     return this.unwrap<T>(outcome);
   }
 
+  /**
+   * THE MODULE LANE — run literal JS INSIDE the game's page, with the
+   * running mount's modules in reach:
+   *
+   * ```js
+   * await game.run(async ({ modules }) => {
+   *   const { simHost } = await modules('src/sim/host.ts');
+   *   return simHost().state.day;
+   * })
+   * ```
+   *
+   * `scope` is `{ page, modules, instanceId }`. Serialization contract as
+   * `game.page()`: the step travels as source (no closures), and the return
+   * value must be plain data. `modules(path)` resolves through the ACTIVE
+   * mount's own url space, so what you touch IS the running game — never a
+   * phantom second copy. Dev-server sessions only; a shipped build's curated
+   * surface is its adapter exports.
+   */
+  async run<T = unknown>(
+    step: (scope: {
+      page: Page;
+      modules: (path: string) => Promise<Record<string, unknown>>;
+      instanceId: string;
+    }) => T | Promise<T>,
+    opts?: { instance?: string },
+  ): Promise<T> {
+    const erased = (arg: unknown) => step(arg as Parameters<typeof step>[0]);
+    const outcome = await this.#transport.runGameScript(step.toString(), erased, opts?.instance);
+    return this.unwrap<T>(outcome);
+  }
+
   /**
    * Reload the document showing the game, resolving only once it is back and
    * answering commands (see `bridge-transport.ts`'s `reloadPage`).