@vgai/live 0.5.23 → 0.5.24

package/dist/vgai-live/src/game-client/bridge-transport.d.ts

@@ -76,6 +76,15 @@ 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/dist/vgai-live/src/game-client/client.d.ts

@@ -39,6 +39,13 @@ export declare class PageTransport implements BridgeTransport {
      *  full honesty-boundary contract; `src` is unused on this leg, kept only
      *  to satisfy the shared interface). */
     runPageScript(_src: string, step: (page: unknown) => unknown): Promise<BridgeCallOutcome>;
+    /** 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. */
+    runGameScript(src: string, _step: (scope: unknown) => unknown, instance?: string): Promise<BridgeCallOutcome>;
     /** 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. */
@@ -296,6 +303,31 @@ export declare class GameClient {
      * `runPageScript` doc comment for the full contract this method wraps.
      */
     page<T = unknown>(step: (page: Page) => T | Promise<T>): Promise<T>;
+    /**
+     * 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.
+     */
+    run<T = unknown>(step: (scope: {
+        page: Page;
+        modules: (path: string) => Promise<Record<string, unknown>>;
+        instanceId: string;
+    }) => T | Promise<T>, opts?: {
+        instance?: string;
+    }): Promise<T>;
     /**
      * Reload the document showing the game, resolving only once it is back and
      * answering commands (see `bridge-transport.ts`'s `reloadPage`).

package/dist/vgai-live/src/game-client/client.js

@@ -128,6 +128,30 @@ export class PageTransport {
             };
         }
     }
+    /** 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, _step, instance) {
+        try {
+            const result = await this.page.evaluate(async (args) => {
+                const hook = window['__vgaiGameEval'];
+                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. */
@@ -422,6 +446,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). */
     #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. */
@@ -504,7 +531,30 @@ export class GameClient {
         // names neither the method nor the shape).
         assertValidWaitForBudget(budget, 'fastForward');
         const clock = {
-            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('runTicksSettled', n, { render });
+                }
+                catch (error) {
+                    const code = error.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).
@@ -676,6 +726,29 @@ export class GameClient {
         const outcome = await this.#transport.runPageScript(step.toString(), erased);
         return this.unwrap(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(step, opts) {
+        const erased = (arg) => step(arg);
+        const outcome = await this.#transport.runGameScript(step.toString(), erased, opts?.instance);
+        return this.unwrap(outcome);
+    }
     /**
      * Reload the document showing the game, resolving only once it is back and
      * answering commands (see `bridge-transport.ts`'s `reloadPage`).

package/dist/vgai-live/src/game-client/relay-transport.d.ts

@@ -109,6 +109,8 @@ export declare class RelayTransport implements BridgeTransport {
      * `PageTransport` (which DOES call it directly) also implements.
      */
     runPageScript(src: string, _step: (page: unknown) => unknown): Promise<BridgeCallOutcome>;
+    /** THE MODULE LANE over the relay — same wire shape as `page-script`. */
+    runGameScript(src: string, _step: (scope: unknown) => unknown, instance?: string): Promise<BridgeCallOutcome>;
     /**
      * P20 — order the tab to reload, then wait for EVIDENCE that it came back.
      *

package/dist/vgai-live/src/game-client/relay-transport.js

@@ -270,6 +270,23 @@ export class RelayTransport {
             };
         }
     }
+    /** THE MODULE LANE over the relay — same wire shape as `page-script`. */
+    async runGameScript(src, _step, instance) {
+        try {
+            const body = await this.postCommand({ type: 'game-eval', src, ...(instance === undefined ? {} : { instance }) }, PAGE_SCRIPT_TIMEOUT_MS);
+            return this.toBridgeOutcome(body);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                error: {
+                    code: 'RELAY_UNREACHABLE',
+                    message: `vgai: could not reach the editor dev server relay at ${this.baseUrl} — ` +
+                        `${err instanceof Error ? err.message : String(err)}`,
+                },
+            };
+        }
+    }
     /**
      * P20 — order the tab to reload, then wait for EVIDENCE that it came back.
      *

package/package.json

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

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

@@ -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

@@ -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).
@@ -802,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`).

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

@@ -345,6 +345,31 @@ export class RelayTransport implements BridgeTransport {
     }
   }
 
+  /** THE MODULE LANE over the relay — same wire shape as `page-script`. */
+  async runGameScript(
+    src: string,
+    _step: (scope: unknown) => unknown,
+    instance?: string,
+  ): Promise<BridgeCallOutcome> {
+    try {
+      const body = await this.postCommand(
+        { type: 'game-eval', src, ...(instance === undefined ? {} : { instance }) },
+        PAGE_SCRIPT_TIMEOUT_MS,
+      );
+      return this.toBridgeOutcome(body);
+    } catch (err) {
+      return {
+        ok: false,
+        error: {
+          code: 'RELAY_UNREACHABLE',
+          message:
+            `vgai: could not reach the editor dev server relay at ${this.baseUrl} — ` +
+            `${err instanceof Error ? err.message : String(err)}`,
+        },
+      };
+    }
+  }
+
   /**
    * P20 — order the tab to reload, then wait for EVIDENCE that it came back.
    *