@volter/editor-blender 0.1.149 → 0.1.151

package/host/scene-sound.ts

@@ -0,0 +1,143 @@
+/**
+ * THE SCENE'S SOUND, MIXED IN THE PAGE (docs/adr/movie-sound-and-react-frames.md, decision 2): this
+ * Blender build has no audio (`aud` and `sound.mixdown` are unavailable), so `render-movie` mixes what `session.py`'s `sound-scene` describes in an
+ * OfflineAudioContext, 48 kHz stereo, from the movie's first frame at 0 s:
+ *
+ * - a sound strip plays its file from where the strip is cut, at its speed, through its volume per
+ *   frame (a fade is keys on volume) and, when its sound is mono, its pan per frame;
+ * - a speaker plays its file from each of its NLA sound strips' start frames, through its volume per
+ *   frame, from its place and facing per frame, heard from the scene camera's (the listener's);
+ * - the scene's own volume scales the mix, and a muted strip, channel, speaker or scene is silent.
+ *
+ * What differs from Blender's own mix is listed in the ADR and in SCENE-ANIMATION.md.
+ */
+import { bytesFromBase64 } from '@volter/blender-engine/browser/three/blender-base64';
+import type { BlenderClipColumn, BlenderSoundFile, BlenderSoundScene } from '@volter/blender-engine/browser/rna';
+
+const SCENE_SOUND_RATE = 48_000;
+
+/** A per-frame column as `count` values of `stride` floats (a constant column repeated). */
+function column(source: BlenderClipColumn, count: number, stride: number): Float32Array {
+  const bytes = bytesFromBase64(source.base64);
+  const values = new Float32Array(bytes.buffer);
+  if (source.count >= count) return values;
+  const out = new Float32Array(count * stride);
+  for (let i = 0; i < count; i++) out.set(values.subarray(0, stride), i * stride);
+  return out;
+}
+
+/** `param` follows `values` (one per frame), ramped linearly between frames from 0 s. */
+function follow(param: AudioParam, values: Float32Array, fps: number, stride = 1, offset = 0, map: (v: number) => number = (v) => v): void {
+  const count = values.length / stride;
+  param.setValueAtTime(map(values[offset]!), 0);
+  for (let i = 1; i < count; i++) param.linearRampToValueAtTime(map(values[i * stride + offset]!), i / fps);
+}
+
+const DISTANCE_MODELS: Readonly<Record<string, DistanceModelType>> = {
+  INVERSE: 'inverse', INVERSE_CLAMPED: 'inverse', LINEAR: 'linear', LINEAR_CLAMPED: 'linear', EXPONENT: 'exponential', EXPONENT_CLAMPED: 'exponential',
+};
+
+/**
+ * The movie's sound as one 48 kHz stereo buffer's planes, or null when the scene has none to play
+ * (no unmuted strip or speaker with a file). `read` gives a file's bytes.
+ */
+export async function mixSceneSound(
+  scene: BlenderSoundScene,
+  read: (file: BlenderSoundFile) => Promise<Uint8Array>,
+): Promise<{ readonly planes: Float32Array[]; readonly sampleRate: number; readonly strips: number; readonly speakers: number } | null> {
+  if (scene.muted && scene.speakers.length === 0) return null;
+  const strips = scene.muted ? [] : scene.strips.filter((strip) => !strip.muted && strip.file !== null);
+  const speakers = scene.speakers.filter((speaker) => !speaker.muted && speaker.file !== null && speaker.starts.length > 0);
+  if (strips.length === 0 && speakers.length === 0) return null;
+
+  const { fps, first, count } = scene;
+  const seconds = count / fps;
+  const context = new OfflineAudioContext({ numberOfChannels: 2, length: Math.ceil(seconds * SCENE_SOUND_RATE), sampleRate: SCENE_SOUND_RATE });
+  const master = context.createGain();
+  master.gain.value = scene.volume;
+  master.connect(context.destination);
+
+  const decoded = new Map<string, Promise<AudioBuffer>>();
+  const decode = (file: BlenderSoundFile): Promise<AudioBuffer> => {
+    const key = 'path' in file ? file.path : file.packed;
+    let buffer = decoded.get(key);
+    if (!buffer) {
+      buffer = read(file).then((bytes) => context.decodeAudioData(bytes.slice().buffer as ArrayBuffer)).catch((thrown: unknown) => {
+        throw new Error(`The sound ${key} could not be read or decoded in this browser: ${thrown instanceof Error ? thrown.message : String(thrown)}`);
+      });
+      decoded.set(key, buffer);
+    }
+    return buffer;
+  };
+
+  for (const strip of strips) {
+    const from = Math.max(strip.finalStart, first);
+    const to = Math.min(strip.finalEnd, first + count);
+    if (to <= from) continue;
+    const buffer = await decode(strip.file!);
+    const source = context.createBufferSource();
+    source.buffer = buffer;
+    source.playbackRate.value = strip.speed;
+    const gain = context.createGain();
+    follow(gain.gain, column(strip.volume, count, 1), fps);
+    source.connect(gain);
+    let out: AudioNode = gain;
+    if (strip.mono || buffer.numberOfChannels === 1) {
+      // Blender pans only a mono sound; a mono strip of a stereo file is mixed down first
+      gain.channelCount = 1;
+      gain.channelCountMode = 'explicit';
+      gain.channelInterpretation = 'speakers';
+      const pan = context.createStereoPanner();
+      follow(pan.pan, column(strip.pan, count, 1), fps, 1, 0, (v) => Math.max(-1, Math.min(1, v)));
+      gain.connect(pan);
+      out = pan;
+    }
+    out.connect(master);
+    source.start((from - first) / fps, ((from - strip.start) / fps) * strip.speed, ((to - from) / fps) * strip.speed);
+  }
+
+  if (speakers.length > 0 && scene.listener) {
+    const listener = context.listener;
+    const position = column(scene.listener.position, count, 3);
+    const forward = column(scene.listener.forward, count, 3);
+    const up = column(scene.listener.up, count, 3);
+    follow(listener.positionX, position, fps, 3, 0); follow(listener.positionY, position, fps, 3, 1); follow(listener.positionZ, position, fps, 3, 2);
+    follow(listener.forwardX, forward, fps, 3, 0); follow(listener.forwardY, forward, fps, 3, 1); follow(listener.forwardZ, forward, fps, 3, 2);
+    follow(listener.upX, up, fps, 3, 0); follow(listener.upY, up, fps, 3, 1); follow(listener.upZ, up, fps, 3, 2);
+  }
+  for (const speaker of speakers) {
+    const buffer = await decode(speaker.file!);
+    const gain = context.createGain();
+    follow(gain.gain, column(speaker.volume, count, 1), fps, 1, 0, (v) => Math.max(speaker.volumeMin, Math.min(speaker.volumeMax, v)));
+    const panner = context.createPanner();
+    panner.panningModel = 'equalpower';
+    panner.distanceModel = DISTANCE_MODELS[scene.distanceModel] ?? 'inverse';
+    panner.refDistance = speaker.distanceReference;
+    panner.maxDistance = speaker.distanceMax;
+    panner.rolloffFactor = scene.distanceModel === 'NONE' ? 0 : speaker.attenuation;
+    panner.coneInnerAngle = (speaker.coneInner * 180) / Math.PI;
+    panner.coneOuterAngle = (speaker.coneOuter * 180) / Math.PI;
+    panner.coneOuterGain = speaker.coneOuterVolume;
+    const position = column(speaker.position, count, 3);
+    const facing = column(speaker.facing, count, 3);
+    follow(panner.positionX, position, fps, 3, 0); follow(panner.positionY, position, fps, 3, 1); follow(panner.positionZ, position, fps, 3, 2);
+    follow(panner.orientationX, facing, fps, 3, 0); follow(panner.orientationY, facing, fps, 3, 1); follow(panner.orientationZ, facing, fps, 3, 2);
+    gain.connect(panner).connect(master);
+    for (const start of speaker.starts) {
+      const end = start + (buffer.duration * fps);
+      if (end <= first || start >= first + count) continue;
+      const source = context.createBufferSource();
+      source.buffer = buffer;
+      source.connect(gain);
+      source.start(Math.max(0, (start - first) / fps), Math.max(0, (first - start) / fps));
+    }
+  }
+
+  const mixed = await context.startRendering();
+  return {
+    planes: [mixed.getChannelData(0), mixed.getChannelData(1)],
+    sampleRate: SCENE_SOUND_RATE,
+    strips: strips.length,
+    speakers: speakers.length,
+  };
+}

