@volter/editor-live 0.5.64 → 0.5.66

package/BUNDLED_NOTICES

@@ -3,8 +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.64
+@volter/editor-project@0.5.66
 Declared license: Apache-2.0
+Source: the unmodified npm package @volter/editor-project@0.5.66, from https://github.com/volter-ai/editor.git
 
 --- packages/editor-project/LICENSE ---
 
@@ -212,8 +213,9 @@ Declared license: Apache-2.0
    limitations under the License.
 
 
-@volter/editor-sdk@0.5.64
+@volter/editor-sdk@0.5.66
 Declared license: Apache-2.0
+Source: the unmodified npm package @volter/editor-sdk@0.5.66, 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;

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

@@ -168,7 +168,7 @@ var EditorClient = class {
         commandDispatcher = void 0;
         if (error?.name === "TimeoutError") {
           throw new EditorCommandError(
-            `The editor at ${this.baseUrl} never answered "${type}" within ${Math.round(deadlineMs / 1e3)}s \u2014 past every server-side budget, so the server itself is not answering. Check the terminal running \`volter-editor edit\`.`,
+            `The editor at ${this.baseUrl} never answered "${type}" within ${Math.round(deadlineMs / 1e3)}s \u2014 past every server-side budget, so the server itself is not answering. Check the terminal that started this editor session.`,
             void 0,
             true
           );
@@ -180,7 +180,7 @@ var EditorClient = class {
           continue;
         }
         throw new EditorCommandError(
-          `POST ${url} ("${type}") never reached the editor: ${code}${detail ? ` (${detail})` : ""}.` + (retried ? ` Retried once after ${TRANSPORT_RETRY_DELAY_MS}ms; it failed the same way.` : "") + (options?.retryTransport === true ? "" : " Not retried automatically: this command can change editor state, and a socket that died after the request was written cannot prove the editor did not already run it.") + " A transport failure means the port stopped answering, not that the editor refused \u2014 the dev server restarts on any watched source edit, and it shuts itself down after an idle window. Check the terminal running `volter-editor edit` and confirm the port this client resolved.",
+          `POST ${url} ("${type}") never reached the editor: ${code}${detail ? ` (${detail})` : ""}.` + (retried ? ` Retried once after ${TRANSPORT_RETRY_DELAY_MS}ms; it failed the same way.` : "") + (options?.retryTransport === true ? "" : " Not retried automatically: this command can change editor state, and a socket that died after the request was written cannot prove the editor did not already run it.") + " A transport failure means the port stopped answering, not that the editor refused \u2014 the dev server restarts on any watched source edit, and it shuts itself down after an idle window. Check the terminal that started this editor session and confirm the port this client resolved.",
           code,
           false
         );
@@ -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);
@@ -1017,7 +1073,7 @@ var EditorClient = class {
       if (error?.name === "TimeoutError") throw error;
       const { code, detail } = describeFetchFailure(error);
       throw new EditorCommandError(
-        `${init?.method ?? "GET"} ${url} never reached the editor: ${code}${detail ? ` (${detail})` : ""}. Nothing answered on that port \u2014 check the terminal running \`volter-editor edit\` and confirm the port this client resolved.`,
+        `${init?.method ?? "GET"} ${url} never reached the editor: ${code}${detail ? ` (${detail})` : ""}. Nothing answered on that port \u2014 check the terminal that started this editor session and confirm the port this client resolved.`,
         code,
         false
       );
@@ -1033,7 +1089,7 @@ var EditorClient = class {
     const contentType = res.headers.get("content-type") ?? "";
     if (!contentType.includes("application/json")) {
       throw new Error(
-        `The editor at ${this.baseUrl} answered with its page fallback (${contentType || "no content-type"}) rather than JSON, so no editor server handled the request. Check that this URL is a running \`volter-editor edit\` session.`
+        `The editor at ${this.baseUrl} answered with its page fallback (${contentType || "no content-type"}) rather than JSON, so no editor server handled the request. Check that this URL is a running editor session.`
       );
     }
     const body = await res.json();
@@ -1252,7 +1308,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 +1326,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 +1338,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 +1377,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 +1479,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 +1780,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();
@@ -1786,8 +1860,8 @@ function lazyChainProxy(resolveRoot, path = []) {
 }
 
 // src/session.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync as realpathSync2 } from "node:fs";
-import { dirname, join as join3, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync3, readFileSync as readFileSync3, realpathSync as realpathSync2 } from "node:fs";
+import { dirname as dirname2, join as join4, resolve as resolve2 } from "node:path";
 
 // ../editor-project/src/manifest/locate.ts
 import { existsSync } from "node:fs";
@@ -1812,18 +1886,175 @@ function resolveManifestPath(dir) {
   return join(dir, MANIFEST_FILENAME);
 }
 
+// ../editor-sdk/src/session/product-locator.ts
+import { existsSync as existsSync2, readFileSync } from "node:fs";
+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/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) {
+  const manifestPath = join2(packageDir, "package.json");
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    return null;
+  }
+  const declared = manifest.vgai?.product;
+  if (declared === void 0) return null;
+  const entry = declared.entry;
+  if (typeof entry !== "string" || !entry.startsWith("./"))
+    throw new Error(
+      `${manifestPath} declares ${PRODUCT_DECLARATION_KEY} but its "entry" is ${JSON.stringify(entry)}. It must be a ./-relative module \u2014 the product's ONE source entry, which is also its frame entry (e.g. "./src/index.ts").`
+    );
+  const resolved = join2(packageDir, entry);
+  if (!existsSync2(resolved))
+    throw new Error(
+      `${manifestPath} declares ${PRODUCT_DECLARATION_KEY}.entry ${JSON.stringify(entry)}, which does not exist (${resolved}).`
+    );
+  const colorTheme = declared.colorTheme;
+  if (typeof colorTheme !== "string" || !PRODUCT_COLOR_THEMES.includes(colorTheme))
+    throw new Error(
+      `${manifestPath} declares ${PRODUCT_DECLARATION_KEY} but its "colorTheme" is ${JSON.stringify(colorTheme)}. It must be ${PRODUCT_COLOR_THEMES.map(
+        (one) => JSON.stringify(one)
+      ).join(" or ")} \u2014 which way round this product paints, read before any of its code runs so the workbench's first frame is already the product's own background.`
+    );
+  const bin = manifest.bin;
+  const commands = bin !== null && typeof bin === "object" ? Object.keys(bin) : [];
+  if (commands.length !== 1)
+    throw new Error(
+      `${manifestPath} declares ${PRODUCT_DECLARATION_KEY} but its "bin" names ${commands.length === 0 ? "no command" : `${commands.length} commands`}. A product has exactly one command \u2014 the one every session message tells a person to run.`
+    );
+  const displayName = declared.displayName;
+  if (typeof displayName !== "string" || displayName.trim() === "")
+    throw new Error(
+      `${manifestPath} declares ${PRODUCT_DECLARATION_KEY} but its "displayName" is ${JSON.stringify(displayName)}. It must be the name a person sees (e.g. "Volter Editor").`
+    );
+  return {
+    name: typeof manifest.name === "string" ? manifest.name : packageDir,
+    version: typeof manifest.version === "string" ? manifest.version : "unknown",
+    command: commands[0],
+    displayName,
+    dir: packageDir,
+    entry,
+    colorTheme,
+    // A private source product may use an explicitly selected matching checkout.
+    // Public packages must always carry a downloadable, checksummed workbench.
+    workbench: manifest.private === true && declared.workbench === void 0 ? null : readProductWorkbench(manifestPath, declared.workbench)
+  };
+}
+var SHA256_HEX = /^[0-9a-f]{64}$/;
+function readProductWorkbench(manifestPath, declared) {
+  const example = '  "vgai": { "product": { "workbench": { "release": "<product>-<fork sha 12>-<platform>", "tarballSha256": "<64 hex>" } } }\n`node scripts/workbench/build-release.mjs --publish --out <release dir>` cuts the release and prints exactly that block.';
+  if (typeof declared !== "object" || declared === null || Array.isArray(declared))
+    throw new Error(
+      `${manifestPath} declares ${PRODUCT_DECLARATION_KEY} but its "workbench" is ${JSON.stringify(declared)}. A product IS the Code-OSS workbench it was compiled into, so it names the published release those bytes are:
+${example}`
+    );
+  const record = declared;
+  const extra = Object.keys(record).filter((key) => key !== "release" && key !== "tarballSha256");
+  if (extra.length > 0)
+    throw new Error(
+      `${manifestPath}'s ${PRODUCT_DECLARATION_KEY}.workbench carries ${extra.map((key) => `"${key}"`).join(", ")}, which this declaration has no meaning for. It names the release and the pin, and nothing else:
+${example}`
+    );
+  const release = record["release"];
+  if (typeof release !== "string" || release.trim() === "")
+    throw new Error(
+      `${manifestPath}'s ${PRODUCT_DECLARATION_KEY}.workbench names no "release" \u2014 the GitHub Release tag its workbench was published under:
+${example}`
+    );
+  const tarballSha256 = record["tarballSha256"];
+  if (typeof tarballSha256 !== "string" || !SHA256_HEX.test(tarballSha256))
+    throw new Error(
+      `${manifestPath}'s ${PRODUCT_DECLARATION_KEY}.workbench has tarballSha256 ${JSON.stringify(tarballSha256)}, which is not 64 hex characters. It is the PIN \u2014 the hash the downloaded tarball is checked against before a byte of it is extracted, so it is never approximate:
+${example}`
+    );
+  return { release, tarballSha256 };
+}
+function declaredVgaiPackages(projectRoot) {
+  let manifest;
+  try {
+    manifest = JSON.parse(
+      readFileSync(join2(projectRoot, "package.json"), "utf8")
+    );
+  } catch {
+    return [];
+  }
+  return Object.keys({ ...manifest.dependencies ?? {}, ...manifest.devDependencies ?? {} }).filter((name) => name.startsWith("@volter/")).sort();
+}
+function locatePackage(projectRoot, name) {
+  const require2 = createRequire(pathToFileURL(join2(projectRoot, "package.json")));
+  try {
+    return dirname(require2.resolve(`${name}/package.json`));
+  } catch {
+    try {
+      let dir = dirname(require2.resolve(name));
+      for (; ; ) {
+        const candidate = join2(dir, "package.json");
+        try {
+          if (JSON.parse(readFileSync(candidate, "utf8")).name === name)
+            return dir;
+        } catch {
+        }
+        const parent = dirname(dir);
+        if (parent === dir) return null;
+        dir = parent;
+      }
+    } catch {
+      return null;
+    }
+  }
+}
+function declaredProducts(projectRoot) {
+  const found = [];
+  for (const name of declaredVgaiPackages(projectRoot)) {
+    const dir = locatePackage(projectRoot, name);
+    if (dir === null) continue;
+    const product = readProductManifest(dir);
+    if (product !== null) found.push(product);
+  }
+  return found;
+}
+function resolveProductForProject(projectRoot) {
+  const products = declaredProducts(projectRoot);
+  if (products.length === 1) return products[0];
+  if (products.length === 0)
+    throw new Error(
+      `${projectRoot} declares no editor product, so there is no editor to open it in.
+The installed product supplies the editor,
+and which one runs is what the project installed, never a flag.
+For THIS folder, install the one you are building with:
+${PRODUCT_INSTALL_LINES.join("\n")}
+then run that product's \`edit\` command again. For a NEW project, the product creates it:
+${PRODUCT_CREATE_LINES.join("\n")}`
+    );
+  throw new Error(
+    `${projectRoot} declares ${products.length} editor products \u2014 ${products.map((product) => product.name).join(" and ")}.
+One page runs one product, and nothing here may choose between them. Remove the one you
+are not building with:
+` + products.map((product) => `  npm uninstall ${product.name}`).join("\n")
+  );
+}
+
 // ../editor-sdk/src/session/registry-format.ts
 import {
   mkdirSync,
   readdirSync,
-  readFileSync,
+  readFileSync as readFileSync2,
   realpathSync,
   unlinkSync,
   writeFileSync
 } from "node:fs";
 import { homedir } from "node:os";
-import { join as join2, resolve } from "node:path";
-var EDITOR_SESSIONS_REGISTRY_FILE = join2(homedir(), ".vgai", "editor-sessions.json");
+import { join as join3, resolve } from "node:path";
+var EDITOR_SESSIONS_REGISTRY_FILE = join3(homedir(), ".vgai", "editor-sessions.json");
 function isEditorSessionEntry(v) {
   if (typeof v !== "object" || v === null) return false;
   const s = v;
@@ -1854,7 +2085,7 @@ function pidAlive(pid) {
 }
 function readLiveRegisteredSessions() {
   try {
-    const raw = JSON.parse(readFileSync(EDITOR_SESSIONS_REGISTRY_FILE, "utf8"));
+    const raw = JSON.parse(readFileSync2(EDITOR_SESSIONS_REGISTRY_FILE, "utf8"));
     return Array.isArray(raw) ? raw.filter(isEditorSessionEntry).map(normalizeEditorSessionEntry).filter((s) => pidAlive(s.pid)) : [];
   } catch {
     return [];
@@ -1933,8 +2164,8 @@ var HttpSessionDiscovery = class {
 function findProjectRootFrom(dir) {
   let cur = resolve2(dir);
   for (; ; ) {
-    if (existsSync2(resolveManifestPath(cur))) return cur;
-    const parent = dirname(cur);
+    if (existsSync3(resolveManifestPath(cur))) return cur;
+    const parent = dirname2(cur);
     if (parent === cur) return null;
     cur = parent;
   }
@@ -1949,7 +2180,7 @@ function canonicalPath(path) {
 function readProjectSession(projectRoot) {
   try {
     const value = JSON.parse(
-      readFileSync2(join3(projectRoot, ".vgai", "session.json"), "utf8")
+      readFileSync3(join4(projectRoot, ".vgai", "session.json"), "utf8")
     );
     if (typeof value !== "object" || value === null) return null;
     const hint = value;
@@ -1981,12 +2212,12 @@ ${manifestError}`
 function noMatchingSessionRefusal(projectRoot, canon, sessions, discoveryFailure) {
   if (discoveryFailure !== null) {
     return new Error(
-      `@volter/editor-live: could not READ the editor session registry while looking for ${projectRoot} \u2014 ${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.`
+      `@volter/editor-live: could not READ the editor session registry while looking for ${projectRoot} \u2014 ${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, ${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 \u2014 it never starts one \u2014 so run \`volter-editor edit\` in that project first, then retry.`
+      `@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 \u2014 it never starts one \u2014 so run ${editCommandFor(projectRoot)} in that project first, then retry.`
     );
   }
   const listed = sessions.map((s) => `    port ${s.port} \u2192 ${s.project === null ? "(no project)" : s.project}`).join("\n");
@@ -1995,7 +2226,7 @@ function noMatchingSessionRefusal(projectRoot, canon, sessions, discoveryFailure
   looking for (resolved): ${canon}
   live sessions:
 ${listed}
-  If one of those is meant to be this project, the two paths differ after resolution \u2014 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 session lists.`
+  If one of those is meant to be this project, the two paths differ after resolution \u2014 the usual cause is a git worktree or a symlink, where the session was opened through a different path to the same files. Run ${editCommandFor(projectRoot)} from THIS path, or use the path the session lists.`
   );
 }
 async function resolveSession(projectDir = process.cwd(), deps = {}) {
@@ -2004,7 +2235,7 @@ async function resolveSession(projectDir = process.cwd(), deps = {}) {
   const projectRoot = findRoot(projectDir);
   if (projectRoot === null) {
     throw new Error(
-      `@volter/editor-live: no vgai.project.json found in ${projectDir} or any parent directory \u2014 is this a vgai project?`
+      `@volter/editor-live: no vgai.project.json found in ${projectDir} or any parent directory \u2014 is this a project?`
     );
   }
   const localHint = (deps.readProjectSession ?? readProjectSession)(projectRoot);
@@ -2039,6 +2270,19 @@ async function resolveSession(projectDir = process.cwd(), deps = {}) {
   if (match.manifestError != null) throw manifestRefusal(projectRoot, match.manifestError);
   return { port: match.port, projectRoot };
 }
+function editCommandFor(projectRoot) {
+  return verbFor(projectRoot, "edit");
+}
+function sessionsCommandFor(projectRoot) {
+  return verbFor(projectRoot, "sessions");
+}
+function verbFor(projectRoot, verb) {
+  try {
+    return `\`${resolveProductForProject(projectRoot).command} ${verb}\``;
+  } catch {
+    return `its product's \`${verb}\` command`;
+  }
+}
 
 // src/singleton.ts
 function createLazySession(factory) {