@volter/blender-engine 0.1.147 → 0.1.149

package/browser/heap-growth.mts

@@ -0,0 +1,23 @@
+import { HEAP_GROWTH_REFUSED } from './protocol';
+
+/** Report WebAssembly.Memory.grow refusals from each thread before allocation aborts obscure the failed growth request. */
+export function watchHeapGrowthSource(report: string): string {
+  return `(() => {
+  const grow = WebAssembly.Memory.prototype.grow;
+  if (grow.volterWatched) return;
+  const watched = function (pages) {
+    let before = 0;
+    try { before = this.buffer.byteLength; } catch (_) {}
+    try { return grow.call(this, pages); }
+    catch (error) {
+      const line = '${HEAP_GROWTH_REFUSED}: the browser refused ' + Math.round(pages * 65536 / 1048576) + ' MB more at ' +
+        Math.round(before / 1048576) + ' MB (' + String(error && error.message || error) + '); allocations fail from here.';
+      try { (${report})(line); } catch (_) {}
+      throw error;
+    }
+  };
+  watched.volterWatched = true;
+  WebAssembly.Memory.prototype.grow = watched;
+})();
+`;
+}

package/browser/index.ts

@@ -3,5 +3,7 @@ export {
   BlenderRuntime,
   type BlenderRuntimeOptions,
   type PresentAnswer,
+  type SavedDocument,
+  type SaveScript,
   type ScreenshotView,
 } from './runtime';

package/browser/protocol.ts

@@ -1,10 +1,21 @@
 import type { FrameChunk } from './frame-stream.mts';
+
+/** The start of the line a Blender thread prints when the browser refuses to grow the engine's heap
+ *  (`blender-emscripten-engine.mts`, `watchHeapGrowthSource`); the tab keeps it (`runtime.ts`). */
+export const HEAP_GROWTH_REFUSED = 'Blender heap could not grow';
 /** Messages between the editor tab and its Blender worker. One session per
  * worker; the model lives in the worker's Python and nowhere else. */
 
 export type WorkerRequest =
   | { id: number; op: 'load-next'; token: string }
   | { id: number; op: 'flush-document' }
+  /** The document's bytes as a save would write them, for a backup: nothing is carried to the
+   *  project and the document stays dirty. */
+  | { id: number; op: 'snapshot-document' }
+  /** Reopen the document from the project's file, discarding what it holds. */
+  | { id: number; op: 'revert-document' }
+  /** Reopen the document as `bytes` (a backup), which is then its unsaved state. */
+  | { id: number; op: 'restore-document'; bytes: Uint8Array }
   | { id: number; op: 'history-begin' | 'history-end' }
   | { id: number; op: 'history-step'; token: string; direction: 'undo' | 'redo' }
   /** `document` is the session's `.blend`, PROJECT-RELATIVE (`models/model.blend`
@@ -19,10 +30,8 @@ export type WorkerRequest =
   | { id: number; op: 'scene-info' }
   | { id: number; op: 'object-info'; name: string }
   | { id: number; op: 'screenshot-view'; maxSize: number }
-  /** PRESENT WHAT THE ENGINE ALREADY HOLDS, with no capture — the frame a
-   *  freshly opened Model document asks for (`session.py`'s `present` op,
-   *  which `dispatch` has always answered; nothing sent it until the document
-   *  did). Every mutation presents, so this is only ever the FIRST one. */
+  /** Present the engine's current document state without capture. Used for initial display and
+   *  explicit refreshes of an already-open document (`session.py`'s `present` op). */
   | { id: number; op: 'present' }
   /** THE RNA DOOR (`./rna.ts` is its contract, `session.py`'s `rna_view`
    *  its answer): one datablock's `bl_rna.properties` as typed rows. `path` is
@@ -73,6 +82,21 @@ export type WorkerRequest =
    *  plus the scene's frame range/fps and the summary row's key columns.
    *  READ ONLY: keying, moving a key and setting a range are edits. */
   | { id: number; op: 'action-clip'; object?: string; bake?: boolean; action?: string; summary?: boolean }
