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

package/dist/repeat.d.cts

@@ -0,0 +1,174 @@
+import type { Generator } from "./types.cjs";
+export type RepeatType = 'loop' | 'reverse' | 'mirror';
+/**
+ * How an ODD iteration plays. `mirror` carries its own second generator rather than reflecting the
+ * first: the pin builds it from the same factory with REVERSED KEYFRAMES and a NEGATED seed
+ * velocity (`JSAnimation:147-153`), and `times`/`ease` pass through untouched — so a mirrored leg is
+ * genuinely a different trajectory, not a time-reflection of the forward one. Carrying the
+ * generator in the variant makes a mirror fold without its second generator UNREPRESENTABLE, which
+ * is what keeps this frame-path module free of a runtime guard it could only report by throwing on
+ * the UI runtime.
+ */
+export type RepeatLeg = {
+    readonly type: 'loop';
+} | {
+    readonly type: 'reverse';
+} | {
+    readonly type: 'mirror';
+    readonly mirrored: Generator;
+};
+export interface RepeatFoldConfig {
+    /** Additional plays after the first. A non-negative integer, or `Infinity` for endless. */
+    readonly repeat: number;
+    readonly leg: RepeatLeg;
+    /** Dead time appended to each iteration, in MILLISECONDS (the public seconds convert upstream). */
+    readonly repeatDelayMs: number;
+    /**
+     * One play's length in ms — the pin's `calculatedDuration`: a tween/keyframe array's authored
+     * duration, and for a PHYSICS spring the `calcIterationDurationMs` scan below.
+     */
+    readonly iterationDurationMs: number;
+}
+export interface RepeatFoldGeometry {
+    /** One iteration INCLUDING its trailing repeat delay (the pin's `resolvedDuration`). */
+    readonly resolvedDurationMs: number;
+    /** The whole fold; `Infinity` for an endless repeat (the pin's `totalDuration`). */
+    readonly totalDurationMs: number;
+}
+export declare const ITERATION_SCAN_STEP_MS = 50;
+export declare const MAX_ITERATION_DURATION_MS = 20000;
+/**
+ * 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).
+ */
+export declare function calcIterationDurationMs(generator: Generator): number;
+/**
+ * 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`).
+ */
+export declare function repeatIterationRefusal(iterationDurationMs: number, repeat: number, repeatDelayMs?: number): Error | null;
+/**
+ * WHICH measurement decides a fold's iteration length. This is the rule that has now been
+ * re-derived, and got wrong, four times — three parallel copies of it exist by necessity
+ * (validation, the reference backend, the worklet backend), and every round a copy drifted:
+ *
+ *   round 1  validation used `type==='tween' || duration || ease`  -> measured springs as tweens
+ *   round 2  validation used "physics keys present"                -> measured tweens as springs
+ *   round 3  validation added the tween short-circuit but stayed target-BLIND -> disagreed with
+ *            both backends for every keyframe-ARRAY target, because the lane depends on the TARGET
+ *            SHAPE as well as the transition
+ *
+ * So the decision itself lives here, once, over primitives — the three callers differ only in the
+ * types they hold (`Transition`, the driver's `PropTransition`, the UI runtime's plain-data
+ * `PlainTransition`), never in the rule. Worklet-safe by construction: primitives in, string out.
+ *
+ * `targetIsNumeric` is the load-bearing parameter validation cannot supply, because the boundary
+ * validator sees a transition and no target. That is not a gap to paper over — it is why validation
+ * must evaluate the rule for EVERY target shape and refuse only when they agree (REQ-TIMING-003).
+ *
+ * INERTIA is not a lane here. It has no repeatable iteration at all, and each caller must already
+ * narrow it off its own union before this point — so an `isInertia` parameter would have been dead
+ * at all three call sites while implying the rule covered a case it does not (round-5 review MINOR).
+ * Callers return early; this answers only the question it can actually decide.
+ */
+export type IterationMeasurementLane = 'keyframes' | 'timing' | 'spring';
+export declare function iterationMeasurementLane(targetIsNumeric: boolean, isExplicitSpring: boolean, isTween: boolean): IterationMeasurementLane;
+/**
+ * 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.
+ */
+export declare const REPEAT_REFUSAL_NAME = "InvalidTransitionError";
+/** The offending property a fold refusal names — `InvalidTransitionError.key` on the JS backend. */
+export declare const 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.
+ */
+export declare function isRepeatFoldRefusalIdentity(name: unknown, key: unknown): boolean;
+export declare function isRepeatFoldRefusal(error: unknown): error is Error & {
+    readonly key: string;
+};
+export declare function repeatRefusalMessage(repeat: number, reason: string): string;
+/**
+ * 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.
+ */
+export declare function repeatFoldGeometry(config: {
+    readonly repeat: number;
+    readonly repeatDelayMs: number;
+    readonly iterationDurationMs: number;
+}): RepeatFoldGeometry;
+/**
+ * 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).
+ */
+export declare function repeatGenerator(base: Generator, config: RepeatFoldConfig): Generator;
+/**
+ * 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`.
+ */
+export declare function buildRepeatedGenerator(repeat: number, leg: RepeatLeg, repeatDelayMs: number, base: Generator, knownIterationDurationMs: number | null): Generator | Error;

package/dist/repeat.d.ts

