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

package/dist/presence/index.cjs

@@ -0,0 +1,19 @@
+"use strict";
+// Public surface of the SPEC-PRESENCE subsystem: the host-agnostic exit-lifecycle controller `core` defines
+// and the native/web presence surfaces bind to. Host-agnostic (SPEC-PRESENCE §1) — imports no react, no
+// driver, no host package. The lifecycle types + total state machine land first (Milestone 1); the
+// controller, settle integration, and cancellation join this surface as they land.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPresenceController = exports.UnimplementedPresenceModeError = exports.transition = exports.createPresenceLedger = void 0;
+// The total exit-lifecycle state machine (SPEC-PRESENCE §3): the pure transition + the key→state ledger the
+// controller owns.
+var machine_1 = require("./machine.cjs");
+Object.defineProperty(exports, "createPresenceLedger", { enumerable: true, get: function () { return machine_1.createPresenceLedger; } });
+Object.defineProperty(exports, "transition", { enumerable: true, get: function () { return machine_1.transition; } });
+// The presence controller (REQ-PRESENCE-001/011): mount authority + exit-target resolution + retention,
+// driven off the MotionGraph settle ledger. The React usePresence/useIsPresent hooks bind over it (M2 host).
+// The legacy typed error remains exported for public-surface compatibility; popLayout itself now
+// uses core's ordinary lifecycle ordering and is composed by the host presence layers.
+var controller_1 = require("./controller.cjs");
+Object.defineProperty(exports, "UnimplementedPresenceModeError", { enumerable: true, get: function () { return controller_1.UnimplementedPresenceModeError; } });
+Object.defineProperty(exports, "createPresenceController", { enumerable: true, get: function () { return controller_1.createPresenceController; } });

package/dist/presence/index.d.cts

@@ -0,0 +1,4 @@
+export type { PresenceChild, PresenceController, PresenceControllerOptions, PresenceMode, PresenceState, } from "./types.cjs";
+export { createPresenceLedger, transition } from "./machine.cjs";
+export type { PresenceEvent, PresenceLedger } from "./machine.cjs";
+export { UnimplementedPresenceModeError, createPresenceController } from "./controller.cjs";

package/dist/presence/index.d.ts

@@ -0,0 +1,4 @@
+export type { PresenceChild, PresenceController, PresenceControllerOptions, PresenceMode, PresenceState, } from "./types.js";
+export { createPresenceLedger, transition } from "./machine.js";
+export type { PresenceEvent, PresenceLedger } from "./machine.js";
+export { UnimplementedPresenceModeError, createPresenceController } from "./controller.js";

package/dist/presence/index.js

@@ -0,0 +1,12 @@
+// Public surface of the SPEC-PRESENCE subsystem: the host-agnostic exit-lifecycle controller `core` defines
+// and the native/web presence surfaces bind to. Host-agnostic (SPEC-PRESENCE §1) — imports no react, no
+// driver, no host package. The lifecycle types + total state machine land first (Milestone 1); the
+// controller, settle integration, and cancellation join this surface as they land.
+// The total exit-lifecycle state machine (SPEC-PRESENCE §3): the pure transition + the key→state ledger the
+// controller owns.
+export { createPresenceLedger, transition } from "./machine.js";
+// The presence controller (REQ-PRESENCE-001/011): mount authority + exit-target resolution + retention,
+// driven off the MotionGraph settle ledger. The React usePresence/useIsPresent hooks bind over it (M2 host).
+// The legacy typed error remains exported for public-surface compatibility; popLayout itself now
+// uses core's ordinary lifecycle ordering and is composed by the host presence layers.
+export { UnimplementedPresenceModeError, createPresenceController } from "./controller.js";

package/dist/presence/machine.cjs

