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

package/dist/index.cjs

@@ -0,0 +1,140 @@
+"use strict";
+// Public surface of @unrulysystems/native-motion-core — the host-agnostic motion graph (SPEC-CORE).
+// Zero host dependencies (REQ-CORE-003): nothing re-exported here reaches react-native / reanimated
+// / gesture-handler / motion / react.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.arc = exports.wrap = exports.motionMix = exports.delayGenerator = exports.MAX_ITERATION_DURATION_MS = exports.ITERATION_SCAN_STEP_MS = exports.repeatIterationRefusal = exports.repeatGenerator = exports.repeatFoldGeometry = exports.calcIterationDurationMs = exports.buildRepeatedGenerator = exports.keyframesGenerator = exports.NAMED_EASING_KEYS = exports.timingGenerator = exports.parseTransformTemplateOutput = exports.buildTransformTemplateArgs = exports.buildTransformString = exports.inertiaGenerator = exports.dragInertiaBounce = exports.DRAG_INERTIA_DEFAULTS = exports.springKeyframeCountRefusal = exports.getDefaultTransition = exports.retargetSpring = exports.resolveSpringGenerator = exports.resolveSpring = exports.assertTwoKeyframes = exports.springGenerator = exports.constants = exports.collectMotionValueReads = exports.ManualScheduler = exports.ManualClock = exports.createMotionGraph = exports.VERSION = void 0;
+exports.VERSION = '0.0.0';
+var graph_1 = require("./graph.cjs");
+Object.defineProperty(exports, "createMotionGraph", { enumerable: true, get: function () { return graph_1.createMotionGraph; } });
+var clock_1 = require("./clock.cjs");
+Object.defineProperty(exports, "ManualClock", { enumerable: true, get: function () { return clock_1.ManualClock; } });
+Object.defineProperty(exports, "ManualScheduler", { enumerable: true, get: function () { return clock_1.ManualScheduler; } });
+// Reactive-derived dependency collection (REQ-API-027's `useTransform(() => expr)` form): records
+// the MotionValues actually read by a compute. Additive; reads outside a collection are untouched.
+var collect_reads_1 = require("./collect-reads.cjs");
+Object.defineProperty(exports, "collectMotionValueReads", { enumerable: true, get: function () { return collect_reads_1.collectMotionValueReads; } });
+exports.constants = __importStar(require("./config/constants.cjs"));
+// SPEC-SPRING animation-value engine (analytic solver; resolvers/timing/interruption land here too).
+var spring_1 = require("./spring.cjs");
+Object.defineProperty(exports, "springGenerator", { enumerable: true, get: function () { return spring_1.springGenerator; } });
+Object.defineProperty(exports, "assertTwoKeyframes", { enumerable: true, get: function () { return spring_1.assertTwoKeyframes; } });
+// SPEC-SPRING config resolution (REQ-SPRING-004/005/006/007/012) + interruption seam (REQ-SPRING-009).
+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; } });
+Object.defineProperty(exports, "getDefaultTransition", { enumerable: true, get: function () { return transition_1.getDefaultTransition; } });
+Object.defineProperty(exports, "springKeyframeCountRefusal", { enumerable: true, get: function () { return transition_1.springKeyframeCountRefusal; } });
+Object.defineProperty(exports, "DRAG_INERTIA_DEFAULTS", { enumerable: true, get: function () { return transition_1.DRAG_INERTIA_DEFAULTS; } });
+Object.defineProperty(exports, "dragInertiaBounce", { enumerable: true, get: function () { return transition_1.dragInertiaBounce; } });
+// SPEC-GESTURE two-phase inertia generator (REQ-GESTURE-016/-023/-027, R16 — the gesture
+// free-drag release curve; golden-pinned to motion-dom@12.42.2 `inertia()`).
+var inertia_1 = require("./inertia.cjs");
+Object.defineProperty(exports, "inertiaGenerator", { enumerable: true, get: function () { return inertia_1.inertiaGenerator; } });
+// T17 bounded transform-template support (the canonical generated-string builder + the bounded
+// template-output parser; specs/T17-TRANSFORM-TEMPLATE-BUILD-PACKET.md).
+var transformTemplate_1 = require("./transformTemplate.cjs");
+Object.defineProperty(exports, "buildTransformString", { enumerable: true, get: function () { return transformTemplate_1.buildTransformString; } });
+Object.defineProperty(exports, "buildTransformTemplateArgs", { enumerable: true, get: function () { return transformTemplate_1.buildTransformTemplateArgs; } });
+Object.defineProperty(exports, "parseTransformTemplateOutput", { enumerable: true, get: function () { return transformTemplate_1.parseTransformTemplateOutput; } });
+// SPEC-SPRING duration+ease timing generator (REQ-TIMING-001/002).
+var timing_1 = require("./timing.cjs");
+Object.defineProperty(exports, "timingGenerator", { enumerable: true, get: function () { return timing_1.timingGenerator; } });
+Object.defineProperty(exports, "NAMED_EASING_KEYS", { enumerable: true, get: function () { return timing_1.NAMED_EASING_KEYS; } });
+// SPEC-COMPONENT multi-keyframe timing generator (REQ-API-033, R8 — array targets).
+var keyframes_1 = require("./keyframes.cjs");
+Object.defineProperty(exports, "keyframesGenerator", { enumerable: true, get: function () { return keyframes_1.keyframesGenerator; } });
+// T18-a repeat elapsed-time fold (REQ-TIMING-003): the pure `t → t'` map that wraps ANY generator
+// to implement repeat/repeatType/repeatDelay, so no generator learns about repetition.
+var repeat_1 = require("./repeat.cjs");
+Object.defineProperty(exports, "buildRepeatedGenerator", { enumerable: true, get: function () { return repeat_1.buildRepeatedGenerator; } });
+Object.defineProperty(exports, "calcIterationDurationMs", { enumerable: true, get: function () { return repeat_1.calcIterationDurationMs; } });
+Object.defineProperty(exports, "repeatFoldGeometry", { enumerable: true, get: function () { return repeat_1.repeatFoldGeometry; } });
+Object.defineProperty(exports, "repeatGenerator", { enumerable: true, get: function () { return repeat_1.repeatGenerator; } });
+Object.defineProperty(exports, "repeatIterationRefusal", { enumerable: true, get: function () { return repeat_1.repeatIterationRefusal; } });
+Object.defineProperty(exports, "ITERATION_SCAN_STEP_MS", { enumerable: true, get: function () { return repeat_1.ITERATION_SCAN_STEP_MS; } });
+Object.defineProperty(exports, "MAX_ITERATION_DURATION_MS", { enumerable: true, get: function () { return repeat_1.MAX_ITERATION_DURATION_MS; } });
+// T18-b delay elapsed-time rebase (REQ-TIMING-004): the pure `t → t − delay` shift that wraps ANY
+// generator or fold to implement transition.delay, so no generator learns about delay.
+var delay_1 = require("./delay.cjs");
+Object.defineProperty(exports, "delayGenerator", { enumerable: true, get: function () { return delay_1.delayGenerator; } });
+// U7a: the authored `{ type: false }` instant lane (the pin's makeAnimationInstant) — no
+// trajectory generator; the final keyframe commits on the driver's next update tick, delay
+// honored. Backend machinery: exported through the internal-driver subpath, never the root.
+// SPEC-VALUE-TYPES typed value parsers + gamma-aware mixers (REQ-VALUETYPE-*): the unified mix() seam
+// SPRING's scalar progress feeds, for numbers/units/colors/complex strings. Host-agnostic
+// (REQ-VALUETYPE-011). Additive — no existing core / SPRING / M1a / M1b API changed.
+__exportStar(require("./value-types/index.cjs"), exports);
+// T23 A: the public Motion `mix` utility (pin motion-dom/utils/mix), executing through the value
+// seam above. The product entries alias it to `mix`; the core-root `mix` name stays the typed seam.
+var motion_mix_1 = require("./motion-mix.cjs");
+Object.defineProperty(exports, "motionMix", { enumerable: true, get: function () { return motion_mix_1.motionMix; } });
+// T24 W: the public Motion `wrap` utility (pin motion-utils/wrap, public via the dom barrel).
+var wrap_1 = require("./wrap.cjs");
+Object.defineProperty(exports, "wrap", { enumerable: true, get: function () { return wrap_1.wrap; } });
+// U8 (REQ-API-059): public `arc()` factory. The UI sampler and brand predicate ride
+// internal-driver (worklet + controller), never the consumer root.
+var motion_arc_1 = require("./motion-arc.cjs");
+Object.defineProperty(exports, "arc", { enumerable: true, get: function () { return motion_arc_1.arc; } });
+// SPEC-UNIVERSAL-SUBSET frozen registry (REQ-SUBSET-010): the single source of truth for which
+// properties/gestures are guaranteed identical across engines, their web-engine path, and their native
+// mapping. Host-agnostic; the Motion-seam canary + authoring gate read it from conformance. Additive.
+__exportStar(require("./subset/index.cjs"), exports);
+// SPEC-COMPONENT declarative API contract (REQ-API-006/015): the end-state public Target/Transition/prop
+// types (Milestone 1); validateTarget + resolveTarget join here as they land. Host-agnostic. Additive.
+__exportStar(require("./component/index.cjs"), exports);
+// SPEC-NATIVE-DRIVER host-agnostic Driver seam (REQ-DRIVER-010): the interface `core` defines and the
+// native worklet / web drivers implement (the pure step + reference driver join as they land). Additive.
+__exportStar(require("./driver/index.cjs"), exports);
+// SPEC-PRESENCE host-agnostic exit-lifecycle controller (REQ-PRESENCE-001): the total present→exiting→removed
+// state machine + controller `core` defines; the React usePresence/useIsPresent hooks bind over it (M2).
+// Host-agnostic — no react/driver import. Additive.
+__exportStar(require("./presence/index.cjs"), exports);
+// SPEC-GESTURE host-agnostic gesture session (REQ-GESTURE-001): the pure gesture math + the begin→active→
+// end/cancel session that drives a motion value from a recognizer sample stream and hands off the platform
+// release velocity (§G) into a settling spring. The Gesture-Handler / motion-react bindings bind over it
+// (M2). Host-agnostic — no react/Gesture-Handler/driver import. Additive.
+__exportStar(require("./gesture/index.cjs"), exports);
+// SPEC-LAYOUT host-agnostic projection engine (REQ-LAYOUT-001): the pure FLIP projection math + (as they
+// land) parent-relative compose, measurement lifecycle, and the projection session that drives the visual
+// delta to zero through a progress spring so an element lands on its host-computed layout. The Fabric
+// measure adapter feeds common-space rects to layout identity (M2); this never imports a host
+// measure API. Additive.
+__exportStar(require("./layout/index.cjs"), exports);

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+export declare const VERSION = "0.0.0";
+export type { ActivityHandle, Animation, Clock, Generator, GeneratorFactory, GeneratorSample, GeneratorSeed, MotionGraph, MotionGraphOptions, DerivedMotionValue, DerivedSource, DerivedSourceValues, MotionValue, MotionValueEvent, Scheduler, ValueChangeListener, } from "./types.cjs";
+export { createMotionGraph } from "./graph.cjs";
+export { ManualClock, ManualScheduler } from "./clock.cjs";
+export { collectMotionValueReads } from "./collect-reads.cjs";
+export type { CollectedReads } from "./collect-reads.cjs";
+export * as constants from "./config/constants.cjs";
+export { springGenerator, assertTwoKeyframes } from "./spring.cjs";
+export type { SpringPhysics, SpringSettleOptions } from "./spring.cjs";
+export { resolveSpring, resolveSpringGenerator, retargetSpring, getDefaultTransition, springKeyframeCountRefusal, DRAG_INERTIA_DEFAULTS, dragInertiaBounce, } from "./transition.cjs";
+export type { SpringConfig, ResolvedSpring, DefaultTransition, InertiaTransition, } from "./transition.cjs";
+export { inertiaGenerator } from "./inertia.cjs";
+export type { InertiaPhysics } from "./inertia.cjs";
+export { buildTransformString, buildTransformTemplateArgs, parseTransformTemplateOutput, } from "./transformTemplate.cjs";
+export type { TransformEntry, TransformProperties, TransformPropertyKey, TransformTemplate, TransformTemplateArgs, TransformTemplateValues, } from "./transformTemplate.cjs";
+export { timingGenerator, NAMED_EASING_KEYS } from "./timing.cjs";
+export type { TimingConfig, Easing, CubicBezier, NamedEasing } from "./timing.cjs";
+export { keyframesGenerator } from "./keyframes.cjs";
+export type { KeyframesConfig } from "./keyframes.cjs";
+export { buildRepeatedGenerator, calcIterationDurationMs, repeatFoldGeometry, repeatGenerator, repeatIterationRefusal, ITERATION_SCAN_STEP_MS, MAX_ITERATION_DURATION_MS, } from "./repeat.cjs";
+export type { RepeatFoldConfig, RepeatFoldGeometry, RepeatLeg, RepeatType } from "./repeat.cjs";
+export { delayGenerator } from "./delay.cjs";
+export * from "./value-types/index.cjs";
+export { type MotionMixer, motionMix } from "./motion-mix.cjs";
+export { wrap } from "./wrap.cjs";
+export { arc } from "./motion-arc.cjs";
+export type { ArcOptions } from "./motion-arc.cjs";
+export * from "./subset/index.cjs";
+export * from "./component/index.cjs";
+export * from "./driver/index.cjs";
+export * from "./presence/index.cjs";
+export * from "./gesture/index.cjs";
+export * from "./layout/index.cjs";

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+export declare const VERSION = "0.0.0";
+export type { ActivityHandle, Animation, Clock, Generator, GeneratorFactory, GeneratorSample, GeneratorSeed, MotionGraph, MotionGraphOptions, DerivedMotionValue, DerivedSource, DerivedSourceValues, MotionValue, MotionValueEvent, Scheduler, ValueChangeListener, } from "./types.js";
+export { createMotionGraph } from "./graph.js";
+export { ManualClock, ManualScheduler } from "./clock.js";
+export { collectMotionValueReads } from "./collect-reads.js";
+export type { CollectedReads } from "./collect-reads.js";
+export * as constants from "./config/constants.js";
+export { springGenerator, assertTwoKeyframes } from "./spring.js";
+export type { SpringPhysics, SpringSettleOptions } from "./spring.js";
+export { resolveSpring, resolveSpringGenerator, retargetSpring, getDefaultTransition, springKeyframeCountRefusal, DRAG_INERTIA_DEFAULTS, dragInertiaBounce, } from "./transition.js";
+export type { SpringConfig, ResolvedSpring, DefaultTransition, InertiaTransition, } from "./transition.js";
+export { inertiaGenerator } from "./inertia.js";
+export type { InertiaPhysics } from "./inertia.js";
+export { buildTransformString, buildTransformTemplateArgs, parseTransformTemplateOutput, } from "./transformTemplate.js";
+export type { TransformEntry, TransformProperties, TransformPropertyKey, TransformTemplate, TransformTemplateArgs, TransformTemplateValues, } from "./transformTemplate.js";
+export { timingGenerator, NAMED_EASING_KEYS } from "./timing.js";
+export type { TimingConfig, Easing, CubicBezier, NamedEasing } from "./timing.js";
+export { keyframesGenerator } from "./keyframes.js";
+export type { KeyframesConfig } from "./keyframes.js";
+export { buildRepeatedGenerator, calcIterationDurationMs, repeatFoldGeometry, repeatGenerator, repeatIterationRefusal, ITERATION_SCAN_STEP_MS, MAX_ITERATION_DURATION_MS, } from "./repeat.js";
+export type { RepeatFoldConfig, RepeatFoldGeometry, RepeatLeg, RepeatType } from "./repeat.js";
+export { delayGenerator } from "./delay.js";
+export * from "./value-types/index.js";
+export { type MotionMixer, motionMix } from "./motion-mix.js";
+export { wrap } from "./wrap.js";
+export { arc } from "./motion-arc.js";
+export type { ArcOptions } from "./motion-arc.js";
+export * from "./subset/index.js";
+export * from "./component/index.js";
+export * from "./driver/index.js";
+export * from "./presence/index.js";
+export * from "./gesture/index.js";
+export * from "./layout/index.js";

