@volter/editor-blender 0.1.5 → 0.1.7

package/contributions/blender-properties-model.ts

@@ -170,6 +170,9 @@ let readFor: string | null = null;
  * A late answer for a deleted duplicate must not overwrite the new selection. */
 let readGeneration = 0;
 let contextRequest = 0;
+/** Views read at the current generation. A held view outside this set is
+ *  STALE: still shown, re-read on the next ask. */
+const fresh = new Set<string>();
 
 function publish(next: Partial<BlenderPropertiesState>, tabsMayHaveChanged = false): void {
   state = { ...state, ...next };
@@ -207,12 +210,17 @@ export function blenderPropertiesState(): BlenderPropertiesState {
  *  presenter draws ships no frame, and before this the rail simply kept the
  *  values it had. */
 function onEngineMoved(): void {
+  // STALE, NOT EMPTY. The generation moves, so every answer already in flight
+  // is dropped when it lands (a deleted duplicate's late read cannot overwrite
+  // the new selection) -- but the panel keeps showing what it holds until the
+  // re-read answers. Clearing here blanked and repainted the whole Properties
+  // panel on every edit, because every edit presents a frame.
   const subject = readFor;
   readGeneration += 1;
   inFlight.clear();
-  readFor = null;
-  publish({ context: null, views: new Map(), error: null, loading: subject !== null });
-  if (subject !== null) scheduleContextRead(subject);
+  fresh.clear();
+  if (subject !== null) scheduleContextRead(subject, true);
+  else publish({});
 }
 
 // THE FRAME IS ONE SIGNAL AND THE RNA DOOR IS THE OTHER. This subscription is
@@ -235,13 +243,13 @@ subscribeBlenderRna(() => {
  */
 let scheduledKey: string | null = null;
 
-function scheduleContextRead(key: string): void {
+function scheduleContextRead(key: string, refresh = false): void {
   if (scheduledKey === key) return;
   scheduledKey = key;
   setTimeout(() => {
     if (scheduledKey !== key) return;
     scheduledKey = null;
-    void readContext(key);
+    void readContext(key, refresh);
   }, 0);
 }
 
@@ -267,20 +275,30 @@ function watchFrames(): void {
   frameSubscription = view.subscribeFrames(noteBlenderRnaChanged);
 }
 
-async function readContext(key: string): Promise<void> {
+async function readContext(key: string, refresh = false): Promise<void> {
   const collection = key.startsWith('collection:') ? key.slice('collection:'.length) : null;
   const object = collection === null && key !== '' ? key : null;
+  // A REFRESH re-reads the subject already shown and keeps it on screen; a new
+  // subject starts empty, because nothing held belongs to it.
+  const sameSubject = refresh && readFor === key;
   if (readFor !== key) {
     readGeneration += 1;
     inFlight.clear();
+    fresh.clear();
   }
   const generation = readGeneration;
   const request = ++contextRequest;
   readFor = key;
-  publish({ loading: true, object, collection, context: null, error: null, views: new Map() });
+  const previous = sameSubject ? state.context : null;
+  if (!sameSubject) publish({ loading: true, object, collection, context: null, error: null, views: new Map() });
   try {
     const context = await blenderRnaContext(object ?? undefined, collection ?? undefined);
     if (generation !== readGeneration || request !== contextRequest) return;
+    if (sameSubject && JSON.stringify(context) === JSON.stringify(previous)) {
+      // Nothing the tab rail matches on moved: no rail recomposition.
+      publish({ loading: false, error: null });
+      return;
+    }
     // ALWAYS a tab-rail notification, and that is a correction rather than a
     // convenience: the gate a tab matches on is BOTH the subject this context
     // was read for and the tab list, so comparing only the list missed the
@@ -314,14 +332,16 @@ export function showBlenderSubject(subject: BlenderSubject): void {
  *  "not read yet", which is what a section renders as its loading state. */
 export function blenderRnaViewFor(path: string): BlenderRnaView | undefined {
   const held = state.views.get(path);
-  if (held !== undefined) return held;
-  if (inFlight.has(path) || !blenderSessionStarted()) return undefined;
+  if (held !== undefined && fresh.has(path)) return held;
+  // A stale view is shown while its re-read is in flight.
+  if (inFlight.has(path) || !blenderSessionStarted()) return held;
   inFlight.add(path);
   const generation = readGeneration;
   void blenderRna(path)
     .then((view) => {
       if (generation !== readGeneration) return;
       inFlight.delete(path);
+      fresh.add(path);
       if (view === null) return;
       const views = new Map(state.views);
       views.set(path, view);
@@ -332,7 +352,7 @@ export function blenderRnaViewFor(path: string): BlenderRnaView | undefined {
       inFlight.delete(path);
       publish({ error: describe(error) });
     });
-  return undefined;
+  return held;
 }
 
 /**
@@ -351,9 +371,8 @@ export async function writeBlenderRnaProperty(
     await blenderRnaSet(path, property, value, index);
     // The write presented; a re-read of this one datablock closes the loop
     // even if the frame listener has not been taken yet.
-    const views = new Map(state.views);
-    views.delete(path);
-    publish({ views, error: null });
+    fresh.delete(path);
+    publish({ error: null });
     return true;
   } catch (error) {
     publish({ error: describe(error) });

package/contributions/blender-runtime.document.tsx

@@ -27,7 +27,7 @@
 import { blenderModelView } from '@volter/blender-engine/browser/three/blender-runtime-view';
 import type { ToolContributionProps, ToolDocumentToolbar } from '@volter/editor-sdk/contributions';
 import { editorHost } from '@volter/editor-sdk/host';
-import { useCallback, useEffect } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 import * as THREE from 'three';
 import { bindModelDocument, openModelDocumentBlend } from '../host/blender-runtime-host';
 import { BlenderObjectModeHeader } from './blender-header-menus';
@@ -79,17 +79,78 @@ export const inspectorBuiltins: readonly string[] = [];
 // one set of presented objects (`blender-runtime-skin.ts`).
 const view = blenderModelView;
 
-export default function BlenderModelDocument({
+export default function BlenderModelDocument(props: ToolContributionProps) {
+  const { active, document, documentId, notify, publishContext } = props;
+  const blend = document?.source?.path;
+  const entryId = document?.id;
+  const key = JSON.stringify([documentId, entryId, blend]);
+  const [opened, setOpened] = useState<{ key: string; error: string | null } | null>(null);
+  const callbacks = useRef({ notify, publishContext });
+  callbacks.current = { notify, publishContext };
+
+  useEffect(() => {
+    if (active === false || !documentId) return;
+    let cancelled = false;
+    let unpublish: (() => void) | undefined;
+    const binding = blend === undefined ? null : { documentId, entryId: entryId!, blend };
+    const unbind = bindModelDocument(binding);
+    const publish = () => { unpublish = callbacks.current.publishContext?.(view); };
+    setOpened(null);
+    void (async () => {
+      try {
+        if (binding) {
+          if (!await openModelDocumentBlend(binding, publish)) return;
+        } else {
+          // The standing Model document is the explicit blender-start target.
+          publish();
+        }
+        if (!cancelled) setOpened({ key, error: null });
+      } catch (error) {
+        if (cancelled) return;
+        unpublish?.();
+        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 });
+      }
+    })();
+    return () => {
+      cancelled = true;
+      unpublish?.();
+      unbind();
+    };
+  }, [active, blend, documentId, entryId, key]);
+
+  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} />;
+}
+
+function BlenderModelViewport({
   active,
   document,
   documentId,
   surfaces,
-  notify,
-  publishContext,
 }: ToolContributionProps) {
-  const build = useCallback(() => ({ root: view.root, dispose() {} }), []);
+  const build = useCallback(
+    () => ({
+      root: view.root,
+      // What the view draws changes with each frame and the work after it,
+      // and with the skin's poses when the Timeline scrubs.
+      onChange(listener: () => void) {
+        const stopView = view.onChange(listener);
+        const stopSkin = blenderSkin.subscribe(listener);
+        return () => {
+          stopView();
+          stopSkin();
+        };
+      },
+      dispose() {},
+    }),
+    [],
+  );
   const blend = document?.source?.path;
-  useEffect(() => publishContext?.(view), [publishContext]);
   /**
    * THE INSPECTION OVERLAYS ARE HELPERS, and the Helpers menu owns them
    * (WORK.md §Blender in the tab is Blender, "Inspection parity", I4).
@@ -149,29 +210,6 @@ export default function BlenderModelDocument({
       detach?.();
     };
   }, [documentId]);
-  useEffect(() => {
-    if (!documentId) return;
-    if (blend === undefined) {
-      // Opened by address: the session names its own document.
-      bindModelDocument(null);
-      return;
-    }
-    // A FRESHLY OPENED MODEL DOCUMENT PRESENTS WITHOUT AN EXECUTE. Every
-    // mutation presents (`session.py::dispatch`), so the document only ever
-    // received a frame once something had RUN — open a `.blend` and the
-    // viewport stayed empty until a `vgai blender-exec`. The first present is
-    // the document's to ask for, because opening a document IS the request to
-    // see what is in it (I1 found this; WORK.md §Blender in the tab is
-    // Blender, "Inspection parity", I2 decision 6).
-    void openModelDocumentBlend(documentId, blend, document!.id).catch((error: unknown) => {
-      notify?.({
-        tone: 'error',
-        title: `Blender could not open ${blend}`,
-        detail: error instanceof Error ? error.message : String(error),
-      });
-    });
-    return () => bindModelDocument(null);
-  }, [blend, document?.id, documentId, notify]);
   if (!documentId) return null;
   const Surface = surfaces.Object3DAuthoring;
   return (

package/host/blender-runtime-host.ts

@@ -206,13 +206,40 @@ export const BLENDER_RUNTIME_DOCUMENT_ID = 'document:blender:runtime';
  * package: the document that binds it and the session that reads it ship
  * together, so there is nothing for the SDK to carry.
  */
-let boundModel: { readonly documentId: string; readonly entryId: string; readonly blend: string } | null = null;
+export interface ModelDocumentBinding {
+  readonly documentId: string;
+  readonly entryId: string;
+  readonly blend: string;
+}
+
+let boundModel: ModelDocumentBinding | null = null;
+let modelBindingGeneration = 0;
 
-/** Called by the Model document when it mounts (and with `null` when it
- *  unmounts): the document id the host published its context under, and the
- *  project-relative `.blend` the engine should have open. */
-export function bindModelDocument(bound: { documentId: string; entryId: string; blend: string } | null): void {
+/** Bind the mounted Model document; the returned cleanup releases only this
+ * binding. `null` names the standing Model without a file entry. */
+export function bindModelDocument(bound: ModelDocumentBinding | null): () => void {
+  const generation = ++modelBindingGeneration;
   boundModel = bound;
+  noteBlenderRnaChanged();
+  return () => {
+    // An old pane's asynchronous cleanup must not unbind its replacement.
+    if (modelBindingGeneration !== generation) return;
+    boundModel = null;
+    noteBlenderRnaChanged();
+  };
+}
+
+function modelDocumentConflict(): string | null {
+  const held = runtime?.document;
+  // The finder owns model:<path>, wrapped by the host as document:<entry>.
+  // Read the active address too: activation precedes the contributed pane's
+  // effect, so an immediate command must not slip through that binding gap.
+  const activeId = editorHost().documents.activeId();
+  const requested = activeId?.startsWith('document:model:')
+    ? activeId.slice('document:model:'.length)
+    : boundModel?.blend;
+  if (!requested || !held || requested === held) return null;
+  return `Blender is editing ${held}; ${requested} is not open. Return to ${held} before editing.`;
 }
 
 /** The document id a present must reach: the open Model document's, or the
@@ -233,25 +260,35 @@ export function blenderPresentationDocumentId(): string {
  * path run backwards. `session.py` opens the named file at start and saves
  * back to it, so naming it here IS opening it.
  *
- * Idempotent and quiet: the runtime binds one project and one document for the
- * tab's lifetime, so a second Model document mounting over a live session
- * simply presents what that session holds. A project with no open session has
- * no engine to open anything in, and says nothing.
+ * 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.
  */
-export async function openModelDocumentBlend(documentId: string, blend: string, entryId: string): Promise<void> {
-  bindModelDocument({ documentId, entryId, blend });
+export async function openModelDocumentBlend(
+  binding: ModelDocumentBinding,
+  publish: () => void,
+): Promise<boolean> {
   const host = editorHost();
-  if (!host.session.open()) return;
+  if (!host.session.open()) throw new Error('Opening a model requires an open project session.');
   const project = host.projectLocalState.projectRootPath();
-  if (project === null) return;
-  await blenderRuntime().start(project, blend);
+  if (project === null) throw new Error('Opening a model requires a project path.');
+  if (boundModel !== binding || host.documents.activeId() !== binding.documentId) 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;
   // AND SHOW WHAT IT OPENED. `start` binds the document and loads the file; it
   // does not present, because presenting is what a MUTATION does
   // (`session.py::dispatch`). So until this line a freshly opened Model
   // document displayed nothing until an execute happened to run — I1 measured
   // it, and "open a model, see the model" is the document's own request rather
   // than a side effect to hope for.
-  await blenderRuntime().present();
+  await session.present();
+  return boundModel === binding;
 }
 
 /**
@@ -268,7 +305,7 @@ export async function openModelDocumentBlend(documentId: string, blend: string,
  * the same reason.
  */
 export function blenderSessionStarted(): boolean {
-  return runtime?.project != null;
+  return runtime?.project != null && modelDocumentConflict() === null;
 }
 
 /**
@@ -650,13 +687,24 @@ 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 {
+  try {
+    const end = editorHost().session.beginWork(`Blender: ${label}`);
+    return () => { try { end(); } catch { /* preserve the operation's result */ } };
+  } catch { return () => {}; }
+}
+
 function terminateBlenderRuntime(): void {
-  invalidateBlenderHistory();
-  captureLifetime?.abort();
-  captureLifetime = null;
-  runtime?.terminate();
-  runtime = null;
-  lastCapture = null;
+  const end = beginBlenderWork('invalidating history and releasing runtime');
+  try {
+    invalidateBlenderHistory();
+    captureLifetime?.abort();
+    captureLifetime = null;
+    runtime?.terminate();
+    runtime = null;
+    lastCapture = null;
+  } finally { end(); }
 }
 
 // THE ENGINE DIES WITH THE SESSION, whether or not the tab can. A page told
@@ -690,23 +738,39 @@ const isRuntimeView = (value: unknown): value is RuntimeView =>
 
 async function runtimeView(): Promise<RuntimeView> {
   const { documents } = editorHost();
-  const published = await documents.waitForContext(presentationDocumentId(), 15_000);
-  if (isRuntimeView(published)) return published;
+  // THE ID IS RE-READ WHILE WAITING. Which document a present reaches depends
+  // on the Model document's binding (`presentationDocumentId`), and at startup
+  // a present can begin before that pane has bound: reading the id once made
+  // it wait the whole window for `document:blender:runtime`, which a
+  // file-backed Model never publishes, while its own document published beside
+  // it -- the battery's preflight failed exactly so, 18 s after its first
+  // command (3 s of boot, then the full wait).
+  const deadline = Date.now() + 15_000;
+  let id = presentationDocumentId();
+  for (;;) {
+    id = presentationDocumentId();
+    const published = await documents.waitForContext(id, Math.max(0, Math.min(250, deadline - Date.now())));
+    if (isRuntimeView(published)) return published;
+    if (Date.now() >= deadline) break;
+  }
   throw new Error(
-    'The Blender Model document is not open, or the open one is not a Model this engine can present ' +
-      'to (it must answer applyFrame, captureSnapshot, recordPresentation and recordPhotograph): present ' +
-      '{kind: "document", id: "blender:runtime"} ' +
-      'first (it ships with the editor; `vgai blender-mcp` presents it before its first call).',
+    `The Blender Model document is not open, or the open one is not a Model this engine can present ` +
+      `to (it must answer applyFrame, captureSnapshot, recordPresentation and recordPhotograph): nothing ` +
+      `published a presentable view as ${id} within 15 s (bound model: ${boundModel?.documentId ?? 'none'}). ` +
+      'Open the Model document first (`vgai blender-mcp` opens it before its first call).',
   );
 }
 
 export function blenderRuntime(): BlenderRuntime {
+  const conflict = modelDocumentConflict();
+  if (conflict) throw new Error(conflict);
   if (runtime !== null) return runtime;
   watchSessionEnd();
   const lifetime = new AbortController();
   captureLifetime = lifetime;
   let photographing = false;
   runtime = new BlenderRuntime({
+    work: beginBlenderWork,
     history: (entries) => {
       const owner = runtime;
       if (!owner) throw new Error('Blender history arrived before its runtime');
@@ -735,8 +799,12 @@ export function blenderRuntime(): BlenderRuntime {
       }
     },
     present: async (frame, description, capture) => {
+      const conflict = modelDocumentConflict();
+      if (conflict) throw new Error(conflict);
       const documentId = presentationDocumentId();
-      const view = await runtimeView();
+      const endWait = beginBlenderWork('waiting for Model presenter');
+      let view: RuntimeView;
+      try { view = await runtimeView(); } finally { endWait(); }
       lifetime.signal.throwIfAborted();
       if (presentationDocumentId() !== documentId)
         throw new Error('Blender document changed before its frame could be presented');
@@ -747,7 +815,11 @@ export function blenderRuntime(): BlenderRuntime {
       // still-running worker (`blender-runtime-view.ts::applyFrame` says how).
       // A document that answers `applyFrame` without one reports no `held` at
       // all, rather than a wrong `null`.
-      const applied = view.applyFrame(frame) as { held?: unknown } | null | undefined;
+      const endApply = beginBlenderWork('applying frame to Model');
+      const applied = (() => {
+        try { return view.applyFrame(frame) as { held?: unknown } | null | undefined; }
+        finally { endApply(); }
+      })();
       const reports = typeof applied === 'object' && applied !== null && 'held' in applied;
       const held = reports ? (applied.held as { session: string; revision: number } | null) : null;
       const answer = (capture: unknown): PresentAnswer => ({
@@ -893,6 +965,7 @@ export function blenderRuntime(): BlenderRuntime {
         await snapshot.prepare(renderCamera);
         assertBinding();
         const captureOptions = {
+          effect: snapshot.effect,
           width: render.width,
           height: render.height,
           transparent: render.transparent === true,

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.5",
+  "version": "0.1.7",
   "publishConfig": {
     "access": "public"
   },
@@ -61,13 +61,13 @@
     ]
   },
   "dependencies": {
-    "@volter/blender-engine": "0.1.5",
-    "@volter/editor-threejs": "0.5.62",
+    "@volter/blender-engine": "0.1.7",
+    "@volter/editor-threejs": "0.5.64",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@volter/editor-sdk": "*",
-    "@volter/editor-project": "*",
+    "@volter/editor-sdk": "0.5.64",
+    "@volter/editor-project": "0.5.64",
     "react": "^19.0.0",
     "three": "^0.180.0"
   },