@volter/blender-engine 0.1.1 → 0.1.3

package/browser/protocol.ts

@@ -2,6 +2,7 @@
  * worker; the model lives in the worker's Python and nowhere else. */
 
 export type WorkerRequest =
+  | { id: number; op: 'flush-document' }
   | { id: number; op: 'history-begin' | 'history-end' }
   | { id: number; op: 'history-step'; token: string; direction: 'undo' | 'redo' }
   /** `document` is the session's `.blend`, PROJECT-RELATIVE (`models/model.blend`
@@ -93,6 +94,7 @@ export type WorkerRequest =
     };
 
 export type WorkerReply =
+  | { op: 'document-dirty'; dirty: boolean }
   | { op: 'history'; entries: NativeHistoryEntry[] }
   | { id: number; result: unknown }
   | { id: number; error: string }

package/browser/runtime.ts

@@ -139,6 +139,14 @@ export class BlenderRuntime {
   >();
   #nextId = 0;
   #started: Promise<RuntimeStart> | null = null;
+  #stopping: Promise<void> | null = null;
+  #terminated = false;
+  #dirty = false;
+  readonly #beforeUnload = (event: BeforeUnloadEvent): void => {
+    if (!this.#dirty && this.#pending.size === 0) return;
+    event.preventDefault();
+    event.returnValue = '';
+  };
   /** `performance.now()` at the `postMessage` of every outstanding call. */
   readonly #callStarts = new Map<number, number>();
   #lastCallMs: number | null = null;
@@ -157,6 +165,7 @@ export class BlenderRuntime {
       type: 'module',
       name: 'blender',
     });
