@vgai/live 0.5.11 → 0.5.13

package/dist/editor-document.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `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
+ * 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
+ * editor surface that is not a running game could be neither read nor driven
+ * through the product. This door is the answer for exactly one subject: the
+ * ACTIVE center document. It is not page automation — a selector resolving
+ * outside that document's container is refused by a message naming the scope.
+ *
+ * It reaches editor chrome only in the sense that a project-tool document IS
+ * chrome; the dock, hierarchy and inspector keep their own doors
+ * (`editor.hierarchy()`, `editor.inspect()`), which report what those panels
+ * 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`
+ * and `game.events` are instance fields.
+ */
+import type { DocumentProbeResult, EditorClient } from '@vgai/editor-sdk';
+/** Modifier/targeting options shared by the gesture verbs. */
+export interface DocumentGestureOptions {
+    /** Which match to drive when the selector matches several (default 0). */
+    index?: number;
+}
+export interface DocumentKeyOptions extends DocumentGestureOptions {
+    /** Target one element instead of whatever inside the document has focus. */
+    selector?: string;
+    code?: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    shiftKey?: boolean;
+    altKey?: boolean;
+}
+export interface DocumentPasteOptions extends DocumentGestureOptions {
+    selector?: string;
+}
+export declare class LiveEditorDocument {
+    #private;
+    constructor(client: EditorClient);
+    /** Read matching elements inside the active document: tag, text, attributes,
+     *  value/checked/disabled and rect. `matched` is the total before `limit`. */
+    query(selector: string, options?: {
+        limit?: number;
+    }): Promise<DocumentProbeResult>;
+    /** 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 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>;
+}

package/dist/editor-document.js

@@ -0,0 +1,57 @@
+/**
+ * `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
+ * 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
+ * editor surface that is not a running game could be neither read nor driven
+ * through the product. This door is the answer for exactly one subject: the
+ * ACTIVE center document. It is not page automation — a selector resolving
+ * outside that document's container is refused by a message naming the scope.
+ *
+ * It reaches editor chrome only in the sense that a project-tool document IS
+ * chrome; the dock, hierarchy and inspector keep their own doors
+ * (`editor.hierarchy()`, `editor.inspect()`), which report what those panels
+ * 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`
+ * and `game.events` are instance fields.
+ */
+export class LiveEditorDocument {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    /** Read matching elements inside the active document: tag, text, attributes,
+     *  value/checked/disabled and rect. `matched` is the total before `limit`. */
+    async query(selector, options) {
+        return this.#probe({
+            action: 'query',
+            selector,
+            ...(options?.limit === undefined ? {} : { limit: options.limit }),
+        });
+    }
+    /** A REAL pointer gesture (pointerdown/mousedown/focus/pointerup/mouseup/click)
+     *  — not `element.click()`, which a `pointerdown` listener never sees. */
+    async click(selector, options) {
+        return this.#probe({
+            action: 'click',
+            selector,
+            ...(options?.index === undefined ? {} : { index: options.index }),
+        });
+    }
+    /** 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 ?? {}) });
+    }
+    /** A real `ClipboardEvent` carrying `text/plain` — the gesture nothing else
+     *  in the product can produce. */
+    async paste(text, options) {
+        return this.#probe({ action: 'paste', text, ...(options ?? {}) });
+    }
+    #probe(step) {
+        return this.#client.documentProbe(step);
+    }
+}

package/dist/editor.d.ts

@@ -10,7 +10,8 @@
  * hand-rolls a `fetch` to `/__editor/command` itself. (WO-8 removed the one
  * exception, `applyDiff`, which was FILE mode rather than a live wire command.)
  */
