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

package/dist/transformTemplate.js

@@ -0,0 +1,215 @@
+'worklet';
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// Bounded transform-template support (T17 packet, specs/T17-TRANSFORM-TEMPLATE-BUILD-PACKET.md):
+// the canonical generated-string builder (pin `motion-dom buildTransform` format and value
+// typing) and the bounded parser that turns a template's RETURN string into the RN transform
+// array. Grammar is exactly the canonical builder's function set; anything off-grammar fails
+// loud naming the offending token — never a silent partial parse (the R13 law). Host-agnostic
+// (REQ-CORE-003): no host imports.
+//
+// alloc-ok: frame — template composition is string-valued by pin design (motion-dom
+// buildTransform allocates the composed string per frame); the parser allocates only the small
+// output entry list, proportional to the entry count.
+// Canonical key order (pin `transformPropOrder` restricted to the shipped transform keys — the
+// same list composeTransform commits, so template and non-template composition agree).
+const TEMPLATE_KEY_ORDER = [
+    'perspective',
+    'x',
+    'y',
+    'scale',
+    'scaleX',
+    'scaleY',
+    'rotate',
+    'rotateX',
+    'rotateY',
+    'skewX',
+    'skewY',
+];
+// Function name in the generated string per key (pin: translateAlias x→translateX, y→translateY).
+const KEY_FUNCTION = {
+    perspective: 'perspective',
+    x: 'translateX',
+    y: 'translateY',
+    scale: 'scale',
+    scaleX: 'scaleX',
+    scaleY: 'scaleY',
+    rotate: 'rotate',
+    rotateX: 'rotateX',
+    rotateY: 'rotateY',
+    skewX: 'skewX',
+    skewY: 'skewY',
+};
+// Plain-object lookups, never Sets: worklet captures stay in the most conservative shareable
+// shape — records of primitives (the composeTransform.ts law) — so serialization can never be
+// the failure mode on the UI runtime.
+const DEGREE_KEYS = Object.freeze({
+    rotate: 1,
+    rotateX: 1,
+    rotateY: 1,
+    skewX: 1,
+    skewY: 1,
+});
+const LENGTH_KEYS = Object.freeze({ perspective: 1, x: 1, y: 1 });
+// Pin build-transform's default law: `value === (key.startsWith("scale") ? 1 : 0)`.
+const SCALE_KEYS = Object.freeze({ scale: 1, scaleX: 1, scaleY: 1 });
+// The values-map key name per canonical key (pin latestValues naming: transformPerspective).
+const VALUES_MAP_KEY = {
+    perspective: 'transformPerspective',
+    x: 'x',
+    y: 'y',
+    scale: 'scale',
+    scaleX: 'scaleX',
+    scaleY: 'scaleY',
+    rotate: 'rotate',
+    rotateX: 'rotateX',
+    rotateY: 'rotateY',
+    skewX: 'skewX',
+    skewY: 'skewY',
+};
+function typedValueFor(key, value) {
+    const unit = DEGREE_KEYS[key] === 1 ? 'deg' : LENGTH_KEYS[key] === 1 ? 'px' : '';
+    return `${value}${unit}`;
+}
+function assertFiniteTemplateValue(key, value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`transformTemplate values: key '${key}' must be a finite number, got ${String(value)} (T17).`);
+    }
+}
+/**
+ * The canonical generated string (pin `buildTransform`): `${fn}(${valueWithUnit})` joined by
+ * spaces in canonical order. A non-finite value fails loud naming the key.
+ */
+export function buildTransformString(values) {
+    let out = '';
+    for (const key of TEMPLATE_KEY_ORDER) {
+        const value = values[key];
+        if (value === undefined)
+            continue;
+        assertFiniteTemplateValue(key, value);
+        out += `${out === '' ? '' : ' '}${KEY_FUNCTION[key]}(${typedValueFor(key, value)})`;
+    }
+    return out;
+}
+/**
+ * The pin's template call args (motion-dom build-transform, verbatim loop): the values map
+ * carries every PRESENT key typed (defaults INCLUDED — `!valueIsDefault || transformTemplate`);
+ * the generated string carries only NON-DEFAULT values in canonical order, so an all-default
+ * transform hands the template '' (pin `transformIsDefault ? "" : transformString`).
+ */
+export function buildTransformTemplateArgs(values) {
+    const typed = {};
+    let generated = '';
+    for (const key of TEMPLATE_KEY_ORDER) {
+        const value = values[key];
+        if (value === undefined)
+            continue;
+        assertFiniteTemplateValue(key, value);
+        const typedValue = typedValueFor(key, value);
+        typed[VALUES_MAP_KEY[key]] = typedValue;
+        const isDefault = SCALE_KEYS[key] === 1 ? value === 1 : value === 0;
+        if (!isDefault) {
+            generated += `${generated === '' ? '' : ' '}${KEY_FUNCTION[key]}(${typedValue})`;
+        }
+    }
+    return { values: typed, generated };
+}
+// Per-function unit law: translate* take px|%; scale* are unitless; rotate*/skew* take
+// deg|unitless; perspective takes px|unitless. Anything else is a named refusal.
+const FUNCTION_UNITS = {
+    perspective: ['px', ''],
+    translate: ['px', '%'],
+    translateX: ['px', '%'],
+    translateY: ['px', '%'],
+    scale: [''],
+    scaleX: [''],
+    scaleY: [''],
+    rotate: ['deg', ''],
+    rotateX: ['deg', ''],
+    rotateY: ['deg', ''],
+    skewX: ['deg', ''],
+    skewY: ['deg', ''],
+};
+const ENTRY_NAME = {
+    perspective: 'perspective',
+    translateX: 'translateX',
+    translateY: 'translateY',
+    scale: 'scale',
+    scaleX: 'scaleX',
+    scaleY: 'scaleY',
+    rotate: 'rotate',
+    rotateX: 'rotateX',
+    rotateY: 'rotateY',
+    skewX: 'skewX',
+    skewY: 'skewY',
+};
+const VALUE_RE = /^(-?(?:\d+(?:\.\d+)?|\.\d+))(px|%|deg)?$/;
+function fail(templateOutput, reason) {
+    throw new Error(`transformTemplate output '${templateOutput}': ${reason} (T17 bounded grammar).`);
+}
+function parseValue(templateOutput, fn, raw) {
+    const m = VALUE_RE.exec(raw.trim());
+    if (m === null) {
+        fail(templateOutput, `unparseable value '${raw}' for ${fn}`);
+    }
+    const [, numeral, rawUnit] = m;
+    const unit = (rawUnit ?? '');
+    const allowed = FUNCTION_UNITS[fn];
+    if (!allowed.includes(unit)) {
+        fail(templateOutput, `unit '${unit || '(none)'}' is not valid for ${fn}`);
+    }
+    // Percent translate entries ride RN's percent-string form. Angle entries commit as RN degree
+    // STRINGS — the shipped composeTransform output shape (RN types the rotate/skew family
+    // string-typed; a bare number is not a valid entry). A unitless angle is degrees by the pin's
+    // getValueAsType law. Everything else commits numeric.
+    if (unit === '%')
+        return `${numeral}%`;
+    if (allowed.includes('deg'))
+        return `${numeral}deg`;
+    return Number(numeral);
+}
+/**
+ * Parse a template's RETURN string into the ordered RN transform array. The grammar is the
+ * canonical builder's function set with px/%/deg/unitless values; `translate` takes 1-2 args
+ * (comma or space separated). Anything else throws naming the offending token.
+ */
+export function parseTransformTemplateOutput(templateOutput) {
+    const out = [];
+    let rest = templateOutput.trim();
+    while (rest.length > 0) {
+        const open = rest.indexOf('(');
+        const fn = open === -1 ? rest.trim() : rest.slice(0, open).trim();
+        if (open === -1 || fn === '' || /\s/.test(fn)) {
+            fail(templateOutput, `malformed token '${fn}' — expected fn(args)`);
+        }
+        if (!(fn in FUNCTION_UNITS) && fn !== 'translate') {
+            fail(templateOutput, `transform function '${fn}' is outside the bounded grammar`);
+        }
+        const close = rest.indexOf(')', open);
+        if (close === -1) {
+            fail(templateOutput, `unbalanced parens near '${fn}('`);
+        }
+        const argsRaw = rest.slice(open + 1, close);
+        const args = argsRaw.includes(',')
+            ? argsRaw.split(',').map((a) => a.trim())
+            : argsRaw.trim() === ''
+                ? []
+                : argsRaw.trim().split(/\s+/);
+        if (fn === 'translate') {
+            if (args.length === 0 || args.length > 2) {
+                fail(templateOutput, `translate takes 1 or 2 args, got ${args.length}`);
+            }
+            out.push({ translateX: parseValue(templateOutput, 'translate', args[0]) });
+            if (args.length === 2) {
+                out.push({ translateY: parseValue(templateOutput, 'translate', args[1]) });
+            }
+        }
+        else {
+            if (args.length !== 1) {
+                fail(templateOutput, `${fn} takes exactly 1 arg, got ${args.length}`);
+            }
+            out.push({ [ENTRY_NAME[fn]]: parseValue(templateOutput, fn, args[0]) });
+        }
+        rest = rest.slice(close + 1).trim();
+    }
+    return out;
+}

