@volter/editor-live 0.5.65 → 0.5.67

package/BUNDLED_NOTICES

@@ -3,9 +3,9 @@ Bundled license notices
 These notices accompany code incorporated into this package. Separate npm dependencies retain their own licenses.
 
 
-@volter/editor-project@0.5.65
+@volter/editor-project@0.5.67
 Declared license: Apache-2.0
-Source: the unmodified npm package @volter/editor-project@0.5.65, from https://github.com/volter-ai/editor.git
+Source: the unmodified npm package @volter/editor-project@0.5.67, from https://github.com/volter-ai/editor.git
 
 --- packages/editor-project/LICENSE ---
 
@@ -213,9 +213,9 @@ Source: the unmodified npm package @volter/editor-project@0.5.65, from https://g
    limitations under the License.
 
 
-@volter/editor-sdk@0.5.65
+@volter/editor-sdk@0.5.67
 Declared license: Apache-2.0
-Source: the unmodified npm package @volter/editor-sdk@0.5.65, from https://github.com/volter-ai/editor.git
+Source: the unmodified npm package @volter/editor-sdk@0.5.67, from https://github.com/volter-ai/editor.git
 
 --- packages/editor-sdk/LICENSE ---
 

package/dist/editor-document.d.ts

@@ -50,6 +50,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 {
     selector?: string;
@@ -89,6 +91,7 @@ export declare class LiveEditorDocument {
      *  — not `element.click()`, which a `pointerdown` listener never sees. */
     click(selector: string, options?: DocumentGestureOptions & {
         clicks?: number;
+        at?: [number, number];
     }): Promise<DocumentProbeResult>;
     /**
      * TYPE into a field and commit with Enter, the way a person does — one
@@ -123,6 +126,10 @@ export declare 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>;
     /** A real keydown/keyup on the target, or on whatever inside the document has focus. */
     key(key: string, options?: DocumentKeyOptions): Promise<DocumentProbeResult>;

package/dist/editor.d.ts

@@ -28,7 +28,7 @@ export declare class LiveEditor {
     readonly document: LiveEditorDocument;
     constructor(client: EditorClient);
     /**
-     * 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`,
@@ -40,7 +40,7 @@ export declare 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.
@@ -70,6 +70,9 @@ export declare 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' })`. */
     captureActiveDocument(size?: CaptureDimensions, view?: EditorView): Promise<ActiveDocumentCapture>;
     /**
      * Photograph the editor PAGE — every panel, tab strip and viewport as the
@@ -159,12 +162,21 @@ export declare class LiveEditor {
      */
     workspace(id: EditorWorkspaceName): Promise<void>;
     /**
-     * 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.
      */
     style(id: string): Promise<void>;
+    /**
+     * 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.
+     */
+    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
@@ -392,6 +404,8 @@ export declare class LiveEditor {
      *  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 `vgai status` — the full live editor state as JSON. */
     status(): Promise<EditorState>;
     /** A live viewport PNG (`EditorClient.captureViewport`) — no direct CLI verb exists; this is the closest wire read. */

package/dist/index.js

@@ -558,10 +558,21 @@ var EditorClient = class {
   }
   /** Apply a STYLE BUNDLE — palette, material, icon set and region defaults
    *  in one gesture (`classic`/`glass`/`maya`/`substance`, or one a package
-   *  the project declares carries, `blender`). */
+   *  the project or product composes carries, such as `blender`). */
   async setStyle(style) {
     await this.command({ type: "set-style", style });
   }
+  /** A document stage's viewport PRESENTATION (`kit/viewport-presentation`), resolved; with a
+   *  `layer`, that choice is recorded for the view first, as the toolbar records it. */
+  /** A view's presentation, answered resolved. With a LAYER the person's choice is recorded
+   *  first; with a STRING, the named view (`*.view.ts`) of that id is put on the view whole. */
+  async viewportPresentation(documentId, layer) {
+    return this.command({
+      type: "viewport-presentation",
+      documentId,
+      ...typeof layer === "string" ? { preset: layer } : layer ? { layer } : {}
+    });
+  }
   /** Set the MATERIAL apart from the bundle that usually carries it.
    *  Answers with what the chrome wears afterwards. */
   async setAppearance(appearance) {
@@ -772,7 +783,8 @@ var EditorClient = class {
   async captureEditorChrome(options) {
     return this.command({
       type: "capture-editor-chrome",
-      ...options?.scale === void 0 ? {} : { scale: options.scale }
+      ...options?.scale === void 0 ? {} : { scale: options.scale },
+      ...options?.region === void 0 ? {} : { region: options.region }
     });
   }
   /** With a view, present and capture it in one request so document discovery
@@ -960,6 +972,50 @@ var EditorClient = class {
   async documentTable() {
     return this.command({ type: "document-table" });
   }
+  /**
+   * Reload the editor's page and wait until the new document answers — the
+   * host's `page-reload`, for a product with no game client (`@volter/game-live`'s
+   * `page.reload()` is the same order with the same two witnesses). A tab's
+   * epoch count rising proves a new document loaded; a host command answering
+   * proves it can be driven. It is sent only once that tab reports its command
+   * listener ready, because a command sent before is filed as a stall.
+   */
+  async reloadPage(timeoutMs = 6e4) {
+    const epochs = async () => {
+      const tabs = (await this.getState().catch(() => ({ tabs: [] }))).tabs ?? [];
+      const byTab = tabs;
+      return new Map(byTab.map((tab) => [tab.tabId8, tab]));
+    };
+    const pause = () => new Promise((settle) => setTimeout(settle, 250));
+    const before = await epochs();
+    const deadline = Date.now() + timeoutMs;
+    await this.command({ type: "page-reload" });
+    let reloaded = [];
+    while (reloaded.length === 0) {
+      if (Date.now() > deadline) throw new Error("The reload was ordered and no tab of this session reported a new page load.");
+      await pause();
+      const now = await epochs();
+      reloaded = [...now].filter(([tabId, tab]) => tab.epochCount > (before.get(tabId)?.epochCount ?? 0)).map(([tabId]) => tabId);
+    }
+    for (; ; ) {
+      if (Date.now() > deadline) throw new Error("A new page loaded, but its command listener did not become ready.");
+      const now = await epochs();
+      if (reloaded.some((tabId) => {
+        const listener = now.get(tabId)?.commandListener;
+        return typeof listener !== "string" || listener === "ready";
+      })) break;
+      await pause();
+    }
+    for (; ; ) {
+      try {
+        await this.command({ type: "current-view" });
+        return;
+      } catch (error) {
+        if (Date.now() > deadline) throw error;
+        await pause();
+      }
+    }
+  }
   async getState() {
     const res = await this.httpFetch(`${this.baseUrl}/__editor/state`);
     const state = await this.readJson(res);
@@ -1114,12 +1170,15 @@ var LiveEditorDocument = class {
   /** A REAL pointer gesture (pointerdown/mousedown/focus/pointerup/mouseup/click)
    *  — not `element.click()`, which a `pointerdown` listener never sees. */
   async click(selector, options) {
+    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 === void 0 ? {} : { scope: options.scope },
       ...options?.index === void 0 ? {} : { index: options.index },
-      ...options?.clicks === void 0 ? {} : { clicks: options.clicks }
+      ...options?.clicks === void 0 ? {} : { clicks: options.clicks },
+      ...options?.at === void 0 ? {} : { at: options.at }
     });
   }
   /**
@@ -1161,7 +1220,9 @@ var LiveEditorDocument = class {
       ...options.altKey === void 0 ? {} : { altKey: options.altKey },
       ...options.ctrlKey === void 0 ? {} : { ctrlKey: options.ctrlKey },
       ...options.metaKey === void 0 ? {} : { metaKey: options.metaKey },
-      ...options.shiftKey === void 0 ? {} : { shiftKey: options.shiftKey }
+      ...options.shiftKey === void 0 ? {} : { shiftKey: options.shiftKey },
+      ...options.button === void 0 ? {} : { button: options.button },
+      ...options.leave === void 0 ? {} : { leave: options.leave }
     });
   }
   /** A real keydown/keyup on the target, or on whatever inside the document has focus. */
@@ -1252,7 +1313,7 @@ function inferAssetKind(path) {
   return EXTENSION_KIND[ext] ?? "json";
 }
 var LiveEditor = class {
-  /** `#`-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. */
   #client;
@@ -1270,7 +1331,7 @@ var LiveEditor = class {
     this.document = new LiveEditorDocument(client);
   }
   /**
-   * 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`,
@@ -1282,7 +1343,7 @@ var LiveEditor = class {
    * 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.
@@ -1321,6 +1382,9 @@ var LiveEditor = class {
    * `@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, view) {
     return this.#client.captureActiveDocument(size, view);
   }
@@ -1420,14 +1484,25 @@ var LiveEditor = class {
     await this.#client.setWorkspace(id);
   }
   /**
-   * 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.
    */
   async style(id) {
     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, layer) {
+    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
@@ -1710,6 +1785,10 @@ var LiveEditor = class {
   async redo() {
     return this.#client.redo();
   }
+  /** Reload the editor's page and resolve once the new document answers. */
+  async reloadPage() {
+    await this.#client.reloadPage();
+  }
   /** Mirrors `vgai status` — the full live editor state as JSON. */
   async status() {
     return this.#client.getState();
@@ -1818,7 +1897,10 @@ import { createRequire } from "node:module";
 import { dirname, join as join2 } from "node:path";
 import { pathToFileURL } from "node:url";
 var PRODUCT_DECLARATION_KEY = "vgai.product";
-var PRODUCT_INSTALL_LINES = ["  npm install --save-dev @volter/editor"];
+var PRODUCT_INSTALL_LINES = [
+  "  npm install --save-dev @volter/model-editor",
+  "  npm install --save-dev @volter/game-editor"
+];
 var PRODUCT_CREATE_LINES = ["  npx @volter/editor create <name>"];
 var PRODUCT_COLOR_THEMES = ["dark", "light"];
 function readProductManifest(packageDir) {