package/dist/index.js

@@ -0,0 +1,70 @@
+// Public surface of @unrulysystems/native-motion-core — the host-agnostic motion graph (SPEC-CORE).
+// Zero host dependencies (REQ-CORE-003): nothing re-exported here reaches react-native / reanimated
+// / gesture-handler / motion / react.
+export const VERSION = '0.0.0';
+export { createMotionGraph } from "./graph.js";
+export { ManualClock, ManualScheduler } from "./clock.js";
+// Reactive-derived dependency collection (REQ-API-027's `useTransform(() => expr)` form): records
+// the MotionValues actually read by a compute. Additive; reads outside a collection are untouched.
+export { collectMotionValueReads } from "./collect-reads.js";
+export * as constants from "./config/constants.js";
+// SPEC-SPRING animation-value engine (analytic solver; resolvers/timing/interruption land here too).
+export { springGenerator, assertTwoKeyframes } from "./spring.js";
+// SPEC-SPRING config resolution (REQ-SPRING-004/005/006/007/012) + interruption seam (REQ-SPRING-009).
+export { resolveSpring, resolveSpringGenerator, retargetSpring, getDefaultTransition, springKeyframeCountRefusal, DRAG_INERTIA_DEFAULTS, dragInertiaBounce, } from "./transition.js";
+// SPEC-GESTURE two-phase inertia generator (REQ-GESTURE-016/-023/-027, R16 — the gesture
+// free-drag release curve; golden-pinned to motion-dom@12.42.2 `inertia()`).
+export { inertiaGenerator } from "./inertia.js";
+// T17 bounded transform-template support (the canonical generated-string builder + the bounded
+// template-output parser; specs/T17-TRANSFORM-TEMPLATE-BUILD-PACKET.md).
+export { buildTransformString, buildTransformTemplateArgs, parseTransformTemplateOutput, } from "./transformTemplate.js";
+// SPEC-SPRING duration+ease timing generator (REQ-TIMING-001/002).
+export { timingGenerator, NAMED_EASING_KEYS } from "./timing.js";
+// SPEC-COMPONENT multi-keyframe timing generator (REQ-API-033, R8 — array targets).
+export { keyframesGenerator } from "./keyframes.js";
+// T18-a repeat elapsed-time fold (REQ-TIMING-003): the pure `t → t'` map that wraps ANY generator
+// to implement repeat/repeatType/repeatDelay, so no generator learns about repetition.
+export { buildRepeatedGenerator, calcIterationDurationMs, repeatFoldGeometry, repeatGenerator, repeatIterationRefusal, ITERATION_SCAN_STEP_MS, MAX_ITERATION_DURATION_MS, } from "./repeat.js";
+// T18-b delay elapsed-time rebase (REQ-TIMING-004): the pure `t → t − delay` shift that wraps ANY
+// generator or fold to implement transition.delay, so no generator learns about delay.
+export { delayGenerator } from "./delay.js";
+// U7a: the authored `{ type: false }` instant lane (the pin's makeAnimationInstant) — no
+// trajectory generator; the final keyframe commits on the driver's next update tick, delay
+// honored. Backend machinery: exported through the internal-driver subpath, never the root.
+// SPEC-VALUE-TYPES typed value parsers + gamma-aware mixers (REQ-VALUETYPE-*): the unified mix() seam
+// SPRING's scalar progress feeds, for numbers/units/colors/complex strings. Host-agnostic
+// (REQ-VALUETYPE-011). Additive — no existing core / SPRING / M1a / M1b API changed.
+export * from "./value-types/index.js";
+// T23 A: the public Motion `mix` utility (pin motion-dom/utils/mix), executing through the value
+// seam above. The product entries alias it to `mix`; the core-root `mix` name stays the typed seam.
+export { motionMix } from "./motion-mix.js";
+// T24 W: the public Motion `wrap` utility (pin motion-utils/wrap, public via the dom barrel).
+export { wrap } from "./wrap.js";
+// U8 (REQ-API-059): public `arc()` factory. The UI sampler and brand predicate ride
+// internal-driver (worklet + controller), never the consumer root.
+export { arc } from "./motion-arc.js";
+// SPEC-UNIVERSAL-SUBSET frozen registry (REQ-SUBSET-010): the single source of truth for which
+// properties/gestures are guaranteed identical across engines, their web-engine path, and their native
+// mapping. Host-agnostic; the Motion-seam canary + authoring gate read it from conformance. Additive.
+export * from "./subset/index.js";
+// SPEC-COMPONENT declarative API contract (REQ-API-006/015): the end-state public Target/Transition/prop
+// types (Milestone 1); validateTarget + resolveTarget join here as they land. Host-agnostic. Additive.
+export * from "./component/index.js";
+// SPEC-NATIVE-DRIVER host-agnostic Driver seam (REQ-DRIVER-010): the interface `core` defines and the
+// native worklet / web drivers implement (the pure step + reference driver join as they land). Additive.
+export * from "./driver/index.js";
+// SPEC-PRESENCE host-agnostic exit-lifecycle controller (REQ-PRESENCE-001): the total present→exiting→removed
+// state machine + controller `core` defines; the React usePresence/useIsPresent hooks bind over it (M2).
+// Host-agnostic — no react/driver import. Additive.
+export * from "./presence/index.js";
+// SPEC-GESTURE host-agnostic gesture session (REQ-GESTURE-001): the pure gesture math + the begin→active→
+// end/cancel session that drives a motion value from a recognizer sample stream and hands off the platform
+// release velocity (§G) into a settling spring. The Gesture-Handler / motion-react bindings bind over it
+// (M2). Host-agnostic — no react/Gesture-Handler/driver import. Additive.
+export * from "./gesture/index.js";
+// SPEC-LAYOUT host-agnostic projection engine (REQ-LAYOUT-001): the pure FLIP projection math + (as they
+// land) parent-relative compose, measurement lifecycle, and the projection session that drives the visual
+// delta to zero through a progress spring so an element lands on its host-computed layout. The Fabric
+// measure adapter feeds common-space rects to layout identity (M2); this never imports a host
+// measure API. Additive.
+export * from "./layout/index.js";