+  /** THE SCENE'S MOVIE (`session.py`'s `rna_scene_movie`): its range, markers and cameras, and every
+   *  object's transform stack and curves, for Timeline playback and glTF export. READ ONLY. */
+  | { id: number; op: 'scene-movie' }
+  /** Scene sound strips and speakers over frames first to last. READ ONLY;
+   * speaker sampling restores the scene frame before returning. */
+  | { id: number; op: 'sound-scene'; first: number; last: number }
+  /** Export a component or level through Blender’s glTF exporter. Restore temporary state before
+   * answering; do not create history, save or present. */
+  | { id: number; op: 'gltf-export'; kind: GltfExportKind; force?: boolean; previous?: GltfExportPrevious; blendSha256?: string; luts?: Readonly<Record<string, string>> }
+  /** A SCRIPT RUN AS `blender -b <document> -P <script> -- <args>` runs one (`session.py`'s `_run_script`): its
+   *  working directory a folder emptied for it, whose files the tab carries into the project. The script puts back
+   *  what it changes: no history, save or present. */
+  | { id: number; op: 'run-script'; source: string; args: readonly string[]; dir: string }
+  /** AN ASSET LIBRARY IN BLENDER'S PREFERENCES (`session.py`'s `_asset_library`): a preference, not an edit. */
+  | { id: number; op: 'asset-library'; library: BlenderAssetLibrary }
   /** ONE RESTRICTION COLUMN, written (`session.py`'s `outliner_set`). A column
    *  Blender draws on no row of that type is refused by name. */
   | { id: number; op: 'outliner-set'; path: string; column: string; value: boolean }
@@ -81,7 +105,6 @@ export type WorkerRequest =
   | { id: number; op: 'view-shading'; shading: 'WIREFRAME' | 'SOLID' | 'MATERIAL' | 'RENDERED' }
   | { id: number; op: 'read-file'; path: string }
   | { id: number; op: 'write-file'; path: string; bytes: Uint8Array }
-  | { id: number; op: 'list-files'; path: string }
   /** The tab's answer to a `present` the worker asked for.
    *
    *  `held` is the PRESENTER'S OWN report of what it held BEFORE this frame
@@ -99,6 +122,8 @@ export type WorkerRequest =
 export type WorkerReply =
   | { op: 'frame-stream'; id: number; chunk: FrameChunk }
   | { op: 'document-dirty'; dirty: boolean }
+  /** A protected document is not being written; null follows a successful project save. */
+  | { op: 'document-saving'; document: string; note: string | null }
   /** THE DOCUMENT FOLLOWED BLENDER: a script's `save_as_mainfile` (or `open_mainfile`) left
    *  another project `.blend` open, and the session's saves now go there
    *  (`session.py::follow_open_file`). Both paths are project-relative. Posted before the
@@ -119,21 +144,7 @@ export type WorkerReply =
    *  displayed-versus-submitted comparison otherwise does not have. */
   | { op: 'present'; id: number; frame: unknown; description: unknown; capture?: CaptureRequest }
   | { op: 'log'; level: 'log' | 'warn' | 'error'; text: string }
