@volter/editor-blender 0.1.150 → 0.1.151

package/producticons/blender-product-icon-theme.json

@@ -0,0 +1,129 @@
+{
+	"_generated": "scripts/workbench/generate-icons.mjs — do not edit. Source: packages/blender/contributions/blender.icons.json sha256 d515ee16432ecbc75a05f9854d7055e4e33d4f05aead3db89709b9d8239df670; 37 ids over 35 traced glyphs.",
+	"fonts": [
+		{
+			"id": "blender",
+			"src": [
+				{
+					"path": "./blender-icons.otf",
+					"format": "opentype"
+				}
+			],
+			"weight": "normal",
+			"style": "normal"
+		}
+	],
+	"iconDefinitions": {
+		"chevron-down": {
+			"fontCharacter": "\\e000"
+		},
+		"chevron-left": {
+			"fontCharacter": "\\e001"
+		},
+		"chevron-right": {
+			"fontCharacter": "\\e002"
+		},
+		"chevron-up": {
+			"fontCharacter": "\\e000"
+		},
+		"arrow-down": {
+			"fontCharacter": "\\e003"
+		},
+		"arrow-left": {
+			"fontCharacter": "\\e004"
+		},
+		"arrow-right": {
+			"fontCharacter": "\\e005"
+		},
+		"arrow-up": {
+			"fontCharacter": "\\e006"
+		},
+		"triangle-down": {
+			"fontCharacter": "\\e007"
+		},
+		"triangle-right": {
+			"fontCharacter": "\\e008"
+		},
+		"close": {
+			"fontCharacter": "\\e009"
+		},
+		"chrome-close": {
+			"fontCharacter": "\\e009"
+		},
+		"add": {
+			"fontCharacter": "\\e00a"
+		},
+		"remove": {
+			"fontCharacter": "\\e00b"
+		},
+		"trash": {
+			"fontCharacter": "\\e00c"
+		},
+		"search": {
+			"fontCharacter": "\\e00d"
+		},
+		"zoom-in": {
+			"fontCharacter": "\\e00e"
+		},
+		"zoom-out": {
+			"fontCharacter": "\\e00f"
+		},
+		"eye": {
+			"fontCharacter": "\\e010"
+		},
+		"eye-closed": {
+			"fontCharacter": "\\e011"
+		},
+		"check": {
+			"fontCharacter": "\\e012"
+		},
+		"info": {
+			"fontCharacter": "\\e013"
+		},
+		"warning": {
+			"fontCharacter": "\\e014"
+		},
+		"error": {
+			"fontCharacter": "\\e015"
+		},
+		"folder": {
+			"fontCharacter": "\\e016"
+		},
+		"folder-opened": {
+			"fontCharacter": "\\e017"
+		},
+		"file": {
+			"fontCharacter": "\\e018"
+		},
+		"file-code": {
+			"fontCharacter": "\\e019"
+		},
+		"copy": {
+			"fontCharacter": "\\e01a"
+		},
+		"link": {
+			"fontCharacter": "\\e01b"
+		},
+		"lock": {
+			"fontCharacter": "\\e01c"
+		},
+		"unlock": {
+			"fontCharacter": "\\e01d"
+		},
+		"play": {
+			"fontCharacter": "\\e01e"
+		},
+		"debug-pause": {
+			"fontCharacter": "\\e01f"
+		},
+		"debug-stop": {
+			"fontCharacter": "\\e020"
+		},
+		"list-flat": {
+			"fontCharacter": "\\e021"
+		},
+		"ellipsis": {
+			"fontCharacter": "\\e022"
+		}
+	}
+}

package/serving/blender-routes.ts

@@ -1,13 +1,4 @@
-/**
- * `@volter/editor-blender`'s server half (`package.json#volter.serving`): the routes the Blender
- * in the tab needs from the session — the engine's WebAssembly build, the file spool its
- * transports move bytes through, the project's files as Blender reads them, and the two ways
- * bytes it produced reach the project (a shipped output, the session's `.blend`). They were
- * the kit's own routes; the kit now names no Blender, and reaches these only because the
- * product that composes this package declares its serving module. Writes go through the kit's
- * services (`@volter/sdk/session/project-serving`), so they are attributed and recorded
- * like every other project write.
- */
+/** The Blender serving half supplies engine artifacts, spool transport, project-file reads, output writes and document saves. SDK serving services attribute and commit project writes. */
 
 import { createHash } from 'node:crypto';
 import { createReadStream } from 'node:fs';
