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

package/dist/worklet-layout/layout/types.js

@@ -0,0 +1,36 @@
+'worklet';
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// SPEC-LAYOUT §2 — the plain geometric data the projection engine operates on. Host-agnostic: a `Rect` is a
+// bounding box in its projection frame, fed in by the host measurement adapter as plain numbers; `core` never
+// imports a Fabric measure API (REQ-CORE-003). Projection sessions may operate in any caller-chosen coherent
+// frame; layout identity is stricter and accepts only branded common/window-space rects so cross-container
+// FLIP cannot accidentally compare parent-relative coordinates (REQ-LAYOUT-020). A `Transform` is the
+// transform-ONLY correction the substrate executes — translate + scale, no rotation/skew at M1 (the FLIP
+// correction never mutates layout-authoritative style, REQ-LAYOUT-001).
+const WINDOW_SPACE_RECT = Symbol('WindowSpaceRect');
+function requireFiniteWindowSpaceField(rect, field) {
+  'worklet';
+    const value = rect[field];
+    if (!Number.isFinite(value)) {
+        throw new Error(`layout identity: window-space rect field '${field}' is ${JSON.stringify(value)}; ` +
+            'a finite number is required before entering the projection registry.');
+    }
+    return value;
+}
+/**
+ * Brand a host-validated common-space measurement for the layoutId registry. Host bindings own the
+ * measurement primitive; core owns the unrepresentable-if-raw registry contract.
+ */
+// alloc-ok: js-thread — measure-commit conversion on the JS side (onLayout path), never per frame.
+export function toWindowSpaceRect(rect) {
+  'worklet';
+    const x = requireFiniteWindowSpaceField(rect, 'x');
+    const y = requireFiniteWindowSpaceField(rect, 'y');
+    const width = requireFiniteWindowSpaceField(rect, 'width');
+    const height = requireFiniteWindowSpaceField(rect, 'height');
+    if (width <= 0 || height <= 0) {
+        throw new Error(`layout identity: window-space rect dimensions must be positive before projection ` +
+            `(width=${width}, height=${height}).`);
+    }
+    return { x, y, width, height };
+}

package/dist/worklet-layout/spring.js