-import type { ActiveDocumentCapture, AssetKind, AssetPreviewCapture, AssetPreviewOptions, AssetPreviewSource, EditorClient, EditorState, EditorView, InspectedInspection, PresentedEditorView, ShadingMode, ViewPreset, ViewportCapture } from '@vgai/editor-sdk';
+import type { ActiveDocumentCapture, AssetKind, AssetPreviewCapture, AssetPreviewOptions, AssetPreviewSource, EditorClient, EditorState, EditorView, HistoryStep, InspectedHierarchy, InspectedInspection, PresentedEditorView, ShadingMode, ViewPreset, ViewportCapture } from '@vgai/editor-sdk';
+import { LiveEditorDocument } from './editor-document.js';
 /** `vgai show <...>`'s four sub-verbs folded into one action name — see `showPanel`. */
 export type PanelName = 'viewport-edit' | 'viewport-play' | 'inspector' | 'console' | 'build';
 /**
@@ -23,6 +24,15 @@ export type PanelName = 'viewport-edit' | 'viewport-play' | 'inspector' | 'conso
 export declare function inferAssetKind(path: string): AssetKind;
 export declare class LiveEditor {
     #private;
+    /**
+     * The ACTIVE center document's own DOM: read it, click it, key it, paste
+     * into it. The one door onto editor chrome that is not play-mode gated, and
+     * deliberately scoped to that document alone —
+     * `packages/editor/src/editor-document-probe.ts` carries the design and the
+     * refusal contract. Screenshotting the same subject is
+     * {@link LiveEditor.captureActiveDocument}, not a fifth verb here.
+     */
+    readonly document: LiveEditorDocument;
     constructor(client: EditorClient);
     /**
      * The active authoring adapter's persistence destination — where a save would
@@ -98,6 +108,24 @@ export declare class LiveEditor {
     helpers(on: boolean): Promise<void>;
     stats(on: boolean): Promise<void>;
     shading(mode: ShadingMode): Promise<void>;
+    /**
+     * CONSENT to edits being written into the game's own source files, for this
+     * session — the Game document's "Persist to game source" checkbox, reachable
+     * from a script.
+     *
+     * Off by default every session, on purpose: it is a statement about what you
+     * are doing right now, never a property of the game. With it off, an edit
+     * lives on the running object and says so; with it on, an edit that can be
+     * honestly anchored to the line that CREATED the object is written there,
+     * and one that cannot still says so. Answers with the server's own phrase for
+     * who records the resulting diff — your version control, or a vendored
+     * game's own lock — and refuses, with the reason, where the checkbox is
+     * disabled.
+     */
+    persistToGameSource(on: boolean): Promise<{
+        enabled: boolean;
+        recorder: string | null;
+    }>;
     /**
      * READ the inspector, as data — the serialized inspection subject
      * (`editor.inspect()`; design: `docs/ARCHITECTURE-CORE.md` §Editor chrome,
@@ -126,6 +154,43 @@ export declare class LiveEditor {
      * `{position, rotation, scale}`, rotation in Euler XYZ degrees).
      */
     inspect(): Promise<InspectedInspection>;
+    /**
+     * READ the hierarchy panel, as data — the rows a human is looking at right
+     * now, nested exactly as the panel nests them.
+     *
+     * The companion to {@link inspect}: that one answers "what IS the selected
+     * thing", this one answers "what does the tree LOOK LIKE". It is the panel's
+     * own output, not a fresh walk of the scene — the adapter's tree after the
+     * component marks fold implementation subtrees (bones, particle renderers,
+     * instanced pools), after the internals reveal, the document promotion, the
+     * child cap, the collapse state, the search filter and the selection scope.
+     *
+     * Works in play mode and edit mode; the answer says which (`playState`,
+     * `activeViewportTab`), because the two are different adapters and a tree
+     * that looks wrong is very often the wrong adapter's tree.
+     *
+     * Prefer this over `status().entities`, which is deliberately a different
+     * question — the RAW adapter tree, unprojected. A panel that renders the
+     * wrong rows looks perfectly healthy in that facet.
+     *
+     * Each row carries `childCount` (what its caret opens), `internalChildCount`
+     * (what is folded behind "Reveal Internals") and `expandable` (whether the
+     * panel draws a caret at all), so "this subtree exists but nothing in the UI
+     * opens it" is a fact you can read rather than one you have to notice.
+     *
+     * Rejects, naming the panel, when no hierarchy panel is mounted — an empty
+     * tree would be a fabricated answer about a surface nobody is being shown.
+     */
+    hierarchy(): Promise<InspectedHierarchy>;
+    /**
+     * Write one editable field from `inspect()` by its stable path, through the
+     * same Inspector IO and persistence boundary the human control uses.
+     */
+    setField(path: string, value: unknown): Promise<InspectedInspection>;
+    /** Undo / redo one project transaction, through the session's own history
+     *  queue — the same one the keyboard shortcut drives. */
+    undo(): Promise<HistoryStep>;
+    redo(): Promise<HistoryStep>;
     /** Mirrors `vgai status` — the full live editor state as JSON. */
     status(): Promise<EditorState>;
     /** A live viewport PNG (`EditorClient.captureViewport`) — no direct CLI verb exists; this is the closest wire read. */

