@volter/editor-live 0.5.64 → 0.5.66

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@volter/editor-live",
   "author": "Volter AI, Inc.",
-  "version": "0.5.64",
+  "version": "0.5.66",
   "publishConfig": {
     "access": "public"
   },
@@ -30,8 +30,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@volter/editor-sdk": "0.5.64",
-    "@volter/editor-project": "0.5.64",
+    "@volter/editor-sdk": "0.5.66",
+    "@volter/editor-project": "0.5.66",
     "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 {

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();

package/src/session.ts

@@ -6,6 +6,7 @@
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { resolveManifestPath } from '@volter/editor-project/manifest/locate';
+import { resolveProductForProject } from '@volter/editor-sdk/session/product-locator';
 import {
   EDITOR_SESSION_DISCOVERY_TIMEOUT_MS,
   type EditorSessionInfo,
@@ -176,14 +177,14 @@ function noMatchingSessionRefusal(
       `@volter/editor-live: could not READ the editor session registry while looking for ${projectRoot} — ` +
         `${discoveryFailure}. This is not the answer "no editor is running": the question went ` +
         'unanswered, so nothing is known about what is live. Retry (a probe can time out while ' +
-        'the box is loaded); if it keeps failing, `vgai sessions` asks the same question directly.',
+        `the box is loaded); if it keeps failing, ${sessionsCommandFor(projectRoot)} asks the same question directly.`,
     );
   }
   if (sessions.length === 0) {
     return new Error(
       `@volter/editor-live: the editor session registry is readable and lists NO live sessions, so none ` +
         `covers ${projectRoot}. @volter/editor-live only attaches to an already-running session — it ` +
-        'never starts one — so run `volter-editor edit` in that project first, then retry.',
+        `never starts one — so run ${editCommandFor(projectRoot)} in that project first, then retry.`,
     );
   }
   const listed = sessions
@@ -196,7 +197,7 @@ function noMatchingSessionRefusal(
       `  live sessions:\n${listed}\n` +
       '  If one of those is meant to be this project, the two paths differ after resolution — ' +
       'the usual cause is a git worktree or a symlink, where the session was opened through a ' +
-      'different path to the same files. Run `volter-editor edit` from THIS path, or use the path the ' +
+      `different path to the same files. Run ${editCommandFor(projectRoot)} from THIS path, or use the path the ` +
       'session lists.',
   );
 }
@@ -211,7 +212,7 @@ export async function resolveSession(
   const projectRoot = findRoot(projectDir);
   if (projectRoot === null) {
     throw new Error(
-      `@volter/editor-live: no vgai.project.json found in ${projectDir} or any parent directory — is this a vgai project?`,
+      `@volter/editor-live: no vgai.project.json found in ${projectDir} or any parent directory — is this a project?`,
     );
   }
 
@@ -265,3 +266,22 @@ export async function resolveSession(
 
   return { port: match.port, projectRoot };
 }
+
+/** `` `<product> edit` `` for the product this project declares, or a generic
+ *  phrase when it declares none — this package serves every product and
+ *  names only the one the project installed. */
+function editCommandFor(projectRoot: string): string {
+  return verbFor(projectRoot, 'edit');
+}
+
+function sessionsCommandFor(projectRoot: string): string {
+  return verbFor(projectRoot, 'sessions');
+}
+
+function verbFor(projectRoot: string, verb: string): string {
+  try {
+    return `\`${resolveProductForProject(projectRoot).command} ${verb}\``;
+  } catch {
+    return `its product's \`${verb}\` command`;
+  }
+}