@@ -0,0 +1,125 @@
+'worklet';
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// Analytic scalar spring solver (SPEC-SPRING REQ-SPRING-001/002/008/010/011). A pure closed-form
+// evaluator — value(t)/velocity(t) computed directly per damping regime, never stepped by Euler/RK.
+// Host-agnostic (REQ-CORE-003): imports nothing from motion/react. Numerics are pinned to
+// motion@12.42.2 (see specs/SPEC-SPRING.md) and proven by golden parity in spring.test.ts.
+//
+// Unit/sign convention (REQ-SPRING-008): time `t` is ms; the undamped angular frequency ω0 is per-ms
+// (rad/ms); internal velocity is px/ms. The public boundary is px/s. The solver seeds internal
+// v0 = −(seed.velocity_px_per_s / 1000) so the position's initial derivative x'(0) equals the true
+// incoming public velocity; returned velocity is internal px/ms × 1000. A sign flip here inverts the
+// first-bounce direction (a conformance failure), so it is asserted by the sign test.
+// REQ-SPRING-013 / REQ-API-005: the scalar spring/inertia generator is two-keyframe ([from, to]). More
+// than two keyframes is a dev-time error — fail loudly, never silently truncate.
+export function assertTwoKeyframes(keyframes) {
+    if (keyframes.length > 2) {
+        throw new Error(`Native Motion spring is scalar two-keyframe ([from, to]); got ${keyframes.length} keyframes.`);
+    }
+}
+// Rest thresholds (REQ-SPRING-003), pinned from motion source (springDefaults). The scale switches to
+// the granular values when the move is tiny (REQ-SPRING-011). Owned here — SPEC-SPRING tightens the
+// core seed constants.
+const REST_SPEED = { default: 2, granular: 0.01 };
+const REST_DELTA = { default: 0.5, granular: 0.005 };
+const GRANULAR_SCALE = 5;
+/**
+ * Build a spring `GeneratorFactory` from a target and resolved physics. The seed supplies the origin
+ * (`from`) and the incoming public velocity (`velocity`, px/s); transition-config resolution
+ * (findSpring / visualDuration / defaults) is a separate concern (SPEC-SPRING Milestone 2).
+ */
+// alloc-ok: lifecycle-edge — the factory resolves physics once per animate command; per-frame work
+// is sample() below, which mutates the reused record and allocates nothing.
+export function springGenerator(target, physics, settle) {
+    const { stiffness, damping, mass } = physics;
+    const omega0 = Math.sqrt(stiffness / mass) / 1000; // undamped angular freq, rad/ms
+    const z = damping / (2 * Math.sqrt(stiffness * mass)); // damping ratio; regime by strict <1/===1/>1
+    const settleDuration = settle?.settleDuration ?? null;
+    // alloc-ok: lifecycle-edge — generator construction at command/interruption time; the closed
+    // forms and the one reused sample record are built here, never per frame.
+    return (seed) => {
+        const origin = seed.from;
+        const delta = target - origin; // initialDelta
+        const v0 = -(seed.velocity / 1000); // internal initial velocity, px/ms (REQ-SPRING-008)
+        // Rest thresholds by move scale (REQ-SPRING-011); per-context overrides win over the scale default.
+        const granular = Math.abs(delta) < GRANULAR_SCALE;
+        // Pinned zero-as-absent (r15 c6e31fd509a8): Motion 12.42.2 reads these thresholds falsy —
+        // an explicit 0 falls back to the scale defaults, never an unbounded active spring.
+        const restSpeed = settle?.restSpeed || (granular ? REST_SPEED.granular : REST_SPEED.default);
+        const restDelta = settle?.restDelta || (granular ? REST_DELTA.granular : REST_DELTA.default);
+        // Regime-specific closed forms. value(t) → px; velocityPerMs(t) → px/ms (= x'(t)).
+        // Each is a NAMED function (frame-path manifest anonymous-sampler repair): the qualified
+        // symbols are springGenerator.factory.<regime>Value/<regime>Velocity.
+        let value;
+        let velocityPerMs;
+        if (z < 1) {
+            // Underdamped (REQ-SPRING-002).
+            const wd = omega0 * Math.sqrt(1 - z * z); // damped angular freq
+            const a = (v0 + z * omega0 * delta) / wd;
+            const sinCoeff = z * omega0 * a + delta * wd;
+            const cosCoeff = z * omega0 * delta - a * wd;
+            function underdampedValue(t) {
+                const env = Math.exp(-z * omega0 * t);
+                return target - env * (a * Math.sin(wd * t) + delta * Math.cos(wd * t));
+            }
+            function underdampedVelocity(t) {
+                const env = Math.exp(-z * omega0 * t);
+                return env * (sinCoeff * Math.sin(wd * t) + cosCoeff * Math.cos(wd * t));
+            }
+            value = underdampedValue;
+            velocityPerMs = underdampedVelocity;
+        }
+        else if (z === 1) {
+            // Critically damped (REQ-SPRING-002).
+            const c = v0 + omega0 * delta;
+            function criticalValue(t) {
+                return target - Math.exp(-omega0 * t) * (delta + c * t);
+            }
+            function criticalVelocity(t) {
+                return Math.exp(-omega0 * t) * (omega0 * c * t - v0);
+            }
+            value = criticalValue;
+            velocityPerMs = criticalVelocity;
+        }
+        else {
+            // Overdamped — pure-exponential form (REQ-SPRING-010). Both λ < 0 → no overflow, no sinh/cosh
+            // cap; the capped form (Motion #1207) is never used. λslow uses −ω0/(z+√(z²−1)) to avoid
+            // catastrophic cancellation at large z.
+            const root = Math.sqrt(z * z - 1);
+            const wd = omega0 * root;
+            const lambdaSlow = -omega0 / (z + root);
+            const lambdaFast = -omega0 * (z + root);
+            const cSlow = (v0 + z * omega0 * delta + wd * delta) / (2 * wd);
+            const cFast = delta - cSlow;
+            function overdampedValue(t) {
+                return target - (cSlow * Math.exp(lambdaSlow * t) + cFast * Math.exp(lambdaFast * t));
+            }
+            function overdampedVelocity(t) {
+                return -(cSlow * lambdaSlow * Math.exp(lambdaSlow * t) +
+                    cFast * lambdaFast * Math.exp(lambdaFast * t));
+            }
+            value = overdampedValue;
+            velocityPerMs = overdampedVelocity;
+        }
+        // One sample record per generator, mutated and returned every call — motion's own generators
+        // return their reused `state` the same way. Per-frame sampling must not allocate
+        // (REQ-DRIVER-015); callers read the scalars immediately and never retain the record.
+        const out = { value: seed.from, velocity: seed.velocity, done: false };
+        return {
+            sample(elapsedMs) {
+                const current = value(elapsedMs);
+                const velocity = velocityPerMs(elapsedMs) * 1000; // → px/s (REQ-SPRING-008)
+                // Settle (REQ-SPRING-011): findSpring (duration) springs finish deterministically at
+                // t ≥ settleDuration; physics + visualDuration springs rest by speed AND delta. On done, snap to
+                // target (matches motion's next()), so an interruption re-seeds from an exact endpoint.
+                const done = settleDuration !== null
+                    ? elapsedMs >= settleDuration
+                    : Math.abs(velocity) <= restSpeed && Math.abs(target - current) <= restDelta;
+                out.value = done ? target : current;
+                out.velocity = velocity;
+                out.done = done;
+                return out;
+            },
+        };
+    };
+}

