@volter/editor-blender 0.1.149 → 0.1.151

package/host/blender-runtime-host.ts

@@ -1,38 +1,16 @@
-/**
- * The editor tab's Blender session and the control-channel doors onto it —
- * Blender's EDITOR half, in `@volter/editor-blender` (WORK.md §Skews as packages under
- * the Code-OSS frame, item 6). Its thirteen verbs are
- * `../contributions/blender.command.ts`, a `workspace.command` contribution;
- * what it needs of the running editor it asks THROUGH THE DOOR,
- * `@volter/sdk/host` — the document context it
- * presents into, the session it lives and dies with. It imports no host module
- * (WORKBENCH.md §The invariants, "Direction": a package imports only the SDK
- * and other packages' exports), which is what lets this lane ship against a
- * workbench it was not built in.
- *
- * `volter blender-mcp` is transport only: every `execute_blender_code`,
- * `get_scene_info`, `get_object_info` and `get_viewport_screenshot` arrives
- * here as a `blender-*` command and is answered by Blender running in this
- * tab's worker (`@volter/blender-engine/browser`). The model exists in that worker
- * and nowhere else; the Model document (`document:blender:runtime`, the
- * project's `blender-runtime` contribution) only displays the frames the
- * worker presents. A screenshot is the tab photographing that document
- * through `capture-active-document`, after `blender-screenshot-view` has
- * presented the model with the viewport's own camera.
- *
- * VOLTER_THREE photographs a detached revision through its own camera.
- * Native CYCLES renders inside the Blender worker. A native preview is a
- * read of that document through Cycles, separate from its Three presentation.
- */
+/** The tab’s Blender session and SDK host doors. blender.verbs.ts registers the page commands; Blender runs in the worker and the Model displays its frames. VOLTER_THREE photographs detached revisions through its camera; native Cycles renders inside the worker. */
 
+import { bytesFromBase64 } from '@volter/blender-engine/browser/three/blender-base64';
 import {
   BlenderRuntime,
-  type CaptureRequest,
   type PresentAnswer,
+  type SavedDocument,
+  type SaveScript,
 } from '@volter/blender-engine/browser';
