@vgai/live 0.5.42 → 0.5.45

package/dist/editor-document.d.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.
  */
 import type { DocumentProbeResult, EditorClient } from '@vgai/editor-sdk';
@@ -48,9 +48,46 @@ export declare class LiveEditorDocument {
     /** A REAL pointer gesture (pointerdown/mousedown/focus/pointerup/mouseup/click)
      *  — not `element.click()`, which a `pointerdown` listener never sees. */
     click(selector: string, options?: DocumentGestureOptions): Promise<DocumentProbeResult>;
+    /**
+     * 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.
+     */
+    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>;
     /** A real keydown/keyup on the target, or on whatever inside the document has focus. */
     key(key: string, options?: DocumentKeyOptions): Promise<DocumentProbeResult>;
     /** A real `ClipboardEvent` carrying `text/plain` — the gesture nothing else
      *  in the product can produce. */
     paste(text: string, options?: DocumentPasteOptions): Promise<DocumentProbeResult>;
+    /**
+     * 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.
+     */
+    select(selector: string, value: string, options?: DocumentGestureOptions): Promise<DocumentProbeResult>;
+    /**
+     * 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.
+     */
+    run<T = unknown>(step: (ctx: unknown, info: {
+        documentId: string;
+    }) => T | Promise<T>): Promise<T>;
 }

package/dist/editor-document.js

@@ -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.
  */
 export class LiveEditorDocument {
@@ -42,6 +42,28 @@ export class LiveEditorDocument {
             ...(options?.index === undefined ? {} : { index: options.index }),
         });
     }
+    /**
+     * 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, options) {
+        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, options) {
         return this.#probe({ action: 'key', key, ...(options ?? {}) });
@@ -51,6 +73,33 @@ export class LiveEditorDocument {
     async paste(text, options) {
         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, value, options) {
+        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(step) {
+        return this.#client.documentScript(step.toString());
+    }
     #probe(step) {
         return this.#client.documentProbe(step);
     }

package/dist/editor.d.ts

@@ -10,7 +10,7 @@
  * hand-rolls a `fetch` to `/__editor/command` itself, and has no FILE-mode
  * escape hatch: every method goes over the wire.
  */
