@volter/live 0.5.211 → 0.5.213

package/src/discovery.ts

@@ -0,0 +1,105 @@
+/** Registered-session discovery; never selects another project's session. */
+import { readLiveRegisteredSessions, servedProjectAnswer, sessionFetch } from './registry-format.js';
+export { servedProjectAnswer } from './registry-format.js';
+
+export const EDITOR_SESSION_DISCOVERY_TIMEOUT_MS = 2000;
+
+export const EDITOR_PROBE_TIMEOUT_MS = 1500;
+
+export class EditorTimeoutError extends Error {
+  constructor(label: string, ms: number) {
+    super(`${label} timed out after ${ms}ms`);
+    this.name = 'EditorTimeoutError';
+  }
+}
+
+export function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
+  return new Promise<T>((resolvePromise, reject) => {
+    const timer = setTimeout(() => reject(new EditorTimeoutError(label, ms)), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolvePromise(v);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      },
+    );
+  });
+}
+
+export interface EditorSessionInfo {
+  /** The port this session's dev server is bound to. */
+  port: number;
+  /** Canonical project root path currently open, or null when none. */
+  project: string | null;
+  /** Dev-server process id, when known from the local session registry (null for an unregistered server the caller only probed by port). */
+  pid: number | null;
+  /** Exact explicitly targeted editor origin/base URL, including protocol and host. */
+  url?: string;
+  /**
+   * Why this server cannot DESCRIBE the `project` it is serving — its
+   * manifest's own parse/validation failure, naming the failing key. `null`
+   * when the project reads fine, and `undefined` from a probe that did not ask
+   * See {@link servedProjectAnswer}: a session in
+   * this state is still THIS project's session, and callers must report the
+   * reason rather than treat it as no session at all.
+   */
+  manifestError?: string | null;
+}
+
+async function fetchJson(url: string, timeoutMs: number): Promise<unknown> {
+  const res = await sessionFetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+  if (!res.ok) throw new Error(`GET /__editor/project returned HTTP ${res.status}`);
+  return await res.json();
+}
+
+function baseUrl(session: EditorSessionInfo): string {
+  return session.url ?? `http://127.0.0.1:${session.port}`;
+}
+
+export interface SessionListingTransport { listSessions(timeoutMs: number): Promise<EditorSessionInfo[]>; }
+export class HttpSessionDiscovery implements SessionListingTransport {
+  async listSessions(timeoutMs: number): Promise<EditorSessionInfo[]> {
+    const registered = readLiveRegisteredSessions();
+    const perProbeTimeout = Math.min(EDITOR_PROBE_TIMEOUT_MS, Math.max(200, timeoutMs));
+    const failures: string[] = [];
+    const probes = await Promise.all(
+      registered.map(async (s) => {
+        try {
+          const body = await fetchJson(
+            `${baseUrl({ port: s.port, project: null, pid: s.pid })}/__editor/project`,
+            perProbeTimeout,
+          );
+          const served = servedProjectAnswer(body);
+          const info: EditorSessionInfo = {
+            port: s.port,
+            project: served.path,
+            pid: s.pid,
+            manifestError: served.manifestError,
+          };
+          return info;
+        } catch (error) {
+          // Name the step that did not answer, not a guess at why: an aborted fetch here means
+          // the server took the request to /__editor/project and sent nothing back in time.
+          const timedOut = (error as { name?: string } | null)?.name === 'TimeoutError';
+          const detail = timedOut
+            ? `GET /__editor/project sent no answer within ${perProbeTimeout} ms (pid ${s.pid})`
+            : error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+          failures.push(`port ${s.port}: ${detail}`);
+          return undefined;
+        }
+      }),
+    );
+    const sessions = probes.filter((p): p is EditorSessionInfo => p !== undefined);
+    // A readable registry with registered live processes is not an empty
+    // registry just because every HTTP discovery request failed. Keep any
+    // verified sessions usable, but refuse an entirely unanswered inventory
+    // rather than telling the caller to launch a second editor.
+    if (registered.length > 0 && sessions.length === 0) {
+      throw new Error(`Registered editor sessions could not be inspected: ${failures.join('; ')}`);
+    }
+    return sessions;
+  }
+}

package/src/editor-document.ts

