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

package/dist/transition.js

@@ -0,0 +1,223 @@
+'worklet';
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// Transition-config resolution (SPEC-SPRING REQ-SPRING-004/005/006/007/012). Turns a user transition
+// config into concrete spring physics + the flags the generator/settle layers need. Host-agnostic
+// (REQ-CORE-003): imports nothing from motion/react. Numerics are pinned to motion@12.42.2 and proven
+// by resolution parity in transition.test.ts.
+//
+// findSpring (REQ-SPRING-004) uses the DETERMINISTIC closed form, not motion's 12-iteration
+// Newton-Raphson: for velocity-free duration springs the closed form is the exact analytic root of
+// motion's envelope, so it reproduces motion's resolution (proven to ~5e-5 relative in the tests) with
+// no iteration.
+import { springGenerator } from "./spring.js";
+// Pinned defaults (REQ-SPRING-003 springDefaults).
+const DEFAULT_PHYSICS = { stiffness: 100, damping: 10, mass: 1 };
+const DEFAULT_DURATION_MS = 800;
+const DEFAULT_BOUNCE = 0.3;
+const SAFE_MIN = 0.001;
+const clamp = (lo, hi, v) => Math.max(lo, Math.min(hi, v));
+// REQ-SPRING-004 critical-root constant: the u solving e^(−u)·(u+1) = SAFE_MIN. Derived from SAFE_MIN
+// by Newton (NOT hard-copied 9.2334…) so it stays consistent if SAFE_MIN changes.
+const CRITICAL_ROOT = (() => {
+    let u = 9;
+    for (let i = 0; i < 40; i++)
+        u -= (Math.exp(-u) * (u + 1) - SAFE_MIN) / (-u * Math.exp(-u));
+    return u;
+})();
+// REQ-SPRING-004: duration+bounce → physics via the closed-form undamped frequency (velocity = 0).
+// alloc-ok: lifecycle-edge — duration→physics resolution at command time.
+function findSpring(durationMs, bounce, mass) {
+    const z = clamp(0.05, 1, 1 - bounce);
+    const tSec = clamp(0.01, 10, durationMs / 1000);
+    const omega = z < 1 ? Math.log(z / (SAFE_MIN * Math.sqrt(1 - z * z))) / (z * tSec) : CRITICAL_ROOT / tSec;
+    if (Number.isNaN(omega)) {
+        return { ...DEFAULT_PHYSICS, mass, durationMs: tSec * 1000 };
+    }
+    const stiffness = omega * omega * mass;
+    return { stiffness, damping: z * 2 * Math.sqrt(mass * stiffness), mass, durationMs: tSec * 1000 };
+}
+// REQ-SPRING-005: visualDuration+bounce → the DISTINCT path (no findSpring). bounce defaults to 0 here
+// (intentional asymmetry with REQ-SPRING-004's 0.3). The 1.2 factor is load-bearing.
+// alloc-ok: lifecycle-edge — visualDuration→physics resolution at command time.
+function visualDurationSpring(visualDuration, bounce, mass) {
+    const root = (2 * Math.PI) / (visualDuration * 1.2);
+    const stiffness = root * root;
+    const damping = 2 * clamp(0.05, 1, 1 - (bounce ?? 0)) * Math.sqrt(stiffness);
+    return { stiffness, damping, mass };
+}
+const hasPhysicsKey = (c) => c.stiffness !== undefined || c.damping !== undefined || c.mass !== undefined;
+/**
+ * Resolve a spring transition config to concrete physics + carry/settle flags (REQ-SPRING-006
+ * precedence). Presence is tested on `!== undefined`.
+ */
+// alloc-ok: lifecycle-edge — config resolution at command time (REQ-SPRING-006 precedence).
+export function resolveSpring(config) {
+    const mass = config.mass ?? DEFAULT_PHYSICS.mass;
+    // Any physics key ⇒ physics used directly; the entire duration family is ignored; velocity carries.
+    if (hasPhysicsKey(config)) {
+        return {
+            physics: {
+                stiffness: config.stiffness ?? DEFAULT_PHYSICS.stiffness,
+                damping: config.damping ?? DEFAULT_PHYSICS.damping,
+                mass,
+            },
+            carryVelocity: true,
+            isResolvedFromDuration: false,
+            calculatedDuration: null,
+        };
+    }
+    // Duration family — velocity is ZEROED (REQ-SPRING-007). visualDuration wins over duration, and a
+    // visualDuration-only config still takes the vd path (REQ-SPRING-006, post-plan-030); it MUST NOT
+    // fall back to default physics.
+    if (config.visualDuration !== undefined) {
+        return {
+            physics: visualDurationSpring(config.visualDuration, config.bounce, mass),
+            carryVelocity: false,
+            isResolvedFromDuration: false, // vd does NOT set the duration flag (REQ-SPRING-011)
+            calculatedDuration: null,
+        };
+    }
+    if (config.duration !== undefined || config.bounce !== undefined) {
+        const fs = findSpring(config.duration ?? DEFAULT_DURATION_MS, config.bounce ?? DEFAULT_BOUNCE, mass);
+        return {
+            physics: { stiffness: fs.stiffness, damping: fs.damping, mass: fs.mass },
+            carryVelocity: false,
+            isResolvedFromDuration: true,
+            calculatedDuration: fs.durationMs,
+        };
+    }
+    // Bare `{type:'spring'}` / empty ⇒ REQ-SPRING-003 defaults (100/10/1); a physics spring (carries).
+    return {
+        physics: { ...DEFAULT_PHYSICS },
+        carryVelocity: true,
+        isResolvedFromDuration: false,
+        calculatedDuration: null,
+    };
+}
+/**
+ * Build a `GeneratorFactory` from a target + config, honoring velocity carry/zero (REQ-SPRING-007).
+ * Duration/visualDuration springs drop the seed's incoming velocity; physics springs keep it —
+ * unless the config carries an AUTHORED `velocity`, which replaces it (REQ-API-053, T21): the pin's
+ * animateMotionValue spreads the authored transition over the live-velocity default
+ * (motion-dom@12.42.2 motion-value.ts:45-50), so the authored number wins on every start.
+ */
+// alloc-ok: lifecycle-edge — factory construction at command time; sampling stays allocation-free.
+export function resolveSpringGenerator(target, config) {
+    const resolved = resolveSpring(config);
+    // findSpring (duration) springs settle at t ≥ calculatedDuration; physics/visualDuration settle by
+    // threshold (settleDuration null). (REQ-SPRING-011)
+    const factory = springGenerator(target, resolved.physics, {
+        settleDuration: resolved.calculatedDuration,
+        ...(config.restSpeed !== undefined ? { restSpeed: config.restSpeed } : {}),
+        ...(config.restDelta !== undefined ? { restDelta: config.restDelta } : {}),
+    });
+    if (resolved.carryVelocity) {
+        const authoredVelocity = config.velocity;
+        if (authoredVelocity === undefined)
+            return factory;
+        // alloc-ok: lifecycle-edge — the authored-velocity reseed wrapper runs at generator construction.
+        return (seed) => factory({ from: seed.from, velocity: authoredVelocity });
+    }
+    // alloc-ok: lifecycle-edge — the zero-velocity reseed wrapper runs at generator construction.
+    return (seed) => factory({ from: seed.from, velocity: 0 });
+}
+/**
+ * Interrupt/retarget (REQ-SPRING-009): build a new generator for `newTarget` from the OUTGOING
+ * generator's analytic state at `atMs` — its exact value and analytic velocity (preferred over any
+ * finite-diff, which avoids systematic velocity loss at high frame rates). Whether that incoming
+ * velocity carries (physics), is replaced by an authored config `velocity` (REQ-API-053), or is
+ * zeroed (duration/visualDuration) is decided by
+ * `resolveSpringGenerator` (REQ-SPRING-007). The result's `value(0)` equals the outgoing `value(atMs)`
+ * exactly — no teleport, no velocity reset. The graph's own interruption seam does the equivalent via
+ * `motionValue.getVelocity()`; this is the explicit spring-layer helper for consumers driving
+ * generators directly (e.g. the Reanimated driver).
+ */
+// alloc-ok: lifecycle-edge — interruption/retarget construction; samples the outgoing generator
+// once, then builds the successor.
+export function retargetSpring(outgoing, atMs, newTarget, config) {
+    const at = outgoing.sample(atMs);
+    return resolveSpringGenerator(newTarget, config)({ from: at.value, velocity: at.velocity });
+}
+// REQ-SPRING-012 getDefaultTransition selection table. transformProps mirrors motion's set.
+const TRANSFORM_PROPS = new Set([
+    'transformPerspective',
+    'x',
+    'y',
+    'z',
+    'translateX',
+    'translateY',
+    'translateZ',
+    'scale',
+    'scaleX',
+    'scaleY',
+    'rotate',
+    'rotateX',
+    'rotateY',
+    'rotateZ',
+    'skew',
+    'skewX',
+    'skewY',
+    'pathRotation',
+]);
+// R8-F1: a spring interpolates EXACTLY two keyframes (origin → target); the pinned Motion throws
+// `spring-two-frames` for any other count. The ONE predicate the reference driver's
+// springKeyframeGenerator throws from AND the native controller PRE-VALIDATES with before issuing any
+// driver command (so a rejected multi-command mount/update mutates nothing — atomicity, review major
+// 36). The worklet driver mirrors the SAME message inline on its 'worklet' path. Returns the loud
+// refusal for a non-two count, else null.
+// alloc-ok: lifecycle-edge — a refusal built at command/pre-validation time, never per frame.
+export function springKeyframeCountRefusal(count) {
+    if (count === 2)
+        return null;
+    return new Error(`a spring transition cannot interpolate through ${count} keyframes — a spring animates exactly ` +
+        'two (origin → target). Keyframe index 2 (the successor) is unreachable; use a tween for a ' +
+        'multi-keyframe array (REQ-API-033, R8-F1).');
+}
+/**
+ * Default transition per property when none is specified (REQ-SPRING-012), keyframe-count-aware to
+ * match the pinned `motion-dom` `getDefaultTransition(valueKey, { keyframes })`
+ * (default-transitions.ts): MORE than two keyframes → an 800ms keyframes transition (regardless of
+ * property); otherwise a transform prop gets an underdamped spring (scale: critically-damped 550,
+ * damping 30 for a non-zero target and 2√550 at exactly 0; other transforms: 500/25), and every
+ * other property gets the 300ms shallow-browser tween. A scalar animation is the two-keyframe case
+ * (`[from, target]`); the last keyframe drives the scale-at-zero branch (Motion reads `keyframes[1]`).
+ */
+// alloc-ok: lifecycle-edge — per-property default selection at command time.
+export function getDefaultTransition(valueKey, keyframes) {
+    if (keyframes.length > 2) {
+        return { type: 'keyframes', duration: 0.8 };
+    }
+    if (TRANSFORM_PROPS.has(valueKey)) {
+        if (valueKey.startsWith('scale')) {
+            const last = keyframes[keyframes.length - 1];
+            const target = typeof last === 'number' ? last : 0;
+            return {
+                type: 'spring',
+                stiffness: 550,
+                damping: target === 0 ? 2 * Math.sqrt(550) : 30,
+                restSpeed: 10,
+            };
+        }
+        return { type: 'spring', stiffness: 500, damping: 25, restSpeed: 10 };
+    }
+    return { type: 'keyframes', ease: [0.25, 0.1, 0.35, 1], duration: 0.3 };
+}
+// Pinned drag-layer physics (startAnimation spread: timeConstant 750, restDelta 1, restSpeed 10;
+// motion-dom inertia `power` default 0.8 — single-sourced with PROJECTION_POWER's pin note).
+export const DRAG_INERTIA_DEFAULTS = {
+    power: 0.8,
+    timeConstant: 750,
+    restDelta: 1,
+    restSpeed: 10,
+};
+// The pin's elastic-conditional boundary-spring pairs (VisualElementDragControls: dragElastic
+// truthy → 200/40, falsy → 1e6/1e7 "overdamp the boundary spring"). dragTransition overrides.
+// Shared frozen constants (never a per-call literal — the frame-path allocation law, REQ-DRIVER-021).
+const ELASTIC_BOUNDARY_BOUNCE = Object.freeze({ bounceStiffness: 200, bounceDamping: 40 });
+const RIGID_BOUNDARY_BOUNCE = Object.freeze({
+    bounceStiffness: 1000000,
+    bounceDamping: 10000000,
+});
+export function dragInertiaBounce(elastic) {
+    return elastic !== undefined && elastic > 0 ? ELASTIC_BOUNDARY_BOUNCE : RIGID_BOUNDARY_BOUNCE;
+}

