@unrulysystems/native-motion-core 0.1.0-alpha.0

package/dist/driver/reference.js

@@ -0,0 +1,757 @@
+// SPEC-NATIVE-DRIVER §Requirements — the reference in-core Driver (REQ-DRIVER-013/020). A concrete,
+// host-agnostic `Driver` the fake host adapter and the deterministic conformance drive; the native worklet
+// and web drivers are the substrate-bound peers of this same interface. It composes the built ladder and
+// forks nothing (REQ-DRIVER-003): the SPRING/TIMING generators (via the COMPONENT seconds→ms converters)
+// supply every trajectory, `retargetSpring` supplies spring continuity, and the pure `stepProp` advances
+// each frame. A command seeds state once (O(1)); `step` reads only seeded state — zero per-frame JS logic
+// beyond the pure advance (REQ-DRIVER-013). An element quiesces when all its animations settle
+// (REQ-DRIVER-020). Host-agnostic (REQ-CORE-003): relative imports only.
+import { InvalidTransitionError, toDelayMs, toKeyframesConfig, toRepeatFoldOptions, toSpringConfig, toTimingConfig, } from "../component/index.js";
+import { isDurationZeroInstantTransition, isTimingLaneTransition, toTimingLaneConfig, } from "../component/transition.js";
+import { delayGenerator } from "../delay.js";
+import { inertiaGenerator } from "../inertia.js";
+import { instantFinalKeyframe, instantGenerator } from "../instant.js";
+import { keyframesGenerator } from "../keyframes.js";
+import { buildRepeatedGenerator, iterationMeasurementLane } from "../repeat.js";
+import { timingGenerator } from "../timing.js";
+import { resolveSpring, resolveSpringGenerator, retargetSpring, springKeyframeCountRefusal, } from "../transition.js";
+import { applyPathProgress } from "../motion-arc.js";
+import { adaptPreparedDriver } from "./prepare.js";
+import { stepProp } from "./step.js";
+// Clear the gesture hold on ONE prop (the matching release/stop command owns it now). Idempotent —
+// clearing an unheld prop is a no-op, so the heldCount stays exact (review r7 major 23).
+function releaseHold(element, key) {
+    if (element.heldVelocity[key] !== undefined) {
+        delete element.heldVelocity[key];
+        element.heldCount--;
+    }
+}
+// Build a fresh generator for a `start`: from the resolved base to the target, under the transition. Springs
+// and tweens are selected by `transition.type` — with one pin-mandated addition (REQ-TIMING-006): an
+// authored duration-ONLY bag (type omitted) also takes the timing generator, the pin's
+// `type = keyframesGenerator` default for any DEFINED transition. Spring remains the fallback for
+// everything else, reusing the COMPONENT seconds→ms
+// converters + the built generators — no forked math (REQ-DRIVER-003). `velocity` is the REQ-DRIVER-023
+// seed (the gesture release's platform handoff); a tween is position-based and ignores it by construction,
+// kept explicit here so the contract reads at the seam.
+// Normalize a PropTransition to the authored inputs the generators consume (R8 M2, consult
+// agent-2026-07-19-e715fd). A controller-resolved default (`DefaultTransition`) carries shapes the
+// authored `Transition` cannot: a `type:'keyframes'` default normalizes to the equivalent tween — an
+// ABSENT `ease` is preserved so the keyframes generator keeps its intrinsic per-segment easeInOut (the
+// 800ms default); a `type:'spring'` default carries `restSpeed` (Motion's default-transitions
+// override), returned alongside to thread into the spring's settle threshold. Since U7c
+// (REQ-SPRING-014) an AUTHORED spring may also carry restSpeed/restDelta — the extraction below
+// reads the same key either way, and `springConfigWithRest` threads it over `toSpringConfig`'s own
+// passthrough, so authored and default thresholds reach the solver identically.
+function normalizeTransition(transition) {
+    if (transition.type === 'keyframes') {
+        return {
+            authored: {
+                type: 'tween',
+                duration: transition.duration,
+                ...(transition.ease !== undefined ? { ease: transition.ease } : {}),
+                ...(transition.delay !== undefined ? { delay: transition.delay } : {}),
+                ...(transition.repeat !== undefined ? { repeat: transition.repeat } : {}),
+                ...(transition.repeatType !== undefined ? { repeatType: transition.repeatType } : {}),
+                ...(transition.repeatDelay !== undefined ? { repeatDelay: transition.repeatDelay } : {}),
+            },
+            restSpeed: undefined,
+        };
+    }
+    const restSpeed = transition.type === 'spring' && 'restSpeed' in transition ? transition.restSpeed : undefined;
+    return { authored: transition, restSpeed };
+}
+// Thread a default spring's `restSpeed` (settle threshold) into the resolved SpringConfig;
+// authored restDelta/restSpeed (U7c) already flow through `toSpringConfig`'s passthrough.
+function springConfigWithRest(transition, restSpeed) {
+    return restSpeed !== undefined
+        ? { ...toSpringConfig(transition), restSpeed }
+        : toSpringConfig(transition);
+}
+/**
+ * T18-a (REQ-API-049 / REQ-DRIVER-031): apply the repeat fold around whatever trajectory the
+ * transition resolves to. The fold is generator-agnostic, so this wraps the ONE unrepeated
+ * construction below rather than teaching any generator about repetition, and it delegates to
+ * core's shared `buildRepeatedGenerator` — the same call the worklet driver makes. Sharing the call
+ * is necessary but NOT sufficient for parity: both backends shared it and still skewed, because
+ * only the start seam folded. What actually holds the two backends together is the executing floor,
+ * `driverParity.differential.test.ts`. (`check:resolution-skew` compares package.json export
+ * conditions — module ENTRY-POINT resolution — and has never inspected either driver.)
+ *
+ * An inertia transition never folds — and is not REFUSED, which an earlier draft of this comment
+ * claimed (fix-up review). There is nothing to refuse: `inertia` is absent from the public
+ * `TransitionType` (`'spring' | 'tween' | false`), so it is unauthorable, reaching this seam only as the
+ * command layer's own gesture-release settle, which carries no authored options. The branch is
+ * therefore a defensive skip over a shape that cannot carry a fold, not a severity boundary.
+ */
+function startGenerator(transition, to, from, velocity) {
+    const { authored } = normalizeTransition(transition);
+    // U7a + transition-default-selection F5: the instant lane — the pin's makeAnimationInstant
+    // (motion-dom@12.42.2 motion-value.ts:89-98). The guard is the pin's, type-independent:
+    // `type: false` (U7a) OR `duration === 0 && !repeatDelay` (F5). NO trajectory generator, NO
+    // fold: the final keyframe commits on the driver's next update tick (never synchronously), and
+    // the authored delay is honored through the shared rebase. A repeatDelay-bearing duration-zero
+    // bag is exempt and keeps its generator below (the zero-length timing base there takes the same
+    // instant SHAPE so the fold's plays stay zero-length). The inertia narrow keeps the union
+    // discriminated for the delay crossing.
+    if (authored.type !== 'inertia' &&
+        (authored.type === false || isDurationZeroInstantTransition(authored))) {
+        return delayGenerator(instantGenerator(instantFinalKeyframe(to))({ from, velocity: 0 }), toDelayMs(authored));
+    }
+    const fold = authored.type === 'inertia' ? null : toRepeatFoldOptions(authored);
+    // T18-b (REQ-TIMING-004 / REQ-DRIVER-032): the delay rebase wraps AROUND the fold-or-generator —
+    // core's shared `delayGenerator`, the ONE rebase seam the worklet driver calls identically at
+    // BOTH phases. An inertia release is command-layer-only and carries no authored delay (mirroring
+    // the fold's defensive skip, not a severity boundary). `toDelayMs` is the seconds→ms crossing.
+    // Sharing the call is not parity on its own — `driverParity.differential.test.ts` executes both
+    // backends over delayed commands and compares frame for frame.
+    const delayMs = authored.type === 'inertia' ? 0 : toDelayMs(authored);
+    if (fold === null)
+        return delayGenerator(unrepeatedGenerator(transition, to, from, velocity, false), delayMs);
+    // Legs are built EAGERLY and passed as values — never a factory the fold would invoke, which on
+    // the UI runtime is the wrong-runtime crash class (`check:worklet-closures`). The worklet driver
+    // mirrors this shape exactly.
+    const leg = fold.repeatType === 'mirror'
+        ? { type: 'mirror', mirrored: unrepeatedGenerator(transition, to, from, velocity, true) }
+        : { type: fold.repeatType };
+    const folded = buildRepeatedGenerator(fold.repeat, leg, fold.repeatDelayMs, unrepeatedGenerator(transition, to, from, velocity, false), knownIterationDurationMs(transition, to));
+    if (folded instanceof Error)
+        throw repeatRefusal(fold, folded);
+    return delayGenerator(folded, delayMs);
+}
+/**
+ * The fold's refusal, TYPED (T18-a fix-up, review MAJOR). Whether a trajectory ever settles depends
+ * on the DISTANCE travelled and the seed velocity, so it is not decidable from the authored
+ * transition and validation cannot own it — this seam, which holds the real generator, does. It
+ * arrived here as a bare `Error`, which is what let the failure surface as an anonymous driver-lane
+ * fault instead of a refusal naming the offending property.
+ */
+// alloc-ok: lifecycle-edge — built only on the refusal path, once per rejected animate command.
+function repeatRefusal(fold, refusal) {
+    return new InvalidTransitionError(undefined, 'repeat', fold.repeat, refusal.message);
+}
+/**
+ * The transition's own resolved iteration length in ms, or null when only a scan can measure it —
+ * mirroring the pin's `calculatedDuration` rule (`spring.ts:378`: `isResolvedFromDuration ?
+ * duration || null : null`; the keyframes generator always knows its own `duration`).
+ */
+function knownIterationDurationMs(transition, to) {
+    const { authored } = normalizeTransition(transition);
+    // Narrows `authored` off the inertia arm as well as answering the lane's first question.
+    if (authored.type === 'inertia')
+        return null;
+    // The lane comes from core's ONE rule, never re-derived here (T18-a fix-up review MAJOR: three
+    // parallel copies of it drifted across four rounds).
+    const lane = iterationMeasurementLane(typeof to === 'number', authored.type === 'spring', 
+    // REQ-TIMING-006 + F6: the untyped timing-lane bag (duration-only OR ease-only) measures the
+    // timing lane (the authored duration, or the generator's 300ms default), never the
+    // duration-spring's resolved settle.
+    authored.type === 'tween' || isTimingLaneTransition(authored));
+    if (lane === 'keyframes')
+        return toKeyframesConfig(authored).duration ?? null;
+    if (lane === 'timing')
+        return toTimingConfig(authored).duration ?? null;
+    const resolved = resolveSpring(toSpringConfig(authored));
+    // `duration || null`: a zero-length resolution is NOT a known duration — the scan measures it,
+    // and the fold's own refusal then names the degenerate iteration (T18-a L3).
+    return resolved.calculatedDuration !== null && resolved.calculatedDuration > 0
+        ? resolved.calculatedDuration
+        : null;
+}
+/**
+ * One unrepeated trajectory. `reversed` builds the MIRRORED leg (the pin's second generator): the
+ * origin and target swap and the seed velocity negates, and a keyframe list is reversed AFTER its
+ * nulls resolve — `times`/`ease` are deliberately untouched, exactly as the pin leaves them, so a
+ * mirrored leg is a genuinely different trajectory rather than a time-reflection.
+ */
+function unrepeatedGenerator(transition, to, from, velocity, reversed) {
+    const { authored, restSpeed } = normalizeTransition(transition);
+    if (typeof to !== 'number') {
+        if (reversed && authored.type !== 'inertia') {
+            // Resolve from-current nulls BEFORE reversing (R8-F2): the pin mirrors the RESOLVED
+            // keyframes, and a null that slid to the tail would re-read `from` at the wrong end.
+            const resolvedKeyframes = to.map((value) => (value === null ? from : value));
+            const mirroredKeyframes = [...resolvedKeyframes].reverse();
+            const mirroredFrom = mirroredKeyframes[0] ?? from;
+            if (authored.type === 'spring') {
+                return springKeyframeGenerator(authored, restSpeed, mirroredKeyframes, mirroredFrom, -velocity);
+            }
+            return keyframesGenerator(mirroredKeyframes, toKeyframesConfig(authored))({ from: mirroredFrom, velocity: 0 });
+        }
+    }
+    if (typeof to !== 'number') {
+        if (authored.type === 'inertia') {
+            // R16 shape totality (review major 3, G-INV-8/-10): a keyframe array under an inertia
+            // transition is a command-shape defect — the worklet driver throws the identical class;
+            // never silently run inertia ignoring the array.
+            throw new Error('a keyframe array cannot run under an inertia transition (REQ-GESTURE-023, R16).');
+        }
+        // A keyframe ARRAY HONORS `transition.type` (REQ-API-033, R8-F1). An EXPLICIT spring interpolates
+        // exactly two keyframes (Motion's `assertTwoKeyframes`): two → spring physics; a >2 spring FAILS
+        // LOUD naming the successor — it never reaches `resolveSpringGenerator` to be silently accepted. A
+        // tween or the DEFAULT routes the array THROUGH the keyframes generator (even offsets, per-segment
+        // ease); position-based, the seed velocity is dropped and a null FIRST element reads `from` (R8-F2).
+        if (authored.type === 'spring')
+            return springKeyframeGenerator(authored, restSpeed, to, from, velocity);
+        return keyframesGenerator(to, toKeyframesConfig(authored))({ from, velocity: 0 });
+    }
+    if (authored.type === 'inertia') {
+        // R16 (REQ-GESTURE-023): the gesture free-drag release's two-phase generator. `to` is the
+        // mirror terminal (the clamped ideal); the generator recomputes its own ideal from the seed
+        // and owns the walls via the boundary spring. The seed velocity is the platform release
+        // velocity, momentum-gated upstream (REQ-GESTURE-027).
+        return inertiaGenerator({
+            power: authored.power,
+            timeConstant: authored.timeConstant,
+            bounceStiffness: authored.bounceStiffness,
+            bounceDamping: authored.bounceDamping,
+            restDelta: authored.restDelta,
+            restSpeed: authored.restSpeed,
+            ...(authored.min !== undefined ? { min: authored.min } : {}),
+            ...(authored.max !== undefined ? { max: authored.max } : {}),
+        })({ from, velocity });
+    }
+    // The scalar mirrored leg: origin and target swap, and the seed velocity negates (the pin builds
+    // its second generator with `velocity: -velocity`).
+    const scalarTo = reversed ? from : to;
+    const scalarFrom = reversed ? to : from;
+    const scalarVelocity = reversed ? -velocity : velocity;
+    // REQ-TIMING-006 + transition-default-selection F1/F6: an authored duration-ONLY bag (type
+    // omitted) OR a defined ease-only bag takes the pin's keyframes/timing generator — monotone,
+    // `easeOut` by default when NO ease spelling is authored, the authored ease verbatim for the
+    // ease-only form (the pin's defined-typeless lane at the 300ms default, JSAnimation.ts:106-116) —
+    // never the old omitted-type duration-spring (U7a finding A, device peak 1.046) and never the
+    // REQ-SPRING-003 generic spring for an ease-only bag. F1 gives the TYPED tween the same easeOut
+    // base through the ONE config builder (component/transition.ts `toTimingLaneConfig`);
+    // `isTimingLaneTransition` is the single-sourced untyped arm.
+    if (authored.type === 'tween' || isTimingLaneTransition(authored)) {
+        // F5: a zero-length timing base takes the pin's makeAnimationInstant SHAPE — hold the seed at
+        // t ≤ 0, commit the final keyframe past it (motion-value.ts:89-98). Only repeatDelay-bearing
+        // bags reach this (a zero duration without one routes to the instant lane above); it keeps
+        // the fold's zero-length plays from committing at the command edge.
+        if (authored.duration === 0) {
+            return instantGenerator(scalarTo)({ from: scalarFrom, velocity: 0 });
+        }
+        return timingGenerator(scalarTo, toTimingLaneConfig(authored))({ from: scalarFrom, velocity: 0 });
+    }
+    return resolveSpringGenerator(scalarTo, springConfigWithRest(authored, restSpeed))({ from: scalarFrom, velocity: scalarVelocity });
+}
+// R8-F1: a keyframe ARRAY under an EXPLICIT spring. A spring interpolates EXACTLY two keyframes — the
+// pinned Motion throws `spring-two-frames` for more. Two keyframes run spring physics from keyframes[0]
+// (the explicit origin; a null first element reads `from`, from-current R8-F2) to keyframes[1] (the
+// target); a longer array FAILS LOUD naming the successor so it never reaches `resolveSpringGenerator`.
+function springKeyframeGenerator(transition, restSpeed, keyframes, from, velocity) {
+    const countRefusal = springKeyframeCountRefusal(keyframes.length);
+    if (countRefusal !== null)
+        throw countRefusal;
+    const origin = keyframes[0];
+    const target = keyframes[1];
+    // Validation guarantees a length-2 array whose only legal null is index 0 and whose target parses;
+    // the guard keeps this TOTAL under noUncheckedIndexedAccess (never hit for a valid target).
+    if (origin === undefined || target === undefined || target === null) {
+        throw new Error(`malformed two-keyframe spring array — a non-null numeric target is required (REQ-API-033).`);
+    }
+    const seedFrom = origin === null ? from : origin;
+    return resolveSpringGenerator(target, springConfigWithRest(transition, restSpeed))({
+        from: seedFrom,
+        velocity,
+    });
+}
+// Build a generator that CONTINUES from a live property's current value+velocity to a new target (REQ-API-
+// 003 interruption continuity). Springs use SPRING's own `retargetSpring` (carries the analytic velocity);
+// tweens are position-based, so they reseed from the live value with no carried velocity.
+function unrepeatedRetargetGenerator(transition, live, to) {
+    // Normalize first, exactly as `unrepeatedGenerator` does: the authored form is what the config
+    // converters accept, and a `type:'keyframes'` default normalizes to its equivalent tween rather
+    // than falling through to the spring branch. The disjoint inertia arm runs FIRST so the union
+    // narrows to `Transition` for the converter accept below (arms are mutually exclusive; the
+    // order swap changes nothing observable).
+    const { authored, restSpeed } = normalizeTransition(transition);
+    if (authored.type === 'inertia') {
+        // R16: a retarget INTO an inertia transition re-seeds the two-phase generator from the LIVE
+        // sample — the same continuity law as a spring retarget (C0/C1). The worklet driver has always
+        // done this; the reference driver used to fall through to the spring branch and hand an inertia
+        // transition to `toSpringConfig`. Pinned as a parity row in driverParity.differential.test.ts.
+        const at = live.generator.sample(live.elapsed);
+        return unrepeatedGenerator(transition, to, at.value, at.velocity, false);
+    }
+    if (authored.type === 'tween' || isTimingLaneTransition(authored)) {
+        // F5: the zero-length timing base takes the instant SHAPE here too — the same routing as
+        // `unrepeatedGenerator`, seeded from the live value (no cross-seam skew).
+        if (authored.duration === 0) {
+            return instantGenerator(to)({ from: live.value, velocity: 0 });
+        }
+        return timingGenerator(to, toTimingLaneConfig(authored))({ from: live.value, velocity: 0 });
+    }
+    return retargetSpring(live.generator, live.elapsed, to, springConfigWithRest(authored, restSpeed));
+}
+/**
+ * T18-a fix-up (review BLOCKER, two independent reviewers): a retarget carries the repeat fold,
+ * exactly as `start` does. For a repeating animation this seam is not an edge case, it is the
+ * COMMON one — an endless repeat is never `done`, so every changed scalar animate key routes here
+ * instead of to `start`. Dropping the fold stopped the loop permanently on the first retarget and
+ * then fired the completion the transition says can never come. The internal tell was that the
+ * gesture-HELD branch already folds (it builds through `startGenerator`), so the same authoring
+ * repeated or not depending on whether a finger happened to be down.
+ *
+ * The pin rebuilds every retarget as a fresh animation spreading `...valueTransition`
+ * (`motion-dom/src/animation/interfaces/motion-value.ts`), so repeat/repeatType/repeatDelay ride
+ * through unchanged. The fold's BASE here is the continuity-carrying retarget generator, so
+ * iteration 0 keeps the live value and analytic velocity (REQ-API-003) and each later iteration
+ * replays from that same seed.
+ */
+function retargetGenerator(transition, live, to) {
+    const { authored } = normalizeTransition(transition);
+    // U7a + F5: the instant lane at the retarget seam — the pin's guard is type-independent
+    // (`type: false` OR `duration === 0 && !repeatDelay`, motion-value.ts:89-98). Commit the new
+    // target on the next update tick from the live value, honoring the retarget's OWN authored
+    // delay (the pin starts a fresh animation per retarget). No fold, exactly as `startGenerator`.
+    // The inertia narrow keeps the union discriminated for the delay crossing.
+    if (authored.type !== 'inertia' &&
+        (authored.type === false || isDurationZeroInstantTransition(authored))) {
+        return delayGenerator(instantGenerator(to)({ from: live.value, velocity: 0 }), toDelayMs(authored));
+    }
+    const base = unrepeatedRetargetGenerator(transition, live, to);
+    const fold = authored.type === 'inertia' ? null : toRepeatFoldOptions(authored);
+    // T18-b (REQ-DRIVER-032): a retarget applies its OWN delay, as the pin starts a fresh animation
+    // per retarget. The rebase wraps the (possibly folded) retarget trajectory — AROUND the fold,
+    // the same core seam as `startGenerator`. A mid-delay retarget reseeds from the held first
+    // keyframe at velocity 0, because the outgoing delay wrapper reports exactly that while held
+    // (packet L2: no motion to be continuous WITH).
+    const delayMs = authored.type === 'inertia' ? 0 : toDelayMs(authored);
+    if (fold === null)
+        return delayGenerator(base, delayMs);
+    // Legs eager, never a factory the fold would invoke — the worklet driver mirrors this shape
+    // exactly (`check:worklet-closures`). The mirrored leg swaps origin/target around the LIVE value.
+    const leg = fold.repeatType === 'mirror'
+        ? { type: 'mirror', mirrored: unrepeatedGenerator(transition, to, live.value, 0, true) }
+        : { type: fold.repeatType };
+    const folded = buildRepeatedGenerator(fold.repeat, leg, fold.repeatDelayMs, base, knownIterationDurationMs(transition, to));
+    if (folded instanceof Error)
+        throw repeatRefusal(fold, folded);
+    return delayGenerator(folded, delayMs);
+}
+// A CONTENDING target drifts FROM the committed finger value — never a backward jump off the finger
+// (REQ-DRIVER-026 / G-INV-2, review major 25). A keyframe array's non-null FIRST element would make the
+// generator restart near keyframes[0], rewinding the drift; re-seed the first keyframe from-current
+// (null-first, R8-F2) so the trajectory runs the live value → remaining keyframes. A scalar (springs/
+// tweens already seed from `from`) and an already-null-first array are unchanged. `to` is a captured
+// snapshot, so this reads it once more into a fresh frozen array only at a command/gesture edge.
+function anchorContentionToLive(to) {
+    if (typeof to === 'number' || to[0] === null)
+        return to;
+    return Object.freeze([null, ...to.slice(1)]);
+}
+/**
+ * This backend's OWN verdict on a fold, for one transition and one target, with the boundary
+ * validation `command()` runs first deliberately NOT in the path.
+ *
+ * It exists because the parity floor that guards this rung was structurally half-blind without it
+ * (fix-up review MAJOR): `prepareDriverCommand` calls `validateTransitionRefusal` before reaching
+ * any generator, so a floor that reads `command()`'s throw sees validation's own refusal echoed back
+ * as "the driver refused". Every over-refusal therefore passed — a mutation that made validation
+ * reject 36 executable configs left the floor green. Only a verdict taken from BELOW validation can
+ * decide whether validation is measuring the fold the way this backend does.
+ *
+ * Returns the fold's refusal, or null when this backend would construct and run the generator.
+ *
+ * `from` is a real parameter, not a convenience: a null-first keyframe array (`[null, 100]`, the
+ * from-current form) resolves its first keyframe FROM the live value, so with `from` pinned at 0 it
+ * is indistinguishable from `[0, 100]` and the target axis loses a shape it claims to sweep (round-5
+ * review MINOR).
+ *
+ * Test seam for this package's own parity floor — NOT part of any published entry: exporting it from
+ * `internal-driver` would pull this whole backend into the seam the worklet driver imports.
+ */
+export function referenceFoldRefusal(transition, to, from = 0) {
+    try {
+        startGenerator(transition, to, from, 0);
+        return null;
+    }
+    catch (error) {
+        // Only the fold's own refusal answers this question. Anything else is a different fault and must
+        // not be laundered into a verdict — it propagates.
+        if (error instanceof InvalidTransitionError && error.key === 'repeat')
+            return error;
+        throw error;
+    }
+}
+/**
+ * The same verdict at the RETARGET seam — the second half of the parity floor's oracle.
+ *
+ * Rounds 4-6 each fixed one axis pinned to a constant (`repeat`, then `repeatDelay`), and round 7
+ * found the pattern one level up: the floor's ORACLE was itself pinned to a constant — the `start`
+ * seam of the reference backend — while `buildRepeatedGenerator` has four seams (two backends x two
+ * phases). The retarget seam is not a duplicate of `start`:
+ *
+ *   - it reseeds the scan from the live VALUE, so the distance it measures is the distance from
+ *     wherever the animation currently IS — a different trajectory than `start` measured, which is
+ *     why it can refuse where `start` ran (round-7 review MAJOR). It also carries the live velocity
+ *     into the reseed; that is structurally present but NOT the demonstrated variable — sweeping the
+ *     dwell from 0 to 480ms at a fixed distance changes no verdict, and removing the dwell entirely
+ *     leaves the floor green (round-8 review MINOR). Distance is what moves it;
+ *   - it cannot reach the keyframes lane at all — `DriverCommand`'s retarget targets are numbers, so
+ *     `targetIsNumeric` is constantly true here. The floor's target axis is structurally
+ *     inexpressible at this seam, and its axis is the LIVE STATE instead.
+ *
+ * Taken from BELOW validation for the same reason as `referenceFoldRefusal`: `command()` validates
+ * first, so reading its throw would make the driver echo the boundary and the floor could only ever
+ * catch over-acceptance.
+ *
+ * A fold that cannot even START is reported as refused — "would this backend run it at a retarget"
+ * is answered `no` either way, and conflating them here would make the phase axis lie about which
+ * seam refused.
+ *
+ * Test seam for this package's own parity floor — NOT part of any published entry.
+ */
+export function referenceRetargetFoldRefusal(transition, startTo, from, retargetTo, dwellMs) {
+    let generator;
+    try {
+        generator = startGenerator(transition, startTo, from, 0);
+    }
+    catch (error) {
+        if (error instanceof InvalidTransitionError && error.key === 'repeat')
+            return error;
+        throw error;
+    }
+    // Reach a genuinely live state the way the driver does, so the retarget carries a real velocity.
+    const live = { generator, elapsed: 0, value: from, done: false };
+    stepProp(live, dwellMs);
+    try {
+        retargetGenerator(transition, live, retargetTo);
+        return null;
+    }
+    catch (error) {
+        if (error instanceof InvalidTransitionError && error.key === 'repeat')
+            return error;
+        throw error;
+    }
+}
+export function createReferenceDriver() {
+    // Indexed by handle (a plain number, worklet-friendly). register() appends; the index is the handle.
+    const elements = [];
+    function elementAt(handle) {
+        const element = elements[handle];
+        if (element === undefined) {
+            throw new Error(`unknown element handle ${String(handle)}: it was never registered on this driver.`);
+        }
+        return element;
+    }
+    const backend = {
+        register(initial) {
+            const handle = elements.length;
+            elements.push({
+                active: false,
+                heldCount: 0,
+                committed: { ...initial },
+                heldVelocity: {},
+                props: new Map(),
+                contending: {},
+                path: null,
+            });
+            return handle;
+        },
+        command(handle, command) {
+            const element = elementAt(handle);
+            switch (command.kind) {
+                case 'start': {
+                    // Only a gesture RELEASE (`releasesGesture`) or a `stop` ends a hold. A declarative start on
+                    // a gesture-held prop CONTENDS instead of being skipped (REQ-DRIVER-026, Motion's shared-
+                    // value model): it seeds a generator that drifts the live value while the finger still owns
+                    // the prop, so a mid-drag `animate` change moves the element and the release reads the
+                    // drifted origin (the snap-selection parity fix). The finger's release velocity is preserved
+                    // (liveFor held-velocity precedence, REQ-DRIVER-025); the hold clears only at release/stop.
+                    const releasesGesture = command.releasesGesture;
+                    // PHASE 1 — build every prop's generator WITHOUT mutating element state. A construction that
+                    // throws (an explicit spring on a >2-keyframe array, R8-F1) aborts the WHOLE command here, so
+                    // a rejected multi-prop start applies NOTHING (fail-closed atomicity, review major 19).
+                    const plans = [];
+                    for (const key of Object.keys(command.targets)) {
+                        const target = command.targets[key]; // key came from Object.keys
+                        // A gesture-RELEASE start takes over the prop (its hold clears in phase 2), so it is treated
+                        // as NOT still-held and uses the command's nominal `from`. A start CONTENDING on a prop the
+                        // finger still holds drifts from the CURRENT live value (never `from`) so committed does not
+                        // jump off the finger. An ordinary non-held start uses `from`.
+                        const stillHeld = !releasesGesture && element.heldVelocity[key] !== undefined;
+                        const from = stillHeld ? element.committed[key] : target.from;
+                        // `target` is already the complete immutable REQ-DRIVER-030 snapshot. No caller-owned
+                        // PropTarget or fallback semantics reach this backend.
+                        const to = target.to;
+                        const transition = target.transition;
+                        // A still-held (contending) start drifts from the finger value: seed the first keyframe
+                        // from-current so it never rewinds to keyframes[0] (major 25). A non-held start keeps the
+                        // array's own origin (a plain keyframe start plays [k0 … kN] verbatim).
+                        const generator = startGenerator(transition, stillHeld ? anchorContentionToLive(to) : to, from, target.velocity);
+                        // Seed committed/value from the generator's TICK-0, not the raw `from`: a keyframe array's
+                        // origin is keyframes[0] (or the null-first seed), so committed() matches liveFor()'s
+                        // zero-sample and never shows a one-frame `from` jump (review major dfeaa4bf4bcf). A scalar
+                        // generator samples `from` at t=0 (no-op). A still-held start keeps the finger-authoritative
+                        // committed. sample(0) is a pure read — no mutation, so phase 1 stays side-effect-free.
+                        const seededValue = stillHeld ? from : generator.sample(0).value;
+                        plans.push({ key, stillHeld, seededValue, generator, to, transition });
+                    }
+                    // PHASE 2 — commit every plan. No throw path here, so element state mutates atomically.
+                    for (const plan of plans) {
+                        if (releasesGesture)
+                            releaseHold(element, plan.key);
+                        element.props.set(plan.key, {
+                            generator: plan.generator,
+                            elapsed: 0,
+                            value: plan.seededValue,
+                            done: false,
+                        });
+                        element.committed[plan.key] = plan.seededValue;
+                        // Track the contention target so a later finger write re-anchors this generator (major 29).
+                        // `plan.to` is ALREADY the phase-1 snapshot the generator was built from (captured once,
+                        // review major 20 + 21), so this stores the SAME frozen array — no second read, no skew; a
+                        // released/non-held start owns the prop outright, so clear any prior contention.
+                        if (plan.stillHeld)
+                            element.contending[plan.key] = {
+                                to: plan.to,
+                                transition: plan.transition,
+                            };
+                        else
+                            delete element.contending[plan.key];
+                    }
+                    if (command.path !== undefined) {
+                        const geometry = command.path;
+                        const generator = startGenerator(geometry.transition, 1000, 0, 0);
+                        const seeded = generator.sample(0).value;
+                        element.path = {
+                            progress: { generator, elapsed: 0, value: seeded, done: false },
+                            geometry,
+                        };
+                        element.props.delete('x');
+                        element.props.delete('y');
+                        element.props.delete('pathRotation');
+                        const sample = applyPathProgress(seeded, geometry, false);
+                        if ('x' in element.committed)
+                            element.committed.x = sample.x;
+                        if ('y' in element.committed)
+                            element.committed.y = sample.y;
+                        if (geometry.rotationScale && 'pathRotation' in element.committed)
+                            element.committed.pathRotation = sample.pathRotation;
+                    }
+                    else if (element.path !== null) {
+                        if (element.path.geometry.rotationScale && 'pathRotation' in element.committed)
+                            element.committed.pathRotation = 0;
+                        element.path = null;
+                    }
+                    element.active = element.props.size > 0 || element.heldCount > 0 || element.path !== null;
+                    break;
+                }
+                case 'retarget': {
+                    // BUILD every key first, COMMIT only once all of them succeeded — the same atomicity law
+                    // `start` already carries (review major 36). Building can REFUSE (the fold re-measures from
+                    // the live value, so a `repeat` executable at start can be refused here), and a per-key
+                    // commit left the earlier keys already retargeted when a later one threw. A refused command
+                    // must mutate nothing; the controller's severity lane depends on it, because it reports the
+                    // refusal and lets the remaining keys proceed.
+                    const staged = [];
+                    for (const key of Object.keys(command.targets)) {
+                        const to = command.targets[key]; // key came from Object.keys
+                        const transition = command.targetTransitions?.[key] ?? command.transition;
+                        // A retarget is NEVER the gesture release (the release is a seeded `start`). A retarget on
+                        // a gesture-HELD prop CONTENDS (REQ-DRIVER-026): it seeds a fresh generator from the
+                        // finger-authoritative COMMITTED value (not the possibly-stale generator `live.value` — a
+                        // finger write may have advanced committed past it, review r10 major 29) toward the new
+                        // target, and records the contention so a later write re-anchors it. A non-held prop
+                        // retargets normally with velocity continuity.
+                        const held = element.heldVelocity[key] !== undefined;
+                        let from;
+                        let generator;
+                        if (held) {
+                            from = element.committed[key]; // held ⇒ written ⇒ committed exists
+                            generator = startGenerator(transition, to, from, 0);
+                            staged.push({ key, from, generator, contendTo: to });
+                            continue;
+                        }
+                        else {
+                            // Retarget carries no base — it derives `from` from the in-flight value (continuity), or
+                            // for a registered-but-idle prop, its last committed value. A key that is neither
+                            // in-flight nor committed is a malformed retarget: fail loud, never silently seed 0.
+                            const live = element.props.get(key);
+                            if (live !== undefined) {
+                                from = live.value;
+                                generator = retargetGenerator(transition, live, to);
+                            }
+                            else {
+                                const base = element.committed[key];
+                                if (base === undefined) {
+                                    throw new Error(`cannot retarget '${key}': it was never registered or started on this element.`);
+                                }
+                                from = base;
+                                generator = startGenerator(transition, to, from, 0);
+                            }
+                        }
+                        staged.push({ key, from, generator });
+                    }
+                    // Past this line nothing can refuse, so the commit is all-or-nothing.
+                    if (element.path !== null &&
+                        staged.some(({ key }) => key === 'x' || key === 'y' || key === 'pathRotation')) {
+                        if (element.path.geometry.rotationScale && 'pathRotation' in element.committed)
+                            element.committed.pathRotation = 0;
+                        element.path = null;
+                    }
+                    for (const { key, from, generator, contendTo } of staged) {
+                        if (contendTo === undefined)
+                            delete element.contending[key];
+                        else
+                            element.contending[key] = {
+                                to: contendTo,
+                                transition: command.targetTransitions?.[key] ?? command.transition,
+                            };
+                        element.props.set(key, { generator, elapsed: 0, value: from, done: false });
+                        element.committed[key] = from;
+                    }
+                    // Recompute from what remains in flight: a held retarget seeds a contending generator
+                    // (props.size grows) and a held element is active regardless (heldCount > 0).
+                    element.active = element.props.size > 0 || element.heldCount > 0 || element.path !== null;
+                    break;
+                }
+                case 'stop': {
+                    // Halt every animation AND release every gesture hold (stop = halt everything); the
+                    // committed values are held as-is (REQ-DRIVER-013). Pin onStop zeroes pathRotation.
+                    element.props.clear();
+                    for (const key of Object.keys(element.heldVelocity))
+                        delete element.heldVelocity[key];
+                    for (const key of Object.keys(element.contending))
+                        delete element.contending[key];
+                    if (element.path !== null) {
+                        if (element.path.geometry.rotationScale && 'pathRotation' in element.committed)
+                            element.committed.pathRotation = 0;
+                        element.path = null;
+                    }
+                    element.heldCount = 0;
+                    element.active = false;
+                    break;
+                }
+            }
+        },
+        step(elapsedMs) {
+            for (const element of elements) {
+                if (!element.active)
+                    continue;
+                let anyActive = false;
+                for (const [key, prop] of element.props) {
+                    stepProp(prop, elapsedMs);
+                    element.committed[key] = prop.value;
+                    if (!prop.done)
+                        anyActive = true;
+                }
+                if (element.path !== null) {
+                    const path = element.path;
+                    stepProp(path.progress, elapsedMs);
+                    const sample = applyPathProgress(path.progress.value, path.geometry, path.progress.done);
+                    if ('x' in element.committed)
+                        element.committed.x = sample.x;
+                    if ('y' in element.committed)
+                        element.committed.y = sample.y;
+                    if (path.geometry.rotationScale && 'pathRotation' in element.committed)
+                        element.committed.pathRotation = sample.pathRotation;
+                    if (path.progress.done)
+                        element.path = null;
+                    else
+                        anyActive = true;
+                }
+                // Quiesce once every animation settles (REQ-DRIVER-020) — UNLESS a gesture still holds a
+                // prop (a finger is down, no animation but unsettled, G-INV-7). heldCount is O(1), so this
+                // stays allocation-free. A held element stays active until the matching release clears it.
+                if (!anyActive && element.heldCount === 0)
+                    element.active = false;
+            }
+        },
+        committed(handle) {
+            return { ...elementAt(handle).committed };
+        },
+        setActive(handle, active) {
+            elementAt(handle).active = active;
+        },
+        isActive(handle) {
+            return elementAt(handle).active;
+        },
+        // The gesture write lane (REQ-DRIVER-024): commit event-driven values and interrupt any
+        // in-flight animation on the written props through ONE entry point — committed state and
+        // animation state can never skew. Never emits a settle edge for a prop that was not
+        // animating (the active flag recomputes from what actually remains in flight).
+        write(handle, values, velocities) {
+            const element = elementAt(handle);
+            for (const key of Object.keys(values)) {
+                if (!(key in element.committed)) {
+                    throw new Error(`cannot write '${key}': it was never registered on this element.`);
+                }
+            }
+            // Validate ALL keys before mutating ANY (fail-closed: a malformed write never half-applies).
+            for (const key of Object.keys(values)) {
+                const finger = values[key];
+                if (element.heldVelocity[key] === undefined)
+                    element.heldCount++; // count a NEW hold once
+                element.committed[key] = finger;
+                // Refresh the per-prop held platform velocity so liveFor reports it while held (G-INV-3 C1
+                // seam, held-velocity precedence over any contending generator); omitted ⇒ 0.
+                element.heldVelocity[key] = velocities?.[key] ?? 0;
+                // Reconcile the prop's generator with the finger write (REQ-DRIVER-026). A LIVE declarative
+                // contention is RE-ANCHORED to the freshly-committed finger value so it drifts FROM here —
+                // never a backward jump to the generator's stale trajectory (review r10 major 29, G-INV-2).
+                // Otherwise the finger owns the value outright: a plain grab interrupts the pre-existing
+                // animation (REQ-GESTURE-012), and a SETTLED contention is finished, so its generator is
+                // dropped (else `step` would keep forcing its value and the finger could never move it).
+                const contention = element.contending[key];
+                const prop = element.props.get(key);
+                if (contention !== undefined && prop !== undefined && !prop.done) {
+                    element.props.set(key, {
+                        // Re-anchor FROM the finger: seed a keyframe array's first element from-current so the
+                        // drift continues from `finger`, never rewinding to keyframes[0] (major 25).
+                        generator: startGenerator(contention.transition, anchorContentionToLive(contention.to), finger, 0),
+                        elapsed: 0,
+                        value: finger,
+                        done: false,
+                    });
+                }
+                else {
+                    if (prop !== undefined)
+                        element.props.delete(key);
+                    delete element.contending[key];
+                }
+            }
+            // A gesture write holds the element unsettled (G-INV-7): a finger is down driving it, so it
+            // stays active until the matching release/stop clears the hold — never a spurious settle edge
+            // mid-drag (the reviewer-reproduced re-grab defect), even after a contending animation settles.
+            element.active = true;
+        },
+        // The grab live-read (REQ-DRIVER-025). An in-flight prop re-samples its generator at the
+        // current elapsed — pure by elapsed time (REQ-CORE-001), scalars copied out immediately (the
+        // sample record is generator-owned and reused). Settled/never-animated ⇒ velocity 0.
+        liveFor(handle, key) {
+            const element = elementAt(handle);
+            // HELD-VELOCITY PRECEDENCE (REQ-DRIVER-025): a held (finger-down) prop reports the platform
+            // finger velocity its write carried EVEN when a contending declarative generator is in flight
+            // (REQ-DRIVER-026) — the release seed is the finger's number, never the generator's. The value
+            // is the live committed number (the finger position, or the contending animation's drift). This
+            // read comes BEFORE the generator branch so contention can't leak the generator velocity into
+            // the release seam (the two-sided G-INV-3 C1 seam; per-prop since review r7 major 23).
+            const heldV = element.heldVelocity[key];
+            if (heldV !== undefined) {
+                const base = element.committed[key];
+                if (base === undefined) {
+                    throw new Error(`cannot read '${key}': it was never registered on this element.`);
+                }
+                return { value: base, velocity: heldV };
+            }
+            const live = element.props.get(key);
+            if (live !== undefined && !live.done) {
+                const sample = live.generator.sample(live.elapsed);
+                return { value: sample.value, velocity: sample.velocity };
+            }
+            const base = element.committed[key];
+            if (base === undefined) {
+                throw new Error(`cannot read '${key}': it was never registered on this element.`);
+            }
+            // A settled or never-animated non-held prop has velocity 0 (REQ-DRIVER-025).
+            return { value: base, velocity: 0 };
+        },
+    };
+    return adaptPreparedDriver(backend, (handle) => {
+        elementAt(handle);
+    });
+}