@volter/editor-live 0.5.65 → 0.5.67

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@volter/editor-live",
   "author": "Volter AI, Inc.",
-  "version": "0.5.65",
+  "version": "0.5.67",
   "publishConfig": {
     "access": "public"
   },
@@ -30,8 +30,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@volter/editor-sdk": "0.5.65",
-    "@volter/editor-project": "0.5.65",
+    "@volter/editor-sdk": "0.5.67",
+    "@volter/editor-project": "0.5.67",
     "undici": "^7.28.0"
   },
   "devDependencies": {

package/src/editor-document.ts

@@ -59,6 +59,8 @@ export interface DocumentKeyOptions extends DocumentGestureOptions {
   metaKey?: boolean;
   shiftKey?: boolean;
   altKey?: boolean;
+  /** Hold the key this long before releasing it (a person holding W). */
+  holdMs?: number;
 }
 
 export interface DocumentPasteOptions extends DocumentGestureOptions {
@@ -114,14 +116,19 @@ export class LiveEditorDocument {
    *  — not `element.click()`, which a `pointerdown` listener never sees. */
   async click(
     selector: string,
-    options?: DocumentGestureOptions & { clicks?: number },
+    options?: DocumentGestureOptions & { clicks?: number; at?: [number, number] },
   ): 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.
+    const unknown = Object.keys(options ?? {}).filter((key) => !['scope', 'index', 'clicks', 'at'].includes(key));
+    if (unknown.length > 0) throw new Error(`click has no option ${unknown.map((key) => `\`${key}\``).join(', ')}; its options are scope, index, clicks and at ([x, y] fractions of the element's box).`);
     return this.#probe({
       action: 'click',
       selector,
       ...(options?.scope === undefined ? {} : { scope: options.scope }),
       ...(options?.index === undefined ? {} : { index: options.index }),
       ...(options?.clicks === undefined ? {} : { clicks: options.clicks }),
+      ...(options?.at === undefined ? {} : { at: options.at }),
     });
   }
 
@@ -163,6 +170,10 @@ export class LiveEditorDocument {
       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;
     },
   ): Promise<DocumentProbeResult> {
     return this.#probe({
@@ -178,6 +189,8 @@ export class LiveEditorDocument {
       ...(options.ctrlKey === undefined ? {} : { ctrlKey: options.ctrlKey }),
       ...(options.metaKey === undefined ? {} : { metaKey: options.metaKey }),
       ...(options.shiftKey === undefined ? {} : { shiftKey: options.shiftKey }),
+      ...(options.button === undefined ? {} : { button: options.button }),
+      ...(options.leave === undefined ? {} : { leave: options.leave }),
     });
   }
 

package/src/editor.ts

@@ -99,7 +99,7 @@ export function inferAssetKind(path: string): AssetKind {
 }
 
 export class LiveEditor {
-  /** `#`-private, not `private`: `volter-editor eval --list` enumerates this object's
+  /** `#`-private, not `private`: `volter-model-editor 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;
@@ -120,7 +120,7 @@ export class LiveEditor {
   }
 
   /**
-   * THE BLENDER LANE'S VERBS, from `volter-editor eval`.
+   * THE BLENDER LANE'S VERBS, from `volter-model-editor eval`.
    *
    * Blender runs headless in the editor tab's worker (ARCHITECTURE-CORE, "THE
    * BLENDER IN THE TAB IS BLENDER") and answers `blender-start`,
@@ -132,7 +132,7 @@ export class LiveEditor {
    * per question — the same discovery failure `eval-surface.ts`'s header
    * records, in a lane that had not noticed it yet.
    *
-   *   volter-editor eval "await editor.blender('blender-execute', { code: 'import bpy; print(len(bpy.data.objects))' })"
+   *   volter-model-editor 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.
@@ -178,6 +178,9 @@ export class LiveEditor {
    * `@volter/editor-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' })`. */
   async captureActiveDocument(
     size?: CaptureDimensions,
     view?: EditorView,
@@ -325,8 +328,8 @@ export class LiveEditor {
   }
 
   /**
-   * Apply a STYLE BUNDLE by id — the chrome's palette, material, icon set and
-   * region defaults in one gesture, the session door beside
+   * 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.
    */
@@ -334,6 +337,21 @@ export class LiveEditor {
     await this.#client.setStyle(id);
   }
 
+  /**
+   * A document stage's viewport PRESENTATION — its draw mode, lighting, backdrop and overlays
+   * (`@volter/editor-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.
+   */
+  async presentation(
+    documentId: string,
+    layer?: Parameters<EditorClient['viewportPresentation']>[1],
+  ): ReturnType<EditorClient['viewportPresentation']> {
+    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
@@ -651,6 +669,11 @@ export class LiveEditor {
     return this.#client.redo();
   }
 
+  /** Reload the editor's page and resolve once the new document answers. */
+  async reloadPage(): Promise<void> {
+    await this.#client.reloadPage();
+  }
+
   /** Mirrors `vgai status` — the full live editor state as JSON. */
   async status(): Promise<EditorState> {
     return this.#client.getState();