package/dist/inertia.cjs

@@ -0,0 +1,214 @@
+"use strict";
+// @frame-path — executes inside the UI-runtime frame step; allocation-gated (REQ-DRIVER-021).
+// Two-phase inertia generator (SPEC-GESTURE REQ-GESTURE-016/-023/-027, R16 packet): a pure
+// closed-form exponential-decay evaluator with a latched boundary spring, pinned verbatim to
+// motion-dom@12.42.2 `inertia()` under the drag-layer invocation
+// (VisualElementDragControls.startAnimation: timeConstant 750, power 0.8, restDelta 1,
+// restSpeed 10, elastic-conditional bounce pairs). Host-agnostic (REQ-CORE-003): imports nothing
+// from motion/react. Parity is proven by golden traces in inertia.test.ts.
+//
+// Pin semantics (motion-dom inertia.ts, replicated exactly):
+//   amplitude = power · velocity        (px — the time constant absorbs the unit)
+//   target    = origin + amplitude      (free-drag: no modifyTarget)
+//   value(t)  = target − amplitude·e^(−t/timeConstant)
+//   done      = |amplitude·e^(−t/timeConstant)| ≤ restDelta  (value snaps to target)
+// Every sample, if the value lies outside [min, max] — INCLUDING a snapped out-of-bounds target —
+// the generator permanently switches to a spring from that value toward the violated bound,
+// seeded with the decay velocity at the crossing instant (stiffness/damping = bounce params).
+// An out-of-bounds origin latches the boundary spring at t=0 (the past-bound release,
+// REQ-GESTURE-016). The decay's initial velocity is amplitude/timeConstant, NOT the seeded
+// velocity — this is the pin's curve, and the goldens hold it.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inertiaGenerator = inertiaGenerator;
+// spring.ts's rest-threshold constants (REQ-SPRING-003/-011), pinned to the same motion
+// springDefaults source: the under/critical latch used to defer to springGenerator for this
+// resolution, so the repair reproduces it verbatim — scale switch at |Δ| < 5, granular
+// 0.01/0.005, default 2/0.5, zero-as-absent (`||`, never `??`).
+const BOUNDARY_GRANULAR_SCALE = 5;
+const BOUNDARY_REST_SPEED = { default: 2, granular: 0.01 };
+const BOUNDARY_REST_DELTA = { default: 0.5, granular: 0.005 };
+/**
+ * Build an inertia `GeneratorFactory` from pinned physics. The seed supplies the origin (`from`)
+ * and the release velocity (`velocity`, px/s — dragMomentum=false hands 0, the pin's
+ * `velocity: dragMomentum ? v : 0`).
+ */
+// alloc-ok: lifecycle-edge — the factory binds physics once per animate command; per-frame work
+// is sample() below. The boundary spring's coefficients latch into one preallocated
+// BoundarySpringState (packet §6: no closure, sample record, generator object, or
+// springGenerator factory at the crossing); sample() itself allocates nothing.
+function inertiaGenerator(physics) {
+    const { power, timeConstant, bounceStiffness, bounceDamping, restDelta, restSpeed } = physics;
+    const min = physics.min;
+    const max = physics.max;
+    return (seed) => {
+        const amplitude = power * seed.velocity;
+        const target = seed.from + amplitude;
+        const decayDelta = (t) => -amplitude * Math.exp(-t / timeConstant);
+        const decayValue = (t) => target + decayDelta(t);
+        // Analytic decay velocity (px/s): d/dt[target − amplitude·e^(−t/tc)] = amplitude/tc·e^(−t/tc) px/ms.
+        const decayVelocity = (t) => (amplitude / timeConstant) * Math.exp(-t / timeConstant) * 1000;
+        const outOfBounds = (v) => {
+            if (min !== undefined && v < min)
+                return min;
+            if (max !== undefined && v > max)
+                return max;
+            return undefined;
+        };
+        // Boundary-spring latch (the pin's timeReachedBoundary + spring, created on first OOB sample).
+        let crossingT;
+        // One preallocated state per generator — reset at the latch, sampled in place per frame.
+        const boundaryState = {
+            bound: 0,
+            from: seed.from,
+            velocity: 0,
+            initialDelta: 0,
+            initialVelocity: 0,
+            restSpeed,
+            restDelta,
+            wd: 0,
+            a: 0,
+            sinCoeff: 0,
+            cosCoeff: 0,
+            c: 0,
+            sinhCoeff: 0,
+            coshCoeff: 0,
+        };
+        // The pin's overdamped branch with its sinh/cosh exponent cap (motion-dom spring.ts:340-374,
+        // the #1207 mechanism — `Math.min(dampedAngularFreq*t, 300)`). Cross-engine parity: the pin
+        // uses the capped form for EVERY overdamped boundary spring (bounceZ > 1), so this generator
+        // does the same — the capped form is the pin's own formula, fp behavior included. Selecting
+        // it only when the cap engages within one frame diverges for intermediate overdamped pairs
+        // (review r3 major 1: bounceStiffness 10000/damping 30000 caps at ~20ms; core's cap-free
+        // solver stays unsettled past 200ms where the pin settles at 70ms). Under/critically-damped
+        // pairs (bounceZ ≤ 1) stay on core's solver — the pin's own branches there are the same
+        // cap-free math (golden regime continuity).
+        const bounceOmega0 = Math.sqrt(bounceStiffness / 1) / 1000; // rad/ms (mass 1)
+        const bounceZ = bounceDamping / (2 * Math.sqrt(bounceStiffness * 1));
+        const bounceDampedFreq = bounceZ > 1 ? bounceOmega0 * Math.sqrt(bounceZ * bounceZ - 1) : 0;
+        // Write target/origin/velocity and the primitive coefficients for the latched regime —
+        // spring.ts's exact closed forms for under/critical (including its REQ-SPRING-011 scale
+        // thresholds and pinned zero-as-absent || fallback) and the pin's capped overdamped branch
+        // (raw physics thresholds, as at HEAD). Runs at the initial or mid-flight latch only.
+        function resetBoundarySpringState(bound, from, velocity, state) {
+            state.bound = bound;
+            state.from = from;
+            state.velocity = velocity;
+            const delta = bound - from; // px (pin: initialDelta = target − origin)
+            const v0 = -velocity / 1000; // px/ms (pin: −millisecondsToSeconds; spring.ts REQ-SPRING-008)
+            state.initialDelta = delta;
+            state.initialVelocity = v0;
+            if (bounceZ > 1) {
+                state.restSpeed = restSpeed;
+                state.restDelta = restDelta;
+                const P = (v0 + bounceZ * bounceOmega0 * delta) / bounceDampedFreq;
+                state.sinhCoeff = bounceZ * bounceOmega0 * P - delta * bounceDampedFreq;
+                state.coshCoeff = bounceZ * bounceOmega0 * delta - P * bounceDampedFreq;
+                return;
+            }
+            // Under/critical latch — springGenerator's exact threshold resolution (scale defaults,
+            // granular switch, zero-as-absent) for the same { restDelta, restSpeed } settle input.
+            const granular = Math.abs(delta) < BOUNDARY_GRANULAR_SCALE;
+            state.restSpeed =
+                restSpeed || (granular ? BOUNDARY_REST_SPEED.granular : BOUNDARY_REST_SPEED.default);
+            state.restDelta =
+                restDelta || (granular ? BOUNDARY_REST_DELTA.granular : BOUNDARY_REST_DELTA.default);
+            if (bounceZ < 1) {
+                const wd = bounceOmega0 * Math.sqrt(1 - bounceZ * bounceZ);
+                const a = (v0 + bounceZ * bounceOmega0 * delta) / wd;
+                state.wd = wd;
+                state.a = a;
+                state.sinCoeff = bounceZ * bounceOmega0 * a + delta * wd;
+                state.cosCoeff = bounceZ * bounceOmega0 * delta - a * wd;
+            }
+            else {
+                state.c = v0 + bounceOmega0 * delta;
+            }
+        }
+        // Sample the latched boundary spring in place: underdamped, critical, and the pin's
+        // capped-overdamped branch — the exact spring.ts/capped-form math, no allocation.
+        function sampleBoundarySpringInto(elapsedMs, state, out) {
+            if (bounceZ > 1) {
+                const f = Math.min(bounceDampedFreq * elapsedMs, 300);
+                const envelope = Math.exp(-bounceZ * bounceOmega0 * elapsedMs);
+                const current = state.bound -
+                    (envelope *
+                        ((state.initialVelocity + bounceZ * bounceOmega0 * state.initialDelta) * Math.sinh(f) +
+                            bounceDampedFreq * state.initialDelta * Math.cosh(f))) /
+                        bounceDampedFreq;
+                const velocityNow = envelope * (state.sinhCoeff * Math.sinh(f) + state.coshCoeff * Math.cosh(f)) * 1000;
+                const done = Math.abs(velocityNow) <= state.restSpeed &&
+                    Math.abs(state.bound - current) <= state.restDelta;
+                out.value = done ? state.bound : current;
+                out.velocity = velocityNow;
+                out.done = done;
+                return;
+            }
+            let current;
+            let velocityPerMs;
+            if (bounceZ < 1) {
+                const env = Math.exp(-bounceZ * bounceOmega0 * elapsedMs);
+                current =
+                    state.bound -
+                        env *
+                            (state.a * Math.sin(state.wd * elapsedMs) +
+                                state.initialDelta * Math.cos(state.wd * elapsedMs));
+                velocityPerMs =
+                    env *
+                        (state.sinCoeff * Math.sin(state.wd * elapsedMs) +
+                            state.cosCoeff * Math.cos(state.wd * elapsedMs));
+            }
+            else {
+                current =
+                    state.bound -
+                        Math.exp(-bounceOmega0 * elapsedMs) * (state.initialDelta + state.c * elapsedMs);
+                velocityPerMs =
+                    Math.exp(-bounceOmega0 * elapsedMs) *
+                        (bounceOmega0 * state.c * elapsedMs - state.initialVelocity);
+            }
+            const velocity = velocityPerMs * 1000; // → px/s (REQ-SPRING-008)
+            const done = Math.abs(velocity) <= state.restSpeed && Math.abs(state.bound - current) <= state.restDelta;
+            out.value = done ? state.bound : current;
+            out.velocity = velocity;
+            out.done = done;
+        }
+        function latchBoundaryInto(bound, value, t, state) {
+            crossingT = t;
+            // The pin's seed (motion-dom getGeneratorVelocity at the latch): the 5ms backward
+            // finite-diff of the DECAY curve — which degenerates to 0 at t=0 (empty window), so an
+            // out-of-bounds origin springs from rest, never from the analytic decay velocity.
+            const prevT = Math.max(t - 5, 0);
+            const dt = t - prevT;
+            const seedVelocity = dt === 0 ? 0 : ((value - decayValue(prevT)) / dt) * 1000;
+            resetBoundarySpringState(bound, value, seedVelocity, state);
+        }
+        // The pin's checkCatchBoundary(0): an out-of-bounds origin springs from t=0.
+        const initialBound = outOfBounds(seed.from);
+        if (initialBound !== undefined)
+            latchBoundaryInto(initialBound, seed.from, 0, boundaryState);
+        const record = { value: seed.from, velocity: seed.velocity, done: false };
+        return {
+            sample(elapsedMs) {
+                if (crossingT !== undefined && elapsedMs >= crossingT) {
+                    sampleBoundarySpringInto(elapsedMs - crossingT, boundaryState, record);
+                    return record;
+                }
+                const delta = decayDelta(elapsedMs);
+                const decayDone = Math.abs(delta) <= restDelta;
+                const value = decayDone ? target : decayValue(elapsedMs);
+                const velocity = decayVelocity(elapsedMs);
+                // OOB check on the POST-friction value — the pin checks after applyFriction, so a decay
+                // that settles past the wall (out-of-bounds target) still engages the boundary spring.
+                const bound = outOfBounds(value);
+                if (bound !== undefined) {
+                    latchBoundaryInto(bound, value, elapsedMs, boundaryState);
+                    sampleBoundarySpringInto(0, boundaryState, record);
+                    return record;
+                }
+                record.value = value;
+                record.velocity = decayDone ? 0 : velocity;
+                record.done = decayDone;
+                return record;
+            },
+        };
+    };
+}