@@ -17,7 +8,7 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { createBrotliDecompress } from 'node:zlib';
 import { projectOutputRootOf } from '@volter/sdk/project/output-roots';
-import { isContainedRelativePath } from '@volter/sdk/session/relative-path-guard';
+import { isContainedRelativePath } from '@volter/sdk/relative-path-guard';
 import type { ProjectServingServices } from '@volter/sdk/session/project-serving';
 import type { Plugin } from 'vite';
 import {
@@ -59,10 +50,8 @@ async function readBody(req: IncomingMessage): Promise<Buffer> {
 export function blenderRoutesPlugin(services: ProjectServingServices): Plugin {
   // ---- File bodies, which are NOT commands.
   //
-  // A FILE IS A BODY, NOT A JSON FIELD. `blender-read-file` used to answer with the whole file
-  // base64'd inside a control-plane message, so a mesh the twin had written came back as a
-  // single JSON frame on the command socket (measured 2026-09-15: a 31 MB file became ~41.5 MB
-  // of base64 in one message and killed the socket). So bytes move as bytes: the page POSTs an
+  // A FILE IS A BODY, NOT A JSON FIELD: a whole file base64'd inside one control-plane message
+  // can kill the command socket. So bytes move as bytes: the page POSTs an
   // octet-stream; the requester GETs it once and it is gone. The spool keeps PATH AUTHORITY
   // WITH THE REQUESTER: the page never names a destination on disk, only an id the caller
   // minted.
@@ -105,9 +94,7 @@ export function blenderRoutesPlugin(services: ProjectServingServices): Plugin {
         json(res, await blenderWasmStatus());
       },
     },
-    // The substrate skew's own doors beside the standalone bundle's: Blender's runtime tree as
-    // one index and one blob (a request per file would be ~2,300 round trips), and the
-    // substrate's browser ESM with its bare specifiers rewritten.
+    // Serve the substrate runtime tree as one index and blob, plus browser ESM with rewritten bare specifiers.
     {
       method: 'GET',
       match: /^\/__editor\/blender-wasm\/runtime\.idx$/,
@@ -212,11 +199,7 @@ export function blenderRoutesPlugin(services: ProjectServingServices): Plugin {
         }
         // The substrate skew's module is served as brotli too, made once (`brotliArtifact`).
         const found = file === BLENDER_WALI_ARTIFACT ? await brotliArtifact(onDisk) : onDisk;
-        // A VALIDATOR, SO THE COMPILED ENGINE IS CACHED. Chrome keeps the machine code it
-        // compiled from an `instantiateStreaming` response only while that response sits in its
-        // HTTP cache, and a response with no validator is never stored (measured: every boot
-        // compiled all 86 MB again, 12-36 s at load ~35). `no-cache` still asks every time, and
-        // this answers 304 while the file on disk is the same one.
+        // Supply a validator so Chrome can cache the compiled engine. no-cache revalidates each boot; return 304 while the artifact identity matches.
         const info = await stat(found.path);
         // A pre-compressed file goes out as stored, declared as brotli, to a client that accepts
         // brotli; one that does not (a service worker in the tab asks with no Accept-Encoding)
@@ -318,10 +301,7 @@ export function blenderRoutesPlugin(services: ProjectServingServices): Plugin {
           json(res, { error: 'That path leaves the project root.' }, 403);
           return;
         }
-        // STREAMED, never read whole: on a tab-served project this server runs in the page, and a
-        // 307 MB document read into one buffer and ended as one body was copied along the page's
-        // own response path. MEASURED 2026-09-29 on the hosted Stoneguard open: the page's
-        // isolate held 1,009 MB of ArrayBuffers while the document crossed, against 19 MB before.
+        // Stream document bytes; the tab-hosted response path must not buffer the entire model.
         let size: number;
         try {
           const info = await stat(absolute);
@@ -430,20 +410,7 @@ export function blenderRoutesPlugin(services: ProjectServingServices): Plugin {
         }
       },
     },
-    // ---- The session's DOCUMENT, written back OUT into the project. A Blender session holds one
-    // `.blend`; its `save_as_mainfile` writes it into the engine's filesystem, and this is how
-    // those bytes reach the disk the project lives on. Unlike the spool, the destination shape is
-    // pinned BY THIS SERVER, and the write is the project's one attributed, conflict-checked
-    // transaction: a `.blend` is the project's file like any other.
-    //
-    // IT ARRIVES AS A DELTA. The page cuts each save into content-defined chunks
-    // (`blender-engine/browser/document-chunks.mts`) and posts their manifest; this answers with
-    // the chunks it does not already hold, the page posts those, and the manifest again commits.
-    // MEASURED 2026-09-29, native Blender 5.2 on the Stoneguard bridge: a 497 MB save, one object
-    // moved, changed 1 of 475 one-MiB chunks, so an edit carries about a megabyte instead of the
-    // whole file. Chunks this server reuses come from the document as it lies on disk, and each
-    // is hashed again against the manifest before the commit: a file changed underneath (another
-    // writer, a restore) is not drift but a missing chunk, re-sent.
+    // Save the session .blend through the attributed, conflict-checked project transaction. A chunk manifest requests only missing bytes. Rehash reused disk chunks at commit so an external file change requests replacement chunks.
     {
       method: 'POST',
       match: /^\/__editor\/blender-document-chunk$/,
@@ -491,8 +458,7 @@ export function blenderRoutesPlugin(services: ProjectServingServices): Plugin {
           json(res, { error: 'No project open, so there is nowhere to save the document.' }, 404);
           return;
         }
-        // The editor server's `express.json` has already read a JSON body when it runs first
-        // (MEASURED: the stream arrived empty); read the stream only when it has not.
+        // Use the parsed JSON body when express.json has consumed the stream; otherwise read it here.
         const parsed = (req as IncomingMessage & { body?: unknown }).body;
         let manifest: unknown = parsed !== null && typeof parsed === 'object' && !Buffer.isBuffer(parsed) ? parsed : null;
         if (manifest === null) {

package/serving/blender-wasm-artifact.ts

@@ -1,57 +1,4 @@
-/**
- * The headless Blender build, served to the editor tab — and the door that
- * says WHICH BUILD it is.
- *
- * THE BLENDER IN THE TAB IS BLENDER (ARCHITECTURE-CORE, owner ruling
- * 2026-09-17), and since the 2026-09-18 amendment there are two builds of it:
- *
- *   emscripten — the STANDALONE skew, and the one `@volter/blender-engine` SHIPS under
- *     `wasm/`: the glue as text plus the two large files pre-compressed
- *     (`blender_browser.wasm.br`, `blender_browser.data.br`, ~38 MB together
- *     against ~156 MB raw). They are served as-is with `Content-Encoding: br`;
- *     the browser decompresses before the runtime sees a byte, so the glue's
- *     own `instantiateStreaming` and `.data` preload run unchanged.
- *
- *   wali — the SUBSTRATE skew: one `blender.wasm` linked for
- *     `wasm32-wali-linux-musl` beside the `runtime/` tree it reads through
- *     `BLENDER_SYSTEM_*` (browser-substrate `programs/blender/5.2.0`, whose
- *     `gate.sh` stages exactly that pair).
- *
- * THE SKEW IS NOT CONFIGURED, IT IS READ. One editor serves one Blender, and
- * the served directory holds either `blender_browser.js` or `blender.wasm`;
- * that IS the answer, and `status` carries it. There is no manifest field, no
- * setting and no flag, because nothing a user does may depend on the skew —
- * the ruling's "a skew may refuse a capability by name, never answer the same
- * question differently" leaves nothing for a chooser to choose.
- * `VOLTER_BLENDER_WASM_DIR` is the existing door for pointing the editor at a
- * different build, and pointing it at a WALI pack is how the substrate skew is
- * reached in development.
- *
- * ONE PATCH IS APPLIED TO THE EMSCRIPTEN GLUE, and it is applied HERE rather
- * than in the worker so that the pthread workers — which the runtime spawns by
- * loading this same URL as a classic worker (`Module.mainScriptUrlOrBlob`) —
- * get the identical text. The build is `-sPROXY_TO_PTHREAD`, and its
- * `pthread_create` glue transfers a `#canvas` to the spawned thread by default.
- * There is no canvas in a worker, and the transfer aborts the spawn, so the
- * transfer list is emptied. The upstream release already does exactly this for
- * node (`if(ENVIRONMENT_IS_NODE){transferredCanvasNames=0}`); a worker needs
- * the same, and for the same reason.
- *
- * THE SAME PATCHING IS WHAT CARRIES THE SUBSTRATE, and it is the precedent
- * being transcribed rather than a new mechanism: `@volter/browser-wali` and
- * `@volter/browser-runtime` are served out of this door too
- * (`/__editor/blender-wasm/wali/<package>/<file>.js`), with their bare
- * `@volter/...` specifiers rewritten to those URLs on the way out. That is
- * what keeps `@volter/blender-engine` free of any dependency on browser-substrate: the
- * standalone skew installs nothing, bundles nothing and fetches nothing, and
- * the WALI engine imports the substrate from URLs instead of specifiers. The
- * nested workers `BrowserWaliWorkerProgram` spawns load from these same URLs,
- * so they get the identical rewritten text — exactly the reason the glue patch
- * lives here.
- *
- * A missing directory is a LOUD 404 naming the variable, never a silent
- * fall-through: the engine either is Blender or says why it is not.
- */
+
 import { createHash } from 'node:crypto';
 import { createReadStream, existsSync } from 'node:fs';
 import { mkdir, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises';
@@ -60,7 +7,7 @@ import { dirname, isAbsolute, join, posix, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { brotliCompress, brotliDecompressSync, constants as zlibConstants } from 'node:zlib';
 
-export type BlenderSkew = 'emscripten' | 'wali';
+type BlenderSkew = 'emscripten' | 'wali';
 
 /** Engine artifacts plus the separately packaged Essentials asset payload. */
 export const BLENDER_WASM_FILES = [
@@ -71,76 +18,33 @@ export const BLENDER_WASM_FILES = [
   'essentials.bin',
 ] as const;
 
-export type BlenderWasmFile = (typeof BLENDER_WASM_FILES)[number];
-
 /** What the WALI skew's directory must hold: the artifact, and the runtime
  *  tree Blender reads through `BLENDER_SYSTEM_*`. */
 export const BLENDER_WALI_ARTIFACT = 'blender.wasm';
-export const BLENDER_WALI_RUNTIME = 'runtime';
+const BLENDER_WALI_RUNTIME = 'runtime';
 
-/**
- * THE THREAD BUDGET, stated once, here, because it is a property of this RUN
- * SURFACE and not of the program.
- *
- * Blender is SERIAL unless it is told `-t N` and says so on stderr
- * (browser-substrate `programs/blender/5.2.0/README.md` §(a): `-t N` sets
- * oneTBB's global control and blenlib's explicitly sized arena). The POOL is a
- * different number and must be comfortably above it: measured 2026-09-18 in
- * the pack's own emulator, `blender -t 4` TRAPS with a host pool of 4, because
- * the stated count buys four oneTBB workers and Blender starts threads of its
- * own besides. 4 in a pool of 16 is the pair this lane measured end to end
- * (`blender-n-gate`, 2026-09-19: boot 12.0 s, first request 0.9 s, later calls
- * ~1.5 s), and a pool of 8 under `-t 4` trapped during boot on this box.
- */
-/**
- * FOUR, MEASURED, NOT THE MACHINE'S CORES. The Emscripten skew runs Blender at 6
- * on this 12-core box; measured 2026-09-20 on the same operations, WALI at 12
- * threads was SLOWER than at 4 everywhere (subsurf level 6: 40 ms against 17;
- * an ico sphere: 30 against 15; the courtyard 31.1 s against 28.6) -- the
- * pool's scheduling costs more than the cores return, so more `-t` is not more
- * speed here. The pool stays four times the count, the ratio that measured
- * clean (16 under 4; 8 under 4 trapped at boot), because Blender starts threads
- * of its own beyond the oneTBB workers `-t` buys.
- */
-/*
- * ONE, MEASURED 2026-09-27, as the standalone skew runs Blender. Through the
- * editor's own worker, on the same work as the standalone skew: at `-t 4` the
- * session held 870 MB after it against the standalone skew's 632, and a
- * boolean of two 8k-polygon spheres took 2.2 s; at `-t 1`, 629 MB and 1.3 s
- * (the standalone skew 3.7 s). On this runtime more `-t` has cost more than
- * it returned, as the courtyard's 12 against 4 already showed above. The
- * pool stays 16: its workers start on a thread's first use, and Blender's
- * libraries start threads of their own.
- */
-export const BLENDER_WALI_WORKERS = { pool: 16, blender: 1 } as const;
+/** The run surface owns the thread budget: Blender’s explicit worker count and the host pool are separate. The pool also serves threads started by Blender libraries. */
+
+/* Use one Blender worker with a 16-worker host pool; pool threads start lazily on first use. */
+const BLENDER_WALI_WORKERS = { pool: 16, blender: 1 } as const;
 
 /** The substrate packages the WALI engine imports, by the URL segment each is
  *  served under and the specifier prefix rewritten to it. */
-export const BLENDER_WALI_SUBSTRATE = [
+const BLENDER_WALI_SUBSTRATE = [
   { segment: 'browser-wali', specifier: '@volter/browser-wali' },
   { segment: 'browser-runtime', specifier: '@volter/browser-runtime' },
 ] as const;
 
-export const BLENDER_WASM_DIR_VARIABLE = 'VOLTER_BLENDER_WASM_DIR';
+const BLENDER_WASM_DIR_VARIABLE = 'VOLTER_BLENDER_WASM_DIR';
 
-/**
- * The bundle `@volter/blender-engine` ships — Blender itself, so its own GPL
- * package (ARCHITECTURE-CORE §Licensing, "Blender's licence stops at the
- * wire"). This resolution is a PATH, not an import: the editor serves those
- * bytes and never imports the engine. `import.meta.url` is THIS FILE's esbuild bundle
- * (`<pkg>/dist-node/serving.mjs`, the `volter.serving` module); from it, two
- * directories up and across is the sibling package -- `packages/blender-engine/wasm`
- * in a checkout, `node_modules/@volter/blender-engine/wasm` installed. Existence is
- * checked once so a realm that lacks it gets a named absence, not a path.
- */
-export const SHIPPED_BLENDER_WASM_DIR: string | null = (() => {
+const SHIPPED_BLENDER_WASM_DIR: string | null = (() => {
   const candidate = fileURLToPath(new URL('../../blender-engine/wasm/', import.meta.url));
   return existsSync(candidate) ? candidate.replace(/\/$/, '') : null;
 })();
 
 /** Where the build is: the named directory, else the shipped one, else null. */
-export function blenderWasmDir(env: NodeJS.ProcessEnv = process.env): string | null {
-  const named = env[BLENDER_WASM_DIR_VARIABLE];
+function blenderWasmDir(): string | null {
+  const named = process.env[BLENDER_WASM_DIR_VARIABLE];
   if (typeof named === 'string' && named.trim() !== '') {
     const dir = named.trim();
     return isAbsolute(dir) ? dir : null;
@@ -178,7 +82,7 @@ export interface BlenderWasmStatus {
   available: boolean;
   /** Which build the served directory holds; null when nothing is served. */
   skew: BlenderSkew | null;
-  /** The directory that was looked in, or null when the variable is unset. */
+  /** The explicit or shipped artifact directory, or null when neither resolves. */
   dir: string | null;
   /** On-disk byte sizes of the files, for the ones that are there
    *  (the `.br` size when a file is stored pre-compressed). */
@@ -210,10 +114,8 @@ async function skewOf(dir: string): Promise<BlenderSkew | null> {
   return null;
 }
 
-export async function blenderWasmStatus(
-  env: NodeJS.ProcessEnv = process.env,
-): Promise<BlenderWasmStatus> {
-  const dir = blenderWasmDir(env);
+export async function blenderWasmStatus(): Promise<BlenderWasmStatus> {
+  const dir = blenderWasmDir();
   if (dir === null)
     return {
       available: false,
@@ -240,7 +142,7 @@ export async function blenderWasmStatus(
           `${BLENDER_WALI_ARTIFACT} (the substrate skew)`,
       ],
     };
-  return skew === 'wali' ? waliStatus(dir) : emscriptenStatus(dir, env);
+  return skew === 'wali' ? waliStatus(dir) : emscriptenStatus(dir);
 }
 
 /**
@@ -249,13 +151,13 @@ export async function blenderWasmStatus(
  * `edit` as that process, and `edit` hands its environment to the session it spawns
  * (`launcher/launch.ts`). A session started on this machine has no such variable.
  */
-export const BROWSER_SUBSTRATE_VARIABLE = 'BROWSER_SUBSTRATE_URL';
+const BROWSER_SUBSTRATE_VARIABLE = 'BROWSER_SUBSTRATE_URL';
 
-export function servedFromTab(env: NodeJS.ProcessEnv = process.env): boolean {
-  return (env[BROWSER_SUBSTRATE_VARIABLE] ?? '').trim() !== '';
+function servedFromTab(): boolean {
+  return (process.env[BROWSER_SUBSTRATE_VARIABLE] ?? '').trim() !== '';
 }
 
-async function emscriptenStatus(dir: string, env: NodeJS.ProcessEnv): Promise<BlenderWasmStatus> {
+async function emscriptenStatus(dir: string): Promise<BlenderWasmStatus> {
   const sizes: Record<string, number> = {};
   const encoded: Record<string, 'br'> = {};
   const missing: string[] = [];
@@ -268,7 +170,7 @@ async function emscriptenStatus(dir: string, env: NodeJS.ProcessEnv): Promise<Bl
     sizes[file] = found.size;
     if (found.encoding) encoded[file] = found.encoding;
   }
-  return { available: missing.length === 0, skew: 'emscripten', dir, sizes, encoded, missing, digests: await emscriptenDigests(dir), inTab: servedFromTab(env) };
+  return { available: missing.length === 0, skew: 'emscripten', dir, sizes, encoded, missing, digests: await emscriptenDigests(dir), inTab: servedFromTab() };
 }
 
 /** The decoded bytes' digests the build records, for the files it records them for. */
@@ -329,16 +231,13 @@ async function waliStatus(dir: string): Promise<BlenderWasmStatus> {
   };
 }
 
-/**
- * The glue, patched. Read once and held: it is 700 KB of text and every
- * pthread the runtime spawns asks for it again.
- */
+/** Cache the patched glue for reuse by each runtime pthread. */
 let patchedGlue: { dir: string; text: string } | null = null;
 
 const CANVAS_TRANSFER =
   'var transferredCanvasNames=attr?(growMemViews(),HEAPU32)[attr+40>>2]:0;if(';
 
-export function patchBlenderGlue(source: string): string {
+function patchBlenderGlue(source: string): string {
   // A headless build spawns no window and its glue carries no canvas transfer:
   // then there is nothing to patch and the glue is served as-is. Only a build
   // that DOES transfer a `#canvas` (the port's UI-derived release) needs the
@@ -375,26 +274,15 @@ export interface RuntimeIndex {
    *  still a new file, and everything that names the tree by its index (the tab's OPFS store,
    *  `runtimeTag`, the compressed blob's cache) must see it. */
   files: { path: string; size: number; mode: number; sha256: string }[];
-  newestMtimeMs?: number;
 }
 
 let cachedRuntimeIndex: { dir: string; index: RuntimeIndex } | null = null;
 
-/**
- * Blender's runtime tree, as ONE index plus ONE blob.
- *
- * ~2,300 files and 78 MB, every one of which has to exist before Blender's
- * first act. The tab fetches this index and then `runtime.bin`, whose bytes
- * are the same files concatenated IN THIS ORDER, and slices
- * (`blender-wali-engine.mts`'s `stageRuntime`). A request per file would be
- * 2,300 round trips; a tar would be a dependency and a decoder. The order is
- * the index's and nothing else may assume it.
- */
+/** Publish the runtime tree as one index and one concatenated blob. The index defines file order; stageRuntime slices each file from runtime.bin. */
 export async function runtimeIndex(dir: string): Promise<RuntimeIndex> {
   if (cachedRuntimeIndex?.dir === dir) return cachedRuntimeIndex.index;
   const root = join(dir, BLENDER_WALI_RUNTIME);
   const files: RuntimeIndex['files'] = [];
-  let newest = 0;
   const walk = async (where: string): Promise<void> => {
     for (const entry of (await readdir(where, { withFileTypes: true })).sort((left, right) =>
       left.name < right.name ? -1 : left.name > right.name ? 1 : 0,
@@ -412,22 +300,16 @@ export async function runtimeIndex(dir: string): Promise<RuntimeIndex> {
         mode: info.mode & 0o7777,
         sha256: createHash('sha256').update(await readFile(path)).digest('hex'),
       });
-      newest = Math.max(newest, info.mtimeMs);
     }
   };
   await walk(root);
   if (files.length === 0) throw new Error(`${root} is empty`);
-  const index = { files, newestMtimeMs: newest };
+  const index = { files };
   cachedRuntimeIndex = { dir, index };
   return index;
 }
 
-/**
- * THE RUNTIME BLOB'S VALIDATOR, so a warm boot takes it from the HTTP cache.
- * Without one it was read from 1,317 files and sent again on every boot: the
- * standalone skew's `.data` payload is one cached file, and this was most of
- * what the substrate skew's boot spent before Blender ran (2026-09-27).
- */
+/** The runtime blob’s validator permits warm boots to reuse the HTTP cache. */
 export function runtimeTag(index: RuntimeIndex): string {
   const contents = createHash('sha256');
   for (const file of index.files) contents.update(`${file.path}\0${file.mode}\0${file.sha256}\n`);
@@ -440,19 +322,8 @@ export async function writeRuntimeBlob(dir: string, write: (chunk: Buffer) => vo
   for (const file of (await runtimeIndex(dir)).files) write(await readFile(join(root, file.path)));
 }
 
-/**
- * Where a substrate package's browser ESM is, or null when it is not
- * installed. Resolved through Node's own resolution from THIS file, so it
- * finds whatever the project that opted into this skew declared.
- *
- * `import.meta.resolve` and not `createRequire().resolve`: these packages
- * export `"."` and `"./*.js"` under the `import` condition ONLY, so a CJS
- * resolve raises ERR_PACKAGE_PATH_NOT_EXPORTED on a package that is plainly
- * installed. The package's OWN ENTRY is resolved rather than its
- * `package.json`, which is not exported at all; the entry's directory IS the
- * published `dist`, which is where every served module comes from.
- */
-export function substrateDir(specifier: string): string | null {
+/** Resolve substrate browser ESM through import.meta.resolve from this file. These packages export their entry and .js modules under the import condition; the entry’s directory is their published dist. Return null when the package is not installed. */
+function substrateDir(specifier: string): string | null {
   try {
     return dirname(fileURLToPath(import.meta.resolve(specifier)));
   } catch {
@@ -496,15 +367,7 @@ export async function substrateModule(
 
 const compressing = new Map<string, Promise<void>>();
 
-/**
- * A file as brotli, kept under the system's temporary directory by `key`
- * once made: its path, or null while it is being made (the first caller
- * starts it and is answered uncompressed). The substrate skew's artifacts are
- * past what Chrome keeps in its HTTP cache uncompressed -- `blender.wasm`
- * 93 MB, the runtime blob 66 -- so every boot fetched them again and compiled
- * the module again; the standalone skew's go out as brotli (18 MB and 7.7 MB)
- * and are kept (2026-09-27: brotli, 20 MB and 25 MB).
- */
+/** Cache each Brotli artifact by content key under the system temporary directory. While compression runs, serve the original file; return the compressed path once ready. */
 async function brotliCopy(key: string, produce: () => Promise<Buffer>): Promise<string | null> {
   const path = join(tmpdir(), 'volter-blender-brotli', `${key.replace(/[^\w.-]/g, '')}.br`);
   try {

package/serving/index.ts

@@ -1,5 +1,5 @@
 /**
- * `@volter/editor-blender`'s server half (`package.json#volter.serving`, the project-serving door in
+ * `@volter/editor-blender`'s server half (`package.json#contributes.volter.serving`, the project-serving door in
  * `@volter/sdk/session/project-serving`): the routes the Blender in the tab reads and
  * writes through.
  */

package/src/api.ts

@@ -0,0 +1,9 @@
+/**
+ * EDITOR-BLENDER'S API, AS TYPES: what its page half's `activate` returns
+ * (`../contributions/blender.page.ts`), the model Play seam's types and a landed save's. A package that reads the
+ * API imports these type-only; the values come from `getExtension(...).exports`.
+ */
+export type BlenderPageApi = ReturnType<typeof import('../contributions/blender.page').activate>;
+export type * from './model-play-extension';
+export type { ModelPlayMode } from './play-mode';
+export type { ModelDocumentSaved } from '../host/blender-runtime-host';

package/src/layouts.tsx

@@ -1,20 +1,4 @@
-/**
- * The BLENDER layout — the composition a models project's adapter declares
- * (`editor/volter.adapter.ts`: `editor: { Layout: ModelLayout }`, the door
- * `@volter/sdk/layouts` documents). `ModelArrangement` names the Model
- * workspace and the chrome regions it shows; Sculpt and Texture open on it too
- * — their reserved panels (the brush rail, the layer stack) ship WITH their
- * programs, never as empty chrome, and until then nothing about a sculpt
- * arrangement differs from a modeling one.
- *
- * WHERE THE PANELS SIT IS THE WORKBENCH'S. A workspace declares what it SHOWS
- * (`regions`) and which documents stand beside the centre one (`areas`); the
- * sizes, the splits and the tab order are the frame's editor-group state,
- * which VS Code persists itself. A captured grid used to ship here beside the
- * contribution, measured off Blender 5.2's own MODELING workspace; the
- * measurement that outlived it is `contributions/model.layout.ts`'s Timeline
- * RATIO, which is a proportion rather than a geometry and is stated there.
- */
+/** ModelArrangement supplies Blender's chrome regions. ModelLayout composes them with the SDK frame; the workbench persists pane sizes, splits and tab order. */
 import {
   EditorFooter,
   EditorFrame,

package/src/looks.ts

@@ -1,14 +1,3 @@
-/**
- * The Blender skew's LOOK and BINDINGS as importable values — `@volter/editor-blender/looks`,
- * the public surface a project's `editor/volter.adapter.ts` declares them from
- * (ARCHITECTURE-CORE §Adapters and contributions are code, not configs):
- *
- *     editor: { Layout: ModelLayout, style: blenderStyle, keymap: blenderKeymap }
- *
- * The same two objects the package's `workspace.style` / `workspace.keymap`
- * contributions register (`package.json#volter.contributions`). Registration
- * publishes them to every project that declares this package; the adapter's
- * declaration is what CHOOSES them for one.
- */
+
 export { keymap as blenderKeymap } from '../contributions/blender.keymap';
 export { style as blenderStyle } from '../contributions/blender.style';

package/src/model-document-saving.ts

@@ -0,0 +1,25 @@
+/** The engine's current save refusal, scoped to the document it protects. */
+const notices = new Map<string, string>();
+const listeners = new Set<() => void>();
+
+export function setModelDocumentSaveNotice(document: string, note: string | null): void {
+  if ((notices.get(document) ?? null) === note) return;
+  if (note === null) notices.delete(document);
+  else notices.set(document, note);
+  for (const listener of [...listeners]) listener();
+}
+
+export function modelDocumentSaveNotice(document: string | undefined): string | null {
+  return document === undefined ? null : notices.get(document) ?? null;
+}
+
+export function subscribeModelDocumentSaving(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+export function clearModelDocumentSaving(): void {
+  if (!notices.size) return;
+  notices.clear();
+  for (const listener of [...listeners]) listener();
+}