@vgai/live 0.5.42 → 0.5.45

package/dist/game-client/capture-notes.js

@@ -2,17 +2,25 @@
  * What a capture knows about ITSELF beyond its pixels — and the one place the
  * caveat sentence is spelled.
  *
- * A PNG is silent about the conditions it was taken under. Two of those
- * conditions change what the frame is worth as evidence, and both are already
- * measured elsewhere in the stack: the editor page reports
+ * A PNG is silent about the conditions it was taken under. Four of those
+ * conditions matter, and each is already measured elsewhere in the stack.
+ * Three change what the frame is worth as EVIDENCE: the editor page reports
  * `loopRecoveryFrame` when the host loop was starved and the runtime had to
  * render one deterministic tick on demand (`command-listener.ts`'s
  * `handleBridgeScreenshot`), and it reports
  * a `flatness.warning` sentence when the frame is nine-tenths one flat surface
- * (`composite-screenshot.ts`'s `measureFlatness`). Until now both stopped at a
+ * (`composite-screenshot.ts`'s `measureFlatness`), and it names the CLIP a
+ * frame of a recorded run belongs to (`command-listener.ts`'s
+ * `screenshotRecordingNotice`). Until now these stopped at a
  * `console.warn` inside the relay transport — visible to a human watching a
  * terminal, invisible to anything that later reads the file.
  *
+ * The fourth is not about the frame at all but about what taking it COST: a
+ * capture written under the served project root goes through the dev server's
+ * file watcher on every shot (measured ~3x slower frame rates), and the
+ * out-path resolver is the only place that knows
+ * (`screenshot-target.ts`'s `underWatchedProjectRoot`).
+ *
  * So the transport seam carries them back as {@link CaptureNotes}, and
  * {@link describeCaptureCaveat} turns them into the ONE sentence every surface
  * says. Its two callers are the transport's own console warning and
@@ -23,15 +31,27 @@
 /** The loop-recovery sentence. Spelled once because it is said in two places
  *  (a live console warning and a persisted record) and a second copy is a
  *  second wording. */
+/**
+ * The cost of writing a capture INSIDE the served project.
+ *
+ * The dev server watches the project root, and its ignore list names build
+ * output only — nothing about capture output — so every PNG written under the
+ * root goes through the watcher. Measured cost class: ~3x slower frame rates
+ * while a capture loop wrote there. Named, not fixed: where a capture goes is
+ * the caller's decision, and this door's job is to stop that decision being
+ * made blind.
+ */
+const WATCHED_CAPTURE_PATH_CAVEAT = 'writing captures under the project root triggers the dev server’s file watcher; expect ~3× ' +
+    'slower frame rates — write outside the project or to the session’s own capture dir';
 const LOOP_RECOVERY_FRAME_CAVEAT = 'LOOP-RECOVERY FRAME — the host loop was starved, so the runtime rendered one ' +
     'deterministic tick on demand. It is current, not stale; it was not produced by ordinary presentation.';
 /**
  * What a reader must be told about this frame, or `null` when there is nothing
  * to tell.
  *
- * Both notes can be true at once (an on-demand recovery tick that also came
- * out near-blank), and both are said — a capture that is degraded twice over
- * must not report only the first reason.
+ * Any of them can be true at once (an on-demand recovery tick that also came
+ * out near-blank, in a recorded run), and each is said — a capture that is
+ * degraded twice over must not report only the first reason.
  */
 export function describeCaptureCaveat(notes) {
     const parts = [];
@@ -40,5 +60,12 @@ export function describeCaptureCaveat(notes) {
     if (typeof notes.flatnessWarning === 'string' && notes.flatnessWarning !== '') {
         parts.push(notes.flatnessWarning);
     }
+    if (typeof notes.recordingPath === 'string' && notes.recordingPath !== '') {
+        parts.push(`ONE FRAME of a recorded run — ${notes.recordingPath} holds the whole of it. A still ` +
+            'answers what it looks like; a temporal question (did the jump land) needs the clip.');
+    }
+    if (typeof notes.watchedProjectRoot === 'string' && notes.watchedProjectRoot !== '') {
+        parts.push(`${WATCHED_CAPTURE_PATH_CAVEAT} (${notes.watchedProjectRoot}).`);
+    }
     return parts.length === 0 ? null : parts.join(' ');
 }

package/dist/game-client/client.d.ts

@@ -87,6 +87,11 @@ export interface GameClientOptions {
      *  actually running). */
     fenceWallMs: number;
     artifactsDir?: string | undefined;
+    /** The project root the editor session is SERVING, when the caller knows it
+     *  (`@vgai/live`'s `connect()` does). Used for one thing: saying, in a
+     *  capture's own notes, that its destination falls under the dev server's
+     *  file watcher — see `capture-notes.ts`. Never used to resolve a path. */
+    projectRoot?: string | undefined;
     /** Set by the caller when it reused an already-running game server rather
      *  than booting a fresh one for this run. Threaded through so `unwrap` can
      *  append the warm-session staleness hint to a
@@ -332,10 +337,28 @@ export declare class GameClient {
      * 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.
+     *
+     * `modules(path)` IS ASYNC — it dynamic-imports that url — so the callback
+     * is `async` and the call is `await`ed, in every example on this page and
+     * everywhere else. Skipping it does not fail quietly: reading a member off
+     * the unawaited promise throws a message naming the fix, because
+     * `TypeError: modules(...).simHost is not a function` (measured, cold fox
+     * #3) says nothing about promises.
+     *
+     * `modules` IS A FUNCTION, not a table — there is no module registry. To ask
+     * what the mount has loaded, read `modules.loaded`, the project-relative
+     * paths you can pass straight back in:
+     *
+     * ```js
+     * await game.run(({ modules }) => modules.loaded)
+     * // → ['src/scenes/MainScene.tsx', 'src/world.tsx', …]
+     * ```
      */
     run<T = unknown>(step: (scope: {
         page: Page;
-        modules: (path: string) => Promise<Record<string, unknown>>;
+        modules: ((path: string) => Promise<Record<string, unknown>>) & {
+            readonly loaded: string[];
+        };
         instanceId: string;
     }) => T | Promise<T>, opts?: {
         instance?: string;

package/dist/game-client/client.js

@@ -454,6 +454,8 @@ export class GameClient {
     #transport;
     /** Where a labelled `screenshot()` lands — project-scoped by `@vgai/live`, cwd-relative otherwise. Public: a caller reading it is asking a fair question, and `screenshot()` returns a path under it anyway. */
     artifactsDir;
+    /** See `GameClientOptions.projectRoot`. */
+    #projectRoot;
     /** See `GameClientOptions.warmSession`. */
     #warmSession;
     /** See `GameClientOptions.testTitle`. */
@@ -484,6 +486,7 @@ export class GameClient {
         this.fenceSimSeconds = opts.fenceSimSeconds;
         this.fenceWallMs = opts.fenceWallMs;
         this.artifactsDir = opts.artifactsDir ?? resolve('.vgai/last-run');
+        this.#projectRoot = opts.projectRoot;
         this.#warmSession = opts.warmSession ?? false;
         this.#testTitle = opts.testTitle ?? 'test';
         this.#bridgeHeartbeat = { lastEmitWallMs: Date.now() };
@@ -705,16 +708,33 @@ export class GameClient {
             artifactsDir: this.artifactsDir,
             sequence: this.#screenshotCounter + 1,
             cwd: process.cwd(),
+            projectRoot: this.#projectRoot,
         });
         if (target.consumedSequence)
             this.#screenshotCounter += 1;
         await mkdir(dirname(target.path), { recursive: true });
-        const notes = await this.#transport.screenshot(target.path);
+        const transportNotes = await this.#transport.screenshot(target.path);
+        // The out-path resolver is the only thing that knows the destination fell
+        // under the served project root, and the notes are where a capture says
+        // what it cost — so the two are joined here rather than at either end.
+        const notes = {
+            ...transportNotes,
+            ...(target.underWatchedProjectRoot === undefined
+                ? {}
+                : { watchedProjectRoot: target.underWatchedProjectRoot }),
+        };
         const capture = {
             label: labelOrPath,
             path: target.path,
             caveat: describeCaptureCaveat(notes),
         };
+        // ONE place says the sentence, with the WHOLE note set — a human watching
+        // this terminal and a run record read beside the frame must not be told
+        // different things (`capture-notes.ts`'s contract). The transport used to
+        // warn from its own partial set, which silently dropped every note this
+        // layer adds.
+        if (capture.caveat !== null)
+            console.warn(`vgai screenshot: ${capture.path} — ${capture.caveat}`);
         // Sequential and AWAITED: a listener may need to read the game to stamp
         // this capture, and it must have finished before the path is handed back —
         // a caller that files the path is entitled to assume the record of it is
@@ -780,6 +800,22 @@ export class GameClient {
      * 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.
+     *
+     * `modules(path)` IS ASYNC — it dynamic-imports that url — so the callback
+     * is `async` and the call is `await`ed, in every example on this page and
+     * everywhere else. Skipping it does not fail quietly: reading a member off
+     * the unawaited promise throws a message naming the fix, because
+     * `TypeError: modules(...).simHost is not a function` (measured, cold fox
+     * #3) says nothing about promises.
+     *
+     * `modules` IS A FUNCTION, not a table — there is no module registry. To ask
+     * what the mount has loaded, read `modules.loaded`, the project-relative
+     * paths you can pass straight back in:
+     *
+     * ```js
+     * await game.run(({ modules }) => modules.loaded)
+     * // → ['src/scenes/MainScene.tsx', 'src/world.tsx', …]
+     * ```
      */
     async run(step, opts) {
         const erased = (arg) => step(arg);

package/dist/game-client/relay-transport.d.ts

@@ -19,7 +19,7 @@
  * anywhere in this path).
  */
 import type { BridgeCallOutcome, BridgeTransport } from './bridge-transport.js';
-import { type CaptureNotes } from './capture-notes.js';
+import type { CaptureNotes } from './capture-notes.js';
 export interface RelayTransportOptions {
     /** The live editor session's dev-server port (e.g. from
      *  `findLiveEditorSession`/`vgai edit`). */

package/dist/game-client/relay-transport.js

@@ -20,7 +20,6 @@
  */
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
-import { describeCaptureCaveat } from './capture-notes.js';
 const DEFAULT_TIMEOUT_MS = 10_000;
 /** `invoke` dispatches to arbitrary game-registered debug commands — give it
  *  real headroom rather than the ordinary sync-call budget above. */
@@ -236,16 +235,20 @@ export class RelayTransport {
         // is indistinguishable from a good one until somebody opens the file —
         // which is exactly how two probes cited blank captures as evidence. The
         // page measured both conditions; carry them back so the caller can persist
-        // them beside the frame, and say the composed sentence here too, where a
-        // human watching this terminal is looking.
+        // them beside the frame.
+        //
+        // The SENTENCE is not said here. `GameClient.screenshot` composes it from
+        // these notes PLUS the ones only it has (the out-path's relation to the
+        // served project root), and `capture-notes.ts`'s whole contract is that
+        // the terminal and the persisted record cannot drift — which a second
+        // `console.warn` on a partial set is exactly how they would.
         const warning = body['flatness']?.warning;
+        const recordingPath = body['recording']?.path;
         const notes = {
             ...(body['loopRecoveryFrame'] === true ? { loopRecoveryFrame: true } : {}),
             ...(typeof warning === 'string' ? { flatnessWarning: warning } : {}),
+            ...(typeof recordingPath === 'string' ? { recordingPath } : {}),
         };
-        const caveat = describeCaptureCaveat(notes);
-        if (caveat !== null)
-            console.warn(`vgai screenshot: ${path} — ${caveat}`);
         return notes;
     }
     /**

package/dist/game-client/screenshot-target.d.ts

@@ -43,6 +43,10 @@ export interface ScreenshotTargetInput {
     readonly sequence: number;
     /** Base for resolving a relative path/artifactsDir — the process cwd. */
     readonly cwd: string;
+    /** The project root the dev server is SERVING, when it is known. Only used
+     *  to say whether the destination lands under the file watcher — see
+     *  {@link ScreenshotTarget.underWatchedProjectRoot}. */
+    readonly projectRoot?: string | undefined;
 }
 export interface ScreenshotTarget {
     readonly kind: ScreenshotArgKind;
@@ -51,6 +55,19 @@ export interface ScreenshotTarget {
     /** True when the caller's own ordinal was consumed (label form only), so a
      *  path-form call never perturbs the numbering of the artifacts around it. */
     readonly consumedSequence: boolean;
+    /**
+     * The served project root this destination falls under, when it does.
+     *
+     * The dev server watches the project root for source changes and its
+     * `server.watch.ignored` list names build output only (`dist/`, `.vercel/`,
+     * `logs/`, `.claude/worktrees/`) — nothing about capture output. So a PNG
+     * written anywhere under the root goes through the watcher on every shot,
+     * and the cost is not theoretical: measured ~3x slower frame rates while a
+     * capture loop wrote under the project. This does not CHANGE where anything
+     * is written; it lets the capture say what it costs
+     * ({@link import('./capture-notes.js').describeCaptureCaveat}).
+     */
+    readonly underWatchedProjectRoot?: string;
 }
 /**
  * Resolve the absolute file a screenshot call must write. Pure — no I/O, no

package/dist/game-client/screenshot-target.js

@@ -19,7 +19,7 @@
  * resolved against the process cwd — the same rule `vgai screenshot --out`
  * already documents.
  */
-import { isAbsolute, resolve } from 'node:path';
+import { isAbsolute, relative, resolve } from 'node:path';
 /**
  * PATH when the argument names a location: absolute, containing a `/` or `\`
  * separator, an explicit `./`-style relative prefix, or carrying a file
@@ -45,6 +45,17 @@ export function classifyScreenshotArg(arg) {
 export function sanitizeScreenshotLabel(label) {
     return label.replace(/[^a-zA-Z0-9-_]+/g, '-');
 }
+/** Is `file` inside `root` (not merely sharing a path prefix)? */
+function isUnder(root, file) {
+    const rel = relative(resolve(root), file);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+/** The watched-root note, when the destination has one. */
+function watchedRoot(path, projectRoot) {
+    if (projectRoot === undefined || projectRoot === '')
+        return {};
+    return isUnder(projectRoot, path) ? { underWatchedProjectRoot: resolve(projectRoot) } : {};
+}
 /**
  * Resolve the absolute file a screenshot call must write. Pure — no I/O, no
  * `process.cwd()` read — so the contract above is testable without a browser,
@@ -54,15 +65,23 @@ export function resolveScreenshotTarget(input) {
     const kind = classifyScreenshotArg(input.arg);
     if (kind === 'path') {
         const withExtension = /\.[a-zA-Z0-9]{1,8}$/.test(input.arg) ? input.arg : `${input.arg}.png`;
+        const path = isAbsolute(withExtension) ? withExtension : resolve(input.cwd, withExtension);
         return {
             kind,
-            path: isAbsolute(withExtension) ? withExtension : resolve(input.cwd, withExtension),
+            path,
             consumedSequence: false,
+            ...watchedRoot(path, input.projectRoot),
         };
     }
     const fileName = `${String(input.sequence).padStart(3, '0')}-${sanitizeScreenshotLabel(input.arg)}.png`;
     const dir = isAbsolute(input.artifactsDir)
         ? input.artifactsDir
         : resolve(input.cwd, input.artifactsDir);
-    return { kind, path: resolve(dir, fileName), consumedSequence: true };
+    const path = resolve(dir, fileName);
+    return {
+        kind,
+        path,
+        consumedSequence: true,
+        ...watchedRoot(path, input.projectRoot),
+    };
 }

package/dist/game.d.ts

@@ -52,7 +52,7 @@ export interface LiveGame extends GameClient {
 /** The unaddressed `game` client — targets the sole live instance and refuses
  *  when several are mounted. Kept as a named export for callers/tests that
  *  want just the base client. */
-export declare function createGameClient(port: number, artifactsDir?: string): GameClient;
+export declare function createGameClient(port: number, artifactsDir?: string, projectRoot?: string): GameClient;
 /** Build the `LiveGame` — the base `game` client plus its instance-addressing
  *  surface. */
-export declare function createLiveGame(port: number, artifactsDir?: string): LiveGame;
+export declare function createLiveGame(port: number, artifactsDir?: string, projectRoot?: string): LiveGame;

package/dist/game.js

@@ -32,7 +32,7 @@ import { GameClient, RelayTransport } from './game-client/index.js';
  * fence. `pageErrors`/`consoleErrors` are always empty — relay mode has no
  * separate page handle to listen on.
  */
-function gameClientFor(port, artifactsDir, instance) {
+function gameClientFor(port, artifactsDir, instance, projectRoot) {
     return new GameClient({
         transport: new RelayTransport(instance === undefined ? { port } : { port, instance }),
         pageErrors: [],
@@ -43,13 +43,14 @@ function gameClientFor(port, artifactsDir, instance) {
         fenceWallMs: Date.now(),
         warmSession: false,
         artifactsDir,
+        projectRoot,
     });
 }
 /** The unaddressed `game` client — targets the sole live instance and refuses
  *  when several are mounted. Kept as a named export for callers/tests that
  *  want just the base client. */
-export function createGameClient(port, artifactsDir) {
-    return gameClientFor(port, artifactsDir);
+export function createGameClient(port, artifactsDir, projectRoot) {
+    return gameClientFor(port, artifactsDir, undefined, projectRoot);
 }
 /** Query the editor's live instance ids over the session wire.
  *
@@ -73,12 +74,12 @@ async function listInstanceIds(port) {
 }
 /** Build the `LiveGame` — the base `game` client plus its instance-addressing
  *  surface. */
-export function createLiveGame(port, artifactsDir) {
-    const base = gameClientFor(port, artifactsDir);
+export function createLiveGame(port, artifactsDir, projectRoot) {
+    const base = gameClientFor(port, artifactsDir, undefined, projectRoot);
     // Tag each addressed handle with the mount id it drives, so a caller can pass
     // `handle.id` to `tools.run(..., { instance })`. The id is already known here
     // (it is what parameterizes the relay); attaching it just hands it back.
-    const instance = (id) => Object.assign(gameClientFor(port, artifactsDir, id), { id });
+    const instance = (id) => Object.assign(gameClientFor(port, artifactsDir, id, projectRoot), { id });
     const instances = async () => (await listInstanceIds(port)).map(instance);
     return Object.assign(base, { instance, instances });
 }

package/dist/index.d.ts

@@ -29,7 +29,7 @@
  *
  * `editor.document` is the OTHER surface door and the one that is NOT
  * play-mode gated: `page(step)` is rooted at the running GAME container, so
- * `editor.document.{query,click,key,paste}` is how an editor surface that is
+ * `editor.document.{query,click,key,paste,select}` is how an editor surface that is
  * not a game — a capability's workspace document, the Data sheet — gets read
  * and driven through the product. It is scoped to the ACTIVE document and
  * refuses anything outside it by name (`editor-document.ts`).

package/dist/index.js

@@ -29,7 +29,7 @@
  *
  * `editor.document` is the OTHER surface door and the one that is NOT
  * play-mode gated: `page(step)` is rooted at the running GAME container, so
- * `editor.document.{query,click,key,paste}` is how an editor surface that is
+ * `editor.document.{query,click,key,paste,select}` is how an editor surface that is
  * not a game — a capability's workspace document, the Data sheet — gets read
  * and driven through the product. It is scoped to the ACTIVE document and
  * refuses anything outside it by name (`editor-document.ts`).
@@ -67,7 +67,7 @@ export { LiveTools } from './tools.js';
 function bindTo(port, projectRoot) {
     const client = new EditorClient({ url: `http://127.0.0.1:${port}` });
     const editor = new LiveEditor(client);
-    const game = createLiveGame(port, join(projectRoot, '.vgai', 'last-run'));
+    const game = createLiveGame(port, join(projectRoot, '.vgai', 'last-run'), projectRoot);
     const step = (fn) => game.page(fn);
     const page = Object.assign(step, { reload: () => game.reloadPage() });
     const tools = new LiveTools(client);

package/package.json

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

package/src/editor-document.ts

@@ -1,7 +1,7 @@
 /**
  * `editor.document` — the session binding for the scoped editor-chrome door.
  *
- * WHY IT IS A SEPARATE OBJECT, and why the verbs are these four, is recorded
+ * WHY IT IS A SEPARATE OBJECT, and why the verbs are these five, is recorded
  * once in the implementation's header
  * (`packages/editor/src/editor-document-probe.ts`); the short version is that
  * `game.page()` is play-mode-gated and rooted at the GAME container, so an
@@ -16,7 +16,7 @@
  * RENDERED rather than what a DOM scrape can find.
  *
  * A field on `LiveEditor` rather than methods on it, so `vgai eval --list`
- * shows the four verbs as one named surface — the same reason `game.input`
+ * shows the six verbs as one named surface — the same reason `game.input`
  * and `game.events` are instance fields.
  */
 
@@ -69,6 +69,41 @@ export class LiveEditorDocument {
     });
   }
 
+  /**
+   * A real pointer DRAG across one matched element — press at `from`, move,
+   * release at `to`, as fractions of the element's box (`[0.5, 0.5]` is its
+   * center). The gesture a direct-manipulation canvas needs; a zero-length
+   * drag is a click at that fraction, which `click` (always the center)
+   * cannot place.
+   */
+  async drag(
+    selector: string,
+    options: DocumentGestureOptions & {
+      from: [number, number];
+      to: [number, number];
+      via?: [number, number][];
+      steps?: number;
+      altKey?: boolean;
+      ctrlKey?: boolean;
+      metaKey?: boolean;
+      shiftKey?: boolean;
+    },
+  ): Promise<DocumentProbeResult> {
+    return this.#probe({
+      action: 'drag',
+      selector,
+      from: options.from,
+      to: options.to,
+      ...(options.via === undefined ? {} : { via: options.via }),
+      ...(options.steps === undefined ? {} : { steps: options.steps }),
+      ...(options.index === undefined ? {} : { index: options.index }),
+      ...(options.altKey === undefined ? {} : { altKey: options.altKey }),
+      ...(options.ctrlKey === undefined ? {} : { ctrlKey: options.ctrlKey }),
+      ...(options.metaKey === undefined ? {} : { metaKey: options.metaKey }),
+      ...(options.shiftKey === undefined ? {} : { shiftKey: options.shiftKey }),
+    });
+  }
+
   /** A real keydown/keyup on the target, or on whatever inside the document has focus. */
   async key(key: string, options?: DocumentKeyOptions): Promise<DocumentProbeResult> {
     return this.#probe({ action: 'key', key, ...(options ?? {}) });
@@ -80,6 +115,41 @@ export class LiveEditorDocument {
     return this.#probe({ action: 'paste', text, ...(options ?? {}) });
   }
 
+  /**
+   * Choose `value` on a `<select>` — a native dropdown's options are drawn by
+   * the OS, so `click` has nothing in the document to resolve, and a plain
+   * `element.value =` is invisible to React. Set through the prototype's own
+   * value setter plus `input`/`change`; `value` is the option's `value`, not
+   * its label. An unknown value is refused with the options it does offer.
+   */
+  async select(
+    selector: string,
+    value: string,
+    options?: DocumentGestureOptions,
+  ): Promise<DocumentProbeResult> {
+    return this.#probe({
+      action: 'select',
+      selector,
+      value,
+      ...(options?.index === undefined ? {} : { index: options.index }),
+    });
+  }
+
+  /**
+   * THE REPL over the open document: run `step` in the editor page against the
+   * object the ACTIVE document published as its context (the mesh document
+   * publishes its `MeshEditSession`, whose `ctx` is the bpy-shaped edit
+   * context — `ctx.ops.mesh.bevel({ offset: 0.1 })`, `ctx.selection`,
+   * `ctx.history`, `session.commit()`). Edit mode, no play. Serialized like
+   * `game.page`: the step's own source travels, so inline every value it
+   * needs and return plain data.
+   */
+  async run<T = unknown>(
+    step: (ctx: unknown, info: { documentId: string }) => T | Promise<T>,
+  ): Promise<T> {
+    return this.#client.documentScript<T>(step.toString());
+  }
+
   #probe(step: DocumentProbeStep): Promise<DocumentProbeResult> {
     return this.#client.documentProbe(step);
   }