@volter/editor-blender 0.1.124 → 0.1.125

package/README.md

@@ -12,6 +12,18 @@ that list through the host's contribution loader.
 Run `npm run typecheck -w @volter/editor-blender` through the active World.
 See LICENSE for the AGPL code and Blender-derived GPL icon notices.
 
+Switching `.blend` documents drains accepted work and saves the previous file
+before retiring its worker and opening the next file. Opens, explicit stops and
+graceful session shutdown share one lifecycle queue. A failed save retains the
+previous worker; a superseded file selection never becomes the current owner.
+If the native workspace remounts the same file's pane during startup, its new
+pane restores the presenter immediately instead of waiting behind the boot
+that needs it. Context cleanup belongs to each publication, so a retiring pane
+cannot withdraw its replacement's publication of the shared view.
+While opening, the document shows the last available model photograph as a
+labeled read-only preview and a loading panel. Without a preview it shows a
+full status surface. A failed open offers Retry and Return to previous model.
+
 This is a private migration staging package. Full editor startup, live editing,
 wire/branding migration and existing-consumer cutover remain unfinished. Passing
 a package build is not proof that the complete editor is ready to release.

package/contributions/blender-model-opening.tsx

@@ -0,0 +1,56 @@
+import type { ModelDocumentPreview } from '../src/model-document-preview';
+import { modelOpeningErrorMessage } from '../src/model-opening-error';
+import { Button, StateSurface, fontSizeVar, spaceVar, themeVars } from '@volter/editor-sdk/widgets';
+import type { AuthoringAdapter, EditorNode } from '@volter/editor-project/adapter';
+import { AssetEditorSubject } from '@volter/editor-sdk/kit/components/AssetEditorShell';
+import { useMemo } from 'react';
+
+/** A loading/error surface has no authoring stage and publishes no model. */
+export function BlenderModelOpening({ documentId, path, error, preview, retry, returnToPreview, preparingView = false }: {
+  readonly documentId: string;
+  readonly path: string;
+  readonly error: string | null;
+  readonly preview: ModelDocumentPreview | null;
+  readonly retry: () => void;
+  readonly returnToPreview: () => void;
+  readonly preparingView?: boolean;
+}) {
+  const title = error ? 'Could not open model' : preparingView ? 'Preparing model view' : 'Opening model';
+  // This document has not published an authoring stage yet. Its panels still
+  // belong to it, rather than the empty project's "Declare a root" fallback.
+  // A boundary row is informational; no old model objects remain editable.
+  const adapter = useMemo<AuthoringAdapter>(() => {
+    const node: EditorNode = { id: `opening:${documentId}`, label: title, secondaryLabel: path,
+      role: 'boundary', kind: 'object', parentId: null, childIds: [] };
+    return { capabilities: { transform: false, inspectorFields: false, persist: false },
+      hierarchy: { roots: () => [node], node: id => id === node.id ? node : null },
+      subscribe: () => () => {} };
+  }, [documentId, path, title]);
+  return (
+    <div data-testid="blender-model-opening" aria-busy={!error}
+      style={{ position: 'absolute', inset: 0, overflow: 'auto', background: themeVars.surface.panel, color: themeVars.content.primary }}>
+      {!preparingView && <AssetEditorSubject key={title} documentId={documentId} type="Model" title={path}
+        status={error ? modelOpeningErrorMessage(error) : title}
+        selection={() => ({ adapter, nodeId: null })} />}
+      {preview && <img src={preview.image} alt={`Last view of ${preview.path}`} draggable={false}
+        style={{ position: 'absolute', inset: 0, width: '100%', height: '100%', objectFit: 'contain', pointerEvents: 'none' }} />}
+      <div style={{ position: 'relative', minHeight: '100%', display: 'flex', flexDirection: 'column', justifyContent: preview ? 'flex-end' : 'center', alignItems: preview ? 'flex-start' : 'center', boxSizing: 'border-box', padding: spaceVar[8], gap: spaceVar[4] }}>
+        {preview && <div style={{ padding: `${spaceVar[2]} ${spaceVar[4]}`, background: themeVars.surface.chrome, border: `1px solid ${themeVars.boundary.default}`, borderRadius: themeVars.shape.small, maxWidth: '100%', overflowWrap: 'anywhere' }}>
+          Previous model: {preview.path} · Preview only
+        </div>}
+        <StateSurface tone={error ? 'error' : 'loading'}
+          style={{ width: 'min(100%, 32rem)', background: themeVars.surface.chrome, border: `1px solid ${themeVars.boundary.default}`, borderRadius: themeVars.shape.small, overflowWrap: 'anywhere' }}
+          title={<span style={{ fontSize: fontSizeVar.lg }}>{title}</span>}
+          description={<>
+            <div style={{ color: themeVars.content.primary, marginBottom: spaceVar[3] }}>{path}</div>
+            {error ? modelOpeningErrorMessage(error) : preparingView ? 'The file is open. Preparing its viewport.' : preview ? 'The previous model stays visible while this file opens.' : 'Preparing Blender and opening this file. The model will appear here when it is ready.'}
+          </>}
+          action={error ? <div style={{ display: 'flex', flexWrap: 'wrap', justifyContent: 'center', gap: spaceVar[3] }}>
+            {preview && <Button onClick={returnToPreview}>Return to previous model</Button>}
+            <Button variant="secondary" onClick={retry}>Retry opening</Button>
+          </div> : <progress aria-label={`Opening ${path}`} style={{ width: 'min(100%, 18rem)', accentColor: themeVars.accent.default }} />}
+        />
+      </div>
+    </div>
+  );
+}