package/dist/types.cjs

@@ -0,0 +1,4 @@
+"use strict";
+// Host-agnostic motion-graph contracts (SPEC-CORE §3). Zero host dependencies (REQ-CORE-003):
+// this file imports nothing from react-native / reanimated / gesture-handler / motion / react.
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types.d.cts

@@ -0,0 +1,175 @@
+/** Injectable time source. Core reads no ambient time (`Date.now`/`performance.now`) — REQ-CLOCK-001. */
+export interface Clock {
+    now(): number;
+}
+/**
+ * Per-frame step seam (REQ-CLOCK-001). Production drives this from vsync; tests pump frames
+ * explicitly. A step receives the elapsed time since the previous frame (already dt-clamped by the
+ * graph, REQ-CLOCK-003).
+ */
+export interface Scheduler {
+    onFrame(step: (dtMs: number) => void): () => void;
+}
+export type ValueChangeListener<T> = (value: T) => void;
+/**
+ * A derived value with a re-attachable input lifecycle (review r4): consumers that bind and
+ * unbind across React effect replays detach/re-attach the SAME value; refresh() resyncs
+ * synchronously when the compute's captured parameters change. Detaching also CANCELS any
+ * already-queued recompute (review r5) — a detached node never applies or notifies.
+ */
+export interface DerivedMotionValue<T> extends MotionValue<T> {
+    attachInputs(): void;
+    detachInputs(): void;
+    refresh(): void;
+}
+/**
+ * The structural input contract of a derivation (REQ-VALUE-002: "one or more motion values" —
+ * ANY value type; REQ-VALUE-013 glitch-freeness holds regardless of T). Every MotionValue<T>
+ * satisfies this shape, so string/color values compose into derivations like numeric ones.
+ */
+export interface DerivedSource<V = unknown> {
+    get(): V;
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Per-position value types of a derivation's input tuple (review r6): the compute receives the
+ * REAL value type of each input — never-erasure would reject valid string code while admitting
+ * mistyped callbacks.
+ */
+export type DerivedSourceValues<Inputs extends readonly DerivedSource[]> = {
+    [Index in keyof Inputs]: Inputs[Index] extends DerivedSource<infer Value> ? Value : never;
+};
+export type MotionValueEvent = 'change' | 'animationStart' | 'animationComplete' | 'animationCancel' | 'destroy';
+/**
+ * The live animated signal (REQ-VALUE-001/010/011/012). Generic over `T` (default `number`);
+ * non-numeric values are opaque and report velocity `0`. `subscribe` never triggers a host render.
+ */
+export interface MotionValue<T = number> {
+    get(): T;
+    /** Set the value; velocity is computed from clock-timestamped samples. */
+    set(value: T): void;
+    /**
+     * Teleport: set the value, reset velocity to `0`, and END any active animation through
+     * `stop()` (a cancellation) — the pinned `jump(v, endAnimation = true)` shape (r15): a dead
+     * flight must never overwrite the teleported value on the next frame.
+     */
+    jump(value: T): void;
+    subscribe(listener: ValueChangeListener<T>): () => void;
+    /** Velocity in units/sec; `0` for non-numeric `T`; `0` if the last sample is stale. */
+    getVelocity(): number;
+    /**
+     * `change` delivers the latest value (pinned payload, r15); lifecycle events carry NONE —
+     * no broad union overload exists (r16 major 5: it made a payload-taking lifecycle listener
+     * representable while runtime supplies undefined). Union-event call sites narrow first.
+     */
+    on(event: 'change', listener: (latest: T) => void): () => void;
+    on(event: Exclude<MotionValueEvent, 'change'>, listener: () => void): () => void;
+    /** Stop any animation currently driving this value, leaving it at its current value. */
+    stop(): void;
+    /**
+     * Whether an animation is currently driving this value (pinned motion-dom member, r12): the
+     * style-binding lane refuses an ALREADY-animating value at attach, not just one that starts
+     * while bound. Derived values are never animated directly and always report false.
+     */
+    isAnimating(): boolean;
+    destroy(): void;
+}
+/** Seed handed to a generator factory when an animation (re)starts on a value (REQ-CORE-002). */
+export interface GeneratorSeed {
+    from: number;
+    velocity: number;
+}
+/**
+ * The record is OWNED and REUSED by its generator — sample() mutates and returns the same object
+ * every call (motion's next() contract; allocation-free per-frame sampling, REQ-DRIVER-015).
+ * Read the scalars immediately; never retain the record across sample() calls.
+ */
+export interface GeneratorSample {
+    value: number;
+    velocity: number;
+    done: boolean;
+}
+/**
+ * An animation source sampled purely by elapsed time (REQ-CORE-001). Core hosts generators through
+ * this interface but does not parameterize their numerics — spring/timing math is SPEC-SPRING's.
+ */
+export interface Generator {
+    sample(elapsedMs: number): GeneratorSample;
+    /**
+     * The value to COMMIT when the trajectory finishes, when that differs from what `sample` reports
+     * at the terminal instant — the pin's `getFinalKeyframe` position.
+     *
+     * The pinned Motion applies `getFinalKeyframe` INSIDE `tick`, gated on
+     * `holdTime === null && (state === 'finished' || (state === 'running' && done))`, and only then
+     * calls `finish()`, which never touches the value (motion-dom `JSAnimation`). A FRESH,
+     * non-autoplaying instance is `paused`, so `holdTime` is non-null and neither disjunct holds: its
+     * `sample()` returns the raw fold, which is how this repo's goldens are generated. An
+     * already-FINISHED instance takes the override at ANY sampled time, mid-play included; a RUNNING
+     * one takes it only at or past `totalDuration`, because that disjunct also requires `done`
+     * (recomputed in `tick` as `currentTime >= totalDuration` at forward speed). 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.
+     *
+     * Absent on every generator whose terminal sample already IS its resting value — only a fractional
+     * `repeat` fold sets it (REQ-TIMING-003). `stepProp` is the one consumer, so both drivers get the
+     * rule from one place.
+     *
+     * **A generator that WRAPS another and rebuilds the object owes this forward.** It is optional, so
+     * a wrapper that omits it silently drops the wrapped trajectory's resting value — exactly what
+     * `delayGenerator` did until the H2 round-1 review caught it. Known wrappers that do NOT forward,
+     * and why that is currently safe: `presence/controller.ts`'s min/max aggregators and its
+     * `normalizedFactory` (which would have to RESCALE a finish value, not forward it). No fold can
+     * reach them — `shippedSurface.ts` lists `repeat`/`repeatType`/`repeatDelay`/`delay` in
+     * `EXIT_LANE_INEXECUTABLE_OPTIONS`, and the presence controller never builds a repeat fold. Named
+     * here so a change that makes them reachable cannot reopen the defect silently (H2 round-2
+     * review MINOR 2). A new wrapper needs its own COMPOSED floor: a defect in composition is
+     * invisible to every floor that tests the parts.
+     */
+    readonly finalValue?: number | undefined;
+}
+/**
+ * Constructs a generator from a seed. The seam that carries velocity across interruption: on start
+ * the seed is the value's current value+velocity; on retarget the new factory is re-seeded with the
+ * current value+velocity so motion continues from the present visual state (REQ-CORE-002).
+ */
+export type GeneratorFactory = (seed: GeneratorSeed) => Generator;
+/** Handle to an in-flight animation. */
+export interface Animation {
+    stop(): void;
+    readonly done: boolean;
+}
+/**
+ * Unsettled-work handle (REQ-SETTLE-001). Gesture and layout (non-core) call `registerActivity`
+ * and hold this handle open while their work is in flight; `release` marks that source done.
+ */
+export interface ActivityHandle {
+    release(): void;
+}
+/**
+ * The motion graph: value factory, derived graph, animation registry, and settle ledger. Owns the
+ * injected clock/scheduler and the definition of graph quiescence (REQ-SETTLE-001).
+ */
+export interface MotionGraph {
+    motionValue<T = number>(initial: T): MotionValue<T>;
+    /**
+     * Read-only value computed from any motion values; recomputes off the host path, glitch-free.
+     * Two call shapes (review r6 + r7): with NO explicit type arguments the input tuple infers
+     * per position, so the compute sees each input's REAL value type and mistyped callbacks are
+     * compile errors; with an explicit `derived<T>(...)` output type (the original public shape)
+     * values arrive as `unknown` and the caller narrows deliberately — sound in both directions.
+     */
+    derived<const Inputs extends readonly DerivedSource[], T>(inputs: Inputs, compute: (...values: DerivedSourceValues<Inputs>) => T): DerivedMotionValue<T>;
+    derived<T>(inputs: readonly DerivedSource[], compute: (...values: unknown[]) => T): DerivedMotionValue<T>;
+    /** Start (or interrupt-and-restart) an animation driving `value`. */
+    animate(value: MotionValue<number>, factory: GeneratorFactory): Animation;
+    activeAnimationCount(): number;
+    registerActivity(): ActivityHandle;
+    /** True iff `activeAnimationCount() === 0` and no activity handle is open. */
+    isSettled(): boolean;
+    /** Resolves exactly on the frame the graph transitions to settled; re-armable; fail-closed. */
+    whenSettled(): Promise<void>;
+}
+export interface MotionGraphOptions {
+    clock: Clock;
+    scheduler: Scheduler;
+}

package/dist/types.d.ts

@@ -0,0 +1,175 @@
+/** Injectable time source. Core reads no ambient time (`Date.now`/`performance.now`) — REQ-CLOCK-001. */
+export interface Clock {
+    now(): number;
+}
+/**
+ * Per-frame step seam (REQ-CLOCK-001). Production drives this from vsync; tests pump frames
+ * explicitly. A step receives the elapsed time since the previous frame (already dt-clamped by the
+ * graph, REQ-CLOCK-003).
+ */
+export interface Scheduler {
+    onFrame(step: (dtMs: number) => void): () => void;
+}
+export type ValueChangeListener<T> = (value: T) => void;
+/**
+ * A derived value with a re-attachable input lifecycle (review r4): consumers that bind and
+ * unbind across React effect replays detach/re-attach the SAME value; refresh() resyncs
+ * synchronously when the compute's captured parameters change. Detaching also CANCELS any
+ * already-queued recompute (review r5) — a detached node never applies or notifies.
+ */
+export interface DerivedMotionValue<T> extends MotionValue<T> {
+    attachInputs(): void;
+    detachInputs(): void;
+    refresh(): void;
+}
+/**
+ * The structural input contract of a derivation (REQ-VALUE-002: "one or more motion values" —
+ * ANY value type; REQ-VALUE-013 glitch-freeness holds regardless of T). Every MotionValue<T>
+ * satisfies this shape, so string/color values compose into derivations like numeric ones.
+ */
+export interface DerivedSource<V = unknown> {
+    get(): V;
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Per-position value types of a derivation's input tuple (review r6): the compute receives the
+ * REAL value type of each input — never-erasure would reject valid string code while admitting
+ * mistyped callbacks.
+ */
+export type DerivedSourceValues<Inputs extends readonly DerivedSource[]> = {
+    [Index in keyof Inputs]: Inputs[Index] extends DerivedSource<infer Value> ? Value : never;
+};
+export type MotionValueEvent = 'change' | 'animationStart' | 'animationComplete' | 'animationCancel' | 'destroy';
+/**
+ * The live animated signal (REQ-VALUE-001/010/011/012). Generic over `T` (default `number`);
+ * non-numeric values are opaque and report velocity `0`. `subscribe` never triggers a host render.
+ */
+export interface MotionValue<T = number> {
+    get(): T;
+    /** Set the value; velocity is computed from clock-timestamped samples. */
+    set(value: T): void;
+    /**
+     * Teleport: set the value, reset velocity to `0`, and END any active animation through
+     * `stop()` (a cancellation) — the pinned `jump(v, endAnimation = true)` shape (r15): a dead
+     * flight must never overwrite the teleported value on the next frame.
+     */
+    jump(value: T): void;
+    subscribe(listener: ValueChangeListener<T>): () => void;
+    /** Velocity in units/sec; `0` for non-numeric `T`; `0` if the last sample is stale. */
+    getVelocity(): number;
+    /**
+     * `change` delivers the latest value (pinned payload, r15); lifecycle events carry NONE —
+     * no broad union overload exists (r16 major 5: it made a payload-taking lifecycle listener
+     * representable while runtime supplies undefined). Union-event call sites narrow first.
+     */
+    on(event: 'change', listener: (latest: T) => void): () => void;
+    on(event: Exclude<MotionValueEvent, 'change'>, listener: () => void): () => void;
+    /** Stop any animation currently driving this value, leaving it at its current value. */
+    stop(): void;
+    /**
+     * Whether an animation is currently driving this value (pinned motion-dom member, r12): the
+     * style-binding lane refuses an ALREADY-animating value at attach, not just one that starts
+     * while bound. Derived values are never animated directly and always report false.
+     */
+    isAnimating(): boolean;
+    destroy(): void;
+}
+/** Seed handed to a generator factory when an animation (re)starts on a value (REQ-CORE-002). */
+export interface GeneratorSeed {
+    from: number;
+    velocity: number;
+}
+/**
+ * The record is OWNED and REUSED by its generator — sample() mutates and returns the same object
+ * every call (motion's next() contract; allocation-free per-frame sampling, REQ-DRIVER-015).
+ * Read the scalars immediately; never retain the record across sample() calls.
+ */
+export interface GeneratorSample {
+    value: number;
+    velocity: number;
+    done: boolean;
+}
+/**
+ * An animation source sampled purely by elapsed time (REQ-CORE-001). Core hosts generators through
+ * this interface but does not parameterize their numerics — spring/timing math is SPEC-SPRING's.
+ */
+export interface Generator {
+    sample(elapsedMs: number): GeneratorSample;
+    /**
+     * The value to COMMIT when the trajectory finishes, when that differs from what `sample` reports
+     * at the terminal instant — the pin's `getFinalKeyframe` position.
+     *
+     * The pinned Motion applies `getFinalKeyframe` INSIDE `tick`, gated on
+     * `holdTime === null && (state === 'finished' || (state === 'running' && done))`, and only then
+     * calls `finish()`, which never touches the value (motion-dom `JSAnimation`). A FRESH,
+     * non-autoplaying instance is `paused`, so `holdTime` is non-null and neither disjunct holds: its
+     * `sample()` returns the raw fold, which is how this repo's goldens are generated. An
+     * already-FINISHED instance takes the override at ANY sampled time, mid-play included; a RUNNING
+     * one takes it only at or past `totalDuration`, because that disjunct also requires `done`
+     * (recomputed in `tick` as `currentTime >= totalDuration` at forward speed). 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.
+     *
+     * Absent on every generator whose terminal sample already IS its resting value — only a fractional
+     * `repeat` fold sets it (REQ-TIMING-003). `stepProp` is the one consumer, so both drivers get the
+     * rule from one place.
+     *
+     * **A generator that WRAPS another and rebuilds the object owes this forward.** It is optional, so
+     * a wrapper that omits it silently drops the wrapped trajectory's resting value — exactly what
+     * `delayGenerator` did until the H2 round-1 review caught it. Known wrappers that do NOT forward,
+     * and why that is currently safe: `presence/controller.ts`'s min/max aggregators and its
+     * `normalizedFactory` (which would have to RESCALE a finish value, not forward it). No fold can
+     * reach them — `shippedSurface.ts` lists `repeat`/`repeatType`/`repeatDelay`/`delay` in
+     * `EXIT_LANE_INEXECUTABLE_OPTIONS`, and the presence controller never builds a repeat fold. Named
+     * here so a change that makes them reachable cannot reopen the defect silently (H2 round-2
+     * review MINOR 2). A new wrapper needs its own COMPOSED floor: a defect in composition is
+     * invisible to every floor that tests the parts.
+     */
+    readonly finalValue?: number | undefined;
+}
+/**
+ * Constructs a generator from a seed. The seam that carries velocity across interruption: on start
+ * the seed is the value's current value+velocity; on retarget the new factory is re-seeded with the
+ * current value+velocity so motion continues from the present visual state (REQ-CORE-002).
+ */
+export type GeneratorFactory = (seed: GeneratorSeed) => Generator;
+/** Handle to an in-flight animation. */
+export interface Animation {
+    stop(): void;
+    readonly done: boolean;
+}
+/**
+ * Unsettled-work handle (REQ-SETTLE-001). Gesture and layout (non-core) call `registerActivity`
+ * and hold this handle open while their work is in flight; `release` marks that source done.
+ */
+export interface ActivityHandle {
+    release(): void;
+}
+/**
+ * The motion graph: value factory, derived graph, animation registry, and settle ledger. Owns the
+ * injected clock/scheduler and the definition of graph quiescence (REQ-SETTLE-001).
+ */
+export interface MotionGraph {
+    motionValue<T = number>(initial: T): MotionValue<T>;
+    /**
+     * Read-only value computed from any motion values; recomputes off the host path, glitch-free.
+     * Two call shapes (review r6 + r7): with NO explicit type arguments the input tuple infers
+     * per position, so the compute sees each input's REAL value type and mistyped callbacks are
+     * compile errors; with an explicit `derived<T>(...)` output type (the original public shape)
+     * values arrive as `unknown` and the caller narrows deliberately — sound in both directions.
+     */
+    derived<const Inputs extends readonly DerivedSource[], T>(inputs: Inputs, compute: (...values: DerivedSourceValues<Inputs>) => T): DerivedMotionValue<T>;
+    derived<T>(inputs: readonly DerivedSource[], compute: (...values: unknown[]) => T): DerivedMotionValue<T>;
+    /** Start (or interrupt-and-restart) an animation driving `value`. */
+    animate(value: MotionValue<number>, factory: GeneratorFactory): Animation;
+    activeAnimationCount(): number;
+    registerActivity(): ActivityHandle;
+    /** True iff `activeAnimationCount() === 0` and no activity handle is open. */
+    isSettled(): boolean;
+    /** Resolves exactly on the frame the graph transitions to settled; re-armable; fail-closed. */
+    whenSettled(): Promise<void>;
+}
+export interface MotionGraphOptions {
+    clock: Clock;
+    scheduler: Scheduler;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// Host-agnostic motion-graph contracts (SPEC-CORE §3). Zero host dependencies (REQ-CORE-003):
+// this file imports nothing from react-native / reanimated / gesture-handler / motion / react.
+export {};