@volter/editor-blender 0.1.135 → 0.1.137

package/contributions/blender-runtime-skin.ts

@@ -1,5 +1,5 @@
 /**
- * THE SKIN AND THE CLIP — three.js PLAYS Blender's animation; Blender holds it
+ * THE TIMELINE'S ANIMATION — three.js PLAYS Blender's animation; Blender holds it
  * as DATA (owner rule, 2026-09-20: "we visualize with three.js, not Blender").
  *
  * ## Why this exists at all
@@ -8,11 +8,15 @@
  * it and re-exports the mesh columns. That is the wrong architecture: it puts
  * a WASM depsgraph evaluation and a full geometry round trip between the
  * person's pointer and the picture, and it moves `scene.frame_current` sixty
- * times a second under every bpy reader in the session. So instead the tab
- * reads the rig ONCE (`session.py`'s `rna_rig`) and the action ONCE
- * (`rna_action_clip`), builds a real `THREE.SkinnedMesh` + `Skeleton` +
- * `AnimationMixer`, and every scrub and every played frame after that costs
- * ZERO calls into Blender.
+ * times a second under every bpy reader in the session. So the skin travels in the
+ * frame itself: the export door ships each Armature-deformed mesh's weights per
+ * exported vertex (`bpy_web_export.cc` `write_skin`), the frame names every bone's
+ * rest, channels, constraints and pose and each armature's NLA stack, and the presenter
+ * builds the skeletons (`blender-runtime-skeleton.ts`). This director poses EVERY armature
+ * at the scene frame with Blender's own evaluation (`blender-pose.ts`): its NLA tracks and
+ * active action, blended as Blender blends them, and its Damped Track constraints. Every scrub
+ * and every played frame costs ZERO calls into Blender; an action is baked again exactly when
+ * the frame says its revision moved.
  *
  * ## The bind pose is the EXPORT pose, and that is the whole trick
  *
@@ -24,227 +28,60 @@
  * own evaluation of the same skin over the same columns. Nothing has to move
  * Blender's frame, ever.
  *
- * ## What that costs, stated rather than implied
+ * ## The fidelity check, and what is not played
  *
- * While a clip plays, the picture is three.js's skinning of the EXPORT-FRAME
- * mesh. Anything else Blender's depsgraph would do per frame — shape keys, a
- * Displace or Cast or Cloth modifier reading the frame, a driver on geometry —
- * does NOT follow the mixer. The Timeline's status line names any such
- * modifier on the played object rather than showing a confident picture of the
- * wrong thing (`modifiersNotPlayed`). A bone whose pose is a CONSTRAINT's
- * rather than its channels' is named the same way, because the clip is derived
- * from the F-Curves alone.
+ * At Blender's own frame, standing still, the picture IS Blender's pose (the frame's), and the
+ * evaluator's answer for that frame is compared with it bone by bone (`poseDivergence`). A bone
+ * further off than a tenth of a degree is said in the console with what would explain it, so a
+ * difference between this Timeline (and a game, which uses the same evaluator) and Blender is
+ * never silent. What the evaluator does not play — a constraint other than Damped Track, a
+ * driver, non-default parenting — is named once as well. Anything Blender's depsgraph does to
+ * GEOMETRY per frame (shape keys, a Displace or Cloth modifier) does not follow the bones.
  */
 
-import type {
-  BlenderActionClip,
-  BlenderRig,
-  BlenderRigBinding,
-} from '@volter/blender-engine/browser/rna';
-import type { StageTransportHandle } from '@volter/editor-sdk/host';
-import * as THREE from 'three';
+import type { BlenderActionClip } from '@volter/blender-engine/browser/rna';
+import type { BlenderArmature } from '@volter/blender-engine/browser/three/blender-runtime-armature';
+import type { BlenderRuntimeView } from '@volter/blender-engine/browser/three/blender-runtime-view';
+import { editorHost, type StageTransportHandle } from '@volter/editor-sdk/host';
 import { blenderRnaSet } from '../host/blender-runtime-host';
+import { actionLayer, ArmaturePose, nlaLayers, poseClip, poseDivergence, type PoseClip, type PoseLayer } from './blender-pose';
 