package/contributions/blender-outliner-authoring.ts

@@ -1104,6 +1104,10 @@ export function blenderOutlinerAuthoringFor(
    *  been read, so the same engine selection must be re-derived when the tree
    *  moves under it. */
   let lastEngineKey: string | null = null;
+  // Tree loading publications can arrive before a gesture's write presents.
+  // Keep its optimistic selection until the latest write settles; an older
+  // write's frame must not replace a newer gesture either.
+  let pendingSelection: symbol | null = null;
   /** The world matrix each live gesture started from — see `beginEdit`. */
   const gestureStart = new Map<THREE.Object3D, THREE.Matrix4>();
   // Retain the subject until endEdit, even if a concurrent native edit removes
@@ -1243,6 +1247,7 @@ export function blenderOutlinerAuthoringFor(
    * disagreement this whole unit exists to end.
    */
   const syncFromEngine = (): void => {
+    if (disposed || pendingSelection !== null) return;
     const engine = blenderEngineSelection();
     const key = `${blenderOutlinerVersion()}${engine.active ?? ''}${[...engine.selected]
       .sort()
@@ -1260,6 +1265,9 @@ export function blenderOutlinerAuthoringFor(
   const selection: SelectionProvider = {
     get: () => [...selected],
     set: (ids) => {
+      if (disposed) return;
+      const request = Symbol('Blender selection');
+      pendingSelection = request;
       // NORMALIZED, because ids arrive in BOTH SPACES (the header's "both
       // ways"). A hierarchy click and this adapter's own verbs speak ROW ids;
       // the viewport's MARQUEE speaks the presentation's, because it picks
@@ -1305,7 +1313,16 @@ export function blenderOutlinerAuthoringFor(
         );
       // The ACTIVE is the LAST row the gesture named, which is the shell's own
       // reading of `selectedEntityId` and Blender's of an active object.
-      void writeBlenderSelection(names, names.length === 0 ? null : names[names.length - 1]!);
+      void writeBlenderSelection(names, names.length === 0 ? null : names[names.length - 1]!)
+        .catch(error => editorHost().console.error(
+          `Blender refused the selection write: ${String(error)}`, 'blender-outliner',
+        ))
+        .finally(() => {
+          if (disposed || pendingSelection !== request) return;
+          pendingSelection = null;
+          lastEngineKey = null;
+          syncFromEngine();
+        });
     },
   };
 

package/contributions/blender-runtime.document.tsx

@@ -50,6 +50,7 @@ import {
   Suspense,
   useCallback,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
   useState,
@@ -65,6 +66,7 @@ import {
   blenderViewShading,
   openModelDocumentBlend,
   modelDocumentMayOpen,
+  modelDocumentOwnsPresentation,
 } from '../host/blender-runtime-host';
 import { BlenderObjectModeHeader } from './blender-header-menus';
 import { blenderOutlinerAuthoringFor, createBlenderOutlinerAuthoring } from './blender-outliner-authoring';
@@ -86,6 +88,15 @@ import {
 import type { ToolObject3DAuthoringProps } from '@volter/editor-threejs/object3d-contributions';
 import { stageStore, subscribeStageStores } from '@volter/editor-sdk/kit/stage-store-registry';
 import { surfaceAcceptsKey } from '@volter/editor-sdk/kit/surface-keyboard';
+import { BlenderModelOpening } from './blender-model-opening';
+import { modelOpeningErrorMessage } from '../src/model-opening-error';
+import {
+  clearModelDocumentPreview,
+  modelDocumentPreview,
+  rememberModelDocumentPreview,
+  subscribeModelDocumentPreview,
+  type ModelDocumentPreview,
+} from '../src/model-document-preview';
 
 /** The second areas' stage stores whose overlays have been opened off (`BlenderViewportArea`). */
 const overlaysOpened = new WeakSet<object>();
@@ -211,9 +222,63 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
   const entryId = document?.id;
   const key = JSON.stringify([documentId, entryId, blend]);
   const [opened, setOpened] = useState<{ key: string; error: string | null } | null>(null);
+  const [attempt, setAttempt] = useState(0);
+  const project = editorHost().projectLocalState.projectRootPath();
+  const preview = useSyncExternalStore(subscribeModelDocumentPreview, () => modelDocumentPreview(project), () => null);
+  const viewportVersion = useSyncExternalStore(subscribeDocumentViewports, documentViewportsVersion, documentViewportsVersion);
+  const lastFrame = useRef<ModelDocumentPreview | null>(null);
   const callbacks = useRef({ notify, publishContext });
   callbacks.current = { notify, publishContext };
 
+  useEffect(() => editorHost().session.onEnded(clearModelDocumentPreview), []);
+  // Retain a bounded photograph while the stage is healthy. Teardown can
+  // already have changed its scene/camera, so it is too late to re-render then.
+  useEffect(() => {
+    if (active === false || !documentId || !entryId || !project || opened?.key !== key || opened.error) return;
+    const stage = object3DDocumentSession(documentId);
+    if (!stage) return;
+    let cancelled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const photograph = async () => {
+      try {
+        const presented = view.snapshot();
+        const viewport = documentViewport(documentId);
+        if (!viewport || stage.root !== view.root || !modelDocumentOwnsPresentation(documentId, entryId, blend, presented)) return;
+        const frame = await stage.requestPresentedFrame();
+        if (cancelled || view.snapshot() !== presented ||
+          object3DDocumentSession(documentId) !== stage || stage.root !== view.root || documentViewport(documentId) !== viewport ||
+          !modelDocumentOwnsPresentation(documentId, entryId, blend, presented)) return;
+        if (frame && frame.width > 0 && frame.height > 0) {
+          const copy = window.document.createElement('canvas');
+          copy.width = Math.min(frame.width, 1024);
+          copy.height = Math.max(1, Math.round(copy.width * frame.height / frame.width));
+          const context = copy.getContext('2d');
+          if (context) {
+            context.drawImage(frame, 0, 0, copy.width, copy.height);
+            lastFrame.current = { project, entryId, path: blend ?? 'Model', image: copy.toDataURL('image/png'), capturedAt: performance.now() };
+            rememberModelDocumentPreview(lastFrame.current);
+          }
+        }
+      } catch {
+        // An unavailable frame leaves the last good photograph intact.
+      } finally {
+        if (!cancelled) timer = setTimeout(() => { void photograph(); }, 1000);
+      }
+    };
+    void photograph();
+    return () => { cancelled = true; clearTimeout(timer); };
+  }, [active, blend, documentId, entryId, project, key, opened, viewportVersion]);
+
+  // Publish only an image, never the old file's authoring stage or context.
+  useLayoutEffect(() => {
+    if (active === false || !documentId || !entryId || !project || opened?.key !== key || opened.error) return;
+    return () => {
+      if (!editorHost().session.open()) return;
+      const frame = lastFrame.current;
+      if (frame?.project === project && frame.entryId === entryId) rememberModelDocumentPreview(frame);
+    };
+  }, [active, blend, documentId, entryId, project, key, opened]);
+
   useEffect(() => {
     if (active === false || !documentId) return;
     let cancelled = false;
@@ -250,7 +315,8 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
         unpublish = undefined;
         const detail = error instanceof Error ? error.message : String(error);
         setOpened({ key, error: detail });
-        callbacks.current.notify?.({ tone: 'error', title: `Blender could not open ${blend ?? 'the model'}`, detail });
+        editorHost().console.error(detail, 'blender-open');
+        callbacks.current.notify?.({ tone: 'error', title: `Blender could not open ${blend ?? 'the model'}`, detail: modelOpeningErrorMessage(detail) });
       } finally {
         starting = false;
       }
@@ -272,12 +338,24 @@ export default function BlenderModelDocument(props: ToolContributionProps) {
       unpublish?.();
       unbind();
     };
-  }, [active, blend, documentId, entryId, key]);
+  }, [active, blend, documentId, entryId, key, attempt]);
 
   if (active === false || !documentId) return null;
-  if (opened?.key !== key) return <div role="status">Opening model…</div>;
-  if (opened.error) return <div role="alert">{opened.error}</div>;
-  return <BlenderModelViewport {...props} />;
+  if (opened?.key !== key || opened.error) return <BlenderModelOpening
+    documentId={documentId} path={blend ?? 'Model'} error={opened?.key === key ? opened.error : null} preview={preview}
+    retry={() => { setOpened(null); setAttempt(value => value + 1); }}
+    returnToPreview={() => {
+      if (!preview) return;
+      void editorHost().workspace.open({ kind: 'document', id: preview.entryId }).then(opened => {
+        if (!opened) throw new Error('The previous model is no longer available in this project.');
+      }).catch(error => callbacks.current.notify?.({ tone: 'error', title: 'Could not return to the previous model', detail: String(error) }));
+    }}
+  />;
+  return <>
+    <BlenderModelViewport {...props} />
+    {!documentViewport(documentId) && <BlenderModelOpening documentId={documentId} path={blend ?? 'Model'} error={null}
+      preparingView preview={preview} retry={() => {}} returnToPreview={() => {}} />}
+  </>;
 }
 
 /**
@@ -385,9 +463,12 @@ function BlenderModelViewport(props: ToolContributionProps) {
     if (!modelViewport) return;
     // registerObject3DDocumentSession creates this document's own viewport object; capture may follow its visible play area.
     const capture = modelViewport.capture;
-    modelViewport.capture = (size) => documentViewport(`${documentId}#play`)?.capture?.(size) ?? null;
+    const playCapture = (size: Parameters<NonNullable<typeof capture>>[0]) => documentViewport(`${documentId}#play`)?.capture?.(size) ?? null;
+    modelViewport.capture = playCapture;
     return () => {
-      modelViewport.capture = capture;
+      if (modelViewport.capture !== playCapture) return;
+      if (capture) modelViewport.capture = capture;
+      else delete modelViewport.capture;
     };
   }, [game, documentId]);
   if (!documentId) return null;
@@ -402,7 +483,7 @@ function BlenderModelViewport(props: ToolContributionProps) {
       </div>
       {game && (
         <div key="play" style={{ position: 'absolute', inset: 12 }} data-testid="blender-play-area">
-          <BlenderViewportArea {...props} documentId={`${documentId}#play`} view={game.view} main={false} play onPlayReady={() => setPlayedReady(true)} onPlayReturn={() => setPlayedReady(false)} />
+          <BlenderViewportArea {...props} documentId={`${documentId}#play`} view={game.view} main={false} playing onPlayReady={() => setPlayedReady(true)} onPlayReturn={() => setPlayedReady(false)} />
         </div>
       )}
       {second && (
@@ -489,10 +570,10 @@ function BlenderViewportArea({
   surfaces,
   view,
   main,
-  play = false,
+  playing = false,
   onPlayReady,
   onPlayReturn,
-}: ToolContributionProps & { readonly view: AreaView; readonly main: boolean; readonly play?: boolean; readonly onPlayReady?: () => void; readonly onPlayReturn?: () => void }) {
+}: ToolContributionProps & { readonly view: AreaView; readonly main: boolean; readonly playing?: boolean; readonly onPlayReady?: () => void; readonly onPlayReturn?: () => void }) {
   const reads = readsOf(view);
   const build = useCallback(
     () => ({
@@ -502,7 +583,7 @@ function BlenderViewportArea({
       // and with the skin's poses when the Timeline scrubs. A PLAYING copy announces nothing:
       // its script moves it every frame, and a source that announces nothing is drawn every
       // frame (`ToolObject3DPreviewSource.onChange`).
-      ...(play
+      ...(playing
         ? {}
         : {
             onChange(listener: () => void) {
@@ -516,7 +597,7 @@ function BlenderViewportArea({
           }),
       dispose() {},
     }),
-    [view, play],
+    [view, playing],
   );
   const blend = document?.source?.path;
   // Re-read on the engine's frames, the skin's publications and every drawn frame of this stage
@@ -557,7 +638,7 @@ function BlenderViewportArea({
    */
   useEffect(() => {
     // A playing copy's camera is its script's.
-    if (main || play || !documentId) return;
+    if (main || playing || !documentId) return;
     let entered = false;
     const enter = (): void => {
       if (entered) return;
@@ -572,7 +653,7 @@ function BlenderViewportArea({
       stopSessions();
       stopFrames();
     };
-  }, [main, play, documentId, view]);
+  }, [main, playing, documentId, view]);
   /**
    * THE PLAYING COPY IS MOVED BY THE PROJECT'S PLAY SCRIPT (the document Play extension), on this
    * stage's own frame hook, once the stage stands. The stage's orbit stands down while it runs,
@@ -587,7 +668,7 @@ function BlenderViewportArea({
   const playReturnRef = useRef(onPlayReturn);
   playReturnRef.current = onPlayReturn;
   useEffect(() => {
-    if (!play || !documentId) return;
+    if (!playing || !documentId) return;
     if (blend === undefined) {
       notifyRef.current?.({
         tone: 'error',
@@ -599,7 +680,7 @@ function BlenderViewportArea({
     const modelId = documentId.replace(/#play$/, '');
     const layers = window.document.createElement('div');
     Object.assign(layers.style, { position: 'absolute', inset: '0', pointerEvents: 'none' });
-    layers.dataset.testid = 'model-play-roots';
+    layers.dataset['testid'] = 'model-play-roots';
     surfaceRef.current?.appendChild(layers);
     setPlayReady(false);
     let stopped = false;
@@ -666,7 +747,7 @@ function BlenderViewportArea({
       layers.remove();
       if (orbit) orbit.enabled = true;
     };
-  }, [play, documentId, blend, view]);
+  }, [playing, documentId, blend, view]);
   /**
    * A SHADING PICK IS KEPT WHERE BLENDER KEEPS IT: in the file's own 3D View, the one it reopens
    * on (`blenderViewShading`), so the next save carries it and a reopen starts from it. Noted on
@@ -836,7 +917,7 @@ function BlenderViewportArea({
    */
   const cursorPress = useRef<{ id: number; x: number; y: number } | null>(null);
   const cursorChord = (event: ReactPointerEvent | ReactMouseEvent): boolean =>
-    !play && event.button === 2 && event.shiftKey && event.target instanceof HTMLCanvasElement;
+    !playing && event.button === 2 && event.shiftKey && event.target instanceof HTMLCanvasElement;
   const onPointerDownCapture = (event: ReactPointerEvent): void => {
     if (!cursorChord(event)) {
       cursorPress.current = null;
@@ -885,8 +966,8 @@ function BlenderViewportArea({
   return (
     <div
       ref={surfaceRef}
-      data-play-ready={play ? playReady : undefined}
-      style={play ? { position: 'absolute', inset: 0 } : { display: 'contents' }}
+      data-play-ready={playing ? playReady : undefined}
+      style={playing ? { position: 'absolute', inset: 0 } : { display: 'contents' }}
       onPointerDownCapture={onPointerDownCapture}
       onPointerUpCapture={onPointerUpCapture}
       onPointerCancelCapture={dropCursorPress}
@@ -915,7 +996,7 @@ function BlenderViewportArea({
       // "Inspection parity", I3).
       // A PLAYING COPY HAS NO AUTHORING: it is read-only to the editor, and what moves it is its
       // script. With none given the stage is the native read-only one.
-      {...(play ? {} : { authoring })}
+      {...(playing ? {} : { authoring })}
       cameraDirection={[0.8187, 0.4458, 0.3617]}
       // FOR A FILE THAT SAVED NO 3D VIEW: Blender's factory Modeling direction, standing back
       // three fits.

package/host/blender-runtime-host.ts

@@ -324,6 +324,22 @@ export function modelDocumentMayOpen(binding: ModelDocumentBinding): boolean {
   return !anotherModel || active === binding.documentId;
 }
 
+/** A retained photograph must belong to the file and revision still on screen,
+ * not a retiring pane or the next worker's first frame. */
+export function modelDocumentOwnsPresentation(
+  documentId: string,
+  entryId: string,
+  blend: string | undefined,
+  presented: { readonly session: string; readonly revision: number } | null,
+): boolean {
+  const binding = boundModel;
+  const latest = runtime?.presented;
+  return editorHost().session.open() && !!binding && binding.documentId === documentId && binding.entryId === entryId &&
+    binding.blend === blend && modelDocumentMayOpen(binding) &&
+    runtime?.project === editorHost().projectLocalState.projectRootPath() && runtime.document === blend &&
+    !!presented && !!latest && presented.session === latest.session && presented.revision === latest.revision;
+}
+
 /**
  * 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
@@ -334,22 +350,73 @@ export function modelDocumentMayOpen(binding: ModelDocumentBinding): boolean {
  * identity. Boot itself can present, so the context must exist before awaiting
  * boot completion. 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;
+
+function queueModelLifecycle<T>(operation: () => Promise<T>): Promise<T> {
+  const result = modelOpenTail.then(operation);
+  modelOpenTail = result.then(() => {}, () => {});
+  return result;
+}
+
 export async function openModelDocumentBlend(
   binding: ModelDocumentBinding,
   publish: () => void,
+): Promise<boolean> {
+  let published = false;
+  const publishOnce = () => {
+    if (published) return;
+    publish();
+    published = true;
+  };
+  const host = editorHost();
+  const starting = modelStartup;
+  // A native workspace restore can remount this pane before boot's first
+  // frame. Its predecessor has unpublished, but still owns the queued boot:
+  // waiting behind it before publishing would make boot wait on itself.
+  // Only the SAME starting resource can restore its presenter here. Another
+  // file still waits for the old worker's save/retirement in the queue.
+  if (starting && starting.session === runtime && host.session.open() &&
+      starting.project === host.projectLocalState.projectRootPath() &&
+      starting.blend === binding.blend && modelDocumentMayOpen(binding)) {
+    publishOnce();
+  }
+  // Only one handoff may own stop/start. Re-check the mounted requester after
+  // every wait: a rapid B -> C selection must not let B publish into C.
+  return queueModelLifecycle(() => openBoundModelDocument(binding, publishOnce));
+}
+
+async function openBoundModelDocument(
+  binding: ModelDocumentBinding,
+  publish: () => void,
 ): Promise<boolean> {
   const host = editorHost();
   if (!host.session.open()) throw new Error('Opening a model requires an open project session.');
   const project = host.projectLocalState.projectRootPath();
   if (project === null) throw new Error('Opening a model requires a project path.');
   if (!modelDocumentMayOpen(binding)) return false;
+  const previous = runtime;
+  if (previous && (previous.project !== project || previous.document !== binding.blend)) {
+    // stop drains accepted work and flushes the OLD worker's bound file. If
+    // saving fails it stays alive; neither its history nor its ownership moves.
+    const end = beginBlenderWork('saving previous model before opening another');
+    try { await previous.stop(); } 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 = session.start(project, binding.blend);
-  publish();
-  await started;
-  if (boundModel !== binding) return false;
+  const starting = { session, project, blend: binding.blend };
+  modelStartup = starting;
+  try {
+    publish();
+    await started;
+  } finally {
+    if (modelStartup === starting) modelStartup = null;
+  }
+  if (!host.session.open() || !modelDocumentMayOpen(binding)) return false;
   // bind_document presents the opened file before start resolves. Do not
   // immediately evaluate/export it again: on Stoneguard that redundant RPC
   // took 13.8 seconds after the resumable startup had already finished.
@@ -357,12 +424,12 @@ export async function openModelDocumentBlend(
   // nothing at start. Compare the view's actual holding with the runtime's
   // revision so both cases still request the frame they need.
   const shown = (await runtimeView()).snapshot();
-  if (boundModel !== binding) return false;
+  if (!host.session.open() || !modelDocumentMayOpen(binding)) return false;
   const latest = session.presented;
   if (!shown || !latest || shown.session !== latest.session || shown.revision !== latest.revision) {
     await session.present();
   }
-  return boundModel === binding;
+  return host.session.open() && modelDocumentMayOpen(binding);
 }
 
 /**
@@ -802,12 +869,15 @@ function terminateBlenderRuntime(): void {
 function watchSessionEnd(): void {
   if (watchingSessionEnd) return;
   watchingSessionEnd = true;
-  editorHost().session.onBeforeClose(async () => {
-    await runtime?.stop();
-    terminateBlenderRuntime();
-  });
+  editorHost().session.onBeforeClose(() => queueModelLifecycle(stopBlenderRuntime));
   editorHost().session.onEnded(terminateBlenderRuntime);
 }
+
+async function stopBlenderRuntime(): Promise<void> {
+  const owner = runtime;
+  await owner?.stop();
+  if (runtime === owner) terminateBlenderRuntime();
+}
 let lastCapture: CaptureRequest | null = null;
 
 const isRuntimeView = (value: unknown): value is RuntimeView =>
@@ -1208,8 +1278,7 @@ export async function handleBlenderCommand(cmd: {
     let requestedDocument = typeof cmd['document'] === 'string' ? cmd['document'] : undefined;
     if (cmd.type === 'blender-stop' || (cmd.type === 'blender-start' && cmd['fresh'] === true)) {
       // Do not invalidate history or discard the worker if persistence fails.
-      await runtime?.stop();
-      terminateBlenderRuntime();
+      await queueModelLifecycle(stopBlenderRuntime);
       if (cmd.type === 'blender-stop') return { ok: true, data: { stopped: true } };
     }
     if (cmd.type === 'blender-start' && !host.documents.context(presentationDocumentId())) {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/editor-blender",
   "author": "Volter AI, Inc.",
   "license": "AGPL-3.0-only AND GPL-3.0-or-later",
-  "version": "0.1.124",
+  "version": "0.1.125",
   "publishConfig": {
     "access": "public"
   },
@@ -69,15 +69,15 @@
     "serving": "./dist-node/serving.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "1.30.0",
-    "@volter/blender-engine": "0.1.122",
-    "@volter/editor-threejs": "0.5.185",
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@volter/blender-engine": "0.1.123",
+    "@volter/editor-threejs": "0.5.186",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@volter/editor-live": "0.5.185",
-    "@volter/editor-project": "0.5.185",
-    "@volter/editor-sdk": "0.5.185",
+    "@volter/editor-live": "0.5.186",
+    "@volter/editor-project": "0.5.186",
+    "@volter/editor-sdk": "0.5.186",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "three": "^0.180.0",

package/src/model-document-preview.ts

@@ -0,0 +1,46 @@
+/** One last photograph, never a live model or an editable document context. */
+export interface ModelDocumentPreview {
+  readonly project: string;
+  readonly entryId: string;
+  readonly path: string;
+  readonly image: string;
+  readonly capturedAt: number;
+}
+
+let preview: ModelDocumentPreview | null = null;
+const listeners = new Set<() => void>();
+let queued = false;
+
+function changed(): void {
+  // A pane captures during layout cleanup; notify other roots after the commit.
+  if (queued) return;
+  queued = true;
+  queueMicrotask(() => {
+    queued = false;
+    for (const listener of [...listeners]) listener();
+  });
+}
+
+export function rememberModelDocumentPreview(value: ModelDocumentPreview): void {
+  // Retained panes may clean up after their replacement. An older photograph
+  // must not overwrite the most recent visible model's frame.
+  if (preview?.project === value.project && preview.capturedAt > value.capturedAt) return;
+  if (preview === value) return;
+  preview = value;
+  changed();
+}
+
+export function clearModelDocumentPreview(): void {
+  if (!preview) return;
+  preview = null;
+  changed();
+}
+
+export function modelDocumentPreview(project: string | null): ModelDocumentPreview | null {
+  return preview?.project === project ? preview : null;
+}
+
+export function subscribeModelDocumentPreview(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}

package/src/model-opening-error.ts

@@ -0,0 +1,12 @@
+/** Worker details remain in the console. The opening panel explains recovery. */
+export function modelOpeningErrorMessage(detail: string): string {
+  if (/file format is not supported|not a blend file/i.test(detail))
+    return 'This file is not a supported Blender model. Choose a valid .blend file or return to the previous model.';
+  if (/EACCES|permission denied|read-only file system/i.test(detail))
+    return 'Blender could not access the model file. Check its file permissions, then try again.';
+  if (/ENOENT|no such file|file not found/i.test(detail))
+    return 'The model file could not be found. Check that it still exists, or return to the previous model.';
+  if (/failed to fetch|networkerror|network error/i.test(detail))
+    return 'Blender could not finish loading. Check your connection, then try again.';
+  return 'Blender could not open this model. Try again, or return to the previous model. Details are available in the console.';
+}