@@ -0,0 +1,174 @@
+import type { Generator } from "./types.js";
+export type RepeatType = 'loop' | 'reverse' | 'mirror';
+/**
+ * How an ODD iteration plays. `mirror` carries its own second generator rather than reflecting the
+ * first: the pin builds it from the same factory with REVERSED KEYFRAMES and a NEGATED seed
+ * velocity (`JSAnimation:147-153`), and `times`/`ease` pass through untouched — so a mirrored leg is
+ * genuinely a different trajectory, not a time-reflection of the forward one. Carrying the
+ * generator in the variant makes a mirror fold without its second generator UNREPRESENTABLE, which
+ * is what keeps this frame-path module free of a runtime guard it could only report by throwing on
+ * the UI runtime.
+ */
+export type RepeatLeg = {
+    readonly type: 'loop';
+} | {
+    readonly type: 'reverse';
+} | {
+    readonly type: 'mirror';
+    readonly mirrored: Generator;
+};
+export interface RepeatFoldConfig {
+    /** Additional plays after the first. A non-negative integer, or `Infinity` for endless. */
+    readonly repeat: number;
+    readonly leg: RepeatLeg;
+    /** Dead time appended to each iteration, in MILLISECONDS (the public seconds convert upstream). */
+    readonly repeatDelayMs: number;
+    /**
+     * One play's length in ms — the pin's `calculatedDuration`: a tween/keyframe array's authored
+     * duration, and for a PHYSICS spring the `calcIterationDurationMs` scan below.
+     */
+    readonly iterationDurationMs: number;
+}
+export interface RepeatFoldGeometry {
+    /** One iteration INCLUDING its trailing repeat delay (the pin's `resolvedDuration`). */
+    readonly resolvedDurationMs: number;
+    /** The whole fold; `Infinity` for an endless repeat (the pin's `totalDuration`). */
+    readonly totalDurationMs: number;
+}
+export declare const ITERATION_SCAN_STEP_MS = 50;
+export declare const MAX_ITERATION_DURATION_MS = 20000;
+/**
+ * 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).
+ */
+export declare function calcIterationDurationMs(generator: Generator): number;
+/**
+ * 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`).
+ */
+export declare function repeatIterationRefusal(iterationDurationMs: number, repeat: number, repeatDelayMs?: number): Error | null;
+/**
+ * WHICH measurement decides a fold's iteration length. This is the rule that has now been
+ * re-derived, and got wrong, four times — three parallel copies of it exist by necessity
+ * (validation, the reference backend, the worklet backend), and every round a copy drifted:
+ *
+ *   round 1  validation used `type==='tween' || duration || ease`  -> measured springs as tweens
+ *   round 2  validation used "physics keys present"                -> measured tweens as springs
+ *   round 3  validation added the tween short-circuit but stayed target-BLIND -> disagreed with
+ *            both backends for every keyframe-ARRAY target, because the lane depends on the TARGET
+ *            SHAPE as well as the transition
+ *
+ * So the decision itself lives here, once, over primitives — the three callers differ only in the
+ * types they hold (`Transition`, the driver's `PropTransition`, the UI runtime's plain-data
+ * `PlainTransition`), never in the rule. Worklet-safe by construction: primitives in, string out.
+ *
+ * `targetIsNumeric` is the load-bearing parameter validation cannot supply, because the boundary
+ * validator sees a transition and no target. That is not a gap to paper over — it is why validation
+ * must evaluate the rule for EVERY target shape and refuse only when they agree (REQ-TIMING-003).
+ *
+ * INERTIA is not a lane here. It has no repeatable iteration at all, and each caller must already
+ * narrow it off its own union before this point — so an `isInertia` parameter would have been dead
+ * at all three call sites while implying the rule covered a case it does not (round-5 review MINOR).
+ * Callers return early; this answers only the question it can actually decide.
+ */
+export type IterationMeasurementLane = 'keyframes' | 'timing' | 'spring';
+export declare function iterationMeasurementLane(targetIsNumeric: boolean, isExplicitSpring: boolean, isTween: boolean): IterationMeasurementLane;
+/**
+ * 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.
+ */
+export declare const REPEAT_REFUSAL_NAME = "InvalidTransitionError";
+/** The offending property a fold refusal names — `InvalidTransitionError.key` on the JS backend. */
+export declare const 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.
+ */
+export declare function isRepeatFoldRefusalIdentity(name: unknown, key: unknown): boolean;
+export declare function isRepeatFoldRefusal(error: unknown): error is Error & {
+    readonly key: string;
+};
+export declare function repeatRefusalMessage(repeat: number, reason: string): string;
+/**
+ * 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.
+ */
+export declare function repeatFoldGeometry(config: {
+    readonly repeat: number;
+    readonly repeatDelayMs: number;
+    readonly iterationDurationMs: number;
+}): RepeatFoldGeometry;
+/**
+ * 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).
+ */
+export declare function repeatGenerator(base: Generator, config: RepeatFoldConfig): Generator;
+/**
+ * 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`.
+ */
+export declare function buildRepeatedGenerator(repeat: number, leg: RepeatLeg, repeatDelayMs: number, base: Generator, knownIterationDurationMs: number | null): Generator | Error;

package/dist/repeat.js

@@ -0,0 +1,300 @@
+'worklet';
+// @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.
+// 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.
+export const ITERATION_SCAN_STEP_MS = 50;
+export const 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.
+export function calcIterationDurationMs(generator) {
+    let duration = 0;
+    let state = generator.sample(duration);
+    while (!state.done && duration < MAX_ITERATION_DURATION_MS) {
+        duration += ITERATION_SCAN_STEP_MS;
+        state = generator.sample(duration);
+    }
+    return duration >= 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.
+export 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 ${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;
+}
+export 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.
+ */
+export const REPEAT_REFUSAL_NAME = 'InvalidTransitionError';
+/** The offending property a fold refusal names — `InvalidTransitionError.key` on the JS backend. */
+export const 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.
+ */
+export function isRepeatFoldRefusalIdentity(name, key) {
+    return name === REPEAT_REFUSAL_NAME && key === REPEAT_REFUSAL_KEY;
+}
+export 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.
+export 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.
+export 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).
+export 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.
+export 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 });
+}