-import type { RenderRequest } from '@volter/blender-engine/browser/protocol';
+import type { BlenderAssetLibrary, GltfExportAnswer, GltfExportKind, GltfExportPrevious, RenderRequest, RuntimeStart } from '@volter/blender-engine/browser/protocol';
 import type {
   BlenderActionClip,
+  BlenderSceneMovie,
   BlenderNodeTree,
   BlenderOutlinerTree,
   BlenderOutlinerWrite,
@@ -43,9 +21,10 @@ import type {
 } from '@volter/blender-engine/browser/rna';
 import { createBlenderDisplayTransform, blenderDisplaySettingsForRender } from '@volter/blender-engine/browser/three/blender-display-transform';
 import { BlenderRuntimeView } from '@volter/blender-engine/browser/three/blender-runtime-view';
-import type { EditorCommandResult } from '@volter/sdk/commands';
-import { editorHost } from '@volter/sdk/host';
-import { invokeViewVerb, type ViewVerbContribution } from '@volter/sdk/views';
+import { commandJobs, type EditorCommandResult } from '@volter/sdk/commands';
+import { editorHost, type EditorHostProject } from '@volter/sdk/host';
+import { waitUntil } from '@volter/sdk/wait-until';
+import type { ViewVerb } from '@volter/sdk/commands';
 import {
   captureSceneImage,
   captureSceneLinear,
@@ -53,6 +32,10 @@ import {
   type LinearCaptureFrame,
 } from '@volter/editor-threejs/capture/scene';
 import {blenderRenderCamera} from '@volter/blender-engine/browser/three/blender-render-camera';
+import { beginMovie, type Movie } from '@volter/editor-movie';
+import { mixSceneSound } from './scene-sound';
+import { clearModelDocumentSaving, setModelDocumentSaveNotice } from '../src/model-document-saving';
+import { startDocument } from '../src/start-document';
 import * as THREE from 'three';
 import { blenderEngineSelection, refreshBlenderOutliner } from '../contributions/blender-outliner-model';
 import {
@@ -65,9 +48,7 @@ import {
 
 /** Raw bytes of a base64 payload, as the half-float words a linear frame is. */
 function halfFloatFrame(base64: string): Uint16Array {
-  const binary = atob(base64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  const bytes = bytesFromBase64(base64);
   return new Uint16Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 1);
 }
 
@@ -180,21 +161,7 @@ export async function photographSnapshot(
 
 export const BLENDER_RUNTIME_DOCUMENT_ID = 'document:blender:runtime';
 
-/**
- * THE MODEL DOCUMENT THIS TAB IS PRESENTING INTO, and the `.blend` it opened.
- *
- * A `model` entry's document is bound to the project's own `.blend`
- * (`models.finder.ts` lists them; `blender-runtime.document.tsx` opens the one
- * its entry names), so the presenter's address is no longer a constant. A
- * project with no `.blend` of its own still gets ONE Model document at the
- * standing `blender:runtime` address — that is what `blender-start` presents
- * into and what the battery photographs — and then this stays null and every
- * read falls back to the constant above.
- *
- * It is a module variable rather than a host door because both sides are THIS
- * package: the document that binds it and the session that reads it ship
- * together, so there is nothing for the SDK to carry.
- */
+/** The bound Model document supplies its presentation address and .blend path. With no project .blend, use the standing blender:runtime document. Both producer and reader belong to this package. */
 export interface ModelDocumentBinding {
   readonly documentId: string;
   readonly entryId: string;
@@ -229,11 +196,7 @@ function shownModelBlend(): string | undefined {
     : boundModel?.blend;
 }
 
-/**
- * A script's Save As into a project `.blend` that no Model document lists (`followMovedDocument`): Blender edits
- * that file and saves there, and the tab it left (`from`) keeps showing Blender, since there is no tab to move to.
- * Without this, every later call was refused as a conflict naming a file no tab can show.
- */
+/** Follow a script’s Save As even when no Model document lists the new project file. Keep the existing tab bound to the session’s current file. */
 let unlistedFollow: { readonly owner: BlenderRuntime; readonly from: string; readonly document: string } | null = null;
 
 function modelDocumentConflict(): string | null {
@@ -241,9 +204,10 @@ function modelDocumentConflict(): string | null {
   const requested = shownModelBlend();
   if (!requested || !held || requested === held) return null;
   if (unlistedFollow !== null && unlistedFollow.owner === runtime && unlistedFollow.document === held && unlistedFollow.from === requested) return null;
-  // Say how to get Blender onto the document the editor shows, not only how to go back: an agent told
-  // just "return to <held>" took it as the Blender door being unusable and built its level by
-  // another route (2026-10-06, the WSL obby run).
+  // Say how to get Blender onto the document the editor shows, not only how to go back: "return to <held>"
+  // alone reads as the Blender door being unusable.
+  // (`session.py`'s `_another_document_shown` reads "but the editor is showing": a first present refused so is a
+  // document switch, not a failure of the document's.)
   // Plain words: people see this in error notices too. Re-opening the document already showing does not
   // remount a failed open (blender-runtime.document.tsx), so the steps that do are named instead.
   return `Blender is editing ${held}, but the editor is showing ${requested}, which Blender has not loaded. ` +
@@ -273,6 +237,16 @@ export function modelDocumentMayOpen(binding: ModelDocumentBinding): boolean {
   return !anotherModel || active === binding.documentId;
 }
 
+/** THE `.blend` A MODEL VIEW SHOWS NOW: the runtime's document, once `view` holds that runtime's
+ *  latest present; null between opening a file and its first present (the view still shows the
+ *  last one). */
+export function presentedModelBlend(view: { snapshot(): { readonly session: string; readonly revision: number } | null }): string | null {
+  const latest = runtime?.presented;
+  const shown = view.snapshot();
+  if (!runtime || !latest || !shown || shown.session !== latest.session || shown.revision !== latest.revision) return null;
+  return runtime.document ?? null;
+}
+
 /** 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(
@@ -289,6 +263,151 @@ export function modelDocumentOwnsPresentation(
     !!presented && !!latest && presented.session === latest.session && presented.revision === latest.revision;
 }
 
+/**
+ * THE MODEL DOCUMENT'S WORKING COPY — what the workbench calls for the `.blend` the engine holds
+ * (the `workingCopy` of `blender-runtime.document.tsx`). The engine is its one writer: a save is
+ * the worker's own, over the session's delta route, and the rest reopen the document inside the
+ * engine.
+ */
+const modelDirtyListeners = new Set<() => void>();
+
+export function subscribeModelDocumentDirty(listener: () => void): () => void {
+  modelDirtyListeners.add(listener);
+  return () => { modelDirtyListeners.delete(listener); };
+}
+
+export function modelDocumentDirty(blend: string): boolean {
+  return runtime?.document === blend && runtime.dirty;
+}
+
+/** How long the workbench's call waits for the engine to hold the model: a cold boot of the engine. */
+const MODEL_HELD_MS = 120_000;
+
+/** The runtime holding `blend`, once it does. */
+async function runtimeHolding(blend: string): Promise<BlenderRuntime> {
+  if (!(await waitUntil(() => runtime?.document === blend, MODEL_HELD_MS)) || !runtime) {
+    throw new Error(`Blender does not hold ${blend}.`);
+  }
+  return runtime;
+}
+
+/** 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> {
+  const owner = runtime;
+  if (owner?.document !== blend || !owner.dirty) return;
+  const saved = await owner.saveDocument(saveScript ?? undefined);
+  if (saved !== null) modelDocumentSaved(owner, saved);
+}
+
+export async function saveModelDocument(blend: string): Promise<void> {
+  const owner = await runtimeHolding(blend);
+  const saved = await owner.saveDocument(saveScript ?? undefined);
+  if (saved !== null) modelDocumentSaved(owner, saved);
+}
+
+/** THE SCRIPT EVERY SAVE RUNS, in the save's own turn, on the scene it wrote (`BlenderRuntime.saveDocument`), as its
+ *  setter names it for the document saved; one at a time, until its removal. */
+let saveScript: SaveScript | null = null;
+
+export function setModelDocumentSaveScript(script: SaveScript): () => void {
+  if (saveScript) throw new Error('A save script is already set for model documents.');
+  saveScript = script;
+  return () => { if (saveScript === script) saveScript = null; };
+}
+
+/** A SAVE THAT LANDED A `.blend` IN THE PROJECT, as its listeners hear it: the file it wrote, what the save script did
+ *  on the scene it wrote (null where none ran: `setModelDocumentSaveScript`), and the carry of that script's files into
+ *  the project at the same paths, as an export's are (`blender-gltf-export.verbs.ts`), which the listener runs when it
+ *  is ready for them. A script that raised has nothing to carry. */
+export interface ModelDocumentSaved {
+  readonly blend: string;
+  readonly script: { readonly output: string; readonly error: string | null; readonly unstaged: readonly string[] } | null;
+  carry(): Promise<void>;
+}
+
+/** EACH SAVE THAT LANDED A `.blend` IN THE PROJECT: the working copy's (a person's Save, the workbench's autosave), an
+ *  export's flush and the save that retires a document alike. What a listener answers is its work on that save (the
+ *  carry and what follows it), which reads files, not Blender: a retirement waits for it ({@link retireRuntime}). */
+type ModelDocumentSavedListener = (saved: ModelDocumentSaved) => Promise<unknown> | void;
+const savedListeners = new Set<ModelDocumentSavedListener>();
+/** The listeners' work on each runtime's saves, not yet done. */
+const savedWork = new Map<BlenderRuntime, Set<Promise<unknown>>>();
+
+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 listener of [...savedListeners]) {
+    const work = listener(heard);
+    if (!work) continue;
+    const held = savedWork.get(owner) ?? new Set<Promise<unknown>>();
+    savedWork.set(owner, held);
+    const settled = work.then(() => {}, () => {}).finally(() => {
+      held.delete(settled);
+      if (held.size === 0 && savedWork.get(owner) === held) savedWork.delete(owner);
+    });
+    held.add(settled);
+  }
+}
+
+export function subscribeModelDocumentSaved(listener: ModelDocumentSavedListener): () => void {
+  savedListeners.add(listener);
+  return () => { savedListeners.delete(listener); };
+}
+
+/**
+ * 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.
+ */
+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]);
+}
+
+/**
+ * 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.
+ */
+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));
+  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;
+}
+
+export async function snapshotModelDocument(blend: string): Promise<Uint8Array> {
+  return (await runtimeHolding(blend)).snapshotDocument();
+}
+
+export async function revertModelDocument(blend: string): Promise<void> {
+  await (await runtimeHolding(blend)).revertDocument();
+}
+
+export async function restoreModelDocument(blend: string, bytes: Uint8Array): Promise<void> {
+  await (await runtimeHolding(blend)).restoreDocument(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
@@ -311,6 +430,7 @@ function queueModelLifecycle<T>(operation: () => Promise<T>): Promise<T> {
 export async function openModelDocumentBlend(
   binding: ModelDocumentBinding,
   publish: () => void,
+  reload = false,
 ): Promise<boolean> {
   let published = false;
   const publishOnce = () => {
@@ -332,12 +452,13 @@ export async function openModelDocumentBlend(
   }
   // 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));
+  return queueModelLifecycle(() => openBoundModelDocument(binding, publishOnce, reload));
 }
 
 async function openBoundModelDocument(
   binding: ModelDocumentBinding,
   publish: () => void,
+  reload: boolean,
 ): Promise<boolean> {
   const host = editorHost();
   if (!host.session.open()) throw new Error('Opening a model requires an open project session.');
@@ -345,40 +466,34 @@ 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 && (previous.project !== project || previous.document !== binding.blend)) {
-    // stop drains accepted work and flushes the OLD worker's bound file. If
+  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
     // 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(); }
+    // (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)' : ''}`);
+    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 = session.start(project, binding.blend);
+  const started = startSession(session, project, binding.blend);
   const starting = { session, project, blend: binding.blend };
   modelStartup = starting;
   try {
     publish();
     await started;
   } catch (error) {
-    // A session whose start failed keeps that failure and never starts. Discard it, so that
-    // "Retry opening" makes a new session and a new worker; without this every retry awaited the
-    // same failed start. A refusal that is not a failed start (another document holds the
-    // session) leaves the session alone: it is someone else's.
+    // 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;
   } 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.
-  // A reopened pane has a NEW view, though, and an absent file presents
-  // nothing at start. Compare the view's actual holding with the runtime's
-  // revision so both cases still request the frame they need.
+  // bind_document presents before start resolves. Request another frame only when the view does not hold the runtime’s current revision, including reopened panes and initially absent files.
   const shown = (await runtimeView()).snapshot();
   if (!host.session.open() || !modelDocumentMayOpen(binding)) return false;
   const latest = session.presented;
@@ -397,7 +512,7 @@ async function openBoundModelDocument(
  * and the panel read one thing.
  *
  * THEY NEVER START THE ENGINE. A panel asking what the engine holds must not
- * be the reason a 880 MB Blender boots, so these answer `null` when this tab
+ * start Blender, so these answer `null` when this tab
  * has no started session — exactly the read `blender-status` makes, and for
  * the same reason.
  */
@@ -405,34 +520,7 @@ export function blenderSessionStarted(): boolean {
   return runtime?.project != null && modelDocumentConflict() === null;
 }
 
-/**
- * THE DOCUMENT'S RNA VERSION — "a tree's freshness is the tree's, not the
- * presented frame's" (orchestrator ruling 3, 2026-09-19, WORK.md §Blender in
- * the tab is Blender, I5).
- *
- * Every view over this engine draws something RNA answers, and until this
- * existed the only "the engine moved" signal in the page was a PRESENTED
- * FRAME: `blender-properties-model.ts` subscribes to the Model document's
- * frames, and its version was what the node view re-read on. MEASURED
- * 2026-09-19 by I5's socket-panel step: collapsing a panel through
- * `blender-rna-set` changes `Node.panel_states[n].is_collapsed`, which changes
- * nothing the presenter draws — so no frame ships, no version moves, and the
- * node view kept drawing the old tree until the document was reopened. It is
- * the same shape as I3's "a present is not a reliable signal for a column"
- * (`hide_render`), and the answer is the same: the WRITE asks for the re-read.
- *
- * So the version is minted HERE, at the door every RNA write goes through,
- * and it is bumped by the write rather than by the picture. Both halves of
- * each door bump it once: the in-page function is what the wire's
- * `blender-rna-set` / `blender-outliner-set` case calls, so a `cyclotron eval` and
- * a panel click are one path. `blender-execute` bumps it too — arbitrary bpy
- * can change anything RNA answers, and a view that went stale under a probe's
- * own script would be the same defect one layer out.
- *
- * WHAT SUBSCRIBES: `blender-properties-model.ts` (which invalidates its cached
- * datablock views and re-reads the context, exactly as it does on a frame),
- * and every view in `@volter/editor-blender/contributions` that draws RNA.
- */
+/** 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. */
 let rnaVersion = 0;
 const rnaListeners = new Set<() => void>();
 
@@ -455,9 +543,9 @@ export function noteBlenderRnaChanged(): void {
   for (const listener of [...rnaListeners]) listener();
 }
 
-export async function blenderRna(path: string, names?: number): Promise<BlenderRnaView | null> {
+export async function blenderRna(path: string): Promise<BlenderRnaView | null> {
   if (!blenderSessionStarted()) return null;
-  return blenderRuntime().rna(path, names);
+  return blenderRuntime().rna(path);
 }
 
 export async function blenderRnaContext(
@@ -487,51 +575,7 @@ export async function blenderViewShading(shading: 'WIREFRAME' | 'SOLID' | 'MATER
   await blenderRuntime().viewShading(shading);
 }
 
-/**
- * THE SCRIPT DOOR, in-page — one bpy script, run the way the MCP add-on runs
- * one (`session.py::execute`: a namespace of its own, output captured, and a
- * PRESENT after it, so the picture that comes back is the engine's own
- * reading).
- *
- * This is what an OPERATOR goes through. The Outliner's structural verbs —
- * add, delete, duplicate — are `bpy.ops.*` calls and nothing else: Blender
- * runs the operator and we only name it (`blender-outliner-authoring.ts`'s
- * `StructureProvider`). Writing a second implementation of `object.delete`'s
- * unparenting, or of `primitive_uv_sphere_add`'s defaults, is the thing this
- * door exists to make unnecessary.
- *
- * SAME SHAPE AS {@link blenderRnaSet}, and for its reason: the RNA version is
- * minted at the door, so the wire's `blender-execute` case calls THIS rather
- * than `session.execute` beside it — arbitrary bpy can change anything RNA
- * answers, and a view left drawing the tree it had is the defect the version
- * exists for. Like every door here it never starts the engine.
- *
- * The answer is `session.py::execute`'s own record — `executed`, the captured
- * `result` text, and `error` when the script raised. A REFUSAL IS NOT A THROW:
- * Blender's traceback comes back in `error`, verbatim, and a caller that wants
- * it to be an exception raises its own (the structure provider does, so the
- * ack it hands the shell carries Blender's sentence).
- *
- * IT DOES NOT GUARD ON `blenderSessionStarted()`, and that is the one way it
- * differs from the read doors above. They are called from a panel's render and
- * must answer "nothing to show" rather than spawn a session; a script is always
- * a deliberate act, and the engine's own refusal — "The Blender session has not
- * been started with a project (blender-start)" — is the honest answer to one
- * made too early. A silent `null` there would have turned the wire's own loud
- * refusal into an empty result.
- *
- * WHAT THE SESSION ACTUALLY ANSWERS WITH IS THE MCP DOOR'S TEXT, not
- * `session.py::execute`'s `{executed, result, error}` record: the worker
- * flattens it into ONE STRING on the way out — `Code executed successfully:
- * <stdout>` or `Error executing code: <traceback>` (`worker.ts:250-260`, "a
- * script's failure is TEXT, not a rejection"), because that is what the MCP
- * tool returns to an agent. So this parses it, once, here. MEASURED 2026-09-21:
- * a first version read `answer.executed`/`answer.error` off the string, where
- * both are `undefined` — every operator RAN and every caller was told it had
- * failed, which is how an added sphere reached `bpy.data.objects` and the
- * Outliner and was never selected. Read-only metadata uses dedicated native
- * reads rather than this execute path, which always presents a mutation.
- */
+/** Execute one bpy script in the current session and bump the RNA version. The worker returns MCP text: Code executed successfully: <stdout> or Error executing code: <traceback>. Parse it once into executed/result/error for in-page callers; preserve the text for wire callers. A call before session startup receives the engine’s refusal. */
 export async function blenderExecute(code: string, history = true, label = 'Blender Python'): Promise<BlenderExecuteAnswer> {
   const session = blenderRuntime();
   const text = await session.execute(code, history, label);
@@ -547,6 +591,187 @@ export async function blenderExecute(code: string, history = true, label = 'Blen
   };
 }
 
+// ---------------------------------------------------------------- a film, rendered
+
+/** WHERE A RENDER'S TIME GOES, one record per photograph a render or a film takes: the frame's
+ *  transfer (from its first staged part to its present; none when nothing new was staged), building
+ *  it into the view it is photographed from, and the photograph itself. Read by `render-movie`
+ *  beside Blender's own time, so a slow film says which side is slow. */
+const renderTimings: { stageMs: number; applyMs: number; photoMs: number }[] = [];
+/** When the frame being transferred staged its first part, render or viewport; taken at its present. */
+let frameStagedAt: number | null = null;
+
+/** The film being encoded (`renderBlenderMovie`), one at a time, and the photographs of the frames
+ *  rendered and not yet encoded, in order (base64 PNG). */
+let film: { readonly movie: Movie; readonly photographs: string[] } | null = null;
+
+async function movieFrames(numbers: readonly number[]): Promise<{ encoded: number; timing: { executeMs: number; stageMs: number; applyMs: number; photoMs: number; encodeMs: number } }> {
+  const current = film;
+  if (!current) throw new Error('No film is being rendered.');
+  const { movie } = current;
+  // ONE CALL TAKES THE CHUNK: each frame set, then photographed as the viewport presents it through
+  // the scene camera (session.py's `photograph_frame`): the present ships only what moved.
+  const code = `
+import bpy, sys
+photograph = next(m.photograph_frame for m in list(sys.modules.values()) if hasattr(m, "photograph_frame"))
+s = bpy.context.scene
+kept = s.frame_current
+try:
+    for f in ${JSON.stringify(numbers)}:
+        s.frame_set(f)
+        photograph(${movie.width}, ${movie.height})
+finally:
+    s.frame_set(kept)
+`;
+  const timedFrom = renderTimings.length;
+  const executeAt = performance.now();
+  const answer = await blenderExecute(code, false, 'render-movie');
+  const executeMs = performance.now() - executeAt;
+  const taken = renderTimings.slice(timedFrom);
+  const encodeAt = performance.now();
+  if (!answer.executed) throw new Error(`Blender could not render frames ${numbers[0]}-${numbers.at(-1)}: ${answer.error}`);
+  const shots = current.photographs.splice(0);
+  if (shots.length !== numbers.length) throw new Error(`Blender rendered ${numbers.length} frames and ${shots.length} photographs were taken.`);
+  for (const shot of shots) {
+    const png = bytesFromBase64(shot);
+    const bitmap = await createImageBitmap(new Blob([png as BlobPart], { type: 'image/png' }));
+    try { await movie.frame(bitmap); } finally { bitmap.close(); }
+  }
+  const mean = (pick: (t: (typeof taken)[number]) => number): number => (taken.length ? taken.reduce((n, t) => n + pick(t), 0) / taken.length : 0);
+  const per = numbers.length || 1;
+  return { encoded: movie.frames, timing: { executeMs: executeMs / per, stageMs: mean((t) => t.stageMs), applyMs: mean((t) => t.applyMs), photoMs: mean((t) => t.photoMs), encodeMs: (performance.now() - encodeAt) / per } };
+}
+
+/** The scene's sound over frames `from` to `to`, mixed, and a movie begun with it encoded first: its track starts at
+ *  the movie's first frame, so a movie from a later frame hears the sound from that frame on. */
+async function beginFilm(size: { readonly width: number; readonly height: number }, fps: number, from: number, to: number): Promise<{ strips: number; speakers: number } | null> {
+  const session = blenderRuntime();
+  const host = editorHost();
+  const project = host.projectLocalState.projectRootPath();
+  const sound = await mixSceneSound(await session.soundScene(from, to), async (file) => {
+    if ('packed' in file) return session.readFile(file.packed);
+    // a file in the project is read from the project; the engine mirrors the project at its own path
+    return project !== null && file.path.startsWith(`${project}/`)
+      ? host.files.readBytes(file.path.slice(project.length + 1))
+      : session.readFile(file.path);
+  });
+  const movie = await beginMovie({ ...size, fps, ...(sound ? { audio: { sampleRate: sound.sampleRate, channels: sound.planes.length } } : {}) });
+  try {
+    if (sound) await movie.audio(sound.planes);
+  } catch (error) {
+    movie.cancel();
+    throw error;
+  }
+  film?.movie.cancel();
+  film = { movie, photographs: [] };
+  return sound ? { strips: sound.strips, speakers: sound.speakers } : null;
+}
+
+/** What a movie render is asked for: the project file it is written to, the `.blend` it renders (the open one by
+ *  default), its first and last frames (frame numbers or marker names; the scene's range by default), its width (the
+ *  scene's resolution by default; the height keeps the scene's aspect), and the frame rate a caller's own movie is at,
+ *  which the scene's must equal. */
+interface BlenderMovieRequest {
+  readonly out: string;
+  readonly document?: string;
+  readonly from?: string | number | undefined;
+  readonly to?: string | number | undefined;
+  readonly width?: number;
+  readonly fps?: number;
+}
+
+/** Where a movie render stands. */
+interface BlenderMovieRender {
+  readonly out: string;
+  readonly state: 'rendering' | 'done' | 'failed';
+  readonly frame: number;
+  readonly frames: number;
+  readonly first?: number;
+  readonly last?: number;
+  readonly width?: number;
+  readonly height?: number;
+  readonly fps?: number;
+  /** The scene's sound the movie carries, or null when the scene plays none. */
+  readonly sound?: { readonly strips: number; readonly speakers: number } | null;
+  /** What the render cannot do as asked (a scene with no camera). */
+  readonly warnings?: readonly string[];
+  /** Where the last chunk's time went, per frame, in milliseconds: Blender's render call and, inside it, the frame's
+   *  transfer, its build into the photograph view and the photograph; then the encode. */
+  readonly timing?: { readonly executeMs: number; readonly stageMs: number; readonly applyMs: number; readonly photoMs: number; readonly encodeMs: number };
+  readonly codec?: string;
+  readonly bytes?: number;
+  readonly error?: string;
+}
+
+/** The movie renders, by the project file each writes. */
+const movieRenders = commandJobs<BlenderMovieRender>();
+
+/** The Timeline of `request.document` (or the open document) rendered with the scene's sound into `request.out`. */
+async function renderBlenderMovie(request: BlenderMovieRequest, report: (render: BlenderMovieRender) => void): Promise<void> {
+  let render: BlenderMovieRender = { out: request.out, state: 'rendering', frame: 0, frames: 0 };
+  const host = editorHost();
+  if (request.document !== undefined) {
+    const opened = await host.documents.openForFile(request.document);
+    if (opened === null) throw new Error(`No Model document is ${request.document}.`);
+    await host.documents.waitForContext(opened);
+  }
+  const probe = await blenderExecute(`
+import bpy, json
+s = bpy.context.scene
+r = s.render
+print(json.dumps({"start": s.frame_start, "end": s.frame_end, "fps": r.fps / (r.fps_base or 1), "width": r.resolution_x, "height": r.resolution_y,
+  "percent": r.resolution_percentage, "camera": s.camera.name if s.camera else None,
+  "markers": {m.name: m.frame for m in s.timeline_markers}, "cameraMarkers": [m.frame for m in s.timeline_markers if m.camera]}))
+`, false, 'render-movie');
+  if (!probe.executed) throw new Error(`Blender could not read the scene: ${probe.error}`);
+  const scene = JSON.parse(probe.result.slice(probe.result.indexOf('{'))) as {
+    start: number; end: number; fps: number; width: number; height: number; percent: number; camera: string | null;
+    markers: Record<string, number>; cameraMarkers: number[];
+  };
+  if (request.fps !== undefined && Math.abs(scene.fps - request.fps) > 1e-6)
+    throw new Error(`The scene plays at ${scene.fps} fps and the movie is at ${request.fps}: set the scene's frame rate to the movie's.`);
+  const frameOf = (at: string | number | undefined, fallback: number): number => {
+    if (at === undefined) return fallback;
+    if (typeof at === 'number') return at;
+    if (/^-?\d+$/.test(at)) return Number(at);
+    const marker = scene.markers[at];
+    if (marker === undefined) throw new Error(`The Timeline has no marker "${at}"; it has ${Object.keys(scene.markers).map((name) => `"${name}"`).join(', ') || 'none'}.`);
+    return marker;
+  };
+  const first = frameOf(request.from, scene.start);
+  const last = frameOf(request.to, scene.end);
+  if (last < first) throw new Error(`It ends (frame ${last}) before it starts (frame ${first}).`);
+  const width = request.width ?? Math.round(scene.width * (scene.percent / 100));
+  const height = Math.round(width * (scene.height / scene.width));
+  const warnings = !scene.camera && !scene.cameraMarkers.some((at) => at <= first)
+    ? ['The scene has no camera; Blender renders through the scene camera or a marker-bound one.'] : [];
+  const sound = await beginFilm({ width, height }, scene.fps, first, last);
+  const movie = film!.movie;
+  render = { ...render, frames: last - first + 1, first, last, width: movie.width, height: movie.height, fps: scene.fps, sound, codec: movie.codec, warnings };
+  report(render);
+  for (let frame = first; frame <= last; frame += 12) {
+    const { encoded, timing } = await movieFrames(Array.from({ length: Math.min(12, last - frame + 1) }, (_, i) => frame + i));
+    render = { ...render, frame: encoded, timing };
+    report(render);
+  }
+  film = null;
+  const bytes = await movie.end();
+  await host.files.write(request.out, bytes);
+  report({ ...render, state: 'done', bytes: bytes.length });
+}
+
+/** Start rendering a movie, answering at once with where it stands. One render at a time. */
+function startBlenderMovie(request: BlenderMovieRequest): BlenderMovieRender {
+  if (movieRenders.running()) throw new Error('A movie is already rendering.');
+  if (!/\.webm$/i.test(request.out)) throw new Error(`A movie is written as .webm, not ${request.out}.`);
+  return movieRenders.start(request.out, { out: request.out, state: 'rendering', frame: 0, frames: 0 }, (report) =>
+    renderBlenderMovie(request, report).catch((thrown: unknown) => {
+      film?.movie.cancel();
+      film = null;
+      throw thrown;
+    }));
+}
+
 /**
  * A Save As the worker reported (`BlenderRuntimeOptions.documentMoved`) that the open Model tab
  * has not followed yet. Taken by the {@link blenderExecute} whose script moved it, once that
@@ -554,6 +779,9 @@ export async function blenderExecute(code: string, history = true, label = 'Blen
  */
 let unfollowedMove: { readonly owner: BlenderRuntime; readonly from: string; readonly document: string } | null = null;
 
+/** A followed Save As waiting for the table to list its new file (`followMovedDocument`); calling it stops waiting. */
+let awaitingListing: (() => void) | null = null;
+
 /**
  * THE MODEL TAB FOLLOWS BLENDER'S SAVE AS. The runtime already holds the new file and its saves
  * go there (`session.py::follow_open_file`); what is left is the tab. Until it moves, the editor
@@ -563,13 +791,17 @@ let unfollowedMove: { readonly owner: BlenderRuntime; readonly from: string; rea
  * its binding. Re-activating the old tab later opens the old file the ordinary way.
  *
  * Only a tab that was showing the old file (or the standing Model of a project that had no
- * `.blend`) is moved; a person who has since switched elsewhere is not pulled back. A new file
- * no Model document lists (outside the project's model finder) is said, not guessed at.
+ * `.blend`) is moved; a person who has since switched elsewhere is not pulled back. A file the
+ * project's finders list may not be in the project folder yet: a script's call through the
+ * project's Blender MCP answers before its Mirror lands the files the script saved, so the tab
+ * follows when the table first lists it. A new file outside every finder's `include` is said, not
+ * guessed at.
  */
 async function followMovedDocument(owner: BlenderRuntime): Promise<void> {
   const move = unfollowedMove;
   if (!move || move.owner !== owner) return;
   unfollowedMove = null;
+  awaitingListing?.();
   const host = editorHost();
   // The tab showing Blender: the file Blender left, or, after an earlier Save As to an unlisted file, the tab
   // that one left.
@@ -580,35 +812,56 @@ async function followMovedDocument(owner: BlenderRuntime): Promise<void> {
     const shown = shownModelBlend();
     return shown === shownFrom || (shown === undefined && host.documents.activeId() === BLENDER_RUNTIME_DOCUMENT_ID);
   };
+  const listing = (table: Awaited<ReturnType<EditorHostProject['documentTable']>>) =>
+    table.entries.find(candidate => candidate.kind === 'model' && candidate.source?.path === move.document);
+  /** A tab that could not move keeps working on the file Blender holds, as for an unlisted file. */
+  const keepShowing = () => {
+    if (stillShowingOld()) unlistedFollow = { owner, from: shownFrom, document: move.document };
+  };
+  const follow = async (id: string) => {
+    if (await host.workspace.open({ kind: 'document', id })) return;
+    keepShowing();
+    host.console.warn(`Blender now has ${move.document} open, but its Model document ${id} did not open; the ${shownFrom} tab keeps showing Blender, which edits ${move.document}.`, 'blender-document');
+  };
+  const failed = (error: unknown) => {
+    keepShowing();
+    host.console.error(`The Model tab could not follow Blender to ${move.document}: ${error instanceof Error ? error.message : String(error)}`, 'blender-document');
+  };
   if (!stillShowingOld()) return;
   try {
-    // The table re-reads the project's files, which now include the file this call saved.
-    const table = await host.project.documentTable();
-    const entry = table.entries.find(candidate => candidate.kind === 'model' && candidate.source?.path === move.document);
-    if (!entry) {
-      if (!stillShowingOld()) return;
-      unlistedFollow = { owner, from: shownFrom, document: move.document };
-      host.console.warn(
-        `Blender now has ${move.document} open and the model saves there. No Model document lists that file ` +
-          `(the project's model finder does not include its folder), so the ${shownFrom} tab keeps showing ` +
-          `Blender, which now edits ${move.document}; ${shownFrom} keeps what it last saved. Save the model ` +
-          `under src/models/ to give it a Model tab of its own.`,
-        'blender-document',
-      );
+    const entry = listing(await host.project.documentTable());
+    if (!stillShowingOld()) return;
+    if (entry) {
+      await follow(entry.id);
       return;
     }
-    if (!stillShowingOld()) return;
-    if (!await host.workspace.open({ kind: 'document', id: entry.id })) {
-      keepShowing();
-      host.console.warn(`Blender now has ${move.document} open, but its Model document ${entry.id} did not open; the ${shownFrom} tab keeps showing Blender, which edits ${move.document}.`, 'blender-document');
+    // Meanwhile the tab works on the file Blender holds.
+    unlistedFollow = { owner, from: shownFrom, document: move.document };
+    if (host.project.finderIncludes(move.document)) {
+      const stop = host.project.onDocumentTable((table) => {
+        const listed = listing(table);
+        if (!listed) return;
+        release();
+        if (!stillShowingOld()) return;
+        unlistedFollow = null;
+        follow(listed.id).catch(failed);
+      });
+      const release = () => {
+        stop();
+        if (awaitingListing === release) awaitingListing = null;
+      };
+      awaitingListing = release;
+      return;
     }
+    host.console.warn(
+      `Blender now has ${move.document} open and the model saves there. No Model document lists that file ` +
+        `(no document finder in the project's adapter includes it), so the ${shownFrom} tab keeps showing ` +
+        `Blender, which now edits ${move.document}; ${shownFrom} keeps what it last saved. Save the model ` +
+        `where the adapter's finder lists models to give it a Model tab of its own.`,
+      'blender-document',
+    );
   } catch (error) {
-    keepShowing();
-    host.console.error(`The Model tab could not follow Blender to ${move.document}: ${error instanceof Error ? error.message : String(error)}`, 'blender-document');
-  }
-  /** A tab that could not move keeps working on the file Blender holds, as for an unlisted file. */
-  function keepShowing(): void {
-    if (stillShowingOld()) unlistedFollow = { owner, from: shownFrom, document: move!.document };
+    failed(error);
   }
 }
 
@@ -648,26 +901,19 @@ export async function blenderOutliner(
 /** THE NODE-TREE DOOR, in-page — one material's shader node tree, which the
  *  Shading workspace's node view draws (`../contributions/blender-node-*`).
  *  Same rule as the doors above: it never starts the engine. */
-export async function blenderNodeTree(options?: {
-  path?: string;
-  material?: string;
-}): Promise<BlenderNodeTree | null> {
+export async function blenderNodeTree(): Promise<BlenderNodeTree | null> {
   if (!blenderSessionStarted()) return null;
-  return blenderRuntime().nodeTree(options);
+  return blenderRuntime().nodeTree();
 }
 
 /** THE UV DOOR, in-page — one mesh's UV layout, which the UV Editing
  *  workspace's view draws (`../contributions/blender-uv-*`). Same rule as the
  *  doors above: it never starts the engine. */
-export async function blenderUvLayout(options?: {
-  object?: string;
-  uvLayer?: string;
-}): Promise<BlenderUvLayout | null> {
+export async function blenderUvLayout(): Promise<BlenderUvLayout | null> {
   if (!blenderSessionStarted()) return null;
-  return blenderRuntime().uvLayout(options);
+  return blenderRuntime().uvLayout();
 }
 
-
 /** THE CLIP DOOR, in-page — one action as three.js keyframe tracks plus the
  *  scene's frame range and the Timeline's summary columns. Called when the
  *  action's own revision moves, never per played frame. */
@@ -683,6 +929,30 @@ export async function blenderActionClip(options?: {
   return blenderRuntime().actionClip(options);
 }
 
+/** THE DOCUMENT AS A COMPONENT OR A LEVEL, by Blender's own glTF exporter (`session.py`'s
+ *  `gltf-export`, RFC 0007), and the bytes of a file it wrote in the module filesystem, for the
+ *  caller to carry into the project. Neither starts the engine. */
+export async function blenderGltfExport(options: { readonly kind: GltfExportKind; readonly force?: boolean; readonly previous?: GltfExportPrevious; readonly blendSha256?: string; readonly luts?: Readonly<Record<string, string>> }): Promise<GltfExportAnswer | null> {
+  if (!blenderSessionStarted()) return null;
+  return blenderRuntime().gltfExport(options);
+}
+
+/** Present the document once now (after a game over the standard artifact ends: `blender-runtime.document.tsx`). */
+export async function blenderPresentDocument(): Promise<void> {
+  if (!blenderSessionStarted()) return;
+  await blenderRuntime().present();
+}
+
+export async function blenderEngineFile(path: string): Promise<Uint8Array> {
+  return blenderRuntime().readFile(path);
+}
+
+/** Read the scene animation for the Timeline preview and glTF export (`session.py`'s
+ *  `rna_scene_movie`). Returns null without starting an absent engine session. */
+export async function blenderSceneMovie(): Promise<BlenderSceneMovie | null> {
+  if (!blenderSessionStarted()) return null;
+  return blenderRuntime().sceneMovie();
+}
 
 export async function blenderOutlinerSet(
   path: string,
@@ -695,46 +965,11 @@ export async function blenderOutlinerSet(
   return written;
 }
 
-/**
- * THE NODE EDITOR'S VERBS, published ONCE and reached two ways (U8's ruling 1,
- * 2026-09-19). Under the Code-OSS frame each is a `volter.blender-node-view.<verb>`
- * command the bridge dispatches into the view; standalone `cyclotron edit`, which has
- * no command service, reaches the SAME table through the session's
- * `blender-node-view` verb below. One table, two doors — the shape
- * `key-actions.ts`'s action table already has, and the reason the next
- * three read-only editors (UV Editing, Animation, Texture Paint) add NO session
- * verb of their own: they register here instead.
- *
- * `state` reads it; `look` follows a node with the N-panel (`node`, null to look
- * at none); `view-all` is Blender's Home; `zoom` takes tree units per CSS px;
- * `pan` takes the tree-space point at the view's centre (`cx`/`cy`). Every
- * EDITING gesture is present and REFUSED by name with the same sentence the
- * pointer handlers give, so the read-only ruling is provable from the product
- * rather than merely implemented.
- */
-export const NODE_VIEW_VERBS: ViewVerbContribution = {
-  view: 'blender-node-view',
-  title: 'Node Editor',
-  verbs: (
-    [
-      ['state', undefined],
-      ['look', undefined],
-      ['view-all', 'Node Editor: Frame All'],
-      ['zoom', undefined],
-      ['pan', undefined],
-      ['move', undefined],
-      ['link', undefined],
-      ['set-value', undefined],
-      ['use-nodes', undefined],
-      ['collapse-panel', undefined],
-    ] as const
-  ).map(([id, title]) => ({
-    id,
-    ...(title ? { title } : {}),
-    run: (args?: Record<string, unknown>) =>
-      driveNodeView({ type: 'blender-node-view', ...args, action: id }),
-  })),
-};
+/** Node-view actions share driveNodeView between page commands and the session relay. State reads, focus, framing, zoom and pan update inspection state; editing gestures refuse by name. */
+export const NODE_VIEW_VERBS: readonly ViewVerb[] = (['state', 'look', 'view-all', 'zoom', 'pan', 'move', 'link', 'set-value', 'use-nodes', 'collapse-panel'] as const).map((id) => ({
+  id,
+  run: (args?: Record<string, unknown>) => driveNodeView({ type: 'blender-node-view', ...args, action: id }),
+}));
 
 /**
  * `blender-node-view` — the node editor's actions and its state, as one verb.
@@ -758,10 +993,7 @@ function driveNodeView(cmd: { type: string; [key: string]: unknown }): NodeViewS
       break;
     case 'view-all':
       requestNodeViewAll();
-      // Framing clears a refusal the way every other non-editing action does.
-      // Measured live 2026-09-19: without this, a refusal outlived the gesture
-      // that raised it and the status line still carried it three actions
-      // later.
+      // A successful framing action clears the prior refusal.
       setNodeViewState({ refusal: null });
       break;
     case 'zoom': {
@@ -781,9 +1013,7 @@ function driveNodeView(cmd: { type: string; [key: string]: unknown }): NodeViewS
       });
       break;
     }
-    // EVERY EDITING GESTURE, ANSWERED BY NAME. These are the same four
-    // refusals the pointer handlers raise, reachable from the session so the
-    // ruling is provable rather than merely implemented.
+    // Expose the same named editing refusals through commands and pointer handlers.
     case 'move':
       refuseNodeViewGesture(
         `Moving "${String(cmd['node'] ?? 'a node')}" writes Node.location — editing parity is not the program.`,
@@ -825,7 +1055,7 @@ function driveNodeView(cmd: { type: string; [key: string]: unknown }): NodeViewS
 interface RuntimeView {
   readonly root: THREE.Group;
   stageFrame(part: { session: string; revision: number; abort?: boolean; mesh?: string; image?: string; piece?: unknown }): void;
-  applyFrame(frame: unknown): unknown;
+  applyFrame(frame: unknown): ReturnType<BlenderRuntimeView['applyFrame']>;
   snapshot(): ReturnType<BlenderRuntimeView['snapshot']>;
   drawStatistics(): ReturnType<BlenderRuntimeView['drawStatistics']>;
   setDrawBatching(enabled: boolean): void;
@@ -873,19 +1103,11 @@ function terminateBlenderRuntime(): void {
     captureLifetime = null;
     runtime?.terminate();
     runtime = null;
-    lastCapture = null;
+    clearModelDocumentSaving();
   } finally { end(); }
 }
 
-// THE ENGINE DIES WITH THE SESSION, whether or not the tab can. A page told
-// `tab-close` calls `window.close()`, which Chrome refuses for a tab a person
-// opened, and falls back to a "Session ended" notice -- a repaint of the
-// document that terminates nothing. The Blender worker kept its whole engine
-// resident behind that notice: measured 2026-09-17, two orphaned tabs from
-// two editor restarts held 13 GB and 7 GB between them and put the box into a
-// swap storm (26 GB of swap, kernel_task at 245%). `session.onEnded` is the
-// host's one signal for every session end, graceful or not, so the worker is
-// terminated there.
+// Terminate the Blender worker on session.onEnded, including when the browser refuses window.close on a person-opened tab.
 function watchSessionEnd(): void {
   if (watchingSessionEnd) return;
   watchingSessionEnd = true;
@@ -895,10 +1117,9 @@ function watchSessionEnd(): void {
 
 async function stopBlenderRuntime(): Promise<void> {
   const owner = runtime;
-  await owner?.stop();
+  if (owner) await retireRuntime(owner);
   if (runtime === owner) terminateBlenderRuntime();
 }
-let lastCapture: CaptureRequest | null = null;
 
 const isRuntimeView = (value: unknown): value is RuntimeView =>
   typeof value === 'object' &&
@@ -913,13 +1134,7 @@ const isRuntimeView = (value: unknown): value is RuntimeView =>
 
 async function runtimeView(): Promise<RuntimeView> {
   const { documents } = editorHost();
-  // 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).
+  // Re-read the Model binding while waiting: a presentation can begin before its pane publishes the final document address.
   const deadline = Date.now() + 15_000;
   let id = presentationDocumentId();
   let publication = 'no context';
@@ -965,12 +1180,19 @@ export function blenderRuntime(): BlenderRuntime {
   const discardStreamedFrame = () => {
     const staged = streamedFrame;
     streamedFrame = null;
+    frameStagedAt = null;
     if (staged) staged.view.stageFrame({ session: staged.session, revision: staged.revision, abort: true });
     discardRenderFrame();
   };
   lifetime.signal.addEventListener('abort', discardStreamedFrame, { once: true });
   runtime = new BlenderRuntime({
     work: beginBlenderWork,
+    documentSaving: ({ document, note }) => {
+      if (!lifetime.signal.aborted) setModelDocumentSaveNotice(document, note);
+    },
+    documentDirty: () => {
+      for (const listener of [...modelDirtyListeners]) listener();
+    },
     history: (entries) => {
       const owner = runtime;
       if (!owner) throw new Error('Blender history arrived before its runtime');
@@ -1013,6 +1235,7 @@ export function blenderRuntime(): BlenderRuntime {
       if (part.evaluation === 'render') {
         if (!renderFrame) {
           if (part.mesh !== undefined || part.image !== undefined) throw new Error('Render resource arrived before its frame');
+          frameStagedAt = performance.now();
           const detached = BlenderRuntimeView.forPhotograph();
           view.root.updateWorldMatrix(true, false);
           detached.root.matrix.copy(view.root.matrixWorld);
@@ -1026,6 +1249,7 @@ export function blenderRuntime(): BlenderRuntime {
       if (renderFrame) throw new Error('Viewport frame arrived during render transfer');
       if (streamedFrame && streamedFrame.view !== view)
         throw new Error('Blender presenter changed during frame transfer');
+      if (!streamedFrame) frameStagedAt = performance.now();
       view.stageFrame(part);
       streamedFrame = { view, session: part.session, revision: part.revision };
     },
@@ -1060,31 +1284,26 @@ export function blenderRuntime(): BlenderRuntime {
       if (rendering && (rendering.source !== view || rendering.sourceFrame !== view.snapshot() || rendering.documentId !== documentId))
         throw new Error('Blender capture source changed before render presentation');
       const presenter = rendering?.view ?? view;
-      // WHAT THE PRESENTER HELD BEFORE THIS FRAME, carried back to the session
-      // beside whatever this present produced. The session only has a RECORD of
-      // what it sent; this view is the authority on what it actually holds, and
-      // the two come apart whenever the Model document is rebuilt under a
-      // 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`.
+      // Report the presenter’s holding before applying this frame.
       const endApply = beginBlenderWork('applying frame to Model');
+      const applyAt = performance.now();
       const applied = (() => {
-        try { return presenter.applyFrame(frame) as { held?: unknown } | null | undefined; }
+        try { return presenter.applyFrame(frame); }
         finally { endApply(); }
       })();
+      const appliedAt = performance.now();
+      const stagedAt = frameStagedAt;
+      frameStagedAt = null;
       streamedFrame = null;
-      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 => ({
         ...(capture === undefined ? {} : { capture }),
-        ...(reports ? { held } : {}),
+        held: applied.held,
       });
       // THE RECORD OF WHAT WAS SUBMITTED, kept only once the frame was taken:
       // a refused frame is not displayed and must not be described as if it
       // were.
       presenter.recordPresentation(description);
       if (!capture) return answer(undefined);
-      lastCapture = capture;
       if (!capture.render) return answer(undefined);
       const presented = view.snapshot();
       // A COMPOSITED FRAME IS NOT PHOTOGRAPHED. The compositor already
@@ -1110,14 +1329,10 @@ export function blenderRuntime(): BlenderRuntime {
       // through THAT matrix -- copied into the detached snapshot, never written out
       // here as a quarter turn -- and a fresh camera is placed on it.
       //
-      // MEASURED 2026-09-18, and the reason this code exists: handing the raw
-      // Blender numbers to `presentEditorView` read them as three.js world
-      // space, so a camera at Blender (0, -3, 0.42) looking +Y photographed the
-      // model's underside from 3 m below the floor, and a straight-down camera
-      // produced a level side view. Every hero image the battery ever graded
-      // came from a misplaced camera. The old path also moved the VIEWPORT onto
-      // the render camera and moved it back; a render that never touches the
-      // viewport needs no such dance, so it is gone rather than made safe.
+      // Handing the raw Blender numbers to `presentEditorView` would read them
+      // as three.js world space and photograph the model from a misplaced
+      // camera, and a render that never touches the viewport needs no move of
+      // the VIEWPORT onto the render camera and back.
       const { render, position, target, up } = capture;
       if (!position || !target || !up)
         throw new Error(
@@ -1151,22 +1366,13 @@ export function blenderRuntime(): BlenderRuntime {
         renderCamera.position.copy(eye);
         renderCamera.lookAt(focus);
         renderCamera.updateMatrixWorld(true);
-        // THE POSE THIS PHOTOGRAPH USED, BACK IN BLENDER'S FRAME. Python asserts
-        // it equals what it sent, with no tolerance: the model root's matrix is an
-        // exact signed axis permutation, so a vector through it and its inverse is
-        // bit-identical. A mismatch means the conversion above is wrong, and the
-        // whole point of this instrument is that a misplaced render camera is
-        // otherwise invisible -- photograph-vs-Cycles is a declared difference, so
-        // the battery's image rows hid it for the entire life of this lane.
+        // Transform the photograph’s pose back through the exact signed axis permutation. Python compares it with the submitted pose and rejects any mismatch.
         const photographedFrom = {
           position: eye.clone().applyMatrix4(toBlender).toArray(),
           target: focus.clone().applyMatrix4(toBlender).toArray(),
           up: upward.clone().applyMatrix3(blenderBasis).toArray(),
         };
-        // RECORDED BEFORE THE PICTURE IS TAKEN, and before Python compares the
-        // two poses. The assertion on the other side THROWS on a mismatch, and
-        // an exception carries the defect out of reach of a harness grading the
-        // run afterwards; both poses have to survive it.
+        // Retain both poses before capture and Python validation, including a refused photograph.
         view.recordPhotograph({
           sent: { position, target, up },
           photographed: photographedFrom,
@@ -1177,7 +1383,15 @@ export function blenderRuntime(): BlenderRuntime {
             orthographic: render.orthographic,
           },
         });
+        const photoAt = performance.now();
         const display = await photographSnapshot(scene, renderCamera, snapshot, render, assertBinding);
+        // Queue each photograph directly for the movie encoder.
+        if (film) film.photographs.push(display.base64);
+        // (a film's frames are viewport photographs, `rendering` null: they are timed too)
+        if (rendering || film) {
+          renderTimings.push({ stageMs: stagedAt === null ? 0 : applyAt - stagedAt, applyMs: appliedAt - applyAt, photoMs: performance.now() - photoAt });
+          if (renderTimings.length > 64) renderTimings.shift();
+        }
         return answer({ ...display, camera: photographedFrom });
       } finally {
         photographing = false;
@@ -1220,25 +1434,7 @@ export function blenderRuntime(): BlenderRuntime {
   return runtime;
 }
 
-/** The view the last `blender-screenshot-view` asked the tab to photograph. */
-export function lastBlenderCapture(): CaptureRequest | null {
-  return lastCapture;
-}
-
-/**
- * THE SESSION'S DOCUMENT when `blender-start` does not name one.
- *
- * Persistence is ON by default, because the job this lane exists to do is to
- * not lose what a script modelled: before this, closing the tab lost it, with
- * no `.blend` anywhere. `models/` rather than `public/` is what says a
- * document is the SOURCE a shipped artifact is exported from, not the artifact
- * — which is also why it carries no provenance record (`volter blender-mcp`'s
- * Mirror owns that line, for `public/`).
- *
- * It is the fallback only. A project that declares the `model` finder lists
- * its OWN `.blend` files, and the document opened for one of those binds the
- * session to it ({@link openModelDocumentBlend}).
- */
+/** The default session document persists under models/ as source. A project’s declared Model file takes precedence. Public exported artifacts are recorded by the MCP mirror. */
 const DEFAULT_BLENDER_DOCUMENT = 'models/model.blend';
 
 const string = (cmd: Record<string, unknown>, key: string): string => {
@@ -1352,16 +1548,16 @@ export async function handleBlenderCommand(cmd: {
         // 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.
-        const shown =
-          unlistedFollow !== null && unlistedFollow.owner === session && unlistedFollow.from === (boundModel?.blend ?? DEFAULT_BLENDER_DOCUMENT)
-            ? unlistedFollow.document
-            : boundModel?.blend;
-        const document =
-          requestedDocument !== undefined
-            ? requestedDocument
-            : (shown ?? DEFAULT_BLENDER_DOCUMENT);
+        // 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 session.start(project!, document)) } };
+          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.
@@ -1370,16 +1566,7 @@ export async function handleBlenderCommand(cmd: {
         }
       }
       case 'blender-execute': {
-        // THROUGH THE IN-PAGE DOOR, not `session.execute` beside it — the same
-        // rule `blender-rna-set` below follows, and for the same reason: the
-        // RNA version is minted at the door (ruling 3, 2026-09-19), and
-        // ARBITRARY bpy can change anything RNA answers, so a script that
-        // reached the engine around it would leave every view drawing the tree
-        // it had. One path for a `cyclotron eval`, an MCP call and a panel's own
-        // operator.
-        // THE DOOR'S TEXT, verbatim — `execute_blender_code`'s MCP contract is
-        // that one string, so the wire keeps answering it while the in-page
-        // callers read the parsed halves beside it.
+        // 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'));
         return { ok: true, data: { result: answer.text } };
       }
@@ -1404,10 +1591,7 @@ export async function handleBlenderCommand(cmd: {
       }
       case 'blender-rna-set': {
         const index = typeof cmd['index'] === 'number' ? cmd['index'] : undefined;
-        // THROUGH THE IN-PAGE DOOR, not `session.rnaSet` beside it: the door is
-        // where the RNA version is minted (ruling 3, 2026-09-19), and a write
-        // that reached the engine around it would leave every view drawing the
-        // tree it had — which is exactly the defect the version exists for.
+        // Use the in-page RNA write door so every write bumps the shared version.
         return {
           ok: true,
           data: {
@@ -1473,30 +1657,11 @@ export async function handleBlenderCommand(cmd: {
       // is a projection of the tree the door already answered, so its actions
       // are pure state (`src/node-view-state.ts`).
       //
-      // THE SESSION IS THE STANDALONE DOOR ONTO `NODE_VIEW_VERBS`, not a second
-      // implementation (U8's ruling 1). Under the Code-OSS frame each verb is a
-      // `volter.blender-node-view.<verb>` command; standalone `cyclotron edit` has no
-      // command service, so this verb routes the SAME table. `invokeViewVerb`
-      // throws the view's own refusal, which is the sentence this door already
-      // answered with.
-      case 'blender-node-view': {
-        const action = typeof cmd['action'] === 'string' ? cmd['action'] : 'state';
-        // An action the TABLE does not carry is still the VIEW's refusal, not the
-        // registry's: I5's proof is that an unknown action names the verb's whole
-        // vocabulary IN THE VIEW's own frame warning, and a thrown registry message
-        // would move that refusal somewhere the view does not draw. So the registry
-        // answers when it can and `driveNodeView`'s own default answers when it
-        // cannot — one implementation either way.
-        const known = NODE_VIEW_VERBS.verbs.some((verb) => verb.id === action);
-        return {
-          ok: true,
-          data: {
-            result: known
-              ? (invokeViewVerb('blender-node-view', action, cmd) as NodeViewState)
-              : driveNodeView(cmd),
-          },
-        };
-      }
+      // The same table the `volter.blender-node-view.<verb>` commands run
+      // (`NODE_VIEW_VERBS`): every action is `driveNodeView`'s, and an action it
+      // does not carry is refused by its own default, naming the vocabulary.
+      case 'blender-node-view':
+        return { ok: true, data: { result: driveNodeView(cmd) } };
       case 'blender-outliner-set':
         return {
           ok: true,
@@ -1528,10 +1693,7 @@ export async function handleBlenderCommand(cmd: {
         return { ok: true, data: { ...preview } };
       }
       case 'blender-read-file': {
-        // The bytes go out as a BODY, not inside this command's answer -- see
-        // `/__editor/blender-file` in `server/routes/relay.ts` for the
-        // measurement that moved them. The caller mints the transfer id, so
-        // the page never names anything on the host's disk.
+        // Transfer bytes in the HTTP body under a caller-minted id; return only the size in the command answer.
         const bytes = await session.readFile(string(cmd, 'path'));
         const transfer = string(cmd, 'transferId');
         const posted = await fetch(`/__editor/blender-file?id=${encodeURIComponent(transfer)}`, {
@@ -1543,9 +1705,32 @@ export async function handleBlenderCommand(cmd: {
           return { ok: false, error: `Transfer ${transfer} was refused: ${posted.status}` };
         return { ok: true, data: { bytes: bytes.length } };
       }
+      // A FILM, RENDERED (`cyclotron render-movie`, a film's Blender shots): started here, answering at once, and
+      // followed until it ends (`renderBlenderMovie`).
+      case 'blender-render-movie': {
+        const optional = (key: string): string | number | undefined => {
+          const value = cmd[key];
+          if (value === undefined || typeof value === 'number' || typeof value === 'string') return value;
+          throw new Error(`${key} is a frame number or a marker name.`);
+        };
+        const width = cmd['width'];
+        const fps = cmd['fps'];
+        const document = cmd['document'];
+        return {
+          ok: true,
+          data: { ...startBlenderMovie({
+            out: string(cmd, 'out'),
+            ...(typeof document === 'string' ? { document } : {}),
+            from: optional('from'), to: optional('to'),
+            ...(typeof width === 'number' ? { width } : {}),
+            ...(typeof fps === 'number' ? { fps } : {}),
+          }) },
+        };
+      }
+      case 'blender-render-status':
+        return { ok: true, data: { ...(await movieRenders.status(string(cmd, 'out'))) } };
       case 'blender-write-file': {
-        const binary = atob(string(cmd, 'base64'));
-        const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+        const bytes = bytesFromBase64(string(cmd, 'base64'));
         await session.writeFile(string(cmd, 'path'), bytes);
         return { ok: true, data: { written: bytes.length } };
       }
@@ -1563,23 +1748,7 @@ export async function handleBlenderCommand(cmd: {
             entries,
             session: document.session,
             revision: document.revision,
-            // AND WHAT THE BYTES WERE MADE FROM. A session-written `.glb` is
-            // exported from a `.blend`, and that path is the one fact that
-            // lets a reader go DOWN by kind later — from a prefab's glTF to
-            // the model document it came from (ARCHITECTURE-CORE §Roots,
-            // "Drilling goes DOWN by kind"). Taken at the instant of the
-            // listing, for the same reason the session identity is.
-            //
-            // IT IS ASKED OF PYTHON, NOT OF `boundModel`, and that distinction
-            // is a measurement rather than a preference. `boundModel` is the
-            // document the TAB opened; a bake script opens its own file with
-            // `wm.open_mainfile`, which retargets `bpy.data.filepath` at once,
-            // the tab only after the call (`followMovedDocument`), and never
-            // for a file outside the project. Measured 2026-09-19: reading `boundModel` recorded
-            // the SAME `.blend` as the input of all three of first-person's
-            // characters — whichever one the tab happened to show — which is
-            // worse than no record, because it is a confident wrong answer.
-            // `bpy.data.filepath` is what the export actually came out of.
+            // Read bpy.data.filepath at listing time as the exported files’ input. A script may have opened a different file before the tab follows that move.
             ...sessionDocumentPath(document.filepath),
           },
         };