package/dist/worklet-layout/timing.js

@@ -0,0 +1,201 @@
+'worklet';
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// Duration+ease timing (tween) generator (SPEC-SPRING REQ-TIMING-001/002). value = mix(origin, target,
+// ease(clamp(0,1,t/duration))); velocity is a 5ms finite difference of that curve; done at t ≥ duration;
+// incoming velocity is ignored. Host-agnostic (REQ-CORE-003): the cubic-bezier evaluator is an exact
+// port of motion-utils' Gaëtan Renaudeau BezierEasing (binary subdivision), NOT imported. Numerics are
+// pinned to motion@12.42.2 and proven by golden parity in timing.test.ts.
+//
+// Worklet safety (hytd3r / Remote Function crash class): NEVER store named-easing evaluators as
+// module-init function values. reverseEasing/mirrorEasing wrappers and cubicBezier returns built at
+// load time lacked __workletHash and crashed when UI-runtime call sites invoked them. All named and
+// cubic evaluation is pure math over number tables; resolveEasing returns thin closures that capture
+// only serializable primitives (name string or control points).
+// Runtime-readable named set (validate / keyframeTiming / shippedSurface share this authority).
+export const NAMED_EASING_KEYS = [
+    'linear',
+    'easeIn',
+    'easeOut',
+    'easeInOut',
+    'circIn',
+    'circOut',
+    'circInOut',
+    'backIn',
+    'backOut',
+    'backInOut',
+    'anticipate',
+];
+const DEFAULT_DURATION_MS = 300; // REQ-TIMING-002 (0.3s)
+const DEFAULT_EASE = [0.25, 0.1, 0.35, 1]; // REQ-TIMING-002
+const VELOCITY_SAMPLE_MS = 5;
+// Named cubic-bezier control points (motion-utils/easing/ease + back). Data only — no function values.
+const EASE_IN = [0.42, 0, 1, 1];
+const EASE_OUT = [0, 0, 0.58, 1];
+const EASE_IN_OUT = [0.42, 0, 0.58, 1];
+// motion-utils/easing/back.ts: backOut = cubicBezier(0.33, 1.53, 0.69, 0.99)
+const BACK_OUT = [0.33, 1.53, 0.69, 0.99];
+const clamp01 = (v) => Math.max(0, Math.min(1, v));
+const mix = (from, to, p) => from + (to - from) * p;
+const SUBDIVISION_PRECISION = 1e-7;
+const SUBDIVISION_MAX_ITERATIONS = 12;
+// x(t)/y(t) of the bezier given a single control-point pair (exact port of motion-utils calcBezier).
+const calcBezier = (t, a1, a2) => ((1 - 3 * a2 + 3 * a1) * t + (3 * a2 - 6 * a1)) * t * t + 3 * a1 * t;
+/** Pure cubic-bezier sample — no nested function allocation at module init (hytd3r). */
+function evaluateCubic(x1, y1, x2, y2, t) {
+    if (t === 0 || t === 1)
+        return t;
+    // Linear gradient is the identity; also avoids a degenerate subdivision.
+    if (x1 === y1 && x2 === y2)
+        return t;
+    let lower = 0;
+    let upper = 1;
+    let currentT = 0;
+    let currentX = 0;
+    let i = 0;
+    do {
+        currentT = lower + (upper - lower) / 2;
+        currentX = calcBezier(currentT, x1, x2) - t;
+        if (currentX > 0)
+            upper = currentT;
+        else
+            lower = currentT;
+    } while (Math.abs(currentX) > SUBDIVISION_PRECISION && ++i < SUBDIVISION_MAX_ITERATIONS);
+    return calcBezier(currentT, y1, y2);
+}
+// motion-utils/easing/circ.ts — pure forms of reverse/mirror so no function-valued table.
+function evaluateCircIn(p) {
+    return 1 - Math.sin(Math.acos(clamp01(p)));
+}
+function evaluateCircOut(p) {
+    // reverse(circIn): 1 - circIn(1 - p)
+    return 1 - evaluateCircIn(1 - p);
+}
+function evaluateCircInOut(p) {
+    // mirror(circIn)
+    return p <= 0.5 ? evaluateCircIn(2 * p) / 2 : (2 - evaluateCircIn(2 * (1 - p))) / 2;
+}
+function evaluateBackOut(p) {
+    return evaluateCubic(BACK_OUT[0], BACK_OUT[1], BACK_OUT[2], BACK_OUT[3], p);
+}
+function evaluateBackIn(p) {
+    // reverse(backOut)
+    return 1 - evaluateBackOut(1 - p);
+}
+function evaluateBackInOut(p) {
+    // mirror(backIn)
+    return p <= 0.5 ? evaluateBackIn(2 * p) / 2 : (2 - evaluateBackIn(2 * (1 - p))) / 2;
+}
+// motion-utils/easing/anticipate.ts
+function evaluateAnticipate(p) {
+    if (p >= 1)
+        return 1;
+    const doubled = p * 2;
+    return doubled < 1 ? 0.5 * evaluateBackIn(doubled) : 0.5 * (2 - Math.pow(2, -10 * (doubled - 1)));
+}
+const NAMED_EASING_SET = new Set(NAMED_EASING_KEYS);
+function isNamedEasing(value) {
+    return NAMED_EASING_SET.has(value);
+}
+/** Pure named-easing sample — captures no function values (hytd3r Remote Function law). */
+function evaluateNamedEasing(name, p) {
+    switch (name) {
+        case 'linear':
+            return p;
+        case 'easeIn':
+            return evaluateCubic(EASE_IN[0], EASE_IN[1], EASE_IN[2], EASE_IN[3], p);
+        case 'easeOut':
+            return evaluateCubic(EASE_OUT[0], EASE_OUT[1], EASE_OUT[2], EASE_OUT[3], p);
+        case 'easeInOut':
+            return evaluateCubic(EASE_IN_OUT[0], EASE_IN_OUT[1], EASE_IN_OUT[2], EASE_IN_OUT[3], p);
+        case 'circIn':
+            return evaluateCircIn(p);
+        case 'circOut':
+            return evaluateCircOut(p);
+        case 'circInOut':
+            return evaluateCircInOut(p);
+        case 'backIn':
+            return evaluateBackIn(p);
+        case 'backOut':
+            return evaluateBackOut(p);
+        case 'backInOut':
+            return evaluateBackInOut(p);
+        case 'anticipate':
+            return evaluateAnticipate(p);
+        default: {
+            // Exhaustiveness + runtime cast guard (9a4arp): never sample NaN for an unknown name.
+            const _exhaustive = name;
+            throw new Error(`unknown named easing '${String(_exhaustive)}'`);
+        }
+    }
+}
+// alloc-ok: lifecycle-edge — easing resolution at factory time. Exported for the multi-keyframe
+// generator (keyframes.ts, REQ-API-033), which resolves ONE easing per segment through this same
+// exact BezierEasing / Motion-named port — never a second easing vocabulary.
+// Closures capture only primitives (name string or four numbers) so worklet serialization never
+// embeds a JS-thread Remote Function (hytd3r).
+// Fail-closed (9a4arp): unknown named strings throw before any sample can emit NaN. The public
+// validateTransition boundary also refuses them; this is the generator-seam backstop for direct
+// timingGenerator / resolveEasing callers.
+export function resolveEasing(ease) {
+    if (typeof ease === 'string') {
+        if (!isNamedEasing(ease)) {
+            throw new Error(`unknown named easing '${ease}' — expected one of ${NAMED_EASING_KEYS.join(', ')} ` +
+                '(REQ-TIMING-001 / REQ-API-033)');
+        }
+        const name = ease;
+        // Named returned closures (frame-path manifest anonymous-sampler repair): the qualified
+        // symbols are resolveEasing.namedEvaluator / resolveEasing.cubicEvaluator.
+        return function namedEvaluator(p) {
+            return evaluateNamedEasing(name, p);
+        };
+    }
+    const x1 = ease[0];
+    const y1 = ease[1];
+    const x2 = ease[2];
+    const y2 = ease[3];
+    return function cubicEvaluator(p) {
+        return evaluateCubic(x1, y1, x2, y2, p);
+    };
+}
+// Disambiguate a PER-SEGMENT easing list (`['easeIn', 'easeOut']`, `[[…],[…]]`) from a SINGLE
+// cubic-bezier easing (`[0.25, 0.1, 0.35, 1]`) — both are arrays. A per-segment list's elements are
+// themselves easings (a named string or a nested bezier array); a single CubicBezier's elements are
+// plain numbers. Mirrors motion-dom's `isEasingArray`. Without this, a single-bezier `ease` on a
+// keyframe array would be mis-read element-by-element as per-segment (REQ-API-033).
+export function isEasingList(ease) {
+    return Array.isArray(ease) && typeof ease[0] !== 'number';
+}
+/**
+ * Build a tween `GeneratorFactory` (REQ-API-004). `seed.from` is the origin; the seed's incoming
+ * velocity is intentionally ignored (REQ-TIMING-001). The tween finishes deterministically at
+ * `t ≥ duration`.
+ */
+// alloc-ok: lifecycle-edge — the factory resolves duration/ease once per animate command;
+// per-frame work is sample() below, which mutates the reused record and allocates nothing.
+export function timingGenerator(target, config) {
+    const duration = config?.duration ?? DEFAULT_DURATION_MS;
+    const ease = resolveEasing(config?.ease ?? DEFAULT_EASE);
+    // alloc-ok: lifecycle-edge — generator construction at command time; the one reused sample
+    // record is built here, never per frame.
+    return (seed) => {
+        const origin = seed.from;
+        const value = (t) => mix(origin, target, ease(clamp01(t / duration)));
+        // One sample record per generator, mutated and returned every call — motion's own generators
+        // return their reused `state` the same way. Per-frame sampling must not allocate
+        // (REQ-DRIVER-015); callers read the scalars immediately and never retain the record.
+        const out = { value: origin, velocity: 0, done: false };
+        return {
+            sample(elapsedMs) {
+                const current = value(elapsedMs);
+                const prevT = Math.max(elapsedMs - VELOCITY_SAMPLE_MS, 0);
+                const dt = elapsedMs - prevT;
+                const velocity = dt ? ((current - value(prevT)) / dt) * 1000 : 0; // px/s (REQ-TIMING-001)
+                const done = elapsedMs >= duration;
+                out.value = done ? target : current;
+                out.velocity = velocity;
+                out.done = done;
+                return out;
+            },
+        };
+    };
+}