@@ -0,0 +1,50 @@
+"use strict";
+// SPEC-PRESENCE §3 — the total exit-lifecycle state machine. A presence-tracked key is always in exactly one
+// of `present | exiting | removed`, and only four edges move it. Every other edge throws (fail-loud): an
+// illegal transition is a controller bug, never a silent no-op or a state teleport. Host-agnostic
+// (REQ-CORE-003): relative imports only, no clock/host reads.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transition = transition;
+exports.createPresenceLedger = createPresenceLedger;
+const EDGES = {
+    'drop-with-exit': { from: 'present', to: 'exiting' },
+    'drop-immediate': { from: 'present', to: 'removed' },
+    resolve: { from: 'exiting', to: 'removed' },
+    cancel: { from: 'exiting', to: 'present' },
+};
+// Pure total transition: map `(current, event)` to the next state, or throw on an illegal edge. Deterministic.
+function transition(current, event) {
+    const edge = EDGES[event];
+    if (current !== edge.from) {
+        throw new Error(`illegal presence transition '${event}' from '${current}': only legal from '${edge.from}'.`);
+    }
+    return edge.to;
+}
+function createPresenceLedger() {
+    // Holds only non-terminal states; absence of a key IS the terminal `removed` state.
+    const states = new Map();
+    return {
+        track(key) {
+            if (states.has(key))
+                throw new Error(`presence key '${key}' is already tracked`);
+            states.set(key, 'present');
+        },
+        stateOf(key) {
+            return states.get(key) ?? 'removed';
+        },
+        send(key, event) {
+            const current = states.get(key) ?? 'removed';
+            const next = transition(current, event);
+            if (next === 'removed') {
+                states.delete(key);
+            }
+            else {
+                states.set(key, next);
+            }
+            return next;
+        },
+        trackedKeys() {
+            return [...states.keys()];
+        },
+    };
+}

package/dist/presence/machine.d.cts

@@ -0,0 +1,10 @@
+import type { PresenceState } from "./types.cjs";
+export type PresenceEvent = 'drop-with-exit' | 'drop-immediate' | 'resolve' | 'cancel';
+export declare function transition(current: PresenceState, event: PresenceEvent): PresenceState;
+export interface PresenceLedger {
+    track(key: string): void;
+    stateOf(key: string): PresenceState;
+    send(key: string, event: PresenceEvent): PresenceState;
+    trackedKeys(): readonly string[];
+}
+export declare function createPresenceLedger(): PresenceLedger;

package/dist/presence/machine.d.ts

@@ -0,0 +1,10 @@
+import type { PresenceState } from "./types.js";
+export type PresenceEvent = 'drop-with-exit' | 'drop-immediate' | 'resolve' | 'cancel';
+export declare function transition(current: PresenceState, event: PresenceEvent): PresenceState;
+export interface PresenceLedger {
+    track(key: string): void;
+    stateOf(key: string): PresenceState;
+    send(key: string, event: PresenceEvent): PresenceState;
+    trackedKeys(): readonly string[];
+}
+export declare function createPresenceLedger(): PresenceLedger;

package/dist/presence/machine.js

@@ -0,0 +1,46 @@
+// SPEC-PRESENCE §3 — the total exit-lifecycle state machine. A presence-tracked key is always in exactly one
+// of `present | exiting | removed`, and only four edges move it. Every other edge throws (fail-loud): an
+// illegal transition is a controller bug, never a silent no-op or a state teleport. Host-agnostic
+// (REQ-CORE-003): relative imports only, no clock/host reads.
+const EDGES = {
+    'drop-with-exit': { from: 'present', to: 'exiting' },
+    'drop-immediate': { from: 'present', to: 'removed' },
+    resolve: { from: 'exiting', to: 'removed' },
+    cancel: { from: 'exiting', to: 'present' },
+};
+// Pure total transition: map `(current, event)` to the next state, or throw on an illegal edge. Deterministic.
+export function transition(current, event) {
+    const edge = EDGES[event];
+    if (current !== edge.from) {
+        throw new Error(`illegal presence transition '${event}' from '${current}': only legal from '${edge.from}'.`);
+    }
+    return edge.to;
+}
+export function createPresenceLedger() {
+    // Holds only non-terminal states; absence of a key IS the terminal `removed` state.
+    const states = new Map();
+    return {
+        track(key) {
+            if (states.has(key))
+                throw new Error(`presence key '${key}' is already tracked`);
+            states.set(key, 'present');
+        },
+        stateOf(key) {
+            return states.get(key) ?? 'removed';
+        },
+        send(key, event) {
+            const current = states.get(key) ?? 'removed';
+            const next = transition(current, event);
+            if (next === 'removed') {
+                states.delete(key);
+            }
+            else {
+                states.set(key, next);
+            }
+            return next;
+        },
+        trackedKeys() {
+            return [...states.keys()];
+        },
+    };
+}