-import type { ActiveDocumentCapture, AnimationCaptureAction, AssetKind, AssetPreviewCapture, AssetPreviewOptions, AssetPreviewSource, EditorClient, EditorState, EditorView, HistoryStep, InspectedFieldWrite, InspectedHierarchy, InspectedInspection, OpenedDocument, PresentedEditorView, RagdollGenerationResult, ShadingMode, ViewPreset, ViewportCapture } from '@vgai/editor-sdk';
+import type { ActiveDocumentCapture, AnimationCaptureAction, 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';
 import { LiveEditorDocument } from './editor-document.js';
 import { LiveGameplayRecording } from './recording.js';
 /** `vgai show <...>`'s four sub-verbs folded into one action name — see `showPanel`. */
@@ -52,8 +52,25 @@ export declare class LiveEditor {
     present(view: EditorView): Promise<PresentedEditorView>;
     /** The human editor's actual active document, selection, camera and utility. */
     currentView(): Promise<EditorView>;
-    /** Capture the same center document the human is currently looking at. */
-    captureActiveDocument(size?: number): Promise<ActiveDocumentCapture>;
+    /**
+     * 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.
+     */
+    captureActiveDocument(size?: CaptureDimensions, view?: EditorView): Promise<ActiveDocumentCapture>;
+    /**
+     * 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.
+     */
+    captureEditorChrome(): Promise<EditorChromeCapture>;
     play(opts?: {
         seed?: number;
     }): Promise<void>;
@@ -77,6 +94,46 @@ export declare class LiveEditor {
      * would otherwise be indistinguishable from one that worked.
      */
     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).
+     */
+    frame(options?: {
+        readonly fit?: number;
+    }): Promise<void>;
+    /**
+     * 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.
+     */
+    orbit(options: {
+        readonly azimuth?: number;
+        readonly elevation?: number;
+        readonly duration?: number;
+    }): Promise<DocumentLookOutcome>;
+    /**
+     * 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.
+     */
+    turntable(options?: {
+        readonly seconds?: number;
+        readonly revolutions?: number;
+    }): Promise<DocumentLookOutcome>;
     view(preset: ViewPreset): Promise<void>;
     /**
      * Show several instances of the running game split-screen — the whole point
@@ -89,10 +146,37 @@ export declare class LiveEditor {
      * session.
      */
     instances(countOrNames: number | string[]): Promise<void>;
+    /**
+     * 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.
+     */
+    workspace(id: EditorWorkspaceName): Promise<void>;
     /** `vgai show <viewport <edit|play>|inspector|console|build>`'s four sub-verbs, folded into one action name. */
     showPanel(name: PanelName): Promise<void>;
     /** `kind` inferred from `path`'s extension when omitted (`inferAssetKind`) — pass it explicitly to override. */
     openAsset(path: string, kind?: AssetKind): Promise<void>;
+    /**
+     * 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.
+     */
+    selectAsset(path: string): Promise<void>;
     /**
      * 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.
@@ -110,6 +194,16 @@ export declare class LiveEditor {
      * always produced, and the bytes form is lab-only.
      */
     assetPreview(source: string | AssetPreviewSource, options?: AssetPreviewOptions): Promise<AssetPreviewCapture>;
+    /**
+     * 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.
+     */
+    assetPreviewShots(source: string | AssetPreviewSource, definition: AssetPreviewShotSetDefinition, options?: AssetPreviewOptions): Promise<LabeledShotSetCapture>;
     grid(on: boolean): Promise<void>;
     helpers(on: boolean): Promise<void>;
     stats(on: boolean): Promise<void>;
@@ -150,6 +244,49 @@ export declare class LiveEditor {
     /** Run one verb listed by `inspect().quickActions`, through the same action
      * the human Inspector button invokes. */
     runAction(actionId: string): Promise<InspectedInspection>;
+    /**
+     * 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.
+     */
+    structure(op: StructureOp, options?: StructureOpOptions): Promise<StructureOpResult>;
+    /**
+     * "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.
+     */
+    extractComponent(options?: {
+        id?: string;
+        name?: string;
+    }): Promise<string>;
+    /**
+     * "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.
+     */
+    forkComponent(options?: {
+        id?: string;
+    }): Promise<string>;
     /**
      * READ the hierarchy panel, as data — the rows a human is looking at right
      * now, nested exactly as the panel nests them.

package/dist/editor.js

@@ -30,6 +30,23 @@ const EXTENSION_KIND = {
     '.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',
 };
 /**
  * Lightweight extension-based `AssetKind` guess for `openAsset`'s optional
@@ -91,9 +108,28 @@ export class LiveEditor {
     async currentView() {
         return this.#client.currentView();
     }
-    /** Capture the same center document the human is currently looking at. */
-    async captureActiveDocument(size) {
-        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, view) {
+        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() {
+        return this.#client.captureEditorChrome();
     }
     async play(opts) {
         await this.#client.play(opts);
@@ -133,16 +169,40 @@ export class LiveEditor {
         }
         await this.#client.focusSelection();
     }
+    async frame(target) {
+        if (typeof target === 'string') {
+            await this.#client.frameEntity(target);
+            return;
+        }
+        await this.#client.frameDocument(target?.fit);
+    }
     /**
-     * Frame the edit viewport camera on one entity. Same framing as
-     * `focus(id)`, but an entity id the scene does not know THROWS, naming the
-     * id — where `focus` quietly does nothing. Reach for this whenever the next
-     * step reads the viewport (`screenshot()`, an
-     * `assetPreview(..., { stage: 'scene' })`): a framing that silently missed
-     * would otherwise be indistinguishable from one that worked.
+     * 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 frame(entityId) {
-        await this.#client.frameEntity(entityId);
+    async orbit(options) {
+        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) {
+        return this.#client.turntableDocument(options);
     }
     async view(preset) {
         await this.#client.viewPreset(preset);
@@ -160,6 +220,24 @@ export class LiveEditor {
     async instances(countOrNames) {
         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) {
+        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) {
         switch (name) {
@@ -184,6 +262,19 @@ export class LiveEditor {
     async openAsset(path, kind) {
         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) {
+        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.
@@ -205,6 +296,18 @@ export class LiveEditor {
     async assetPreview(source, options) {
         return this.#client.captureAssetPreview(typeof source === 'string' ? { assetPath: source } : source, options);
     }
+    /**
+     * 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, definition, options) {
+        return this.#client.captureShotSetPreview(typeof source === 'string' ? { assetPath: source } : source, definition, options);
+    }
     async grid(on) {
         await this.#client.setGrid(on);
     }
@@ -259,6 +362,50 @@ export class LiveEditor {
     async runAction(actionId) {
         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, options) {
+        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) {
+        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) {
+        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/dist/game-client/capture-notes.d.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
@@ -20,7 +28,7 @@
  * listener — so the words a human reads in the terminal and the words a run
  * 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
@@ -29,6 +37,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
  *  on disk. `caveat` is already composed — see {@link describeCaptureCaveat} —
@@ -50,8 +68,8 @@ export type CaptureListener = (capture: CaptureRecord) => void | Promise<void>;
  * 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 declare function describeCaptureCaveat(notes: CaptureNotes): string | null;