@volter/live 0.5.211 → 0.5.213

package/dist/editor.d.ts

@@ -1,70 +1,35 @@
 /** 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 type { ActiveDocumentCapture, AssetKind, AssetPreviewCapture, AssetPreviewOptions, AssetPreviewShotSetDefinition, AssetPreviewSource, CaptureDimensions, DocumentLookOutcome, StageFrameCostReading, EditorChromeCapture, EditorChromeCaptureOptions, EditorState, EditorView, EditorWorkspaceName, InspectedFieldWrite, InspectedHierarchy, InspectedInspection, LabeledShotSetCapture, PresentedEditorView, ShadingMode, StructureOp, StructureOpOptions, StructureOpResult, 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. */
-export type PanelName = 'viewport-edit' | 'console' | (string & {});
+/** 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 = '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.
+ * `kind` argument. 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.
-     */
+    /** 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);
-    /**
-     * 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>;
+    /** A verb a composed package contributes (`<package>-<verb>`), waited on for its own row's budget. */
+    contributedVerb<T extends object = Record<string, unknown>>(type: string, fields?: Record<string, unknown>): Promise<T>;
     /**
      * 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.
      */
     scene(): Promise<string | null>;
@@ -76,19 +41,10 @@ export declare class LiveEditor {
     present(view: EditorView): Promise<PresentedEditorView>;
     /** The human editor's actual active document, selection, camera and utility. */
     currentView(): Promise<EditorView>;
-    /**
-     * Capture the same center document the human is currently looking at.
-     *
-     * 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. */
     captureActiveDocument(size?: CaptureDimensions, view?: EditorView): Promise<ActiveDocumentCapture>;
     /**
      * Photograph the editor PAGE — every panel, tab strip and viewport as the
@@ -117,7 +73,7 @@ export declare class LiveEditor {
      */
     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).
@@ -128,7 +84,7 @@ export declare 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
@@ -173,22 +129,10 @@ export declare class LiveEditor {
         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>;
+    workspace(id: EditorWorkspaceName): Promise<{
+        readonly workspace: EditorWorkspaceName;
+        readonly applied: boolean;
+    }>;
     /**
      * Apply a STYLE BUNDLE by id — the chrome's palette, material and icon set in
      * one gesture, the session door beside
@@ -198,28 +142,12 @@ export declare class LiveEditor {
     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
+     * (`@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.
      */
     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
+    /** 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. */
     showPanel(name: PanelName): Promise<void>;
@@ -228,12 +156,8 @@ export declare class LiveEditor {
     /**
      * 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.
      */
     selectAsset(path: string): Promise<void>;
     /**
@@ -244,8 +168,8 @@ export declare 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.
      */
     assetPreview(source: string | AssetPreviewSource, options?: AssetPreviewOptions): Promise<AssetPreviewCapture>;
     /**
@@ -254,72 +178,22 @@ export declare 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.
      */
     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 })
+     * 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-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.
      */
     command(commandId: string, args?: unknown): Promise<unknown>;
     /**
@@ -332,11 +206,6 @@ export declare 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
@@ -371,23 +240,14 @@ export declare 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.
@@ -426,7 +286,9 @@ export declare class LiveEditor {
      * 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 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. */
     open(id: string): Promise<OpenedDocument>;
     /** Undo / redo one project transaction, through the session's own history
      *  queue — the same one the keyboard shortcut drives. */

package/dist/http-transport.d.ts

@@ -0,0 +1,6 @@
+/** Node session clients need explicit header deadlines for long modeling calls.
+ * Some runtimes supply an undici-compatible Agent without destroy(); callers
+ * close explicitly when that lifecycle method exists. */
+import { type Dispatcher } from 'undici';
+export declare function createDispatcher(timeoutMs: number): Dispatcher;
+export declare function dispatchFetch(url: string, init?: RequestInit, dispatcher?: Dispatcher): Promise<Response>;

package/dist/index.d.ts

@@ -1,17 +1,15 @@
 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 { AssetDownloadRequest, AssetDownloadResult, AssetFileOption, AssetSearchQuery, OnlineAsset } from './asset-library.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, NO_SESSION_FOR_PROJECT } from './session.js';
-export type { ResolvedSession, SessionResolutionDeps, SessionListingTransport, ProjectSessionHint } from './session.js';
+export { resolveSession, findProjectRootFrom, NO_SESSION_FOR_PROJECT, SESSION_MANIFEST_UNREADABLE } from './session.js';
+export type { ResolvedSession, SessionResolutionDeps, SessionListingTransport } 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;
@@ -21,4 +19,3 @@ 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;