@volter/editor-blender 0.1.150 → 0.1.151

package/contributions/blender-pose.ts

@@ -1,25 +1,16 @@
 /**
- * BLENDER'S POSE, EVALUATED ON THE PRESENTER'S BONES. One evaluator, used by the Timeline
- * (`blender-runtime-skin.ts`) and by a game (`blender-play-skin.ts`), so the two can never disagree
- * with each other, and both follow what Blender itself does:
+ * THE NLA'S TIMING: which strip of each track a scene frame falls on, the action frame that strip
+ * shows, its influence, and where the active action is placed over the tracks, for the Timeline
+ * (`blender-runtime-skin.ts`), following what Blender itself does:
  *
  * - THE STACK is `BKE_animsys_evaluate_animdata`'s: the NLA tracks bottom to top (mute and solo as
  *   Blender reads them), then the active action over them. A strip's time is
  *   `nlastrip_get_frame_actionclip`'s (scale, repeat, reverse), its influence its blend in and out
- *   or its own `influence`, and outside it the track holds as its extrapolation says.
- * - EACH CHANNEL blends as `nla_blend_value` / `nla_combine_*` blend it: per component, Replace,
- *   Combine, Add, Subtract or Multiply at the layer's influence. A component no layer animates
- *   keeps the bone's own value; one that is animated starts from the property's default. So an
- *   action that keys only the upper body layers over one that keys the legs, with no masks.
- * - THE MATRIX is `BKE_pchan_to_mat4` then `BKE_armature_mat_bone_to_pose`: rotation by the
- *   bone's own mode, and `parent @ rest @ basis` down the hierarchy.
- * - CONSTRAINTS run per bone after its parent, in stack order, blended by their influence as
- *   `BKE_constraints_solve` blends them. Damped Track is evaluated (`damptrack_do_transform`).
- *   Any other type is not, and is named (`unsupported`): its effect is Blender's alone.
+ *   or its keyed `influence` (that one F-Curve evaluated as `fcurve_eval_keyframes` does), and
+ *   outside it the track holds as its extrapolation says.
  *
- * A clip holds an action's F-Curves whole (`session.py`'s `rna_action_clip`): keys, handles,
- * interpolation, extrapolation and Cycles modifiers, evaluated as `fcurve_eval_keyframes` and
- * `fcm_cycles_time` evaluate them, so a pose is Blender's at any frame, whole or fractional.
+ * The layers it answers are played by three.js (`blender-mixer-pose.ts`): Blender samples each
+ * action, and an `AnimationMixer` blends them.
  *
  * LICENCE. This file follows Blender's source (the functions named above), so it is a derivative
  * work of Blender and is GPL-3.0-or-later, not the AGPL the package's own code carries
@@ -28,31 +19,13 @@
  *
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
-import type { BlenderActionClip, BlenderClipCurve } from '@volter/blender-engine/browser/rna';
-import type {
-  BlenderArmature,
-  BlenderArmatureAnimation,
-  BlenderArmatureBone,
-  BlenderNlaStrip,
-} from '@volter/blender-engine/browser/three/blender-runtime-armature';
-import type { ArmatureRig } from '@volter/blender-engine/browser/three/blender-runtime-skeleton';
-import * as THREE from 'three';
-
-type Channel = 'location' | 'rotation_quaternion' | 'rotation_euler' | 'rotation_axis_angle' | 'scale';
-const CHANNELS: readonly Channel[] = ['location', 'rotation_quaternion', 'rotation_euler', 'rotation_axis_angle', 'scale'];
-const DEFAULTS: Record<Channel, readonly number[]> = {
-  location: [0, 0, 0],
-  rotation_quaternion: [1, 0, 0, 0],
-  rotation_euler: [0, 0, 0],
-  // Blender's NLA default for an axis-angle channel is all zeros (`anim_sys.cc`, zero_v4).
-  rotation_axis_angle: [0, 0, 0, 0],
-  scale: [1, 1, 1],
-};
+import { bytesFromBase64 } from '@volter/blender-engine/browser/three/blender-base64';
+import type { BlenderClipCurve } from '@volter/blender-engine/browser/rna';
+import type { BlenderArmatureAnimation, BlenderNlaStrip } from '@volter/blender-engine/browser/three/blender-runtime-armature';
+import type { MixerClip, MixerLayer } from './blender-mixer-pose';
 
 function float32Of(base64: string): Float32Array {
-  const binary = atob(base64);
-  const bytes = new Uint8Array(binary.length);
-  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  const bytes = bytesFromBase64(base64);
   return new Float32Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 2);
 }
 
@@ -65,49 +38,6 @@ interface PoseCurve {
   readonly cycles: readonly [number, number, number, number] | null;
 }
 
-/** One action read for one armature: its F-Curves, by bone and channel, one per component. */
-export interface PoseClip {
-  readonly action: string;
-  readonly start: number;
-  readonly end: number;
-  /** Where Blender holds the active action over NLA strips; infinite where Cycles repeats it. */
-  readonly keysStart: number;
-  readonly keysEnd: number;
-  readonly cyclic: boolean;
-  readonly channels: readonly {
-    readonly bone: string;
-    readonly channel: Channel;
-    readonly mask: number;
-    readonly stride: number;
-    readonly curves: readonly (PoseCurve | null)[];
-  }[];
-  /** What its curves do in Blender that is not played. */
-  readonly unsupported: readonly string[];
-}
-
-/** The clip door's curves as a clip, or null when it holds nothing a pose can take. */
-export function poseClip(clip: BlenderActionClip): PoseClip | null {
-  if (!clip.action || clip.clipStart === undefined || clip.clipEnd === undefined || !clip.tracks.length) return null;
-  const channels = new Map<string, { bone: string; channel: Channel; mask: number; stride: number; curves: (PoseCurve | null)[] }>();
-  const unsupported = new Set<string>();
-  for (const track of clip.tracks) {
-    const key = `${track.bone}\u0000${track.property}`;
-    const stride = DEFAULTS[track.property].length;
-    let entry = channels.get(key);
-    if (!entry) channels.set(key, entry = { bone: track.bone, channel: track.property, mask: 0, stride, curves: Array.from({ length: stride }, () => null) });
-    if (track.index < 0 || track.index >= stride) continue;
-    entry.mask |= 1 << track.index;
-    entry.curves[track.index] = poseCurve(track);
-    for (const thing of track.unsupported ?? []) unsupported.add(`${clip.action}'s ${thing}`);
-  }
-  for (const thing of clip.unsupported ?? []) unsupported.add(`${clip.action}'s ${thing}`);
-  return {
-    action: clip.action, start: clip.clipStart, end: clip.clipEnd,
-    keysStart: clip.keysStart === null ? -Infinity : clip.keysStart ?? clip.clipStart,
-    keysEnd: clip.keysEnd === null ? Infinity : clip.keysEnd ?? clip.clipEnd,
-    cyclic: clip.cyclic ?? false, channels: [...channels.values()], unsupported: [...unsupported] };
-}
-
 function poseCurve(curve: Pick<BlenderClipCurve, 'extrapolation' | 'interpolation' | 'keysBase64'> & { readonly cycles?: BlenderClipCurve['cycles'] | undefined }): PoseCurve {
   return { extrapolation: curve.extrapolation, interpolation: curve.interpolation, keys: float32Of(curve.keysBase64), cycles: curve.cycles ?? null };
 }
