@volter/editor-blender 0.1.151 → 0.1.152

package/host/blender-runtime-host.ts

@@ -3,11 +3,12 @@
 import { bytesFromBase64 } from '@volter/blender-engine/browser/three/blender-base64';
 import {
   BlenderRuntime,
+  DocumentNotOpened,
   type PresentAnswer,
   type SavedDocument,
   type SaveScript,
 } from '@volter/blender-engine/browser';
-import type { BlenderAssetLibrary, GltfExportAnswer, GltfExportKind, GltfExportPrevious, RenderRequest, RuntimeStart } from '@volter/blender-engine/browser/protocol';
+import type { BlenderAssetLibrary, DocumentOpened, GltfExportAnswer, GltfExportKind, GltfExportPrevious, RenderRequest } from '@volter/blender-engine/browser/protocol';
 import type {
   BlenderActionClip,
   BlenderSceneMovie,
@@ -291,6 +292,11 @@ async function runtimeHolding(blend: string): Promise<BlenderRuntime> {
   return runtime;
 }
 
+/** The project's `.blend` the engine holds now, or `null` while it holds none. */
+export function heldModelDocument(): string | null {
+  return runtime?.document ?? null;
+}
+
 /** Bring the project's `.blend` up to the model the engine holds, for a reader that takes the
  *  file's bytes as the model's (a cook's or an export's hash beside what the engine exported). */
 export async function flushModelDocument(blend: string): Promise<void> {
@@ -334,13 +340,24 @@ const savedListeners = new Set<ModelDocumentSavedListener>();
 /** The listeners' work on each runtime's saves, not yet done. */
 const savedWork = new Map<BlenderRuntime, Set<Promise<unknown>>>();
 
+/** Whether the project's file already holds these bytes. A save script's export of an unchanged scene (a call that
+ *  read the model, a save with nothing changed) writes the same bytes, and a rewrite of them is still a change to
+ *  what watches the file: the game's dev server reloads every page on it. So an unchanged file is left as it is. */
+async function holds(path: string, bytes: Uint8Array): Promise<boolean> {
+  const files = editorHost().files;
+  // (a file that can't be read is written, as every carry wrote it before)
+  if ((await files.stat(path).catch(() => null))?.size !== bytes.byteLength) return false;
+  const held = await files.readBytes(path).catch(() => null);
+  return held !== null && held.byteLength === bytes.byteLength && held.every((byte, at) => byte === bytes[at]);
+}
+
 function modelDocumentSaved(owner: BlenderRuntime, saved: SavedDocument): void {
   const files = saved.script?.error === null ? saved.script.files : [];
   const heard: ModelDocumentSaved = {
     blend: saved.document,
     script: saved.script === null ? null : { output: saved.script.output, error: saved.script.error, unstaged: saved.script.unstaged },
     async carry() {
-      for (const file of files) await editorHost().files.write(file.path, file.bytes);
+      for (const file of files) if (!(await holds(file.path, file.bytes))) await editorHost().files.write(file.path, file.bytes);
     },
   };
   for (const listener of [...savedListeners]) {
@@ -361,72 +378,213 @@ export function subscribeModelDocumentSaved(listener: ModelDocumentSavedListener
   return () => { savedListeners.delete(listener); };
 }
 
+/** The listeners' work on every save `owner` made, which reads files and not Blender, done. */
+async function savedWorkDone(owner: BlenderRuntime): Promise<void> {
+  for (let held = savedWork.get(owner); held !== undefined; held = savedWork.get(owner)) await Promise.all([...held]);
+}
+
 /**
- * A RUNTIME RETIRED WITH ITS SAVES' WORK DONE, for every retirement (another document opened, a reload, a stop, the
- * session's close): its last save runs the save script in its turn as every save does and is heard, and then the
- * listeners' work on every save the runtime made, which reads files and not Blender, is waited for. A save that fails
- * throws, and the runtime stays alive with its document.
+ * THE DOCUMENT BLENDER HOLDS, RELEASED WITH ITS SAVES' WORK DONE, before Blender opens another `.blend`: its last
+ * save runs the save script in its turn as every save does and is heard, Blender takes no other call from then until
+ * the next open (`BlenderRuntime.releaseDocument`), so no edit lands unsaved, and the listeners' work on its saves is
+ * waited for. A save that fails throws, and Blender keeps the document, its history and its ownership.
+ */
+async function releaseDocument(owner: BlenderRuntime, next: string): Promise<void> {
+  await owner.releaseDocument(next, { ...(saveScript ? { after: saveScript } : {}), landed: (saved) => modelDocumentSaved(owner, saved) });
+  await savedWorkDone(owner);
+}
+
+/**
+ * A RUNTIME RETIRED WITH ITS SAVES' WORK DONE, for every retirement (a reload, a stop, the session's close): its last
+ * save is the document's as {@link releaseDocument}'s is, taken as the runtime stops. A save that fails throws, and the
+ * runtime stays alive with its document.
  */
 async function retireRuntime(owner: BlenderRuntime): Promise<void> {
   await owner.stop({ ...(saveScript ? { after: saveScript } : {}), landed: (saved) => modelDocumentSaved(owner, saved) });
-  for (let held = savedWork.get(owner); held !== undefined; held = savedWork.get(owner)) await Promise.all([...held]);
+  await savedWorkDone(owner);
 }
 
 /**
- * THE ASSET LIBRARIES EVERY SESSION'S BLENDER HAS (Preferences > File Paths > Asset Libraries), by name: set in the
- * running session at once, and in each session after it starts (`startSession`). Blender's preferences live as long as
- * its session, and each `.blend` opened is a new session. The removal leaves a running session's library as it is.
+ * THE ASSET LIBRARIES EVERY BLENDER HAS (Preferences > File Paths > Asset Libraries), by name: set in the running
+ * Blender at once (once it is up, if it is starting), and in each Blender after it starts ({@link startedRuntime}).
+ * Blender's preferences live as long as its worker, whatever `.blend` it opens. The removal leaves a running Blender's
+ * library as it is.
  */
 const assetLibraries = new Map<string, BlenderAssetLibrary>();
 
 export function setBlenderAssetLibrary(library: BlenderAssetLibrary): () => void {
   assetLibraries.set(library.name, library);
-  if (blenderSessionStarted()) void blenderRuntime().setAssetLibrary(library).catch(refusedLibrary(library));
+  if (runtime?.project != null) void runtime.setAssetLibrary(library).catch(refusedLibrary(library));
   return () => { if (assetLibraries.get(library.name) === library) assetLibraries.delete(library.name); };
 }
 
 const refusedLibrary = (library: BlenderAssetLibrary) => (error: unknown): void =>
   editorHost().console.error(`Blender did not take the asset library ${library.name} (${library.directory}): ${error instanceof Error ? error.message : String(error)}`, 'blender-asset-library');
 
-/** A session's start, then the asset libraries every session has. Called where a start is asked for; the start
- *  claims its resource synchronously, before the first await. */
-async function startSession(session: BlenderRuntime, project: string, document: string): Promise<RuntimeStart> {
-  const started = await session.start(project, document);
-  for (const library of assetLibraries.values()) await session.setAssetLibrary(library).catch(refusedLibrary(library));
-  return started;
+/**
+ * THE PAGE'S BLENDER, started at `project` if it is not yet: its boot claimed now, holding no document, and the asset
+ * libraries every Blender has set once it is up. Whatever needs it started waits on its start (`BlenderRuntime.start`,
+ * one per worker), so an open that arrives while it starts waits for it rather than starting another. A start that
+ * fails is discarded here, and whoever waited on it says why; the next one makes a new Blender.
+ */
+function startedRuntime(project: string): BlenderRuntime {
+  const session = pageRuntime();
+  if (session.project !== null) return session;
+  setStarting(session);
+  void session.start(project).then(async () => {
+    if (startingSession === session) setStarting(null);
+    for (const library of assetLibraries.values()) {
+      if (runtime !== session) return;
+      await session.setAssetLibrary(library).catch(refusedLibrary(library));
+    }
+  }, () => {
+    if (startingSession === session) setStarting(null);
+    if (session.startFailed && runtime === session) terminateBlenderRuntime();
+  });
+  return session;
+}
+
+/** The page's Blender while its start is under way, which an open waits on before its own file's load. */
+let startingSession: BlenderRuntime | null = null;
+const startingListeners = new Set<() => void>();
+function notifyBlenderModelState(): void {
+  for (const listener of [...startingListeners]) listener();
+}
+function setStarting(session: BlenderRuntime | null): void {
+  startingSession = session;
+  notifyBlenderModelState();
+}
+
+/** Whether the page's Blender is starting: the first open, or one after a reload or a failure, waits on it. */
+export function blenderStarting(): boolean {
+  return startingSession !== null && startingSession === runtime;
+}
+
+/** Hear Blender start, and start or finish changing the model it holds. */
+export function subscribeBlenderStarting(listener: () => void): () => void {
+  startingListeners.add(listener);
+  return () => { startingListeners.delete(listener); };
+}
+
+/** `document` opened in `session`, Blender's own open; claimed at the call. A Blender that could not open it is
+ *  discarded, so the next open makes a new one rather than reaching a half-opened model. */
+async function openInRuntime(session: BlenderRuntime, document: string): Promise<DocumentOpened> {
+  try {
+    return await session.openDocument(document);
+  } catch (error) {
+    if (runtime === session) terminateBlenderRuntime();
+    throw error;
+  }
+}
+
+type DocumentTable = Awaited<ReturnType<EditorHostProject['documentTable']>>;
+
+/** A project's table lists a model: a `.blend` a finder found, the `model:` entries (`models.finder.ts`). */
+const listsModel = (table: DocumentTable): boolean =>
+  table.entries.some((entry) => entry.kind === 'model' && entry.source?.path.endsWith('.blend') === true);
+
+/** The project Blender was started early for, once per project this page opens (until its session ends). */
+let startedEarlyFor: string | null = null;
+
+/**
+ * BLENDER STARTED AS THE PROJECT OPENS, once its table lists a model: started holding no document, so the first model
+ * opened waits only for what is left of the start and then for its own file's load, and every later one opens in the
+ * same Blender ({@link openModelDocumentBlend}). Read from the table the project has published and each one after it,
+ * without asking for one: this package activates on its finder (`onFinder:modelsFromBlendFiles`) as the project's
+ * first table is resolved. Taken in turn with the documents' opens and retirements, so an open already under way
+ * starts Blender itself. Once per project the page opens; returns the unsubscribe.
+ */
+export function startBlenderWithProject(): () => void {
+  const host = editorHost();
+  const ended = host.session.onEnded(() => { startedEarlyFor = null; });
+  const tables = host.project.onDocumentTable((table) => {
+    if (!host.session.open() || !listsModel(table)) return;
+    const project = host.projectLocalState.projectRootPath();
+    if (project === null || startedEarlyFor === project) return;
+    startedEarlyFor = project;
+    void queueModelLifecycle(async () => {
+      if (runtime?.project != null || !host.session.open() || host.projectLocalState.projectRootPath() !== project) return;
+      // (said in the session journal, so a model's open can be read against the start it waited for)
+      const end = beginBlenderWork('Starting Blender');
+      startedRuntime(project).start(project).then(end, end);
+    });
+  });
+  return () => { tables(); ended(); };
 }
 
 export async function snapshotModelDocument(blend: string): Promise<Uint8Array> {
   return (await runtimeHolding(blend)).snapshotDocument();
 }
 
+/**
+ * THE DOCUMENT OPENED AGAIN, in turn with the documents' opens and switches: from its project file (a revert,
+ * discarding its changes) or as `bytes`, its unsaved state (a backup's restore). A failure before Blender's own open
+ * (its file's staging) keeps the running Blender with the document it held; one inside Blender's open discards it,
+ * as any failed open does.
+ */
+async function reopenModelDocument(blend: string, bytes?: Uint8Array): Promise<void> {
+  // (waited for outside the queue, which the open of `blend` may still be in)
+  const session = await runtimeHolding(blend);
+  await queueModelLifecycle(async () => {
+    if (runtime !== session || session.document !== blend) throw new Error(`Blender does not hold ${blend}.`);
+    try {
+      await session.openDocument(blend, bytes);
+    } catch (error) {
+      if (!(error instanceof DocumentNotOpened) && runtime === session) terminateBlenderRuntime();
+      throw error;
+    }
+  });
+}
+
+/** The document opened again from its project file, discarding its changes. */
 export async function revertModelDocument(blend: string): Promise<void> {
-  await (await runtimeHolding(blend)).revertDocument();
+  await reopenModelDocument(blend);
 }
 
+/** The document opened again as `bytes`, its unsaved state (a backup). */
 export async function restoreModelDocument(blend: string, bytes: Uint8Array): Promise<void> {
-  await (await runtimeHolding(blend)).restoreDocument(bytes);
+  await reopenModelDocument(blend, bytes);
 }
 
 /**
  * OPEN A `.blend` IN THE ENGINE — the Model document's own call, the WS-F save
- * path run backwards. `session.py` opens the named file at start and saves
- * back to it, so naming it here IS opening it.
+ * path run backwards. One Blender serves the page's documents one after
+ * another, as a desktop Blender does: opening another `.blend` saves the one it
+ * holds and opens the next in it (`open-document`, Blender's own open, which
+ * `session.py` saves back to). A reload, another project or a Blender whose start
+ * failed takes a new worker.
  *
- * The worker owns one file. Validate ownership before publishing a context;
- * a refused open must never expose the previous model under a new tab's
- * identity. Boot itself can present, so the context must exist before awaiting
- * boot completion. Return false when the requesting pane has since unmounted.
+ * Blender holds one file at a time. Validate ownership before publishing a
+ * context; a refused open must never expose the previous model under a new
+ * tab's identity. The open itself presents, so the context must exist before
+ * awaiting it. Return false when the requesting pane has since unmounted.
  */
 let modelOpenTail: Promise<void> = Promise.resolve();
 let modelStartup: { readonly session: BlenderRuntime; readonly project: string; readonly blend: string } | null = null;
 
+/** How many model opens, switches and retirements are queued or under way. */
+let modelLifecycles = 0;
+
 function queueModelLifecycle<T>(operation: () => Promise<T>): Promise<T> {
+  modelLifecycles += 1;
+  notifyBlenderModelState();
   const result = modelOpenTail.then(operation);
   modelOpenTail = result.then(() => {}, () => {});
+  void modelOpenTail.then(() => { modelLifecycles -= 1; notifyBlenderModelState(); });
   return result;
 }
 
+/** Whether Blender is starting or changing the model it holds (an open, a switch, a retirement): a read of its
+ *  model waits for it rather than failing. */
+export function blenderModelChanging(): boolean {
+  return modelLifecycles > 0 || blenderStarting();
+}
+
+/** Why Blender holds another document than the editor shows, in a person's words, or null. */
+export function blenderModelConflict(): string | null {
+  return modelDocumentConflict();
+}
+
 export async function openModelDocumentBlend(
   binding: ModelDocumentBinding,
   publish: () => void,
@@ -466,29 +624,46 @@ async function openBoundModelDocument(
   if (project === null) throw new Error('Opening a model requires a project path.');
   if (!modelDocumentMayOpen(binding)) return false;
   const previous = runtime;
-  if (previous && (reload || previous.project !== project || previous.document !== binding.blend)) {
-    // The OLD worker's bound file is saved and its saves' work done before it stops. If
+  // (each document named, so the session journal says which document gave way to which)
+  const handoff = (reloading: boolean) =>
+    beginBlenderWork(`Saving ${previous?.document ?? 'the previous model'} before ${reloading ? 'reopening' : 'opening'} ${binding.blend}`);
+  if (previous && (reload || previous.startFailed || (previous.project !== null && previous.project !== project))) {
+    // A NEW BLENDER: the old worker's file is saved and its saves' work done before it stops. If
     // saving fails it stays alive; neither its history nor its ownership moves.
-    // (named, both, so the session journal says which document gave way to which)
-    const end = beginBlenderWork(`saving ${previous.document ?? 'the previous model'} before opening ${binding.blend}${reload ? ' (a reload)' : ''}`);
+    const end = handoff(reload);
     try { await retireRuntime(previous); } finally { end(); }
     if (runtime === previous) terminateBlenderRuntime();
     if (!host.session.open() || !modelDocumentMayOpen(binding)) return false;
   }
-  const session = blenderRuntime();
-  // start claims its resource synchronously; its first frame may arrive before
-  // the returned promise resolves. The getter above rejects a conflicting file.
-  const started = startSession(session, project, binding.blend);
+  const switching = previous?.document != null && previous.document !== binding.blend ? previous : null;
+  let session: BlenderRuntime;
+  let opened: Promise<unknown>;
+  try {
+    if (switching) {
+      // ANOTHER `.blend` IN THE SAME BLENDER: the one it holds is saved and its saves' work done
+      // first. If saving fails Blender keeps it; neither its history nor its ownership moves.
+      const end = handoff(false);
+      try { await releaseDocument(switching, binding.blend); } finally { end(); }
+      if (!host.session.open() || !modelDocumentMayOpen(binding)) return false;
+      // What was the old document's goes with it, as a worker's does when it stops: its history
+      // (Blender's own load resets it too), its save notices and a Save As the tab had yet to follow.
+      forgetDocument();
+    }
+    session = startedRuntime(project);
+    // The open claims the document synchronously; its first frame may arrive before the
+    // returned promise resolves. A document Blender already holds (a remounted pane, a tab that
+    // followed a Save As) waits only for the start it may still be making.
+    opened = session.document === binding.blend ? session.start(project) : openInRuntime(session, binding.blend);
+  } finally {
+    // Every way out of a switch ends its release: the next document's open, once asked for, ends it in its own
+    // turn; any other way out (abandoned, failed) keeps the document Blender holds.
+    switching?.keepDocument();
+  }
   const starting = { session, project, blend: binding.blend };
   modelStartup = starting;
   try {
     publish();
-    await started;
-  } catch (error) {
-    // Discard a failed start so reopening creates a new worker. A session owned by another
-    // document remains alive and retains its resource.
-    if (session.startFailed && runtime === session) terminateBlenderRuntime();
-    throw error;
+    await opened;
   } finally {
     if (modelStartup === starting) modelStartup = null;
   }
@@ -514,10 +689,10 @@ async function openBoundModelDocument(
  * THEY NEVER START THE ENGINE. A panel asking what the engine holds must not
  * start Blender, so these answer `null` when this tab
  * has no started session — exactly the read `blender-status` makes, and for
- * the same reason.
+ * the same reason — or a started one that holds no model yet.
  */
 export function blenderSessionStarted(): boolean {
-  return runtime?.project != null && modelDocumentConflict() === null;
+  return runtime?.project != null && runtime.document !== null && modelDocumentConflict() === null;
 }
 
 /** The RNA version invalidates every view over this engine. Bump it at script, RNA and Outliner write doors, including writes that change no rendered geometry; presented frames bump it too. */
@@ -1076,6 +1251,8 @@ interface RuntimeView {
 
 let runtime: BlenderRuntime | null = null;
 const historyResources = new Set<string>();
+/** Which document Blender holds, counted: each one given up ({@link forgetDocument}) is a new count. */
+let heldDocument = 0;
 
 function invalidateBlenderHistory(): void {
   if (historyResources.size) editorHost().history.invalidate([...historyResources]);
@@ -1087,23 +1264,36 @@ let captureLifetime: AbortController | null = null;
  *  terminate, and the host door only exists inside a running editor. */
 let watchingSessionEnd = false;
 
-/** Diagnostics must not prevent teardown if the host has already detached. */
-function beginBlenderWork(label: string): () => void {
+/** Blender's work as a wait (`session.beginWork`): one a person follows ("Starting Blender") is theirs and the
+ *  session's, and an engine's own step (`internal`) the session's alone. Reporting it must not prevent teardown if the
+ *  host has already detached. */
+function beginBlenderWork(label: string, internal = false): () => void {
   try {
-    const end = editorHost().session.beginWork(`Blender: ${label}`);
+    const end = editorHost().session.beginWork(label, internal ? { internal } : undefined);
     return () => { try { end(); } catch { /* preserve the operation's result */ } };
   } catch { return () => {}; }
 }
 
+/** What belongs to the document Blender held and goes with it: its history, its save notices and a Save As the tab
+ *  had yet to follow. */
+function forgetDocument(): void {
+  heldDocument += 1;
+  invalidateBlenderHistory();
+  clearModelDocumentSaving();
+  unfollowedMove = null;
+  unlistedFollow = null;
+  awaitingListing?.();
+}
+
 function terminateBlenderRuntime(): void {
-  const end = beginBlenderWork('invalidating history and releasing runtime');
+  const end = beginBlenderWork('releasing the runtime', true);
   try {
-    invalidateBlenderHistory();
+    forgetDocument();
     captureLifetime?.abort();
     captureLifetime = null;
     runtime?.terminate();
     runtime = null;
-    clearModelDocumentSaving();
+    if (startingSession !== null) setStarting(null);
   } finally { end(); }
 }
 
@@ -1161,9 +1351,18 @@ async function runtimeView(): Promise<RuntimeView> {
   );
 }
 
+/** The page's Blender for a call on its document: refused while it is on another document than the editor shows, and
+ *  while it has started holding none. */
 export function blenderRuntime(): BlenderRuntime {
   const conflict = modelDocumentConflict();
   if (conflict) throw new Error(conflict);
+  if (runtime?.project != null && runtime.document === null)
+    throw new Error('Blender has started and holds no model yet: open a Model document (blender-start opens the one the editor shows).');
+  return pageRuntime();
+}
+
+/** The page's one Blender handle, made if there is none (not started: {@link startedRuntime} starts it). */
+function pageRuntime(): BlenderRuntime {
   if (runtime !== null) return runtime;
   watchSessionEnd();
   const lifetime = new AbortController();
@@ -1186,7 +1385,8 @@ export function blenderRuntime(): BlenderRuntime {
   };
   lifetime.signal.addEventListener('abort', discardStreamedFrame, { once: true });
   runtime = new BlenderRuntime({
-    work: beginBlenderWork,
+    // (the worker's own steps: the session's phase, never the person's status bar)
+    work: (label) => beginBlenderWork(label, true),
     documentSaving: ({ document, note }) => {
       if (!lifetime.signal.aborted) setModelDocumentSaveNotice(document, note);
     },
@@ -1203,8 +1403,11 @@ export function blenderRuntime(): BlenderRuntime {
         }
         if (!entry.resource) throw new Error('A Blender edit has no document resource');
         historyResources.add(entry.resource);
+        // (the document it was made in, through a script's Save As, which keeps Blender's history; not one opened since)
+        const held = heldDocument;
         const restore = async (direction: 'undo' | 'redo'): Promise<boolean> => {
           if (runtime !== owner) throw new Error('This Blender history belongs to a closed worker');
+          if (heldDocument !== held) throw new Error(`This Blender history belongs to ${entry.resource}, which Blender no longer holds`);
           const moved = await owner.historyStep(entry.id, direction);
           noteBlenderRnaChanged();
           // The restored frame arrives before the Outliner's scheduled read.
@@ -1270,7 +1473,7 @@ export function blenderRuntime(): BlenderRuntime {
         return {};
       }
       const documentId = presentationDocumentId();
-      const endWait = beginBlenderWork('waiting for Model presenter');
+      const endWait = beginBlenderWork('waiting for the Model presenter', true);
       let view: RuntimeView;
       try { view = await runtimeView(); } finally { endWait(); }
       lifetime.signal.throwIfAborted();
@@ -1285,7 +1488,7 @@ export function blenderRuntime(): BlenderRuntime {
         throw new Error('Blender capture source changed before render presentation');
       const presenter = rendering?.view ?? view;
       // Report the presenter’s holding before applying this frame.
-      const endApply = beginBlenderWork('applying frame to Model');
+      const endApply = beginBlenderWork('applying a frame to the Model', true);
       const applyAt = performance.now();
       const applied = (() => {
         try { return presenter.applyFrame(frame); }
@@ -1483,7 +1686,10 @@ export async function handleBlenderCommand(cmd: {
       data: {
         started: runtime?.project != null,
         document: host.documents.context(presentationDocumentId()) !== undefined,
-        instancing: runtime?.project != null ? (await runtimeView()).drawStatistics() : null,
+        // (the `.blend` Blender holds: none after a start as the project opened, before a model's open)
+        holds: runtime?.document ?? null,
+        instancing: runtime?.project != null && host.documents.context(presentationDocumentId()) !== undefined
+          ? (await runtimeView()).drawStatistics() : null,
         lastOutput: runtime?.lastOutput ?? [],
       },
     };
@@ -1538,33 +1744,41 @@ export async function handleBlenderCommand(cmd: {
             'opens that document (the Model document ships with @volter/editor-blender).',
         };
     }
+    if (cmd.type === 'blender-start') {
+      const conflict = modelDocumentConflict();
+      if (conflict) throw new Error(conflict);
+      // A start that fails is discarded (`startedRuntime`), so the next `blender-start` makes a
+      // new Blender instead of awaiting the same failure.
+      const session = startedRuntime(project!);
+      // THE OPEN MODEL DOCUMENT'S `.blend` WINS over the default: a models
+      // project's document is its own `src/models/<name>.blend`, and a
+      // `blender-start` that named none is asking for the session this tab
+      // is showing, not for a second file beside it.
+      // After a script's Save As to a file no Model lists, the session this tab
+      // shows holds that file (`unlistedFollow`), and a start naming none
+      // asks for it, not for the file the tab was opened on.
+      // The shown file is read as `modelDocumentConflict` reads it (active tab first): the bound pane lags a
+      // tab that just followed a Save As (`../src/start-document.ts`).
+      const document = startDocument({
+        requested: requestedDocument,
+        shown: shownModelBlend(),
+        follow: unlistedFollow !== null && unlistedFollow.owner === session ? unlistedFollow : null,
+        fallback: DEFAULT_BLENDER_DOCUMENT,
+      });
+      const started = await session.start(project!);
+      // A Model document's own open puts its file in this Blender, and this waits for it; a Blender
+      // still holding none (the standing Model of a project with no `.blend`) opens the one asked for.
+      const opened = await queueModelLifecycle(async (): Promise<DocumentOpened | null> => {
+        if (runtime !== session) throw new Error('Blender was discarded before it held a model (its start or open failed); start it again.');
+        if (session.document === null) return openInRuntime(session, document);
+        if (session.document !== document)
+          throw new Error(`Blender resource conflict: the session holds ${session.document}; cannot open ${document}`);
+        return null;
+      });
+      return { ok: true, data: { ...started, ...(opened ?? { document }) } };
+    }
     const session = blenderRuntime();
     switch (cmd.type) {
-      case 'blender-start': {
-        // THE OPEN MODEL DOCUMENT'S `.blend` WINS over the default: a models
-        // project's document is its own `src/models/<name>.blend`, and a
-        // `blender-start` that named none is asking for the session this tab
-        // is showing, not for a second file beside it.
-        // After a script's Save As to a file no Model lists, the session this tab
-        // shows holds that file (`unlistedFollow`), and a start naming none
-        // asks for it, not for the file the tab was opened on.
-        // The shown file is read as `modelDocumentConflict` reads it (active tab first): the bound pane lags a
-        // tab that just followed a Save As (`../src/start-document.ts`).
-        const document = startDocument({
-          requested: requestedDocument,
-          shown: shownModelBlend(),
-          follow: unlistedFollow !== null && unlistedFollow.owner === session ? unlistedFollow : null,
-          fallback: DEFAULT_BLENDER_DOCUMENT,
-        });
-        try {
-          return { ok: true, data: { ...(await startSession(session, project!, document)) } };
-        } catch (error) {
-          // As the document's own open does: a session whose start failed is discarded, so the
-          // next `blender-start` makes a new one instead of awaiting the same failure.
-          if (session.startFailed && runtime === session) terminateBlenderRuntime();
-          throw error;
-        }
-      }
       case 'blender-execute': {
         // Use the in-page script door so every bpy write bumps the shared RNA version. Wire callers receive the original MCP text.
         const answer = await blenderExecute(string(cmd, 'code'));

package/node/blender-mcp.ts

@@ -23,6 +23,7 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import { EditorClient } from '@volter/live/client';
+import { sessionFetch } from '@volter/live/registry-format';
 import type { EditorView } from '@volter/sdk';
 import blenderBundle from '@volter/blender-engine/wasm/BUNDLE.json';
 import { projectOutputRootOf } from '@volter/sdk/project/output-roots';
@@ -158,7 +159,7 @@ class Mirror {
         // only hands over a body. See `/__editor/blender-file`.
         const transferId = randomUUID();
         await tab.commandHeld<{ bytes: number }>('blender-read-file', { path: entry.path, transferId });
-        const spooled = await fetch(`${await tab.origin()}/__editor/blender-file?id=${transferId}`);
+        const spooled = await sessionFetch(`${await tab.origin()}/__editor/blender-file?id=${transferId}`);
         if (!spooled.ok) throw new Error(`Transfer of ${entry.path} failed: ${spooled.status}`);
         const bytes = Buffer.from(await spooled.arrayBuffer());
         if (shipped === null) {
@@ -189,7 +190,7 @@ class Mirror {
           // server validates each one as a project-relative path of its own.
           if (typeof listing.document === 'string' && listing.document !== '')
             query.append('inputs', listing.document);
-          const recorded = await fetch(`${await tab.origin()}/__editor/blender-output?${query}`, {
+          const recorded = await sessionFetch(`${await tab.origin()}/__editor/blender-output?${query}`, {
             method: 'POST',
             body: new Uint8Array(bytes),
           });