package/dist/worklet-layout/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/worklet-layout.cjs

@@ -0,0 +1,47 @@
+"use strict";
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// UI-runtime layout entry — the source of truth for the `./worklet-layout` subpath export.
+// Re-exports exactly the layout-identity crossing chain a UI worklet may execute (registry/session +
+// the spring/projection callees they reach) plus the types callers need to hold them. Building this
+// from src (zshy emits dist/worklet-layout.{js,d.ts}; `tsgo -b` emits the same on a bare checkout)
+// keeps the subpath resolvable without a prior package build — the review-found false green where
+// only a previously-built dist made `nub run check` pass.
+//
+// This file stays pragma-free (core src never carries 'worklet' — the isolation gate's law); the
+// worklet tagging is post-build only: scripts/tag-worklet-dist.mjs redirects the emitted barrel at
+// FILE-level-tagged copies under dist/worklet-layout/. JS-thread callers keep importing the package
+// root, whose dist stays function-tagged for the dual-use modules.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLayoutIdentityRegistry = exports.createProjectionSession = exports.createProjectionTree = exports.isIdentity = exports.applyTransformToRect = exports.projectAtProgress = exports.invert = exports.IDENTITY_TRANSFORM = exports.MAX_VELOCITY_DELTA_MS = exports.DT_CLAMP_MS = exports.EPSILON_VEL = exports.EPSILON_SCALE = exports.EPSILON_POS = exports.toWindowSpaceRect = exports.retargetSpring = exports.resolveSpringGenerator = exports.resolveSpring = void 0;
+var transition_1 = require("./transition.cjs");
+Object.defineProperty(exports, "resolveSpring", { enumerable: true, get: function () { return transition_1.resolveSpring; } });
+Object.defineProperty(exports, "resolveSpringGenerator", { enumerable: true, get: function () { return transition_1.resolveSpringGenerator; } });
+Object.defineProperty(exports, "retargetSpring", { enumerable: true, get: function () { return transition_1.retargetSpring; } });
+var types_1 = require("./layout/types.cjs");
+Object.defineProperty(exports, "toWindowSpaceRect", { enumerable: true, get: function () { return types_1.toWindowSpaceRect; } });
+// accountForLayoutScroll (REQ-LAYOUT-022) is package-root only this rung: the layoutScroll
+// measure correction runs on the JS measure-commit path, not inside the UI frame step.
+var constants_1 = require("./layout/constants.cjs");
+Object.defineProperty(exports, "EPSILON_POS", { enumerable: true, get: function () { return constants_1.EPSILON_POS; } });
+Object.defineProperty(exports, "EPSILON_SCALE", { enumerable: true, get: function () { return constants_1.EPSILON_SCALE; } });
+Object.defineProperty(exports, "EPSILON_VEL", { enumerable: true, get: function () { return constants_1.EPSILON_VEL; } });
+// REQ-CLOCK-003: the UI-runtime graph adapter clamps per-frame elapsed with CORE's number, not a
+// fork — a background/long-frame gap must not jump a layout flight forward unbounded.
+var constants_2 = require("./config/constants.cjs");
+Object.defineProperty(exports, "DT_CLAMP_MS", { enumerable: true, get: function () { return constants_2.DT_CLAMP_MS; } });
+Object.defineProperty(exports, "MAX_VELOCITY_DELTA_MS", { enumerable: true, get: function () { return constants_2.MAX_VELOCITY_DELTA_MS; } });
+var projection_1 = require("./layout/projection.cjs");
+Object.defineProperty(exports, "IDENTITY_TRANSFORM", { enumerable: true, get: function () { return projection_1.IDENTITY_TRANSFORM; } });
+Object.defineProperty(exports, "invert", { enumerable: true, get: function () { return projection_1.invert; } });
+Object.defineProperty(exports, "projectAtProgress", { enumerable: true, get: function () { return projection_1.projectAtProgress; } });
+Object.defineProperty(exports, "applyTransformToRect", { enumerable: true, get: function () { return projection_1.applyTransformToRect; } });
+Object.defineProperty(exports, "isIdentity", { enumerable: true, get: function () { return projection_1.isIdentity; } });
+// M3.5 component projection tree. This stays on the worklet-only layout surface: native owns
+// UI-runtime records and calls the pure tree during its existing frame callback; the public core
+// root exports the same host-agnostic types for deterministic unit coverage.
+var tree_1 = require("./layout/tree.cjs");
+Object.defineProperty(exports, "createProjectionTree", { enumerable: true, get: function () { return tree_1.createProjectionTree; } });
+var session_1 = require("./layout/session.cjs");
+Object.defineProperty(exports, "createProjectionSession", { enumerable: true, get: function () { return session_1.createProjectionSession; } });
+var identity_1 = require("./layout/identity.cjs");
+Object.defineProperty(exports, "createLayoutIdentityRegistry", { enumerable: true, get: function () { return identity_1.createLayoutIdentityRegistry; } });

