@volter/game-editor 0.5.65 → 0.5.66

package/dist-node/cli.js

@@ -584,10 +584,21 @@ var init_client = __esm({
       }
       /** 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) {
@@ -798,7 +809,8 @@ var init_client = __esm({
       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
@@ -986,6 +998,50 @@ var init_client = __esm({
       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);
@@ -1969,8 +2025,7 @@ function projectRelative(project, absolute) {
   if (rel === "" || rel.startsWith("../")) return null;
   return rel;
 }
-async function serveBlenderMcp(project, ensureEditor = async () => {
-}, command = "volter-editor") {
+async function serveBlenderMcp(project, ensureEditor, command) {
   const runtimeIdentity = `Blender ${BUNDLE_default.blender} (source ${BUNDLE_default.source}), compiled to WebAssembly and running headless in the editor tab; three.js takes its photographs. Factory bpy.context.scene.render.engine: '${BUNDLE_default.factoryEngine}'. Documents are .blend. save_as_mainfile records the actual saved path in bpy.data.filepath; open_mainfile reopens it.`;
   const tools = blender_mcp_tools_default.map(
     (tool) => tool.name === "execute_blender_code" ? { ...tool, description: `${runtimeIdentity}
@@ -2255,7 +2310,7 @@ import { fileURLToPath as fileURLToPath2 } from "node:url";
 var package_default = {
   name: "@volter/game-editor",
   author: "Volter AI, Inc.",
-  version: "0.5.65",
+  version: "0.5.66",
   publishConfig: {
     access: "public"
   },
@@ -2297,23 +2352,26 @@ var package_default = {
       displayName: "Volter Game Editor",
       colorTheme: "dark",
       workbench: {
-        release: "game-editor-f8664703ab59-595ba7af8402-darwin-arm64",
-        tarballSha256: "fac04a80a9745b6af25c232308faab1691ef2ecc40883cc8c9b89b42f12f8ccd"
+        release: "game-editor-9ef15b1f345b-e22708e88dca-darwin-arm64",
+        tarballSha256: "ffa4556a84b2744c966d3461d022ccf27c5123bcb48025628f3a0129779e9b17"
       }
     }
   },
   dependencies: {
-    "@volter/editor-core": "0.5.65",
-    "@volter/editor-game": "0.5.65",
-    "@volter/editor-blender": "0.1.8",
-    "@volter/blender-engine": "0.1.7",
-    "@volter/editor-project": "0.5.65",
-    "@volter/editor-sdk": "0.5.65",
-    "@volter/editor-live": "0.5.65",
-    "@volter/game-live": "0.5.65",
+    "@volter/editor-core": "0.5.66",
+    "@volter/editor-game": "0.5.66",
+    "@volter/editor-react": "0.5.66",
+    "@volter/editor-threejs": "0.5.66",
+    "@volter/editor-xstate": "0.5.66",
+    "@volter/editor-blender": "0.1.9",
+    "@volter/blender-engine": "0.1.8",
+    "@volter/editor-project": "0.5.66",
+    "@volter/editor-sdk": "0.5.66",
+    "@volter/editor-live": "0.5.66",
+    "@volter/game-live": "0.5.66",
     "@modelcontextprotocol/sdk": "1.30.0",
-    "@volter/game-runtime": "0.5.65",
-    "@volter/threejs-runtime": "0.5.65",
+    "@volter/game-runtime": "0.5.66",
+    "@volter/threejs-runtime": "0.5.66",
     undici: "7.29.1",
     typescript: "5.9.3",
     "@colyseus/schema": "^4.0.14",
@@ -2392,14 +2450,8 @@ var STUDIO_OWNED_PATHS = [
   "src/contributions/analytics.analytics.tsx"
 ];
 var REACT_ONLY_REMOVED_PATHS = [
-  "src/runtime",
-  "src/scripts",
   "src/prefabs",
-  "src/stage",
   "src/world.tsx",
-  "src/lib/humanoid",
-  "src/lib/mesh",
-  "src/lib/native-three",
   "src/components",
   "public"
 ];
@@ -2437,6 +2489,43 @@ export function ReactGamePage({ lastInput, title = 'My Game' }: ReactGamePagePro
   );
 }
 `;
+var REACT_HUD_PAGE_SOURCE = `export interface ReactGamePageProps {
+  readonly lastInput: string;
+  readonly title?: string;
+}
+
+/** The game's HUD over its 3D world. Runtime input ownership stays in game.tsx. */
+export function ReactGamePage({ lastInput, title = 'My Game' }: ReactGamePageProps) {
+  return (
+    <main
+      data-testid="game-ui-root"
+      style={{
+        position: 'absolute',
+        inset: 0,
+        padding: 16,
+        pointerEvents: 'none',
+        fontFamily: 'system-ui, sans-serif',
+      }}
+    >
+      <section
+        style={{
+          display: 'inline-block',
+          padding: '10px 14px',
+          borderRadius: 8,
+          pointerEvents: 'auto',
+          color: '#f7f4ea',
+          background: 'rgba(17, 24, 39, 0.72)',
+        }}
+      >
+        <h1 style={{ margin: 0, fontSize: 18 }}>{title}</h1>
+        <p aria-live="polite" style={{ margin: '4px 0 0', color: '#cbd5e1', fontSize: 13 }}>
+          Last input: {lastInput}
+        </p>
+      </section>
+    </main>
+  );
+}
+`;
 var REACT_ONLY_GAME_SOURCE = `import { useEffect, useState } from 'react';
 import { useDebugProvider } from '@volter/game-runtime/react/world-state';
 import { ReactGamePage } from './game-page';
@@ -3704,34 +3793,36 @@ import {
 import { dirname, isAbsolute, join as join3, relative as relative2, resolve, sep as sep2 } from "node:path";
 
 // node/scaffold/adapter-region-merge.ts
-import ts from "typescript";
+import { createRequire } from "node:module";
+var loaded;
+var typescript = () => loaded ??= createRequire(import.meta.url)("typescript");
 function quoteLike(source, sample) {
   const double = sample !== void 0 && source[sample.getStart()] === '"';
   return (value) => double || value.includes("'") ? JSON.stringify(value) : `'${value}'`;
 }
 function stringLiteralOf(node) {
-  return node && ts.isStringLiteralLike(node) ? node.text : void 0;
+  return node && typescript().isStringLiteralLike(node) ? node.text : void 0;
 }
 function propertyOf(object, name) {
   for (const member of object.properties) {
-    if (!ts.isPropertyAssignment(member)) continue;
-    const key = ts.isIdentifier(member.name) ? member.name.text : stringLiteralOf(member.name);
+    if (!typescript().isPropertyAssignment(member)) continue;
+    const key = typescript().isIdentifier(member.name) ? member.name.text : stringLiteralOf(member.name);
     if (key === name) return member;
   }
   return void 0;
 }
 function definitionObject(source) {
   for (const statement of source.statements) {
-    if (!ts.isExportAssignment(statement) || statement.isExportEquals) continue;
+    if (!typescript().isExportAssignment(statement) || statement.isExportEquals) continue;
     const call = statement.expression;
-    if (!ts.isCallExpression(call)) {
+    if (!typescript().isCallExpression(call)) {
       return { reason: "its default export is not a direct `defineAdapter({\u2026})` call" };
     }
     const arg = call.arguments[0];
     if (arg === void 0) {
       return { reason: "its default export takes no argument object to declare into" };
     }
-    if (!ts.isObjectLiteralExpression(arg)) {
+    if (!typescript().isObjectLiteralExpression(arg)) {
       return { reason: "its default export is not called with an object literal" };
     }
     return { object: arg };
@@ -3781,11 +3872,11 @@ ${indent}},`;
 }
 function mergeAdapterRegionIncludes(source, additions) {
   if (additions.length === 0) return { kind: "unchanged" };
-  const parsed = ts.createSourceFile("vgai.adapter.ts", source, ts.ScriptTarget.Latest, true);
+  const parsed = typescript().createSourceFile("vgai.adapter.ts", source, typescript().ScriptTarget.Latest, true);
   const definition = definitionObject(parsed);
   if ("reason" in definition) return { kind: "unreadable", reason: definition.reason };
   const listed = propertyOf(definition.object, "regions");
-  if (listed && !ts.isStringLiteralLike(listed.initializer)) {
+  if (listed && !typescript().isStringLiteralLike(listed.initializer)) {
     return {
       kind: "unreadable",
       reason: "it states an explicit `regions` list, whose entries carry their own `include`"
@@ -3806,7 +3897,7 @@ ${indent}},`;
       })
     );
   } else {
-    if (!ts.isObjectLiteralExpression(overlay.initializer)) {
+    if (!typescript().isObjectLiteralExpression(overlay.initializer)) {
       return { kind: "unreadable", reason: "`regionIncludes` is not an object literal" };
     }
     const table = overlay.initializer;
@@ -3819,7 +3910,7 @@ ${indent}},`;
         );
         continue;
       }
-      if (!ts.isObjectLiteralExpression(entry.initializer)) {
+      if (!typescript().isObjectLiteralExpression(entry.initializer)) {
         return {
           kind: "unreadable",
           reason: `\`regionIncludes.${addition.rootId}\` is not an object literal`
@@ -3838,7 +3929,7 @@ ${indent}],`;
         );
         continue;
       }
-      if (!ts.isArrayLiteralExpression(include.initializer)) {
+      if (!typescript().isArrayLiteralExpression(include.initializer)) {
         return {
           kind: "unreadable",
           reason: `\`regionIncludes.${addition.rootId}.include\` is not an array literal`
@@ -5420,7 +5511,11 @@ function rewriteTemplateVariantFiles(targetDir, composition, additions, starterD
     for (const [relative7, source] of Object.entries(REACT_ONLY_FILES)) {
       if (relative7 === "src/main.ts") continue;
       mkdirSync3(dirname2(join4(targetDir, relative7)), { recursive: true });
-      writeFileSync3(join4(targetDir, relative7), source, "utf-8");
+      writeFileSync3(
+        join4(targetDir, relative7),
+        relative7 === "src/ui/game-page.tsx" ? REACT_HUD_PAGE_SOURCE : source,
+        "utf-8"
+      );
     }
     return;
   }
@@ -5462,6 +5557,9 @@ function rewriteTsconfig(targetDir, engineRelPath, editorRelPath) {
   if (editorRelPath) {
     tsconfig.compilerOptions.paths["@editor/*"] = [`${editorRelPath}/src/*`];
   }
+  tsconfig.compilerOptions.paths["@editor/game-module-access"] = [
+    "node_modules/@volter/editor-game/src/host/game-module-access.ts"
+  ];
   if (Array.isArray(tsconfig.files)) {
     tsconfig.files = tsconfig.files.map((f) => rewriteEngineRelativeFilePath(f, engineRelPath));
   }
@@ -6339,7 +6437,7 @@ import { createRequire as createRequire2 } from "node:module";
 import { mkdirSync as mkdirSync32, openSync, closeSync, realpathSync as realpathSync3 } from "node:fs";
 import { join as join42, resolve as resolve22 } from "node:path";
 import { existsSync as existsSync6, readFileSync as readFileSync7 } from "node:fs";
-import { createRequire } from "node:module";
+import { createRequire as createRequire3 } from "node:module";
 import { dirname as dirname5, join as join8 } from "node:path";
 import { pathToFileURL } from "node:url";
 import { execFileSync as execFileSync4 } from "node:child_process";
@@ -6362,7 +6460,10 @@ import { mkdirSync as mkdirSync22, readFileSync as readFileSync32, renameSync as
 import { homedir as homedir22 } from "node:os";
 import { dirname as dirname22, join as join32 } from "node:path";
 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) {
@@ -6460,7 +6561,7 @@ function declaredVgaiPackages(projectRoot) {
   return Object.keys({ ...manifest.dependencies ?? {}, ...manifest.devDependencies ?? {} }).filter((name) => name.startsWith("@volter/")).sort();
 }
 function locatePackage(projectRoot, name) {
-  const require2 = createRequire(pathToFileURL(join8(projectRoot, "package.json")));
+  const require2 = createRequire3(pathToFileURL(join8(projectRoot, "package.json")));
   try {
     return dirname5(require2.resolve(`${name}/package.json`));
   } catch {
@@ -6676,7 +6777,8 @@ async function resolveWorkbenchForProject(options) {
       fetched: false
     };
   const declared = readWorkbenchDeclaration(projectRoot);
-  if (declared !== null)
+  const fetchRecord = declared !== null && product.workbench !== null && declared.startsWith(`${WORKBENCH_CACHE_ROOT}/`);
+  if (declared !== null && !fetchRecord)
     return {
       ...resolveWorkbench(declared, productId),
       source: "declaration",
@@ -7127,6 +7229,22 @@ async function launch(folder, launching, options = {}) {
     clearLaunch();
   }
 }
+async function prepareSession(folder, launching) {
+  const project = realpathSync3(resolve22(folder));
+  const product = resolveProductForProject(project);
+  if (product.name !== launching.packageName) throw new Error(`${project} declares ${product.name}, not ${launching.displayName}.`);
+  const entry = createRequire2(join42(product.dir, "package.json")).resolve("@volter/editor-core/server/packaged");
+  const code = await new Promise((done, fail2) => {
+    const child = spawn2(process.execPath, [entry], {
+      cwd: project,
+      stdio: ["ignore", "inherit", "inherit"],
+      env: { ...process.env, VGAI_PROJECT: project, VGAI_PRODUCT_DIR: product.dir, VGAI_NO_OPEN: "1", VGAI_PREPARE: "1" }
+    });
+    child.once("error", fail2);
+    child.once("exit", done);
+  });
+  if (code !== 0) throw new Error(`${launching.command} prepare exited with code ${code} for ${project}.`);
+}
 async function ensureTab(serverUrl, noOpen) {
   const openAttemptAt = Date.now();
   const result = await requestEditorTabEnsure(serverUrl, !noOpen);
@@ -7140,7 +7258,7 @@ async function ensureTab(serverUrl, noOpen) {
   if (outcome.status !== "connected") throw new Error(`Editor page ${outcome.status === "never-arrived" ? "did not arrive" : "arrived but did not become ready"}; open the printed workbench URL and inspect the session log.`);
 }
 
-// ../editor-core/dist/server/chunk-PXZD53D5.js
+// ../editor-core/dist/server/chunk-IVCRYPQI.js
 import { Agent, fetch as nodeFetch } from "undici";
 function createDispatcher(timeoutMs) {
   return new Agent({ headersTimeout: timeoutMs, bodyTimeout: timeoutMs });
@@ -7698,10 +7816,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) {
@@ -7912,7 +8041,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
@@ -8100,6 +8230,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);
@@ -8221,8 +8395,82 @@ var EditorClient = class {
 };
 
 // ../editor-core/dist/server/launcher/control.js
-import { connect } from "@volter/editor-live";
+import { connect, unconnectedBindings } from "@volter/editor-live";
+var NOISE = /* @__PURE__ */ new Set(["constructor", "then", "catch", "finally"]);
+var FUNCTION_NOISE = /* @__PURE__ */ new Set(["length", "name", "prototype", "arguments", "caller"]);
+function describe(target, key) {
+  let current = target;
+  while (current !== null) {
+    const descriptor = Object.getOwnPropertyDescriptor(current, key);
+    if (descriptor !== void 0) return descriptor;
+    current = Object.getPrototypeOf(current);
+  }
+  return void 0;
+}
+function ownAndInheritedKeys(target) {
+  const targetIsFunction = typeof target === "function";
+  const keys = [];
+  const seen = /* @__PURE__ */ new Set();
+  let current = target;
+  while (current !== null && current !== Object.prototype && current !== Function.prototype && current !== Array.prototype) {
+    for (const name of Object.getOwnPropertyNames(current)) {
+      if (seen.has(name)) continue;
+      seen.add(name);
+      if (NOISE.has(name) || name.startsWith("_")) continue;
+      if (targetIsFunction && FUNCTION_NOISE.has(name)) continue;
+      keys.push(name);
+    }
+    current = Object.getPrototypeOf(current);
+  }
+  return keys;
+}
+function isNamespace(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  if (proto === Object.prototype || proto === null) return false;
+  return ownAndInheritedKeys(value).some((key) => typeof describe(value, key)?.value === "function");
+}
+function surfaceMembers(target) {
+  if (typeof target !== "object" && typeof target !== "function" || target === null) return [];
+  const members = [];
+  for (const name of ownAndInheritedKeys(target)) {
+    const descriptor = describe(target, name);
+    if (descriptor === void 0) continue;
+    if (descriptor.get !== void 0 || descriptor.set !== void 0) {
+      members.push({ name, kind: "value", arity: 0 });
+      continue;
+    }
+    const value = descriptor.value;
+    if (typeof value === "function") members.push({ name, kind: "method", arity: value.length });
+    else if (isNamespace(value)) {
+      for (const inner of ownAndInheritedKeys(value)) {
+        const innerValue = describe(value, inner)?.value;
+        if (typeof innerValue === "function") members.push({ name: `${name}.${inner}`, kind: "method", arity: innerValue.length });
+      }
+    } else members.push({ name, kind: "value", arity: 0 });
+  }
+  return members.sort((a, b) => a.name.localeCompare(b.name));
+}
+function formatSurface(command, bindings) {
+  const lines = [`In scope for \`${command} eval\` (read from the objects themselves):`, ""];
+  for (const [binding, target] of Object.entries(bindings)) {
+    const members = surfaceMembers(target);
+    lines.push(binding);
+    if (members.length === 0) lines.push(`  (data; inspect it with: ${command} eval 'return ${binding}')`);
+    const names = members.map((m) => m.kind === "method" ? `${m.name}(${m.arity || ""})` : m.name);
+    const width = Math.max(0, ...names.map((n) => n.length)) + 2;
+    for (let i = 0; i < names.length; i += 3) lines.push(`  ${names.slice(i, i + 3).map((n) => n.padEnd(width)).join("").trimEnd()}`);
+    lines.push("");
+  }
+  lines.push("Parens mark a method; the number is its declared parameter count. A bare name is a field.");
+  return lines.join("\n");
+}
 async function control(command, verb, argument, reason, scope) {
+  if (verb === "eval" && argument === "--list") {
+    const unconnected = { ...unconnectedBindings(), session: { port: 0, projectRoot: process.cwd() } };
+    console.log(formatSurface(command, { ...unconnected, ...scope?.(unconnected) }));
+    return;
+  }
   const live = await connect();
   const client = new EditorClient({ url: `http://127.0.0.1:${live.session.port}` });
   if (verb === "close") {
@@ -8240,11 +8488,18 @@ async function control(command, verb, argument, reason, scope) {
     console.log(JSON.stringify(result, null, 2));
   } else if (verb === "status") console.log(JSON.stringify(await live.editor.status(), null, 2));
   else if (verb === "eval") {
-    if (!argument) throw new Error("eval requires a JavaScript function body; use return to print a result.");
+    if (!argument) throw new Error(`eval requires JavaScript; \`${command} eval --list\` shows what is in scope.`);
     const AsyncFunction = Object.getPrototypeOf(async function() {
     }).constructor;
     const bindings = { editor: live.editor, tools: live.tools, session: live.session, ...scope?.(live) };
-    const result = await new AsyncFunction(...Object.keys(bindings), argument)(...Object.values(bindings));
+    let body;
+    try {
+      body = new AsyncFunction(...Object.keys(bindings), `return (${argument}
+);`);
+    } catch {
+      body = new AsyncFunction(...Object.keys(bindings), argument);
+    }
+    const result = await body(...Object.values(bindings));
     if (result !== void 0) console.log(JSON.stringify(result, null, 2));
   } else if (verb !== "console") throw new Error(`Unknown command: ${verb}`);
   const consoleState = await client.getUnresolvedConsole();
@@ -8272,22 +8527,10 @@ var alwaysRefresh = (timeoutMs = DEFAULT_RELAY_COMMAND_TIMEOUT_MS) => ({
 });
 var RELAY_COMMANDS = {
   "session-prepare-close": noDerivedRefresh(12e4),
-  // ---- Selection and framing ---------------------------------------------
+  // ---- Selection ---------------------------------------------------------
   select: noDerivedRefresh(3e4),
   "select-multiple": noDerivedRefresh(),
   "select-all": noDerivedRefresh(),
-  "focus-entity": noDerivedRefresh(),
-  "frame-entity": noDerivedRefresh(),
-  "focus-selection": noDerivedRefresh(),
-  "view-preset": noDerivedRefresh(),
-  "set-camera": noDerivedRefresh(),
-  // ---- Looking at the open Object3D document ------------------------------
-  // These ANIMATE the shared camera and ack when the move ends, so their
-  // budget is the move's own wall clock, not an editor edit's. Both refuse a
-  // duration past 60 s themselves; the ceiling here is the relay's backstop.
-  "document-orbit": noDerivedRefresh(12e4),
-  "document-turntable": noDerivedRefresh(12e4),
-  "document-frame": noDerivedRefresh(),
   // ---- Editor chrome ------------------------------------------------------
   "viewport-tab": noDerivedRefresh(),
   // Focusing a panel is dock work, but its ack WAITS for the dock to report
@@ -8320,6 +8563,8 @@ var RELAY_COMMANDS = {
   // A style bundle is chrome appearance; the document is untouched.
   "set-style": noDerivedRefresh(),
   "set-appearance": noDerivedRefresh(),
+  // A view's viewport presentation (lighting, backdrop, overlays); the document is untouched.
+  "viewport-presentation": noDerivedRefresh(),
   "present-view": alwaysRefresh(3e4),
   "current-view": refreshIfContentChanged(),
   // A read of the resolved document table; changes nothing.
@@ -8370,21 +8615,14 @@ var RELAY_COMMANDS = {
   "capture-active-document": refreshIfContentChanged(3e4),
   // The whole editor page through the same compositor; the foreignObject leg
   // over a full dock takes seconds, not milliseconds.
-  "capture-editor-chrome": refreshIfContentChanged(3e4),
-  "capture-viewport": refreshIfContentChanged(),
-  "capture-asset-preview": refreshIfContentChanged(3e4),
+  "capture-editor-chrome": refreshIfContentChanged(3e4)
   // The ONE door onto a view's verbs (`@volter/editor-sdk/views`, U8 ruling 1).
   // A verb either READS the view or moves its own transform; neither touches
   // a document, so nothing derived refreshes.
-  // ---- Viewport toggles ---------------------------------------------------
-  "set-grid": noDerivedRefresh(),
-  "set-helpers": noDerivedRefresh(),
-  "set-stats": noDerivedRefresh(),
-  "set-shading-mode": noDerivedRefresh(),
-  "set-helper-type": noDerivedRefresh(),
-  "set-transform-mode": noDerivedRefresh(),
-  "set-transform-space": noDerivedRefresh(),
-  "set-snap": noDerivedRefresh()
+  // The THREE VIEWPORT'S verbs — framing, the camera, view presets, the open
+  // Object3D document's orbit/turntable/frame, the viewport photograph and the
+  // display and transform toggles — are its own command contribution
+  // (`viewport-commands.ts`), each budget on its contributed row.
   // The BLENDER lane's ten verbs are `@vgai/blender`'s
   // `contributions/blender.command.ts` (WORK.md §The workbench, item D) —
   // each row's budget travelled with it, onto the contributed spec the page
@@ -9211,10 +9449,12 @@ try {
     port: { type: "string" },
     version: { type: "boolean", short: "v" },
     help: { type: "boolean", short: "h" },
+    list: { type: "boolean" },
     ...SCREENSHOT_OPTIONS,
     ...CAPABILITY_OPTIONS
   } });
   const [verb = "edit", folder = "."] = positionals;
+  if (values.list && verb !== "eval") throw new Error("--list belongs to eval.");
   for (const key of Object.keys(SCREENSHOT_OPTIONS))
     if (values[key] !== void 0 && verb !== "screenshot") throw new Error(`--${key} belongs to screenshot.`);
   for (const key of Object.keys(CAPABILITY_OPTIONS))
@@ -9224,10 +9464,11 @@ try {
   } else if (values.help) {
     console.log(`Volter Game Editor
   volter-game-editor create <folder> [--template ${Object.keys(presets.templates).join("|")}] [--with ${SCAFFOLD_ADDITIONS.join(",")}] [--workbench <dir>]
+  volter-game-editor prepare [folder]    # run the session's dependency optimizer ahead of time (an image build's step)
   volter-game-editor edit [folder] [--workbench <dir>] [--no-open] [--port <n>]
   volter-game-editor status | console | close
   volter-game-editor console ack <id> --reason <text>
-  volter-game-editor eval <JavaScript body>   # { editor, game, page, tools, session } in scope
+  volter-game-editor eval <JavaScript> | --list   # { editor, game, page, tools, session } in scope
   volter-game-editor play | stop | restart
   volter-game-editor ${SCREENSHOT_USAGE}
   volter-game-editor sessions | project | projects
@@ -9272,6 +9513,9 @@ try {
   } else if (verb === "sessions" || verb === "project" || verb === "projects") {
     if (positionals.length > 1) throw new Error(`Usage: volter-game-editor ${verb}`);
     await (verb === "sessions" ? listSessions() : verb === "project" ? showProject() : listRecentProjects());
+  } else if (verb === "prepare") {
+    if (positionals.length > 2) throw new Error("Usage: volter-game-editor prepare [folder]");
+    await prepareSession(folder, PRODUCT3);
   } else if (verb === "open") {
     if (positionals.length !== 2) throw new Error("Usage: volter-game-editor open <path>");
     await openProject(positionals[1]);
@@ -9281,7 +9525,7 @@ try {
   } else if (["status", "console", "eval", "close"].includes(verb)) {
     if (positionals.length > (verb === "eval" ? 2 : 1)) throw new Error("Unexpected arguments.");
     const { gameBindings } = await import("@volter/game-live");
-    await control(PRODUCT3.command, verb, positionals[1], void 0, (live) => {
+    await control(PRODUCT3.command, verb, values.list ? "--list" : positionals[1], void 0, (live) => {
       const { game, page, recording } = gameBindings(live.session);
       return { editor: Object.assign(live.editor, { recording }), game, page };
     });