@@ -1,46 +1,15 @@
-/**
- * `editor.document` — the session binding for the scoped editor-chrome door.
- *
- * WHY IT IS A SEPARATE OBJECT, and why the verbs are these, is recorded once
- * in the implementation's header
- * (`packages/sdk/src/kit/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.
- *
- * WHAT IT ADDRESSES is a closed VOCABULARY of named surfaces, passed as
- * `{ scope }` on every verb:
- *
- *   `document` (default) the active centre document's whole box
- *   `header` / `shelf`   that document's toolbar strip / tool rail
- *   `rail`               the PROPERTIES view — its tabs, sections and fields
- *   `outliner`           the OUTLINER view — its rows and their controls
- *   `content`            the CONTENT view — its categories and asset rows
- *   `menubar`            the APPLICATION MENUS (Edit, View, …) and the menus they open
- *
- *   await editor.document.click('[data-testid=app-menu-edit]', { scope: 'menubar' });
- *   await editor.document.query('[role=tab]', { scope: 'rail' });
- *   await editor.document.click('[data-testid=properties-tab-modifiers]', { scope: 'rail' });
- *   await editor.document.click('[data-ingest-name=Cube]', { scope: 'outliner', clicks: 2 });
- *   await editor.document.type('Wheel', { scope: 'outliner' });
- *
- * It is not page automation: a selector resolving outside the named surface is
- * refused by a message naming the scope and listing the others. `rail` and
- * `outliner`, and `content` are editor chrome and stay readable while the Game document is
- * active; `editor.hierarchy()` / `editor.inspect()` keep answering what those
- * panels RESOLVED, where this door answers what they DREW.
- *
- * A field on `LiveEditor` rather than methods on it, so the editor's `eval --list` command
- * shows the verbs as one named surface — the same reason `game.input`
- * and `game.events` are instance fields.
- */
+/** Session binding for reading and driving the editor's named surfaces.
+ * Each verb accepts a document-probe scope: document, header, shelf, rail,
+ * outliner, utility or area. Targets outside that scope are refused. Chrome
+ * scopes remain available without an open document. The eval member listing
+ * groups these verbs under editor.document. */
 
 import type {
   DocumentProbeResult,
   DocumentProbeScope,
   DocumentProbeStep,
-  EditorClient,
 } from '@volter/sdk';
