@volter/blender-engine 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# Blender engine
+
+Read this when building or changing the Blender worker or its Three.js frame
+presenter. This package contains Blender itself, compiled to WebAssembly, its
+worker, Python session, message protocol and tab-side handle. It is independent
+of the editor host and game runtime.
+
+The package is GPL-3.0-or-later. Preserve [LICENSE](LICENSE), including all
+upstream notices. No repository-wide license overrides this package's license.
+
+## Build and check
+
+From the repository root, install the locked dependencies and run:
+
+```sh
+npm ci
+npm run typecheck
+npm run build:blender-three
+```
+
+Run these commands through the active World when working in the Volter
+development environment. The browser typecheck has no monorepo aliases and no
+Node ambient types. The presenter build emits its standalone module and sky
+worker under this package's `dist/release/` directory.
+
+The checked-in WASM files are prebuilt. Their exact upstream source, recipe and
+artifact hashes are in [wasm/BUNDLE.json](wasm/BUNDLE.json). Building the presenter
+does not rebuild or verify Blender itself. The corresponding Blender source
+remains in the separate `volter-ai/blender` fork.
+
+## Distribution
+
+The corresponding source is public at `volter-ai/blender`, and
+`wasm/BUNDLE.json` pins its snapshot, release and artifact hashes. Publication
+still requires the repository release checks; a successful local build alone is
+not sufficient.
+
+[The import record](../../provenance/blender-engine.json) identifies the original
+source revision and hashes. Runtime, protocol and artifact bytes are preserved;
+legacy internal wire markers and Blender build identifiers are intentionally not
+renamed independently of their producers and consumers. Package identity and
+build configuration use the public repository.
+
+Benchmark/oracle tools remain at the pinned source revision until their inputs
+and execution dependencies are migrated. Their old results are not verification
+of a new editor release. The original editor still uses its existing package;
+consumer cutover is tracked in the repository's `WORK.md`; do not create a
+second independently edited implementation.

package/browser/blender-emscripten-engine.mts