+    globalThis.addEventListener?.('beforeunload', this.#beforeUnload);
     this.#worker.onmessage = (event: MessageEvent<WorkerReply>) => void this.#receive(event.data);
     this.#worker.onerror = (event) => {
       // A module worker that fails to LOAD reports an ErrorEvent with an empty
@@ -410,7 +419,29 @@ export class BlenderRuntime {
     return this.#presented;
   }
 
+  /** Drain accepted calls and persist the document before destroying its only
+   * copy. A failed save keeps the worker alive so the caller can retry. */
+  stop(): Promise<void> {
+    if (this.#terminated) return Promise.resolve();
+    if (this.#stopping) return this.#stopping;
+    this.#stopping = (async () => {
+      if (this.#started) {
+        await this.#started;
+        await this.#request({ op: 'flush-document' }, true);
+      }
+      this.terminate();
+    })().catch(error => {
+      this.#stopping = null;
+      throw error;
+    });
+    return this.#stopping;
+  }
+
+  /** Forced teardown for a lost session; explicit user stops must use stop(). */
   terminate(): void {
+    if (this.#terminated) return;
+    this.#terminated = true;
+    globalThis.removeEventListener?.('beforeunload', this.#beforeUnload);
     this.#worker.terminate();
     const error = new Error('The Blender session was terminated');
     for (const id of [...this.#pending.keys()]) this.#settled(id);
@@ -470,7 +501,9 @@ export class BlenderRuntime {
       this.#lastCallWindow = { start: started, end: started + elapsed };
   }
 
-  #request(request: Request): Promise<unknown> {
+  #request(request: Request, shutdown = false): Promise<unknown> {
+    if (this.#terminated || (this.#stopping && !shutdown))
+      return Promise.reject(new Error('The Blender session is stopping or terminated'));
     const id = ++this.#nextId;
     return new Promise((resolve, reject) => {
       this.#pending.set(id, { resolve, reject });
@@ -483,6 +516,10 @@ export class BlenderRuntime {
 
   async #receive(reply: WorkerReply): Promise<void> {
     if ('op' in reply) {
+      if (reply.op === 'document-dirty') {
+        this.#dirty = reply.dirty;
+        return;
+      }
       if (reply.op === 'history') {
         this.#options.history?.(reply.entries);
         return;

package/browser/worker.ts

@@ -19,18 +19,17 @@
  * before every call, and what the session writes is mirrored back out by the
  * transport (`list-files`/`read-file`).
  *
- * THE DOCUMENT'S DEBOUNCE LIVES HERE, because this is the only side of the
- * session that has a clock. Python's loop cannot ask the tab for anything
+ * THE DOCUMENT'S SAVE BARRIER LIVES HERE. Python's loop cannot ask the tab for anything
  * while it is idle — `serveAsks` only runs inside a request's poll loop, so an
  * `ask` raised between calls is never answered and wedges the Blender pthread.
- * So the session marks a present `saveDue`, this file waits out one idle
- * second, calls `save-document` as an ordinary request (which Python's loop
+ * So the session marks a present `saveDue`, this file finishes the command,
+ * calls `save-document` as an ordinary request (which Python's loop
  * picks up BETWEEN calls, never mid-call), and carries the bytes to the
- * project through `/__editor/blender-document`.
+ * project through `/__editor/blender-document` BEFORE acknowledging the edit.
  *
  * WHY THE CARRY IS NOT THE MIRROR'S JOB (`vgai blender-mcp`, class Mirror):
  * the Mirror is pull-based and runs only after an `execute_blender_code`, so
- * a document saved one idle second after the LAST call of a modeling session
+ * a document saved after the LAST call of a modeling session
  * would never leave the worker — which is exactly the state this closes
  * ("closing the tab loses the model"). The Mirror still lists and mirrors the
  * same file in the MCP lane; it just is not what persistence depends on.
@@ -114,36 +113,29 @@ let engine: BlenderEngine | null = null;
 // the only one that crosses to the server, which joins it to its own root so
 // no host path is ever on the wire.
 let documentPath: string | null = null;
-let saveTimer: ReturnType<typeof setTimeout> | null = null;
-/** Calls the tab is waiting on. A save waits for zero. */
-let callsInFlight = 0;
-
-/** The idle second. One save per second of quiet, however many presents
- *  arrived during it: the timer is RESET by each, so a script presenting in a
- *  tight loop writes the document once, when it stops. */
-const DOCUMENT_SAVE_IDLE_MS = 1_000;
+let documentDirty = false;
+// Commands and saves share one lane. In particular a flush cannot overtake
+// an accepted edit, and a later edit cannot race an upload of older bytes.
+let workTail: Promise<unknown> = Promise.resolve();
+function enqueue<T>(work: () => Promise<T>): Promise<T> {
+  const result = workTail.then(work);
+  workTail = result.catch(() => undefined);
+  return result;
+}
 
-function armDocumentSave(): void {
-  if (documentPath === null) return;
-  if (saveTimer !== null) clearTimeout(saveTimer);
-  saveTimer = setTimeout(() => {
-    saveTimer = null;
-    void saveDocument();
-  }, DOCUMENT_SAVE_IDLE_MS);
+function setDocumentDirty(dirty: boolean): void {
+  documentDirty = dirty;
+  post({ op: 'document-dirty', dirty });
 }
 
 /**
  * Save the document and land it in the project.
  *
- * NEVER MID-CALL: a call still outstanding means a script is running, and its
- * half-built model is not the document. The timer re-arms instead of writing.
+ * Only called inside the command lane, after previous calls have finished.
+ * Failure is a rejection: explicit shutdown must retain the live model.
  */
 async function saveDocument(): Promise<void> {
   if (!engine || documentPath === null) return;
-  if (callsInFlight > 0) {
-    armDocumentSave();
-    return;
-  }
   const relative = documentPath;
   let answer: { saved?: boolean; path?: string; size?: number };
   try {
@@ -151,22 +143,15 @@ async function saveDocument(): Promise<void> {
   } catch (error) {
     // A document that cannot be written is the session's work at risk, so it
     // is a named condition in the editor's console, not a debug line.
-    log(
-      'error',
-      `@@VGAI-ERROR the Blender document ${relative} could not be saved: ${describeThrown(error)}`,
-    );
-    return;
+    throw new Error(`The Blender document ${relative} could not be saved: ${describeThrown(error)}`);
   }
-  if (!answer?.saved || typeof answer.path !== 'string') return;
+  if (!answer?.saved || typeof answer.path !== 'string')
+    throw new Error(`Blender did not save the document ${relative}`);
   let bytes: Uint8Array;
   try {
     bytes = await engine.files.readFile(answer.path);
   } catch (error) {
-    log(
-      'error',
-      `@@VGAI-ERROR the Blender document ${relative} was saved but could not be read back out of the engine: ${describeThrown(error)}`,
-    );
-    return;
+    throw new Error(`The Blender document ${relative} could not be read back out of the engine: ${describeThrown(error)}`);
   }
   // The engine's copy is now the newer one, so the stager must stop treating
   // this path as the host's: an entry left in `staged` would make the next
@@ -181,19 +166,12 @@ async function saveDocument(): Promise<void> {
     });
     if (!posted.ok) {
       const said = await posted.text().catch(() => '');
-      log(
-        'error',
-        `@@VGAI-ERROR the Blender document ${relative} was not written to the project: HTTP ${posted.status} ${said}`,
-      );
-      return;
+      throw new Error(`HTTP ${posted.status} ${said}`);
     }
   } catch (error) {
-    log(
-      'error',
-      `@@VGAI-ERROR the Blender document ${relative} was not written to the project: ${describeThrown(error)}`,
-    );
-    return;
+    throw new Error(`The Blender document ${relative} was not written to the project: ${describeThrown(error)}`);
   }
+  setDocumentDirty(false);
   log('log', `@@VGAI-DOCUMENT ${JSON.stringify({ path: relative, bytes: bytes.length })}`);
 }
 
@@ -206,9 +184,8 @@ async function startBlender(project: string, document?: string): Promise<unknown
     log,
     ask: async ({ frame, capture, saveDue }) => {
       if (!holder.engine) throw new Error('The Blender session presented before it started');
-      // The session says this present left the document behind the model. The
-      // clock is here; the write is one idle second away.
-      if (saveDue) armDocumentSave();
+      // Save once after the whole command, never during a partial frame.
+      if (saveDue && documentPath !== null) setDocumentDirty(true);
       // THE ARENA IS READ ONCE, HERE, and both readers share those bytes: the
       // typed arrays the tab draws from, and the record of what was sent
       // (`describeFrame`). After the post the buffers are detached and the
@@ -480,6 +457,9 @@ async function handle(request: WorkerRequest): Promise<unknown> {
    *  shape the caller wants (the RNA door). */
   const ask = engine.request.bind(engine);
   switch (request.op) {
+    case 'flush-document':
+      await saveDocument();
+      return { saved: true };
     case 'history-begin':
     case 'history-end':
       return ask({ op: request.op });
@@ -638,17 +618,19 @@ function reportMemory(): void {
   if (bytes !== null) post({ op: 'memory', bytes });
 }
 
-self.onmessage = async (event: MessageEvent<WorkerRequest>) => {
+self.onmessage = (event: MessageEvent<WorkerRequest>) => {
   const request = event.data;
   if (request.op === 'present-result') {
-    await handle(request);
+    void handle(request);
     return;
   }
-  // Held across the WHOLE call, so the document's save timer can tell "the
-  // session is quiet" from "a script is still running".
-  callsInFlight += 1;
+  void enqueue(() => answerRequest(request));
+};
+
+async function answerRequest(request: WorkerRequest): Promise<void> {
   try {
     const result = await handle(request);
+    if (documentDirty) await saveDocument();
     await reportHistory();
     post({ id: request.id, result });
   } catch (error) {
@@ -661,13 +643,11 @@ self.onmessage = async (event: MessageEvent<WorkerRequest>) => {
       message += `\nUnable to deliver Blender history: ${describeThrown(historyError)}`;
     }
     post({ id: request.id, error: message });
-  } finally {
-    callsInFlight -= 1;
   }
   // AFTER the answer, never before it: the reading is a passenger and must not
   // sit between a finished call and the reply the caller is waiting on.
   reportMemory();
-};
+}
 
 async function reportHistory(): Promise<void> {
   if (!engine || !session) return;

package/package.json

@@ -2,7 +2,7 @@
   "name": "@volter/blender-engine",
   "author": "Volter AI, Inc.",
   "license": "GPL-3.0-or-later",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "publishConfig": {
     "access": "public"
   },