package/dist/inertia.d.cts

@@ -0,0 +1,53 @@
+import type { GeneratorFactory } from "./types.cjs";
+/**
+ * Preallocated boundary-spring state (REQ-DRIVER-021, packet §6 inertia-midflight repair): one
+ * record per generator, reset at the latch and sampled in place — the mid-flight latch creates
+ * no closure, no GeneratorSample record, no generator object, and no springGenerator factory.
+ * Coefficients are the exact closed forms of spring.ts (under/critical) and the pin's capped
+ * overdamped branch (#1207), resolved once per latch by `resetBoundarySpringState`.
+ */
+export interface BoundarySpringState {
+    /** Latched bound (the spring target). */
+    bound: number;
+    /** Crossing value (the spring origin). */
+    from: number;
+    /** Seed velocity at the latch (px/s, public unit). */
+    velocity: number;
+    /** bound − from (px) and −velocity/1000 (px/ms) — spring.ts's delta/v0. */
+    initialDelta: number;
+    initialVelocity: number;
+    /** Rest thresholds resolved at the latch for the latched regime. */
+    restSpeed: number;
+    restDelta: number;
+    /** Underdamped coefficients (spring.ts: ωd, a, sin/cos). */
+    wd: number;
+    a: number;
+    sinCoeff: number;
+    cosCoeff: number;
+    /** Critically-damped coefficient (spring.ts: c = v0 + ω0·δ). */
+    c: number;
+    /** Capped-overdamped coefficients (the pin's #1207 sinh/cosh form). */
+    sinhCoeff: number;
+    coshCoeff: number;
+}
+export interface InertiaPhysics {
+    /** Pinned drag-layer default 0.8 (motion-dom inertia `power`). */
+    readonly power: number;
+    /** Pinned drag-layer default 750 ms (startAnimation spread; motion-dom's own default is 325). */
+    readonly timeConstant: number;
+    /** Boundary spring parameters — elastic-conditional 200/40 vs 1e6/1e7, `dragTransition` override. */
+    readonly bounceStiffness: number;
+    readonly bounceDamping: number;
+    /** Decay settle threshold (px): done when the remaining delta shrinks below it. Drag layer: 1. */
+    readonly restDelta: number;
+    /** Boundary spring settle threshold (px/s). Drag layer: 10. */
+    readonly restSpeed: number;
+    readonly min?: number;
+    readonly max?: number;
+}
+/**
+ * Build an inertia `GeneratorFactory` from pinned physics. The seed supplies the origin (`from`)
+ * and the release velocity (`velocity`, px/s — dragMomentum=false hands 0, the pin's
+ * `velocity: dragMomentum ? v : 0`).
+ */
+export declare function inertiaGenerator(physics: InertiaPhysics): GeneratorFactory;

