@volter/editor-live 0.5.57

package/dist/index.js

@@ -0,0 +1,2080 @@
+// ../editor-sdk/src/http-transport.node.ts
+import { Agent, fetch as nodeFetch } from "undici";
+function createDispatcher(timeoutMs) {
+  return new Agent({ headersTimeout: timeoutMs, bodyTimeout: timeoutMs });
+}
+async function dispatchFetch(url, init, dispatcher) {
+  if (!dispatcher) return fetch(url, init);
+  return await nodeFetch(url, {
+    ...init,
+    dispatcher
+  });
+}
+
+// ../editor-sdk/src/client.ts
+var DEFAULT_URL = "http://127.0.0.1:20173";
+var EditorCommandError = class extends Error {
+  code;
+  /**
+   * True when the RELAY ended the command itself rather than the editor
+   * answering it — the HTTP 504 that `server/server-utils.ts`'s
+   * `commandResponseFor` gives any `timedOut` result, or this client's own
+   * deadline below.
+   *
+   * Read it as "no answer", not as "the budget expired". `editor-server.ts`
+   * raises `timedOut` for five conditions and only one of them takes the full
+   * budget: the command's timer expiring, the controlling tab's socket dying,
+   * the receipt window closing unanswered, a beating-but-dead tab, and no tab
+   * present at all. The last four can fail in milliseconds.
+   *
+   * A caller that converges by retrying (`vgai restart`) needs the distinction
+   * because a refusal the editor ANSWERED may go differently next time, while
+   * a command the relay abandoned tells you nothing new on a second identical
+   * attempt — and when the abandonment was a 120s budget, re-running it three
+   * times is `restart-readiness.ts`'s 361-seconds-of-silence defect.
+   */
+  timedOut;
+  constructor(message, code, timedOut = false) {
+    super(message);
+    this.name = "EditorCommandError";
+    this.code = code;
+    this.timedOut = timedOut;
+  }
+};
+var COMMAND_DEADLINE_MS = 15e4;
+var BLENDER_DEADLINE_MS = 30 * 6e4;
+var UNDICI_DEFAULT_HEADERS_TIMEOUT_MS = 3e5;
+var CONSOLE_DRAIN_TIMEOUT_MS = 1500;
+function describeFetchFailure(error) {
+  const messages = [];
+  let current = error;
+  for (let depth = 0; depth < 8; depth++) {
+    if (!(current instanceof Error)) break;
+    if (current.message) messages.push(current.message);
+    const code = current.code;
+    if (typeof code === "string" && code !== "") {
+      return { code, detail: messages.join(" <- ") };
+    }
+    const aggregate = current.errors;
+    if (Array.isArray(aggregate) && aggregate.length > 0) {
+      const inner = describeFetchFailure(aggregate[0]);
+      return { code: inner.code, detail: [...messages, inner.detail].join(" <- ") };
+    }
+    current = current.cause;
+  }
+  return { code: "UNKNOWN", detail: messages.join(" <- ") || String(error) };
+}
+var RETRYABLE_TRANSPORT_CODES = /* @__PURE__ */ new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "EPIPE",
+  "ETIMEDOUT",
+  "EHOSTUNREACH",
+  "UND_ERR_SOCKET",
+  "UND_ERR_CONNECT_TIMEOUT"
+]);
+var TRANSPORT_RETRY_DELAY_MS = 400;
+var EditorClient = class {
+  baseUrl;
+  /**
+   * The running game's debug plane — see {@link GameDebugDoor}. It rides the
+   * SAME `/__editor/command` relay every other method here uses (relay cases
+   * `inspect-gameplay-state` / `invoke-debug-command`, `command-listener.ts`),
+   * so a tool contribution reaches the game through the client it already has
+   * rather than a second channel of its own.
+   */
+  game;
+  /**
+   * Called with the raw body of EVERY response this client receives — command
+   * envelopes and `/__editor/state` alike, on success AND on refusal.
+   *
+   * It exists for exactly one contract: the server stamps `unresolvedConsole`
+   * onto every envelope (`server-utils.ts`'s `commandResponseFor`), and the CLI
+   * has to see those counts to be loud about them. Routing that through a
+   * single observer here — rather than teaching each of the CLI's output sites
+   * to unpack a response — is what keeps the loudness contract ONE mechanism.
+   * The observer must not throw; anything it raises is swallowed, because a
+   * reporting hook may never break the command it is reporting on.
+   */
+  transport;
+  onEnvelope;
+  constructor(opts) {
+    if (opts !== void 0 && (typeof opts !== "object" || opts === null || Array.isArray(opts))) {
+      throw new TypeError(
+        'EditorClient options must be an object. Use new EditorClient({ url: "http://127.0.0.1:20173" }), not new EditorClient("...").'
+      );
+    }
+    const unknownOptions = Object.keys(opts ?? {}).filter(
+      (key) => key !== "url" && key !== "onEnvelope" && key !== "transport"
+    );
+    if (unknownOptions.length > 0) {
+      throw new Error(
+        `EditorClient: unknown option${unknownOptions.length === 1 ? "" : "s"} ${unknownOptions.map((key) => `"${key}"`).join(", ")}. Use { url: "http://127.0.0.1:<port>" } to target an editor.`
+      );
+    }
+    this.baseUrl = (opts?.url ?? DEFAULT_URL).replace(/\/$/, "");
+    this.onEnvelope = opts?.onEnvelope ?? null;
+    this.transport = opts?.transport ?? null;
+    this.game = {
+      state: async (name) => {
+        const data = await this.command({
+          type: "inspect-gameplay-state",
+          keys: [name]
+        });
+        return data.state?.[name];
+      },
+      command: async (name, ...args) => (await this.command({ type: "invoke-debug-command", name, args })).result
+    };
+  }
+  /**
+   * `retryTransport` opts a command into ONE automatic retry after a transport
+   * failure (see {@link RETRYABLE_TRANSPORT_CODES}). It is deliberately
+   * OPT-IN and off by default: a socket that died after the request was written
+   * cannot prove the editor did not already run the command, so a blanket retry
+   * would risk playing/stopping/writing twice. Read-only relays — the captures —
+   * have no such hazard and turn it on.
+   */
+  async command(body, options) {
+    const type = String(body["type"] ?? "command");
+    const deadlineMs = options?.deadlineMs ?? COMMAND_DEADLINE_MS;
+    if (this.transport) {
+      const answered = await this.transport(body);
+      if (!answered.ok) {
+        throw new EditorCommandError(
+          answered.error ?? `Editor command "${type}" failed`,
+          answered.code
+        );
+      }
+      return answered;
+    }
+    const url = `${this.baseUrl}/__editor/command`;
+    const request = JSON.stringify(body);
+    let res;
+    let retried = false;
+    let commandDispatcher;
+    for (; ; ) {
+      try {
+        const init = {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: request,
+          signal: AbortSignal.timeout(deadlineMs)
+        };
+        commandDispatcher = deadlineMs > UNDICI_DEFAULT_HEADERS_TIMEOUT_MS ? createDispatcher(deadlineMs + 3e4) : void 0;
+        res = await dispatchFetch(url, init, commandDispatcher);
+        break;
+      } catch (error) {
+        await commandDispatcher?.destroy?.();
+        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\`.`,
+            void 0,
+            true
+          );
+        }
+        const { code, detail } = describeFetchFailure(error);
+        if (options?.retryTransport === true && !retried && RETRYABLE_TRANSPORT_CODES.has(code)) {
+          retried = true;
+          await new Promise((resolve3) => setTimeout(resolve3, TRANSPORT_RETRY_DELAY_MS));
+          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.",
+          code,
+          false
+        );
+      }
+    }
+    let data;
+    try {
+      data = await this.readJson(res);
+    } finally {
+      await commandDispatcher?.destroy?.();
+    }
+    if (!data.ok) {
+      throw new EditorCommandError(
+        data.error ?? `Editor command failed: ${res.status}`,
+        data.code,
+        // 504 is every `timedOut` result (`commandResponseFor`) — the relay
+        // gave up, on any of its five grounds. A 200 body with `ok: false` is
+        // an ANSWER from the editor, however unwelcome. See `timedOut` above.
+        res.status === 504
+      );
+    }
+    return data;
+  }
+  // --- Play control ---
+  /** `opts.seed` (D15/T-D15.6, objection-4 fix) — `vgai play --seed <n>`'s
+   *  explicit config leg, relayed as `cmd['seed']`; `handleCommand`'s
+   *  `'play'` case threads it into `enterPlayMode`'s highest-precedence seed
+   *  argument (beats manifest.determinism.defaultSeed/?vgai-seed=). Omitted,
+   *  boot seeding falls back to that precedence unchanged.
+   *
+   *  `opts.name` (`vgai play --name <text>`) — an OPTIONAL label for this run,
+   *  relayed as `cmd['name']` and slugified server-side into the run's
+   *  `logs/play-*.jsonl` filename and its session-journal line. Findability
+   *  only: no registry, no uniqueness, no lookup verb — grep and `ls` are the
+   *  query engine. Omitted, the filename keeps its exact unnamed shape. */
+  /*  `opts.record` (`vgai play --record <name>`) — NAMES this run's recording
+   *  file. It does not ENABLE recording: every relayed play records, with no
+   *  flag (see `@vgai/game`'s `src/play/play-recording.ts`). Omitted, the clip is named for
+   *  the durable Gameplay Session; named, it becomes an explicit keepsake in
+   *  `.vgai/recordings/<name>.webm`. */
+  async play(opts) {
+    return this.command({
+      type: "play",
+      ...opts?.seed !== void 0 ? { seed: opts.seed } : {},
+      ...opts?.name ? { name: opts.name } : {},
+      ...opts?.record ? { record: opts.record } : {}
+    });
+  }
+  /** Dispose the current play session and mount it again from fresh project entry source. */
+  async restart() {
+    await this.command({ type: "play" });
+  }
+  /** Stops play, and finalizes this run's recording before the surface it was
+   *  photographing is torn down. The capture is absent when nothing recorded. */
+  async stop() {
+    return this.command({ type: "stop" });
+  }
+  async pause() {
+    await this.command({ type: "pause" });
+  }
+  async resume() {
+    await this.command({ type: "resume" });
+  }
+  async step() {
+    await this.command({ type: "step" });
+  }
+  // --- Selection ---
+  async select(id) {
+    await this.command({ type: "select", id });
+  }
+  async selectMultiple(ids) {
+    await this.command({ type: "select-multiple", ids });
+  }
+  async selectAll() {
+    await this.command({ type: "select-all" });
+  }
+  // --- Viewport ---
+  async focusEntity(id) {
+    await this.command({ type: "focus-entity", id });
+  }
+  async focusSelection() {
+    await this.command({ type: "focus-selection" });
+  }
+  /**
+   * Frame the EDIT viewport camera on one entity — the strict sibling of
+   * {@link focusEntity}. Same framing; an id the scene does not know is a
+   * refusal naming the id (`EditorCommandError`, code `ENTITY_NOT_FOUND`)
+   * rather than `focusEntity`'s silent no-op, so a caller that frames an
+   * entity before capturing it cannot photograph the wrong thing.
+   */
+  async frameEntity(id) {
+    await this.command({ type: "frame-entity", id });
+  }
+  async viewPreset(preset) {
+    await this.command({ type: "view-preset", preset });
+  }
+  /**
+   * LOOK AROUND THE OPEN MODEL, visibly. Swings the active Object3D
+   * document's camera — the one on the human's screen — by `azimuth`/
+   * `elevation` radians, animated over `duration` seconds, and resolves when
+   * the move ends. A human drag during the move cancels it where it stands
+   * (`cancelledBy: 'human'`); the promise still resolves.
+   */
+  async orbitDocument(options) {
+    return this.command({ type: "document-orbit", ...options });
+  }
+  /** A slow full revolution around the open document's subject, at a constant rate. */
+  async turntableDocument(options) {
+    return this.command({ type: "document-turntable", ...options });
+  }
+  /**
+   * Frame the open document's subject (its selection if it has one). `fit`
+   * scales the fitted distance: 1 is the toolbar Frame button's tight fit.
+   */
+  async frameDocument(fit) {
+    return this.command({
+      type: "document-frame",
+      ...fit === void 0 ? {} : { fit }
+    });
+  }
+  async setCamera(position, target, fov) {
+    await this.command({
+      type: "set-camera",
+      position,
+      target,
+      ...fov === void 0 ? {} : { fov }
+    });
+  }
+  async captureViewport(size) {
+    const data = await this.command({
+      type: "capture-viewport",
+      ...size === void 0 ? {} : { size }
+    });
+    return { base64: data.base64, mimeType: data.mimeType };
+  }
+  /**
+   * Unit 4 (live-front-door wave) — capture the RUNNING GAME (`vgai
+   * screenshot`'s wire leg). Sends the SAME `bridge-screenshot` relay op
+   * `@vgai/live`'s `RelayTransport.screenshot` (and therefore
+   * `game.screenshot()` on the relay path) already sends, so all three
+   * surfaces composite the identical full game stack — canvas(es) plus the
+   * HUD/react DOM layers — rather than any of them inventing a second,
+   * subtly-different capture path. Contrast {@link captureViewport}, which
+   * captures the EDITOR viewport's canvas and would silently hand back an
+   * editor-only (HUD-less, possibly not-even-playing) image.
+   *
+   * Rejects — loudly, via `command`'s own `{ok:false}` unwrap — when play
+   * mode isn't running ("not in play mode — start play before using the
+   * debug seam") or no game canvas is mounted yet. Never returns a blank or
+   * editor-only frame as a stand-in.
+   *
+   * `opts.refreshStarvedFrame` is the loop-starvation leg: without recent rAF
+   * progress the canvas holds a provably stale frame and the relay
+   * refuses it with `BRIDGE_SCREENSHOT_STALE` rather than pass it off as
+   * current. Setting this asks the relay to render exactly ONE deterministic
+   * tick (`runTicks(1, {render:'last'})`) first — the same escape
+   * `@vgai/live`'s `RelayTransport.screenshot` has always used, which is why
+   * `vgai eval` could recover these frames while `vgai screenshot` could not.
+   * Off by default: a caller who does not ask must never be handed a frame
+   * that only exists because the capture drove the game.
+   */
+  async captureGame(opts) {
+    const data = await this.command({
+      type: "bridge-screenshot",
+      ...opts?.refreshStarvedFrame === true ? { refreshStarvedFrame: true } : {}
+    });
+    const layers = data.layers;
+    const flatness = data.flatness;
+    return {
+      base64: data.base64,
+      mimeType: data.mimeType,
+      composite: data.composite === true,
+      ...layers && Number.isInteger(layers.canvases) && Number.isInteger(layers.domOverlays) ? { layers } : {},
+      // Pass the pixel-honesty fields through as the page reported them: the
+      // warning sentence is written where the pixels are, so nothing here
+      // re-derives (or softens) it.
+      ...flatness && typeof flatness.dominantFraction === "number" ? { flatness } : {},
+      ...data.loopRecoveryFrame === true ? { loopRecoveryFrame: true } : {},
+      // Same pass-through rule: the recorded-run notice is written where the
+      // pixels are, so nothing here re-derives or softens it.
+      ...data.recording && typeof data.recording.notice === "string" ? { recording: data.recording } : {}
+    };
+  }
+  /** Start recording the same clean running-game composite `captureGame`
+   * photographs. Recording state lives in the editor page, so another process
+   * may stop it later through the same project session. */
+  async startGameplayRecording(options = {}) {
+    return this.command({
+      type: "bridge-recording-start",
+      ...options.fps !== void 0 ? { fps: options.fps } : {},
+      ...options.name !== void 0 ? { name: options.name } : {},
+      ...options.format !== void 0 ? { format: options.format } : {}
+    });
+  }
+  /** Export a paused run as fixed-step video. Advances game state; maximum
+   * five minutes. `audio` describes the muxed track, or is `false` when the
+   * world implements no `AudioAdapter.renderOffline` and the file is
+   * genuinely silent — read it, never assume either. */
+  async exportGameplayVideo(options) {
+    return this.command(
+      { type: "bridge-recording-export", ...options },
+      { deadlineMs: 61e4, retryTransport: false }
+    );
+  }
+  /** Stop the page-owned recorder and return its WebM path and metadata. */
+  async stopGameplayRecording() {
+    return this.command({ type: "bridge-recording-stop" });
+  }
+  /** Read the active capture's monotonic media position. This is the only clock
+   * suitable for selecting intervals inside the finalized recording. */
+  async getGameplayRecordingTimeline() {
+    const timeline = await this.command({
+      type: "bridge-recording-timeline"
+    });
+    return { startedAt: timeline.startedAt, elapsedMs: timeline.elapsedMs };
+  }
+  /** Encode a recorded canvas/DOM interval into a normal composite WebM. */
+  async exportGameplayReplay(options) {
+    return this.command(
+      { type: "bridge-recording-replay-export", ...options },
+      { deadlineMs: 61e4, retryTransport: false }
+    );
+  }
+  async captureGameplayReplay(replayPath, positionMs) {
+    return this.command({
+      type: "bridge-recording-replay-capture",
+      replayPath,
+      positionMs
+    });
+  }
+  /**
+   * Capture an isolated, deterministic four-view preview through the editor's
+   * native Asset Lab. The SDK delegates rendering to the editor; it never
+   * loads, clones, or interprets Three.js assets itself.
+   */
+  async captureAssetPreview(source, options = {}) {
+    const data = await this.command(
+      {
+        type: "capture-asset-preview",
+        ...source,
+        ...options
+      },
+      // Photographing changes nothing, and this is the relay `vgai screenshot
+      // <module>` / `project.bake.preview` rides — the lane where a momentary
+      // transport failure cost a cold agent three probe modules.
+      { retryTransport: true }
+    );
+    return {
+      width: data.width,
+      height: data.height,
+      // Absent from editors that predate orientation reporting.
+      ...data.orientation ? { orientation: data.orientation } : {},
+      views: data.views,
+      contactSheet: data.contactSheet
+    };
+  }
+  /**
+   * A project-defined labeled shot set (`vgai screenshot <target> --shots <set>`):
+   * the DEFINITION travels with the command (project data — see
+   * `AssetPreviewShotSetDefinition`; the CLI resolves it from the registered
+   * `project.<set>.previewShots` tool), and the editor's generic
+   * capture engine renders it — see `packages/editor/src/asset-preview.ts`'s
+   * `captureShotSetAssetPreview`. Throws (via `command`'s `{ok:false}`
+   * unwrap) with a clear message naming the missing joint(s) when the asset
+   * lacks a bone the definition requires.
+   */
+  async captureShotSetPreview(source, definition, options = {}) {
+    const data = await this.command(
+      {
+        type: "capture-asset-preview",
+        ...source,
+        ...options,
+        shotSet: definition
+      },
+      { retryTransport: true }
+    );
+    return {
+      width: data.width,
+      height: data.height,
+      shots: data.shots,
+      // An older editor predates the empty-frame guard and sends none.
+      warnings: data.warnings ?? [],
+      contactSheet: data.contactSheet
+    };
+  }
+  /**
+   * B8.4 — score the asset against a reference GLB (`vgai screenshot
+   * <model.glb> --compare <ref.glb>`): matched orthographic front + side silhouettes
+   * (equal-height bounding-box framing, both yaw-normalized to face the
+   * camera), per-view IoU numbers, and overlay evidence images. The
+   * reference GLB's raw bytes travel base64 in the command; the editor
+   * renders and scores — the SDK never interprets Three.js assets itself.
+   */
+  async captureAssetComparePreview(source, refGlbBase64, options = {}) {
+    const { refForward, ...dimensions } = options;
+    const data = await this.command({
+      type: "capture-asset-preview",
+      ...source,
+      ...dimensions,
+      compare: { glbBase64: refGlbBase64, ...refForward ? { forward: refForward } : {} }
+    });
+    return { width: data.width, height: data.height, views: data.views };
+  }
+  /**
+   * The STORY lane (`vgai screenshot <file>.stories.tsx`): every CSF export of
+   * one project story file rendered in the live session's DOM and captured
+   * through the same composite leg {@link captureGame} uses, returned as
+   * per-export images plus one variant sheet. `options.story` narrows to a
+   * single export.
+   *
+   * Rendering happens in the EDITOR — the SDK never imports, composes or
+   * mounts a CSF module itself; the session already owns that machinery for
+   * its Stories panel and this drives it.
+   */
+  async captureStoryVariants(modulePath, options = {}) {
+    const data = await this.command({
+      type: "capture-story-variants",
+      modulePath,
+      ...options
+    });
+    return {
+      modulePath: data.modulePath,
+      width: data.width,
+      height: data.height,
+      variants: data.variants,
+      contactSheet: data.contactSheet
+    };
+  }
+  // --- Panels ---
+  async showViewport(tab) {
+    await this.command({ type: "viewport-tab", tab });
+  }
+  /** Focus a static workspace panel by the key the editor's panel registry
+   *  holds; an unknown key refuses naming the keys it does hold. */
+  async showPanel(panel) {
+    await this.command({ type: "show-panel", panel });
+  }
+  /** Show several instances of the running game split-screen — multiplayer
+   *  authoring. Pass a total `count` (default "Player N" labels) or an array of
+   *  `names` (its length is the count; index 0 is the primary). Requires a live
+   *  play session. */
+  async setInstanceCount(countOrNames) {
+    await this.command(
+      Array.isArray(countOrNames) ? { type: "set-instance-count", names: countOrNames } : { type: "set-instance-count", count: countOrNames }
+    );
+  }
+  async openAsset(path, kind) {
+    await this.command({ type: "open-asset-tab", path, kind });
+  }
+  /** SELECT a project asset — the other half of the browser's
+   *  selection-vs-open contract (single click selects and fills the
+   *  Inspector; double click opens a document). */
+  async selectAsset(path) {
+    await this.command({ type: "select-asset", path });
+  }
+  async closeAsset(key) {
+    await this.command({ type: "close-asset-tab", key });
+  }
+  async toggleCommandPalette() {
+    await this.command({ type: "toggle-command-palette" });
+  }
+  async toggleConsole() {
+    await this.command({ type: "toggle-console" });
+  }
+  /** Switch the editor's NAMED WORKSPACE — the task-named layout memory
+   *  (`game`/`model`/`sculpt`/`texture`/`animate`/`look`). Resolves once the
+   *  dock has finished rebuilding, so a following capture photographs the
+   *  arrangement that was asked for. */
+  async setWorkspace(workspace) {
+    await this.command({ type: "set-workspace", workspace });
+  }
+  /** 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`). */
+  async setStyle(style) {
+    await this.command({ type: "set-style", style });
+  }
+  /** Set the MATERIAL apart from the bundle that usually carries it.
+   *  Answers with what the chrome wears afterwards. */
+  async setAppearance(appearance) {
+    return this.command({
+      type: "set-appearance",
+      ...appearance
+    });
+  }
+  async showBuild() {
+    await this.command({ type: "show-build" });
+  }
+  /** Atomically present a durable editor view and return its shareable URL. */
+  async present(view) {
+    const presented = await this.command({ type: "present-view", view });
+    return { view: presented.view, url: presented.url, warnings: presented.warnings };
+  }
+  /**
+   * The INSPECTION SUBJECT the editor is showing right now, as data — the
+   * serialized projection of the inspection model (design:
+   * `docs/ARCHITECTURE-CORE.md` §Editor chrome, "The Inspection Model").
+   *
+   * The same subject a human reads in the inspector: identity, presentation,
+   * verbs, and the identified sections in display order — with a `fields`
+   * section's CURRENT VALUES read through the same io the field rows edit
+   * through. With nothing selected it answers the active surface's own
+   * no-selection subject when it has one, exactly as the panel does; it never
+   * reports another surface's, and when the panel itself is unmounted it
+   * answers `{none: true}` rather than a subject nobody is looking at. A
+   * `custom` section body is a named opaque (`{kind, id, title}`) — the editor
+   * renders those with React — plus its displayed values under `data` when it
+   * has any (the Transform section's position/rotation/scale).
+   */
+  async inspect() {
+    const data = await this.command({ type: "inspect" });
+    return data.subject;
+  }
+  /** Run one verb exposed by the active Inspector subject, by its id. */
+  async runInspectionAction(actionId) {
+    const data = await this.command({
+      type: "run-inspection-action",
+      actionId
+    });
+    return data.subject;
+  }
+  /**
+   * Run ONE command by id — the door to everything the command palette lists.
+   *
+   * Under the Code-OSS frame this is the workbench's own `ICommandService`, so
+   * any command id works: a view's `vgai.<view>.<verb>`, an editor action's
+   * `vgai.action.<id>`, or one of VS Code's own. Standalone `vgai edit` has no
+   * command service and answers the `vgai.<view>.<verb>` shape directly off
+   * the views registry, refusing anything else BY NAME.
+   *
+   * The result is whatever the command answered — a view verb's state, or
+   * `null` for a command that returns nothing.
+   */
+  async runCommand(commandId, args) {
+    const data = await this.command({
+      type: "run-command",
+      commandId,
+      ...args === void 0 ? {} : { args }
+    });
+    return data.result;
+  }
+  /**
+   * One STRUCTURE op on the authored tree — the hierarchy context menu's own
+   * verbs, on the same helpers, for a caller with no pointer to right-click
+   * with. `id`/`ids` default to the current selection.
+   */
+  async structureOp(op, options = {}) {
+    return this.command({ type: "structure-op", op, ...options });
+  }
+  /** "Extract Component…" — the hierarchy row's action, as a command. Answers
+   *  the action's own sentence, which NAMES the files it created. */
+  async extractComponent(options = {}) {
+    return this.command({ type: "extract-component", ...options });
+  }
+  /** "Fork Component…" — extract's twin: one new file, one callsite retargeted. */
+  async forkComponent(options = {}) {
+    return this.command({ type: "fork-component", ...options });
+  }
+  /**
+   * The HIERARCHY PANEL's actual rendered row tree, as data.
+   *
+   * The same rows a human is looking at: the adapter's tree after the component
+   * marks fold implementation subtrees, after the internals reveal, after the
+   * document promotion, the child cap, the collapse state, the search filter
+   * and the selection scope. Works in play mode and edit mode alike — the
+   * answer reports which (`playState`, `activeViewportTab`), because a
+   * play-mode tree and an edit-mode tree come from different adapters.
+   *
+   * Deliberately NOT `status().entities`, which walks the raw adapter tree and
+   * therefore answers a different question: a panel defect is invisible in it.
+   *
+   * Each row carries `childCount` (what its caret opens), `internalChildCount`
+   * (what is folded behind "Reveal Internals") and `expandable` (whether the
+   * panel draws a caret at all) — so "this subtree exists but the UI offers no
+   * way to open it" is a readable fact rather than something only a human
+   * squinting at the panel can notice.
+   *
+   * Rejects, naming the panel, when no hierarchy panel is mounted: an empty
+   * tree would be a fabricated answer about a surface nobody is being shown.
+   */
+  async hierarchy() {
+    const data = await this.command({ type: "hierarchy" });
+    return data.hierarchy;
+  }
+  /** Run the Hierarchy panel's own Expand All action. */
+  async expandHierarchyAll() {
+    await this.command({ type: "expand-hierarchy-all" });
+  }
+  /** Run the Hierarchy panel's own Collapse All action — Expand All's other
+   *  half, and the only way back to the tree's rest state through the product
+   *  (see `HierarchyPanelSnapshot.collapseAll`). */
+  async collapseHierarchyAll() {
+    await this.command({ type: "collapse-hierarchy-all" });
+  }
+  /**
+   * Write one editable path through the active Inspector's own IO.
+   *
+   * The answer carries `write` as well as the subject, because an ack alone
+   * cannot be believed: a write with no persistence route open succeeds and
+   * changes no byte, and `write.persisted` is how the caller tells the two
+   * apart without diffing the tree (`InspectedWriteDestination` in `types.ts`).
+   */
+  async setInspectionField(path, value) {
+    const data = await this.command({
+      type: "set-inspection-field",
+      path,
+      value
+    });
+    return { subject: data.subject, write: data.write };
+  }
+  /**
+   * REMOVE one editable path's authored override — the other half of the write
+   * door, and the only one that can express byte-ABSENCE.
+   *
+   * {@link setInspectionField} writes a VALUE, so reverting a property an
+   * authoring gesture ADDED puts the default back EXPLICITLY and leaves the
+   * source one attribute heavier than it started. This drops the property, so
+   * whatever governs it in its absence takes over — the same `io.remove` the
+   * Inspector's revert arrow calls, the same persistence pipe, the same awaited
+   * `{ destination, persisted }` ack.
+   *
+   * Rejects with `code: 'REMOVAL_UNAVAILABLE'` when the field does not declare
+   * itself removable or the lane implements no removal door. That refusal is a
+   * MISSING SEAM, not a failed removal, and it is coded rather than phrased
+   * precisely so a caller can grade the two differently.
+   */
+  async removeInspectionField(path) {
+    const data = await this.command({
+      type: "remove-inspection-field",
+      path
+    });
+    return { subject: data.subject, write: data.write };
+  }
+  /**
+   * OPEN one piece of the adapter's SCENE TABLE by id — a scene, a prefab, or
+   * a story state, because the table makes them siblings (they differ only in
+   * instance site). The ids are exactly what `getState().adapter.scenes.entries`
+   * reports, so the table is both the menu and the address space.
+   *
+   * With a game LIVE in the session, opening a scene the adapter declares
+   * reachable through that game's own scenes contract NAVIGATES it — the same
+   * switch the editor's own scene picker makes — and the answer carries the
+   * game's own reading (`scene`).
+   *
+   * Rejects with a coded reason rather than prose: `SCENE_NOT_FOUND` (and it
+   * names the ids that DO exist), `SCENE_NOT_OPENABLE` carrying the adapter's
+   * own declared reason for a scene it says nothing can reach,
+   * `SCENE_NAVIGATION_NOT_RUNNING` for a live-only scene with no game running,
+   * `SCENE_CONTRACT_UNAVAILABLE` / `SCENE_NOT_IN_CONTRACT` (naming the ids the
+   * game itself publishes) / `SCENE_SWITCH_FAILED` when the running game's own
+   * navigation cannot take it, `SCENE_NOT_OPENABLE_LIVE` when this session has
+   * no remount for a native swap-slot scene,
+   * `SCENE_TABLE_UNAVAILABLE` before the adapter has loaded, and
+   * `SCENE_DOCUMENT_NOT_MOUNTED` when the host has no document for a piece the
+   * table says is openable — a host gap, not a table statement.
+   */
+  async open(id) {
+    return this.command({ type: "open", id });
+  }
+  /**
+   * Undo / redo one project transaction — the same queue the keyboard shortcut
+   * drives. `moved` is false when there was nothing left in that direction.
+   */
+  async undo() {
+    return this.command({ type: "undo" });
+  }
+  async redo() {
+    return this.command({ type: "redo" });
+  }
+  /** Read the editor's actual current durable projection. */
+  async currentView() {
+    const data = await this.command({ type: "current-view" });
+    return data.view;
+  }
+  /**
+   * Capture the active center document exactly as presented to the user.
+   *
+   * A number is a SQUARE of that size (the default shape); `{width, height}`
+   * asks for a shaped frame — a video-aspect look that needs no crop. Both are
+   * bounded by the relay budget; see {@link CaptureDimensions}.
+   */
+  /** Photograph the editor PAGE itself — every panel as the person sees it, at
+   *  `scale` output pixels per CSS pixel (default `devicePixelRatio`), which is
+   *  what a 1 px border or a glyph edge is judged through. */
+  async captureEditorChrome(options) {
+    return this.command({
+      type: "capture-editor-chrome",
+      ...options?.scale === void 0 ? {} : { scale: options.scale }
+    });
+  }
+  /** With a view, present and capture it in one request so document discovery
+   * cannot retarget the capture between two client calls. */
+  async captureActiveDocument(size, view) {
+    return this.command({
+      type: "capture-active-document",
+      ...view ? { view } : {},
+      ...typeof size === "number" ? { size } : {},
+      ...typeof size === "object" && size !== null ? { width: size.width, height: size.height } : {}
+    });
+  }
+  /**
+   * Read or drive the ACTIVE center document's own DOM — the scoped
+   * editor-chrome door, and the read/gesture half of the same subject
+   * {@link captureActiveDocument} photographs. NOT play-mode gated, and NOT
+   * page automation: a target outside the active document's container is
+   * refused by name. Design and scope contract:
+   * `packages/editor/src/editor-document-probe.ts`.
+   */
+  async documentProbe(step) {
+    return this.command({ type: "document-probe", step });
+  }
+  /**
+   * Run a wire-carried step against the ACTIVE document's published context
+   * (`packages/editor/src/document-context-registry.ts`) — the REPL door over
+   * an open document, in Edit mode. `src` is the step's own `toString()`;
+   * same serialization contract as `page-script` (no closures survive).
+   */
+  /**
+   * The Blender lane's doors (`blender-execute`, `blender-scene-info`,
+   * `blender-object-info`, `blender-screenshot-view`, `blender-read-file`,
+   * `blender-write-file`, `blender-list-files`, `blender-start`,
+   * `blender-status`): Blender runs in the editor tab's worker, and
+   * `vgai blender-mcp` is transport onto these. `blender-status` is the only
+   * one that creates nothing — it answers whether this tab already has a
+   * session, which is how a caller survives an editor restart.
+   */
+  async blender(type, fields = {}) {
+    return this.command({ type, ...fields }, { deadlineMs: BLENDER_DEADLINE_MS });
+  }
+  async documentScript(src) {
+    const outcome = await this.command({ type: "document-script", src });
+    return outcome.result;
+  }
+  // --- Display (set semantics) ---
+  async setGrid(enabled) {
+    await this.command({ type: "set-grid", enabled });
+  }
+  async setHelpers(enabled) {
+    await this.command({ type: "set-helpers", enabled });
+  }
+  async setStats(enabled) {
+    await this.command({ type: "set-stats", enabled });
+  }
+  async setShadingMode(mode) {
+    await this.command({ type: "set-shading-mode", mode });
+  }
+  async setHelperType(helperType, enabled) {
+    await this.command({ type: "set-helper-type", helperType, enabled });
+  }
+  // --- Transform tools (set semantics) ---
+  async setTransformMode(mode) {
+    await this.command({ type: "set-transform-mode", mode });
+  }
+  async setTransformSpace(space) {
+    await this.command({ type: "set-transform-space", space });
+  }
+  async setSnap(enabled) {
+    await this.command({ type: "set-snap", enabled });
+  }
+  // --- Project management ---
+  async createProject(name, location, template = "default", exampleId) {
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/create-project`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name, location, template, ...exampleId ? { exampleId } : {} })
+    });
+    const data = await this.readJson(res);
+    if (!res.ok) {
+      throw new Error(data.error ?? `Create project failed: ${res.status}`);
+    }
+    return { path: data.path, config: data.config };
+  }
+  async openProject(path) {
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/open-project`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ path })
+    });
+    const body = await this.readJson(res);
+    if (!res.ok) {
+      throw new Error(body.error ?? `Open project failed: ${res.status}`);
+    }
+  }
+  async getProject() {
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/project`);
+    const data = await this.readJson(res);
+    if (!res.ok) throw new Error(data.error ?? `Failed to get project: ${res.status}`);
+    return data.project;
+  }
+  async listRecentProjects() {
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/recent-projects`);
+    const data = await this.readJson(res);
+    if (!res.ok) throw new Error(data.error ?? `Failed to list projects: ${res.status}`);
+    return data.projects;
+  }
+  // --- Registered project tools ---
+  /** List tools explicitly registered in `package.json#vgai.tools`.
+   * The editor server loads callable metadata in Node; modules never enter the
+   * editor browser merely because they were listed. */
+  async listProjectTools() {
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/project-tools`);
+    const body = await this.readJson(res);
+    if (!res.ok) throw new Error(`Failed to list project tools: ${res.status}`);
+    return body;
+  }
+  /** Execute one Node-hosted project tool through the shared validated
+   * dispatcher. Write/destructive tools require `confirm:true`. */
+  async runProjectTool(name, input = {}, options = {}) {
+    const dispatcher = createDispatcher(0);
+    try {
+      const res = await this.httpFetch(
+        `${this.baseUrl}/__editor/project-tools/run`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            name,
+            input,
+            confirm: options.confirm === true,
+            // Omitted (not null) when unset — the wire body is JSON and the tool
+            // host reads absence as "the sole instance", same convention as the
+            // relay's `instance`.
+            ...options.instance !== void 0 ? { instance: options.instance } : {}
+          })
+        },
+        dispatcher
+      );
+      const body = await this.readJson(res);
+      if (!body || typeof body !== "object" || typeof body.ok !== "boolean") {
+        throw new Error(`Project tool returned an invalid response (${res.status}).`);
+      }
+      return body;
+    } finally {
+      await dispatcher?.destroy?.();
+    }
+  }
+  // --- First-party generation job activity ---
+  /** Read the one project-local generation job ledger. Provider-native
+   * request/result shapes remain on their registered operations. */
+  async listGenerationJobs() {
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/generations`);
+    const body = await this.readJson(res);
+    if (!res.ok) throw new Error(`Failed to list generation jobs: ${res.status}`);
+    return body;
+  }
+  /** Forget operational job state. Accepted provenance and project assets
+   * are deliberately unaffected. */
+  async forgetGenerationJob(id) {
+    const res = await this.httpFetch(
+      `${this.baseUrl}/__editor/generations/${encodeURIComponent(id)}`,
+      {
+        method: "DELETE"
+      }
+    );
+    const body = await this.readJson(res);
+    if (!res.ok) throw new Error(body.error ?? `Failed to forget generation job: ${res.status}`);
+    return body.removed === true;
+  }
+  // --- Logs ---
+  async getLogEntries() {
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/log-entries`);
+    const data = await this.readJson(res);
+    if (!res.ok) return [];
+    return data.entries;
+  }
+  // --- State ---
+  /**
+   * The document table the host resolved — every scene, prefab, page, model,
+   * shot, take … the project's finders produced (`getState().adapter.scenes`
+   * is the same projection). A command, so it answers wherever the control
+   * channel reaches, not only where `/__editor/state` is served.
+   */
+  async documentTable() {
+    return this.command({ type: "document-table" });
+  }
+  async getState() {
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/state`);
+    const state = await this.readJson(res);
+    if (!res.ok) throw new Error(`Failed to get editor state: ${res.status} ${res.statusText}`);
+    return state;
+  }
+  /**
+   * The complete unresolved console set the session is holding right now.
+   *
+   * Command envelopes only carry COUNTS (`unresolvedConsole` on
+   * `commandResponseFor`). The named conditions live on GET `/__editor/console`.
+   * This is the method that turns "a command that exits before an envelope
+   * arrives" into a real reading: the CLI calls it at start and at exit
+   * through the same {@link onEnvelope} observer every other response uses.
+   * A session that does not answer within {@link CONSOLE_DRAIN_TIMEOUT_MS} is
+   * a thrown error the caller treats as "nothing learned", never a hang.
+   */
+  async getUnresolvedConsole(opts) {
+    const res = await this.httpFetch(
+      `${this.baseUrl}/__editor/console${opts?.all === true ? "?all=1" : ""}`,
+      { signal: AbortSignal.timeout(CONSOLE_DRAIN_TIMEOUT_MS) }
+    );
+    if (!res.ok) {
+      throw new Error(`Failed to read unresolved console: ${res.status}`);
+    }
+    return await this.readJson(res, true);
+  }
+  /** Acknowledge one named console condition. The response is observed and
+   *  hydrated through the same path as every other client response. */
+  async acknowledgeConsole(input) {
+    const res = await this.httpFetch(`${this.baseUrl}/__editor/console/ack`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(input),
+      signal: AbortSignal.timeout(CONSOLE_DRAIN_TIMEOUT_MS * 4)
+    });
+    const body = await this.readJson(res);
+    return body;
+  }
+  /**
+   * `fetch` for this client's plain routes, with the ONE thing Node's `fetch`
+   * will not do: name why it failed.
+   *
+   * `readJson` below already owns "the server answered the wrong thing"; this
+   * owns "nothing answered at all", which used to reach the caller as the bare
+   * `TypeError: fetch failed` with the real code buried on `.cause`. No retry
+   * here — these routes create projects, run tools and acknowledge console
+   * conditions, so repeating one is the caller's decision. The relayed
+   * `command` path above has its own opt-in retry for the read-only captures.
+   */
+  async httpFetch(url, init, dispatcher) {
+    try {
+      return await dispatchFetch(url, init, dispatcher);
+    } catch (error) {
+      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.`,
+        code,
+        false
+      );
+    }
+  }
+  /** Parse one JSON body and hand it to {@link onEnvelope}.
+   *
+   * A command/state envelope carries current counts but not the named set. If
+   * an observer is installed, do the bounded console GET before resolving the
+   * original request. That makes a subsequent `process.exit()` safe: the
+   * observer has already received every condition and occurrence count. */
+  async readJson(res, consoleComplete = false) {
+    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.`
+      );
+    }
+    const body = await res.json();
+    this.observe(body, { unresolvedConsoleComplete: consoleComplete });
+    if (this.onEnvelope !== null && !consoleComplete && body !== null && typeof body === "object" && "unresolvedConsole" in body) {
+      try {
+        const consoleRes = await this.httpFetch(`${this.baseUrl}/__editor/console`, {
+          signal: AbortSignal.timeout(CONSOLE_DRAIN_TIMEOUT_MS)
+        });
+        if (consoleRes.ok) {
+          const consoleBody = await consoleRes.json();
+          this.observe(consoleBody, { unresolvedConsoleComplete: true });
+        }
+      } catch {
+      }
+    }
+    return body;
+  }
+  /** Hand one response body to {@link onEnvelope}, never letting it throw. */
+  observe(body, observation) {
+    if (this.onEnvelope === null) return;
+    try {
+      this.onEnvelope(body, observation);
+    } catch {
+    }
+  }
+  /**
+   * Whether an editor browser tab is connected to the server *right now*.
+   * Unlike {@link getState}, this reflects live SSE connections, not cached
+   * state — use it to check whether commands will actually reach an editor.
+   */
+  async isConnected() {
+    const state = await this.getState();
+    return state.connected === true;
+  }
+  async waitForState(predicate, timeoutMs = 1e4) {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      const state = await this.getState();
+      if (predicate(state)) return state;
+      await new Promise((r) => setTimeout(r, 100));
+    }
+    throw new Error(`waitForState timed out after ${timeoutMs}ms`);
+  }
+};
+
+// src/editor-document.ts
+var LiveEditorDocument = class {
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /**
+   * Read matching elements inside the active document: tag, text, attributes,
+   * value/checked/disabled and rect. `matched` is the total before `limit`.
+   *
+   * `styles` additionally resolves named properties per match — and resolving
+   * is the point, because a theme token is an expression until an element
+   * paints it. Ask for the standard property to learn the colour a person
+   * sees; ask for a `--vgai-…` custom property to learn what a rule WOULD
+   * paint, which is the only way to measure a `:hover` colour (`:hover` is a
+   * browser state no synthetic event can enter, so there is deliberately no
+   * hover verb on this door).
+   *
+   *   await editor.document.query('.vgai-tree-row', {
+   *     styles: ['backgroundColor', '--vgai-widget-regular-hover'],
+   *   });
+   */
+  async query(selector, options) {
+    return this.#probe({
+      action: "query",
+      selector,
+      ...options?.scope === void 0 ? {} : { scope: options.scope },
+      ...options?.limit === void 0 ? {} : { limit: options.limit },
+      ...options?.styles === void 0 ? {} : { styles: [...options.styles] }
+    });
+  }
+  /** A REAL pointer gesture (pointerdown/mousedown/focus/pointerup/mouseup/click)
+   *  — not `element.click()`, which a `pointerdown` listener never sees. */
+  async click(selector, options) {
+    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 }
+    });
+  }
+  /**
+   * TYPE into a field and commit with Enter, the way a person does — one
+   * character at a time through the prototype's value setter, between real
+   * `keydown`/`keyup`.
+   *
+   * `paste` is not a substitute: an untrusted `ClipboardEvent` performs no
+   * default action, so a plain `<input>` with no paste handler keeps its old
+   * value. Omit `selector` to type into whatever inside the scope has focus —
+   * which is what a rename field is, one gesture after
+   * `click(row, { clicks: 2 })`.
+   */
+  async type(text, options) {
+    return this.#probe({ action: "type", text, ...options ?? {} });
+  }
+  /**
+   * A real pointer DRAG across one matched element — press at `from`, move,
+   * release at `to`. The gesture a direct-manipulation canvas needs; a
+   * zero-length drag is a click at that fraction, which `click` (always the
+   * center) cannot place.
+   *
+   * `from`, `to` and every point in `via` are `[x, y]` FRACTIONS OF THE
+   * MATCHED ELEMENT'S BOX, 0..1 from its top-left — NEVER pixels and never
+   * page coordinates. `[0.5, 0.5]` is its center, `[1, 0]` its top-right.
+   * Compute a pixel target by measuring the element first: `query` answers
+   * its `rect`, and `(px - rect.x) / rect.width` is the fraction to pass.
+   */
+  async drag(selector, options) {
+    return this.#probe({
+      action: "drag",
+      selector,
+      ...options.scope === void 0 ? {} : { scope: options.scope },
+      from: options.from,
+      to: options.to,
+      ...options.via === void 0 ? {} : { via: options.via },
+      ...options.steps === void 0 ? {} : { steps: options.steps },
+      ...options.index === void 0 ? {} : { index: options.index },
+      ...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 }
+    });
+  }
+  /** A real keydown/keyup on the target, or on whatever inside the document has focus. */
+  async key(key, options) {
+    return this.#probe({ action: "key", key, ...options ?? {} });
+  }
+  /** A real `ClipboardEvent` carrying `text/plain` — the gesture nothing else
+   *  in the product can produce. */
+  async paste(text, options) {
+    return this.#probe({ action: "paste", text, ...options ?? {} });
+  }
+  /**
+   * Choose `value` on a `<select>` — a native dropdown's options are drawn by
+   * the OS, so `click` has nothing in the document to resolve, and a plain
+   * `element.value =` is invisible to React. Set through the prototype's own
+   * value setter plus `input`/`change`; `value` is the option's `value`, not
+   * its label. An unknown value is refused with the options it does offer.
+   */
+  async select(selector, value, options) {
+    return this.#probe({
+      action: "select",
+      selector,
+      value,
+      ...options?.scope === void 0 ? {} : { scope: options.scope },
+      ...options?.index === void 0 ? {} : { index: options.index }
+    });
+  }
+  /**
+   * THE REPL over the open document: run `step` in the editor page against the
+   * object the ACTIVE document published as its context (the mesh document
+   * publishes its `MeshEditSession`, whose `ctx` is the bpy-shaped edit
+   * context — `ctx.ops.mesh.bevel({ offset: 0.1 })`, `ctx.selection`,
+   * `ctx.history`, `session.commit()`). Edit mode, no play. Serialized like
+   * `game.page`: the step's own source travels, so inline every value it
+   * needs and return plain data.
+   */
+  async run(step) {
+    return this.#client.documentScript(step.toString());
+  }
+  #probe(step) {
+    return this.#client.documentProbe(step);
+  }
+};
+
+// src/editor.ts
+var EXTENSION_KIND = {
+  ".glb": "model",
+  ".gltf": "model",
+  ".png": "image",
+  ".jpg": "image",
+  ".jpeg": "image",
+  ".webp": "image",
+  ".gif": "image",
+  ".svg": "image",
+  ".hdr": "image",
+  ".exr": "image",
+  ".mp4": "video",
+  ".webm": "video",
+  ".mp3": "audio",
+  ".ogg": "audio",
+  ".wav": "audio",
+  ".flac": "audio",
+  ".glsl": "source",
+  ".vert": "source",
+  ".frag": "source",
+  // PROJECT SCRIPTS ARE SOURCE. Without these the guess below falls through to
+  // `'json'`, the asset-document router sends the file to the generic JSON
+  // viewer (`asset-documents.tsx#assetDocumentViewerRoute`: `spec.kind ===
+  // 'json'` is decided before any content routing), and the LIVE MODELING
+  // DOCUMENT never mounts — `editor.openAsset('src/lib/fox/fox.model.ts')`
+  // silently shows a text pane instead of the model. Only `kind: 'source'`
+  // reaches `SourceAssetViewer`, which is what content-routes a project script
+  // to `LiveModuleDocument`. The set matches that viewer's own
+  // `isProjectScriptPath` regex, `/\.(?:[cm]?[jt]sx?)$/`.
+  ".ts": "source",
+  ".tsx": "source",
+  ".mts": "source",
+  ".cts": "source",
+  ".js": "source",
+  ".jsx": "source",
+  ".mjs": "source",
+  ".cjs": "source"
+};
+function inferAssetKind(path) {
+  if (path.endsWith(".prefab.json")) return "prefab";
+  const dot = path.lastIndexOf(".");
+  const ext = dot >= 0 ? path.slice(dot).toLowerCase() : "";
+  return EXTENSION_KIND[ext] ?? "json";
+}
+var LiveEditor = class {
+  /** `#`-private, not `private`: `volter-editor eval --list` enumerates this object's
+   *  real runtime members, and TypeScript's erased `private` would leave the
+   *  raw `EditorClient` advertised beside them. */
+  #client;
+  /**
+   * The ACTIVE center document's own DOM: read it, click it, key it, paste
+   * into it. The one door onto editor chrome that is not play-mode gated, and
+   * deliberately scoped to that document alone —
+   * `packages/editor/src/editor-document-probe.ts` carries the design and the
+   * refusal contract. Screenshotting the same subject is
+   * {@link LiveEditor.captureActiveDocument}, not a fifth verb here.
+   */
+  document;
+  constructor(client) {
+    this.#client = client;
+    this.document = new LiveEditorDocument(client);
+  }
+  /**
+   * THE BLENDER LANE'S VERBS, from `volter-editor eval`.
+   *
+   * Blender runs headless in the editor tab's worker (ARCHITECTURE-CORE, "THE
+   * BLENDER IN THE TAB IS BLENDER") and answers `blender-start`,
+   * `blender-execute`, `blender-scene-info`, `blender-object-info`,
+   * `blender-screenshot-view`, `blender-read-file`, `blender-write-file`,
+   * `blender-list-files`, `blender-stop` and `blender-status`. They were
+   * reachable from `@volter/editor-sdk` and through `vgai blender-mcp` but from
+   * no GENERAL door, so driving a session meant writing an MCP client script
+   * 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))' })"
+   *
+   * `blender-status` is the only verb that creates nothing: it answers whether
+   * this tab already has a session without starting one.
+   */
+  async blender(type, fields = {}) {
+    return this.#client.blender(type, fields);
+  }
+  /**
+   * The active authoring adapter's persistence destination — where a save would
+   * land (`status().savePath`). A read only: a three root has no scene document
+   * to open, and its root is activated instead.
+   */
+  async scene() {
+    const state = await this.#client.getState();
+    return state.savePath;
+  }
+  /**
+   * Make the connected human editor show the same subject/view as the agent.
+   * The returned URL is a compact, shareable projection — not a serialized
+   * workspace or document payload.
+   */
+  async present(view) {
+    return this.#client.present(view);
+  }
+  /** The human editor's actual active document, selection, camera and utility. */
+  async currentView() {
+    return this.#client.currentView();
+  }
+  /**
+   * Capture the same center document the human is currently looking at.
+   *
+   * A number is a SQUARE of that size — the default, and the right shape for
+   * an unstaged look at a model. `{width, height}` asks for a shaped frame, so
+   * a video-aspect look needs no crop afterwards. Both are bounded by the
+   * relay budget (64-1024 per side, total no larger than a 1024 square); see
+   * `@volter/editor-sdk`'s `CaptureDimensions`.
+   * Supply a view to present and photograph it in one editor request.
+   */
+  async captureActiveDocument(size, view) {
+    return this.#client.captureActiveDocument(size, view);
+  }
+  /**
+   * Photograph the editor PAGE — every panel, tab strip and viewport as the
+   * person sees it. `vgai screenshot editor` is this verb from the shell. The
+   * one door for judging chrome sighted: a skin, a workspace arrangement or a
+   * contributed panel is looked at through this, never guessed at from DOM
+   * probes. The page at its own layout, `scale` output pixels per CSS pixel
+   * (default `devicePixelRatio`) — a 1 px border or a glyph stroke is only
+   * judgeable at the scale the reference it is compared against was captured
+   * at, and the result reports its own `size` and `scale`.
+   */
+  async captureEditorChrome(options) {
+    return this.#client.captureEditorChrome(options);
+  }
+  /** `'all'` -> `EditorClient.selectAll()` (mirrors `vgai select --all`); otherwise `EditorClient.select(id)` (mirrors `vgai select <entityId>`). */
+  async select(id) {
+    if (id === "all") {
+      await this.#client.selectAll();
+      return;
+    }
+    await this.#client.select(id);
+  }
+  /** Mirrors `vgai deselect`. */
+  async deselect() {
+    await this.#client.select(null);
+  }
+  /** No `id` -> focus the current selection (mirrors bare `vgai focus`); `id` given -> focus that entity. */
+  async focus(id) {
+    if (id !== void 0) {
+      await this.#client.focusEntity(id);
+      return;
+    }
+    await this.#client.focusSelection();
+  }
+  async frame(target) {
+    if (typeof target === "string") {
+      await this.#client.frameEntity(target);
+      return;
+    }
+    await this.#client.frameDocument(target?.fit);
+  }
+  /**
+   * WATCH THE AGENT LOOK AROUND THE MODEL.
+   *
+   * Swings the open Object3D document's camera — the camera the human's tab is
+   * showing — around the framed subject by `azimuth`/`elevation` RADIANS,
+   * animated over `duration` seconds (default 0.6), and resolves when the move
+   * ends. This is deliberately not a jump cut: the point of the verb is that a
+   * person watching sees the agent walk around the thing it is working on.
+   *
+   * `await editor.orbit({ azimuth: Math.PI / 2 })` — a quarter turn to the right.
+   *
+   * There is ONE camera, and the human owns it: a drag during the move cancels
+   * it exactly where it is, and the resolved outcome says `cancelledBy:
+   * 'human'` rather than throwing. A second look verb supersedes the first.
+   * The move is drawn by the document's own frame loop, so a document that
+   * isn't being drawn (background tab, inactive panel) doesn't orbit.
+   */
+  async orbit(options) {
+    const known = ["azimuth", "elevation", "duration"];
+    const unknown = Object.keys(options ?? {}).filter((key) => !known.includes(key));
+    if (unknown.length > 0)
+      throw new Error(
+        `editor.orbit: ${unknown.join(", ")} ${unknown.length === 1 ? "is not a key" : "are not keys"} this verb takes. It takes azimuth and elevation in RADIANS (relative to where the camera is now) and duration in SECONDS.`
+      );
+    return this.#client.orbitDocument(options);
+  }
+  /**
+   * A slow full revolution of the open document's subject — {@link orbit} with
+   * the turns spelled out and a constant angular rate. Resolves at the end of
+   * the last revolution.
+   */
+  async turntable(options) {
+    return this.#client.turntableDocument(options);
+  }
+  async view(preset) {
+    await this.#client.viewPreset(preset);
+  }
+  /**
+   * Switch the editor's NAMED WORKSPACE — `await editor.workspace('model')`.
+   *
+   * A workspace is a task-named LAYOUT MEMORY over the one dock
+   * (ARCHITECTURE-CORE §Editor chrome): `game` (the default, the editor's
+   * standing arrangement), `model`, `sculpt`, `texture`, `animate`, `look`.
+   * Switching is an EXPLICIT act — nothing in the editor moves chrome on its
+   * own, opening a document included — and this is the session door to it,
+   * beside `Window → Workspace` and the registered actions.
+   *
+   * Resolves once the dock has finished rebuilding, so a capture taken
+   * immediately after photographs the arrangement that was asked for. Each
+   * workspace remembers the user's own hand-tuning per project, so switching
+   * away and back is lossless.
+   */
+  async workspace(id) {
+    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
+   * `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);
+  }
+  /**
+   * Set the MATERIAL apart from the bundle that usually carries it.
+   * Appearance is palette × material, independent axes by ruling, so
+   * `style()` alone can never say whether a cost belongs to the blur or to
+   * the palette. This is the door that measures them apart; it answers with
+   * what the chrome wears afterwards (`style` is `null` when the mix matches
+   * no registered bundle).
+   */
+  async appearance(appearance) {
+    return this.#client.setAppearance(appearance);
+  }
+  /** Focus an editor panel: a viewport tab, the console, the build surface, or
+   *  any key the editor's static-panel registry holds — an unknown key refuses
+   *  naming the ones it does. */
+  async showPanel(name) {
+    switch (name) {
+      case "viewport-edit":
+        await this.#client.showViewport("edit");
+        return;
+      case "console":
+        await this.#client.toggleConsole();
+        return;
+      default:
+        await this.#client.showPanel(name);
+        return;
+    }
+  }
+  /** `kind` inferred from `path`'s extension when omitted (`inferAssetKind`) — pass it explicitly to override. */
+  async openAsset(path, kind) {
+    await this.#client.openAsset(path, kind ?? inferAssetKind(path));
+  }
+  /**
+   * SELECT a project asset — the browser's single click, which fills the
+   * Inspector without opening a document. `openAsset` is the double click.
+   *
+   * This is how a project's own `asset.inspector` section is reached: select
+   * the file it matches, then `inspect()` lists the verbs that section
+   * declares and `runAction(id)` runs one. Selecting a path nothing matches
+   * is not an error — the Inspector shows what it has, exactly as it does
+   * for a human.
+   */
+  async selectAsset(path) {
+    await this.#client.selectAsset(path);
+  }
+  /**
+   * Captures the editor's native four-view preview. A bare string is a
+   * project-relative asset path (the common case); an explicit source object
+   * targets a path, a LIVE SCENE ENTITY (`assetPreview({ entityId }, …)`) —
+   * which is what makes `options.stage: 'scene'`, the entity photographed
+   * where it stands under the scene's own lighting, reachable from here — or
+   * RAW GLB BYTES (`assetPreview({ glbBase64 }, …)`), for a model that exists
+   * only in the calling Node process's memory and has never been written to
+   * disk. `stage` defaults to `'lab'`, the neutral Asset Lab staging this has
+   * always produced, and the bytes form is lab-only.
+   */
+  async assetPreview(source, options) {
+    return this.#client.captureAssetPreview(
+      typeof source === "string" ? { assetPath: source } : source,
+      options
+    );
+  }
+  /**
+   * The same subject photographed as a LABELED SHOT SET instead of the four
+   * views — a caller-supplied definition of turntable yaws and bone-anchored
+   * crops, rendered against the asset's own skeleton, with a contact sheet.
+   * Every source {@link assetPreview} takes works here, GLB bytes included:
+   * a shot set stages its own subject, so it needs no place to stand.
+   *
+   * Sole in-repo caller today: `project.bake.preview`'s `--orbit` lane.
+   */
+  async assetPreviewShots(source, definition, options) {
+    return this.#client.captureShotSetPreview(
+      typeof source === "string" ? { assetPath: source } : source,
+      definition,
+      options
+    );
+  }
+  async grid(on) {
+    await this.#client.setGrid(on);
+  }
+  async helpers(on) {
+    await this.#client.setHelpers(on);
+  }
+  async stats(on) {
+    await this.#client.setStats(on);
+  }
+  async shading(mode) {
+    await this.#client.setShadingMode(mode);
+  }
+  /**
+   * READ the inspector, as data — the serialized inspection subject
+   * (`editor.inspect()`; design: `docs/ARCHITECTURE-CORE.md` §Editor chrome,
+   * "The Inspection Model"). This is the Figma-Inspect analog: whatever a
+   * human would see in the inspector right now — the subject's identity, its
+   * verbs, and every identified section in display order, with a `fields`
+   * section's CURRENT VALUES at their scriptable `path`s.
+   *
+   * Reach for it whenever the next step depends on what an object actually
+   * IS: `await editor.select(id)` then `await editor.inspect()` answers "what
+   * properties does this thing have, and what are they set to" in one call,
+   * against the same model the panel renders — no scene-graph reads, no
+   * guessing at property names.
+   *
+   * When the inspector is showing NOTHING — nothing selected on a surface
+   * with no empty-state subject of its own, which is most of them — the answer
+   * is `{none: true}`, so "the human sees no inspector" and "the read failed"
+   * are never the same value. A surface whose empty space IS a real thing (an
+   * open Asset Lab document) still answers with that subject, and never with
+   * another surface's.
+   *
+   * A `custom` section body is a named opaque: the editor renders it with
+   * React, so the wire reports its identity rather than pretending to describe
+   * its rendering — plus, when the section can say what it DISPLAYS, a `data`
+   * payload in its own vocabulary (`transform` carries
+   * `{position, rotation, scale}`, rotation in Euler XYZ degrees).
+   */
+  async inspect() {
+    return this.#client.inspect();
+  }
+  /** Run one verb listed by `inspect().quickActions`, through the same action
+   * the human Inspector button invokes. */
+  async runAction(actionId) {
+    return this.#client.runInspectionAction(actionId);
+  }
+  /**
+   * Run ONE command by id — the door to everything the command palette lists.
+   *
+   * ONE NAME (orchestrator ruling 2026-09-19). There were briefly TWO doors
+   * onto the one view-verb table — this one and `editor.viewVerb(view, verb)`,
+   * which addressed the same registry by its two halves. A second addressing
+   * of one table is a second name for one thing, and an agent reading
+   * `--list` had to choose between them with nothing to choose on. This door
+   * stays because it is strictly wider: it addresses a COMMAND ID, so under
+   * the frame it reaches everything the workbench knows — a `vgai.action.<id>`
+   * editor action, one of VS Code's own — and not only a view. A VIEW is
+   * reached by spelling its verb's command id:
+   *
+   *     await editor.command('vgai.blender-uv-view.state')
+   *     await editor.command('vgai.blender-uv-view.zoom', { to: 600 })
+   *
+   *     await editor.command('vgai.blender-node-view.view-all')
+   *     await editor.command('vgai.blender-node-view.look', { node: 'Principled BSDF' })
+   *
+   * Under the Code-OSS frame this is the workbench's own command service, so
+   * any command id works — ours and VS Code's alike. Standalone `vgai edit`
+   * has no command service and answers the `vgai.<view>.<verb>` shape off the
+   * SAME verb table the frame's commands call, refusing any other id by name.
+   * One table, two doors, exactly like the keymap's.
+   *
+   * Answers with whatever the command returned — a view verb's own state, or
+   * `null` for a command that returns nothing.
+   */
+  async command(commandId, args) {
+    return this.#client.runCommand(commandId, args);
+  }
+  /**
+   * RESTRUCTURE the authored tree — the hierarchy context menu's own verbs.
+   *
+   * `create`, `delete`, `duplicate`, `reparent`, `reorder`, `wrap`, `unwrap`,
+   * `group`, `ungroup`, `copy`, `cut`, `paste`; `extractComponent` and
+   * `forkComponent` are the two that write whole new files and have their own
+   * doors below. All of them run the SAME `authoring/consumer-actions.ts`
+   * helpers the menu items call, so there is one implementation of each op and
+   * not a second that can disagree with what a human gets.
+   *
+   * It exists because the menu is a POINTER surface: every one of these ops was
+   * reachable only by right-clicking a hierarchy row, which is nothing an agent
+   * can do — so for an ingest root, whose only authoring surface IS the editor,
+   * structure was closed entirely.
+   *
+   * `id`/`ids` default to the current selection. The answer carries the same
+   * per-edit `write` ack `setField` does, so `write.persisted` tells a saved
+   * restructure from a live-only one. An op the active adapter does not provide
+   * REJECTS by name — never a silent no-op.
+   */
+  async structure(op, options) {
+    return this.#client.structureOp(op, options ?? {});
+  }
+  /**
+   * "Extract Component…" — lift the selected native subtree into its own
+   * component file (plus a story) and replace the callsite with it.
+   *
+   * Answers the action's own sentence, which NAMES both new files, because
+   * undo owns the callsite edit and will not remove them.
+   */
+  async extractComponent(options) {
+    return (await this.#client.extractComponent(options ?? {})).hint;
+  }
+  /**
+   * "Fork Component…" — copy the selected instance's component definition to a
+   * new file and retarget THIS CALLSITE at it.
+   *
+   * One callsite is the unit of the edit; when that callsite sits inside a
+   * component rendered many times, every one of those renders now renders the
+   * fork.
+   */
+  async forkComponent(options) {
+    return (await this.#client.forkComponent(options ?? {})).hint;
+  }
+  /**
+   * READ the hierarchy panel, as data — the rows a human is looking at right
+   * now, nested exactly as the panel nests them.
+   *
+   * The companion to {@link inspect}: that one answers "what IS the selected
+   * thing", this one answers "what does the tree LOOK LIKE". It is the panel's
+   * own output, not a fresh walk of the scene — the adapter's tree after the
+   * component marks fold implementation subtrees (bones, particle renderers,
+   * instanced pools), after the internals reveal, the document promotion, the
+   * child cap, the collapse state, the search filter and the selection scope.
+   *
+   * Works in play mode and edit mode; the answer says which (`playState`,
+   * `activeViewportTab`), because the two are different adapters and a tree
+   * that looks wrong is very often the wrong adapter's tree.
+   *
+   * Prefer this over `status().entities`, which is deliberately a different
+   * question — the RAW adapter tree, unprojected. A panel that renders the
+   * wrong rows looks perfectly healthy in that facet.
+   *
+   * Each row carries `childCount` (what its caret opens), `internalChildCount`
+   * (what is folded behind "Reveal Internals") and `expandable` (whether the
+   * panel draws a caret at all), so "this subtree exists but nothing in the UI
+   * opens it" is a fact you can read rather than one you have to notice.
+   *
+   * Rejects, naming the panel, when no hierarchy panel is mounted — an empty
+   * tree would be a fabricated answer about a surface nobody is being shown.
+   */
+  async hierarchy() {
+    return this.#client.hierarchy();
+  }
+  /** Expand every branch through the Hierarchy panel's own action. */
+  async expandHierarchyAll() {
+    await this.#client.expandHierarchyAll();
+  }
+  /** Collapse every branch through the same panel action. Expanding is
+   *  persisted per project, so without this the tree's REST STATE — what a
+   *  person sees on opening the project — is unreachable once any reader has
+   *  expanded it. */
+  async collapseHierarchyAll() {
+    await this.#client.collapseHierarchyAll();
+  }
+  /**
+   * Write one editable field from `inspect()` by its stable path, through the
+   * same Inspector IO and persistence boundary the human control uses.
+   *
+   * The answer is `{ subject, write }`, and `write` is the half worth reading
+   * first: a write with no persistence route open still succeeds — it lands on
+   * the live object and journals live-only — so `write.persisted` is how you
+   * tell a saved edit from one that will not survive the session, without
+   * diffing the tree. `write.destination` is the adapter's own words for where
+   * it went ("live-only (not saved)" is a destination, never silence).
+   */
+  async setField(path, value) {
+    return this.#client.setInspectionField(path, value);
+  }
+  /**
+   * REMOVE one field's authored override — the revert arrow, as a command.
+   *
+   * Reach for this instead of `setField` whenever you are UNDOING an edit that
+   * added a property the source did not carry: `setField` can only write a
+   * value, so setting the default back leaves `position={[0, 0, 0]}` in the
+   * file where there was nothing before. Only this door restores the bytes.
+   *
+   * The answer is the same `{ subject, write }` shape, awaited past the bytes.
+   * It rejects with `code: 'REMOVAL_UNAVAILABLE'` when the field is not
+   * declared removable or the lane has no removal door — which is a missing
+   * seam to report, not a removal that failed.
+   */
+  async removeField(path) {
+    return this.#client.removeInspectionField(path);
+  }
+  /** Open a document by its adapter-declared id, through its registered owner. */
+  async open(id) {
+    return this.#client.open(id);
+  }
+  /** Undo / redo one project transaction, through the session's own history
+   *  queue — the same one the keyboard shortcut drives. */
+  async undo() {
+    return this.#client.undo();
+  }
+  async redo() {
+    return this.#client.redo();
+  }
+  /** Mirrors `vgai status` — the full live editor state as JSON. */
+  async status() {
+    return this.#client.getState();
+  }
+  /** A live viewport PNG (`EditorClient.captureViewport`) — no direct CLI verb exists; this is the closest wire read. */
+  async screenshot(size) {
+    return this.#client.captureViewport(size);
+  }
+};
+
+// src/tools.ts
+var LiveTools = class {
+  /** `#`-private for the same reason `LiveEditor.#client` is. */
+  #client;
+  constructor(client) {
+    this.#client = client;
+  }
+  /** Enumerate the exact `package.json#vgai.tools` catalog without executing it. */
+  async list() {
+    return this.#client.listProjectTools();
+  }
+  /** Return one tool's discoverable metadata, or `null` when it is not registered. */
+  async describe(name) {
+    const catalog = await this.list();
+    return catalog.tools.find((tool) => tool.name === name) ?? null;
+  }
+  /**
+   * Invoke the same validated callable used by the editor and CLI.
+   *
+   * `instance` names WHICH mounted instance the tool should drive when several
+   * are live (multiplayer authoring) — it reaches the tool as `ctx.instance`,
+   * and a tool that drives the game binds
+   * `game.instance(ctx.instance)` from it. Omitted is the single-instance case;
+   * the tool then targets the sole live instance, exactly as before.
+   */
+  async run(name, input = {}, options = {}) {
+    return this.#client.runProjectTool(name, input, options);
+  }
+};
+
+// src/lazy-proxy.ts
+function isFunction(value) {
+  return typeof value === "function";
+}
+function walk(root, path) {
+  if (path.length === 0) return { thisArg: void 0, fn: root };
+  let obj = root;
+  for (let i = 0; i < path.length - 1; i++) {
+    const key = path[i];
+    obj = obj[key];
+  }
+  const lastKey = path[path.length - 1];
+  return { thisArg: obj, fn: obj[lastKey] };
+}
+function lazyChainProxy(resolveRoot, path = []) {
+  const callableTarget = (() => {
+  });
+  return new Proxy(callableTarget, {
+    get(_target, prop) {
+      if (prop === "then" || prop === "catch" || prop === "finally") return void 0;
+      return lazyChainProxy(resolveRoot, [...path, prop]);
+    },
+    apply(_target, _thisArg, args) {
+      return resolveRoot().then((root) => {
+        const { thisArg, fn } = walk(root, path);
+        if (!isFunction(fn)) {
+          const label = path.length > 0 ? path.map(String).join(".") : "(the connected value)";
+          throw new TypeError(`@volter/editor-live: ${label} is not a function on the connected session.`);
+        }
+        return fn.apply(thisArg, args);
+      });
+    }
+  });
+}
+
+// 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";
+
+// ../editor-project/src/manifest/locate.ts
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+// ../editor-project/src/manifest/filename.ts
+var MANIFEST_FILENAME = "vgai.project.json";
+var REMOVED_MANIFEST_FILENAME = "vgai.game.json";
+function removedManifestFilenameMessage(where) {
+  return `${where}: found \`${REMOVED_MANIFEST_FILENAME}\` and no \`${MANIFEST_FILENAME}\`. \`${REMOVED_MANIFEST_FILENAME}\` was REMOVED (the legacy-removal doctrine, docs/ARCHITECTURE-CORE.md \xA7Vocabulary) \u2014 nothing reads it any more, and it is deliberately NOT read as a fallback, because a second accepted name is the defect.
+Fix: rename it \u2014 \`git mv ${REMOVED_MANIFEST_FILENAME} ${MANIFEST_FILENAME}\`. The contents are unchanged; only the filename moved.`;
+}
+
+// ../editor-project/src/manifest/locate.ts
+function assertNoRemovedManifestFilename(dir) {
+  if (existsSync(join(dir, MANIFEST_FILENAME))) return;
+  if (!existsSync(join(dir, REMOVED_MANIFEST_FILENAME))) return;
+  throw new Error(removedManifestFilenameMessage(join(dir, REMOVED_MANIFEST_FILENAME)));
+}
+function resolveManifestPath(dir) {
+  assertNoRemovedManifestFilename(dir);
+  return join(dir, MANIFEST_FILENAME);
+}
+
+// ../editor-sdk/src/session/registry-format.ts
+import {
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  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");
+function isEditorSessionEntry(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const s = v;
+  const optionalIdentity = (value) => value === void 0 || value === null || typeof value === "string";
+  return (typeof s["project"] === "string" || s["project"] === null) && typeof s["port"] === "number" && typeof s["pid"] === "number" && typeof s["startedAt"] === "string" && optionalIdentity(s["sessionId"]) && optionalIdentity(s["controlSecret"]) && optionalIdentity(s["repositoryId"]) && optionalIdentity(s["worktreeId"]) && optionalIdentity(s["worktreeRoot"]) && optionalIdentity(s["projectRelativePath"]) && optionalIdentity(s["branch"]) && optionalIdentity(s["headCommit"]) && optionalIdentity(s["baseCommit"]);
+}
+function normalizeEditorSessionEntry(session) {
+  return {
+    ...session,
+    sessionId: session.sessionId ?? null,
+    controlSecret: session.controlSecret ?? null,
+    repositoryId: session.repositoryId ?? null,
+    worktreeId: session.worktreeId ?? null,
+    worktreeRoot: session.worktreeRoot ?? null,
+    projectRelativePath: session.projectRelativePath ?? null,
+    branch: session.branch ?? null,
+    headCommit: session.headCommit ?? null,
+    baseCommit: session.baseCommit ?? null
+  };
+}
+function pidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function readLiveRegisteredSessions() {
+  try {
+    const raw = JSON.parse(readFileSync(EDITOR_SESSIONS_REGISTRY_FILE, "utf8"));
+    return Array.isArray(raw) ? raw.filter(isEditorSessionEntry).map(normalizeEditorSessionEntry).filter((s) => pidAlive(s.pid)) : [];
+  } catch {
+    return [];
+  }
+}
+function servedProjectAnswer(body) {
+  const b = body;
+  return {
+    path: b.project?.path ?? b.serving?.path ?? null,
+    manifestError: b.project ? null : b.serving?.error ?? null
+  };
+}
+
+// ../editor-sdk/src/session/discovery.ts
+var EDITOR_SESSION_DISCOVERY_TIMEOUT_MS = 2e3;
+var EDITOR_PROBE_TIMEOUT_MS = 1500;
+var EditorTimeoutError = class extends Error {
+  constructor(label, ms) {
+    super(`${label} timed out after ${ms}ms`);
+    this.name = "EditorTimeoutError";
+  }
+};
+function withTimeout(promise, ms, label) {
+  return new Promise((resolvePromise, reject) => {
+    const timer = setTimeout(() => reject(new EditorTimeoutError(label, ms)), ms);
+    promise.then(
+      (v) => {
+        clearTimeout(timer);
+        resolvePromise(v);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    );
+  });
+}
+async function fetchJson(url, timeoutMs) {
+  try {
+    const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok) return void 0;
+    return await res.json();
+  } catch {
+    return void 0;
+  }
+}
+function baseUrl(session) {
+  return session.url ?? `http://127.0.0.1:${session.port}`;
+}
+var HttpSessionDiscovery = class {
+  async listSessions(timeoutMs) {
+    const registered = readLiveRegisteredSessions();
+    const perProbeTimeout = Math.min(EDITOR_PROBE_TIMEOUT_MS, Math.max(200, timeoutMs));
+    const probes = await Promise.all(
+      registered.map(async (s) => {
+        const body = await fetchJson(
+          `${baseUrl({ port: s.port, project: null, pid: s.pid })}/__editor/project`,
+          perProbeTimeout
+        );
+        if (body === void 0) return void 0;
+        const served = servedProjectAnswer(body);
+        const info = {
+          port: s.port,
+          project: served.path,
+          pid: s.pid,
+          manifestError: served.manifestError
+        };
+        return info;
+      })
+    );
+    return probes.filter((p) => p !== void 0);
+  }
+};
+
+// src/session.ts
+function findProjectRootFrom(dir) {
+  let cur = resolve2(dir);
+  for (; ; ) {
+    if (existsSync2(resolveManifestPath(cur))) return cur;
+    const parent = dirname(cur);
+    if (parent === cur) return null;
+    cur = parent;
+  }
+}
+function canonicalPath(path) {
+  try {
+    return realpathSync2(path);
+  } catch {
+    return resolve2(path);
+  }
+}
+function readProjectSession(projectRoot) {
+  try {
+    const value = JSON.parse(
+      readFileSync2(join3(projectRoot, ".vgai", "session.json"), "utf8")
+    );
+    if (typeof value !== "object" || value === null) return null;
+    const hint = value;
+    if (typeof hint["port"] !== "number" || !Number.isInteger(hint["port"]) || hint["port"] <= 0 || typeof hint["pid"] !== "number" || typeof hint["url"] !== "string" || typeof hint["startedAt"] !== "string") {
+      return null;
+    }
+    return hint;
+  } catch {
+    return null;
+  }
+}
+async function probeServedProject(port) {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/__editor/project`, {
+      signal: AbortSignal.timeout(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS)
+    });
+    if (!response.ok) return void 0;
+    return servedProjectAnswer(await response.json());
+  } catch {
+    return void 0;
+  }
+}
+function manifestRefusal(projectRoot, manifestError) {
+  return new Error(
+    `@volter/editor-live: the editor session for ${projectRoot} is live, but its vgai.project.json does not load, so there is no editor or game to drive \u2014 the editor page is showing this same error. Fix the manifest and retry; the session recovers on save, no restart needed.
+${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.`
+    );
+  }
+  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.`
+    );
+  }
+  const listed = sessions.map((s) => `    port ${s.port} \u2192 ${s.project === null ? "(no project)" : s.project}`).join("\n");
+  return new Error(
+    `@volter/editor-live: ${sessions.length} live editor session(s) are running, but none of them opens ${projectRoot}. @volter/editor-live never silently attaches to a different project.
+  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.`
+  );
+}
+async function resolveSession(projectDir = process.cwd(), deps = {}) {
+  const findRoot = deps.findProjectRootFrom ?? findProjectRootFrom;
+  const transport = deps.transport ?? new HttpSessionDiscovery();
+  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?`
+    );
+  }
+  const localHint = (deps.readProjectSession ?? readProjectSession)(projectRoot);
+  if (localHint) {
+    if (deps.verifyProjectSession) {
+      if (await deps.verifyProjectSession(localHint, projectRoot)) {
+        return { port: localHint.port, projectRoot };
+      }
+    } else {
+      const served = await probeServedProject(localHint.port);
+      if (served?.path != null && canonicalPath(served.path) === canonicalPath(projectRoot)) {
+        if (served.manifestError !== null) throw manifestRefusal(projectRoot, served.manifestError);
+        return { port: localHint.port, projectRoot };
+      }
+    }
+  }
+  let sessions;
+  let discoveryFailure = null;
+  try {
+    sessions = await withTimeout(
+      transport.listSessions(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS),
+      EDITOR_SESSION_DISCOVERY_TIMEOUT_MS,
+      "editor session discovery"
+    );
+  } catch (err) {
+    sessions = [];
+    discoveryFailure = err instanceof Error ? err.message : String(err);
+  }
+  const canon = canonicalPath(projectRoot);
+  const match = sessions.find((s) => s.project !== null && canonicalPath(s.project) === canon);
+  if (!match) throw noMatchingSessionRefusal(projectRoot, canon, sessions, discoveryFailure);
+  if (match.manifestError != null) throw manifestRefusal(projectRoot, match.manifestError);
+  return { port: match.port, projectRoot };
+}
+
+// src/singleton.ts
+function createLazySession(factory) {
+  let promise = null;
+  return {
+    ensure() {
+      promise ??= factory();
+      return promise;
+    },
+    reset() {
+      promise = null;
+    }
+  };
+}
+
+// src/index.ts
+function bindTo(port) {
+  const client = new EditorClient({ url: `http://127.0.0.1:${port}` });
+  return { editor: new LiveEditor(client), tools: new LiveTools(client) };
+}
+function unconnectedBindings() {
+  return bindTo(0);
+}
+async function connect(projectDir, deps) {
+  const session = await resolveSession(projectDir, deps);
+  return { ...bindTo(session.port), session };
+}
+var lazySession = createLazySession(() => connect());
+var editor = lazyChainProxy(() => lazySession.ensure().then((s) => s.editor));
+var tools = lazyChainProxy(() => lazySession.ensure().then((s) => s.tools));
+export {
+  LiveEditor,
+  LiveEditorDocument,
+  LiveTools,
+  connect,
+  editor,
+  findProjectRootFrom,
+  inferAssetKind,
+  resolveSession,
+  tools,
+  unconnectedBindings
+};
+//# sourceMappingURL=index.js.map