package/dist/presence/types.cjs

@@ -0,0 +1,6 @@
+"use strict";
+// SPEC-PRESENCE §2 — the presence/exit lifecycle type contract. Host-agnostic (REQ-CORE-003): the controller
+// lives in `core`, drives exits over the injected MotionGraph + clock, and never imports a driver, React, or
+// the DOM (SPEC-PRESENCE §1). The React `usePresence`/`useIsPresent` hooks are Milestone-2 host bindings over
+// the `isPresent`/`safeToRemove` semantics declared here.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/presence/types.d.cts

@@ -0,0 +1,32 @@
+import type { ResolvedTargetValue, ResolvedValue, Target, Transition } from "../component/index.cjs";
+import type { MotionGraph } from "../types.cjs";
+export type PresenceState = 'present' | 'exiting' | 'removed';
+export type PresenceMode = 'sync' | 'wait' | 'popLayout';
+export type PresenceLiveValues = Readonly<Record<string, ResolvedValue>>;
+export type PresenceResolvedExits = Readonly<Record<string, readonly (number | null)[]>>;
+export interface PresenceChild {
+    readonly key: string;
+    readonly exit?: Target;
+    readonly animate?: Target;
+    readonly transition?: Transition;
+    readonly deferred?: boolean;
+    readonly mountedKeys?: readonly string[];
+}
+export interface PresenceControllerOptions {
+    readonly graph: MotionGraph;
+    readonly mode?: PresenceMode;
+    readonly initial?: boolean;
+    readonly onExitComplete?: () => void;
+}
+export interface PresenceController {
+    syncChildren(children: readonly PresenceChild[], liveValuesByKey?: ReadonlyMap<string, PresenceLiveValues>, resolvedExitsByKey?: ReadonlyMap<string, PresenceResolvedExits>): void;
+    mountedKeys(): readonly string[];
+    stateOf(key: string): PresenceState;
+    isPresent(key: string): boolean;
+    safeToRemove(key: string): void;
+    deferExit(key: string): void;
+    resolvedExitTarget(key: string): Readonly<Record<string, ResolvedTargetValue>> | undefined;
+    enterSuppressed(key: string): boolean;
+    exitProgress(key: string): number | undefined;
+    exitVelocity(key: string): number | undefined;
+}

package/dist/presence/types.d.ts

@@ -0,0 +1,32 @@
+import type { ResolvedTargetValue, ResolvedValue, Target, Transition } from "../component/index.js";
+import type { MotionGraph } from "../types.js";
+export type PresenceState = 'present' | 'exiting' | 'removed';
+export type PresenceMode = 'sync' | 'wait' | 'popLayout';
+export type PresenceLiveValues = Readonly<Record<string, ResolvedValue>>;
+export type PresenceResolvedExits = Readonly<Record<string, readonly (number | null)[]>>;
+export interface PresenceChild {
+    readonly key: string;
+    readonly exit?: Target;
+    readonly animate?: Target;
+    readonly transition?: Transition;
+    readonly deferred?: boolean;
+    readonly mountedKeys?: readonly string[];
+}
+export interface PresenceControllerOptions {
+    readonly graph: MotionGraph;
+    readonly mode?: PresenceMode;
+    readonly initial?: boolean;
+    readonly onExitComplete?: () => void;
+}
+export interface PresenceController {
+    syncChildren(children: readonly PresenceChild[], liveValuesByKey?: ReadonlyMap<string, PresenceLiveValues>, resolvedExitsByKey?: ReadonlyMap<string, PresenceResolvedExits>): void;
+    mountedKeys(): readonly string[];
+    stateOf(key: string): PresenceState;
+    isPresent(key: string): boolean;
+    safeToRemove(key: string): void;
+    deferExit(key: string): void;
+    resolvedExitTarget(key: string): Readonly<Record<string, ResolvedTargetValue>> | undefined;
+    enterSuppressed(key: string): boolean;
+    exitProgress(key: string): number | undefined;
+    exitVelocity(key: string): number | undefined;
+}