package/dist/inertia.d.ts

@@ -0,0 +1,53 @@
+import type { GeneratorFactory } from "./types.js";
+/**
+ * Preallocated boundary-spring state (REQ-DRIVER-021, packet §6 inertia-midflight repair): one
+ * record per generator, reset at the latch and sampled in place — the mid-flight latch creates
+ * no closure, no GeneratorSample record, no generator object, and no springGenerator factory.
+ * Coefficients are the exact closed forms of spring.ts (under/critical) and the pin's capped
+ * overdamped branch (#1207), resolved once per latch by `resetBoundarySpringState`.
+ */
+export interface BoundarySpringState {
+    /** Latched bound (the spring target). */
+    bound: number;
+    /** Crossing value (the spring origin). */
+    from: number;
+    /** Seed velocity at the latch (px/s, public unit). */
+    velocity: number;
+    /** bound − from (px) and −velocity/1000 (px/ms) — spring.ts's delta/v0. */
+    initialDelta: number;
+    initialVelocity: number;
+    /** Rest thresholds resolved at the latch for the latched regime. */
+    restSpeed: number;
+    restDelta: number;
+    /** Underdamped coefficients (spring.ts: ωd, a, sin/cos). */
+    wd: number;
+    a: number;
+    sinCoeff: number;
+    cosCoeff: number;
+    /** Critically-damped coefficient (spring.ts: c = v0 + ω0·δ). */
+    c: number;
+    /** Capped-overdamped coefficients (the pin's #1207 sinh/cosh form). */
+    sinhCoeff: number;
+    coshCoeff: number;
+}
+export interface InertiaPhysics {
+    /** Pinned drag-layer default 0.8 (motion-dom inertia `power`). */
+    readonly power: number;
+    /** Pinned drag-layer default 750 ms (startAnimation spread; motion-dom's own default is 325). */
+    readonly timeConstant: number;
+    /** Boundary spring parameters — elastic-conditional 200/40 vs 1e6/1e7, `dragTransition` override. */
+    readonly bounceStiffness: number;
+    readonly bounceDamping: number;
+    /** Decay settle threshold (px): done when the remaining delta shrinks below it. Drag layer: 1. */
+    readonly restDelta: number;
+    /** Boundary spring settle threshold (px/s). Drag layer: 10. */
+    readonly restSpeed: number;
+    readonly min?: number;
+    readonly max?: number;
+}
+/**
+ * Build an inertia `GeneratorFactory` from pinned physics. The seed supplies the origin (`from`)
+ * and the release velocity (`velocity`, px/s — dragMomentum=false hands 0, the pin's
+ * `velocity: dragMomentum ? v : 0`).
+ */
+export declare function inertiaGenerator(physics: InertiaPhysics): GeneratorFactory;