package/dist/transition.cjs

@@ -0,0 +1,231 @@
+"use strict";
+// @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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DRAG_INERTIA_DEFAULTS = void 0;
+exports.resolveSpring = resolveSpring;
+exports.resolveSpringGenerator = resolveSpringGenerator;
+exports.retargetSpring = retargetSpring;
+exports.springKeyframeCountRefusal = springKeyframeCountRefusal;
+exports.getDefaultTransition = getDefaultTransition;
+exports.dragInertiaBounce = dragInertiaBounce;
+const spring_1 = require("./spring.cjs");
+// 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).
+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.
+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 = (0, spring_1.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.
+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.
+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.
+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).
+exports.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,
+});
+function dragInertiaBounce(elastic) {
+    return elastic !== undefined && elastic > 0 ? ELASTIC_BOUNDARY_BOUNCE : RIGID_BOUNDARY_BOUNCE;
+}

package/dist/transition.d.cts

@@ -0,0 +1,89 @@
+import type { SpringPhysics } from "./spring.cjs";
+import type { Generator, GeneratorFactory } from "./types.cjs";
+import type { Transition } from "./component/types.cjs";
+export interface SpringConfig {
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    duration?: number;
+    bounce?: number;
+    visualDuration?: number;
+    velocity?: number;
+    restSpeed?: number;
+    restDelta?: number;
+}
+export interface ResolvedSpring {
+    physics: SpringPhysics;
+    carryVelocity: boolean;
+    isResolvedFromDuration: boolean;
+    calculatedDuration: number | null;
+}
+/**
+ * Resolve a spring transition config to concrete physics + carry/settle flags (REQ-SPRING-006
+ * precedence). Presence is tested on `!== undefined`.
+ */
+export declare function resolveSpring(config: SpringConfig): ResolvedSpring;
+/**
+ * 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.
+ */
+export declare function resolveSpringGenerator(target: number, config: SpringConfig): GeneratorFactory;
+/**
+ * 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).
+ */
+export declare function retargetSpring(outgoing: Generator, atMs: number, newTarget: number, config: SpringConfig): Generator;
+export declare function springKeyframeCountRefusal(count: number): Error | null;
+export type DefaultTransition = ({
+    type: 'spring';
+    stiffness: number;
+    damping: number;
+    restSpeed: number;
+} & Pick<Transition, 'delay' | 'repeat' | 'repeatType' | 'repeatDelay'>) | ({
+    type: 'keyframes';
+    ease?: readonly [number, number, number, number];
+    duration: number;
+} & Pick<Transition, 'delay' | 'repeat' | 'repeatType' | 'repeatDelay'>);
+/**
+ * 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]`).
+ */
+export declare function getDefaultTransition(valueKey: string, keyframes: readonly (number | null)[]): DefaultTransition;
+export interface InertiaTransition {
+    readonly type: 'inertia';
+    /** Pinned drag-layer defaults (VisualElementDragControls.startAnimation); all fields resolved */
+    readonly power: number;
+    readonly timeConstant: number;
+    readonly bounceStiffness: number;
+    readonly bounceDamping: number;
+    readonly restDelta: number;
+    readonly restSpeed: number;
+    /** Constraint bounds for the boundary spring; ±Infinity sentinels are legal (open sides). */
+    readonly min?: number;
+    readonly max?: number;
+}
+export declare const DRAG_INERTIA_DEFAULTS: {
+    readonly power: 0.8;
+    readonly timeConstant: 750;
+    readonly restDelta: 1;
+    readonly restSpeed: 10;
+};
+export declare function dragInertiaBounce(elastic: number | undefined): {
+    readonly bounceStiffness: number;
+    readonly bounceDamping: number;
+};