@@ -246,14 +176,13 @@ export function curveAt(curve: PoseCurve, frame: number): number {
   return keyframesAt(curve, time) + offset;
 }
 
-
 /**
  * THE ACTIVE ACTION'S LAYER at a scene frame, placed as `animsys_calculate_nla` places it: a soloed
  * track leaves it out; when no enabled track has strips (or the NLA is off) it is evaluated alone,
  * whole, at full influence; otherwise it is one more strip spanning its own range, at its influence
  * and blend type, holding or not past that range as its extrapolation says.
  */
-export function actionLayer(animation: BlenderArmatureAnimation | undefined, clip: PoseClip, frame: number,
+export function actionLayer(animation: BlenderArmatureAnimation | undefined, clip: MixerClip, frame: number,
   stripsEvaluated: boolean): PoseLayer | null {
   const nla = animation?.useNla ?? true;
   if (nla && animation!.tracks.some((track) => track.solo)) return null;
@@ -271,15 +200,10 @@ export function actionLayer(animation: BlenderArmatureAnimation | undefined, cli
 }
 
 /** One layer of the stack: an action at a frame of its own, an influence, a blend type. */
-export interface PoseLayer {
-  readonly clip: PoseClip;
-  readonly frame: number;
-  readonly influence: number;
-  readonly blend: string;
-}
+export type PoseLayer = MixerLayer;
 
 /** A clip by action name: the clip, `undefined` while it is being baked, null when it has none. */
-export type ClipSource = (action: string) => PoseClip | null | undefined;
+export type ClipSource = (action: string) => MixerClip | null | undefined;
 
 /** The strip a track plays at `frame`, and the time it plays it at (`nlastrips_ctime_get_strip`). */
 function stripAt(strips: readonly BlenderNlaStrip[], frame: number): { strip: BlenderNlaStrip; time: number } | null {
@@ -326,8 +250,7 @@ function stripInfluence(strip: BlenderNlaStrip, time: number): number {
  * clip it needs is still being baked; `skipped` names what plays in Blender and not here;
  * `evaluated` says an enabled track has strips (what places the active action over the NLA).
  */
-export function nlaLayers(animation: BlenderArmatureAnimation | undefined, frame: number, clips: ClipSource,
-  tracks?: (name: string) => boolean): { layers: PoseLayer[]; waiting: boolean; skipped: string[]; evaluated: boolean } {
+export function nlaLayers(animation: BlenderArmatureAnimation | undefined, frame: number, clips: ClipSource): { layers: PoseLayer[]; waiting: boolean; skipped: string[]; evaluated: boolean } {
   const layers: PoseLayer[] = [];
   const skipped: string[] = [];
   let waiting = false;
@@ -336,9 +259,8 @@ export function nlaLayers(animation: BlenderArmatureAnimation | undefined, frame
   const solo = animation.tracks.some((track) => track.solo);
   for (const track of animation.tracks) {
     // ENABLED as `BKE_nlatrack_is_enabled` says: under a solo only the soloed track, muted or not.
-    if ((solo ? !track.solo : track.mute) || (tracks && !tracks(track.name))) continue;
-    // AN ENABLED TRACK WITH STRIPS places the active action over the NLA, whether or not the frame
-    // falls on one of them (`animsys_evaluate_nla_for_flush`'s `has_strips`; measured in 5.2).
+    if (solo ? !track.solo : track.mute) continue;
+    // An enabled NLA track with strips places the active action over the NLA even when the current frame lies outside its strips (animsys_evaluate_nla_for_flush).
     if (track.strips.length) evaluated = true;
     const hit = stripAt(track.strips, frame);
     if (!hit) continue;
@@ -354,275 +276,3 @@ export function nlaLayers(animation: BlenderArmatureAnimation | undefined, frame
   }
   return { layers, waiting, skipped, evaluated };
 }
-
-type Values = Record<Channel, number[]>;
-
-const quatMul = (a: readonly number[], b: readonly number[]): number[] => [
-  a[0]! * b[0]! - a[1]! * b[1]! - a[2]! * b[2]! - a[3]! * b[3]!,
-  a[0]! * b[1]! + a[1]! * b[0]! + a[2]! * b[3]! - a[3]! * b[2]!,
-  a[0]! * b[2]! + a[2]! * b[0]! + a[3]! * b[1]! - a[1]! * b[3]!,
-  a[0]! * b[3]! + a[3]! * b[0]! + a[1]! * b[2]! - a[2]! * b[1]!,
-];
-const quatNormal = (q: readonly number[]): number[] => {
-  const length = Math.hypot(q[0]!, q[1]!, q[2]!, q[3]!);
-  return length > 0 ? q.map((v) => v / length) : [1, 0, 0, 0];
-};
-/** `pow_qt_fl_normalized`. */
-const quatPow = (q: readonly number[], k: number): number[] => {
-  const angle = k * Math.acos(Math.max(-1, Math.min(1, q[0]!)));
-  const length = Math.hypot(q[1]!, q[2]!, q[3]!);
-  const s = Math.sin(angle);
-  return length > 0 ? [Math.cos(angle), (q[1]! / length) * s, (q[2]! / length) * s, (q[3]! / length) * s] : [Math.cos(angle), 0, 0, 0];
-};
-/** One layer blended into the values (`nla_blend_value`, `nla_combine_value`, `nla_combine_quaternion`). */
-function blendLayer(values: Map<string, Values>, touched: Map<string, Record<Channel, number>>, layer: PoseLayer): void {
-  const k = Math.max(0, Math.min(1, layer.influence));
-  if (k === 0) return;
-  const frame = layer.frame;
-  for (const channel of layer.clip.channels) {
-    const bone = values.get(channel.bone);
-    if (!bone) continue;
-    const marks = touched.get(channel.bone)!;
-    const out = bone[channel.channel];
-    // A COMPONENT AN ACTION ANIMATES starts from the property's default, as Blender's NLA does.
-    for (let i = 0; i < channel.stride; i++) if (channel.mask & (1 << i) && !(marks[channel.channel] & (1 << i))) out[i] = DEFAULTS[channel.channel][i]!;
-    marks[channel.channel] |= channel.mask;
-    const sample = channel.curves.map((curve) => (curve ? curveAt(curve, frame) : 0));
-    if (layer.blend === 'COMBINE' && channel.channel === 'rotation_quaternion') {
-      const result = quatMul(quatNormal(out), quatPow(quatNormal(sample), k));
-      for (let i = 0; i < channel.stride; i++) if (channel.mask & (1 << i)) out[i] = result[i]!;
-      continue;
-    }
-    for (let i = 0; i < channel.stride; i++) {
-      if (!(channel.mask & (1 << i))) continue;
-      const lower = out[i]!;
-      const upper = sample[i]!;
-      switch (layer.blend) {
-        case 'ADD': out[i] = lower + upper * k; break;
-        case 'SUBTRACT': out[i] = lower - upper * k; break;
-        case 'MULTIPLY': out[i] = k * (lower * upper) + (1 - k) * lower; break;
-        case 'COMBINE':
-          out[i] = channel.channel === 'scale' ? lower * Math.pow(upper, k) : lower + (upper - DEFAULTS[channel.channel][i]!) * k;
-          break;
-        default: out[i] = lower * (1 - k) + upper * k;
-      }
-    }
-  }
-}
-
-/** `BKE_pchan_to_mat4`: the channels as the bone's basis matrix, rotation by its own mode. */
-function basisMatrix(mode: string, values: Values): THREE.Matrix4 {
-  const rotation = new THREE.Quaternion();
-  if (mode === 'QUATERNION') {
-    const q = quatNormal(values.rotation_quaternion);
-    rotation.set(q[1]!, q[2]!, q[3]!, q[0]!);
-  } else if (mode === 'AXIS_ANGLE') {
-    const v = values.rotation_axis_angle;
-    rotation.setFromAxisAngle(new THREE.Vector3(v[1], v[2], v[3]).normalize(), v[0]!);
-  } else {
-    // Blender's `XYZ` applies X first; three's Euler order names the matrix product, so it reads
-    // the same rotation reversed.
-    const e = values.rotation_euler;
-    rotation.setFromEuler(new THREE.Euler(e[0], e[1], e[2], mode.split('').reverse().join('') as THREE.EulerOrder));
-  }
-  const [x, y, z] = values.location;
-  const [sx, sy, sz] = values.scale;
-  return new THREE.Matrix4().compose(new THREE.Vector3(x, y, z), rotation, new THREE.Vector3(sx, sy, sz));
-}
-
-const TRACK_AXES = ['TRACK_X', 'TRACK_Y', 'TRACK_Z', 'TRACK_NEGATIVE_X', 'TRACK_NEGATIVE_Y', 'TRACK_NEGATIVE_Z'];
-const TRACK_VECTORS = [[1, 0, 0], [0, 1, 0], [0, 0, 1], [-1, 0, 0], [0, -1, 0], [0, 0, -1]] as const;
-
-/** `damptrack_do_transform`: the smallest rotation that points the owner's axis at the target. */
-function dampedTrack(owner: THREE.Matrix4, target: THREE.Vector3, axis: string): THREE.Matrix4 {
-  const flag = Math.max(0, TRACK_AXES.indexOf(axis));
-  const basis = new THREE.Matrix3().setFromMatrix4(owner);
-  const obvec = new THREE.Vector3(...TRACK_VECTORS[flag]!).applyMatrix3(basis);
-  if (obvec.lengthSq() === 0) return owner.clone();
-  obvec.normalize();
-  const obloc = new THREE.Vector3().setFromMatrixPosition(owner);
-  const tarvec = target.clone().sub(obloc);
-  if (tarvec.lengthSq() === 0) tarvec.copy(obvec);
-  else tarvec.normalize();
-  const raxis = new THREE.Vector3().crossVectors(obvec, tarvec);
-  let rangle = Math.acos(Math.max(-1, Math.min(1, obvec.dot(tarvec))));
-  const norm = raxis.length();
-  if (norm < 1.1920929e-7) {
-    if (Math.abs(rangle) < Math.PI - 0.01) return owner.clone();
-    rangle = Math.PI;
-    const other = new THREE.Vector3(...TRACK_VECTORS[(flag + 1) % 6]!).applyMatrix3(basis);
-    raxis.crossVectors(obvec, other);
-    if (raxis.lengthSq() === 0) return owner.clone();
-  } else if (norm < 0.1) {
-    rangle = rangle > Math.PI / 2 ? Math.PI - Math.asin(norm) : Math.asin(norm);
-  }
-  const turned = new THREE.Matrix4().makeRotationAxis(raxis.normalize(), rangle).multiply(owner);
-  return turned.setPosition(obloc);
-}
-
-/** `interp_m4_m4m4`: a constraint's result taken by its influence. */
-function blendMatrix(before: THREE.Matrix4, after: THREE.Matrix4, k: number): THREE.Matrix4 {
-  if (k >= 1) return after;
-  const [p0, q0, s0] = [new THREE.Vector3(), new THREE.Quaternion(), new THREE.Vector3()];
-  const [p1, q1, s1] = [new THREE.Vector3(), new THREE.Quaternion(), new THREE.Vector3()];
-  before.decompose(p0, q0, s0);
-  after.decompose(p1, q1, s1);
-  return new THREE.Matrix4().compose(p0.lerp(p1, k), q0.slerp(q1, k), s0.lerp(s1, k));
-}
-
-/** What a game changes on a constraint while it runs. */
-export interface ConstraintOverride {
-  readonly influence?: number;
-  /** The object it aims at instead of the file's target. */
-  readonly target?: THREE.Object3D | null;
-}
-
-/** Where a constraint's targets are, in the scene the bones are in. */
-export interface ConstraintWorld {
-  /** An object by its Blender name (its presented copy). */
-  object(name: string): THREE.Object3D | null;
-  /** A game's change to one constraint of one bone, if it made one. */
-  override?(bone: string, constraint: string): ConstraintOverride | undefined;
-}
-
-/** One armature's bones, posed by the stack: Blender's evaluation, on the presenter's skeleton. */
-export class ArmaturePose {
-  #bones: readonly BlenderArmatureBone[] = [];
-  #restRelative = new Map<string, THREE.Matrix4>();
-  #armature: BlenderArmature | null = null;
-
-  constructor(readonly rig: ArmatureRig) {}
-
-  /** Take the frame's facts for this armature (its bones' rest, channels and constraints). */
-  facts(armature: BlenderArmature): void {
-    if (armature === this.#armature) return;
-    this.#armature = armature;
-    this.#bones = armature.bones;
-    const rest = new Map(armature.bones.map((bone) => [bone.name, matrixOf(bone.rest ?? bone.matrix)]));
-    this.#restRelative = new Map(armature.bones.map((bone) => {
-      const own = rest.get(bone.name)!;
-      const parent = bone.parent === null ? undefined : rest.get(bone.parent);
-      return [bone.name, parent ? parent.clone().invert().multiply(own) : own.clone()];
-    }));
-  }
-
-  get armature(): BlenderArmature | null {
-    return this.#armature;
-  }
-
-  /** What this armature does in Blender that the evaluator does not, besides its clips' own
-   *  (`PoseClip.unsupported`): each named once. */
-  unsupported(): string[] {
-    const out: string[] = [];
-    for (const bone of this.#bones) {
-      for (const constraint of bone.constraints ?? []) {
-        if (constraint.enabled && constraint.type !== 'DAMPED_TRACK') out.push(`the ${constraintLabel(constraint.type)} constraint "${constraint.name}" on bone "${bone.name}"`);
-      }
-      if (bone.inherit?.length) out.push(`bone "${bone.name}"'s parenting (${bone.inherit.join(', ')})`);
-    }
-    for (const bone of this.#armature?.animation?.drivers ?? []) out.push(`the drivers on bone "${bone}"`);
-    if (this.#armature?.animation?.tweak) out.push('the NLA in tweak mode (leave it with Tab in the NLA editor)');
-    for (const track of this.#armature?.animation?.tracks ?? [])
-      for (const strip of track.strips)
-        if (!strip.mute && strip.animatedTime) out.push(`the animated strip time of "${strip.name}"`);
-    return out;
-  }
-
-  /** Pose the bones from these layers and constraints; answers each bone's armature-space pose.
-   *  `write: false` only answers it, leaving the bones as they are (the fidelity check). */
-  apply(layers: readonly PoseLayer[], world: ConstraintWorld, write = true): Map<string, THREE.Matrix4> {
-    const values = new Map<string, Values>();
-    const touched = new Map<string, Record<Channel, number>>();
-    for (const bone of this.#bones) {
-      const own = bone.channels;
-      values.set(bone.name, Object.fromEntries(CHANNELS.map((channel) => [channel, [...(own?.[channel] ?? DEFAULTS[channel])]])) as Values);
-      touched.set(bone.name, { location: 0, rotation_quaternion: 0, rotation_euler: 0, rotation_axis_angle: 0, scale: 0 });
-    }
-    for (const layer of layers) blendLayer(values, touched, layer);
-
-    this.rig.object.updateWorldMatrix(true, false);
-    const armatureWorld = this.rig.object.matrixWorld;
-    const toArmature = armatureWorld.clone().invert();
-    const poses = new Map<string, THREE.Matrix4>();
-    for (const bone of this.#bones) {
-      const parent = bone.parent === null ? null : poses.get(bone.parent) ?? null;
-      const basis = basisMatrix(bone.channels?.mode ?? 'QUATERNION', values.get(bone.name)!);
-      let pose = (parent ? parent.clone() : new THREE.Matrix4()).multiply(this.#restRelative.get(bone.name)!).multiply(basis);
-      for (const constraint of bone.constraints ?? []) {
-        if (!constraint.enabled || constraint.type !== 'DAMPED_TRACK') continue;
-        const change = world.override?.(bone.name, constraint.name);
-        const influence = change?.influence ?? constraint.influence;
-        if (influence <= 0) continue;
-        const target = this.#target(constraint, change, poses, world);
-        if (!target) continue;
-        const owner = armatureWorld.clone().multiply(pose);
-        const solved = dampedTrack(owner, target, constraint.trackAxis ?? 'TRACK_Y');
-        pose = toArmature.clone().multiply(blendMatrix(owner, solved, influence));
-      }
-      poses.set(bone.name, pose);
-    }
-    if (!write) return poses;
-    for (const bone of this.#bones) {
-      const own = poses.get(bone.name)!;
-      const parent = bone.parent === null ? undefined : poses.get(bone.parent);
-      const local = parent ? parent.clone().invert().multiply(own) : own;
-      const presented = this.rig.bones.get(bone.name);
-      if (presented) local.decompose(presented.position, presented.quaternion, presented.scale);
-    }
-    this.rig.object.updateMatrixWorld(true);
-    return poses;
-  }
-
-  /** A constraint's target point in world space: an object's origin, or a point along a bone. */
-  #target(constraint: NonNullable<BlenderArmatureBone['constraints']>[number], change: ConstraintOverride | undefined,
-    poses: ReadonlyMap<string, THREE.Matrix4>, world: ConstraintWorld): THREE.Vector3 | null {
-    if (change?.target) {
-      change.target.updateWorldMatrix(true, false);
-      return new THREE.Vector3().setFromMatrixPosition(change.target.matrixWorld);
-    }
-    if (change?.target === null || !constraint.target) return null;
-    const object = world.object(constraint.target);
-    if (!object) return null;
-    object.updateWorldMatrix(true, false);
-    if (!constraint.subtarget) return new THREE.Vector3().setFromMatrixPosition(object.matrixWorld);
-    const own = constraint.target === this.rig.armature;
-    const pose = own ? poses.get(constraint.subtarget) : undefined;
-    const bone = this.#bones.find((one) => one.name === constraint.subtarget);
-    if (own && pose && bone) {
-      const along = new THREE.Vector3(0, bone.length * (constraint.headTail ?? 0), 0).applyMatrix4(pose);
-      return along.applyMatrix4(this.rig.object.matrixWorld);
-    }
-    const presented = object.getObjectByName(constraint.subtarget);
-    return presented ? new THREE.Vector3().setFromMatrixPosition(presented.matrixWorld) : null;
-  }
-}
-
-const matrixOf = (rows: readonly (readonly number[])[]): THREE.Matrix4 =>
-  new THREE.Matrix4().set(...(rows.flat() as Parameters<THREE.Matrix4['set']>));
-
-const constraintLabel = (type: string): string =>
-  type.toLowerCase().split('_').map((word) => (word === 'ik' ? 'IK' : word[0]!.toUpperCase() + word.slice(1))).join(' ');
-
-/**
- * THE FIDELITY CHECK: how far an evaluated pose is from Blender's own at the same frame (the
- * frame's `PoseBone.matrix`). Answers the bone that is furthest off, or null when every bone is
- * within a tenth of a degree and a thousandth of its length.
- */
-export function poseDivergence(evaluated: ReadonlyMap<string, THREE.Matrix4>, armature: BlenderArmature):
-  { bone: string; degrees: number; offset: number } | null {
-  let worst: { bone: string; degrees: number; offset: number; score: number } | null = null;
-  const [p0, q0, s0, p1, q1, s1] = [new THREE.Vector3(), new THREE.Quaternion(), new THREE.Vector3(), new THREE.Vector3(), new THREE.Quaternion(), new THREE.Vector3()];
-  for (const bone of armature.bones) {
-    const ours = evaluated.get(bone.name);
-    if (!ours) continue;
-    ours.decompose(p0, q0, s0);
-    matrixOf(bone.matrix).decompose(p1, q1, s1);
-    const degrees = THREE.MathUtils.radToDeg(q0.angleTo(q1));
-    // Relative to the bone, but never to less than a tenth of a metre: a fingertip bone a
-    // centimetre long is not off by a tenth of a millimetre's float noise.
-    const offset = p0.distanceTo(p1) / Math.max(bone.length, 0.1);
-    const score = Math.max(degrees / 0.1, offset / 1e-3);
-    if (score > 1 && (!worst || score > worst.score)) worst = { bone: bone.name, degrees, offset, score };
-  }
-  return worst && { bone: worst.bone, degrees: worst.degrees, offset: worst.offset };
-}

package/contributions/blender-properties-context.ts

@@ -1,6 +1,6 @@
 /** Blender's Properties context remains inspectable without a selection.
  * Reuse the same RNA sections and Properties projection as selected objects. */
-import { registerNullSubjectProvider } from '@volter/sdk/kit/inspection/null-subject';
+import { registerNullSubjectProvider } from '@volter/sdk/inspection/null-subject';
 import { blenderOutlinerState } from './blender-outliner-model';
 import { blenderOutlinerKind } from './blender-outliner-authoring';
 import {

package/contributions/blender-properties-model.ts

@@ -1,37 +1,4 @@
-/**
- * WHAT THE PROPERTIES SECTIONS ARE LOOKING AT — the page-side half of the RNA
- * door (WORK.md §Blender in the tab is Blender, "Inspection parity", I1).
- *
- * React-free ON PURPOSE: this module is a plain store with `subscribe` /
- * `version` / `state`, so the host's Blender side can import it without
- * pulling React into its closure, and the sections read it through one
- * `useSyncExternalStore` (`blender-properties-view.tsx`).
- *
- * THE SUBJECT IS THE PRESENTED BLENDER CONTEXT. The person clicks a node
- * in our viewport; the adapter hands that node's `THREE.Object3D`; the
- * presented view answers which Blender object that three object IS
- * (`BlenderRuntimeView.blenderObjectName`, a lookup by object identity in the
- * frame's own table — never a name match). That name goes to
- * `rna_context(object=…)`, which builds the Properties context around it
- * exactly as `buttons_context.cc` builds one around
- * `BKE_view_layer_active_object_get`. Reading our selection never WRITES the
- * engine's active object: that is a mutation, and the document would save it.
- * With no selected node, the presented frame's active object remains the
- * Properties subject; no active object resolves the scene instead.
- *
- * WHEN IT RE-READS. Three times, and each is a signal rather than a poll:
- *  - a PRESENT (`BlenderRuntimeView.subscribeFrames`) — every mutation
- *    presents (`session.py::dispatch`), so a frame is "what you are showing is
- *    stale";
- *  - the RNA DOOR'S OWN VERSION (`subscribeBlenderRna`, ruling 3 of
- *    2026-09-19) — because a write can change what RNA answers and nothing the
- *    presenter draws, so no frame ships: `Node.panel_states[n].is_collapsed`
- *    and `Object.hide_render` are the two measured cases;
- *  - the SELECTION moving to another datablock.
- * A re-read that changes which TABS exist also calls the host door's
- * `documents.contextChanged`, because the tab rail IS the section list and
- * nothing in a host store moved.
- */
+/** React-free Properties store over the RNA door. Resolve the subject from the presented Blender context without mutating selection. Re-read on presented frames, RNA writes and selection changes; notify documents.contextChanged whenever the resolved tab context changes. */
 
 import type { BlenderRnaContext, BlenderRnaView } from '@volter/blender-engine/browser/rna';
 import { editorHost } from '@volter/sdk/host';
@@ -65,13 +32,10 @@ const isPresentedView = (value: unknown): value is PresentedView =>
   typeof (value as PresentedView).blenderObjectName === 'function' &&
   typeof (value as PresentedView).blenderSelection === 'function';
 
-/** The active authoring adapter, as much of it as this module reads. The
- *  adapter is deliberately `unknown` at the contribution point (adapter-native
- *  API, never a fabricated projection), and `@volter/editor-blender` holds no host
- *  import — so the shape it needs is stated here and checked at runtime. */
+/** The adapter-native fields this SDK-host reader uses, checked at runtime. */
 interface Object3DAuthoringLike {
   readonly documentId: string;
-  readonly hierarchy: { object3D(id: string): THREE.Object3D | null };
+  readonly hierarchy: { nativeObject(id: string): THREE.Object3D | null };
   readonly documentRootObject: THREE.Object3D | null;
 }
 
@@ -79,7 +43,7 @@ const isObject3DAuthoring = (value: unknown): value is Object3DAuthoringLike =>
   typeof value === 'object' &&
   value !== null &&
   typeof (value as Object3DAuthoringLike).documentId === 'string' &&
-  typeof (value as Object3DAuthoringLike).hierarchy?.object3D === 'function';
+  typeof (value as Object3DAuthoringLike).hierarchy?.nativeObject === 'function';
 
 function presentedView(): PresentedView | null {
   const published = editorHost().documents.context(blenderPresentationDocumentId());
@@ -127,20 +91,14 @@ export function resolveBlenderSubject(
   if (node.id === adapter.documentId)
     return adapter.documentRootObject === view.root ? { kind: 'scene' } : null;
   // A COLLECTION ROW HAS NO OBJECT, so it has to be resolved before the object
-  // lookup rather than after it — `object3D` answers null for one, which is the
-  // honest answer and used to end the resolution here (I3's standing OPEN: the
-  // rail simply stayed on the previous subject). The row table is this
+  // lookup rather than after it — `nativeObject` answers null for one, which would
+  // leave the rail on the previous subject. The row table is this
   // package's own (`blender-outliner-model.ts`), so this is a map lookup.
   const row = blenderOutlinerState().byId.get(node.id);
   if (row?.type === 'TSE_LAYER_COLLECTION') return { kind: 'collection', path: row.path };
-  const object = adapter.hierarchy.object3D(node.id);
+  const object = adapter.hierarchy.nativeObject(node.id);
   if (object === null) return null;
-  // THE SCENE COLLECTION IS THE SCENE SUBJECT. Under I3 the hierarchy is
-  // Blender's Outliner, whose root row is the Scene Collection and NOT a
-  // document row of the host's — so the row that stands for the whole file is
-  // the one whose object is the presented ROOT, and it stands for exactly what
-  // the document row did: the tabs that need no object (Render, Output, View
-  // Layer, Scene, World, Collection).
+  // The Scene Collection root resolves the scene subject and its object-independent Properties tabs.
   if (object === view.root) return { kind: 'scene' };
   const name = view.blenderObjectName(object);
   return name === null ? null : { kind: 'object', name };
@@ -211,22 +169,12 @@ export function blenderPropertiesState(): BlenderPropertiesState {
   return state;
 }
 
-/** THE ENGINE MOVED: everything read off it is stale. The CONTEXT is
- *  re-read immediately (the tabs may have changed — a modifier was added, a
- *  bone became active); the datablock views are dropped and re-read by
- *  whichever section is still showing them.
- *
- *  Two things call this, and the second is why it is no longer named
- *  `onFrame`: a PRESENTED FRAME, and the RNA door's own version (ruling 3,
- *  2026-09-19 — `blenderRnaVersion`). A write that changes nothing the
- *  presenter draws ships no frame, and before this the rail simply kept the
- *  values it had. */
+/** Invalidate datablock caches and re-read context on RNA version changes, including writes that produce no presented-frame change. */
 function onEngineMoved(): void {
   // STALE, NOT EMPTY. The generation moves, so every answer already in flight
   // is dropped when it lands (a deleted duplicate's late read cannot overwrite
   // the new selection) -- but the panel keeps showing what it holds until the
-  // re-read answers. Clearing here blanked and repainted the whole Properties
-  // panel on every edit, because every edit presents a frame.
+  // re-read answers. Keep the settled panel visible while each edit presents its frame.
   const subject = readFor;
   readGeneration += 1;
   inFlight.clear();
@@ -235,26 +183,15 @@ function onEngineMoved(): void {
   else publish({});
 }
 
-// THE FRAME IS ONE SIGNAL AND THE RNA DOOR IS THE OTHER. This subscription is
-// module-level rather than taken beside the frame one, because the RNA door
-// exists from the first import while the document's view arrives later — and a
-// write made before the first present is exactly the case that went unseen.
+// Subscribe on module import so RNA writes before the first presented frame
+// also invalidate the context. Frame changes provide the other signal.
 subscribeBlenderRna(() => {
   onEngineMoved();
 });
 
-/**
- * THE READ NEVER STARTS INSIDE A RENDER. `showBlenderSubject` is called from a
- * tab's `match()`, which the host runs while it is RENDERING the workspace —
- * and the read's first act is to publish `loading`, which is a `setState` in
- * every subscribed component. React said so by name ("Cannot update a
- * component (BlenderPropertiesSection) while rendering a different
- * component"), measured live 2026-09-19. The WANT is recorded
- * synchronously so a second matcher in the same pass does not queue a second
- * read; the read itself runs on the next turn of the loop, outside the render.
- */
 let scheduledKey: string | null = null;
 
+/** Queue the context read outside React render; record the request synchronously to deduplicate matchers in the same composition. */
 function scheduleContextRead(key: string, refresh = false): void {
   if (scheduledKey === key) return;
   scheduledKey = key;
@@ -278,12 +215,7 @@ function watchFrames(): void {
   if (frameSubscription !== null) return;
   const view = presentedView();
   if (view === null) return;
-  // A FRAME IS REPORTED TO THE RNA DOOR'S VERSION, not consumed here. The
-  // subscription lives in this module because this module is what the document
-  // publishes its view to, but the signal belongs to every view over the
-  // engine — so it is minted in ONE place (ruling 3) and this module hears its
-  // own frame back through `subscribeBlenderRna` above, exactly as the node
-  // view and the UV view do.
+  // Report frames through the shared RNA version so Properties, node and UV views receive the same engine-change signal.
   frameSubscription = view.subscribeFrames(noteBlenderRnaChanged);
 }
 
@@ -311,14 +243,7 @@ async function readContext(key: string, refresh = false): Promise<void> {
       publish({ loading: false, error: null });
       return;
     }
-    // ALWAYS a tab-rail notification, and that is a correction rather than a
-    // convenience: the gate a tab matches on is BOTH the subject this context
-    // was read for and the tab list, so comparing only the list missed the
-    // case that actually happens — selecting the Cube after the document row
-    // reads the SAME thirteen tabs for a different subject, the gated tabs'
-    // `state.object !== object` went false, and nothing ever said so. Measured
-    // live 2026-09-19: Collection/Modifiers/Particles/Object Data/Material
-    // disappeared on the first selection and only came back on a re-select.
+    // Notify the tab rail after every context read; both the subject identity and tab list determine matches.
     publish({ context, loading: false, error: null }, true);
   } catch (error) {
     if (generation !== readGeneration || request !== contextRequest) return;