+import type { EditorClient } from './client.js';
 
 /** Which named surface a verb runs against; `document` when omitted. */
 export interface DocumentScopeOption {
@@ -128,8 +97,7 @@ export class LiveEditorDocument {
       shiftKey?: boolean;
     },
   ): Promise<DocumentProbeResult> {
-    // An option this door does not know is refused, never dropped: a dropped `position` clicked
-    // the element's centre and answered as if it had clicked where it was asked.
+    // Refuse unknown options before dispatching the gesture.
     const known = ['scope', 'index', 'clicks', 'at', 'altKey', 'ctrlKey', 'metaKey', 'shiftKey'];
     const unknown = Object.keys(options ?? {}).filter((key) => !known.includes(key));
     if (unknown.length > 0) throw new Error(`click has no option ${unknown.map((key) => `\`${key}\``).join(', ')}; its options are scope, index, clicks, at ([x, y] fractions of the element's box) and the modifier keys altKey, ctrlKey, metaKey and shiftKey.`);
@@ -164,9 +132,7 @@ export class LiveEditorDocument {
 
   /**
    * A real pointer DRAG across one matched element — press at `from`, move,
-   * release at `to`. The gesture a direct-manipulation canvas needs; a
-   * zero-length drag is a click at that fraction, which `click` (always the
-   * center) cannot place.
+   * release at `to`. A zero-length drag presses and releases at one fraction.
    *
    * `from`, `to` and every point in `via` are `[x, y]` FRACTIONS OF THE
    * MATCHED ELEMENT'S BOX, 0..1 from its top-left — NEVER pixels and never
@@ -250,13 +216,10 @@ export class LiveEditorDocument {
   }
 
   /**
-   * 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 `step` in the editor page against the active document's published
+   * context, with its document id in `info`. The document owns the context's
+   * API. The step's source is serialized, so inline every value it needs and
+   * return plain data.
    */
   async run<T = unknown>(
     step: (ctx: unknown, info: { documentId: string }) => T | Promise<T>,

package/src/editor.ts

@@ -13,17 +13,13 @@ import type {
   StageFrameCostReading,
   EditorChromeCapture,
   EditorChromeCaptureOptions,
-  EditorClient,
   EditorState,
   EditorView,
   EditorWorkspaceName,
-  HistoryStep,
   InspectedFieldWrite,
   InspectedHierarchy,
   InspectedInspection,
   LabeledShotSetCapture,
-  ModelPlayLogReading,
-  OpenedDocument,
   PresentedEditorView,
   ShadingMode,
   StructureOp,
@@ -32,14 +28,15 @@ import type {
   ViewPreset,
   ViewportCapture,
 } from '@volter/sdk';
+import type { EditorClient, HistoryStep, OpenedDocument } from './client.js';
+import { LiveAssetLibrary } from './asset-library.js';
 import { LiveEditorDocument } from './editor-document.js';
 
-/** A panel `showPanel` can focus: the viewport tabs, the console, the build
- *  surface, or any key the editor's own static-panel registry holds
- *  (`hierarchy`, `assets`, `asset-library`, `inspector`, `history`, …) — which
- *  is why this is open: the registry, not this union, is the vocabulary. */
+/** A panel `showPanel` can focus: the console, the build surface, or any key
+ *  the editor's own static-panel registry holds (`hierarchy`, `asset-library`,
+ *  `inspector`, `history`, …) — which is why this is open: the registry, not
+ *  this union, is the vocabulary. */
 export type PanelName =
-  | 'viewport-edit'
   | 'console'
   // Keeps the literals above in autocomplete while admitting every key the
   // editor's registry holds — the registry answers, this union only hints.
@@ -65,15 +62,8 @@ 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?)$/`.
+  // Source kinds select SourceAssetViewer, which routes project scripts by content to
+  // LiveModuleDocument. Keep these extensions aligned with its isProjectScriptPath predicate.
   '.ts': 'source',
   '.tsx': 'source',
   '.mts': 'source',
@@ -86,14 +76,11 @@ const EXTENSION_KIND: Record<string, AssetKind> = {
 
 /**
  * Lightweight extension-based `AssetKind` guess for `openAsset`'s optional
- * `kind` argument. Deliberately independent of (not shared with) the
- * editor's own `AssetBrowser.tsx#getAssetKind` — that function is a private,
- * React-component-local helper of a package `@volter/live` has no dependency
- * on. Callers with an unusual extension can always pass `kind` explicitly.
+ * `kind` argument. Callers with an unusual extension can always pass `kind`
+ * explicitly.
  */
 export function inferAssetKind(path: string): AssetKind {
-  // `.prefab.json` is retired (PRs #578/#581/#589) but the `'prefab'`
-  // AssetKind itself remains in `@volter/sdk` for view-link compatibility.
+  // `'prefab'` is an `@volter/sdk` AssetKind that view links name.
   if (path.endsWith('.prefab.json')) return 'prefab';
   const dot = path.lastIndexOf('.');
   const ext = dot >= 0 ? path.slice(dot).toLowerCase() : '';
@@ -101,69 +88,37 @@ export function inferAssetKind(path: string): AssetKind {
 }
 
 export class LiveEditor {
-  /** `#`-private, not `private`: `cyclotron eval --list` enumerates this object's
+  /** `#`-private, not `private`: `<command> eval --list` enumerates this object's
    *  real runtime members, and TypeScript's erased `private` would leave the
    *  raw `EditorClient` advertised beside them. */
   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/sdk/src/kit/editor-document-probe.ts` carries the design and the
-   * refusal contract. Screenshotting the same subject is
-   * {@link LiveEditor.captureActiveDocument}, not a fifth verb here.
-   */
+  /** Read and drive DOM within a named scope: the active document by default, or editor chrome
+   * such as header, shelf, rail, outliner, utility and area. Targets outside the scope are refused.
+   * See `@volter/sdk`'s editor-document-probe for scope and gesture contracts. */
   readonly document: LiveEditorDocument;
 
+  /** The asset library: search a source, list an asset's files, download one into the project with its license
+   *  recorded (`asset-library.ts`). */
+  readonly assetLibrary: LiveAssetLibrary;
+
   constructor(client: EditorClient) {
     this.#client = client;
     this.document = new LiveEditorDocument(client);
+    this.assetLibrary = new LiveAssetLibrary(client);
   }
 
-  /**
-   * THE BLENDER LANE'S VERBS, from `cyclotron eval`.
-   *
-   * Blender runs headless in the editor tab's worker (ARCHITECTURE-CORE, "THE
-   * BLENDER IN THE TAB IS BLENDER") and answers `blender-start`,
-   * `blender-execute`, `blender-scene-info`, `blender-object-info`,
-   * `blender-screenshot-view`, `blender-read-file`, `blender-write-file`,
-   * `blender-list-files`, `blender-stop` and `blender-status`. They were
-   * reachable from `@volter/sdk` and through `volter blender-mcp` but from
-   * no GENERAL door, so driving a session meant writing an MCP client script
-   * per question — the same discovery failure `eval-surface.ts`'s header
-   * records, in a lane that had not noticed it yet.
-   *
-   *   cyclotron eval "await editor.blender('blender-execute', { code: 'import bpy; print(len(bpy.data.objects))' })"
-   *
-   * `blender-status` is the only verb that creates nothing: it answers whether
-   * this tab already has a session without starting one.
-   */
-  async blender<T extends object = Record<string, unknown>>(
-    type: `blender-${string}`,
+  /** A verb a composed package contributes (`<package>-<verb>`), waited on for its own row's budget. */
+  async contributedVerb<T extends object = Record<string, unknown>>(
+    type: string,
     fields: Record<string, unknown> = {},
   ): Promise<T> {
-    return this.#client.blender<T>(type, fields);
-  }
-
-  /**
-   * MODEL PLAY'S LOG, from `cyclotron eval` — the same read as
-   * `cyclotron play-log`. A play script writes it with
-   * `play.log(kind, facts)`; the runner adds `play-start`, `script-reload`,
-   * `script-error` and `play-stop`. Every entry carries `simT` (simulation
-   * seconds) and `tick` (the frame). Each model document keeps its own: the
-   * current run, or the last one after Stop; Play from a fresh copy empties it.
-   * `documentId` picks one (`documents` lists them); the active Play's by default.
-   *
-   *   cyclotron eval "(await editor.modelPlayLog({ kind: 'death' })).entries"
-   */
-  async modelPlayLog(query?: { readonly documentId?: string; readonly since?: number; readonly kind?: string }): Promise<ModelPlayLogReading> {
-    return this.#client.modelPlayLog(query);
+    return this.#client.contributedVerb<T>(type, fields);
   }
 
   /**
    * The active authoring adapter's persistence destination — where a save would
-   * land (`status().savePath`). A read only: a three root has no scene document
+   * land (`status().savePath`). A read only: a stage root has no scene document
    * to open, and its root is activated instead.
    */
   async scene(): Promise<string | null> {
@@ -185,19 +140,10 @@ export class LiveEditor {
     return this.#client.currentView();
   }
 
-  /**
-   * 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
-   * `@volter/sdk`'s `CaptureDimensions`.
-   * Supply a view to present and photograph it in one editor request.
-   */
-  /** The active document's RENDER alone, at the size asked for: what the document draws,
-   *  without what the viewport draws over it (its navigation gizmo, its readouts). To see a
-   *  stage as the person does, use `captureEditorChrome({ region: 'document' })`. */
+  /** Capture the active document's render without viewport navigation gizmos or readouts.
+   * A number requests a square; `{width, height}` requests a shaped frame, bounded by
+   * `CaptureDimensions`. Supply a view to present and capture it in one request.
+   * Use `captureEditorChrome({ region: 'document' })` to include viewport chrome. */
   async captureActiveDocument(
     size?: CaptureDimensions,
     view?: EditorView,
@@ -252,7 +198,7 @@ export class LiveEditor {
    */
   async frame(entityId: string): Promise<void>;
   /**
-   * Bare `frame()` frames the OPEN Object3D document's subject instead — its
+   * Bare `frame()` frames the OPEN asset 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).
@@ -269,7 +215,7 @@ export class LiveEditor {
   /**
    * WATCH THE AGENT LOOK AROUND THE MODEL.
    *
-   * Swings the open Object3D document's camera — the camera the human's tab is
+   * Swings the open asset 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
@@ -292,12 +238,7 @@ export class LiveEditor {
     /** SECONDS the move takes (default 0.6). */
     readonly duration?: number;
   }): Promise<DocumentLookOutcome> {
-    // AN UNKNOWN KEY IS REFUSED BY NAME. Every member here is optional, so a
-    // misspelling — `yaw` for `azimuth`, `pitch` for `elevation` — used to
-    // orbit by nothing at all while the outcome still reported a plausible
-    // ABSOLUTE azimuth, which reads exactly like a move that happened
-    // (measured 2026-09-21, and it cost a round). The keys and their unit are
-    // in the refusal because that is the moment the caller needs them.
+    // Refuse unknown keys by name and include the supported keys and units.
     const known = ['azimuth', 'elevation', 'duration'];
     const unknown = Object.keys(options ?? {}).filter((key) => !known.includes(key));
     if (unknown.length > 0)
@@ -336,23 +277,9 @@ export class LiveEditor {
     await this.#client.viewPreset(preset);
   }
 
-  /**
-   * 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);
+
+  async workspace(id: EditorWorkspaceName): Promise<{ readonly workspace: EditorWorkspaceName; readonly applied: boolean }> {
+    return this.#client.setWorkspace(id);
   }
 
   /**
@@ -367,11 +294,9 @@ export class LiveEditor {
 
   /**
    * A document stage's viewport PRESENTATION — its draw mode, lighting, backdrop and overlays
-   * (`@volter/sdk/kit/viewport-presentation`) — resolved. With `layer`, that choice is
+   * (`@volter/sdk/viewport-presentation`) — resolved. With `layer`, that choice is
    * recorded for the view first, as a person's toolbar change would be, e.g.
    * `presentation('model:src/models/cube.blend', { all: { lighting: { studioPreset: 'kit' } } })`.
-   * With a STRING, the named view of that id (`*.view.ts`, e.g. `'godot'`) is put on the view
-   * whole; the answer's `viewPresets` lists the ones registered.
    */
   async presentation(
     documentId: string,
@@ -380,28 +305,11 @@ export class LiveEditor {
     return this.#client.viewportPresentation(documentId, layer);
   }
 
-  /**
-   * Set the MATERIAL apart from the bundle that usually carries it.
-   * Appearance is palette × material, independent axes by ruling, so
-   * `style()` alone can never say whether a cost belongs to the blur or to
-   * the palette. This is the door that measures them apart; it answers with
-   * what the chrome wears afterwards (`style` is `null` when the mix matches
-   * no registered bundle).
-   */
-  async appearance(appearance: {
-    readonly material?: string;
-  }): Promise<{ material: string; style: string | null }> {
-    return this.#client.setAppearance(appearance);
-  }
-
-  /** Focus an editor panel: a viewport tab, the console, the build surface, or
+  /** Focus an editor panel: the console, the build surface, or
    *  any key the editor's static-panel registry holds — an unknown key refuses
    *  naming the ones it does. */
   async showPanel(name: PanelName): Promise<void> {
     switch (name) {
-      case 'viewport-edit':
-        await this.#client.showViewport('edit');
-        return;
       case 'console':
         await this.#client.toggleConsole();
         return;
@@ -415,24 +323,18 @@ export class LiveEditor {
 
   /** `kind` inferred from `path`'s extension when omitted (`inferAssetKind`) — pass it explicitly to override. */
   async openAsset(path: string, kind?: AssetKind): Promise<void> {
-    // A `.blend` is not an asset but a Model document the project's finder lists; opened as an
-    // asset it fell to the extension guess's `json` and showed its bytes.
-    if (path.toLowerCase().endsWith('.blend'))
-      throw new Error(
-        `${path} is a Blender Model document, not an asset: open it with editor.open("model:${path}").`,
-      );
+    // Finder-listed documents use their document opener rather than asset-kind inference.
+    const document = (await this.#client.documentTable()).entries.find((entry) => entry.source?.path === path);
+    if (document)
+      throw new Error(`${path} is a ${document.kind} document, not an asset: open it with editor.open("${document.id}").`);
     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.
+   * 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);
@@ -446,8 +348,8 @@ export class LiveEditor {
    * where it stands under the scene's own lighting, reachable from here — or
    * RAW GLB BYTES (`assetPreview({ glbBase64 }, …)`), for a model that exists
    * only in the calling Node process's memory and has never been written to
-   * disk. `stage` defaults to `'lab'`, the neutral Asset Lab staging this has
-   * always produced, and the bytes form is lab-only.
+   * disk. `stage` defaults to `'lab'`, the neutral Asset Lab staging, and the
+   * bytes form is lab-only.
    */
   async assetPreview(
     source: string | AssetPreviewSource,
@@ -465,8 +367,6 @@ export class LiveEditor {
    * 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,
@@ -496,33 +396,7 @@ export class LiveEditor {
     await this.#client.setShadingMode(mode);
   }
 
-  /**
-   * READ the inspector, as data — the serialized inspection subject
-   * (`editor.inspect()`; design: `docs/ARCHITECTURE-CORE.md` §Editor chrome,
-   * "The Inspection Model"). This is the Figma-Inspect analog: whatever a
-   * human would see in the inspector right now — the subject's identity, its
-   * verbs, and every identified section in display order, with a `fields`
-   * section's CURRENT VALUES at their scriptable `path`s.
-   *
-   * Reach for it whenever the next step depends on what an object actually
-   * IS: `await editor.select(id)` then `await editor.inspect()` answers "what
-   * properties does this thing have, and what are they set to" in one call,
-   * against the same model the panel renders — no scene-graph reads, no
-   * guessing at property names.
-   *
-   * When the inspector is showing NOTHING — nothing selected on a surface
-   * with no empty-state subject of its own, which is most of them — the answer
-   * is `{none: true}`, so "the human sees no inspector" and "the read failed"
-   * are never the same value. A surface whose empty space IS a real thing (an
-   * open Asset Lab document) still answers with that subject, and never with
-   * another surface's.
-   *
-   * A `custom` section body is a named opaque: the editor renders it with
-   * React, so the wire reports its identity rather than pretending to describe
-   * its rendering — plus, when the section can say what it DISPLAYS, a `data`
-   * payload in its own vocabulary (`transform` carries
-   * `{position, rotation, scale}`, rotation in Euler XYZ degrees).
-   */
+
   async inspect(): Promise<InspectedInspection> {
     return this.#client.inspect();
   }
@@ -534,32 +408,11 @@ export class LiveEditor {
   }
 
   /**
-   * Run ONE command by id — the door to everything the command palette lists.
-   *
-   * ONE NAME (orchestrator ruling 2026-09-19). There were briefly TWO doors
-   * onto the one view-verb table — this one and `editor.viewVerb(view, verb)`,
-   * which addressed the same registry by its two halves. A second addressing
-   * of one table is a second name for one thing, and an agent reading
-   * `--list` had to choose between them with nothing to choose on. This door
-   * stays because it is strictly wider: it addresses a COMMAND ID, so under
-   * the frame it reaches everything the workbench knows — a `volter.action.<id>`
-   * editor action, one of VS Code's own — and not only a view. A VIEW is
-   * reached by spelling its verb's command id:
+   * Run a command by id. Under the native frame this uses ICommandService and
+   * can invoke editor or VS Code commands. Standalone sessions resolve registered
+   * view verbs of the form `volter.<view>.<verb>` and refuse other ids.
    *
-   *     await editor.command('volter.blender-uv-view.state')
-   *     await editor.command('volter.blender-uv-view.zoom', { to: 600 })
-   *
-   *     await editor.command('volter.blender-node-view.view-all')
-   *     await editor.command('volter.blender-node-view.look', { node: 'Principled BSDF' })
-   *
-   * Under the Code-OSS frame this is the workbench's own command service, so
-   * any command id works — ours and VS Code's alike. Standalone the editor's `edit` command
-   * has no command service and answers the `volter.<view>.<verb>` shape off the
-   * SAME verb table the frame's commands call, refusing any other id by name.
-   * One table, two doors, exactly like the keymap's.
-   *
-   * Answers with whatever the command returned — a view verb's own state, or
-   * `null` for a command that returns nothing.
+   * Returns the command’s result, or `null` when it returns nothing.
    */
   async command(commandId: string, args?: unknown): Promise<unknown> {
     return this.#client.runCommand(commandId, args);
@@ -575,11 +428,6 @@ export class LiveEditor {
    * 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
@@ -618,23 +466,14 @@ export class LiveEditor {
    *
    * 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.
+   * own projection of component marks, document promotion, child caps,
+   * collapse state, search and selection scope onto the adapter 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.
+   * Each row reports the projected child count and whether the panel draws a disclosure control.
    *
    * 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.
@@ -688,7 +527,9 @@ export class LiveEditor {
     return this.#client.removeInspectionField(path);
   }
 
-  /** Open a document by its adapter-declared id, through its registered owner. */
+  /** Open a document by its adapter-declared id, through its registered owner. An id the adapter would list for a
+   *  file not written yet (a new model, `model:prefabs/coin/coin.blend`) opens as that new document, written by its
+   *  first save. */
   async open(id: string): Promise<OpenedDocument> {
     return this.#client.open(id);
   }