package/dist/presence/types.js

@@ -0,0 +1,5 @@
+// SPEC-PRESENCE §2 — the presence/exit lifecycle type contract. Host-agnostic (REQ-CORE-003): the controller
+// lives in `core`, drives exits over the injected MotionGraph + clock, and never imports a driver, React, or
+// the DOM (SPEC-PRESENCE §1). The React `usePresence`/`useIsPresent` hooks are Milestone-2 host bindings over
+// the `isPresent`/`safeToRemove` semantics declared here.
+export {};

package/dist/repeat.cjs

@@ -0,0 +1,311 @@
+"use strict";
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// T18-a / REQ-TIMING-003 — the repeat elapsed-time FOLD. `repeat`/`repeatType`/`repeatDelay` are not
+// generator features in the pinned Motion: they are a pure `t → t'` map wrapped AROUND a generator
+// (motion-dom@12.42.2 `JSAnimation.initAnimation` + `tick`). This module is that map, so every
+// generator core owns — spring, tween, keyframe array — repeats identically and none of them learns
+// about repetition. Host-agnostic (REQ-CORE-003): relative imports only. Numerics are pinned by
+// per-sample goldens in repeat.test.ts.
+//
+// The fold divides by the RESOLVED iteration length (play + repeatDelay), so it is TOTAL only
+// when that is finite and positive: a zero-length play with no repeatDelay produces NaN at the
+// pin and is refused upstream (`repeatIterationRefusal`), as is an unbounded one. Zero-length
+// plays separated by a repeatDelay are the pin's executable shape (transition-default-selection
+// F5) and fold fine.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REPEAT_REFUSAL_KEY = exports.REPEAT_REFUSAL_NAME = exports.MAX_ITERATION_DURATION_MS = exports.ITERATION_SCAN_STEP_MS = void 0;
+exports.calcIterationDurationMs = calcIterationDurationMs;
+exports.repeatIterationRefusal = repeatIterationRefusal;
+exports.iterationMeasurementLane = iterationMeasurementLane;
+exports.isRepeatFoldRefusalIdentity = isRepeatFoldRefusalIdentity;
+exports.isRepeatFoldRefusal = isRepeatFoldRefusal;
+exports.repeatRefusalMessage = repeatRefusalMessage;
+exports.repeatFoldGeometry = repeatFoldGeometry;
+exports.repeatGenerator = repeatGenerator;
+exports.buildRepeatedGenerator = buildRepeatedGenerator;
+// The pin's `calcGeneratorDuration` scan constants (motion-dom keyframes/calc-duration.ts). The
+// 50ms grid is why a physics spring's iteration length is COARSE — it is the pin's number, not an
+// analytic settle time, and reproducing it exactly is what keeps repeated springs in parity.
+exports.ITERATION_SCAN_STEP_MS = 50;
+exports.MAX_ITERATION_DURATION_MS = 20_000;
+/**
+ * The iteration length of a generator that does not know its own duration (a physics or
+ * visualDuration spring — the pin's `calculatedDuration === null` case). Samples on the pin's 50ms
+ * grid until the trajectory reports done, and reports `Infinity` at the cap rather than scanning
+ * forever. Safe to run against a live generator: core's generators are pure functions of elapsed
+ * time (they latch no state, only reuse their sample record).
+ */
+// alloc-ok: lifecycle-edge — the scan runs once per animate command, never per frame.
+function calcIterationDurationMs(generator) {
+    let duration = 0;
+    let state = generator.sample(duration);
+    while (!state.done && duration < exports.MAX_ITERATION_DURATION_MS) {
+        duration += exports.ITERATION_SCAN_STEP_MS;
+        state = generator.sample(duration);
+    }
+    return duration >= exports.MAX_ITERATION_DURATION_MS ? Infinity : duration;
+}
+/**
+ * Refuse a fold the pin cannot execute (packet L3). The fold divides by the RESOLVED iteration
+ * length (play + repeatDelay), so a zero-length play with NOTHING separating it yields NaN at the
+ * pin and is refused here. A zero-length play separated by a `repeatDelay` is a different shape:
+ * the pin totals the delay gaps around the zero-length plays (`JSAnimation.initAnimation` —
+ * `totalDuration = calculatedDuration * (repeat + 1) + repeatDelay * repeat`), so the fold
+ * EXECUTES, holding each play's final keyframe through the gaps (transition-default-selection
+ * F5). An unbounded iteration still emits NaN for the rest of the animation and is refused either
+ * way. The refusal is CROSS-FIELD — either length is legal without `repeat`, where nothing
+ * divides. Returns the loud refusal or null (the `springKeyframeCountRefusal` shape: this module
+ * crosses to the UI runtime, where a throw is a bare `std::terminate`).
+ */
+// alloc-ok: lifecycle-edge — a refusal built at command/validation time, never per frame.
+function repeatIterationRefusal(iterationDurationMs, repeat, repeatDelayMs = 0) {
+    if (repeat <= 0)
+        return null;
+    if (iterationDurationMs <= 0 && repeatDelayMs <= 0) {
+        return new Error('a repeated transition cannot fold a zero-length iteration — `repeat` divides by the ' +
+            "iteration's duration, so a zero-duration play repeats nothing (the pinned Motion " +
+            'silently holds the final keyframe instead). Give the transition a duration, or drop ' +
+            '`repeat` (REQ-TIMING-003, T18-a L3).');
+    }
+    if (!Number.isFinite(iterationDurationMs)) {
+        return new Error(`a repeated transition cannot fold an iteration that never settles — this trajectory is ` +
+            `still moving after ${exports.MAX_ITERATION_DURATION_MS}ms, past the point where the pinned ` +
+            'Motion stops measuring it and starts emitting NaN. Bound the transition (duration, or ' +
+            'stiffer physics), or drop `repeat` (REQ-TIMING-003, T18-a L3).');
+    }
+    return null;
+}
+function iterationMeasurementLane(targetIsNumeric, isExplicitSpring, isTween) {
+    // A keyframe ARRAY target is played by the keyframes generator unless the transition explicitly
+    // asked for a spring — so an untyped or tween-typed transition changes lane with the target.
+    if (!targetIsNumeric && !isExplicitSpring)
+        return 'keyframes';
+    if (isTween)
+        return 'timing';
+    return 'spring';
+}
+/**
+ * The refusal's identity, shared by BOTH backends (T18-a fix-up, review MAJOR).
+ *
+ * `repeatIterationRefusal` returns a bare `Error` because it crosses to the UI runtime. The
+ * reference backend re-wraps it as an `InvalidTransitionError`, which names the offending property
+ * instead of surfacing an anonymous driver-lane fault. The worklet backend cannot: it must not
+ * construct a core class inside a worklet, and the lane marshals only `{name, message}` to RN
+ * anyway, so the class identity could not survive the crossing even if it could be built.
+ *
+ * What CAN be identical across the crossing is exactly what the crossing carries — the name and the
+ * message. Both backends therefore build them here, so a developer sees one refusal whichever
+ * engine they are on, and `repeatRefusalParity` pins the two against each other.
+ */
+exports.REPEAT_REFUSAL_NAME = 'InvalidTransitionError';
+/** The offending property a fold refusal names — `InvalidTransitionError.key` on the JS backend. */
+exports.REPEAT_REFUSAL_KEY = 'repeat';
+/**
+ * A fold refusal, as a CONSUMER can recognize it after any transport.
+ *
+ * The severity router used `error instanceof InvalidTransitionError && error.key === 'repeat'`,
+ * which is decidable only on the reference backend: the UI runtime cannot construct a core class,
+ * and the crossing marshals plain data, so the shipping backend's refusal arrived as a bare `Error`
+ * and the router silently stopped firing (T18-a round-9 review BLOCKING 1). Class identity is not
+ * available across the crossing, so the recognition contract cannot be built on it — it is
+ * STRUCTURAL by necessity, and it lives here, beside the name and the message it completes, so the
+ * whole identity is one thing that one floor can hold.
+ *
+ * `isRepeatFoldRefusalIdentity` is the two-field core, so the UI lane — which holds the refusal as a
+ * marshalled `{name, message, key}` record, never an `Error` — decides it with the SAME rule the
+ * consumer applies to the rethrown error rather than a second copy that can drift.
+ */
+function isRepeatFoldRefusalIdentity(name, key) {
+    return name === exports.REPEAT_REFUSAL_NAME && key === exports.REPEAT_REFUSAL_KEY;
+}
+function isRepeatFoldRefusal(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const candidate = error;
+    return isRepeatFoldRefusalIdentity(candidate.name, candidate.key);
+}
+// Mirrors `InvalidTransitionError`'s message format for an anonymous component with a numeric
+// value. It is duplicated rather than imported because `validate.ts` is JS-side-only (it reaches
+// the subset registry and the value-type parsers) and this module crosses to the UI runtime. The
+// duplication is held honest by the cross-backend floor, not by review.
+// alloc-ok: lifecycle-edge — a refusal built at command time, never per frame.
+function repeatRefusalMessage(repeat, reason) {
+    return `<Motion.View>: invalid transition option 'repeat' = ${String(repeat)} — ${reason}`;
+}
+/**
+ * The fold's geometry, verbatim from the pin (`JSAnimation.initAnimation:169-170`). The trailing
+ * delay of the LAST iteration is subtracted: a repeat delay separates plays, it does not extend
+ * the animation past its final one.
+ */
+// alloc-ok: lifecycle-edge — geometry resolved once per animate command.
+function repeatFoldGeometry(config) {
+    const resolvedDurationMs = config.iterationDurationMs + config.repeatDelayMs;
+    return {
+        resolvedDurationMs,
+        totalDurationMs: resolvedDurationMs * (config.repeat + 1) - config.repeatDelayMs,
+    };
+}
+function clamp01(value) {
+    return value > 1 ? 1 : value < 0 ? 0 : value;
+}
+// DECLARATION ORDER IS LOAD-BEARING in this module: it ships FILE-tagged, so the workletizer
+// emits every function as a non-hoisted const and a worklet may only reference worklets declared
+// ABOVE it. `buildRepeatedGenerator` calls this, so this comes first. Pinned by
+// check-worklet-forward-refs.test.ts.
+/**
+ * Wrap `base` in the repeat fold (REQ-TIMING-003). The returned generator is a `Generator` like any
+ * other — the driver steps it without knowing it repeats.
+ *
+ * Two laws diverge deliberately from a naive port of the pin's `tick`:
+ *
+ *  - A REVERSED leg negates the reported velocity. Our `GeneratorSample` carries the ANALYTIC
+ *    velocity that the C1 retarget seam and `liveFor` read (REQ-SPRING-009 / REQ-DRIVER-025),
+ *    whereas the pin's user-visible velocity is a finite-diff of the value — correctly signed by
+ *    construction even though its generator's internal velocity on a reversed leg is not.
+ *    Reproducing the pin's internal sign would seed a mid-reverse retarget in the wrong direction.
+ *  - `done` follows the fold's `totalDuration`, never the base trajectory's own settle. The base
+ *    settles once per iteration; only the last one ends the animation, and an endless repeat is
+ *    never done at all (packet L5 — such an element intentionally never quiesces).
+ */
+// alloc-ok: lifecycle-edge — construction resolves geometry and builds the ONE reused sample
+// record; sample() below mutates it and allocates nothing (REQ-DRIVER-021).
+function repeatGenerator(base, config) {
+    const { repeat, leg, repeatDelayMs, iterationDurationMs } = config;
+    const { resolvedDurationMs, totalDurationMs } = repeatFoldGeometry({
+        repeat,
+        repeatDelayMs,
+        iterationDurationMs,
+    });
+    const mirrored = leg.type === 'mirror' ? leg.mirrored : null;
+    const isReverse = leg.type === 'reverse';
+    // The pin's terminal keyframe rule (motion-dom keyframes/get-final.ts), reduced to the only case
+    // where it disagrees with where this fold naturally lands:
+    //
+    //   useFirstKeyframe = speed < 0 || (repeat && repeatType !== 'loop' && repeat % 2 === 1)
+    //
+    // `repeat % 2 === 1` selects exactly the ODD INTEGERS, and `repeatType !== 'loop'` puts BOTH
+    // `reverse` and `mirror` in that branch. An integer fold already ENDS on the pin's keyframe by
+    // construction — a whole-number progress is corrected to `iterationProgress` 1; a `reverse` leg
+    // reflects that to 0 and a `mirror` leg samples the mirrored trajectory at ITS end, which is the
+    // base origin, so both odd cases report the pin's FIRST keyframe while a `loop` leg and every
+    // EVEN case hold at 1 and report the pin's LAST. So the integer path needs no snap and must not
+    // get one. (Measured on the pin, `[0,100]` and `[0,100,30]`, repeats 1-4 × all three types: odd
+    // reverse and odd mirror both land on FIRST, everything else on LAST.) A FRACTIONAL repeat is
+    // the gap: at forward speed it satisfies no branch of the rule, so the pin commits the LAST keyframe while this
+    // fold is mid-play. `speed < 0` has no native producer (drivers accumulate non-negative elapsed
+    // only), so that half of the rule is stated and not implemented.
+    const snapsAtTerminal = Number.isFinite(repeat) && repeat > 0 && !Number.isInteger(repeat);
+    // The pin's snap is NOT part of the fold: `JSAnimation.tick` computes the fold, then applies
+    // `getFinalKeyframe` under its `isAnimationFinished` gate
+    // (`holdTime === null && (state === 'finished' || (state === 'running' && done))`), and only then
+    // calls `finish()` — which never touches the value. A FRESH, non-autoplaying instance never
+    // satisfies that gate: it is `paused`, so `holdTime` is non-null and neither disjunct holds, and
+    // its `sample()` returns the raw fold at EVERY time. An already-FINISHED instance takes the
+    // override at ANY sampled time, mid-play included; a RUNNING one only at or past `totalDuration`,
+    // because that disjunct also requires `done`. Measured on `repeat: 1.5 reverse`, whose raw fold is
+    // 80 mid-play and 50 at the terminal — paused 80/50, running 80/100, finished 100/100.
+    //
+    // `gen-repeat-goldens.mjs` builds a FRESH `autoplay: false` instance per sample, so the golden
+    // records both layers: `samples` are raw-fold seeks (50 at the terminal) and `terminalValue` comes
+    // from playing to the end (100). Keeping `sample` seek-faithful and exposing the commit separately
+    // reproduces that split instead of collapsing it; putting the snap inside `sample` broke the
+    // pinned `tween-reverse-fractional` samples, which is the golden reporting the wrong layer (H2 F1).
+    //
+    // The value is the FORWARD base at its end, never the leg the partial play was on: the pin
+    // commits `resolvedKeyframes[length - 1]` whatever direction it was travelling, so a `reverse` or
+    // `mirror` fold descending toward the origin jumps UP to the target. Core's generators are pure
+    // functions of elapsed, so sampling one here is safe and allocation-free at the frame path.
+    const finalValue = snapsAtTerminal ? base.sample(resolvedDurationMs).value : undefined;
+    // The delay's share of one resolved iteration — the reverse leg's re-bias factor, hoisted so the
+    // frame path does no division beyond the progress one.
+    const delayFraction = repeatDelayMs / resolvedDurationMs;
+    const out = { value: 0, velocity: 0, done: false };
+    return {
+        finalValue,
+        sample(rawElapsedMs) {
+            // The pin clamps before folding (`JSAnimation.tick`: `Math.max(timeWithoutDelay, 0)`), and so
+            // must this: `floor` of a negative progress is -1, an ODD iteration, so a `reverse` leg would
+            // reflect and report the far endpoint at a moment the animation has not begun. Today's
+            // drivers only ever accumulate non-negative deltas, but the pin's one producer of negative
+            // elapsed is `currentTime - delay` — property-lane `delay`, this packet's successor rung.
+            // `Math.max` rather than `rawElapsedMs > 0 ? rawElapsedMs : 0` — they agree on every number
+            // and disagree on NaN, which the comparison silently maps to 0 (reporting the trajectory's
+            // ORIGIN for a broken clock) while `Math.max` propagates it. A NaN clock is a programmer
+            // error, and it must stay loud rather than resolve to a plausible-looking value (review
+            // MINOR).
+            const elapsedMs = Math.max(rawElapsedMs, 0);
+            let elapsed = elapsedMs;
+            let frameGenerator = base;
+            let reversedLeg = false;
+            if (repeat > 0) {
+                // Progress across the WHOLE fold in iteration units: 2.5 is halfway through the third play.
+                const progress = Math.min(elapsedMs, totalDurationMs) / resolvedDurationMs;
+                let currentIteration = Math.floor(progress);
+                let iterationProgress = progress % 1;
+                // A whole-number progress at or past the first boundary is the END of the PREVIOUS
+                // iteration, not the start of the next — otherwise every boundary flickers a frame of the
+                // successor's origin.
+                if (iterationProgress === 0 && progress >= 1) {
+                    iterationProgress = 1;
+                    currentIteration--;
+                }
+                if (currentIteration > repeat + 1)
+                    currentIteration = repeat + 1;
+                if (currentIteration % 2 !== 0) {
+                    if (isReverse) {
+                        iterationProgress = 1 - iterationProgress;
+                        // Reflecting progress would put the dead time at the START of the reversed play; this
+                        // subtraction moves it back to the END, so the rule stays uniform across repeat types:
+                        // every play holds on the value it FINISHED on. A reversed leg therefore begins
+                        // descending immediately from the iteration's end value and pauses at its start value.
+                        if (repeatDelayMs > 0)
+                            iterationProgress -= delayFraction;
+                        reversedLeg = true;
+                    }
+                    else if (mirrored !== null) {
+                        frameGenerator = mirrored;
+                    }
+                }
+                elapsed = clamp01(iterationProgress) * resolvedDurationMs;
+            }
+            const sample = frameGenerator.sample(elapsed);
+            out.value = sample.value;
+            out.velocity = reversedLeg ? -sample.velocity : sample.velocity;
+            out.done = elapsedMs >= totalDurationMs;
+            return out;
+        },
+    };
+}
+/**
+ * Build the folded generator for a repeated transition — the ONE implementation every driver seam
+ * calls (both drivers' start AND retarget seams). Sharing this call does not by itself prevent
+ * skew: the fix-up review found both backends sharing it while both omitted it from retarget.
+ * Parity is held by the executing floor, `driverParity.differential.test.ts`. Each driver supplies
+ * only what it alone knows:
+ *
+ *  - `base` / `leg` — its own already-CONSTRUCTED generators. The mirrored trajectory rides inside
+ *    the `mirror` leg (origin/target swapped, seed velocity negated, keyframe list reversed), so a
+ *    mirror fold without one stays unrepresentable.
+ *  - `knownIterationDurationMs` — the transition's own resolved duration when it has one (a tween,
+ *    a keyframe array, or a duration-resolved spring, mirroring the pin's `calculatedDuration`), or
+ *    null for a physics/visualDuration spring, whose length is measured by the scan. A known ZERO
+ *    is honored exactly: an authored `duration: 0` under a repeatDelay fold has genuinely
+ *    zero-length plays (transition-default-selection F5) — scanning the base instead would invent
+ *    a 50ms iteration the pin does not have.
+ *
+ * Generators are passed as VALUES, never as a factory callback: synchronously invoking a captured
+ * function parameter on the UI runtime is the wrong-runtime crash class, and `check:worklet-closures`
+ * fails closed on it. Both drivers therefore build their own legs eagerly and hand them over.
+ *
+ * Returns the folded generator, or the loud refusal for a fold the pin cannot execute (L3). The
+ * caller routes that refusal through its severity boundary — this never throws, because it runs on
+ * the UI runtime where a throw is a bare `std::terminate`.
+ */
+// alloc-ok: lifecycle-edge — one fold construction per animate command, never per frame.
+function buildRepeatedGenerator(repeat, leg, repeatDelayMs, base, knownIterationDurationMs) {
+    const iterationDurationMs = knownIterationDurationMs ?? calcIterationDurationMs(base);
+    const refusal = repeatIterationRefusal(iterationDurationMs, repeat, repeatDelayMs);
+    if (refusal !== null)
+        return refusal;
+    return repeatGenerator(base, { repeat, leg, repeatDelayMs, iterationDurationMs });
+}