@woosh/meep-engine 3.1.0 → 3.3.0

package/src/REVIEW_2026_08_06/engine-animation.md

@@ -1,167 +1,167 @@
-# Correctness review — `engine/animation/` + `engine/interpolation/`
-
-Scope: every non-spec source file under
-`meep/src/engine/animation/` and `meep/src/engine/interpolation/`
-(plus the prioritised `core/math/spline/spline3_hermite_reverse.js`,
-`spline3_hermite_apply_transform.js`, `spline3_hermite_bounds.js`).
-
-Specs were read as evidence only.
-
----
-
-## Findings
-
-### ANIM-1 `animation_curve_nearest_point` minimises in normalized-time space but selects in real-time space
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/curve/animation_curve_nearest_point.js:44-60`
-- **Defect**: The per-segment search is handed `ref_t = inverseLerp(key0.time, key1.time, ref_time)` — the reference point re-expressed with its x-axis squeezed into `[0,1]` — while the value axis is left in real units. `spline3_hermite_nearest_point` therefore minimises `(t − ref_t)² + (p(t) − ref_value)²`, a distance in a distorted metric, but the winner is then scored at line 60 with `v2_distance_sqr(curve_time, curve_value, …)` in real `(time, value)` units. The two metrics only coincide when the segment duration is exactly 1, which is the only case the spec file exercises.
-- **Failure scenario**: `const c = AnimationCurve.linear(0, 0, 10, 10);` (keys `(0,0,in 0,out 1)` and `(10,10,in 1,out 0)`, a straight line `y = x`). Call `animation_curve_nearest_point(c, 10, 0)`. In normalized space the segment is `p(t) = 10t`, so minimising `(t−1)² + (10t)²` gives `t = 1/101 ≈ 0.0099`; that maps back to `curve_time ≈ 0.099`, whose real distance² to `(10,0)` is `98.05` — better than the `100` of the seeded candidate `(0,0)`, so it wins. **Returned `0.099`.** The true nearest point on `y = x` to `(10,0)` is `(5,5)` at distance² `50`, i.e. **time `5`**. Downstream, `detectClosestCurveTimePoint` (`curve/draw/isInjectedKeyframeInBounds.js:56`) turns this into a user-visible failure: on any curve whose keys are not ~1 apart, clicking directly on the plotted line reports a curve point tens of pixels away, `mousePosition.distanceTo(...) <= 10` fails, and a keyframe cannot be injected by clicking the curve.
-- **Fix**: Search in a space where both axes carry the same unit. Divide the value axis by `time_delta` as well, then de-normalize:
-  ```js
-  const inv = time_delta === 0 ? 0 : 1 / time_delta;
-  const t = spline3_hermite_nearest_point(
-      ref_t, ref_value * inv,
-      key0.value * inv, key1.value * inv,
-      key0.outTangent, key1.inTangent   // == m0*inv, m1*inv
-  );
-  ```
-  and keep line 58 evaluating the *unscaled* `spline3_hermite(t, key0.value, key1.value, m0, m1)`. (Scaling the whole plane by `1/time_delta` scales every distance by the same factor, so the argmin is preserved and now matches the real-space metric used at line 60.)
-- **Confidence**: Confirmed
-
----
-
-### ANIM-2 `AnimationTrackPlayback` constructor seeks to absolute 0, not `track.timeStart`
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/keyed2/AnimationTrackPlayback.js:36`
-- **Defect**: Line 16 correctly sets `this.position = track.timeStart`, then line 36 overwrites it with `this.setPosition(0)`. For a track whose first key is not at t=0, `setPosition(0)` runs `keyLowerBoundIndexAt(0)`, which returns `-1` ("no key at or before this time"). `__lastKeyIndex` is then `-1`, and `readKeyValues(-1, result)` computes `offset = -propertyCount` and reads off the front of `keyValues`, producing `undefined` → `NaN` in the `Float64Array` value buffer. `reset()` (line 70) and `AnimationBehavior.initialize` (`keyed2/behavior/AnimationBehavior.js:37`) both use `track.timeStart`, so the constructor is the odd one out.
-- **Failure scenario**:
-  ```js
-  const t = new AnimationTrack(['alpha']);
-  t.addKey(1, [10]);            // timeStart = 1
-  t.addKey(2, [20]);            // timeEnd   = 2
-  t.addTransition(0, TransitionFunctions.Linear);
-
-  const p = new AnimationTrackPlayback(t, cb, null);
-  // __lastKeyIndex === -1, __lastTransitionIndex === -1, __nextKeyTime === 1
-  p.update();                   // cb(NaN)   <-- expected cb(10)
-  p.advance(0.016);             // cb(NaN)
-  ```
-  This is reached on the shipping paths that call `update()` before the first tick: `playTrackRealTime.js:26` ("tick animation to make sure the state is synchronized") and `GUIEngine.js:535` ("force view status to initial key of animation"). With such a track the latter writes `el.style.opacity = NaN` and `view.scale.set(NaN, NaN)`. Playbacks driven through `AnimationBehavior` are shielded because `initialize()` re-seeks to `timeStart`; `playAnimationTrack`/direct `advance()` are not.
-- **Fix**: Change line 36 to `this.setPosition(track.timeStart);` (line 16 then becomes redundant). Note the existing spec `"playback starts at position 0 by default"` only covers a track whose `timeStart` is already 0, so it stays green.
-- **Confidence**: Confirmed
-
----
-
-### ANIM-3 `advanceKey()` leaves a stale `__lastTransitionIndex` when the transition scan runs off the end
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/keyed2/AnimationTrackPlayback.js:135-146`
-- **Defect**: The scan
-  ```js
-  for (let i = this.__lastTransitionIndex + 1; i < transitionCount; i++) { … }
-  ```
-  only writes `__lastTransitionIndex = -1` in the `startKeyIndex > __lastKeyIndex` branch. If the loop exhausts without entering either branch — which happens whenever the new key is at or past the last entry in `transitionKeys` — the previous transition index survives. `readCurrentValues` then takes the transition branch for a key that has no transition, interpolating where `setPosition` (via `transitionIndexAt`, which returns `-1` for the same time) would hold. The loop-wrap case at lines 112-117 has the same root: `__lastKeyIndex` rewinds to `0` but the scan cursor is never rewound to `0`, so a transition on key 0 is missed after the first loop.
-- **Failure scenario A (no loop)**:
-  ```js
-  const t = new AnimationTrack(['scale']);
-  t.addKey(0, [1]); t.addKey(1, [0]); t.addKey(2, [5]);
-  t.addTransition(0, TransitionFunctions.Linear);   // transitionKeys = [0]
-  const p = new AnimationTrackPlayback(t, cb, null); // __lastTransitionIndex = 0
-  p.advanceKey();   // __lastKeyIndex = 1; loop runs from i=1, transitionCount=1 → no iterations
-  p.update();
-  ```
-  `__lastTransitionIndex` is still `0`, so the segment key1→key2 is Linear-interpolated from `0` toward `5`; seeking to the same time with `setPosition(1.0)` yields `__lastTransitionIndex === -1` and holds `0`. Two different poses for the same time on the same track.
-- **Failure scenario B (loop wrap)**: same track plus `t.addTransition(1, TransitionFunctions.EaseOut)` and `p.setLoop(true)`. Advance to the last key (`__lastTransitionIndex === 1`), then `advanceKey()` wraps `__lastKeyIndex` to `0`; the scan starts at `i = 2 >= transitionCount`, so `__lastTransitionIndex` stays `1`. The key0→key1 segment is now driven by `transitionFunctions[1]` (EaseOut) instead of `transitionFunctions[0]` (Linear) — the second and every later loop iteration eases differently from the first.
-- **Fix**: Clear the cursor before scanning and rewind it on wrap:
-  ```js
-  if (wrapped) { this.__lastTransitionIndex = -1; }        // in the loop branch, before += 1
-  const scan_start = this.__lastTransitionIndex + 1;
-  this.__lastTransitionIndex = -1;                          // default: no transition
-  for (let i = scan_start; i < transitionCount; i++) {
-      const startKeyIndex = transitionKeys[i];
-      if (startKeyIndex === this.__lastKeyIndex) { this.__lastTransitionIndex = i; break; }
-      if (startKeyIndex > this.__lastKeyIndex) { break; }
-  }
-  ```
-- **Confidence**: Confirmed
-
----
-
-### ANIM-4 `AnimationClipBinding.bind()` cannot bind any clip the engine actually produces
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/clip/AnimationClipBinding.js:64-76`
-- **Defect**: Two independent breaks on the same path.
-  1. `binding_registry[track.type]` keys off `AnimationTrack.type`, which defaults to `""` (`clip/AnimationTrack.js:31`). The only producer of `AnimationClip`/`AnimationTrack` in the tree is `convert_three_clip` → `AnimationTrack.from(curves, track_name)` (`clip/ecd_bind_animation_curve.js:106`), which sets `curves` and `name` and **never sets `type`**. Every track therefore looks up `""`.
-  2. Even with a populated registry, the contract is `new WriterClass()` followed by `writer.bind(root, track.path)`. The only writers that can express a vector/quaternion target — `BoundVector3Writer` and `BoundQuaternionWriter` — take their target in the *constructor* and do not override `bind()`, so they inherit `BoundValueWriter.bind` which unconditionally `throw new Error('Not Implemented')` (`curve/binding/BoundValueWriter.js:19`). The one writer that does implement `bind()`, `BoundPlainNumericPropertyWriter`, writes a single scalar (`this.parent[this.property_name] = data[0]`), so it cannot carry a 3- or 4-component track.
-- **Failure scenario**: Import a glTF, get `const cb = convert_three_clip(node, threeClip)` (this is what `SGMeshAnimationControllerSystem.js:78` does), then retarget it to a second skeleton, which is exactly what `bind()` exists for:
-  ```js
-  cb.bind(other_node, { position: BoundVector3Writer, quaternion: BoundQuaternionWriter });
-  ```
-  → throws `No binding class in registry for track type ''` on the first track. Supply `{ "": BoundVector3Writer }` to get past that and it throws `Not Implemented` from `writer.bind`. Note that `bind()` also `splice`s `this.tracks` empty *before* the throw (line 54), so the binding is left destroyed — a clip that rendered fine before the retarget attempt now writes nothing.
-- **Fix**: (a) set `type` in `convert_three_clip` from the property name it already computes (`three_track.name.split('.')` last part, or `three_track.ValueTypeName`) before `AnimationTrack.from(...)`; (b) give `BoundVector3Writer`/`BoundQuaternionWriter` no-arg constructors plus a real `bind(root, path)` that resolves the target the way `bind_property_writer` does, so they satisfy the registry contract; and (c) build the new track list into a local array and only assign it over `this.tracks` once every track bound, so a failure leaves the previous binding intact.
-- **Confidence**: Confirmed
-
----
-
-### ANIM-5 CUBICSPLINE quaternion tracks are not hemisphere-aligned
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/clip/ecd_bind_animation_curve.js:66-67`
-- **Defect**: The alignment guard is `interpolation === AnimationInterpolationKind.Linear && track.ValueTypeName === 'quaternion'`. A glTF `CUBICSPLINE` rotation track resolves to `AnimationInterpolationKind.CubicTangents` (line 26/32) and so skips `hemisphere_align_quaternion_values` entirely, yet it is still decomposed into four independent scalar Hermite curves (line 74-89) and reassembled by `BoundQuaternionWriter.write` → `fromArray` + `normalize`. Component-wise interpolation across a key pair with a negative dot product takes the long arc. (This is *not* the already-fixed LINEAR case; the in-code comment acknowledges the CubicTangents path as "not yet aligned".)
-- **Failure scenario**: A Blender-exported glTF with `CUBICSPLINE` rotation on a bone, with adjacent keys `q0 = (0, 0, 0, 1)` (identity) and `q1 = (0, 0, −0.0872, −0.9962)` (a −10° Z rotation written in the negative hemisphere; `dot = −0.9962`). Per-component Hermite at the midpoint gives roughly `(0, 0, −0.0436, 0.0019)`; after `normalize()` that is ≈ `(0, 0, −0.999, 0.044)`, i.e. ~175° of Z rotation. The bone whips through nearly a full turn between two keys that are 10° apart, and passes through a near-degenerate quaternion where the normalize is numerically unstable.
-- **Fix**: Align CubicTangents quaternion tracks too, but negate the *whole key triple* — a CUBICSPLINE key is `[inTangent, value, outTangent]` per component, so a sign flip on the value must flip that key's in- and out-tangents as well or the tangents will fight the values. That needs a CubicTangents-aware variant of `hemisphere_align_quaternion_values` operating on a stride of `3 * component_count` and deciding the flip from the value sub-block.
-- **Confidence**: Confirmed
-
----
-
-### ANIM-6 `acquireInjectedKeyframePosition` uses `time === 0` / `time >= 0` as "unset" sentinels
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/curve/draw/isInjectedKeyframeInBounds.js:76-86`
-- **Defect**: `prevKeyframeRef` and `nextKeyframeRef` are `new Keyframe()`, i.e. `time = 0, value = 0`. The bracketing scan then uses those zeros as sentinels: `kf.time >= prevKeyframeRef.time` treats "0" as "nothing found yet", and `nextKeyframeRef.time === 0` is the "still unset" test. Both are wrong for a curve that has keys at or before t = 0 — `0` is a legitimate keyframe time, and a legitimate keyframe time can be negative.
-- **Failure scenario**: A curve with keys at times `−2, −1, 0, 1` (the editor's frame pans freely into negative time, and `position_canvas_to_curve` maps whatever is on screen). The user clicks on the curve at `timeSplicePosition = −1.5`, which passes the `curveTimePos > curve.keys[0].time` gate. The scan then:
-  - `kf(−2)`: `−2 <= −1.5` ✓ but `−2 >= 0` ✗ → **prev is never captured**, stays the phantom `(0, 0)`;
-  - `kf(−1)`: `−1 >= −1.5` ✓ and `next.time === 0` ✓ → next = `kf(−1)`.
-
-  `segmentTimeDiff = −1 − 0 = −1`, `segmentTimeTravel = −1.5 − 0 = −1.5`, `segmentTimeSplitRatio = 1.5`. `animation_curve_subdivide` is then called with `t = 1.5` (its `assert.ok(t >= 0 && t <= 1)` is compiled out in prod) between the phantom `(0,0)` and `kf(−1)`, so the injected keyframe gets an extrapolated value computed from a keyframe that does not exist. The key lands on the curve at the right time with a visibly wrong value and wrong tangents.
-  A second, independent instance of the same sentinel: with keys at `−1, 0, 1` and a splice at `−0.5`, `kf(0)` is copied into `nextKeyframeRef` but leaves `nextKeyframeRef.time === 0`, so `kf(1)` overwrites it — the "next" key is two keys away.
-- **Fix**: Drop the sentinels and bracket by index, e.g. `const i = curve.getKeyIndexLow(timeSplicePosition);` then `prev = curve.keys[i]`, `next = curve.keys[i + 1]` (with an early-out when `i + 1 >= curve.length`). `getKeyIndexLow` already does this correctly and handles duplicate times.
-- **Confidence**: Confirmed
-
----
-
-### ANIM-7 `isNotAlreadyAligned` is never called, and the comparison it makes is inverted
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/curve/draw/build_tangent_editor.js:243, 254`
-- **Defect**: Two errors that partially mask each other.
-  1. Line 254: `if (enableTangentAlignment.getValue() === true && isNotAlreadyAligned)` tests the *function object*, not its result. A function is always truthy, so the guard is a no-op.
-  2. Line 243: the predicate itself is `!(keyframe.inTangent === -keyframe.outTangent)`. Alignment in this editor means `inTangent === outTangent` — that is what the drag-time alignment branch produces (`updateTangentValues`, lines 55-63, sets `inTangent = outTangent`) and what `AnimationCurve.alignTangents` produces for a smooth key. The `-` makes the predicate report a *corner* (`in = 1, out = −1`) as "already aligned" and a correctly aligned key (`in = out = 2`) as "not aligned".
-- **Failure scenario**: Select a keyframe whose tangents are already equal, e.g. `Keyframe.from(0.5, 1, 2, 2)`, and tick the "align tangents" checkbox. `modifyTangentAlignmentPosition` runs, computes `avgTangent = 2`, writes the same values back, and still calls `actionProcessor.mark('auto move tangents')` + `actionProcessor.do(new TangentChangeAction(...))`. An undo entry that changes nothing is pushed onto the stack; Ctrl+Z afterwards consumes a step with no visible effect. Conversely, if the missing `()` is added without also fixing the `-`, a corner key (`in = 1, out = −1`) would silently refuse to align — the checkbox would appear to do nothing.
-- **Fix**: `… && isNotAlreadyAligned()` **and** change the predicate body to `return keyframe.inTangent !== keyframe.outTangent;`. (Separately, `Math.abs(newTangent) > Infinity` on line 249 is never true; if a non-finite guard is wanted it should be `!Number.isFinite(newTangent)`.)
-- **Confidence**: Confirmed
-
----
-
-## Status of the "already known, unconfirmed" items
-
-| Item | Status |
-| --- | --- |
-| `AnimationGraph` JSON dropping state `name`/`tags` | **FIXED** — `writeAnimationGraphDefinitionToJSON.js:69-71` now emits `name` and `tags` for states (and `name`/`tags` for clips); `readAnimationGraphDefinitionFromJSON.js:80-88` destructures `{ motion, type, name, tags = [] }` and assigns both back. |
-| `startingSate` typo | **STILL PRESENT** — the misspelling is load-bearing across the field (`AnimationGraphDefinition.js:29`), the JSON key (`writeAnimationGraphDefinitionToJSON.js:100` / `readAnimationGraphDefinitionFromJSON.js:25,130`), the binary adapter (`AnimationGraphDefinitionSerializationAdapter.js:154,295`) and both readers (`AnimationGraph.js:160,350`). Consistent everywhere, so no behavioural defect — renaming requires a JSON migration. |
-| `AnimationClip.repeatCount` default | **FIXED** — `engine/ecs/animation/AnimationClip.js:9` initialises `new ObservedInteger(1)` and `fromJSON` (lines 83-87) falls back to `this.repeatCount.set(1)` when the field is absent. `toJSON`/`toBinaryBuffer`/`fromBinaryBuffer` all carry the field, so the three paths agree. |
-
----
-
-## Areas checked and found clean
-
-- **`engine/interpolation/` (whole package)** — `InterpolationSystem` link/unlink is symmetric, `snap` is consumed exactly once per set, per-source playout windows are sampled once per frame and cleared each update, `PoseInterpolationAdapter` does hemisphere-corrected nlerp with renormalize and reduces correctly when `first_offset === second_offset`, `TransformPoseSerializationAdapter` round-trips the same 7 × Float64 layout it declares, `InterpolationLog.interpolate` never reads a stale scratch offset for a tick it failed to locate, and `locate`'s page walk matches the page layout `begin_tick`/`begin_record` write.
-- **`spline3_hermite_reverse`** — verified against `R(u) = H(1−u)`: `R(0) = p1`, `R(1) = p0`, `R'(0) = −m1`, `R'(1) = −m0`; the written order `[p1, p0, −m1, −m0]` matches the `[p0, p1, m0, m1]` layout, and double-reversal is exactly the identity.
-- **`spline3_hermite_apply_transform`** — column-major indexing is right (`m4[0,4,8,12]` for x′), endpoints take the translation column and tangents do not, and the 12 outputs are in the declared `p0/p1/m0/m1` order.
-- **`spline3_hermite_bounds`** (scale-relative change) — the derivative quadratic `a = 3(m0+m1+2p0−2p1)`, `b = −2(2m0+m1+3p0−3p1)`, `c = m0` matches `H′(t)` exactly; the relative `epsilon = max3(|a|,|b|,|c|)·1e-12` correctly degrades to the linear branch without losing interior extrema on small-coordinate curves.
-- **`spline3_hermite_nearest_point`** quintic coefficients — expanded by hand, all six match `(t − ref_t) + (p(t) − ref_p)·p′(t)`. The bug in ANIM-1 is entirely at the call site.
-- **`curve_from_track_data_discrete`** — the reverse `splice` produces `[(t0,v0),(t1,v0),(t1,v1),(t2,v1),(t2,v2)]`; walked through `getKeyIndexLow`/`evaluate` at `t < t1`, `t = t1`, `t1 < t < t2`, `t = t2` and every case gives correct step behaviour with no zero-span division.
-- **`curve_from_track_data_linear`** + `alignTangents` — for each segment `k0.outTangent == k1.inTangent == (v1−v0)/(t1−t0)`, so the Hermite degenerates to exactly the straight line; coincident keys are handled by the `time_span === 0 → 0` branch.
-- **`Tween`** ping-pong turnaround — at `timeElapsed = N·duration`, `cycleWhole = N` and `cycleFraction = 0` give `state = 1` for odd `N` and `0` for even `N`, which is the correct reversal at both ends; the non-oscillating branch fires `ended` once (`destroy()` removes the driving entity in the same call).
-- **`AnimationTrackPlayback.advance`** event semantics — `ended` fires exactly once per forward crossing for a delta larger than the whole clip, and does not re-fire while parked past `timeEnd`; the negative-delta branch correctly avoids the one-shot.
-- **`downsample_float_array_curve_by_error`** — ping-pong buffer sizes (`n/2` and `n/4`) are never overrun as `current_size` halves, and the `target_samples === 1` special case stops the loop before `downsample_float_array` can be handed an odd size.
-- **`animation_curve_optimize`** — the `i--; key_count--` removal step keeps the cursor correct, and the first/last keys are structurally protected.
-- **`animation_curve_fit`** — `calculateTangent` boundary/interior cases are consistent with the tangent convention `evaluate_two_key_curve` uses (`slope × segment duration`), the recursion strictly shrinks, and `splitIndex === -1` is unreachable when `maxSegmentError > maxError`.
-- **`table_find_min_index_in_ordered_column`** — returns the correct lower bound (`minIndex − 1`) on a miss and `−1` before the first sample, which `findLowSampleIndexByTime` clamps.
-- **`AnimationCurveView.draw_key_tangents`** — `in_angle = −atan2(inTangent, −1)` is the angle of `(−1, −m)`, correct for a backward-pointing handle in curve space before the y-flipping transform; `build_tangent_editor.handleTangentUpdate`'s screen-space angles (`π − atan2(in,1)`, `−atan2(out,1)`) are the correct y-down equivalents.
+# Correctness review — `engine/animation/` + `engine/interpolation/`
+
+Scope: every non-spec source file under
+`meep/src/engine/animation/` and `meep/src/engine/interpolation/`
+(plus the prioritised `core/math/spline/spline3_hermite_reverse.js`,
+`spline3_hermite_apply_transform.js`, `spline3_hermite_bounds.js`).
+
+Specs were read as evidence only.
+
+---
+
+## Findings
+
+### ANIM-1 `animation_curve_nearest_point` minimises in normalized-time space but selects in real-time space
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/curve/animation_curve_nearest_point.js:44-60`
+- **Defect**: The per-segment search is handed `ref_t = inverseLerp(key0.time, key1.time, ref_time)` — the reference point re-expressed with its x-axis squeezed into `[0,1]` — while the value axis is left in real units. `spline3_hermite_nearest_point` therefore minimises `(t − ref_t)² + (p(t) − ref_value)²`, a distance in a distorted metric, but the winner is then scored at line 60 with `v2_distance_sqr(curve_time, curve_value, …)` in real `(time, value)` units. The two metrics only coincide when the segment duration is exactly 1, which is the only case the spec file exercises.
+- **Failure scenario**: `const c = AnimationCurve.linear(0, 0, 10, 10);` (keys `(0,0,in 0,out 1)` and `(10,10,in 1,out 0)`, a straight line `y = x`). Call `animation_curve_nearest_point(c, 10, 0)`. In normalized space the segment is `p(t) = 10t`, so minimising `(t−1)² + (10t)²` gives `t = 1/101 ≈ 0.0099`; that maps back to `curve_time ≈ 0.099`, whose real distance² to `(10,0)` is `98.05` — better than the `100` of the seeded candidate `(0,0)`, so it wins. **Returned `0.099`.** The true nearest point on `y = x` to `(10,0)` is `(5,5)` at distance² `50`, i.e. **time `5`**. Downstream, `detectClosestCurveTimePoint` (`curve/draw/isInjectedKeyframeInBounds.js:56`) turns this into a user-visible failure: on any curve whose keys are not ~1 apart, clicking directly on the plotted line reports a curve point tens of pixels away, `mousePosition.distanceTo(...) <= 10` fails, and a keyframe cannot be injected by clicking the curve.
+- **Fix**: Search in a space where both axes carry the same unit. Divide the value axis by `time_delta` as well, then de-normalize:
+  ```js
+  const inv = time_delta === 0 ? 0 : 1 / time_delta;
+  const t = spline3_hermite_nearest_point(
+      ref_t, ref_value * inv,
+      key0.value * inv, key1.value * inv,
+      key0.outTangent, key1.inTangent   // == m0*inv, m1*inv
+  );
+  ```
+  and keep line 58 evaluating the *unscaled* `spline3_hermite(t, key0.value, key1.value, m0, m1)`. (Scaling the whole plane by `1/time_delta` scales every distance by the same factor, so the argmin is preserved and now matches the real-space metric used at line 60.)
+- **Confidence**: Confirmed
+
+---
+
+### ANIM-2 `AnimationTrackPlayback` constructor seeks to absolute 0, not `track.timeStart`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/keyed2/AnimationTrackPlayback.js:36`
+- **Defect**: Line 16 correctly sets `this.position = track.timeStart`, then line 36 overwrites it with `this.setPosition(0)`. For a track whose first key is not at t=0, `setPosition(0)` runs `keyLowerBoundIndexAt(0)`, which returns `-1` ("no key at or before this time"). `__lastKeyIndex` is then `-1`, and `readKeyValues(-1, result)` computes `offset = -propertyCount` and reads off the front of `keyValues`, producing `undefined` → `NaN` in the `Float64Array` value buffer. `reset()` (line 70) and `AnimationBehavior.initialize` (`keyed2/behavior/AnimationBehavior.js:37`) both use `track.timeStart`, so the constructor is the odd one out.
+- **Failure scenario**:
+  ```js
+  const t = new AnimationTrack(['alpha']);
+  t.addKey(1, [10]);            // timeStart = 1
+  t.addKey(2, [20]);            // timeEnd   = 2
+  t.addTransition(0, TransitionFunctions.Linear);
+
+  const p = new AnimationTrackPlayback(t, cb, null);
+  // __lastKeyIndex === -1, __lastTransitionIndex === -1, __nextKeyTime === 1
+  p.update();                   // cb(NaN)   <-- expected cb(10)
+  p.advance(0.016);             // cb(NaN)
+  ```
+  This is reached on the shipping paths that call `update()` before the first tick: `playTrackRealTime.js:26` ("tick animation to make sure the state is synchronized") and `GUIEngine.js:535` ("force view status to initial key of animation"). With such a track the latter writes `el.style.opacity = NaN` and `view.scale.set(NaN, NaN)`. Playbacks driven through `AnimationBehavior` are shielded because `initialize()` re-seeks to `timeStart`; `playAnimationTrack`/direct `advance()` are not.
+- **Fix**: Change line 36 to `this.setPosition(track.timeStart);` (line 16 then becomes redundant). Note the existing spec `"playback starts at position 0 by default"` only covers a track whose `timeStart` is already 0, so it stays green.
+- **Confidence**: Confirmed
+
+---
+
+### ANIM-3 `advanceKey()` leaves a stale `__lastTransitionIndex` when the transition scan runs off the end
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/keyed2/AnimationTrackPlayback.js:135-146`
+- **Defect**: The scan
+  ```js
+  for (let i = this.__lastTransitionIndex + 1; i < transitionCount; i++) { … }
+  ```
+  only writes `__lastTransitionIndex = -1` in the `startKeyIndex > __lastKeyIndex` branch. If the loop exhausts without entering either branch — which happens whenever the new key is at or past the last entry in `transitionKeys` — the previous transition index survives. `readCurrentValues` then takes the transition branch for a key that has no transition, interpolating where `setPosition` (via `transitionIndexAt`, which returns `-1` for the same time) would hold. The loop-wrap case at lines 112-117 has the same root: `__lastKeyIndex` rewinds to `0` but the scan cursor is never rewound to `0`, so a transition on key 0 is missed after the first loop.
+- **Failure scenario A (no loop)**:
+  ```js
+  const t = new AnimationTrack(['scale']);
+  t.addKey(0, [1]); t.addKey(1, [0]); t.addKey(2, [5]);
+  t.addTransition(0, TransitionFunctions.Linear);   // transitionKeys = [0]
+  const p = new AnimationTrackPlayback(t, cb, null); // __lastTransitionIndex = 0
+  p.advanceKey();   // __lastKeyIndex = 1; loop runs from i=1, transitionCount=1 → no iterations
+  p.update();
+  ```
+  `__lastTransitionIndex` is still `0`, so the segment key1→key2 is Linear-interpolated from `0` toward `5`; seeking to the same time with `setPosition(1.0)` yields `__lastTransitionIndex === -1` and holds `0`. Two different poses for the same time on the same track.
+- **Failure scenario B (loop wrap)**: same track plus `t.addTransition(1, TransitionFunctions.EaseOut)` and `p.setLoop(true)`. Advance to the last key (`__lastTransitionIndex === 1`), then `advanceKey()` wraps `__lastKeyIndex` to `0`; the scan starts at `i = 2 >= transitionCount`, so `__lastTransitionIndex` stays `1`. The key0→key1 segment is now driven by `transitionFunctions[1]` (EaseOut) instead of `transitionFunctions[0]` (Linear) — the second and every later loop iteration eases differently from the first.
+- **Fix**: Clear the cursor before scanning and rewind it on wrap:
+  ```js
+  if (wrapped) { this.__lastTransitionIndex = -1; }        // in the loop branch, before += 1
+  const scan_start = this.__lastTransitionIndex + 1;
+  this.__lastTransitionIndex = -1;                          // default: no transition
+  for (let i = scan_start; i < transitionCount; i++) {
+      const startKeyIndex = transitionKeys[i];
+      if (startKeyIndex === this.__lastKeyIndex) { this.__lastTransitionIndex = i; break; }
+      if (startKeyIndex > this.__lastKeyIndex) { break; }
+  }
+  ```
+- **Confidence**: Confirmed
+
+---
+
+### ANIM-4 `AnimationClipBinding.bind()` cannot bind any clip the engine actually produces
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/clip/AnimationClipBinding.js:64-76`
+- **Defect**: Two independent breaks on the same path.
+  1. `binding_registry[track.type]` keys off `AnimationTrack.type`, which defaults to `""` (`clip/AnimationTrack.js:31`). The only producer of `AnimationClip`/`AnimationTrack` in the tree is `convert_three_clip` → `AnimationTrack.from(curves, track_name)` (`clip/ecd_bind_animation_curve.js:106`), which sets `curves` and `name` and **never sets `type`**. Every track therefore looks up `""`.
+  2. Even with a populated registry, the contract is `new WriterClass()` followed by `writer.bind(root, track.path)`. The only writers that can express a vector/quaternion target — `BoundVector3Writer` and `BoundQuaternionWriter` — take their target in the *constructor* and do not override `bind()`, so they inherit `BoundValueWriter.bind` which unconditionally `throw new Error('Not Implemented')` (`curve/binding/BoundValueWriter.js:19`). The one writer that does implement `bind()`, `BoundPlainNumericPropertyWriter`, writes a single scalar (`this.parent[this.property_name] = data[0]`), so it cannot carry a 3- or 4-component track.
+- **Failure scenario**: Import a glTF, get `const cb = convert_three_clip(node, threeClip)` (this is what `SGMeshAnimationControllerSystem.js:78` does), then retarget it to a second skeleton, which is exactly what `bind()` exists for:
+  ```js
+  cb.bind(other_node, { position: BoundVector3Writer, quaternion: BoundQuaternionWriter });
+  ```
+  → throws `No binding class in registry for track type ''` on the first track. Supply `{ "": BoundVector3Writer }` to get past that and it throws `Not Implemented` from `writer.bind`. Note that `bind()` also `splice`s `this.tracks` empty *before* the throw (line 54), so the binding is left destroyed — a clip that rendered fine before the retarget attempt now writes nothing.
+- **Fix**: (a) set `type` in `convert_three_clip` from the property name it already computes (`three_track.name.split('.')` last part, or `three_track.ValueTypeName`) before `AnimationTrack.from(...)`; (b) give `BoundVector3Writer`/`BoundQuaternionWriter` no-arg constructors plus a real `bind(root, path)` that resolves the target the way `bind_property_writer` does, so they satisfy the registry contract; and (c) build the new track list into a local array and only assign it over `this.tracks` once every track bound, so a failure leaves the previous binding intact.
+- **Confidence**: Confirmed
+
+---
+
+### ANIM-5 CUBICSPLINE quaternion tracks are not hemisphere-aligned
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/clip/ecd_bind_animation_curve.js:66-67`
+- **Defect**: The alignment guard is `interpolation === AnimationInterpolationKind.Linear && track.ValueTypeName === 'quaternion'`. A glTF `CUBICSPLINE` rotation track resolves to `AnimationInterpolationKind.CubicTangents` (line 26/32) and so skips `hemisphere_align_quaternion_values` entirely, yet it is still decomposed into four independent scalar Hermite curves (line 74-89) and reassembled by `BoundQuaternionWriter.write` → `fromArray` + `normalize`. Component-wise interpolation across a key pair with a negative dot product takes the long arc. (This is *not* the already-fixed LINEAR case; the in-code comment acknowledges the CubicTangents path as "not yet aligned".)
+- **Failure scenario**: A Blender-exported glTF with `CUBICSPLINE` rotation on a bone, with adjacent keys `q0 = (0, 0, 0, 1)` (identity) and `q1 = (0, 0, −0.0872, −0.9962)` (a −10° Z rotation written in the negative hemisphere; `dot = −0.9962`). Per-component Hermite at the midpoint gives roughly `(0, 0, −0.0436, 0.0019)`; after `normalize()` that is ≈ `(0, 0, −0.999, 0.044)`, i.e. ~175° of Z rotation. The bone whips through nearly a full turn between two keys that are 10° apart, and passes through a near-degenerate quaternion where the normalize is numerically unstable.
+- **Fix**: Align CubicTangents quaternion tracks too, but negate the *whole key triple* — a CUBICSPLINE key is `[inTangent, value, outTangent]` per component, so a sign flip on the value must flip that key's in- and out-tangents as well or the tangents will fight the values. That needs a CubicTangents-aware variant of `hemisphere_align_quaternion_values` operating on a stride of `3 * component_count` and deciding the flip from the value sub-block.
+- **Confidence**: Confirmed
+
+---
+
+### ANIM-6 `acquireInjectedKeyframePosition` uses `time === 0` / `time >= 0` as "unset" sentinels
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/curve/draw/isInjectedKeyframeInBounds.js:76-86`
+- **Defect**: `prevKeyframeRef` and `nextKeyframeRef` are `new Keyframe()`, i.e. `time = 0, value = 0`. The bracketing scan then uses those zeros as sentinels: `kf.time >= prevKeyframeRef.time` treats "0" as "nothing found yet", and `nextKeyframeRef.time === 0` is the "still unset" test. Both are wrong for a curve that has keys at or before t = 0 — `0` is a legitimate keyframe time, and a legitimate keyframe time can be negative.
+- **Failure scenario**: A curve with keys at times `−2, −1, 0, 1` (the editor's frame pans freely into negative time, and `position_canvas_to_curve` maps whatever is on screen). The user clicks on the curve at `timeSplicePosition = −1.5`, which passes the `curveTimePos > curve.keys[0].time` gate. The scan then:
+  - `kf(−2)`: `−2 <= −1.5` ✓ but `−2 >= 0` ✗ → **prev is never captured**, stays the phantom `(0, 0)`;
+  - `kf(−1)`: `−1 >= −1.5` ✓ and `next.time === 0` ✓ → next = `kf(−1)`.
+
+  `segmentTimeDiff = −1 − 0 = −1`, `segmentTimeTravel = −1.5 − 0 = −1.5`, `segmentTimeSplitRatio = 1.5`. `animation_curve_subdivide` is then called with `t = 1.5` (its `assert.ok(t >= 0 && t <= 1)` is compiled out in prod) between the phantom `(0,0)` and `kf(−1)`, so the injected keyframe gets an extrapolated value computed from a keyframe that does not exist. The key lands on the curve at the right time with a visibly wrong value and wrong tangents.
+  A second, independent instance of the same sentinel: with keys at `−1, 0, 1` and a splice at `−0.5`, `kf(0)` is copied into `nextKeyframeRef` but leaves `nextKeyframeRef.time === 0`, so `kf(1)` overwrites it — the "next" key is two keys away.
+- **Fix**: Drop the sentinels and bracket by index, e.g. `const i = curve.getKeyIndexLow(timeSplicePosition);` then `prev = curve.keys[i]`, `next = curve.keys[i + 1]` (with an early-out when `i + 1 >= curve.length`). `getKeyIndexLow` already does this correctly and handles duplicate times.
+- **Confidence**: Confirmed
+
+---
+
+### ANIM-7 `isNotAlreadyAligned` is never called, and the comparison it makes is inverted
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/curve/draw/build_tangent_editor.js:243, 254`
+- **Defect**: Two errors that partially mask each other.
+  1. Line 254: `if (enableTangentAlignment.getValue() === true && isNotAlreadyAligned)` tests the *function object*, not its result. A function is always truthy, so the guard is a no-op.
+  2. Line 243: the predicate itself is `!(keyframe.inTangent === -keyframe.outTangent)`. Alignment in this editor means `inTangent === outTangent` — that is what the drag-time alignment branch produces (`updateTangentValues`, lines 55-63, sets `inTangent = outTangent`) and what `AnimationCurve.alignTangents` produces for a smooth key. The `-` makes the predicate report a *corner* (`in = 1, out = −1`) as "already aligned" and a correctly aligned key (`in = out = 2`) as "not aligned".
+- **Failure scenario**: Select a keyframe whose tangents are already equal, e.g. `Keyframe.from(0.5, 1, 2, 2)`, and tick the "align tangents" checkbox. `modifyTangentAlignmentPosition` runs, computes `avgTangent = 2`, writes the same values back, and still calls `actionProcessor.mark('auto move tangents')` + `actionProcessor.do(new TangentChangeAction(...))`. An undo entry that changes nothing is pushed onto the stack; Ctrl+Z afterwards consumes a step with no visible effect. Conversely, if the missing `()` is added without also fixing the `-`, a corner key (`in = 1, out = −1`) would silently refuse to align — the checkbox would appear to do nothing.
+- **Fix**: `… && isNotAlreadyAligned()` **and** change the predicate body to `return keyframe.inTangent !== keyframe.outTangent;`. (Separately, `Math.abs(newTangent) > Infinity` on line 249 is never true; if a non-finite guard is wanted it should be `!Number.isFinite(newTangent)`.)
+- **Confidence**: Confirmed
+
+---
+
+## Status of the "already known, unconfirmed" items
+
+| Item | Status |
+| --- | --- |
+| `AnimationGraph` JSON dropping state `name`/`tags` | **FIXED** — `writeAnimationGraphDefinitionToJSON.js:69-71` now emits `name` and `tags` for states (and `name`/`tags` for clips); `readAnimationGraphDefinitionFromJSON.js:80-88` destructures `{ motion, type, name, tags = [] }` and assigns both back. |
+| `startingSate` typo | **STILL PRESENT** — the misspelling is load-bearing across the field (`AnimationGraphDefinition.js:29`), the JSON key (`writeAnimationGraphDefinitionToJSON.js:100` / `readAnimationGraphDefinitionFromJSON.js:25,130`), the binary adapter (`AnimationGraphDefinitionSerializationAdapter.js:154,295`) and both readers (`AnimationGraph.js:160,350`). Consistent everywhere, so no behavioural defect — renaming requires a JSON migration. |
+| `AnimationClip.repeatCount` default | **FIXED** — `engine/ecs/animation/AnimationClip.js:9` initialises `new ObservedInteger(1)` and `fromJSON` (lines 83-87) falls back to `this.repeatCount.set(1)` when the field is absent. `toJSON`/`toBinaryBuffer`/`fromBinaryBuffer` all carry the field, so the three paths agree. |
+
+---
+
+## Areas checked and found clean
+
+- **`engine/interpolation/` (whole package)** — `InterpolationSystem` link/unlink is symmetric, `snap` is consumed exactly once per set, per-source playout windows are sampled once per frame and cleared each update, `PoseInterpolationAdapter` does hemisphere-corrected nlerp with renormalize and reduces correctly when `first_offset === second_offset`, `TransformPoseSerializationAdapter` round-trips the same 7 × Float64 layout it declares, `InterpolationLog.interpolate` never reads a stale scratch offset for a tick it failed to locate, and `locate`'s page walk matches the page layout `begin_tick`/`begin_record` write.
+- **`spline3_hermite_reverse`** — verified against `R(u) = H(1−u)`: `R(0) = p1`, `R(1) = p0`, `R'(0) = −m1`, `R'(1) = −m0`; the written order `[p1, p0, −m1, −m0]` matches the `[p0, p1, m0, m1]` layout, and double-reversal is exactly the identity.
+- **`spline3_hermite_apply_transform`** — column-major indexing is right (`m4[0,4,8,12]` for x′), endpoints take the translation column and tangents do not, and the 12 outputs are in the declared `p0/p1/m0/m1` order.
+- **`spline3_hermite_bounds`** (scale-relative change) — the derivative quadratic `a = 3(m0+m1+2p0−2p1)`, `b = −2(2m0+m1+3p0−3p1)`, `c = m0` matches `H′(t)` exactly; the relative `epsilon = max3(|a|,|b|,|c|)·1e-12` correctly degrades to the linear branch without losing interior extrema on small-coordinate curves.
+- **`spline3_hermite_nearest_point`** quintic coefficients — expanded by hand, all six match `(t − ref_t) + (p(t) − ref_p)·p′(t)`. The bug in ANIM-1 is entirely at the call site.
+- **`curve_from_track_data_discrete`** — the reverse `splice` produces `[(t0,v0),(t1,v0),(t1,v1),(t2,v1),(t2,v2)]`; walked through `getKeyIndexLow`/`evaluate` at `t < t1`, `t = t1`, `t1 < t < t2`, `t = t2` and every case gives correct step behaviour with no zero-span division.
+- **`curve_from_track_data_linear`** + `alignTangents` — for each segment `k0.outTangent == k1.inTangent == (v1−v0)/(t1−t0)`, so the Hermite degenerates to exactly the straight line; coincident keys are handled by the `time_span === 0 → 0` branch.
+- **`Tween`** ping-pong turnaround — at `timeElapsed = N·duration`, `cycleWhole = N` and `cycleFraction = 0` give `state = 1` for odd `N` and `0` for even `N`, which is the correct reversal at both ends; the non-oscillating branch fires `ended` once (`destroy()` removes the driving entity in the same call).
+- **`AnimationTrackPlayback.advance`** event semantics — `ended` fires exactly once per forward crossing for a delta larger than the whole clip, and does not re-fire while parked past `timeEnd`; the negative-delta branch correctly avoids the one-shot.
+- **`downsample_float_array_curve_by_error`** — ping-pong buffer sizes (`n/2` and `n/4`) are never overrun as `current_size` halves, and the `target_samples === 1` special case stops the loop before `downsample_float_array` can be handed an odd size.
+- **`animation_curve_optimize`** — the `i--; key_count--` removal step keeps the cursor correct, and the first/last keys are structurally protected.
+- **`animation_curve_fit`** — `calculateTangent` boundary/interior cases are consistent with the tangent convention `evaluate_two_key_curve` uses (`slope × segment duration`), the recursion strictly shrinks, and `splitIndex === -1` is unreachable when `maxSegmentError > maxError`.
+- **`table_find_min_index_in_ordered_column`** — returns the correct lower bound (`minIndex − 1`) on a miss and `−1` before the first sample, which `findLowSampleIndexByTime` clamps.
+- **`AnimationCurveView.draw_key_tangents`** — `in_angle = −atan2(inTangent, −1)` is the angle of `(−1, −m)`, correct for a backward-pointing handle in curve space before the y-flipping transform; `build_tangent_editor.handleTangentUpdate`'s screen-space angles (`π − atan2(in,1)`, `−atan2(out,1)`) are the correct y-down equivalents.