package/dist/worklet-layout.d.cts

@@ -0,0 +1,15 @@
+export type { ActivityHandle, Animation, Generator, GeneratorFactory, MotionGraph, MotionValue, MotionValueEvent, ValueChangeListener, } from "./types.cjs";
+export { resolveSpring, resolveSpringGenerator, retargetSpring } from "./transition.cjs";
+export type { SpringConfig, ResolvedSpring } from "./transition.cjs";
+export type { TimingConfig, Easing, NamedEasing, CubicBezier } from "./timing.cjs";
+export { toWindowSpaceRect } from "./layout/types.cjs";
+export type { Rect, Transform, LayoutIdToken, WindowSpaceRect } from "./layout/types.cjs";
+export { EPSILON_POS, EPSILON_SCALE, EPSILON_VEL } from "./layout/constants.cjs";
+export { DT_CLAMP_MS, MAX_VELOCITY_DELTA_MS } from "./config/constants.cjs";
+export { IDENTITY_TRANSFORM, invert, projectAtProgress, applyTransformToRect, isIdentity, } from "./layout/projection.cjs";
+export { createProjectionTree } from "./layout/tree.cjs";
+export type { ProjectionNodeOutput, ProjectionStaleNodeCode, ProjectionStaleNodeReport, ProjectionTree, ProjectionTreeNode, ProjectionTreeOptions, } from "./layout/tree.cjs";
+export { createProjectionSession } from "./layout/session.cjs";
+export type { MutableRect, ProjectionSession, ProjectionSessionOptions, ProjectionSessionState, RectVelocity, } from "./layout/session.cjs";
+export { createLayoutIdentityRegistry } from "./layout/identity.cjs";
+export type { IdentityEnterResult, IdentityHolderHandle, IdentityHolderWrite, IdentityRead, LayoutIdentityFlightOptions, LayoutIdentityRegistry, LayoutIdentityRegistryOptions, LayoutIdentityRole, } from "./layout/identity.cjs";