@volter/blender-engine 0.1.0

package/browser/runtime.ts

@@ -0,0 +1,511 @@
+/**
+ * The tab-side handle on a Blender session: spawns the worker, forwards the
+ * four tool calls, and hands every presented frame to whoever displays it.
+ * One instance per editor tab; the session and its model die with the worker.
+ */
+import type {
+  CaptureRequest,
+  FileEntry,
+  RuntimeStart,
+  WorkerReply,
+  WorkerRequest,
+} from './protocol';
+import type {
+  BlenderActionClip,
+  BlenderNodeTree,
+  BlenderOutlinerTree,
+  BlenderOutlinerWrite,
+  BlenderRig,
+  BlenderRnaContext,
+  BlenderRnaView,
+  BlenderRnaWrite,
+  BlenderUvLayout,
+} from './rna';
+
+type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : never;
+type Request = DistributiveOmit<WorkerRequest, 'id'>;
+
+export interface BlenderRuntimeOptions {
+  /** Display a frame. A screenshot `capture` has its view REMEMBERED so the
+   *  next document capture photographs what the agent asked for; a render
+   *  capture (`capture.render`) is photographed here and now, and its answer
+   *  is what this returns to the operator waiting on it.
+   *
+   *  `description` is the same frame with its columns replaced by digests
+   *  (`protocol.ts`), for whoever displays it to keep as the record of what was
+   *  submitted. */
+  present(
+    frame: unknown,
+    description: unknown,
+    capture?: CaptureRequest,
+  ): Promise<PresentAnswer> | PresentAnswer;
+  log?(level: 'log' | 'error', text: string): void;
+}
+
+/**
+ * What the tab answers a present with.
+ *
+ * `held` is WHAT THE PRESENTER HELD BEFORE THIS FRAME — the presenter's own
+ * report of its state, which the session compares against its record of what
+ * it sent (`session.py::_present`). `null` says it held nothing; an ABSENT
+ * field says this presenter does not report one (an older editor integration), and
+ * the session then judges nothing rather than resetting on every frame.
+ */
+export interface PresentAnswer {
+  capture?: unknown;
+  held?: { session: string; revision: number } | null;
+}
+
+/**
+ * WHO MODELLED THIS, AND AT WHAT STATE — the two fields every presented frame
+ * carries about the session that produced it (`browser/session.py`'s `Session`:
+ * a per-session id, and a `revision` that advances once per present).
+ *
+ * Read by anything that has to say WHERE a byte came from rather than merely
+ * display it — `blender-list-files` answers with it, so the CLI's write-back
+ * door can record which session's model a mirrored file was exported from
+ * (`packages/vgai-cli/src/blender-mcp.ts`, class Mirror). Null until the
+ * session's first present.
+ */
+export interface PresentedState {
+  readonly session: string;
+  readonly revision: number;
+}
+
+export interface ScreenshotView {
+  size: number;
+  position?: number[];
+  target?: number[];
+}
+
+/**
+ * HOW LONG THE WORKER TOOK, measured by the PAGE.
+ *
+ * WHY THE PAGE MEASURES (2026-09-16): a single `blender-execute` held the
+ * worker for over 1,800s and wedged the tab, and the only report anyone got
+ * was a replay harness timing out. A blocked worker cannot report on itself —
+ * the loop that would send the number is the loop that is stuck — so the one
+ * vantage point that still works is the side that POSTED the message. Every
+ * call goes through {@link BlenderRuntime.metrics}'s meter, which stamps the
+ * `postMessage` and the reply.
+ *
+ * MEASUREMENT ONLY. Nothing here cancels, kills or budgets a call: a budget is
+ * a policy decision, and this is the number a policy would have to be made
+ * from.
+ *
+ * Times are milliseconds on `performance.now()`. Counters are monotonic since
+ * this runtime was constructed (one per page load).
+ */
+export interface BlenderCallMetrics {
+  /** Age of the OLDEST outstanding call, or null when the worker is idle.
+   *  This is the field that has a number during the wedge — the counters
+   *  below only learn about a call when it comes back. */
+  readonly inFlightMs: number | null;
+  /** Duration of the newest COMPLETED call; null before the first one. */
+  readonly lastCallMs: number | null;
+  /** The longest call yet, counting an outstanding one at its current age —
+   *  otherwise the worst call this session has ever seen is invisible for
+   *  exactly as long as it keeps running. */
+  readonly maxCallMs: number | null;
+  /** Calls whose duration passed 5s, counting outstanding ones already past it. */
+  readonly callsOver5s: number;
+  /** The same at 30s — a call this side of it is slow, past it is a wedge. */
+  readonly callsOver30s: number;
+  /** The newest call's window on the `performance.now()` clock (`end` null
+   *  while it is outstanding). The editor's long-task observer intersects its
+   *  own entries with this to say what the MAIN thread was doing during the
+   *  call; nothing else reads it. */
+  readonly lastCallWindow: { readonly start: number; readonly end: number | null } | null;
+  /**
+   * The module's LINEAR MEMORY in MB, as the worker last reported it
+   * (`protocol.ts`'s `memory` reply); null before the session's first call.
+   *
+   * The engine's memory, which is a different question from every other number
+   * on this tab: the census's `heapUsedMB` is the PAGE's JS heap and the
+   * renderer's RSS is everything at once. wasm32 memory never shrinks, so this
+   * is also the high-water mark and no separate peak is kept.
+   */
+  readonly wasmMemoryMB: number | null;
+}
+
+export class BlenderRuntime {
+  readonly #worker: Worker;
+  readonly #options: BlenderRuntimeOptions;
+  readonly #pending = new Map<
+    number,
+    { resolve: (value: unknown) => void; reject: (error: Error) => void }
+  >();
+  #nextId = 0;
+  #started: Promise<RuntimeStart> | null = null;
+  /** `performance.now()` at the `postMessage` of every outstanding call. */
+  readonly #callStarts = new Map<number, number>();
+  #lastCallMs: number | null = null;
+  #maxCompletedMs = 0;
+  #completedOver5s = 0;
+  #completedOver30s = 0;
+  #lastCallWindow: { start: number; end: number | null } | null = null;
+  #presented: PresentedState | null = null;
+  /** Bytes of module linear memory at the worker's last report; see
+   *  {@link BlenderCallMetrics.wasmMemoryMB}. */
+  #wasmBytes: number | null = null;
+
+  constructor(options: BlenderRuntimeOptions) {
+    this.#options = options;
+    this.#worker = new Worker(new URL('./worker.ts', import.meta.url), {
+      type: 'module',
+      name: 'blender',
+    });
+    this.#worker.onmessage = (event: MessageEvent<WorkerReply>) => void this.#receive(event.data);
+    this.#worker.onerror = (event) => {
+      // A module worker that fails to LOAD reports an ErrorEvent with an empty
+      // message, so `${event.message}` alone said "undefined" and named
+      // nothing. Every field the event carries goes in: the thrown error's own
+      // message and stack when there is one, and the file and line otherwise,
+      // which is what a failed nested import leaves behind.
+      const thrown = event.error as Error | undefined;
+      const where = event.filename ? ` at ${event.filename}:${event.lineno}:${event.colno}` : '';
+      const said = thrown?.stack ?? thrown?.message ?? event.message;
+      const error = new Error(
+        `Blender worker failed: ${said || 'the worker script did not load'}${where}`,
+      );
+      // The page console is the editor's ledger (`installEditorConsoleReporting`
+      // captures it, source-blind), and this package may import nothing of the
+      // editor to say it any other way. Without this line the failure reached
+      // a toast and `vgai console` read 0/0 while no Model document could open
+      // (measured 2026-09-20 from a registry install).
+      console.error(error.message);
+      for (const id of [...this.#pending.keys()]) this.#settled(id);
+      for (const pending of this.#pending.values()) pending.reject(error);
+      this.#pending.clear();
+    };
+  }
+
+  #project: string | null = null;
+  #document: string | null = null;
+
+  get project(): string | null {
+    return this.#project;
+  }
+
+  /** Idempotent: the first call boots Blender at `project`'s
+   *  absolute path; later calls await it (a different path is refused).
+   *
+   *  `document` is the session's `.blend`, project-relative. An explicit
+   *  different file is a resource conflict, including while boot is pending.
+   *  Omitting it on an already-started handle means await that same session. */
+  start(project: string, document?: string): Promise<RuntimeStart> {
+    if (this.#project !== null && this.#project !== project)
+      return Promise.reject(
+        new Error(`The Blender session is bound to ${this.#project}, not ${project}`),
+      );
+    if (document !== undefined && this.#document !== null && this.#document !== document)
+      return Promise.reject(
+        new Error(
+          `Blender resource conflict: the session holds ${this.#document}; cannot open ${document}`,
+        ),
+      );
+    this.#project = project;
+    this.#document ??= document ?? 'models/model.blend';
+    this.#started ??= this.#request({
+      op: 'start',
+      project,
+      ...(document === undefined ? {} : { document }),
+    }) as Promise<RuntimeStart>;
+    return this.#started;
+  }
+
+  #ready(): Promise<RuntimeStart> {
+    if (this.#project === null)
+      return Promise.reject(
+        new Error('The Blender session has not been started with a project (blender-start)'),
+      );
+    return this.start(this.#project);
+  }
+
+  async execute(code: string): Promise<string> {
+    await this.#ready();
+    return (await this.#request({ op: 'execute', code })) as string;
+  }
+
+  async sceneInfo(): Promise<string> {
+    await this.#ready();
+    return (await this.#request({ op: 'scene-info' })) as string;
+  }
+
+  async objectInfo(name: string): Promise<string> {
+    await this.#ready();
+    return (await this.#request({ op: 'object-info', name })) as string;
+  }
+
+  /** One datablock's whole RNA surface (`./rna.ts`). A path that names a
+   *  COLLECTION answers with its members instead of its properties. */
+  async rna(path: string, names?: number): Promise<BlenderRnaView> {
+    await this.#ready();
+    return (await this.#request({
+      op: 'rna',
+      path,
+      ...(names === undefined ? {} : { names }),
+    })) as BlenderRnaView;
+  }
+
+  /** The Properties context: the active object (or the one the caller NAMES),
+   *  its active bone / material slot / modifier / vertex group, and the tabs
+   *  Blender would show for it. */
+  async rnaContext(object?: string, collection?: string): Promise<BlenderRnaContext> {
+    await this.#ready();
+    return (await this.#request({
+      op: 'rna-context',
+      ...(object === undefined ? {} : { object }),
+      ...(collection === undefined ? {} : { collection }),
+    })) as BlenderRnaContext;
+  }
+
+  /** Write ONE property through bpy. Rejects by name when Blender's own RNA
+   *  says the property is read-only. */
+  async rnaSet(
+    path: string,
+    property: string,
+    value: unknown,
+    index?: number,
+  ): Promise<BlenderRnaWrite> {
+    await this.#ready();
+    return (await this.#request({
+      op: 'rna-set',
+      path,
+      property,
+      value,
+      ...(index === undefined ? {} : { index }),
+    })) as BlenderRnaWrite;
+  }
+
+  /** BLENDER'S VIEW LAYER TREE for the scene — what its Outliner shows, as
+   *  rows (`./rna.ts`, `BlenderOutlinerTree`). `selected` is our viewport's
+   *  selection by object name; reading it never writes the engine's. */
+  async outliner(selected?: readonly string[]): Promise<BlenderOutlinerTree> {
+    await this.#ready();
+    return (await this.#request({
+      op: 'outliner',
+      ...(selected === undefined ? {} : { selected }),
+    })) as BlenderOutlinerTree;
+  }
+
+  /** ONE MATERIAL'S SHADER NODE TREE, whole (`./rna.ts`, `BlenderNodeTree`) —
+   *  what the node editor draws. Given neither `path` nor `material`, the
+   *  active object's active material answers, which is what Blender's own
+   *  Shading header resolves. */
+  async nodeTree(options?: { path?: string; material?: string }): Promise<BlenderNodeTree> {
+    await this.#ready();
+    return (await this.#request({
+      op: 'node-tree',
+      ...(options?.path === undefined ? {} : { path: options.path }),
+      ...(options?.material === undefined ? {} : { material: options.material }),
+    })) as BlenderNodeTree;
+  }
+
+  /** ONE MESH'S UV LAYOUT (`./rna.ts`, `BlenderUvLayout`) — what the UV
+   *  editor draws. Given no `object`, the view layer's ACTIVE object answers,
+   *  which is the only subject there is outside edit mode. */
+  async uvLayout(options?: { object?: string; uvLayer?: string }): Promise<BlenderUvLayout> {
+    await this.#ready();
+    return (await this.#request({
+      op: 'uv-layout',
+      ...(options?.object === undefined ? {} : { object: options.object }),
+      ...(options?.uvLayer === undefined ? {} : { uvLayer: options.uvLayer }),
+    })) as BlenderUvLayout;
+  }
+
+  /** ONE MESH'S SKIN BINDING (`./rna.ts`, `BlenderRig`) — the armature's
+   *  bones and the per-vertex influences a `THREE.SkinnedMesh` needs. Given no
+   *  `object`, the view layer's ACTIVE mesh answers. */
+  async rig(options?: { object?: string }): Promise<BlenderRig> {
+    await this.#ready();
+    return (await this.#request({
+      op: 'rig',
+      ...(options?.object === undefined ? {} : { object: options.object }),
+    })) as BlenderRig;
+  }
+
+  /** ONE ACTION AS A THREE.JS CLIP (`./rna.ts`, `BlenderActionClip`). `bake:
+   *  false` answers the header and the summary row's key columns without the
+   *  sampled tracks, which is what a Timeline that only needs to DRAW asks
+   *  for. */
+  async actionClip(options?: { object?: string; bake?: boolean }): Promise<BlenderActionClip> {
+    await this.#ready();
+    return (await this.#request({
+      op: 'action-clip',
+      ...(options?.object === undefined ? {} : { object: options.object }),
+      ...(options?.bake === undefined ? {} : { bake: options.bake }),
+    })) as BlenderActionClip;
+  }
+
+  /** Write ONE restriction column (the eye, the render camera, a collection's
+   *  Exclude). A column Blender draws on no row of that type is refused by
+   *  name rather than written somewhere near it. */
+  async outlinerSet(path: string, column: string, value: boolean): Promise<BlenderOutlinerWrite> {
+    await this.#ready();
+    return (await this.#request({
+      op: 'outliner-set',
+      path,
+      column,
+      value,
+    })) as BlenderOutlinerWrite;
+  }
+
+  /**
+   * PRESENT WHAT THE ENGINE HOLDS, with no capture.
+   *
+   * Every mutation presents (`session.py::dispatch`), so in the ordinary
+   * course of a session nothing needs to ask. The exception is the first
+   * frame: opening a `.blend` is not a mutation, so a freshly opened Model
+   * document had nothing to display until something RAN — measured by I1 and
+   * fixed here (WORK.md §Blender in the tab is Blender, "Inspection parity",
+   * I2 decision 6). The document asks on mount.
+   */
+  async present(): Promise<void> {
+    await this.#ready();
+    await this.#request({ op: 'present' });
+  }
+
+  /** Presents the model with the viewport's camera and returns that view. */
+  async screenshotView(maxSize: number): Promise<{ view: ScreenshotView } | { error: string }> {
+    await this.#ready();
+    return (await this.#request({ op: 'screenshot-view', maxSize })) as
+      | { view: ScreenshotView }
+      | { error: string };
+  }
+
+  async readFile(path: string): Promise<Uint8Array> {
+    await this.#ready();
+    return (await this.#request({ op: 'read-file', path })) as Uint8Array;
+  }
+
+  async writeFile(path: string, bytes: Uint8Array): Promise<void> {
+    await this.#ready();
+    await this.#request({ op: 'write-file', path, bytes });
+  }
+
+  async listFiles(path: string): Promise<FileEntry[]> {
+    await this.#ready();
+    return (await this.#request({ op: 'list-files', path })) as FileEntry[];
+  }
+
+  /** The session and revision of the last frame this runtime forwarded; null
+   *  before the first present. See {@link PresentedState}. */
+  get presented(): PresentedState | null {
+    return this.#presented;
+  }
+
+  terminate(): void {
+    this.#worker.terminate();
+    const error = new Error('The Blender session was terminated');
+    for (const id of [...this.#pending.keys()]) this.#settled(id);
+    for (const pending of this.#pending.values()) pending.reject(error);
+    this.#pending.clear();
+  }
+
+  /**
+   * What this tab knows about the worker's responsiveness, right now.
+   *
+   * Computed at READ time rather than accumulated, because the interesting
+   * call is the one that has not come back: an outstanding call contributes to
+   * `maxCallMs` and to the two bucket counts at its CURRENT age, so a wedge
+   * shows up while it is happening instead of only in its post-mortem.
+   *
+   * A `present` is not counted separately — the worker only presents from
+   * inside a call this meter is already holding open, and the page-side cost of
+   * displaying the frame is main-thread time, which is the long-task observer's
+   * subject (`packages/editor/src/blender-tab-metrics.ts`).
+   */
+  metrics(now: number = performance.now()): BlenderCallMetrics {
+    let oldest: number | null = null;
+    let max = this.#maxCompletedMs;
+    let over5 = this.#completedOver5s;
+    let over30 = this.#completedOver30s;
+    for (const started of this.#callStarts.values()) {
+      const elapsed = now - started;
+      if (oldest === null || elapsed > oldest) oldest = elapsed;
+      if (elapsed > max) max = elapsed;
+      if (elapsed >= 5_000) over5 += 1;
+      if (elapsed >= 30_000) over30 += 1;
+    }
+    return {
+      inFlightMs: oldest === null ? null : Math.round(oldest),
+      lastCallMs: this.#lastCallMs === null ? null : Math.round(this.#lastCallMs),
+      // Zero here would mean "no call has ever taken any time", which is a
+      // different claim from "no call has happened yet".
+      maxCallMs: this.#lastCallMs === null && oldest === null ? null : Math.round(max),
+      callsOver5s: over5,
+      callsOver30s: over30,
+      lastCallWindow: this.#lastCallWindow,
+      wasmMemoryMB: this.#wasmBytes === null ? null : Math.round(this.#wasmBytes / 1048576),
+    };
+  }
+
+  /** Close a call's window, whether it answered, threw, or was terminated. */
+  #settled(id: number): void {
+    const started = this.#callStarts.get(id);
+    if (started === undefined) return;
+    this.#callStarts.delete(id);
+    const elapsed = performance.now() - started;
+    this.#lastCallMs = elapsed;
+    if (elapsed > this.#maxCompletedMs) this.#maxCompletedMs = elapsed;
+    if (elapsed >= 5_000) this.#completedOver5s += 1;
+    if (elapsed >= 30_000) this.#completedOver30s += 1;
+    if (this.#lastCallWindow !== null && this.#lastCallWindow.start === started)
+      this.#lastCallWindow = { start: started, end: started + elapsed };
+  }
+
+  #request(request: Request): Promise<unknown> {
+    const id = ++this.#nextId;
+    return new Promise((resolve, reject) => {
+      this.#pending.set(id, { resolve, reject });
+      const started = performance.now();
+      this.#callStarts.set(id, started);
+      this.#lastCallWindow = { start: started, end: null };
+      this.#worker.postMessage({ ...request, id });
+    });
+  }
+
+  async #receive(reply: WorkerReply): Promise<void> {
+    if ('op' in reply) {
+      if (reply.op === 'log') {
+        this.#options.log?.(reply.level, reply.text);
+        return;
+      }
+      if (reply.op === 'memory') {
+        this.#wasmBytes = reply.bytes;
+        return;
+      }
+      // Recorded BEFORE the display, and whether or not the display throws:
+      // the fact being kept is that the session reached this revision, which is
+      // true the moment the frame arrives. A presenter that refuses the frame
+      // has not un-modelled it.
+      const frame = reply.frame as { session?: unknown; revision?: unknown } | null;
+      if (typeof frame?.session === 'string' && typeof frame.revision === 'number')
+        this.#presented = { session: frame.session, revision: frame.revision };
+      try {
+        const answer = await this.#options.present(reply.frame, reply.description, reply.capture);
+        this.#worker.postMessage({
+          op: 'present-result',
+          id: reply.id,
+          ...(answer?.capture === undefined ? {} : { capture: answer.capture }),
+          ...(answer !== null && answer !== undefined && 'held' in answer
+            ? { held: answer.held }
+            : {}),
+        } satisfies WorkerRequest);
+      } catch (error) {
+        this.#worker.postMessage({
+          op: 'present-result',
+          id: reply.id,
+          error: error instanceof Error ? error.message : String(error),
+        } satisfies WorkerRequest);
+      }
+      return;
+    }
+    const pending = this.#pending.get(reply.id);
+    if (!pending) return;
+    this.#pending.delete(reply.id);
+    this.#settled(reply.id);
+    'error' in reply ? pending.reject(new Error(reply.error)) : pending.resolve(reply.result);
+  }
+}

