@vgai/live 0.5.42 → 0.5.44

package/src/editor.ts

@@ -17,18 +17,27 @@ import type {
   AssetKind,
   AssetPreviewCapture,
   AssetPreviewOptions,
+  AssetPreviewShotSetDefinition,
   AssetPreviewSource,
+  CaptureDimensions,
+  DocumentLookOutcome,
+  EditorChromeCapture,
   EditorClient,
   EditorState,
   EditorView,
+  EditorWorkspaceName,
   HistoryStep,
   InspectedFieldWrite,
   InspectedHierarchy,
   InspectedInspection,
+  LabeledShotSetCapture,
   OpenedDocument,
   PresentedEditorView,
   RagdollGenerationResult,
   ShadingMode,
+  StructureOp,
+  StructureOpOptions,
+  StructureOpResult,
   ViewPreset,
   ViewportCapture,
 } from '@vgai/editor-sdk';
@@ -56,6 +65,23 @@ const EXTENSION_KIND: Record<string, AssetKind> = {
   '.glsl': 'source',
   '.vert': 'source',
   '.frag': 'source',
+  // PROJECT SCRIPTS ARE SOURCE. Without these the guess below falls through to
+  // `'json'`, the asset-document router sends the file to the generic JSON
+  // viewer (`asset-documents.tsx#assetDocumentViewerRoute`: `spec.kind ===
+  // 'json'` is decided before any content routing), and the LIVE MODELING
+  // DOCUMENT never mounts — `editor.openAsset('src/lib/fox/fox.model.ts')`
+  // silently shows a text pane instead of the model. Only `kind: 'source'`
+  // reaches `SourceAssetViewer`, which is what content-routes a project script
+  // to `LiveModuleDocument`. The set matches that viewer's own
+  // `isProjectScriptPath` regex, `/\.(?:[cm]?[jt]sx?)$/`.
+  '.ts': 'source',
+  '.tsx': 'source',
+  '.mts': 'source',
+  '.cts': 'source',
+  '.js': 'source',
+  '.jsx': 'source',
+  '.mjs': 'source',
+  '.cjs': 'source',
 };
 
 /**
@@ -125,9 +151,32 @@ export class LiveEditor {
     return this.#client.currentView();
   }
 
-  /** Capture the same center document the human is currently looking at. */
-  async captureActiveDocument(size?: number): Promise<ActiveDocumentCapture> {
-    return this.#client.captureActiveDocument(size);
+  /**
+   * Capture the same center document the human is currently looking at.
+   *
+   * A number is a SQUARE of that size — the default, and the right shape for
+   * an unstaged look at a model. `{width, height}` asks for a shaped frame, so
+   * a video-aspect look needs no crop afterwards. Both are bounded by the
+   * relay budget (64-1024 per side, total no larger than a 1024 square); see
+   * `@vgai/editor-sdk`'s `CaptureDimensions`.
+   * Supply a view to present and photograph it in one editor request.
+   */
+  async captureActiveDocument(
+    size?: CaptureDimensions,
+    view?: EditorView,
+  ): Promise<ActiveDocumentCapture> {
+    return this.#client.captureActiveDocument(size, view);
+  }
+
+  /**
+   * Photograph the editor PAGE — every panel, tab strip and viewport as the
+   * person sees it. `vgai screenshot editor` is this verb from the shell. The
+   * one door for judging chrome sighted: a skin, a workspace arrangement or a
+   * contributed panel is looked at through this, never guessed at from DOM
+   * probes. Returns the page at its own size.
+   */
+  async captureEditorChrome(): Promise<EditorChromeCapture> {
+    return this.#client.captureEditorChrome();
   }
 
   async play(opts?: { seed?: number }): Promise<void> {
@@ -184,8 +233,57 @@ export class LiveEditor {
    * `assetPreview(..., { stage: 'scene' })`): a framing that silently missed
    * would otherwise be indistinguishable from one that worked.
    */
-  async frame(entityId: string): Promise<void> {
-    await this.#client.frameEntity(entityId);
+  async frame(entityId: string): Promise<void>;
+  /**
+   * Bare `frame()` frames the OPEN Object3D document's subject instead — its
+   * selection if it has one, else the whole model: the toolbar's own Frame
+   * button, reachable from a script. `fit` scales the fitted distance (1 is
+   * that button's tight fit, 1.5 stands back a little for a shot).
+   */
+  async frame(options?: { readonly fit?: number }): Promise<void>;
+  async frame(target?: string | { readonly fit?: number }): Promise<void> {
+    if (typeof target === 'string') {
+      await this.#client.frameEntity(target);
+      return;
+    }
+    await this.#client.frameDocument(target?.fit);
+  }
+
+  /**
+   * WATCH THE AGENT LOOK AROUND THE MODEL.
+   *
+   * Swings the open Object3D document's camera — the camera the human's tab is
+   * showing — around the framed subject by `azimuth`/`elevation` RADIANS,
+   * animated over `duration` seconds (default 0.6), and resolves when the move
+   * ends. This is deliberately not a jump cut: the point of the verb is that a
+   * person watching sees the agent walk around the thing it is working on.
+   *
+   * `await editor.orbit({ azimuth: Math.PI / 2 })` — a quarter turn to the right.
+   *
+   * There is ONE camera, and the human owns it: a drag during the move cancels
+   * it exactly where it is, and the resolved outcome says `cancelledBy:
+   * 'human'` rather than throwing. A second look verb supersedes the first.
+   * The move is drawn by the document's own frame loop, so a document that
+   * isn't being drawn (background tab, inactive panel) doesn't orbit.
+   */
+  async orbit(options: {
+    readonly azimuth?: number;
+    readonly elevation?: number;
+    readonly duration?: number;
+  }): Promise<DocumentLookOutcome> {
+    return this.#client.orbitDocument(options);
+  }
+
+  /**
+   * A slow full revolution of the open document's subject — {@link orbit} with
+   * the turns spelled out and a constant angular rate. Resolves at the end of
+   * the last revolution.
+   */
+  async turntable(options?: {
+    readonly seconds?: number;
+    readonly revolutions?: number;
+  }): Promise<DocumentLookOutcome> {
+    return this.#client.turntableDocument(options);
   }
 
   async view(preset: ViewPreset): Promise<void> {
@@ -206,6 +304,25 @@ export class LiveEditor {
     await this.#client.setInstanceCount(countOrNames);
   }
 
+  /**
+   * Switch the editor's NAMED WORKSPACE — `await editor.workspace('model')`.
+   *
+   * A workspace is a task-named LAYOUT MEMORY over the one dock
+   * (ARCHITECTURE-CORE §Editor chrome): `game` (the default, the editor's
+   * standing arrangement), `model`, `sculpt`, `texture`, `animate`, `look`.
+   * Switching is an EXPLICIT act — nothing in the editor moves chrome on its
+   * own, opening a document included — and this is the session door to it,
+   * beside `Window → Workspace` and the registered actions.
+   *
+   * Resolves once the dock has finished rebuilding, so a capture taken
+   * immediately after photographs the arrangement that was asked for. Each
+   * workspace remembers the user's own hand-tuning per project, so switching
+   * away and back is lossless.
+   */
+  async workspace(id: EditorWorkspaceName): Promise<void> {
+    await this.#client.setWorkspace(id);
+  }
+
   /** `vgai show <viewport <edit|play>|inspector|console|build>`'s four sub-verbs, folded into one action name. */
   async showPanel(name: PanelName): Promise<void> {
     switch (name) {
@@ -232,6 +349,20 @@ export class LiveEditor {
     await this.#client.openAsset(path, kind ?? inferAssetKind(path));
   }
 
+  /**
+   * SELECT a project asset — the browser's single click, which fills the
+   * Inspector without opening a document. `openAsset` is the double click.
+   *
+   * This is how a project's own `asset.inspector` section is reached: select
+   * the file it matches, then `inspect()` lists the verbs that section
+   * declares and `runAction(id)` runs one. Selecting a path nothing matches
+   * is not an error — the Inspector shows what it has, exactly as it does
+   * for a human.
+   */
+  async selectAsset(path: string): Promise<void> {
+    await this.#client.selectAsset(path);
+  }
+
   /**
    * Fit native Rapier bodies and joints to a rigged GLB/glTF, copy the reusable
    * project capability, and open the generated TSX prefab's Setup story.
@@ -261,6 +392,27 @@ export class LiveEditor {
     );
   }
 
+  /**
+   * The same subject photographed as a LABELED SHOT SET instead of the four
+   * views — a caller-supplied definition of turntable yaws and bone-anchored
+   * crops, rendered against the asset's own skeleton, with a contact sheet.
+   * Every source {@link assetPreview} takes works here, GLB bytes included:
+   * a shot set stages its own subject, so it needs no place to stand.
+   *
+   * Sole in-repo caller today: `project.bake.preview`'s `--orbit` lane.
+   */
+  async assetPreviewShots(
+    source: string | AssetPreviewSource,
+    definition: AssetPreviewShotSetDefinition,
+    options?: AssetPreviewOptions,
+  ): Promise<LabeledShotSetCapture> {
+    return this.#client.captureShotSetPreview(
+      typeof source === 'string' ? { assetPath: source } : source,
+      definition,
+      options,
+    );
+  }
+
   async grid(on: boolean): Promise<void> {
     await this.#client.setGrid(on);
   }
@@ -322,6 +474,53 @@ export class LiveEditor {
     return this.#client.runInspectionAction(actionId);
   }
 
+  /**
+   * RESTRUCTURE the authored tree — the hierarchy context menu's own verbs.
+   *
+   * `create`, `delete`, `duplicate`, `reparent`, `reorder`, `wrap`, `unwrap`,
+   * `group`, `ungroup`, `copy`, `cut`, `paste`; `extractComponent` and
+   * `forkComponent` are the two that write whole new files and have their own
+   * doors below. All of them run the SAME `authoring/consumer-actions.ts`
+   * helpers the menu items call, so there is one implementation of each op and
+   * not a second that can disagree with what a human gets.
+   *
+   * It exists because the menu is a POINTER surface: every one of these ops was
+   * reachable only by right-clicking a hierarchy row, which is nothing an agent
+   * can do — so for an ingest root, whose only authoring surface IS the editor,
+   * structure was closed entirely.
+   *
+   * `id`/`ids` default to the current selection. The answer carries the same
+   * per-edit `write` ack `setField` does, so `write.persisted` tells a saved
+   * restructure from a live-only one. An op the active adapter does not provide
+   * REJECTS by name — never a silent no-op.
+   */
+  async structure(op: StructureOp, options?: StructureOpOptions): Promise<StructureOpResult> {
+    return this.#client.structureOp(op, options ?? {});
+  }
+
+  /**
+   * "Extract Component…" — lift the selected native subtree into its own
+   * component file (plus a story) and replace the callsite with it.
+   *
+   * Answers the action's own sentence, which NAMES both new files, because
+   * undo owns the callsite edit and will not remove them.
+   */
+  async extractComponent(options?: { id?: string; name?: string }): Promise<string> {
+    return (await this.#client.extractComponent(options ?? {})).hint;
+  }
+
+  /**
+   * "Fork Component…" — copy the selected instance's component definition to a
+   * new file and retarget THIS CALLSITE at it.
+   *
+   * One callsite is the unit of the edit; when that callsite sits inside a
+   * component rendered many times, every one of those renders now renders the
+   * fork.
+   */
+  async forkComponent(options?: { id?: string }): Promise<string> {
+    return (await this.#client.forkComponent(options ?? {})).hint;
+  }
+
   /**
    * READ the hierarchy panel, as data — the rows a human is looking at right
    * now, nested exactly as the panel nests them.

package/src/game-client/capture-notes.ts

@@ -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
@@ -21,7 +29,7 @@
  * record carries beside the frame cannot drift apart.
  */
 
-/** The conditions a capture was taken under, as facts. Both fields are
+/** The conditions a capture was taken under, as facts. Every field is
  *  optional and absent means "not so": an ordinary frame carries no notes. */
 export interface CaptureNotes {
   /** The host loop was starved, so the frame exists only because the runtime
@@ -30,6 +38,16 @@ export interface CaptureNotes {
   /** The page's own near-blank-frame sentence, verbatim (it owns the wording;
    *  see `composite-screenshot.ts`'s `CaptureFlatness.warning`). */
   readonly flatnessWarning?: string;
+  /** The clip this frame is one frame OF — every `vgai play` records
+   *  (`play-recording.ts`). Not a degradation: the still is delivered and is
+   *  the right instrument for a look question. It is here because a still of a
+   *  MOVING game answers a temporal question only by luck, and a reader of the
+   *  persisted record has to be able to find the door that answers it. */
+  readonly recordingPath?: string;
+  /** The SERVED project root this capture was written under, when it was.
+   *  Not a degradation of the frame — a cost of taking it; see
+   *  {@link WATCHED_CAPTURE_PATH_CAVEAT}. */
+  readonly watchedProjectRoot?: string;
 }
 
 /** One capture, as reported to a {@link CaptureListener} after the bytes are
@@ -53,6 +71,20 @@ export type CaptureListener = (capture: CaptureRecord) => void | Promise<void>;
 /** 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.';
@@ -61,9 +93,9 @@ const LOOP_RECOVERY_FRAME_CAVEAT =
  * 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: CaptureNotes): string | null {
   const parts: string[] = [];
@@ -71,5 +103,14 @@ export function describeCaptureCaveat(notes: CaptureNotes): string | null {
   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/src/game-client/client.ts

@@ -256,6 +256,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
@@ -572,6 +577,8 @@ export class GameClient {
   readonly #transport: BridgeTransport;
   /** 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. */
   readonly artifactsDir: string;
+  /** See `GameClientOptions.projectRoot`. */
+  readonly #projectRoot: string | undefined;
   /** See `GameClientOptions.warmSession`. */
   readonly #warmSession: boolean;
   /** See `GameClientOptions.testTitle`. */
@@ -603,6 +610,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() };
@@ -862,15 +870,32 @@ 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: CaptureNotes = {
+      ...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
@@ -941,11 +966,27 @@ 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<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/src/game-client/relay-transport.ts

@@ -22,7 +22,7 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import type { BridgeCallOutcome, BridgeTransport } from './bridge-transport.js';
-import { type CaptureNotes, describeCaptureCaveat } 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
@@ -310,15 +310,20 @@ export class RelayTransport implements BridgeTransport {
     // 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'] as { warning?: string } | undefined)?.warning;
+    const recordingPath = (body['recording'] as { path?: string } | undefined)?.path;
     const notes: CaptureNotes = {
       ...(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/src/game-client/screenshot-target.ts

@@ -20,7 +20,7 @@
  * already documents.
  */
 
-import { isAbsolute, resolve } from 'node:path';
+import { isAbsolute, relative, resolve } from 'node:path';
 
 /** A caller's argument, classified. */
 export type ScreenshotArgKind = 'path' | 'label';
@@ -57,6 +57,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 {
@@ -66,6 +70,34 @@ 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;
+}
+
+/** Is `file` inside `root` (not merely sharing a path prefix)? */
+function isUnder(root: string, file: string): boolean {
+  const rel = relative(resolve(root), file);
+  return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+}
+
+/** The watched-root note, when the destination has one. */
+function watchedRoot(
+  path: string,
+  projectRoot: string | undefined,
+): { underWatchedProjectRoot: string } | Record<string, never> {
+  if (projectRoot === undefined || projectRoot === '') return {};
+  return isUnder(projectRoot, path) ? { underWatchedProjectRoot: resolve(projectRoot) } : {};
 }
 
 /**
@@ -77,15 +109,23 @@ export function resolveScreenshotTarget(input: ScreenshotTargetInput): Screensho
   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/src/game.ts

@@ -66,7 +66,12 @@ export interface LiveGame extends GameClient {
  * fence. `pageErrors`/`consoleErrors` are always empty — relay mode has no
  * separate page handle to listen on.
  */
-function gameClientFor(port: number, artifactsDir?: string, instance?: string): GameClient {
+function gameClientFor(
+  port: number,
+  artifactsDir?: string,
+  instance?: string,
+  projectRoot?: string,
+): GameClient {
   return new GameClient({
     transport: new RelayTransport(instance === undefined ? { port } : { port, instance }),
     pageErrors: [],
@@ -77,14 +82,19 @@ function gameClientFor(port: number, artifactsDir?: string, instance?: string):
     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: number, artifactsDir?: string): GameClient {
-  return gameClientFor(port, artifactsDir);
+export function createGameClient(
+  port: number,
+  artifactsDir?: string,
+  projectRoot?: string,
+): GameClient {
+  return gameClientFor(port, artifactsDir, undefined, projectRoot);
 }
 
 /** Query the editor's live instance ids over the session wire.
@@ -110,13 +120,17 @@ async function listInstanceIds(port: number): Promise<string[]> {
 
 /** Build the `LiveGame` — the base `game` client plus its instance-addressing
  *  surface. */
-export function createLiveGame(port: number, artifactsDir?: string): LiveGame {
-  const base = gameClientFor(port, artifactsDir);
+export function createLiveGame(
+  port: number,
+  artifactsDir?: string,
+  projectRoot?: string,
+): LiveGame {
+  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: string): AddressedGameClient =>
-    Object.assign(gameClientFor(port, artifactsDir, id), { id });
+    Object.assign(gameClientFor(port, artifactsDir, id, projectRoot), { id });
   const instances = async (): Promise<AddressedGameClient[]> =>
     (await listInstanceIds(port)).map(instance);
   return Object.assign(base, { instance, instances });

package/src/index.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`).
@@ -125,7 +125,7 @@ export interface LiveBindings {
 function bindTo(port: number, projectRoot: string): LiveBindings {
   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: GameClient['page'] = (fn) => game.page(fn);
   const page: PageStep = Object.assign(step, { reload: () => game.reloadPage() });
   const tools = new LiveTools(client);