@@ -0,0 +1,289 @@
+/**
+ * The STANDALONE skew: Blender in this worker's own WebAssembly module.
+ *
+ * `blender-engine.mts` is the seam and says how the skew is chosen; this is
+ * one of its two implementations, and the one `@volter/editor-blender` ships. It has no
+ * in-house dependency of any kind and reaches nothing but the editor's own
+ * routes.
+ *
+ * THREE THINGS THE BUILD REQUIRES, each measured rather than assumed:
+ *
+ * 1. CROSS-ORIGIN ISOLATION. The build is `-sPROXY_TO_PTHREAD` with pthreads,
+ *    so it needs `SharedArrayBuffer`. The editor's dev server already sets
+ *    `Cross-Origin-Opener-Policy: same-origin` and
+ *    `Cross-Origin-Embedder-Policy: credentialless` ahead of every route
+ *    (`packages/editor/server/dev.ts`) — `credentialless` rather than
+ *    `require-corp` precisely so cross-origin images and iframes keep loading.
+ *    A worker without `crossOriginIsolated` is refused BY NAME here rather
+ *    than left to fail inside the runtime.
+ *
+ * 2. THE GLUE IS PATCHED SERVER-SIDE, not here, because the runtime spawns its
+ *    pthreads by loading that same URL as a classic worker
+ *    (`Module.mainScriptUrlOrBlob`). See `blender-wasm-artifact.ts`.
+ *
+ * 3. FILES ARE STAGED WITH `FS_createDataFile`, before the runtime starts.
+ *    This is a WasmFS build: `Module.FS` exists and works from this thread,
+ *    but its preload directories come out non-writable, which is why
+ *    `session.py` chmods its own root as its first act.
+ */
+
+import {
+  artifactUrl,
+  type BlenderArtifactStatus,
+  type BlenderEngine,
+  type BlenderEngineOptions,
+  type BlenderFiles,
+  openSessionChannel,
+  PAGE_OWNED_DIRECTORIES,
+  SESSION_ROOT,
+  SESSION_SCRIPT,
+  sleep,
+} from './blender-engine.mts';
+import sessionPython from './session.py?raw';
+
+/** What the module factory is, in the only shape this file uses. */
+interface BlenderModule {
+  FS: {
+    readFile(path: string): Uint8Array;
+    writeFile(path: string, data: string | Uint8Array): void;
+    mkdirTree(path: string): void;
+    readdir(path: string): string[];
+    unlink(path: string): void;
+    stat(path: string): { size: number; mode?: number; mtime?: Date | number };
+    chmod(path: string, mode: number): void;
+  };
+  ENV: Record<string, string>;
+  /** The export door's arena, read by `readArena`. */
+  HEAPU8: Uint8Array;
+  /**
+   * Hand back the packed `.data` payload, once. Linked in by the bundle's
+   * `--post-js` (the spike's `recipe/release-preloaded-file-data.js`, whose
+   * header carries the measurement); absent means the module predates it,
+   * which is why the call below is guarded and says so.
+   */
+  releasePreloadedFileData?(): { files: number; bytes: number };
+  _blender_web_export_buffer(): number;
+  _blender_web_export_buffer_size(): number;
+  FS_createPath(parent: string, name: string, canRead: boolean, canWrite: boolean): void;
+  FS_createDataFile(
+    parent: string,
+    name: string,
+    data: Uint8Array,
+    canRead: boolean,
+    canWrite: boolean,
+    canOwn: boolean,
+  ): void;
+}
+
+type BlenderModuleFactory = (options: Record<string, unknown>) => Promise<BlenderModule>;
+
+/** The glue, evaluated in this worker. It is a UMD bundle, so it is given the
+ *  `module`/`exports` pair it looks for and hands back the factory. */
+async function loadFactory(glueUrl: string): Promise<BlenderModuleFactory> {
+  const source = await fetch(glueUrl);
+  if (!source.ok) throw new Error(`${glueUrl}: HTTP ${source.status}`);
+  const text = await source.text();
+  const container = { exports: {} as { default?: BlenderModuleFactory } };
+  const evaluate = new Function(
+    'module',
+    'exports',
+    'define',
+    `${text}\nreturn typeof createBlenderModule === 'function' ? createBlenderModule : module.exports;`,
+  ) as (module: unknown, exports: unknown, define: unknown) => BlenderModuleFactory;
+  const factory = evaluate(container, container.exports, undefined);
+  if (typeof factory !== 'function')
+    throw new Error('blender_browser.js did not produce a module factory');
+  return factory;
+}
+
+const utf8 = new TextEncoder();
+
+function mkdirp(module: BlenderModule, directory: string): void {
+  let current = '';
+  for (const part of directory.split('/').filter(Boolean)) {
+    module.FS_createPath(current || '/', part, true, true);
+    current += `/${part}`;
+  }
+}
+
+/** `Module.FS`, as {@link BlenderFiles}. Every call is synchronous underneath;
+ *  the promises are the seam's, for the skew that cannot be synchronous. */
+function moduleFiles(module: BlenderModule): BlenderFiles {
+  const FS = module.FS;
+  return {
+    readFile: async (path) => FS.readFile(path),
+    writeFile: async (path, data) => FS.writeFile(path, data),
+    mkdirTree: async (path) => FS.mkdirTree(path),
+    readdir: async (path) => FS.readdir(path),
+    stat: async (path) => {
+      let info: { size: number; mode?: number; mtime?: Date | number };
+      try {
+        info = FS.stat(path);
+      } catch {
+        return null;
+      }
+      const mtime = info.mtime;
+      return {
+        size: info.size,
+        mode: info.mode ?? 0,
+        mtimeMs: typeof mtime === 'number' ? mtime : (mtime?.getTime() ?? 0),
+      };
+    },
+    unlink: async (path) => FS.unlink(path),
+  };
+}
+
+export async function startEmscriptenBlenderEngine(
+  options: BlenderEngineOptions,
+  _status: BlenderArtifactStatus,
+): Promise<BlenderEngine> {
+  if (!self.crossOriginIsolated)
+    throw new Error(
+      'Headless Blender needs SharedArrayBuffer, so the editor page has to be cross-origin ' +
+        'isolated (Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy on ' +
+        'every response). This worker reports crossOriginIsolated=false.',
+    );
+  const glueUrl = artifactUrl('blender_browser.js');
+  const factory = await loadFactory(glueUrl);
+  const started = performance.now();
+  let readyLine: string | null = null;
+  // BLENDER'S OWN STREAMS ARE PAGE OUTPUT, NOT EDITOR-CONSOLE CONDITIONS.
+  // Measured on the first live run: routing `printErr` at `error` put every
+  // ordinary startup line -- the WebGPU preinit notice, a Python
+  // DeprecationWarning, the ready banner itself -- into the session's
+  // unresolved console set, which is the set an agent must drive to zero. The
+  // editor's console door is for conditions somebody must resolve, so only the
+  // session's OWN named conditions go there.
+  const say = (_level: 'log' | 'error', text: string) => {
+    if (text.startsWith('@@VGAI-READY ')) readyLine = text.slice('@@VGAI-READY '.length);
+    options.log(
+      text.startsWith('@@VGAI-WARN') || text.startsWith('@@VGAI-ERROR') ? 'error' : 'log',
+      text,
+    );
+  };
+  const module = await factory({
+    arguments: ['--background', '--factory-startup', '--python', SESSION_SCRIPT],
+    locateFile: (file: string) => artifactUrl(file),
+    // The pthreads load the SAME patched glue this worker just evaluated.
+    mainScriptUrlOrBlob: glueUrl,
+    print: (text: string) => say('log', text),
+    printErr: (text: string) => say('error', text),
+    preRun: [
+      (mod: BlenderModule) => {
+        mod.ENV ??= {};
+        Object.assign(mod.ENV, {
+          BLENDER_SYSTEM_RESOURCES: '/bw',
+          BLENDER_SYSTEM_PYTHON: '/bw/python',
+          BLENDER_SYSTEM_SCRIPTS: '/bw/scripts',
+          BLENDER_SYSTEM_DATAFILES: '/bw/datafiles',
+          VGAI_SESSION_ROOT: SESSION_ROOT,
+          HOME: '/root',
+          TMPDIR: '/tmp',
+        });
+        // VGAI_EXPORT_BUFFER_PATH IS DELIBERATELY UNSET. This engine reads the
+        // arena off `HEAPU8`; asking the door to also write it to a file would
+        // cost this skew a megabyte-scale write per present for bytes it
+        // already has (`session.py`, EXPORT_BUFFER_PATH).
+        // `in` and `reply` are this page's under the channel's ownership rule
+        // (`blender-engine.mts`); `session.py` makes `out` and `ask`, which
+        // are its own.
+        for (const directory of [
+          '/tmp',
+          '/root',
+          '/work',
+          SESSION_ROOT,
+          ...PAGE_OWNED_DIRECTORIES,
+          options.project,
+        ])
+          mkdirp(mod, directory);
+        mod.FS_createDataFile(
+          SESSION_ROOT,
+          'session.py',
+          utf8.encode(sessionPython),
+          true,
+          true,
+          true,
+        );
+      },
+    ],
+  });
+  // `main()` runs on a pthread (`-sPROXY_TO_PTHREAD`), so the factory resolves
+  // long before the session exists. The ready line is what says it does.
+  while (readyLine === null) await sleep(5);
+  const bootMs = performance.now() - started;
+  const banner = JSON.parse(readyLine) as { blender: string; engines: string[] };
+
+  // THE PAYLOAD EXISTS TWICE UNTIL THIS CALL. `--preload-file` reads the whole
+  // `.data` package into one ArrayBuffer, WasmFS copies every file out of it
+  // into the wasm heap during its own init, and then emscripten keeps the
+  // subarrays forever in `wasmFSPreloadedFiles` -- so a booted session holds
+  // ~55 MB of JS-side bytes that are already in linear memory and will never
+  // be read again. Measured 2026-09-18: Node's `arrayBuffers` sat at 55 MB
+  // from `factory resolved` through every later call, and two forced GCs did
+  // not move it. Here is the one moment it is safe to drop: WasmFS flushed
+  // long before the ready line, and anything staged after this takes
+  // `FS_createDataFile`'s post-flush branch, which never consults the array.
+  let releasedPayloadBytes: number | null = null;
+  if (typeof module.releasePreloadedFileData === 'function') {
+    const released = module.releasePreloadedFileData();
+    releasedPayloadBytes = released.bytes;
+    options.log(
+      'log',
+      `blender: released the preloaded ${(released.bytes / 1048576).toFixed(0)} MB ` +
+        `payload (${released.files} files); WasmFS already holds it`,
+    );
+  } else {
+    options.log(
+      'error',
+      'blender: this bundle has no releasePreloadedFileData, so the ~55 MB packed ' +
+        '.data payload stays resident beside the copy WasmFS made of it — relink with ' +
+        "the recipe's --post-js (recipe/release-preloaded-file-data.js).",
+    );
+  }
+
+  const FS = module.FS;
+
+  // A DIRECTORY MADE BY THE PRELOAD DOOR IS NOT WRITABLE. `FS_createPath`
+  // ignores its `canWrite` argument in this build, so the project root and
+  // everything above it come out read-only and the first `mkdirTree` under
+  // them raises `ErrnoError` -- measured on the first live round trip
+  // (2026-09-17: `stageProjectFiles` threw before any project file was
+  // staged). The session chmods its own root from Python for the same reason;
+  // this is the other half, for the paths Python never touches.
+  let climb = '';
+  for (const part of `${options.project}`.split('/').filter(Boolean)) {
+    climb += `/${part}`;
+    try {
+      FS.chmod(climb, 0o777);
+    } catch {
+      /* a path the module does not hold is not this loop's business */
+    }
+  }
+  for (const directory of ['/work', '/tmp', '/root', SESSION_ROOT, ...PAGE_OWNED_DIRECTORIES])
+    try {
+      FS.chmod(directory, 0o777);
+    } catch {
+      /* the session has already taken the ones it owns */
+    }
+
+  const files = moduleFiles(module);
+  const { request } = openSessionChannel(files, options);
+
+  return {
+    skew: 'emscripten',
+    banner,
+    files,
+    request,
+    // A VIEW, NOT A COPY. The arena is wasm linear memory and under
+    // `-sPROXY_TO_PTHREAD` that memory is SHARED, so `session-frame.mts`
+    // slices every column it reads out of here; this call itself is free.
+    readArena: async () =>
+      module.HEAPU8.subarray(
+        module._blender_web_export_buffer(),
+        module._blender_web_export_buffer() + module._blender_web_export_buffer_size(),
+      ),
+    bootMs,
+    memoryBytes: () => module.HEAPU8.length,
+    releasedPayloadBytes,
+  };
+}