package/browser/session-frame.mts

@@ -0,0 +1,169 @@
+/**
+ * The session's frame, read out of the EXPORT DOOR'S ARENA as typed arrays.
+ *
+ * The C++ door (`bpy_web_export.cc`) answers one call with a small JSON frame
+ * and a side arena of bytes; every large column lives in the arena and the
+ * frame names it as `{offset, length, dtype, count, stride}`. Nothing large is
+ * ever spelled in the JSON, because the JSON is parsed and the arena is not.
+ * This is the other half: each descriptor becomes the typed array the
+ * presenter reads, and the buffers are what `presentToTab` transfers.
+ *
+ * THIS FILE DOES NOT KNOW WHICH BLENDER IT IS SERVING, and that is the seam
+ * working. It is handed THE ARENA'S BYTES -- offset zero at the arena's base --
+ * by `BlenderEngine.readArena`, which is a view on `HEAPU8` where the host can
+ * reach the module's memory and the contents of `export_frame`'s `buffer_path`
+ * file where it cannot. Both are valid until the next `export_frame`; nothing
+ * else about the two skews reaches this far up.
+ *
+ * THE COPY IS MANDATORY. On the standalone skew the arena is wasm linear
+ * memory, and under `-sPROXY_TO_PTHREAD` that memory is SHARED: a view onto it
+ * cannot be transferred to the tab, and the next `export_frame` overwrites it.
+ * `.slice()` is what makes the bytes this thread's own -- and it also puts
+ * them at offset zero of a fresh buffer, which is what lets a `Float32Array`
+ * be built over bytes the arena only aligned to eight.
+ */
+
+export interface ColumnDescriptor {
+  /** Byte offset into the arena. */
+  offset: number;
+  /** Byte length. */
+  length: number;
+  dtype: string;
+  /** Elements; `count * stride` values. */
+  count: number;
+  /** Values per element (3 for a position, 2 for an edge, 1 for a flag). */
+  stride: number;
+}
+
+const isDescriptor = (value: unknown): value is ColumnDescriptor =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as ColumnDescriptor).offset === 'number' &&
+  typeof (value as ColumnDescriptor).length === 'number' &&
+  typeof (value as ColumnDescriptor).dtype === 'string' &&
+  typeof (value as ColumnDescriptor).count === 'number' &&
+  typeof (value as ColumnDescriptor).stride === 'number';
+
+type Typed =
+  | Float32Array
+  | Float64Array
+  | Uint32Array
+  | Int32Array
+  | Uint8Array
+  | Int8Array
+  | Int16Array
+  | Uint16Array;
+
+/** The door's own dtype vocabulary -- the C type each column was written from,
+ *  not numpy's codes: the Python exporter that spoke numpy is gone. */
+const READERS: Record<string, (bytes: Uint8Array) => Typed> = {
+  f32: (b) => new Float32Array(b.buffer, b.byteOffset, b.byteLength >> 2),
+  f64: (b) => new Float64Array(b.buffer, b.byteOffset, b.byteLength >> 3),
+  u32: (b) => new Uint32Array(b.buffer, b.byteOffset, b.byteLength >> 2),
+  i32: (b) => new Int32Array(b.buffer, b.byteOffset, b.byteLength >> 2),
+  u16: (b) => new Uint16Array(b.buffer, b.byteOffset, b.byteLength >> 1),
+  i16: (b) => new Int16Array(b.buffer, b.byteOffset, b.byteLength >> 1),
+  u8: (b) => b,
+  i8: (b) => new Int8Array(b.buffer, b.byteOffset, b.byteLength),
+};
+
+function readColumn(arena: Uint8Array, name: string, descriptor: ColumnDescriptor): Typed {
+  const read = READERS[descriptor.dtype];
+  if (!read) throw new Error(`Blender frame column ${name}: unknown dtype ${descriptor.dtype}`);
+  const { offset, length } = descriptor;
+  // ONE PAST THE ARENA IS AN ERROR NAMING THE COLUMN. A descriptor is an offset
+  // into the arena; a wrong one reads whatever else lives there, silently.
+  if (offset < 0 || length < 0 || offset + length > arena.byteLength)
+    throw new Error(
+      `Blender frame column ${name}: bytes ${offset}..${offset + length} lie outside the ${arena.byteLength}-byte export arena`,
+    );
+  const bytes = arena.subarray(offset, offset + length).slice();
+  const view = read(bytes);
+  const expected = descriptor.count * descriptor.stride;
+  if (view.length !== expected)
+    throw new Error(
+      `Blender frame column ${name}: ${view.length} values, ${expected} declared (${descriptor.count} x ${descriptor.stride})`,
+    );
+  return view;
+}
+
+/**
+ * Every `{offset, length, dtype, count, stride}` in the frame, replaced by its
+ * typed array.
+ *
+ * `co` is widened to `Float64Array` because that is what `MeshColumns`
+ * declares and `drawArraysFromColumns` is typed against, while Blender's own
+ * vertex array is single precision.
+ */
+export function columnsToTypedArrays(arena: Uint8Array, frame: unknown): unknown {
+  const walk = (value: unknown, key: string): unknown => {
+    if (isDescriptor(value)) {
+      const view = readColumn(arena, key, value);
+      return key === 'co' ? Float64Array.from(view) : view;
+    }
+    if (Array.isArray(value)) return value.map((entry) => walk(entry, key));
+    if (typeof value === 'object' && value !== null) {
+      const out: Record<string, unknown> = {};
+      for (const [name, held] of Object.entries(value)) out[name] = walk(held, name);
+      return out;
+    }
+    return value;
+  };
+  return walk(frame, '');
+}
+
+/** A column as the RECORD of it: what it was, how many bytes, and their digest.
+ *  Never the bytes — see `describeFrame`. */
+export interface ColumnDigest {
+  dtype: string;
+  length: number;
+  /** Lowercase hex SHA-256 of exactly the `length` bytes the descriptor names. */
+  sha256: string;
+}
+
+/**
+ * THE FRAME THIS PRESENT SUBMITTED, as a record that can sit in a JSON file.
+ *
+ * The presenter is asked, later, whether what it DISPLAYS is what the session
+ * SENT (`replay_draw_compare.compare_draws`), and that comparison had no second
+ * side: the live document keeps the frame's identity and object table but drops
+ * every geometry payload the moment it has built the `BufferGeometry` (850 MB of
+ * main-thread heap otherwise — `blender-runtime-view.ts`), and nothing else
+ * remembered the frame at all.
+ *
+ * So the worker records it here, while the arena is still the frame's own: every
+ * `{offset, length, dtype, count, stride}` becomes `{dtype, length, sha256}` and
+ * everything else — objects, materials, cameras, the world, the counts — is
+ * copied as it stands. THE COLUMN BYTES NEVER LEAVE THE TAB; a record of the
+ * numbers is not the numbers, and a battery run must not write a scene's meshes
+ * to disk a second time.
+ *
+ * This runs BEFORE `presentToTab` posts, for two reasons that are both fatal
+ * otherwise: the buffers are TRANSFERRED (detached the instant they are posted),
+ * and the arena is overwritten by the next `export_frame`.
+ */
+export async function describeFrame(arena: Uint8Array, frame: unknown): Promise<unknown> {
+  const walk = async (value: unknown, key: string): Promise<unknown> => {
+    if (isDescriptor(value)) {
+      const { offset, length, dtype } = value;
+      if (offset < 0 || length < 0 || offset + length > arena.byteLength)
+        throw new Error(
+          `Blender frame column ${key}: bytes ${offset}..${offset + length} lie outside the ${arena.byteLength}-byte export arena`,
+        );
+      const bytes = arena.subarray(offset, offset + length).slice();
+      const hash = await crypto.subtle.digest('SHA-256', bytes);
+      const sha256 = [...new Uint8Array(hash)]
+        .map((byte) => byte.toString(16).padStart(2, '0'))
+        .join('');
+      return { dtype, length, sha256 } satisfies ColumnDigest;
+    }
+    if (Array.isArray(value)) return Promise.all(value.map((entry) => walk(entry, key)));
+    if (typeof value === 'object' && value !== null) {
+      const out: Record<string, unknown> = {};
+      for (const [name, held] of Object.entries(value)) out[name] = await walk(held, name);
+      return out;
+    }
+    return value;
+  };
+  return walk(frame, '');
+}