@volter/live 0.0.0-stage → 0.5.204

package/README.md

@@ -1,4 +1,20 @@
-# Temporary Holding Version
+# Live client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
-If no other versions are published within 30 days, this package and version will be deleted.
+Attach to an existing editor session and drive its documents, Blender commands,
+inspection, history and registered project tools. This package never starts a
+session or runs Blender outside the editor tab.
+
+```js
+import { connect } from '@volter/live';
+const { editor } = await connect('/path/to/project');
+await editor.blender('blender-status');
+```
+
+Connection selection matches the project's canonical path and refuses a missing
+or mismatched session. Gameplay control, recording and game-page automation are
+not part of this modeling release. Runtime JavaScript is bundled for plain Node;
+source and declarations ship alongside it.
+
+Private migration staging: the new product's launcher is not available yet.
+Existing session storage and wire identifiers remain until their producers move
+with them. See the repository WORK.md for the remaining release gates.

package/dist/editor-document.d.ts

@@ -0,0 +1,170 @@
+/**
+ * `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.
+ */
+import type { DocumentProbeResult, DocumentProbeScope, EditorClient } from '@volter/sdk';
+/** Which named surface a verb runs against; `document` when omitted. */
+export interface DocumentScopeOption {
+    scope?: DocumentProbeScope;
+}
+/** Modifier/targeting options shared by the gesture verbs. */
+export interface DocumentGestureOptions extends DocumentScopeOption {
+    /** 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 scope has focus. */
+    selector?: string;
+    code?: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    shiftKey?: boolean;
+    altKey?: boolean;
+    /** Hold the key this long before releasing it (a person holding W).
+     * Finite, nonnegative, and at most 120,000 ms. */
+    holdMs?: number;
+}
+export interface DocumentPasteOptions extends DocumentGestureOptions {
+    selector?: string;
+}
+export interface DocumentTypeOptions extends DocumentGestureOptions {
+    /** The field; omitted types into whatever inside the scope has focus. */
+    selector?: string;
+    /** Replace what the field holds first (default true). */
+    replace?: boolean;
+    /** Press Enter after the text (default true). */
+    enter?: boolean;
+}
+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`.
+     *
+     * `styles` additionally resolves named properties per match — and resolving
+     * is the point, because a theme token is an expression until an element
+     * paints it. Ask for the standard property to learn the colour a person
+     * sees; ask for a `--volter-…` custom property to learn what a rule WOULD
+     * paint, which is the only way to measure a `:hover` colour (`:hover` is a
+     * browser state no synthetic event can enter, so there is deliberately no
+     * hover verb on this door).
+     *
+     *   await editor.document.query('.volter-tree-row', {
+     *     styles: ['backgroundColor', '--volter-widget-regular-hover'],
+     *   });
+     */
+    query(selector: string, options?: DocumentScopeOption & {
+        limit?: number;
+        styles?: readonly string[];
+    }): 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 & {
+        clicks?: number;
+        at?: [number, number];
+        altKey?: boolean;
+        ctrlKey?: boolean;
+        metaKey?: boolean;
+        shiftKey?: boolean;
+    }): Promise<DocumentProbeResult>;
+    /**
+     * TYPE into a field and commit with Enter, the way a person does — one
+     * character at a time through the prototype's value setter, between real
+     * `keydown`/`keyup`.
+     *
+     * `paste` is not a substitute: an untrusted `ClipboardEvent` performs no
+     * default action, so a plain `<input>` with no paste handler keeps its old
+     * value. Omit `selector` to type into whatever inside the scope has focus —
+     * which is what a rename field is, one gesture after
+     * `click(row, { clicks: 2 })`.
+     */
+    type(text: string, options?: DocumentTypeOptions): Promise<DocumentProbeResult>;
+    /**
+     * 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.
+     *
+     * `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
+     * page coordinates. `[0.5, 0.5]` is its center, `[1, 0]` its top-right.
+     * Compute a pixel target by measuring the element first: `query` answers
+     * its `rect`, and `(px - rect.x) / rect.width` is the fraction to pass.
+     */
+    drag(selector: string, options: DocumentGestureOptions & {
+        from: [number, number];
+        to: [number, number];
+        via?: [number, number][];
+        steps?: number;
+        altKey?: boolean;
+        ctrlKey?: boolean;
+        metaKey?: boolean;
+        shiftKey?: boolean;
+        /** 0 primary (default), 1 middle, 2 secondary. */
+        button?: 0 | 1 | 2;
+        /** `via`/`to` may leave the element's box after the press (a handle drag). */
+        leave?: boolean;
+        /** Keep the button down at `to`, for readings taken mid-gesture; {@link release} lets go. */
+        hold?: boolean;
+    }): Promise<DocumentProbeResult>;
+    /** Lets go of the drag `hold: true` left pressed, where it was left. */
+    release(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>;
+    /**
+     * 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.d.ts

@@ -0,0 +1,441 @@
+/** Editor and document automation over the shared session command wire.
+ * Modeling executes in the editor tab; this client owns no model state. */
+import type { ActiveDocumentCapture, AssetKind, AssetPreviewCapture, AssetPreviewOptions, AssetPreviewShotSetDefinition, AssetPreviewSource, CaptureDimensions, DocumentLookOutcome, StageFrameCostReading, EditorChromeCapture, EditorChromeCaptureOptions, EditorClient, EditorState, EditorView, EditorWorkspaceName, HistoryStep, InspectedFieldWrite, InspectedHierarchy, InspectedInspection, LabeledShotSetCapture, ModelPlayLogReading, OpenedDocument, PresentedEditorView, ShadingMode, StructureOp, StructureOpOptions, StructureOpResult, ViewPreset, ViewportCapture } from '@volter/sdk';
+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. */
+export type PanelName = 'viewport-edit' | 'console' | (string & {});
+/**
+ * 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.
+ */
+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/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.
+     */
+    readonly document: LiveEditorDocument;
+    constructor(client: EditorClient);
+    /**
+     * 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.
+     */
+    blender<T extends object = Record<string, unknown>>(type: `blender-${string}`, fields?: Record<string, unknown>): Promise<T>;
+    /**
+     * 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"
+     */
+    modelPlayLog(query?: {
+        readonly documentId?: string;
+        readonly since?: number;
+        readonly kind?: string;
+    }): Promise<ModelPlayLogReading>;
+    /**
+     * The active authoring adapter's persistence destination — where a save would
+     * land (`status().savePath`). A read only: a three root has no scene document
+     * to open, and its root is activated instead.
+     */
+    scene(): Promise<string | null>;
+    /**
+     * Make the connected human editor show the same subject/view as the agent.
+     * The returned URL is a compact, shareable projection — not a serialized
+     * workspace or document payload.
+     */
+    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.
+     *
+     * 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' })`. */
+    captureActiveDocument(size?: CaptureDimensions, view?: EditorView): Promise<ActiveDocumentCapture>;
+    /**
+     * Photograph the editor PAGE — every panel, tab strip and viewport as the
+     * person sees it. the editor's `screenshot editor` command 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. The page at its own layout, `scale` output pixels per CSS pixel
+     * (default `devicePixelRatio`) — a 1 px border or a glyph stroke is only
+     * judgeable at the scale the reference it is compared against was captured
+     * at, and the result reports its own `size` and `scale`.
+     */
+    captureEditorChrome(options?: EditorChromeCaptureOptions): Promise<EditorChromeCapture>;
+    /** `'all'` -> `EditorClient.selectAll()` (mirrors `volter select --all`); otherwise `EditorClient.select(id)` (mirrors `volter select <entityId>`). */
+    select(id: string | 'all'): Promise<void>;
+    /** Mirrors `volter deselect`. */
+    deselect(): Promise<void>;
+    /** No `id` -> focus the current selection (mirrors bare `volter focus`); `id` given -> focus that entity. */
+    focus(id?: string): Promise<void>;
+    /**
+     * 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.
+     */
+    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: {
+        /** RADIANS, relative to where the camera is now. `Math.PI / 2` is a
+         *  quarter turn; degrees are not accepted and `90` is fourteen turns. */
+        readonly azimuth?: number;
+        /** RADIANS, relative to where the camera is now. */
+        readonly elevation?: number;
+        /** SECONDS the move takes (default 0.6). */
+        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>;
+    /**
+     * What a frame of the open 3D document's stage costs when nothing caps it: `frames` of the
+     * stage's own frame back to back, each waited out on the GPU (median, p95, min ms), the canvas
+     * with its device pixel ratio, what was drawn after culling against what the scene holds, and
+     * the draw mode. `stage` names another stage by its id (a split's second area,
+     * `<documentId>#area-2`).
+     */
+    frameCost(options?: {
+        readonly frames?: number;
+        readonly stage?: string;
+        readonly quality?: 'full' | 'navigation';
+    }): Promise<StageFrameCostReading>;
+    view(preset: ViewPreset): 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>;
+    /**
+     * Apply a STYLE BUNDLE by id — the chrome's palette, material and icon set in
+     * one gesture, the session door beside
+     * `View → <Style> Style`. A bundle the open project does not offer refuses
+     * and names the vocabulary; `currentView().style` reports the one worn.
+     */
+    style(id: string): Promise<void>;
+    /**
+     * A document stage's viewport PRESENTATION — its draw mode, lighting, backdrop and overlays
+     * (`@volter/sdk/kit/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.
+     */
+    presentation(documentId: string, layer?: Parameters<EditorClient['viewportPresentation']>[1]): ReturnType<EditorClient['viewportPresentation']>;
+    /**
+     * 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).
+     */
+    appearance(appearance: {
+        readonly material?: string;
+    }): Promise<{
+        material: string;
+        style: string | null;
+    }>;
+    /** Focus an editor panel: a viewport tab, the console, the build surface, or
+     *  any key the editor's static-panel registry holds — an unknown key refuses
+     *  naming the ones it does. */
+    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>;
+    /**
+     * Captures the editor's native four-view preview. A bare string is a
+     * project-relative asset path (the common case); an explicit source object
+     * targets a path, a LIVE SCENE ENTITY (`assetPreview({ entityId }, …)`) —
+     * which is what makes `options.stage: 'scene'`, the entity photographed
+     * 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.
+     */
+    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>;
+    shading(mode: ShadingMode): Promise<void>;
+    /**
+     * 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).
+     */
+    inspect(): Promise<InspectedInspection>;
+    /** Run one verb listed by `inspect().quickActions`, through the same action
+     * the human Inspector button invokes. */
+    runAction(actionId: string): Promise<InspectedInspection>;
+    /**
+     * 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:
+     *
+     *     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.
+     */
+    command(commandId: string, args?: unknown): Promise<unknown>;
+    /**
+     * 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.
+     *
+     * 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>;
+    /** Expand every branch through the Hierarchy panel's own action. */
+    expandHierarchyAll(): Promise<void>;
+    /** Collapse every branch through the same panel action. Expanding is
+     *  persisted per project, so without this the tree's REST STATE — what a
+     *  person sees on opening the project — is unreachable once any reader has
+     *  expanded it. */
+    collapseHierarchyAll(): Promise<void>;
+    /**
+     * Write one editable field from `inspect()` by its stable path, through the
+     * same Inspector IO and persistence boundary the human control uses.
+     *
+     * The answer is `{ subject, write }`, and `write` is the half worth reading
+     * first: a write with no persistence route open still succeeds — it lands on
+     * the live object and journals live-only — so `write.persisted` is how you
+     * tell a saved edit from one that will not survive the session, without
+     * diffing the tree. `write.destination` is the adapter's own words for where
+     * it went ("live-only (not saved)" is a destination, never silence).
+     */
+    setField(path: string, value: unknown): Promise<InspectedFieldWrite>;
+    /**
+     * REMOVE one field's authored override — the revert arrow, as a command.
+     *
+     * Reach for this instead of `setField` whenever you are UNDOING an edit that
+     * added a property the source did not carry: `setField` can only write a
+     * value, so setting the default back leaves `position={[0, 0, 0]}` in the
+     * file where there was nothing before. Only this door restores the bytes.
+     *
+     * The answer is the same `{ subject, write }` shape, awaited past the bytes.
+     * It rejects with `code: 'REMOVAL_UNAVAILABLE'` when the field is not
+     * declared removable or the lane has no removal door — which is a missing
+     * seam to report, not a removal that failed.
+     */
+    removeField(path: string): Promise<InspectedFieldWrite>;
+    /** Open a document by its adapter-declared id, through its registered owner. */
+    open(id: string): Promise<OpenedDocument>;
+    /** 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>;
+    /** Reload the editor's page and resolve once the new document answers. */
+    reloadPage(): Promise<void>;
+    /** Mirrors the editor's `status` command — 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. */
+    screenshot(size?: number): Promise<ViewportCapture>;
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { LiveEditor } from './editor.js';
+import { LiveTools } from './tools.js';
+import { type ResolvedSession, type SessionResolutionDeps } from './session.js';
+export { LiveEditor, inferAssetKind, type PanelName } from './editor.js';
+export { LiveEditorDocument } from './editor-document.js';
+export type { DocumentGestureOptions, DocumentKeyOptions, DocumentPasteOptions } from './editor-document.js';
+export { LiveTools } from './tools.js';
+export { editorMemberHint, withEditorMemberHints } from './member-hints.js';
+export { resolveSession, findProjectRootFrom } from './session.js';
+export type { ResolvedSession, SessionResolutionDeps, SessionListingTransport, ProjectSessionHint } from './session.js';
+export type { ActiveDocumentCapture, EditorView, PresentedEditorView } from '@volter/sdk';
+export interface LiveBindings {
+    editor: LiveEditor;
+    tools: LiveTools;
+}
+export interface LiveSession extends LiveBindings {
+    session: ResolvedSession;
+}
+/** Inspect the callable surface without connecting; calls fail on port zero. */
+export declare function unconnectedBindings(): LiveBindings;
+/** Attach only to the session serving the requested project's canonical path. */
+export declare function connect(projectDir?: string, deps?: SessionResolutionDeps): Promise<LiveSession>;
+export declare const editor: LiveEditor;
+export declare const tools: LiveTools;