package/dist/transition.d.ts

@@ -0,0 +1,89 @@
+import type { SpringPhysics } from "./spring.js";
+import type { Generator, GeneratorFactory } from "./types.js";
+import type { Transition } from "./component/types.js";
+export interface SpringConfig {
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    duration?: number;
+    bounce?: number;
+    visualDuration?: number;
+    velocity?: number;
+    restSpeed?: number;
+    restDelta?: number;
+}
+export interface ResolvedSpring {
+    physics: SpringPhysics;
+    carryVelocity: boolean;
+    isResolvedFromDuration: boolean;
+    calculatedDuration: number | null;
+}
+/**
+ * Resolve a spring transition config to concrete physics + carry/settle flags (REQ-SPRING-006
+ * precedence). Presence is tested on `!== undefined`.
+ */
+export declare function resolveSpring(config: SpringConfig): ResolvedSpring;
+/**
+ * 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.
+ */
+export declare function resolveSpringGenerator(target: number, config: SpringConfig): GeneratorFactory;
+/**
+ * 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).
+ */
+export declare function retargetSpring(outgoing: Generator, atMs: number, newTarget: number, config: SpringConfig): Generator;
+export declare function springKeyframeCountRefusal(count: number): Error | null;
+export type DefaultTransition = ({
+    type: 'spring';
+    stiffness: number;
+    damping: number;
+    restSpeed: number;
+} & Pick<Transition, 'delay' | 'repeat' | 'repeatType' | 'repeatDelay'>) | ({
+    type: 'keyframes';
+    ease?: readonly [number, number, number, number];
+    duration: number;
+} & Pick<Transition, 'delay' | 'repeat' | 'repeatType' | 'repeatDelay'>);
+/**
+ * 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]`).
+ */
+export declare function getDefaultTransition(valueKey: string, keyframes: readonly (number | null)[]): DefaultTransition;
+export interface InertiaTransition {
+    readonly type: 'inertia';
+    /** Pinned drag-layer defaults (VisualElementDragControls.startAnimation); all fields resolved */
+    readonly power: number;
+    readonly timeConstant: number;
+    readonly bounceStiffness: number;
+    readonly bounceDamping: number;
+    readonly restDelta: number;
+    readonly restSpeed: number;
+    /** Constraint bounds for the boundary spring; ±Infinity sentinels are legal (open sides). */
+    readonly min?: number;
+    readonly max?: number;
+}
+export declare const DRAG_INERTIA_DEFAULTS: {
+    readonly power: 0.8;
+    readonly timeConstant: 750;
+    readonly restDelta: 1;
+    readonly restSpeed: 10;
+};
+export declare function dragInertiaBounce(elastic: number | undefined): {
+    readonly bounceStiffness: number;
+    readonly bounceDamping: number;
+};