package/node/blender-mcp.ts

@@ -6,10 +6,10 @@
  * No modeling happens in this process. `execute_blender_code`,
  * `get_scene_info`, `get_object_info` and `get_viewport_screenshot` become
  * `blender-*` control commands answered by the tab's worker
- * (`packages/editor-blender/contributions/blender.command.ts`, the engine's own
- * `workspace.command` contribution); the screenshot is the tab
- * photographing its own Model document. The 24 integration tools answer as
- * an add-on with no integrations, exactly as the Python server did.
+ * (`packages/editor-blender/contributions/blender.verbs.ts`, the engine's own
+ * Code-OSS commands); the screenshot is the tab
+ * photographing its own Model document. The remaining tools return static
+ * status or disabled-integration responses.
  */
 import { randomUUID } from 'node:crypto';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -22,7 +22,8 @@ import {
   ListPromptsRequestSchema,
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
-import { EditorClient, type EditorView } from '@volter/sdk';
+import { EditorClient } from '@volter/live/client';
+import type { EditorView } from '@volter/sdk';
 import blenderBundle from '@volter/blender-engine/wasm/BUNDLE.json';
 import { projectOutputRootOf } from '@volter/sdk/project/output-roots';
 import blenderDefaults from './blender-mcp-defaults.json';
@@ -110,52 +111,21 @@ function projectRelative(project: string, absolute: string): string | null {
  * (`C:\Users\me\p`) at its URI path (`/C:/Users/me/p`) — `projectMount` in
  * `@volter/blender-engine/browser/worker.ts`, which this mirrors because that module is the
  * worker's and cannot load here. Every path crossing the transport goes through these two:
- * the engine's spelling on the wire, the host's on disk. Until 2026-10-06 the Mirror sent the
- * host's spelling, the worker listed nothing at a path it did not have, and on Windows no
- * script output ever reached disk while every call reported success.
+ * the engine's spelling on the wire, the host's on disk. Sending the host's spelling would have
+ * the worker list nothing at a path it does not have, and on Windows no script output would
+ * reach disk while every call reported success.
  */
-export function engineSpelling(host: string): string {
+function engineSpelling(host: string): string {
   return /^[A-Za-z]:[\\/]/.test(host) ? `/${host.replaceAll('\\', '/')}` : host;
 }
 
 /** {@link engineSpelling} backwards: `/C:/Users/me/p/x.glb` → `C:\Users\me\p\x.glb` on
  *  Windows; a POSIX host's paths are the engine's own. */
-export function hostSpelling(engine: string, platform: NodeJS.Platform = process.platform): string {
-  return platform === 'win32' && /^\/[A-Za-z]:\//.test(engine) ? engine.slice(1).replaceAll('/', '\\') : engine;
+function hostSpelling(engine: string): string {
+  return process.platform === 'win32' && /^\/[A-Za-z]:\//.test(engine) ? engine.slice(1).replaceAll('/', '\\') : engine;
 }
 
-/**
- * The worker's filesystem is the only place a script's outputs exist; this
- * mirrors them to disk. Roots: the project (a script's `public/models/x.glb`
- * lands in the project) plus any `VOLTER_BLENDER_MIRROR_ROOTS` (absolute paths separated by
- * the platform's own `path.delimiter` — `:` on POSIX, `;` on Windows, where a drive letter's
- * colon is part of the path — the replay harness names its run directory). Only files
- * whose size or mtime changed since the last mirror are read back, and only
- * files the SESSION owns are listed at all — a project file it merely read
- * belongs to the host and is never written back over it.
- *
- * THIS IS THE DOOR THAT RECORDS, because it is the door a session's bytes
- * enter the project through. MEASURED 2026-09-18: a script's
- * `export_scene.gltf` to `<project>/public/models/lantern.glb` landed here and
- * `.volter/provenance.json` was never created — the one state
- * `scripts/validate-project-provenance.mjs` calls fatal, and the opposite of
- * the doctrine that a generated artifact enters `public/` through a door that
- * records it atomically. So a file this lands under `public/` is POSTed to the
- * session's `/__editor/blender-output`, which commits the bytes and the ledger
- * rewrite as ONE rollback-safe transaction through the same writer the
- * editor's own bake and acceptance tools use; the record's kind is
- * `project.session.write` and it names the session (see
- * `ProjectProvenanceSessionSchema`).
- *
- * The session process owns the writer and the project's ledger. This
- * transport uses that same session boundary as the other product commands;
- * it never creates a second ledger writer in the MCP process.
- *
- * Everything else the session owns — `.volter/tmp/*.png`, a `.blend`, a replay
- * harness's run directory outside the project — is mirrored with a plain write
- * and deliberately NOT recorded: the ledger is about what the project SHIPS,
- * and `public/` is what ships.
- */
+/** Mirror session-owned output files whose size or mtime changed to the project or VOLTER_BLENDER_MIRROR_ROOTS. Files under public/ go through /__editor/blender-output, which commits bytes and provenance atomically under the session writer. Other outputs use plain writes. Never mirror a host input merely read by Blender. */
 class Mirror {
   readonly #seen = new Map<string, string>();
   constructor(
@@ -165,13 +135,12 @@ class Mirror {
     private readonly source: string,
   ) {}
 
-  async sync(tab: TabSession, callId: string | null): Promise<number> {
-    let written = 0;
+  async sync(tab: TabSession, callId: string): Promise<void> {
     for (const root of this.roots) {
-      const listing = await tab.command<{
+      const listing = await tab.commandHeld<{
         entries: FileEntry[];
-        session?: string;
-        revision?: number;
+        session: string;
+        revision: number;
         document?: string;
       }>('blender-list-files', { path: engineSpelling(root) });
       for (const entry of listing.entries) {
@@ -185,20 +154,10 @@ class Mirror {
           projectPath !== null && projectOutputRootOf(projectPath) === 'public'
             ? projectPath
             : null;
-        // ANTI-SHIM: an unrecordable shipped file is REFUSED, not written
-        // anyway. Landing it unrecorded is the defect this door exists to
-        // close, and inventing a session for it would be worse than both.
-        if (shipped !== null && (listing.session === undefined || listing.revision === undefined))
-          throw new Error(
-            `The Blender session wrote ${shipped} but has not named itself — it has presented no ` +
-              'frame, so there is no session identity or revision to record the file under, and ' +
-              'an unrecorded binary under public/ is what `npm run validate-provenance` calls ' +
-              'fatal. Nothing was written for it.',
-          );
         // WE mint the transfer id and WE choose where the bytes land; the page
         // only hands over a body. See `/__editor/blender-file`.
         const transferId = randomUUID();
-        await tab.command<{ bytes: number }>('blender-read-file', { path: entry.path, transferId });
+        await tab.commandHeld<{ bytes: number }>('blender-read-file', { path: entry.path, transferId });
         const spooled = await fetch(`${await tab.origin()}/__editor/blender-file?id=${transferId}`);
         if (!spooled.ok) throw new Error(`Transfer of ${entry.path} failed: ${spooled.status}`);
         const bytes = Buffer.from(await spooled.arrayBuffer());
@@ -219,10 +178,10 @@ class Mirror {
         } else {
           const query = new URLSearchParams({
             path: shipped,
-            session: listing.session as string,
-            revision: String(listing.revision as number),
+            session: listing.session,
+            revision: String(listing.revision),
             source: this.source,
-            ...(callId === null ? {} : { callId }),
+            callId,
           });
           // WHAT THE BYTES WERE MADE FROM, when the session holds a document:
           // the `.blend` this export came out of. Passed as a repeatable
@@ -242,10 +201,8 @@ class Mirror {
           }
         }
         this.#seen.set(entry.path, stamp);
-        written += 1;
       }
     }
-    return written;
   }
 }
 
@@ -253,7 +210,6 @@ class TabSession {
   #client: EditorClient | null = null;
   #connecting: Promise<EditorClient> | null = null;
   #origin: string | null = null;
-  #port: number | null = null;
   /** A replay starts with a fresh model once; ordinary agent sessions persist. */
   #freshSessionPending = Boolean(process.env['VOLTER_BLENDER_FRESH_SESSION']);
   constructor(
@@ -268,7 +224,6 @@ class TabSession {
         await this.ensureEditor();
         const { resolveSession } = await import('@volter/live');
         const session = await resolveSession(this.project);
-        this.#port = session.port;
         this.#origin = `http://127.0.0.1:${session.port}`;
         this.#client = new EditorClient({ url: this.#origin });
         return this.#client;
@@ -285,44 +240,36 @@ class TabSession {
     return this.#origin as string;
   }
 
-  /** The machine-local port this project's session answers on — the address a
-   *  provenance record names so a reader can get back to the tab. */
-  async port(): Promise<number> {
-    await this.client();
-    return this.#port as number;
-  }
-
   /**
    * The Model document open and the session started at this project's path.
    *
    * Asked every call, never remembered: the session lives in the editor tab,
    * so an editor restart ends it while this process keeps running.
-   * The editor owns opening the Model document and idempotent startup. A
-   * separate status query would put a five-second check before that startup
-   * request and introduce a race with an editor restart.
+   * The editor owns opening the Model document and idempotent startup on each call.
    */
   async started(): Promise<EditorClient> {
     const client = await this.client();
     const fresh = this.#freshSessionPending;
     this.#freshSessionPending = false;
-    await client.blender('blender-start', { project: this.project, ...(fresh ? { fresh } : {}) });
+    await client.contributedVerb('blender-start', { project: this.project, ...(fresh ? { fresh } : {}) });
     return client;
   }
 
   async command<T>(type: string, fields: Record<string, unknown> = {}): Promise<T> {
     const client = await this.started();
-    return client.blender<T & object>(type as `blender-${string}`, fields);
+    return client.contributedVerb<T & object>(type, fields);
+  }
+
+  /** Read outputs through the session the call used, without another start. During Save As the tab can briefly lag Blender’s file; output reads need no document binding. */
+  async commandHeld<T>(type: string, fields: Record<string, unknown>): Promise<T> {
+    const client = await this.client();
+    return client.contributedVerb<T & object>(type, fields);
   }
 }
 
 const text = (value: string) => ({ content: [{ type: 'text' as const, text: value }] });
 
-/** `VOLTER_BLENDER_MIRROR_ROOTS`, split on the platform's delimiter. A root Blender cannot mount
- *  is REFUSED by name rather than dropped: dropping it was how a Windows root (`C:\…`, split on
- *  its own colon) silently mirrored nothing. Blender's filesystem has a mount for a POSIX root
- *  (`/runs/x`) and a drive root (`C:\runs\x`, as `/C:/runs/x`) only, so a relative path, a UNC
- *  share (`\\server\share`) and a drive-less rooted path (`\runs\x`) — all of which Node calls
- *  absolute or nearly — are refused too (#147 review). */
+/** Split VOLTER_BLENDER_MIRROR_ROOTS by the platform delimiter. Accept only mountable POSIX or drive roots; refuse relative, UNC and drive-less rooted paths by name. */
 function mirrorRoots(raw: string | undefined): string[] {
   const roots = (raw ?? '').split(delimiter).filter((root) => root !== '');
   const mountable = (root: string) => /^[A-Za-z]:[\\/]/.test(root) || (root.startsWith('/') && !root.startsWith('//'));
@@ -342,17 +289,14 @@ export async function serveBlenderMcp(
   command: string,
 ): Promise<void> {
   const runtimeIdentity = `Blender ${blenderBundle.blender} (source ${blenderBundle.source}), compiled to WebAssembly and running headless in the editor tab; three.js takes its photographs. Factory bpy.context.scene.render.engine: '${blenderBundle.factoryEngine}'. Documents are .blend. save_as_mainfile records the actual saved path in bpy.data.filepath; open_mainfile reopens it.`;
-  // THE PHOTOGRAPH STAYS IN THE EDITOR. An agent asked to "take a photograph" with no word on where
-  // it goes rendered one, wrote it into the project and ran the OS `open` on it: Preview started
-  // outside the editor. The editor already shows a picture as one of its documents.
+  // Photographs remain visible in the editor's own image documents.
   const photographs = `A photograph is shown to the person in the editor, never in another app: get_viewport_screenshot returns one, and an image file written inside the project opens as an editor document with \`npx ${command} eval 'editor.openAsset("<project-relative path>")'\`. Do not run the OS \`open\` on it.`;
   // Blender's own spelling of the root: on Windows the project's `C:\…` is `/C:/…` inside it, and
   // a script told the host spelling writes to a path that is not the project's.
   const mounted = engineSpelling(project);
   // Files the agent wrote a moment ago are copied in before each call (blender-engine worker,
-  // stageProjectFiles), so a project script runs from its file; an agent unsure of that built its level
-  // through the eval CLI instead of this door (2026-10-06, the WSL obby run).
-  const filesystem = `Project files are mounted in Blender at the project's actual absolute path: ${mounted}${mounted !== project ? ` (this machine's ${project})` : ''}. Use that root for image loads, saves and exports; /project is not an alias. The project's source files written before a call, including ones written just now, are in place when that call runs (dotfiles and dot-directories, node_modules, dist, coverage and logs are not copied in), so run a project script from its file: exec(open(${JSON.stringify(`${mounted}/src/models/<name>.py`)}).read()).`;
+  // stageProjectFiles), so a project script runs from its file; the instructions say so.
+  const filesystem = `Project files are mounted in Blender at the project's actual absolute path: ${mounted}${mounted !== project ? ` (this machine's ${project})` : ''}. Use that root for image loads, saves and exports; /project is not an alias. The project's source files written before a call, including ones written just now, are in place when that call runs (dotfiles and dot-directories, node_modules, dist, coverage and logs are not copied in), so run a project script from its file: import runpy; script_globals = runpy.run_path(${JSON.stringify(`${mounted}/src/models/<name>.py`)}, run_name="__main__"). This sets __file__ for sibling asset paths and returns the script's own globals as script_globals.`;
   const instructions = `${runtimeIdentity}\n${filesystem}\n${photographs}`;
   const tools = (blenderTools as ToolShape[]).map((tool) =>
     tool.name === 'execute_blender_code'
@@ -389,7 +333,7 @@ export async function serveBlenderMcp(
     // The transport's own number for THIS call. A file the script writes is
     // recorded under it, so a ledger entry points back at the exact request
     // that produced the bytes.
-    const callId = extra.requestId === undefined ? null : String(extra.requestId);
+    const callId = String(extra.requestId);
     if (name in STATIC_TOOLS) return text(STATIC_TOOLS[name]!);
     if (name in defaults) return text(defaults[name]!);
     switch (name) {
@@ -419,7 +363,20 @@ export async function serveBlenderMcp(
         const { result } = await tab.command<{ result: string }>('blender-execute', {
           code: String(args['code'] ?? ''),
         });
-        await mirror.sync(tab, callId);
+        // The script has run and what it saved is saved: a failure to copy its other files is said BESIDE its
+        // answer, preserving the script’s successful result.
+        try {
+          await mirror.sync(tab, callId);
+        } catch (error) {
+          return {
+            ...text(
+              `${result}\n\nThe script ran, but the files it wrote did not all reach the project's disk: ` +
+                `${error instanceof Error ? error.message : String(error)}. The next execute_blender_code call ` +
+                'copies what is still missing.',
+            ),
+            isError: true,
+          };
+        }
         return text(result);
       }
       case 'get_viewport_screenshot': {
@@ -429,7 +386,6 @@ export async function serveBlenderMcp(
           view?: { size: number; position?: number[]; target?: number[] };
           error?: string;
         }>('blender-screenshot-view', { maxSize });
-        if (!answer.document) throw new Error('Screenshot failed: Blender supplied no document address');
         if (!answer.view)
           throw new Error(answer.error ?? 'Screenshot failed: No 3D viewport found');
         const { view } = answer;