-  /**
-   * HOW BIG THE MODULE'S LINEAR MEMORY IS, posted after every call.
-   *
-   * The one number about the engine's memory that only the worker can read
-   * (`Module.HEAPU8.length`), and the one the tab's census had no field for:
-   * `heapUsedMB` is the PAGE's JS heap and says nothing about the wasm. wasm32
-   * memory never shrinks, so this value is also the session's high-water mark
-   * — a reader needs no separate peak.
-   *
-   * MEASURED 2026-09-18: 512 MB reserved at boot of which ~166 MB is ever
-   * touched (so the reservation itself costs no resident pages), growing to
-   * 1036 MB across `17-workshop-interior`. Every byte dlmalloc takes inside it
-   * stays taken: there is no `madvise` in wasm, so a scene's peak allocation is
-   * a permanent cost for the life of the tab.
-   */
+  /** The worker’s current wasm linear-memory size, posted after each call. This differs from the page’s JS heap and also records the wasm high-water mark because wasm32 memory does not shrink. */
   | { op: 'memory'; bytes: number };
 
 export type NativeHistoryEntry = { reset: true } | {
@@ -193,15 +204,7 @@ export interface CaptureRequest {
   render?: RenderRequest;
 }
 
-/**
- * `bpy.ops.render.render()` asking for the scene camera's own picture.
- *
- * three.js IS the renderer (ARCHITECTURE-CORE, "No second implementation of a
- * substrate capability ships"), so a render is the Model document photographed
- * through the scene's camera at `scene.render`'s exact resolution — and unlike
- * a screenshot, whose view is only REMEMBERED for the transport to photograph
- * later, the pixels come back to the caller inside the operator that asked.
- */
+
 export interface RenderRequest {
   /** Omit the visible world while retaining its illumination. */
   transparent?: boolean;
@@ -218,7 +221,7 @@ export interface RenderRequest {
   /** The scene's own view transform, as the three.js tone mapping of the same
    *  NAME (`bpy/_render_three.py`). A transform with no curve here never
    *  reaches this point: Python refuses it. */
-  toneMapping: 'none' | 'agx' | 'filmic' | 'neutral';
+  toneMapping: 'none' | 'agx' | 'filmic' | 'neutral' | 'aces13' | 'aces20';
   /** The colour-management LOOK the scene asks for, as Blender names it.
    *  `'None'` means the base transform; anything else is a look the view holds
    *  a baked table for, because the renderer refuses the rest by name. */
@@ -241,6 +244,90 @@ export interface RenderRequest {
   orthographic: boolean;
 }
 
+/**
+ * Export a component .blend or a level that links components.
+ */
+export type GltfExportKind = 'component' | 'level';
+
+/** The project's earlier export, as the tab holds it: its manifest and its file's SHA-256. */
+export interface GltfExportPrevious {
+  readonly manifest: GltfExportManifest;
+  readonly sha256: string | null;
+}
+
+/** One placement marker of a level (`extras.component`, `extras.action`, `extras.tint`, visibility). */
+export interface GltfExportMarker {
+  readonly name: string;
+  readonly component: { readonly file: string; readonly collection: string };
+  readonly action: string | null;
+  readonly visible: boolean;
+  readonly tint: unknown;
+  readonly parent: string | null;
+}
+
+/** The manifest written beside each export (`<name>.json`): what made it, and what it holds. */
+export interface GltfExportManifest {
+  readonly format: 1;
+  readonly kind: GltfExportKind;
+  /** The `.blend`, project-relative, and the SHA-256 of its bytes when it was exported. */
+  readonly blend: string;
+  readonly blendSha256: string;
+  /** Blender's version, its glTF add-on's, and the first 16 hex digits of `gltf_export.py`'s SHA-256. */
+  readonly exporter: { readonly blender: string; readonly gltf: string; readonly script: string };
+  readonly settings: Readonly<Record<string, string | boolean>>;
+  readonly file: string;
+  readonly sha256: string;
+  readonly bytes: number;
+  readonly nodes: number;
+  readonly meshes: number;
+  readonly skins: number;
+  readonly animations: readonly string[];
+  readonly extensionsUsed: readonly string[];
+  readonly hiddenNodes: number;
+  readonly warnings: readonly string[];
+  /**
+   * A component’s collections, named after the component.
+   */
+  readonly collections?: readonly string[];
+  /** A level's placements, the components they name, and the override edits no marker carries. */
+  readonly markers?: readonly GltfExportMarker[];
+  readonly components?: readonly { readonly file: string; readonly collection: string }[];
+  readonly unsupported?: readonly { readonly placement: string; readonly edit: string }[];
+}
+
+/** What `gltf-export` answers. `files` are the module-filesystem paths of the written `.glb`
+ *  and manifest (none when the earlier export is `current`), for the tab to carry out. */
+export interface GltfExportAnswer {
+  readonly kind: GltfExportKind;
+  readonly name: string;
+  readonly document: string;
+  readonly current: boolean;
+  readonly ms: number;
+  readonly manifest: GltfExportManifest;
+  readonly files: readonly string[];
+  /** What this Blender writes for either kind: the exporter's version and each kind's settings. */
+  readonly exporter: GltfExportManifest['exporter'];
+  readonly settings: Readonly<Record<GltfExportKind, GltfExportManifest['settings']>>;
+}
+
+/** What `run-script` answers: the script's printed output and its raise (`error`, null when it ran to its end), and
+ *  each file it wrote under its own working directory (the run's `dir`), by its path from there, with its bytes.
+ *  `unstaged` names the project files that could not be copied into Blender before it ran. */
+export interface ScriptRunAnswer {
+  readonly output: string;
+  readonly error: string | null;
+  readonly files: readonly { readonly path: string; readonly bytes: Uint8Array }[];
+  readonly unstaged: readonly string[];
+}
+
+/** An asset library as Preferences > File Paths > Asset Libraries lists one: its name, its folder by its path from the
+ *  project, and how an asset dragged from it is imported. */
+export interface BlenderAssetLibrary {
+  readonly name: string;
+  readonly directory: string;
+  readonly importMethod: 'LINK' | 'APPEND' | 'APPEND_REUSE' | 'PACK';
+}
+
 export interface FileEntry {
   path: string;
   size: number;
@@ -251,11 +338,8 @@ export interface FileEntry {
 export interface RuntimeStart {
   session: string;
   python: string;
-  /** Which build of Blender answered: the standalone Emscripten module, or
-   *  Blender as a WALI program on browser-substrate. One gate, both skews --
-   *  a board that cannot name the skew it measured cannot call a difference
-   *  between them a defect in either. */
-  skew?: 'emscripten' | 'wali';
+  /** The engine implementation that answered: standalone Emscripten or WALI on browser-substrate. */
+  skew: 'emscripten' | 'wali';
   /** The session's document, project-relative, when one was named. */
   document?: string;
   /** True when the project already held that `.blend` and it was OPENED —

package/browser/pull-job.mts

@@ -10,15 +10,7 @@ export class PullJob<T> {
   private expected: string | null = null;
   private resume: (() => void) | null = null;
   private waiter: { resolve: (value: PullResult<T>) => void; reject: (error: unknown) => void } | null = null;
-  /**
-   * How the work ended, when it ended while nobody was waiting on a step. Work normally ends only
-   * while a step waits, but work that races something against a checkpoint (an engine compiling
-   * beside an import) can fail in the gap after a `continue` was handed out. The outcome is kept
-   * for the step that comes next, so the caller is told what actually happened. Before this, the
-   * failure was thrown at nobody and the next step answered "Invalid or replayed load
-   * continuation", which named the protocol instead of the fault (measured 2026-10-08: a Blender
-   * start refused by a content security policy showed only that message, on every retry).
-   */
+  /** Keep a terminal result that arrives between cooperative steps so the next step reports the original failure. */
   private ended: { readonly value: T } | { readonly error: unknown } | null = null;
   constructor(private readonly work: (checkpoint: (phase: string) => Promise<void>) => Promise<T>) {}
   step(token?: string): Promise<PullResult<T>> {
@@ -48,7 +40,7 @@ export class PullJob<T> {
         if (waiter) waiter.reject(error);
         else {
           this.ended = { error };
-          // Said now as well: if the owner never asks for the next step, nobody would collect it.
+          // Report the failure now while retaining it for the next step.
           console.warn('A Blender load failed between steps; the next step reports it:', error);
         }
       });

package/browser/rna.ts

@@ -1,17 +1,4 @@
-/**
- * THE RNA DOOR'S CONTRACT — what `session.py`'s `rna_view`, `rna_context` and
- * `rna_set` answer, as types. TYPES ONLY, no imports and no values: the
- * Properties sections (`../contributions/blender-properties-*`) read these
- * shapes, and a type-only module costs their closure nothing.
- *
- * Everything here is Blender's own introspection of Blender's own data
- * (`bl_rna.properties`) — the ruling's "everything Blender SHOWS about a
- * datablock, we show, in OUR panels, read from the engine through bpy and RNA"
- * (ARCHITECTURE-CORE §Blender north star, "Inspection parity, not editing
- * parity"). Nothing in this file is a volter invention over RNA: every field is
- * a `PropertyRNA` member, a `bpy.types` name, or an address `path_from_id()`
- * produced.
- */
+
 
 /** `PropertyRNA.type` — Blender's own property-type enum. */
 export type BlenderRnaType =
@@ -71,9 +58,7 @@ export interface BlenderRnaRow {
    *  swatch instead of three numbers. */
   readonly subtype: string;
   readonly description: string;
-  /** The RNA STRUCT that declares this property (`Object`, `ID`, `Mesh`) —
-   *  the only grouping RNA exposes, and the one the generic view groups by.
-   *  Blender's panel layout is not this and is not read (the ruling). */
+  /** The declaring RNA struct (Object, ID, Mesh), used to group properties independently of Blender’s panel layout. */
   readonly group: string;
   readonly groupName: string;
   readonly arrayLength: number;
@@ -86,7 +71,7 @@ export interface BlenderRnaRow {
    *  `ViewLayer.depsgraph` (`rna_layer.cc:733`), the NLA tweak storage
    *  (`rna_animation.cc:1701,1713`). The door reports it; the generic view
    *  OMITS it, and no curated list names one. */
-  readonly hidden?: boolean;
+  readonly hidden: boolean;
   /** UNDRAWN STATE — RNA never gave this property UI text, so
    *  `rna_define.cc:1311-1312`'s defaults still stand: `name` is the
    *  identifier and `description` is empty. The modifier panel-open booleans
@@ -238,8 +223,7 @@ export interface BlenderRnaWrite {
 // ---- the outliner tree -----------------------------------------------------
 //
 // WHAT `session.py`'s `rna_outliner` ANSWERS: Blender's VIEW LAYER tree for the
-// session's scene, as rows (WORK.md §Blender in the tab is Blender,
-// "Inspection parity", I3). Every field below is Blender's own — a `TSE_*`
+// session's scene, as rows. Every field below is Blender's own — a `TSE_*`
 // element type, an `ICON_*` name `tree_element_get_icon` picks, a restriction
 // column `outliner_draw_restrictbuts` draws — and nothing here is a volter
 // invention over the Outliner.
@@ -303,7 +287,7 @@ export interface BlenderOutlinerRow {
   readonly object?: string;
   /** A layer collection row's COLLECTION address. The row itself is addressed
    *  by its POSITION in the view layer, because a `LayerCollection` has no
-   *  `path_from_id()` (I2's finding); this is the collection datablock it
+   *  `path_from_id()`; this is the collection datablock it
    *  shows. */
   readonly data?: string;
   readonly selected?: boolean;
@@ -408,7 +392,7 @@ export interface BlenderNode {
   readonly colorTag: BlenderNodeColorTag;
   /** Tree-space `[x, y]`: the node's top-left corner, which is where
    *  `node_update_basis` starts laying out (`node_draw.cc:1295-1300`). */
-  readonly location: readonly number[];
+  readonly location: readonly [number, number];
   readonly width: number;
   /** `Node.hide` — Blender's COLLAPSED node, drawn as a short rounded bar
    *  (`node_update_collapsed`, `node_draw.cc:1326-1390`). */
@@ -416,23 +400,12 @@ export interface BlenderNode {
   readonly muted: boolean;
   readonly selected: boolean;
   readonly useCustomColor: boolean;
-  readonly color: readonly number[];
+  readonly color: readonly [number, number, number];
   /** The frame node this one sits inside, by name, or null. */
   readonly parent: string | null;
   /** `NODE_DO_OUTPUT` through its one RNA spelling. */
   readonly activeOutput: boolean;
-  /**
-   * HOW MANY SOCKET PANELS THE NODE DECLARES (`Node.panel_states`). A panel
-   * state carries a `persistent_uid` and `is_collapsed` and nothing else
-   * (`rna_nodetree.cc:9289-9299`, `:9430-9434`); which SOCKETS belong to a
-   * panel, and what a panel is CALLED, live in the node's C++ declaration
-   * that `node_update_basis_from_declaration` (`node_draw.cc:1086-1218`)
-   * walks, and bpy exposes neither — so that half is TRACED from Blender's
-   * source (ruled 2026-09-19) and this door owes only the live half. The
-   * trace and its table belong to the CONSUMER, `@volter/editor-blender`, because they
-   * read a Blender checkout rather than the running engine; this package
-   * answers what the engine knows and nothing else.
-   */
+  /** Live Node.panel_states values. Socket-panel labels and membership come from Blender’s C++ declarations and belong to the editor-blender consumer’s source table. */
   readonly panelCount: number;
   /**
    * The states themselves, IN DECLARATION ORDER — Blender indexes
@@ -473,39 +446,14 @@ export interface BlenderNodeTree {
   readonly links: readonly BlenderNodeLink[];
 }
 
-/**
- * What `rna_uv_layout` answers — ONE MESH'S UV LAYOUT, as Blender's UV editor
- * would draw it.
- *
- * THE PER-CORNER ARRAYS CROSS AS BASE64 typed-array bytes, for the reason
- * I4's weights do: a layout is `loops` two-float corners plus a
- * triangulation, and the generic RNA door answers a struct at a time.
- * `uvBase64` is `Float32Array` of `loops * 2` (u, v per corner, in corner
- * order); `triangleBase64` is `Uint32Array` of `triangles * 3` CORNER indices
- * into that array — Blender's own `calc_loop_triangles` fan, never one of
- * ours; `loopStartBase64` / `loopTotalBase64` are `Uint32Array` of
- * `polygons`, which is what makes a face's UV outline a contiguous walk;
- * `pinBase64` is `Uint8Array` of `loops` and is null when nothing is pinned.
- *
- * `active` null with a non-empty `layers` cannot happen (a mesh with UV maps
- * has an active one); `active` null with `layers` empty is a mesh that has no
- * UV map at all, which is a STATE — `arena-vanguard.blend`'s 17,778-vertex
- * body is exactly that, measured 2026-09-19 — and the door answers the header
- * alone.
- *
- * `selection` is null at this pin and says so rather than being absent: UV
- * selection lives in the BMesh an edit-mode session holds, and
- * `MeshUVLoopLayer` (`rna_mesh.cc:2380-2456`) declares `uv`, `pin`, `name`,
- * `active`, `active_render` and `active_clone` and no selection of any kind.
- */
+/** One mesh’s UV layout. uvBase64 contains Float32 corner pairs; triangleBase64 contains Uint32 corner indices; loopStartBase64 and loopTotalBase64 delimit polygon corners; pinBase64 is Uint8 or null. A mesh with no UV layers has no active layer. Selection is null because MeshUVLoopLayer exposes no selection field outside edit-mode BMesh. */
 export interface BlenderUvLayout {
   readonly object: string | null;
   readonly mesh: string | null;
   readonly path?: string;
   readonly layers: readonly string[];
   readonly active: string | null;
-  /** `bpy.context.mode` — reported, never required (orchestrator ruling 1,
-   *  2026-09-19: inspection is not mode-gated). */
+  /** bpy.context.mode, reported without gating inspection on the current mode. */
   readonly mode: string;
   readonly loops: number;
   readonly polygons: number;
@@ -538,6 +486,23 @@ export interface BlenderClipTrack extends BlenderClipCurve {
   readonly index: number;
 }
 
+/** One sampled column of a {@link BlenderClipBone}: `count` samples (one when it never changes),
+ *  base64 Float32. */
+export interface BlenderClipColumn {
+  readonly count: number;
+  readonly base64: string;
+}
+
+/** One bone of an action as three.js plays it: its local position, quaternion (x, y, z, w) and
+ *  scale per integer frame of the clip's range, and the frames it is keyed on. */
+export interface BlenderClipBone {
+  readonly bone: string;
+  readonly keys: readonly number[];
+  readonly position: BlenderClipColumn;
+  readonly quaternion: BlenderClipColumn;
+  readonly scale: BlenderClipColumn;
+}
+
 /** An F-Curve's body: everything Blender evaluates it from, wherever it lives. */
 export interface BlenderClipCurve {
   /** `FCurve.extrapolation`: `CONSTANT` or `LINEAR`. */
@@ -604,13 +569,9 @@ export interface BlenderActionClip {
   readonly slot: string | null;
   /** The action's object slots: at most one means every armature reads the same curves. */
   readonly objectSlots?: number;
-  /** `layered` at this pin — an `Action` has no `.fcurves`; they live at
-   *  `layers[0].strips[0].channelbags[0].fcurves`. `legacy` is the branch for
-   *  a build where the old attribute is still there. */
-  readonly channels?: string;
   /** The scene's own name — the Timeline's one write addresses
    *  `bpy.data.scenes["<name>"]`, because an RNA path starts at `bpy.data.`. */
-  readonly scene?: string;
+  readonly scene: string;
   readonly frameCurrent: number;
   readonly frameStart: number;
   readonly frameEnd: number;
@@ -621,7 +582,7 @@ export interface BlenderActionClip {
   readonly keyframes: readonly BlenderClipKeyColumn[];
   /** Every animated object in the view layer, for the summary row's
    *  selection filter. Always present; empty for a file with no animation. */
-  readonly summary?: readonly BlenderClipSummaryObject[];
+  readonly summary: readonly BlenderClipSummaryObject[];
   readonly tracks: readonly BlenderClipTrack[];
   readonly clipStart?: number;
   readonly clipEnd?: number;
@@ -629,14 +590,170 @@ export interface BlenderActionClip {
    *  modifier repeats into. */
   readonly keysStart?: number | null;
   readonly keysEnd?: number | null;
-  /** Blender repeats it past its range (Cycles modifiers on its curves, or `use_cyclic`). */
-  readonly cyclic?: boolean;
   readonly duration?: number;
-  readonly sampled?: number;
   /** Bones the action names that the armature does not have. */
   readonly unplayedBones?: readonly string[];
-  /** What the action keys besides bone channels (the object's own transform, a property),
-   *  which plays only in Blender. */
+  /** THE ACTION AS THREE.JS PLAYS IT (`session.py`'s `_three_bones`): per bone it keys, the bone's
+   *  local transform at every integer frame from `clipStart` to `clipEnd`, sampled by Blender. */
+  readonly bones?: readonly BlenderClipBone[];
+  /** Keyed channels the three.js animation preview does not play (a custom property or delta
+   *  transform). Object transforms are handled by {@link BlenderSceneMovie}. */
   readonly unsupported?: readonly string[];
   readonly reason?: string;
 }
+
+/** One object the scene's movie moves or looks through. */
+export interface BlenderMovieObject {
+  readonly name: string;
+  readonly type: string;
+  readonly parent: string | null;
+  /** `Object.rotation_mode`. */
+  readonly rotationMode: string;
+  /** Its own channels as the file holds them, which a component no action keys keeps. */
+  readonly channels: {
+    readonly location: readonly number[];
+    readonly rotation_quaternion: readonly number[];
+    readonly rotation_euler: readonly number[];
+    readonly rotation_axis_angle: readonly number[];
+    readonly scale: readonly number[];
+  };
+  /** Its delta transform (the rotation as a quaternion w, x, y, z), applied as `BKE_object_to_mat4`. */
+  readonly delta: { readonly location: readonly number[]; readonly rotation: readonly number[]; readonly scale: readonly number[] };
+  /** What places its basis in its parent's space: `matrix_parent_inverse` (identity without a parent). */
+  readonly pre: readonly (readonly number[])[];
+  readonly constraints: readonly {
+    readonly name: string;
+    readonly type: string;
+    readonly enabled: boolean;
+    readonly influence: number;
+    readonly target?: string;
+    readonly trackAxis?: string;
+    readonly upAxis?: string;
+    readonly useTargetZ?: boolean;
+  }[];
+  /** A camera's projection as held by the file, with sampled columns when keyed. */
+  readonly camera?: {
+    readonly type: string;
+    readonly lens: number;
+    readonly sensor_width: number;
+    readonly sensor_height: number;
+    readonly sensor_fit: string;
+    readonly ortho_scale: number;
+    readonly clip_start: number;
+    readonly clip_end: number;
+    readonly shift_x: number;
+    readonly shift_y: number;
+    /** Disabled in renders: Blender's marker cuts skip it. */
+    readonly renderHidden: boolean;
+    /** Its projection at every scene frame, sampled by Blender (present when keyed). */
+    readonly sampled?: { readonly start: number; readonly end: number } & Readonly<Record<
+      'lens' | 'sensor_width' | 'sensor_height' | 'ortho_scale' | 'shift_x' | 'shift_y' | 'clip_start' | 'clip_end', BlenderClipColumn>>;
+  };
+  /** Its local transform at every scene frame, sampled by Blender (`session.py`'s `_sample_object`):
+   *  `hidden` (1 hidden) when its render visibility is keyed. Present when it is animated. */
+  readonly sampled?: {
+    readonly start: number;
+    readonly end: number;
+    readonly position: BlenderClipColumn;
+    readonly quaternion: BlenderClipColumn;
+    readonly scale: BlenderClipColumn;
+    readonly hidden?: BlenderClipColumn;
+  };
+  /** Animation behavior the three.js preview does not play. */
+  readonly unsupported?: readonly string[];
+}
+
+/** A sound's file: a path Blender holds it at (the project's, absolute), or a packed sound's copy
+ *  beside the session, read back through the session's files. */
+export type BlenderSoundFile = { readonly path: string } | { readonly packed: string };
+
+/**
+ * THE SCENE'S SOUND, DESCRIBED FOR THE PAGE TO MIX (`session.py`'s `rna_sound_scene`), over the
+ * movie's frames `first` to `last`. Every per-frame column holds `count` values (stride 1, or 3 for a
+ * point), or one when it never changes.
+ */
+export interface BlenderSoundScene {
+  readonly fps: number;
+  readonly first: number;
+  readonly last: number;
+  readonly count: number;
+  /** The scene's own volume, and whether its sequencer sound is muted (`Scene.use_audio`). */
+  readonly volume: number;
+  readonly muted: boolean;
+  /** `Scene.audio_distance_model`: `NONE`, `INVERSE`, `INVERSE_CLAMPED`, `LINEAR`, `LINEAR_CLAMPED`, `EXPONENT`, `EXPONENT_CLAMPED`. */
+  readonly distanceModel: string;
+  readonly strips: readonly {
+    readonly name: string;
+    readonly file: BlenderSoundFile | null;
+    readonly mono: boolean;
+    readonly muted: boolean;
+    /** The frame the sound's own start sits at, and the frames the strip is cut to (end exclusive). */
+    readonly start: number;
+    readonly finalStart: number;
+    readonly finalEnd: number;
+    readonly speed: number;
+    readonly volume: BlenderClipColumn;
+    readonly pan: BlenderClipColumn;
+  }[];
+  readonly speakers: readonly {
+    readonly name: string;
+    readonly file: BlenderSoundFile | null;
+    readonly muted: boolean;
+    /** The frames its NLA sound strips start on. */
+    readonly starts: readonly number[];
+    readonly volume: BlenderClipColumn;
+    readonly volumeMin: number;
+    readonly volumeMax: number;
+    readonly attenuation: number;
+    readonly distanceReference: number;
+    readonly distanceMax: number;
+    /** Radians. */
+    readonly coneInner: number;
+    readonly coneOuter: number;
+    readonly coneOuterVolume: number;
+    /** Blender world space, per frame (stride 3); facing is the speaker's -Z. */
+    readonly position: BlenderClipColumn;
+    readonly facing: BlenderClipColumn;
+  }[];
+  /** The scene camera's place and axes per frame (stride 3), the speakers' listener; null without speakers. */
+  readonly listener: { readonly position: BlenderClipColumn; readonly forward: BlenderClipColumn; readonly up: BlenderClipColumn } | null;
+}
+
+/**
+ * The scene animation from `session.py`'s `rna_scene_movie`, consumed by the Timeline preview
+ * and glTF export.
+ */
+export interface BlenderSceneMovie {
+  readonly scene: {
+    readonly name: string;
+    readonly start: number;
+    readonly end: number;
+    readonly fps: number;
+    readonly current: number;
+    readonly camera: string | null;
+  };
+  /** The Timeline's markers by frame, each with the camera it cuts to (`TimelineMarker.camera`). */
+  readonly markers: readonly { readonly name: string; readonly frame: number; readonly camera: string | null }[];
+  readonly objects: readonly BlenderMovieObject[];
+  /** MATERIALS whose Principled inputs a curve keys (`_sample_material`): base colour, emission (colour times strength) and alpha at every scene frame, each
+   *  present only when keyed. */
+  readonly materials: readonly {
+    readonly name: string;
+    readonly start: number;
+    readonly end: number;
+    readonly color?: BlenderClipColumn;
+    readonly emissive?: BlenderClipColumn;
+    readonly opacity?: BlenderClipColumn;
+  }[];
+  /** MESHES whose shape keys a curve keys (`_sample_shapes`): each keyed key's offset at
+   *  every vertex (from the key it is relative to), its value at every scene frame and the value the
+   *  presented geometry already holds; `mapped` false when modifiers change the mesh's vertices. */
+  readonly shapes: readonly {
+    readonly object: string;
+    readonly start: number;
+    readonly end: number;
+    readonly vertices: number;
+    readonly mapped: boolean;
+    readonly keys: readonly { readonly name: string; readonly delta: BlenderClipColumn; readonly values: BlenderClipColumn; readonly current: number }[];
+  }[];
+}