package/dist/editor.js

@@ -10,6 +10,7 @@
  * hand-rolls a `fetch` to `/__editor/command` itself. (WO-8 removed the one
  * exception, `applyDiff`, which was FILE mode rather than a live wire command.)
  */
+import { LiveEditorDocument } from './editor-document.js';
 const EXTENSION_KIND = {
     '.glb': 'model',
     '.gltf': 'model',
@@ -19,10 +20,15 @@ const EXTENSION_KIND = {
     '.webp': 'image',
     '.gif': 'image',
     '.svg': 'image',
+    '.hdr': 'image',
+    '.exr': 'image',
     '.mp3': 'audio',
     '.ogg': 'audio',
     '.wav': 'audio',
     '.flac': 'audio',
+    '.glsl': 'source',
+    '.vert': 'source',
+    '.frag': 'source',
 };
 /**
  * Lightweight extension-based `AssetKind` guess for `openAsset`'s optional
@@ -32,14 +38,10 @@ const EXTENSION_KIND = {
  * on. Callers with an unusual extension can always pass `kind` explicitly.
  */
 export function inferAssetKind(path) {
-    // WO-8: `.vscn.json` mapped to 'scene' here. That format is deleted, and
-    // `.prefab.json` is likewise retired (PRs #578/#581/#589) but the `'prefab'`
-    // AssetKind itself still exists in `@vgai/editor-sdk`, so the mapping is left
-    // for that retirement's own follow-up rather than half-removed here.
+    // `.prefab.json` is retired (PRs #578/#581/#589) but the `'prefab'`
+    // AssetKind itself remains in `@vgai/editor-sdk` for view-link compatibility.
     if (path.endsWith('.prefab.json'))
         return 'prefab';
-    if (path.endsWith('.mat.json'))
-        return 'material';
     const dot = path.lastIndexOf('.');
     const ext = dot >= 0 ? path.slice(dot).toLowerCase() : '';
     return EXTENSION_KIND[ext] ?? 'json';
@@ -50,8 +52,18 @@ export class LiveEditor {
      *  raw `EditorClient` advertised beside them. See `./game-client/`'s
      *  `client.ts` (GameClient's field block) for the full reasoning. */
     #client;
+    /**
+     * The ACTIVE center document's own DOM: read it, click it, key it, paste
+     * into it. The one door onto editor chrome that is not play-mode gated, and
+     * deliberately scoped to that document alone —
+     * `packages/editor/src/editor-document-probe.ts` carries the design and the
+     * refusal contract. Screenshotting the same subject is
+     * {@link LiveEditor.captureActiveDocument}, not a fifth verb here.
+     */
+    document;
     constructor(client) {
         this.#client = client;
+        this.document = new LiveEditorDocument(client);
     }
     /**
      * The active authoring adapter's persistence destination — where a save would
@@ -203,6 +215,23 @@ export class LiveEditor {
     async shading(mode) {
         await this.#client.setShadingMode(mode);
     }
+    /**
+     * CONSENT to edits being written into the game's own source files, for this
+     * session — the Game document's "Persist to game source" checkbox, reachable
+     * from a script.
+     *
+     * Off by default every session, on purpose: it is a statement about what you
+     * are doing right now, never a property of the game. With it off, an edit
+     * lives on the running object and says so; with it on, an edit that can be
+     * honestly anchored to the line that CREATED the object is written there,
+     * and one that cannot still says so. Answers with the server's own phrase for
+     * who records the resulting diff — your version control, or a vendored
+     * game's own lock — and refuses, with the reason, where the checkbox is
+     * disabled.
+     */
+    async persistToGameSource(on) {
+        return this.#client.setSourcePersistConsent(on);
+    }
     /**
      * READ the inspector, as data — the serialized inspection subject
      * (`editor.inspect()`; design: `docs/ARCHITECTURE-CORE.md` §Editor chrome,
@@ -233,6 +262,51 @@ export class LiveEditor {
     async inspect() {
         return this.#client.inspect();
     }
+    /**
+     * READ the hierarchy panel, as data — the rows a human is looking at right
+     * now, nested exactly as the panel nests them.
+     *
+     * The companion to {@link inspect}: that one answers "what IS the selected
+     * thing", this one answers "what does the tree LOOK LIKE". It is the panel's
+     * own output, not a fresh walk of the scene — the adapter's tree after the
+     * component marks fold implementation subtrees (bones, particle renderers,
+     * instanced pools), after the internals reveal, the document promotion, the
+     * child cap, the collapse state, the search filter and the selection scope.
+     *
+     * Works in play mode and edit mode; the answer says which (`playState`,
+     * `activeViewportTab`), because the two are different adapters and a tree
+     * that looks wrong is very often the wrong adapter's tree.
+     *
+     * Prefer this over `status().entities`, which is deliberately a different
+     * question — the RAW adapter tree, unprojected. A panel that renders the
+     * wrong rows looks perfectly healthy in that facet.
+     *
+     * Each row carries `childCount` (what its caret opens), `internalChildCount`
+     * (what is folded behind "Reveal Internals") and `expandable` (whether the
+     * panel draws a caret at all), so "this subtree exists but nothing in the UI
+     * opens it" is a fact you can read rather than one you have to notice.
+     *
+     * Rejects, naming the panel, when no hierarchy panel is mounted — an empty
+     * tree would be a fabricated answer about a surface nobody is being shown.
+     */
+    async hierarchy() {
+        return this.#client.hierarchy();
+    }
+    /**
+     * Write one editable field from `inspect()` by its stable path, through the
+     * same Inspector IO and persistence boundary the human control uses.
+     */
+    async setField(path, value) {
+        return this.#client.setInspectionField(path, value);
+    }
+    /** Undo / redo one project transaction, through the session's own history
+     *  queue — the same one the keyboard shortcut drives. */
+    async undo() {
+        return this.#client.undo();
+    }
+    async redo() {
+        return this.#client.redo();
+    }
     /** Mirrors `vgai status` — the full live editor state as JSON. */
     async status() {
         return this.#client.getState();

package/dist/index.d.ts

@@ -27,6 +27,13 @@
  *   await editor.grid(true);
  *   await game.input.tap('jump');
  *
+ * `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
+ * 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`).
+ *
  * `page(step)` = `GameClient.page(step)` (Wave-2's playwright-shim surface,
  * PR #166) — write `step` as a literal `async (page) => {...}` and inline
  * every value it needs. KNOWN WIRE LIMITATION: under the relay transport this
@@ -44,6 +51,8 @@ import { LiveTools } from './tools.js';
 export type { ActiveDocumentCapture, EditorClient, EditorView, EditorViewDocument, PresentedEditorView, } from '@vgai/editor-sdk';
 export type { PanelName } from './editor.js';
 export { inferAssetKind, LiveEditor } from './editor.js';
+export type { DocumentGestureOptions, DocumentKeyOptions, DocumentPasteOptions, } from './editor-document.js';
+export { LiveEditorDocument } from './editor-document.js';
 export { createGameClient, createLiveGame, type LiveGame } from './game.js';
 export * from './game-client/index.js';
 export type { ProjectSessionHint, ResolvedSession, SessionListingTransport, SessionResolutionDeps, } from './session.js';

package/dist/index.js

@@ -27,6 +27,13 @@
  *   await editor.grid(true);
  *   await game.input.tap('jump');
  *
+ * `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
+ * 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`).
+ *
  * `page(step)` = `GameClient.page(step)` (Wave-2's playwright-shim surface,
  * PR #166) — write `step` as a literal `async (page) => {...}` and inline
  * every value it needs. KNOWN WIRE LIMITATION: under the relay transport this
@@ -45,6 +52,7 @@ import { resolveSession } from './session.js';
 import { createLazySession } from './singleton.js';
 import { LiveTools } from './tools.js';
 export { inferAssetKind, LiveEditor } from './editor.js';
+export { LiveEditorDocument } from './editor-document.js';
 export { createGameClient, createLiveGame } from './game.js';
 export * from './game-client/index.js';
 export { findProjectRootFrom, resolveSession } from './session.js';

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/live",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.11",
+  "version": "0.5.13",
   "type": "module",
   "repository": {
     "type": "git",
@@ -31,8 +31,8 @@
     "dev": "tsc -p tsconfig.build.json --watch --preserveWatchOutput"
   },
   "dependencies": {
-    "@vgai/editor-sdk": "0.5.11",
-    "@vgai/sdk": "0.5.11"
+    "@vgai/editor-sdk": "0.5.13",
+    "@vgai/sdk": "0.5.13"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.58.2 <2"

package/src/editor-document.ts

@@ -0,0 +1,86 @@
+/**
+ * `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
+ * 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
+ * editor surface that is not a running game could be neither read nor driven
+ * through the product. This door is the answer for exactly one subject: the
+ * ACTIVE center document. It is not page automation — a selector resolving
+ * outside that document's container is refused by a message naming the scope.
+ *
+ * It reaches editor chrome only in the sense that a project-tool document IS
+ * chrome; the dock, hierarchy and inspector keep their own doors
+ * (`editor.hierarchy()`, `editor.inspect()`), which report what those panels
+ * 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`
+ * and `game.events` are instance fields.
+ */
+
+import type { DocumentProbeResult, DocumentProbeStep, EditorClient } from '@vgai/editor-sdk';
+
+/** Modifier/targeting options shared by the gesture verbs. */
+export interface DocumentGestureOptions {
+  /** Which match to drive when the selector matches several (default 0). */
+  index?: number;
+}
+
+export interface DocumentKeyOptions extends DocumentGestureOptions {
+  /** Target one element instead of whatever inside the document has focus. */
+  selector?: string;
+  code?: string;
+  ctrlKey?: boolean;
+  metaKey?: boolean;
+  shiftKey?: boolean;
+  altKey?: boolean;
+}
+
+export interface DocumentPasteOptions extends DocumentGestureOptions {
+  selector?: string;
+}
+
+export class LiveEditorDocument {
+  readonly #client: EditorClient;
+
+  constructor(client: EditorClient) {
+    this.#client = client;
+  }
+
+  /** Read matching elements inside the active document: tag, text, attributes,
+   *  value/checked/disabled and rect. `matched` is the total before `limit`. */
+  async query(selector: string, options?: { limit?: number }): Promise<DocumentProbeResult> {
+    return this.#probe({
+      action: 'query',
+      selector,
+      ...(options?.limit === undefined ? {} : { limit: options.limit }),
+    });
+  }
+
+  /** A REAL pointer gesture (pointerdown/mousedown/focus/pointerup/mouseup/click)
+   *  — not `element.click()`, which a `pointerdown` listener never sees. */
+  async click(selector: string, options?: DocumentGestureOptions): Promise<DocumentProbeResult> {
+    return this.#probe({
+      action: 'click',
+      selector,
+      ...(options?.index === undefined ? {} : { index: options.index }),
+    });
+  }
+
+  /** 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 ?? {}) });
+  }
+
+  /** A real `ClipboardEvent` carrying `text/plain` — the gesture nothing else
+   *  in the product can produce. */
+  async paste(text: string, options?: DocumentPasteOptions): Promise<DocumentProbeResult> {
+    return this.#probe({ action: 'paste', text, ...(options ?? {}) });
+  }
+
+  #probe(step: DocumentProbeStep): Promise<DocumentProbeResult> {
+    return this.#client.documentProbe(step);
+  }
+}

package/src/editor.ts

@@ -20,12 +20,15 @@ import type {
   EditorClient,
   EditorState,
   EditorView,
+  HistoryStep,
+  InspectedHierarchy,
   InspectedInspection,
   PresentedEditorView,
   ShadingMode,
   ViewPreset,
   ViewportCapture,
 } from '@vgai/editor-sdk';
+import { LiveEditorDocument } from './editor-document.js';
 
 /** `vgai show <...>`'s four sub-verbs folded into one action name — see `showPanel`. */
 export type PanelName = 'viewport-edit' | 'viewport-play' | 'inspector' | 'console' | 'build';
@@ -39,10 +42,15 @@ const EXTENSION_KIND: Record<string, AssetKind> = {
   '.webp': 'image',
   '.gif': 'image',
   '.svg': 'image',
+  '.hdr': 'image',
+  '.exr': 'image',
   '.mp3': 'audio',
   '.ogg': 'audio',
   '.wav': 'audio',
   '.flac': 'audio',
+  '.glsl': 'source',
+  '.vert': 'source',
+  '.frag': 'source',
 };
 
 /**
@@ -53,12 +61,9 @@ const EXTENSION_KIND: Record<string, AssetKind> = {
  * on. Callers with an unusual extension can always pass `kind` explicitly.
  */
 export function inferAssetKind(path: string): AssetKind {
-  // WO-8: `.vscn.json` mapped to 'scene' here. That format is deleted, and
-  // `.prefab.json` is likewise retired (PRs #578/#581/#589) but the `'prefab'`
-  // AssetKind itself still exists in `@vgai/editor-sdk`, so the mapping is left
-  // for that retirement's own follow-up rather than half-removed here.
+  // `.prefab.json` is retired (PRs #578/#581/#589) but the `'prefab'`
+  // AssetKind itself remains in `@vgai/editor-sdk` for view-link compatibility.
   if (path.endsWith('.prefab.json')) return 'prefab';
-  if (path.endsWith('.mat.json')) return 'material';
   const dot = path.lastIndexOf('.');
   const ext = dot >= 0 ? path.slice(dot).toLowerCase() : '';
   return EXTENSION_KIND[ext] ?? 'json';
@@ -71,8 +76,19 @@ export class LiveEditor {
    *  `client.ts` (GameClient's field block) for the full reasoning. */
   readonly #client: EditorClient;
 
+  /**
+   * The ACTIVE center document's own DOM: read it, click it, key it, paste
+   * into it. The one door onto editor chrome that is not play-mode gated, and
+   * deliberately scoped to that document alone —
+   * `packages/editor/src/editor-document-probe.ts` carries the design and the
+   * refusal contract. Screenshotting the same subject is
+   * {@link LiveEditor.captureActiveDocument}, not a fifth verb here.
+   */
+  readonly document: LiveEditorDocument;
+
   constructor(client: EditorClient) {
     this.#client = client;
+    this.document = new LiveEditorDocument(client);
   }
 
   /**
@@ -254,6 +270,24 @@ export class LiveEditor {
     await this.#client.setShadingMode(mode);
   }
 
+  /**
+   * CONSENT to edits being written into the game's own source files, for this
+   * session — the Game document's "Persist to game source" checkbox, reachable
+   * from a script.
+   *
+   * Off by default every session, on purpose: it is a statement about what you
+   * are doing right now, never a property of the game. With it off, an edit
+   * lives on the running object and says so; with it on, an edit that can be
+   * honestly anchored to the line that CREATED the object is written there,
+   * and one that cannot still says so. Answers with the server's own phrase for
+   * who records the resulting diff — your version control, or a vendored
+   * game's own lock — and refuses, with the reason, where the checkbox is
+   * disabled.
+   */
+  async persistToGameSource(on: boolean): Promise<{ enabled: boolean; recorder: string | null }> {
+    return this.#client.setSourcePersistConsent(on);
+  }
+
   /**
    * READ the inspector, as data — the serialized inspection subject
    * (`editor.inspect()`; design: `docs/ARCHITECTURE-CORE.md` §Editor chrome,
@@ -285,6 +319,55 @@ export class LiveEditor {
     return this.#client.inspect();
   }
 
+  /**
+   * READ the hierarchy panel, as data — the rows a human is looking at right
+   * now, nested exactly as the panel nests them.
+   *
+   * The companion to {@link inspect}: that one answers "what IS the selected
+   * thing", this one answers "what does the tree LOOK LIKE". It is the panel's
+   * own output, not a fresh walk of the scene — the adapter's tree after the
+   * component marks fold implementation subtrees (bones, particle renderers,
+   * instanced pools), after the internals reveal, the document promotion, the
+   * child cap, the collapse state, the search filter and the selection scope.
+   *
+   * Works in play mode and edit mode; the answer says which (`playState`,
+   * `activeViewportTab`), because the two are different adapters and a tree
+   * that looks wrong is very often the wrong adapter's tree.
+   *
+   * Prefer this over `status().entities`, which is deliberately a different
+   * question — the RAW adapter tree, unprojected. A panel that renders the
+   * wrong rows looks perfectly healthy in that facet.
+   *
+   * Each row carries `childCount` (what its caret opens), `internalChildCount`
+   * (what is folded behind "Reveal Internals") and `expandable` (whether the
+   * panel draws a caret at all), so "this subtree exists but nothing in the UI
+   * opens it" is a fact you can read rather than one you have to notice.
+   *
+   * Rejects, naming the panel, when no hierarchy panel is mounted — an empty
+   * tree would be a fabricated answer about a surface nobody is being shown.
+   */
+  async hierarchy(): Promise<InspectedHierarchy> {
+    return this.#client.hierarchy();
+  }
+
+  /**
+   * Write one editable field from `inspect()` by its stable path, through the
+   * same Inspector IO and persistence boundary the human control uses.
+   */
+  async setField(path: string, value: unknown): Promise<InspectedInspection> {
+    return this.#client.setInspectionField(path, value);
+  }
+
+  /** Undo / redo one project transaction, through the session's own history
+   *  queue — the same one the keyboard shortcut drives. */
+  async undo(): Promise<HistoryStep> {
+    return this.#client.undo();
+  }
+
+  async redo(): Promise<HistoryStep> {
+    return this.#client.redo();
+  }
+
   /** Mirrors `vgai status` — the full live editor state as JSON. */
   async status(): Promise<EditorState> {
     return this.#client.getState();

package/src/index.ts

@@ -27,6 +27,13 @@
  *   await editor.grid(true);
  *   await game.input.tap('jump');
  *
+ * `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
+ * 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`).
+ *
  * `page(step)` = `GameClient.page(step)` (Wave-2's playwright-shim surface,
  * PR #166) — write `step` as a literal `async (page) => {...}` and inline
  * every value it needs. KNOWN WIRE LIMITATION: under the relay transport this
@@ -56,6 +63,12 @@ export type {
 } from '@vgai/editor-sdk';
 export type { PanelName } from './editor.js';
 export { inferAssetKind, LiveEditor } from './editor.js';
+export type {
+  DocumentGestureOptions,
+  DocumentKeyOptions,
+  DocumentPasteOptions,
+} from './editor-document.js';
+export { LiveEditorDocument } from './editor-document.js';
 export { createGameClient, createLiveGame, type LiveGame } from './game.js';
 export * from './game-client/index.js';
 export type {