-/** Base64 → the typed array it holds. The same three lines every payload in
- *  this package decodes with (`blender-uv-geometry.ts`'s `uvBytes`); kept
- *  local because this module is in the presenter's closure and that one is in
- *  the UV view's. */
-function bytesOf(base64: string): Uint8Array {
-  const binary = atob(base64);
-  const out = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
-  return out;
-}
-function float32Of(base64: string): Float32Array {
-  const bytes = bytesOf(base64);
-  return new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 2);
-}
-function uint16Of(base64: string): Uint16Array {
-  const bytes = bytesOf(base64);
-  return new Uint16Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 1);
-}
-
-/** A row-major four-row matrix, as every matrix in the RNA doors crosses —
- *  `THREE.Matrix4.set` takes its arguments row-major too, so this is a spread
- *  and not a transpose. */
-function matrixOf(rows: readonly (readonly [number, number, number, number])[]): THREE.Matrix4 {
-  return new THREE.Matrix4().set(...(rows.flat() as unknown as Parameters<THREE.Matrix4['set']>));
-}
-
-/** What the presenter needs of the view to swap a Mesh for a SkinnedMesh and
- *  to hang bones off an armature. Deliberately three methods and not the view:
- *  this module has no business knowing about frames, materials or overlays. */
-export interface SkinPresentation {
-  /** The presented `Object3D` for a Blender object NAME, or null. */
-  objectForBlenderName(name: string): THREE.Object3D | null;
-  /** Put `next` where `previous` was — same parent, same place in the object
-   *  table — so the next frame's reuse check finds it. */
-  replacePresentedObject(previous: THREE.Object3D, next: THREE.Object3D): void;
-  /** The presented root, for the one forced `updateMatrixWorld` a bind needs. */
-  root: THREE.Object3D;
+/** How the director reads the engine: the Timeline's subject (its keys, the scene's range) and
+ *  one action baked for one armature. */
+export interface SkinReader {
+  clip(armature: string): Promise<BlenderActionClip | null>;
+  bake(armature: string, action: string): Promise<BlenderActionClip | null>;
 }
 
-export interface BoundRig {
-  /** The MESH object's Blender name. */
-  readonly object: string;
-  readonly armature: string;
-  readonly mesh: THREE.SkinnedMesh;
-  readonly boneRoot: THREE.Group;
-  readonly bones: readonly THREE.Bone[];
-  readonly skeleton: THREE.Skeleton;
-  /** `scene.frame_current` the binding was read at. */
-  readonly frame: number;
-  /** The identity a re-read is compared against: rebuilding a skeleton on
-   *  every present would throw away the mixer's time sixty times a minute. */
-  readonly signature: string;
-}
-
-function rigSignature(rig: BlenderRigBinding, frame: number): string {
-  return [rig.object, rig.mesh, rig.armature, rig.vertexCount, rig.bones.length, frame].join('|');
+/** An armature's layers at a scene frame: its NLA, then its active action over them. */
+export function sceneLayers(armature: BlenderArmature, frame: number,
+  clips: (action: string) => PoseClip | null | undefined): { layers: PoseLayer[]; waiting: boolean; skipped: string[] } {
+  const stack = nlaLayers(armature.animation, frame, clips);
+  const action = armature.action ?? null;
+  if (action) {
+    const clip = clips(action);
+    if (clip === undefined) stack.waiting = true;
+    const layer = clip ? actionLayer(armature.animation, clip, frame, stack.evaluated) : null;
+    if (layer) stack.layers.push(layer);
+  }
+  return stack;
 }
 
-/**
- * A BLENDER ACTION'S BAKED TRACKS as three.js keyframe tracks over `bones` (by Blender's bone
- * name), addressed by bone UUID because three's track-name grammar splits on `.` and `hand.L`
- * is an ordinary bone name. A track for a bone this binding lacks is named in `warnings`.
- */
-export function clipTracks(clip: BlenderActionClip, bones: ReadonlyMap<string, THREE.Bone>, warnings: string[]): THREE.KeyframeTrack[] {
-  const tracks: THREE.KeyframeTrack[] = [];
-  const missing = new Set<string>();
-  for (const track of clip.tracks) {
-    const bone = bones.get(track.bone);
-    if (!bone) {
-      missing.add(track.bone);
-      continue;
-    }
-    const times = float32Of(track.timeBase64);
-    const values = float32Of(track.valueBase64);
-    const path = `${bone.uuid}.${track.property}`;
-    tracks.push(
-      track.property === 'quaternion'
-        ? new THREE.QuaternionKeyframeTrack(path, Array.from(times), Array.from(values))
-        : new THREE.VectorKeyframeTrack(path, Array.from(times), Array.from(values)),
-    );
-  }
-  if (missing.size) warnings.push(`${clip.action} animates ${[...missing].join(', ')}, which this binding has no bone for.`);
-  return tracks;
+/** What to do about what plays only in Blender, by kind. */
+export function remedy(unsupported: readonly string[]): string {
+  const out: string[] = [];
+  if (unsupported.some((thing) => thing.includes(' constraint ') || thing.includes('drivers')))
+    out.push('Bake a constraint or driver into the action (Pose ▸ Animation ▸ Bake Action, Visual Keying), or aim with a Damped Track.');
+  if (unsupported.some((thing) => thing.includes('curves on ')))
+    out.push("Key the motion on a bone (the root bone) instead of the armature object, or move the object from the game.");
+  if (unsupported.some((thing) => thing.includes('interpolation') || thing.includes(' modifier')))
+    out.push('Use Bezier, Linear or Constant keys and the Cycles modifier only, or bake the curves (Key ▸ Bake Keyframes).');
+  return out.length ? ` ${out.join(' ')}` : '';
 }
 
-/**
- * BIND ONE RIGGED MESH of a presentation: its drawn mesh becomes a `THREE.SkinnedMesh` over a
- * `Skeleton` built from Blender's bones, in the pose the columns were exported at (so the bind
- * is an identity there). Shared by the Timeline's director and Play's copy (`blender-play-skin.ts`).
- */
-export function bindRig(
-  presentation: SkinPresentation,
-  rig: BlenderRigBinding,
-  frame: number,
-  warnings: string[],
-): BoundRig | null {
-  const meshObject = presentation.objectForBlenderName(rig.object ?? '');
-  const armatureObject = presentation.objectForBlenderName(rig.armature ?? '');
-  if (!meshObject || !armatureObject) return null;
-  const source = meshObject as THREE.Mesh;
-  const geometry = source.geometry;
-  if (!geometry) return null;
-  const blenderVertex = geometry.getAttribute('blenderVertex');
-  if (!blenderVertex) {
-    warnings.push(
-      `"${rig.object}" cannot be skinned: its presented geometry carries no \`blenderVertex\` attribute, so a per-Blender-vertex weight cannot be expanded onto its drawn vertices (presented as ${(meshObject as THREE.Object3D).type} with ${Object.keys(geometry.attributes).join(', ') || 'no attributes'}).`,
-    );
-    return null;
-  }
-  if (rig.vertexCount === 0) return null;
-  // THE COLUMNS AND THE BINDING MUST BE THE SAME MESH. `rna_rig` reads the
-  // ORIGINAL mesh's vertices (a deform layer is not geometry, so that is
-  // where the weights live); a generative modifier — Subdivision, Mirror,
-  // Array — makes the EVALUATED mesh the export door ships a different
-  // vertex set, and a skin bound across that mismatch would weight the wrong
-  // vertices. Named, never silently drawn.
-  let highest = 0;
-  for (let i = 0; i < blenderVertex.count; i++)
-    highest = Math.max(highest, blenderVertex.getX(i));
-  if (highest >= rig.vertexCount) {
-    warnings.push(
-      `"${rig.object}" is not skinned here: its presented geometry references Blender vertex ${highest} while the mesh declares ${rig.vertexCount}, which is a generative modifier (Subdivision, Mirror, Array…) between the two. Blender's own viewport shows the evaluated result; this presenter shows the exported columns unskinned.`,
-    );
-    return null;
-  }
-  const skinIndex = uint16Of(rig.skinIndexBase64 ?? '');
-  const skinWeight = float32Of(rig.skinWeightBase64 ?? '');
-  const drawn = blenderVertex.count;
-  const indices = new Uint16Array(drawn * 4);
-  const weights = new Float32Array(drawn * 4);
-  for (let i = 0; i < drawn; i++) {
-    const vertex = blenderVertex.getX(i);
-    for (let k = 0; k < 4; k++) {
-      indices[i * 4 + k] = skinIndex[vertex * 4 + k] ?? 0;
-      weights[i * 4 + k] = skinWeight[vertex * 4 + k] ?? 0;
-    }
-  }
-  geometry.setAttribute('skinIndex', new THREE.Uint16BufferAttribute(indices, 4));
-  geometry.setAttribute('skinWeight', new THREE.Float32BufferAttribute(weights, 4));
-
-  const boneRoot = new THREE.Group();
-  boneRoot.name = `${rig.armature}:bones`;
-  const bones: THREE.Bone[] = [];
-  const armatureSpace = rig.bones.map((bone) => matrixOf(bone.pose));
-  const indexByName = new Map(rig.bones.map((bone, index) => [bone.name, index]));
-  rig.bones.forEach((declared, index) => {
-    const bone = new THREE.Bone();
-    // THE NAME IS BLENDER'S, unsanitized, because a game reads it: the
-    // arena's `Player.tsx` finds its bones by Blender's own names. The CLIP
-    // therefore addresses bones by UUID rather than by name — three's
-    // `PropertyBinding` track-name grammar splits on `.`, and Blender's
-    // `hand.L` is an ordinary bone name.
-    bone.name = declared.name;
-    bones.push(bone);
-    const parentIndex = declared.parent === null ? undefined : indexByName.get(declared.parent);
-    const local =
-      parentIndex === undefined
-        ? armatureSpace[index]!.clone()
-        : armatureSpace[parentIndex]!.clone().invert().multiply(armatureSpace[index]!);
-    local.decompose(bone.position, bone.quaternion, bone.scale);
-    (parentIndex === undefined ? boneRoot : bones[parentIndex]!).add(bone);
-  });
-  armatureObject.add(boneRoot);
-
-  const skinned = new THREE.SkinnedMesh(geometry, source.material);
-  skinned.name = source.name;
-  skinned.matrixAutoUpdate = false;
-  skinned.matrix.copy(source.matrix);
-  skinned.matrix.decompose(skinned.position, skinned.quaternion, skinned.scale);
-  skinned.userData = source.userData;
-  // A SKIN MOVES PAST ITS BIND BOUNDS. three computes a SkinnedMesh's
-  // bounding sphere from the bind pose, so a raised arm at frame 24 is
-  // culled while its bind-pose sphere is off screen — a picture that
-  // vanishes mid-scrub with no error anywhere.
-  skinned.frustumCulled = false;
-  presentation.replacePresentedObject(source, skinned);
-  // THE BIND IS TAKEN AFTER THE GRAPH STANDS, because both halves of it are
-  // WORLD matrices: `Skeleton`'s bone inverses are the bones' `matrixWorld`
-  // at this instant and `bindMatrix` is the mesh's.
-  presentation.root.updateMatrixWorld(true);
-  const skeleton = new THREE.Skeleton(bones);
-  skinned.bind(skeleton, skinned.matrixWorld.clone());
-  if (rig.constrainedBones?.length)
-    warnings.push(
-      `Bone constraints on ${rig.constrainedBones.join(', ')}: the clip is derived from the F-Curves alone, so those bones play their channels rather than Blender's solved pose.`,
-    );
-  if (rig.unmappedGroups?.length)
-    warnings.push(
-      `${rig.object} carries vertex groups no bone is named for (${rig.unmappedGroups.join(', ')}); they weight nothing here, exactly as they deform nothing in Blender.`,
-    );
-  return {
-    object: rig.object ?? '',
-    armature: rig.armature ?? '',
-    mesh: skinned,
-    boneRoot,
-    bones,
-    skeleton,
-    frame,
-    signature: rigSignature(rig, frame),
-  };
+/** True when an armature has anything to evaluate: an action, or NLA strips. */
+export function animated(armature: BlenderArmature): boolean {
+  return !!armature.action || !!armature.animation?.tracks.some((track) => track.strips.length);
 }
 
 /**
@@ -255,21 +92,17 @@ export function bindRig(
  * copy of the playback state anywhere.
  */
 export class BlenderSkinDirector {
-  #rigs = new Map<string, BoundRig>();
-  /** Rigs that could not be bound, by mesh name, at the signature tried: not retried until the
-   *  rig changes (a generative modifier, no vertex map), so a settle does not re-read and re-warn. */
-  #unbindable = new Map<string, string>();
-
-  /** What could not be bound, keyed by the rig AND what is presented for its mesh: the fix for a
-   *  refusal (removing a generative modifier, showing a hidden object) changes the presentation,
-   *  not the rig, and must be retried. */
-  static #tried(presentation: SkinPresentation, mesh: string, signature: string): string {
-    const object = presentation.objectForBlenderName(mesh) as THREE.Mesh | null;
-    return `${signature}|${object?.uuid ?? 'absent'}|${object?.geometry?.uuid ?? 'none'}`;
-  }
-  #mixer: THREE.AnimationMixer | null = null;
-  #action: THREE.AnimationAction | null = null;
+  /** The presented view whose skeletons are posed (`sync`). */
+  #view: BlenderRuntimeView | null = null;
+  #reader: SkinReader | null = null;
+  /** The Timeline's subject: the armature its keys and header describe, and what its header was
+   *  read for. Read again only when that changes. */
+  #armature: string | null = null;
+  #clipKey: string | null = null;
   #clip: BlenderActionClip | null = null;
+  /** Each posed armature's evaluator, and every action baked for it, at the revision baked. */
+  #poses = new Map<string, ArmaturePose>();
+  #baked = new Map<string, { revision: number | null; clip: PoseClip | null | undefined }>();
   /** The frame the last SEEK asked for — see {@link frame}. */
   #seeked: number | null = null;
   /** The stage transport this skin is attached to, or null before `attachTo`.
@@ -279,6 +112,8 @@ export class BlenderSkinDirector {
   #listeners = new Set<() => void>();
   #version = 0;
   #warnings: string[] = [];
+  /** What was already said in the console, so each finding is said once. */
+  #said = new Set<string>();
   /** Engine calls this director has made, counted so a walk can prove that a
    *  scrub costs none (the acceptance the owner named). */
   #engineCalls = 0;
@@ -301,9 +136,8 @@ export class BlenderSkinDirector {
     for (const listener of [...this.#listeners]) listener();
   }
 
-  /** The clip's own facts plus the mixer's live time, expressed in BLENDER
-   *  FRAMES — which is the only number the Timeline draws, and the only one a
-   *  person or an agent ever names. */
+  /** The subject's facts plus the playhead, expressed in BLENDER FRAMES — which is the only
+   *  number the Timeline draws, and the only one a person or an agent ever names. */
   state(): {
     frame: number;
     start: number;
@@ -315,9 +149,8 @@ export class BlenderSkinDirector {
     bones: number;
     keyframes: readonly { frame: number; type: string; select: boolean }[];
     /** Every animated object's own columns plus its SELECTION — what the
-     *  summary row's `show_only_selected` filter chooses between. The mixer
-     *  never reads it: what plays is the bound action, filter or no filter,
-     *  exactly as in Blender. */
+     *  summary row's `show_only_selected` filter chooses between. What plays
+     *  is every armature's stack, filter or no filter, exactly as in Blender. */
     summary: readonly {
       object: string;
       action: string;
@@ -332,30 +165,27 @@ export class BlenderSkinDirector {
     engineCalls: number;
     /** BLENDER'S OWN `scene.frame_current`, as the clip door last read it —
      *  which is a different number from `frame` on purpose. `frame` is where
-     *  the person is looking (the mixer's); this is where bpy and the
-     *  Properties rail are. They agree after a pause or a scrub-end, and they
-     *  are deliberately allowed to differ in between. */
+     *  the person is looking; this is where bpy and the Properties rail are.
+     *  They agree after a pause or a scrub-end, and they are deliberately
+     *  allowed to differ in between. */
     blenderFrame: number | null;
   } {
     const clip = this.#clip;
-    const start = clip?.frameStart ?? 1;
-    const end = clip?.frameEnd ?? 250;
-    const fps = clip?.fps ?? 24;
     return {
       frame: this.frame(),
-      start,
-      end,
-      fps,
+      start: clip?.frameStart ?? 1,
+      end: clip?.frameEnd ?? 250,
+      fps: clip?.fps ?? 24,
       action: clip?.action ?? null,
       object: clip?.object ?? null,
       armature: clip?.armature ?? null,
-      bones: [...this.#rigs.values()].reduce((sum, rig) => sum + rig.bones.length, 0),
+      bones: this.#armature ? this.#view?.skeletons.rig(this.#armature)?.bones.size ?? 0 : 0,
       keyframes: clip?.keyframes ?? [],
       summary: clip?.summary ?? [],
       clipStart: clip?.clipStart ?? null,
       clipEnd: clip?.clipEnd ?? null,
       tracks: clip?.tracks.length ?? 0,
-      bound: [...this.#rigs.keys()],
+      bound: [...this.#poses.keys()],
       warnings: this.#warnings,
       engineCalls: this.#engineCalls,
       blenderFrame: clip?.frameCurrent ?? null,
@@ -368,193 +198,167 @@ export class BlenderSkinDirector {
     return this.#clip ? this.frame() : null;
   }
 
-  /** The mixer's time as a Blender frame. With no clip the scene's own current
-   *  frame stands, which is Blender's answer for a file with no animation. */
+  /** The frame on screen: the last seek's, else Blender's own. */
   frame(): number {
-    const clip = this.#clip;
-    if (this.#seeked !== null) return this.#seeked;
-    if (!clip || !this.#action || clip.clipStart === undefined) return clip?.frameCurrent ?? 1;
-    // A SEEK'S OWN ANSWER, while one is standing. `LoopRepeat` wraps
-    // `action.time` into `[0, duration)`, so a seek to the LAST frame lands on
-    // `time === duration` and reads back as the FIRST — measured on the first
-    // walk, where `jump-end` answered frame 1 over a frame-48 pose. The
-    // wrapping is right for playback and wrong for a question, so a standing
-    // seek answers with the frame it was given and the play tick clears it.
-    // THE ACTION'S TIME, NOT THE MIXER'S, and the difference is the whole of
-    // looping: `AnimationMixer.time` is monotonic and never wraps, while
-    // `AnimationAction.time` is wrapped into `[0, duration]` by `LoopRepeat`.
-    // Measured on the first walk: two seconds of playback over a 47-frame clip
-    // read as frame 63.5 off the mixer, where the picture was correctly back
-    // near the start.
-    return clip.clipStart + this.#action.time * clip.fps;
+    return this.#seeked ?? this.#clip?.frameCurrent ?? 1;
   }
 
   /** Blender's scene clock exists even when the scene has no action. */
-  /** Whether a bind would change anything: nothing is bound yet, or a bound mesh is no longer the
-   *  object presented for its name (the presenter replaced it with a new draw). Lets the model
-   *  skip the rig read on the edits that touch no rig. */
-  stale(presentation: SkinPresentation): boolean {
-    // An unbindable rig whose presentation changed since it was tried is worth trying again.
-    for (const [mesh, tried] of this.#unbindable) {
-      const signature = tried.split('|').slice(0, -2).join('|');
-      if (BlenderSkinDirector.#tried(presentation, mesh, signature) !== tried) return true;
-    }
-    if (this.#rigs.size === 0) return this.#unbindable.size === 0;
-    for (const rig of this.#rigs.values()) {
-      if (presentation.objectForBlenderName(rig.object) !== rig.mesh) return true;
-      // A redraw that kept the object but replaced its geometry (a weight or mesh edit with the same
-      // vertex count) leaves the skinned mesh without its skin attributes.
-      if (!rig.mesh.geometry.getAttribute('skinIndex')) return true;
-    }
-    return false;
-  }
-
   get playable(): boolean {
     return this.#clip !== null && this.#transport !== null;
   }
 
-  // ------------------------------------------------------------ the binding
+  // ------------------------------------------------------------ the frame
 
   /**
-   * Bind every rigged mesh the frame carries, and load the active action.
-   *
-   * IDEMPOTENT BY SIGNATURE: a rig whose mesh, armature, vertex count, bone
-   * count and export frame are unchanged is left exactly as it is, mixer time
-   * included. That is what lets the presenter call this after EVERY frame
-   * without the picture jumping back to the bind pose each time something
-   * unrelated moved.
+   * FOLLOW THE PRESENTED FRAME. Every armature the frame names is posed; the Timeline's subject is
+   * the active object's armature (itself, or the one its skin is bound to), else the one armature
+   * that has an action, and its header is read through the clip door when the frame says
+   * something about it moved. Actions are baked once per revision, the first time a frame needs
+   * them. Otherwise this costs nothing, which is what lets the model call it after every present.
    */
-  async bind(
-    presentation: SkinPresentation,
-    read: {
-      rig(): Promise<BlenderRig | null>;
-      clip(): Promise<BlenderActionClip | null>;
-    },
-  ): Promise<void> {
-    this.#engineCalls++;
-    const answer = await read.rig();
-    if (!answer) return;
-    const warnings: string[] = [];
-    const wanted = new Set<string>();
-    let changed = false;
-    for (const rig of answer.rigs) {
-      if (!rig.object || !rig.armature || !rig.skinIndexBase64 || !rig.skinWeightBase64) {
-        if (rig.reason) warnings.push(rig.reason);
+  async sync(view: BlenderRuntimeView, read: SkinReader): Promise<void> {
+    this.#view = view;
+    this.#reader = read;
+    const facts = view.animationFacts();
+    const names = Object.keys(facts.armatures);
+    const active = facts.active;
+    const armature = active && facts.armatures[active] ? active
+      : (active ? facts.skinArmature(active) : null)
+        ?? (names.filter((name) => facts.armatures[name]!.action).length === 1
+          ? names.find((name) => facts.armatures[name]!.action)! : null);
+    // EVERY ARMATURE'S EVALUATOR, over the rig the presenter holds for it now.
+    for (const [name, pose] of [...this.#poses])
+      if (!facts.armatures[name] || view.skeletons.rig(name) !== pose.rig) this.#poses.delete(name);
+    for (const [name, entry] of Object.entries(facts.armatures)) {
+      const rig = view.skeletons.rig(name);
+      if (!rig || !animated(entry)) {
+        this.#poses.delete(name);
         continue;
       }
-      wanted.add(rig.object);
-      const signature = rigSignature(rig, answer.frame);
-      const held = this.#rigs.get(rig.object);
-      // Unchanged only while what it bound is still what is presented, skinned: a redraw that
-      // replaced the object or its geometry (same vertex count, same signature) is bound again.
-      if (held?.signature === signature && presentation.objectForBlenderName(rig.object) === held.mesh
-        && held.mesh.geometry.getAttribute('skinIndex')) continue;
-      const tried = BlenderSkinDirector.#tried(presentation, rig.object, signature);
-      if (this.#unbindable.get(rig.object) === tried) continue;
-      const bound = this.#bindOne(presentation, rig, answer.frame, warnings);
-      if (!bound) {
-        this.#unbindable.set(rig.object, tried);
-        if (held) {
-          held.skeleton.dispose();
-          held.boneRoot.removeFromParent();
-          // A skinned mesh still presented with no skeleton would hold its last pose; it draws as
-          // the plain mesh it is again.
-          if (presentation.objectForBlenderName(rig.object) === held.mesh) {
-            const plain = new THREE.Mesh(held.mesh.geometry, held.mesh.material);
-            plain.name = held.mesh.name;
-            plain.matrixAutoUpdate = false;
-            plain.matrix.copy(held.mesh.matrix);
-            plain.matrix.decompose(plain.position, plain.quaternion, plain.scale);
-            plain.userData = held.mesh.userData;
-            presentation.replacePresentedObject(held.mesh, plain);
-          }
-          this.#rigs.delete(rig.object);
-          changed = true;
-        }
+      let pose = this.#poses.get(name);
+      if (!pose) this.#poses.set(name, pose = new ArmaturePose(rig));
+      pose.facts(entry);
+    }
+    // A BAKE IS GOOD FOR ITS ACTION'S REVISION; a new revision bakes it again when next needed.
+    for (const [key, entry] of [...this.#baked]) {
+      const action = key.slice(key.indexOf('\u0000') + 1);
+      if ((facts.actions[action] ?? null) !== entry.revision) this.#baked.delete(key);
+    }
+    const action = armature ? facts.armatures[armature]?.action ?? null : null;
+    const key = JSON.stringify([armature, action, action ? facts.actions[action] ?? null : null, facts.clock, facts.frame]);
+    if (key !== this.#clipKey) {
+      this.#clipKey = key;
+      this.#armature = armature;
+      let clip: BlenderActionClip | null = null;
+      if (armature) {
+        this.#engineCalls++;
+        clip = await read.clip(armature);
+        if (clip?.action && clip.armature) this.#baked.set(`${clip.armature}\u0000${clip.action}`, { revision: facts.actions[clip.action] ?? null, clip: poseClip(clip) });
       }
-      if (bound) {
-        this.#unbindable.delete(rig.object);
-        held?.skeleton.dispose();
-        held?.boneRoot.removeFromParent();
-        this.#rigs.set(rig.object, bound);
-        changed = true;
+      const previous = this.#clip;
+      const rangeChanged = clip?.frameStart !== previous?.frameStart ||
+        clip?.frameEnd !== previous?.frameEnd || clip?.fps !== previous?.fps;
+      this.#clip = clip ?? null;
+      if (!clip || clip.scene !== previous?.scene) this.#seeked = null;
+      const activeSubject = this.#transport?.snapshot().activeSubject;
+      if (rangeChanged && activeSubject) this.#transport?.setActiveSubject(activeSubject);
+      const playing = this.#transport?.snapshot().playbackState === 'playing';
+      if (clip && !playing) {
+        this.#seeked = null;
+        if (this.#transport && clip.fps > 0) this.#transport.seek(clip.frameCurrent / clip.fps);
       }
     }
-    for (const [name, rig] of [...this.#rigs])
-      if (!wanted.has(name)) {
-        rig.skeleton.dispose();
-        rig.boneRoot.removeFromParent();
-        this.#rigs.delete(name);
-        changed = true;
-      }
+    this.#pose();
+    this.#publish();
+  }
+
+  /** One action of one armature: baked, or being baked now (once), or null when it plays nothing. */
+  #clipOf(armature: string, action: string): PoseClip | null | undefined {
+    const key = `${armature}\u0000${action}`;
+    const held = this.#baked.get(key);
+    if (held) return held.clip;
+    const reader = this.#reader;
+    const revision = this.#view?.animationFacts().actions[action] ?? null;
+    if (!reader) return null;
+    const entry: { revision: number | null; clip: PoseClip | null | undefined } = { revision, clip: undefined };
+    this.#baked.set(key, entry);
     this.#engineCalls++;
-    const clip = await read.clip();
-    const previous = this.#clip;
-    const rangeChanged = clip?.frameStart !== previous?.frameStart ||
-      clip?.frameEnd !== previous?.frameEnd || clip?.fps !== previous?.fps;
-    const movedAction =
-      clip?.action !== previous?.action ||
-      clip?.tracks.length !== previous?.tracks.length ||
-      clip?.clipStart !== previous?.clipStart ||
-      clip?.clipEnd !== previous?.clipEnd;
-    this.#clip = clip ?? null;
-    if (!clip || clip.scene !== previous?.scene) this.#seeked = null;
-    if (clip?.reason) warnings.push(clip.reason);
-    if (clip && (movedAction || changed)) this.#loadClip(presentation, clip, warnings);
-    // The subject can attach before the asynchronous scene read arrives.
-    // Refresh its clock range through the transport's own subject door.
-    const activeSubject = this.#transport?.snapshot().activeSubject;
-    if (rangeChanged && activeSubject) this.#transport?.setActiveSubject(activeSubject);
-    // BLENDER'S OWN FRAME RE-SYNCS THE PLAYHEAD. An agent that set
-    // `scene.frame_current` in bpy has said where it wants to be, and a
-    // present is how we hear about it; while the transport is PLAYING it would
-    // be the Timeline arguing with itself, so it is honoured only at rest.
+    void reader.bake(armature, action).then((baked) => {
+      entry.clip = baked ? poseClip(baked) : null;
+      if (this.#baked.get(key) !== entry) return;
+      this.#pose();
+      this.#publish();
+    }, (error: unknown) => {
+      entry.clip = null;
+      this.#say(`bake:${key}`, `${armature} / ${action} could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    });
+    return undefined;
+  }
+
+  /**
+   * POSE EVERY ARMATURE AT THE FRAME ON SCREEN. At Blender's own frame, standing still, the bones
+   * take Blender's pose (the frame's, exact) and the evaluator's answer is checked against it;
+   * anywhere else they take the evaluator's.
+   */
+  #pose(): void {
+    const view = this.#view;
+    if (!view) return;
+    const facts = view.animationFacts();
+    const frame = this.frame();
+    // BLENDER'S OWN FRAME is the one the presented pose was evaluated at, not the bookmark: a pause
+    // writes the bookmark first and the frame evaluated there arrives after.
+    const atBlender = frame === facts.frame;
     const playing = this.#transport?.snapshot().playbackState === 'playing';
-    if (clip && !playing && (rangeChanged || previous?.frameCurrent !== clip.frameCurrent)) {
-      this.#seek(clip.frameCurrent);
-      // THE BOOKMARK READ, once per bind: the file says where it was left, and
-      // the transport is what everything else now asks.
-      if (this.#transport && clip.fps > 0) this.#transport.seek(clip.frameCurrent / clip.fps);
+    const warnings: string[] = this.#clip?.reason ? [this.#clip.reason] : [];
+    const world = { object: (name: string) => view.objectForBlenderName(name) };
+    for (const [name, pose] of this.#poses) {
+      const armature = facts.armatures[name];
+      if (!armature) continue;
+      const unsupported = [...pose.unsupported(), ...this.#clipsOf(name).flatMap((clip) => clip.unsupported)];
+      if (unsupported.length) {
+        const said = `${name} plays ${unsupported.join(', ')} only in Blender, not in the Timeline or a game.${remedy(unsupported)}`;
+        warnings.push(said);
+        this.#say(`unsupported:${name}:${unsupported.join('|')}`, said);
+      }
+      const stack = sceneLayers(armature, frame, (action) => this.#clipOf(name, action));
+      for (const skipped of stack.skipped) this.#say(`skipped:${name}:${skipped}`, `${name}: ${skipped} plays only in Blender, not in the Timeline or a game.`);
+      if (stack.waiting) continue;
+      if (atBlender && !playing) {
+        view.skeletons.restorePose(name);
+        pose.rig.object.updateMatrixWorld(true);
+        this.#check(name, pose, armature, stack.layers, world, unsupported);
+      } else {
+        pose.apply(stack.layers, world);
+      }
     }
     this.#warnings = warnings;
-    this.#publish();
   }
 
-  #bindOne(presentation: SkinPresentation, rig: BlenderRigBinding, frame: number, warnings: string[]): BoundRig | null {
-    return bindRig(presentation, rig, frame, warnings);
+  /** The clips baked so far for one armature. */
+  #clipsOf(armature: string): PoseClip[] {
+    const out: PoseClip[] = [];
+    for (const [key, entry] of this.#baked) if (key.startsWith(`${armature}`) && entry.clip) out.push(entry.clip);
+    return out;
   }
 
-  #loadClip(presentation: SkinPresentation, clip: BlenderActionClip, warnings: string[]): void {
-    this.#mixer?.stopAllAction();
-    this.#mixer = null;
-    this.#action = null;
-    if (!clip.tracks.length || clip.clipStart === undefined || clip.clipEnd === undefined) return;
-    const armature = clip.armature ? presentation.objectForBlenderName(clip.armature) : null;
-    if (!armature) return;
-    const byName = new Map<string, THREE.Bone>();
-    for (const rig of this.#rigs.values())
-      if (rig.armature === clip.armature) for (const bone of rig.bones) byName.set(bone.name, bone);
-    const tracks = clipTracks(clip, byName, warnings);
-    if (!tracks.length) return;
-    const duration = clip.duration ?? (clip.clipEnd - clip.clipStart) / clip.fps;
-    const mixer = new THREE.AnimationMixer(armature);
-    const action = mixer.clipAction(
-      new THREE.AnimationClip(clip.action ?? 'action', duration, tracks),
-    );
-    action.setLoop(THREE.LoopRepeat, Number.POSITIVE_INFINITY);
-    action.play();
-    this.#mixer = mixer;
-    this.#action = action;
-    // THE FRESH MIXER STARTS AT BLENDER'S OWN FRAME, not at zero, and that is
-    // the invariant this whole design rests on: the mesh columns were exported
-    // at `frameCurrent` and the skeleton was bound in that pose, so seeking
-    // anywhere else would make the first picture after a re-bind disagree with
-    // the geometry underneath it. Measured on the first walk: a pause wrote
-    // frame 16, the write presented, the present re-exported the mesh at 16
-    // and re-bound — and `setTime(0)` snapped the playhead back to frame 1
-    // over a frame-16 mesh.
-    this.#seek(clip.frameCurrent);
-    this.#refresh();
+  /** THE FIDELITY CHECK at Blender's own frame: the evaluator's pose against Blender's. */
+  #check(name: string, pose: ArmaturePose, armature: BlenderArmature, layers: readonly PoseLayer[],
+    world: { object(name: string): ReturnType<BlenderRuntimeView['objectForBlenderName']> }, unsupported: readonly string[]): void {
+    const off = poseDivergence(pose.apply(layers, world, false), armature);
+    if (!off) return;
+    const frame = this.#clip?.frameCurrent ?? this.frame();
+    const why = unsupported.length
+      ? `What Blender plays here and the evaluator does not: ${unsupported.join(', ')}.`
+      : 'Nothing the evaluator knows of explains it; this is a defect in the presenter, report it with the file.';
+    this.#say(`divergence:${name}:${frame}:${off.bone}:${Math.round(off.degrees)}`,
+      `${name} at frame ${frame}: bone "${off.bone}" is ${off.degrees.toFixed(1)}° and ${(off.offset * 100).toFixed(1)}% of its length off Blender's own pose, so the Timeline and a game show it differently from Blender. ${why}`);
+  }
+
+  #say(key: string, message: string): void {
+    if (this.#said.has(key)) return;
+    this.#said.add(key);
+    editorHost().console.warn(message, 'blender-animation');
   }
 
   // ------------------------------------------------------------ the playback
@@ -562,27 +366,8 @@ export class BlenderSkinDirector {
   #seek(frame: number): void {
     const clip = this.#clip;
     if (!clip) return;
-    const clamped = Math.min(clip.frameEnd, Math.max(clip.frameStart, frame));
-    this.#seeked = clamped;
-    // An action supplies a pose at this scene time; it does not own whether
-    // the scene clock can move. Empty/static scenes still play and scrub.
-    if (!this.#mixer || clip.clipStart === undefined || clip.clipEnd === undefined) return;
-    // The TIME is nudged inside the clip so the last frame evaluates as the
-    // last frame rather than wrapping to the first; the number REPORTED is the
-    // one asked for (see `frame`).
-    const duration = (clip.clipEnd - clip.clipStart) / clip.fps;
-    this.#mixer.setTime(Math.max(0, Math.min(duration - 1e-4, (clamped - clip.clipStart) / clip.fps)));
-    this.#refresh();
-  }
-
-  /** The bones moved; make the world matrices agree before the stage's next
-   *  render reads them. A `Bone` keeps `matrixAutoUpdate`, so this is a forced
-   *  pass over a handful of nodes rather than a recomposition of the scene. */
-  #refresh(): void {
-    for (const rig of this.#rigs.values()) {
-      rig.boneRoot.updateMatrixWorld(true);
-      rig.skeleton.update();
-    }
+    this.#seeked = Math.min(clip.frameEnd, Math.max(clip.frameStart, frame));
+    this.#pose();
   }
 
   /** The scene's name, for the one address the Timeline writes to. */
@@ -685,16 +470,13 @@ export class BlenderSkinDirector {
 
   dispose(): void {
     this.#detach?.();
-    this.#mixer?.stopAllAction();
-    this.#mixer = null;
-    this.#action = null;
     this.#clip = null;
     this.#seeked = null;
-    for (const rig of this.#rigs.values()) {
-      rig.skeleton.dispose();
-      rig.boneRoot.removeFromParent();
-    }
-    this.#rigs.clear();
+    for (const name of this.#poses.keys()) this.#view?.skeletons.restorePose(name);
+    this.#poses.clear();
+    this.#baked.clear();
+    this.#armature = null;
+    this.#clipKey = null;
   }
 }