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

package/dist/gesture/projection.cjs

@@ -0,0 +1,95 @@
+"use strict";
+// SPEC-GESTURE §2 — the projection function, project-then-snap selection, velocity normalization, and the
+// shared release-target selector. Pure functions over plain numbers (REQ-GESTURE-010/016/017/019); no graph,
+// no clock, no host. Host-agnostic (REQ-CORE-003): only a type import.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROJECTION_POWER = void 0;
+exports.project = project;
+exports.selectSnap = selectSnap;
+exports.normalizeVelocity = normalizeVelocity;
+exports.absoluteDragOrigin = absoluteDragOrigin;
+exports.selectReleaseTarget = selectReleaseTarget;
+const elastic_1 = require("./elastic.cjs");
+// The default projection power = the pinned `motion` 12.42.2 inertia `power` default (verified `power = 0.8`
+// in node_modules/motion-dom/dist). The M1 selection/monotonicity invariants only need `power > 0`, so this
+// exact value binds cross-engine PARITY (scenario 12, M2), not the M1 scenarios. A different value is a
+// recorded divergence (REQ-GESTURE-019).
+exports.PROJECTION_POWER = 0.8;
+// P(origin, v) = origin + power·v (REQ-GESTURE-019, Motion's `power · velocity` model). The projected landing
+// point the snap selector targets; `v = 0` collapses `ideal` to `origin` (nearest-to-release).
+function project(origin, velocity, power = exports.PROJECTION_POWER) {
+    return origin + power * velocity;
+}
+// argmin_{s ∈ points} |s − ideal| (REQ-GESTURE-017). Fails loud on an empty set (G-INV-8) — a snap drag with
+// no targets is a config error, never a silent no-op. Exact-midpoint ties resolve toward the SMALLER snap
+// value, ORDER-INDEPENDENT — matching the web mapping (`native-motion-web` nearestSnap) byte-for-byte so
+// the two engines never disagree on a tie (G-INV-10 cross-engine parity; review major 2). An
+// order-dependent tie-break would return the far snap on native and the near one on web for the same input.
+function selectSnap(ideal, points) {
+    if (points.length === 0) {
+        throw new Error('selectSnap: empty snap set — a snap drag needs at least one snap point (fail-loud, never a silent no-op)');
+    }
+    let best = points[0];
+    let bestDist = Math.abs(best - ideal);
+    for (let i = 1; i < points.length; i++) {
+        const p = points[i];
+        const d = Math.abs(p - ideal);
+        // Strictly nearer wins; on an exact tie the SMALLER value wins (web-parity, order-independent).
+        if (d < bestDist || (d === bestDist && p < best)) {
+            best = p;
+            bestDist = d;
+        }
+    }
+    return best;
+}
+// Normalize a recognizer velocity to the canonical px/s unit (REQ-GESTURE-010, Decision §G). The platform
+// velocity is already px/s, so this is a unit-contract pass-through that carries sign — explicitly NO ÷1000
+// (a px/ms conversion is the defect this guards). Fails loud on a non-finite value; it never silently zeroes
+// (a hold-then-release yields a genuine ~0 sample from the platform, which is finite and passes through).
+function normalizeVelocity(velocity) {
+    if (!Number.isFinite(velocity)) {
+        throw new Error(`normalizeVelocity: velocity must be a finite px/s value, got ${velocity}`);
+    }
+    return velocity;
+}
+// Product dual-authority baseline (REQ-GESTURE-022 class): host drag callbacks report gesture-relative
+// `info.offset` (Motion PanInfo / native translationX/Y). The engine handoff projects from the absolute
+// live release origin. Controlled product `animate` retargets must rebuild absolute origin as
+// grabOrigin (last committed snap / settle) + gesture-relative offset — never offset alone when grab≠0.
+function absoluteDragOrigin(grabOrigin, gestureRelativeOffset) {
+    if (!Number.isFinite(grabOrigin) || !Number.isFinite(gestureRelativeOffset)) {
+        throw new Error(`absoluteDragOrigin: grabOrigin and gestureRelativeOffset must be finite, got ${grabOrigin}, ${gestureRelativeOffset}`);
+    }
+    return grabOrigin + gestureRelativeOffset;
+}
+// The release target (REQ-GESTURE-016/017/023), shared verbatim by the M1 session and the handoff session
+// (REQ-GESTURE-022) so the terminal decision can never fork: a boundary spring-back when released past a
+// constraint bound, else project-then-snap onto the snap set, else — free-drag — the projected ideal
+// clamped into the constraints. Under R16 that clamped ideal is NOT a spring target (the retired R13
+// clamp): it is the inertia descriptor's MIRROR terminal — the two-phase generator recomputes its own
+// ideal from the seed and owns the walls, so the actual settle can diverge from it (an out-of-bounds
+// origin settles AT the violated bound via the t=0 latch, never at a clamped ideal that lies elsewhere).
+function selectReleaseTarget(current, platformVelocity, constraints, snap) {
+    if (constraints !== undefined) {
+        // Same polarity law as applyConstraints (review major 0d144ea2f856): refuse wrong-polarity
+        // open sentinels before any comparison that would return ±Infinity as a spring target.
+        (0, elastic_1.assertLegalConstraintBounds)(constraints, 'selectReleaseTarget');
+        if (Number.isFinite(constraints.max) && current > constraints.max)
+            return constraints.max;
+        if (Number.isFinite(constraints.min) && current < constraints.min)
+            return constraints.min;
+    }
+    if (snap !== undefined)
+        return selectSnap(project(current, platformVelocity), snap.points);
+    // Free-drag (REQ-GESTURE-023): the inertia descriptor's MIRROR terminal — Motion inertia
+    // ideal = origin + power · v, clamped into the constraints. The generator owns the actual
+    // settle (R16); this value never steers the curve.
+    const ideal = project(current, platformVelocity);
+    if (constraints === undefined)
+        return ideal;
+    if (Number.isFinite(constraints.max) && ideal > constraints.max)
+        return constraints.max;
+    if (Number.isFinite(constraints.min) && ideal < constraints.min)
+        return constraints.min;
+    return ideal;
+}

package/dist/gesture/projection.d.cts

@@ -0,0 +1,7 @@
+import type { DragConstraints, SnapConfig } from "./types.cjs";
+export declare const PROJECTION_POWER = 0.8;
+export declare function project(origin: number, velocity: number, power?: number): number;
+export declare function selectSnap(ideal: number, points: readonly number[]): number;
+export declare function normalizeVelocity(velocity: number): number;
+export declare function absoluteDragOrigin(grabOrigin: number, gestureRelativeOffset: number): number;
+export declare function selectReleaseTarget(current: number, platformVelocity: number, constraints: DragConstraints | undefined, snap: SnapConfig | undefined): number;

package/dist/gesture/projection.d.ts

@@ -0,0 +1,7 @@
+import type { DragConstraints, SnapConfig } from "./types.js";
+export declare const PROJECTION_POWER = 0.8;
+export declare function project(origin: number, velocity: number, power?: number): number;
+export declare function selectSnap(ideal: number, points: readonly number[]): number;
+export declare function normalizeVelocity(velocity: number): number;
+export declare function absoluteDragOrigin(grabOrigin: number, gestureRelativeOffset: number): number;
+export declare function selectReleaseTarget(current: number, platformVelocity: number, constraints: DragConstraints | undefined, snap: SnapConfig | undefined): number;

package/dist/gesture/projection.js

@@ -0,0 +1,87 @@
+// SPEC-GESTURE §2 — the projection function, project-then-snap selection, velocity normalization, and the
+// shared release-target selector. Pure functions over plain numbers (REQ-GESTURE-010/016/017/019); no graph,
+// no clock, no host. Host-agnostic (REQ-CORE-003): only a type import.
+import { assertLegalConstraintBounds } from "./elastic.js";
+// The default projection power = the pinned `motion` 12.42.2 inertia `power` default (verified `power = 0.8`
+// in node_modules/motion-dom/dist). The M1 selection/monotonicity invariants only need `power > 0`, so this
+// exact value binds cross-engine PARITY (scenario 12, M2), not the M1 scenarios. A different value is a
+// recorded divergence (REQ-GESTURE-019).
+export const PROJECTION_POWER = 0.8;
+// P(origin, v) = origin + power·v (REQ-GESTURE-019, Motion's `power · velocity` model). The projected landing
+// point the snap selector targets; `v = 0` collapses `ideal` to `origin` (nearest-to-release).
+export function project(origin, velocity, power = PROJECTION_POWER) {
+    return origin + power * velocity;
+}
+// argmin_{s ∈ points} |s − ideal| (REQ-GESTURE-017). Fails loud on an empty set (G-INV-8) — a snap drag with
+// no targets is a config error, never a silent no-op. Exact-midpoint ties resolve toward the SMALLER snap
+// value, ORDER-INDEPENDENT — matching the web mapping (`native-motion-web` nearestSnap) byte-for-byte so
+// the two engines never disagree on a tie (G-INV-10 cross-engine parity; review major 2). An
+// order-dependent tie-break would return the far snap on native and the near one on web for the same input.
+export function selectSnap(ideal, points) {
+    if (points.length === 0) {
+        throw new Error('selectSnap: empty snap set — a snap drag needs at least one snap point (fail-loud, never a silent no-op)');
+    }
+    let best = points[0];
+    let bestDist = Math.abs(best - ideal);
+    for (let i = 1; i < points.length; i++) {
+        const p = points[i];
+        const d = Math.abs(p - ideal);
+        // Strictly nearer wins; on an exact tie the SMALLER value wins (web-parity, order-independent).
+        if (d < bestDist || (d === bestDist && p < best)) {
+            best = p;
+            bestDist = d;
+        }
+    }
+    return best;
+}
+// Normalize a recognizer velocity to the canonical px/s unit (REQ-GESTURE-010, Decision §G). The platform
+// velocity is already px/s, so this is a unit-contract pass-through that carries sign — explicitly NO ÷1000
+// (a px/ms conversion is the defect this guards). Fails loud on a non-finite value; it never silently zeroes
+// (a hold-then-release yields a genuine ~0 sample from the platform, which is finite and passes through).
+export function normalizeVelocity(velocity) {
+    if (!Number.isFinite(velocity)) {
+        throw new Error(`normalizeVelocity: velocity must be a finite px/s value, got ${velocity}`);
+    }
+    return velocity;
+}
+// Product dual-authority baseline (REQ-GESTURE-022 class): host drag callbacks report gesture-relative
+// `info.offset` (Motion PanInfo / native translationX/Y). The engine handoff projects from the absolute
+// live release origin. Controlled product `animate` retargets must rebuild absolute origin as
+// grabOrigin (last committed snap / settle) + gesture-relative offset — never offset alone when grab≠0.
+export function absoluteDragOrigin(grabOrigin, gestureRelativeOffset) {
+    if (!Number.isFinite(grabOrigin) || !Number.isFinite(gestureRelativeOffset)) {
+        throw new Error(`absoluteDragOrigin: grabOrigin and gestureRelativeOffset must be finite, got ${grabOrigin}, ${gestureRelativeOffset}`);
+    }
+    return grabOrigin + gestureRelativeOffset;
+}
+// The release target (REQ-GESTURE-016/017/023), shared verbatim by the M1 session and the handoff session
+// (REQ-GESTURE-022) so the terminal decision can never fork: a boundary spring-back when released past a
+// constraint bound, else project-then-snap onto the snap set, else — free-drag — the projected ideal
+// clamped into the constraints. Under R16 that clamped ideal is NOT a spring target (the retired R13
+// clamp): it is the inertia descriptor's MIRROR terminal — the two-phase generator recomputes its own
+// ideal from the seed and owns the walls, so the actual settle can diverge from it (an out-of-bounds
+// origin settles AT the violated bound via the t=0 latch, never at a clamped ideal that lies elsewhere).
+export function selectReleaseTarget(current, platformVelocity, constraints, snap) {
+    if (constraints !== undefined) {
+        // Same polarity law as applyConstraints (review major 0d144ea2f856): refuse wrong-polarity
+        // open sentinels before any comparison that would return ±Infinity as a spring target.
+        assertLegalConstraintBounds(constraints, 'selectReleaseTarget');
+        if (Number.isFinite(constraints.max) && current > constraints.max)
+            return constraints.max;
+        if (Number.isFinite(constraints.min) && current < constraints.min)
+            return constraints.min;
+    }
+    if (snap !== undefined)
+        return selectSnap(project(current, platformVelocity), snap.points);
+    // Free-drag (REQ-GESTURE-023): the inertia descriptor's MIRROR terminal — Motion inertia
+    // ideal = origin + power · v, clamped into the constraints. The generator owns the actual
+    // settle (R16); this value never steers the curve.
+    const ideal = project(current, platformVelocity);
+    if (constraints === undefined)
+        return ideal;
+    if (Number.isFinite(constraints.max) && ideal > constraints.max)
+        return constraints.max;
+    if (Number.isFinite(constraints.min) && ideal < constraints.min)
+        return constraints.min;
+    return ideal;
+}

package/dist/gesture/session.cjs

@@ -0,0 +1,162 @@
+"use strict";
+// SPEC-GESTURE §2 — the gesture SESSION: the total begin→active→end/cancel state machine that ingests a
+// recognizer sample stream, drives a motion value continuously with grab continuity + live constraints, and
+// on release hands off `(live value, platform velocity)` into the pinned two-phase inertia generator
+// (free-drag, REQ-GESTURE-023 R16) or a velocity-seeded spring toward a project-then-snap target (snap).
+// Drives the exit off the injected MotionGraph + the built generators — no forked math, no velocity
+// estimator (Decision §G), no driver/React import. Host-agnostic (REQ-CORE-003): relative imports only.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GESTURE_RELEASE_SPRING = void 0;
+exports.createGestureSession = createGestureSession;
+const transition_1 = require("../transition.cjs");
+const inertia_1 = require("../inertia.cjs");
+const elastic_1 = require("./elastic.cjs");
+const projection_1 = require("./projection.cjs");
+// First-spike release spring (physics ⇒ carries the seeded velocity, REQ-SPRING-007). A near-critical snap
+// spring — minimal overshoot for a settling sheet. Config constant, not an inline literal; refinable (the
+// exact stiffness/damping binds feel + cross-engine parity at M2, not the M1 continuity/settle invariants).
+// Exported: the component's driver-integrated release (REQ-GESTURE-022) seeds the SAME default into the
+// driver's spring — one constant, never a duplicated literal. Typed with REQUIRED fields (satisfies, not
+// annotation) so consumers can lift it into shapes with required numbers under exactOptionalPropertyTypes.
+exports.GESTURE_RELEASE_SPRING = {
+    stiffness: 400,
+    damping: 40,
+};
+// Wrap a generator factory so the spring seeds from the LIVE value (C0) but with an EXPLICIT velocity (the
+// platform release velocity, §G) rather than the value's own tracked velocity. The release spring is physics-
+// resolved (carryVelocity true), so the seeded velocity is honored.
+function seedWith(factory, velocity) {
+    return (seed) => factory({ from: seed.from, velocity });
+}
+function createGestureSession(options) {
+    const { graph } = options;
+    const constraints = options.constraints;
+    const snap = options.snap;
+    const releaseSpring = options.releaseSpring ?? exports.GESTURE_RELEASE_SPRING;
+    const value = graph.motionValue(options.initial ?? 0);
+    let state = 'idle';
+    let grabValue = 0; // the value at the last grab (P0)
+    let activationTranslation = 0; // recognizer translation captured at activation (dead-zone subtraction)
+    let preGrabValue = 0; // the value before the current grab — the cancel target (REQ-GESTURE-018)
+    let animation; // the in-flight release/cancel spring, if any
+    let lastHandoffVelocity; // the velocity seeded at the last release/cancel (§G)
+    // A finger being down is unsettled work with no animation, so the graph would otherwise report settled
+    // mid-drag. Hold an activity handle for the duration of the active gesture (G-INV-7 / REQ-DRIVER-002).
+    let dragHandle;
+    function releaseDragHandle() {
+        dragHandle?.release();
+        dragHandle = undefined;
+    }
+    // Reconcile the internal state to the graph: once the release/cancel spring has settled, the session is
+    // idle again. The settle is asynchronous (a later frame step), so the session cannot mutate `state` at the
+    // moment it happens — every state-dependent entry point reconciles first. Without this the field stayed
+    // stale at 'settling' after settle, and a subsequent cancel()/fail() rewound to the PREVIOUS gesture's
+    // pre-grab value (the "idle cancel rewind"). The state() getter reconciled for reads but the mutators did
+    // not, so the public state and the behavior disagreed.
+    function sync() {
+        if (state === 'settling' && graph.isSettled())
+            state = 'idle';
+    }
+    // Map a recognizer translation to the constrained motion value: P0 + (translation − activation), then
+    // hard-clamp / rubber-band per constraints (REQ-GESTURE-011/015). Delta-since-activation gives C0 across a
+    // non-zero activeOffset dead zone.
+    function applyToValue(translation) {
+        const raw = grabValue + (translation - activationTranslation);
+        value.set(constraints === undefined ? raw : (0, elastic_1.applyConstraints)(raw, constraints));
+    }
+    function startSpring(target, seedVelocity) {
+        animation = graph.animate(value, seedWith((0, transition_1.resolveSpringGenerator)(target, releaseSpring), seedVelocity));
+        state = 'settling';
+    }
+    // R16 (REQ-GESTURE-023): the free-drag release runs the pinned two-phase inertia generator on
+    // the SAME graph — the decay + boundary-spring curve, never the projected-landing spring. The
+    // generator recomputes the ideal from the seed and owns the walls; the drag-layer physics are
+    // the pin's (timeConstant 750, power 0.8, restDelta 1, restSpeed 10, elastic-conditional bounce).
+    function startInertia(seedVelocity) {
+        const elastic = constraints?.elastic;
+        const bounce = (0, transition_1.dragInertiaBounce)(elastic);
+        animation = graph.animate(value, seedWith((0, inertia_1.inertiaGenerator)({
+            power: transition_1.DRAG_INERTIA_DEFAULTS.power,
+            timeConstant: transition_1.DRAG_INERTIA_DEFAULTS.timeConstant,
+            bounceStiffness: bounce.bounceStiffness,
+            bounceDamping: bounce.bounceDamping,
+            restDelta: transition_1.DRAG_INERTIA_DEFAULTS.restDelta,
+            restSpeed: transition_1.DRAG_INERTIA_DEFAULTS.restSpeed,
+            ...(constraints === undefined ? {} : { min: constraints.min, max: constraints.max }),
+        }), seedVelocity));
+        state = 'settling';
+    }
+    function cancelTo(target) {
+        sync(); // reconcile first — a settled release is 'idle', not a stale 'settling' (else the guard misfires)
+        if (state !== 'active' && state !== 'settling') {
+            // idle ⇒ no gesture in flight. Fail loud, consistent with the total state machine (G-INV-8:
+            // illegal transitions throw). NOT a silent no-op (which hides recognizer/caller misuse) and NOT a
+            // rewind — the throw fires before any mutation, so the settled value is untouched.
+            throw new Error(`gesture: cancel() in state '${state}' — no active or settling gesture to cancel`);
+        }
+        // state is 'active' (cancel the drag) or 'settling' (redirect the in-flight release) — both cancel to target.
+        animation?.stop();
+        lastHandoffVelocity = 0;
+        startSpring(target, 0); // cancel is a zero-velocity return to the cancel target (REQ-GESTURE-018)
+        releaseDragHandle(); // the spring now holds the graph unsettled; drop the drag handle
+    }
+    return {
+        begin(activation) {
+            sync(); // a settled prior release is idle, not 'settling' — a fresh grab is legal
+            if (state === 'active') {
+                throw new Error('gesture: begin() during an active gesture — end() or cancel() first');
+            }
+            animation?.stop(); // re-grab: stop any in-flight release (decrements activeAnimationCount, REQ-GESTURE-012)
+            animation = undefined;
+            releaseDragHandle(); // defensive: never stack handles across a re-grab
+            grabValue = value.get();
+            preGrabValue = value.get();
+            activationTranslation = activation;
+            dragHandle = graph.registerActivity(); // a finger is down ⇒ the graph is unsettled (G-INV-7)
+            state = 'active';
+        },
+        active(sample) {
+            sync();
+            if (state !== 'active') {
+                throw new Error(`gesture: active() in state '${state}' — begin() a gesture first`);
+            }
+            applyToValue(sample.translation);
+        },
+        end(sample) {
+            sync();
+            if (state !== 'active') {
+                throw new Error(`gesture: end() in state '${state}' — no active gesture to release`);
+            }
+            applyToValue(sample.translation); // commit the final active position (C0 seam)
+            const platformVelocity = (0, projection_1.normalizeVelocity)(sample.velocity);
+            if (snap === undefined) {
+                // Free-drag (REQ-GESTURE-023, R16): the two-phase inertia generator owns the curve.
+                lastHandoffVelocity = platformVelocity;
+                startInertia(platformVelocity);
+            }
+            else {
+                // Resolve the target BEFORE mutating settle state so a config error leaves the session
+                // untouched rather than half-released. The selector is the SHARED pure seam (REQ-GESTURE-022 parity).
+                const target = (0, projection_1.selectReleaseTarget)(value.get(), platformVelocity, constraints, snap);
+                lastHandoffVelocity = platformVelocity; // the velocity handed off, UNSCALED (§G / REQ-GESTURE-013)
+                startSpring(target, platformVelocity);
+            }
+            releaseDragHandle(); // release AFTER the spring starts so there is no spurious settled frame
+        },
+        cancel() {
+            cancelTo(preGrabValue);
+        },
+        fail() {
+            cancelTo(preGrabValue); // a recognizer fail is a cancel to the pre-grab value (REQ-GESTURE-018)
+        },
+        value: () => value.get(),
+        velocity: () => value.getVelocity(),
+        isSettled: () => graph.isSettled(),
+        // Reconcile the post-release state: once the release/cancel spring has settled, the session is idle.
+        state: () => {
+            sync();
+            return state;
+        },
+        handoffVelocity: () => lastHandoffVelocity,
+    };
+}

package/dist/gesture/session.d.cts

@@ -0,0 +1,29 @@
+import { type SpringConfig } from "../transition.cjs";
+import type { MotionGraph } from "../types.cjs";
+import type { DragConstraints, GestureSample, SnapConfig } from "./types.cjs";
+export declare const GESTURE_RELEASE_SPRING: {
+    readonly stiffness: 400;
+    readonly damping: 40;
+};
+export type GestureSessionState = 'idle' | 'active' | 'settling';
+export interface GestureSessionOptions {
+    readonly graph: MotionGraph;
+    readonly initial?: number;
+    readonly constraints?: DragConstraints;
+    readonly snap?: SnapConfig;
+    readonly releaseSpring?: SpringConfig;
+}
+export interface GestureSession {
+    begin(activationTranslation: number): void;
+    active(sample: GestureSample): void;
+    end(sample: GestureSample): void;
+    cancel(): void;
+    fail(): void;
+    value(): number;
+    velocity(): number;
+    isSettled(): boolean;
+    state(): GestureSessionState;
+    /** The velocity (px/s) seeded into the following animation at the last release/cancel; `undefined` before any. */
+    handoffVelocity(): number | undefined;
+}
+export declare function createGestureSession(options: GestureSessionOptions): GestureSession;

package/dist/gesture/session.d.ts

@@ -0,0 +1,29 @@
+import { type SpringConfig } from "../transition.js";
+import type { MotionGraph } from "../types.js";
+import type { DragConstraints, GestureSample, SnapConfig } from "./types.js";
+export declare const GESTURE_RELEASE_SPRING: {
+    readonly stiffness: 400;
+    readonly damping: 40;
+};
+export type GestureSessionState = 'idle' | 'active' | 'settling';
+export interface GestureSessionOptions {
+    readonly graph: MotionGraph;
+    readonly initial?: number;
+    readonly constraints?: DragConstraints;
+    readonly snap?: SnapConfig;
+    readonly releaseSpring?: SpringConfig;
+}
+export interface GestureSession {
+    begin(activationTranslation: number): void;
+    active(sample: GestureSample): void;
+    end(sample: GestureSample): void;
+    cancel(): void;
+    fail(): void;
+    value(): number;
+    velocity(): number;
+    isSettled(): boolean;
+    state(): GestureSessionState;
+    /** The velocity (px/s) seeded into the following animation at the last release/cancel; `undefined` before any. */
+    handoffVelocity(): number | undefined;
+}
+export declare function createGestureSession(options: GestureSessionOptions): GestureSession;

package/dist/gesture/session.js

@@ -0,0 +1,158 @@
+// SPEC-GESTURE §2 — the gesture SESSION: the total begin→active→end/cancel state machine that ingests a
+// recognizer sample stream, drives a motion value continuously with grab continuity + live constraints, and
+// on release hands off `(live value, platform velocity)` into the pinned two-phase inertia generator
+// (free-drag, REQ-GESTURE-023 R16) or a velocity-seeded spring toward a project-then-snap target (snap).
+// Drives the exit off the injected MotionGraph + the built generators — no forked math, no velocity
+// estimator (Decision §G), no driver/React import. Host-agnostic (REQ-CORE-003): relative imports only.
+import { DRAG_INERTIA_DEFAULTS, dragInertiaBounce, resolveSpringGenerator, } from "../transition.js";
+import { inertiaGenerator } from "../inertia.js";
+import { applyConstraints } from "./elastic.js";
+import { normalizeVelocity, selectReleaseTarget } from "./projection.js";
+// First-spike release spring (physics ⇒ carries the seeded velocity, REQ-SPRING-007). A near-critical snap
+// spring — minimal overshoot for a settling sheet. Config constant, not an inline literal; refinable (the
+// exact stiffness/damping binds feel + cross-engine parity at M2, not the M1 continuity/settle invariants).
+// Exported: the component's driver-integrated release (REQ-GESTURE-022) seeds the SAME default into the
+// driver's spring — one constant, never a duplicated literal. Typed with REQUIRED fields (satisfies, not
+// annotation) so consumers can lift it into shapes with required numbers under exactOptionalPropertyTypes.
+export const GESTURE_RELEASE_SPRING = {
+    stiffness: 400,
+    damping: 40,
+};
+// Wrap a generator factory so the spring seeds from the LIVE value (C0) but with an EXPLICIT velocity (the
+// platform release velocity, §G) rather than the value's own tracked velocity. The release spring is physics-
+// resolved (carryVelocity true), so the seeded velocity is honored.
+function seedWith(factory, velocity) {
+    return (seed) => factory({ from: seed.from, velocity });
+}
+export function createGestureSession(options) {
+    const { graph } = options;
+    const constraints = options.constraints;
+    const snap = options.snap;
+    const releaseSpring = options.releaseSpring ?? GESTURE_RELEASE_SPRING;
+    const value = graph.motionValue(options.initial ?? 0);
+    let state = 'idle';
+    let grabValue = 0; // the value at the last grab (P0)
+    let activationTranslation = 0; // recognizer translation captured at activation (dead-zone subtraction)
+    let preGrabValue = 0; // the value before the current grab — the cancel target (REQ-GESTURE-018)
+    let animation; // the in-flight release/cancel spring, if any
+    let lastHandoffVelocity; // the velocity seeded at the last release/cancel (§G)
+    // A finger being down is unsettled work with no animation, so the graph would otherwise report settled
+    // mid-drag. Hold an activity handle for the duration of the active gesture (G-INV-7 / REQ-DRIVER-002).
+    let dragHandle;
+    function releaseDragHandle() {
+        dragHandle?.release();
+        dragHandle = undefined;
+    }
+    // Reconcile the internal state to the graph: once the release/cancel spring has settled, the session is
+    // idle again. The settle is asynchronous (a later frame step), so the session cannot mutate `state` at the
+    // moment it happens — every state-dependent entry point reconciles first. Without this the field stayed
+    // stale at 'settling' after settle, and a subsequent cancel()/fail() rewound to the PREVIOUS gesture's
+    // pre-grab value (the "idle cancel rewind"). The state() getter reconciled for reads but the mutators did
+    // not, so the public state and the behavior disagreed.
+    function sync() {
+        if (state === 'settling' && graph.isSettled())
+            state = 'idle';
+    }
+    // Map a recognizer translation to the constrained motion value: P0 + (translation − activation), then
+    // hard-clamp / rubber-band per constraints (REQ-GESTURE-011/015). Delta-since-activation gives C0 across a
+    // non-zero activeOffset dead zone.
+    function applyToValue(translation) {
+        const raw = grabValue + (translation - activationTranslation);
+        value.set(constraints === undefined ? raw : applyConstraints(raw, constraints));
+    }
+    function startSpring(target, seedVelocity) {
+        animation = graph.animate(value, seedWith(resolveSpringGenerator(target, releaseSpring), seedVelocity));
+        state = 'settling';
+    }
+    // R16 (REQ-GESTURE-023): the free-drag release runs the pinned two-phase inertia generator on
+    // the SAME graph — the decay + boundary-spring curve, never the projected-landing spring. The
+    // generator recomputes the ideal from the seed and owns the walls; the drag-layer physics are
+    // the pin's (timeConstant 750, power 0.8, restDelta 1, restSpeed 10, elastic-conditional bounce).
+    function startInertia(seedVelocity) {
+        const elastic = constraints?.elastic;
+        const bounce = dragInertiaBounce(elastic);
+        animation = graph.animate(value, seedWith(inertiaGenerator({
+            power: DRAG_INERTIA_DEFAULTS.power,
+            timeConstant: DRAG_INERTIA_DEFAULTS.timeConstant,
+            bounceStiffness: bounce.bounceStiffness,
+            bounceDamping: bounce.bounceDamping,
+            restDelta: DRAG_INERTIA_DEFAULTS.restDelta,
+            restSpeed: DRAG_INERTIA_DEFAULTS.restSpeed,
+            ...(constraints === undefined ? {} : { min: constraints.min, max: constraints.max }),
+        }), seedVelocity));
+        state = 'settling';
+    }
+    function cancelTo(target) {
+        sync(); // reconcile first — a settled release is 'idle', not a stale 'settling' (else the guard misfires)
+        if (state !== 'active' && state !== 'settling') {
+            // idle ⇒ no gesture in flight. Fail loud, consistent with the total state machine (G-INV-8:
+            // illegal transitions throw). NOT a silent no-op (which hides recognizer/caller misuse) and NOT a
+            // rewind — the throw fires before any mutation, so the settled value is untouched.
+            throw new Error(`gesture: cancel() in state '${state}' — no active or settling gesture to cancel`);
+        }
+        // state is 'active' (cancel the drag) or 'settling' (redirect the in-flight release) — both cancel to target.
+        animation?.stop();
+        lastHandoffVelocity = 0;
+        startSpring(target, 0); // cancel is a zero-velocity return to the cancel target (REQ-GESTURE-018)
+        releaseDragHandle(); // the spring now holds the graph unsettled; drop the drag handle
+    }
+    return {
+        begin(activation) {
+            sync(); // a settled prior release is idle, not 'settling' — a fresh grab is legal
+            if (state === 'active') {
+                throw new Error('gesture: begin() during an active gesture — end() or cancel() first');
+            }
+            animation?.stop(); // re-grab: stop any in-flight release (decrements activeAnimationCount, REQ-GESTURE-012)
+            animation = undefined;
+            releaseDragHandle(); // defensive: never stack handles across a re-grab
+            grabValue = value.get();
+            preGrabValue = value.get();
+            activationTranslation = activation;
+            dragHandle = graph.registerActivity(); // a finger is down ⇒ the graph is unsettled (G-INV-7)
+            state = 'active';
+        },
+        active(sample) {
+            sync();
+            if (state !== 'active') {
+                throw new Error(`gesture: active() in state '${state}' — begin() a gesture first`);
+            }
+            applyToValue(sample.translation);
+        },
+        end(sample) {
+            sync();
+            if (state !== 'active') {
+                throw new Error(`gesture: end() in state '${state}' — no active gesture to release`);
+            }
+            applyToValue(sample.translation); // commit the final active position (C0 seam)
+            const platformVelocity = normalizeVelocity(sample.velocity);
+            if (snap === undefined) {
+                // Free-drag (REQ-GESTURE-023, R16): the two-phase inertia generator owns the curve.
+                lastHandoffVelocity = platformVelocity;
+                startInertia(platformVelocity);
+            }
+            else {
+                // Resolve the target BEFORE mutating settle state so a config error leaves the session
+                // untouched rather than half-released. The selector is the SHARED pure seam (REQ-GESTURE-022 parity).
+                const target = selectReleaseTarget(value.get(), platformVelocity, constraints, snap);
+                lastHandoffVelocity = platformVelocity; // the velocity handed off, UNSCALED (§G / REQ-GESTURE-013)
+                startSpring(target, platformVelocity);
+            }
+            releaseDragHandle(); // release AFTER the spring starts so there is no spurious settled frame
+        },
+        cancel() {
+            cancelTo(preGrabValue);
+        },
+        fail() {
+            cancelTo(preGrabValue); // a recognizer fail is a cancel to the pre-grab value (REQ-GESTURE-018)
+        },
+        value: () => value.get(),
+        velocity: () => value.getVelocity(),
+        isSettled: () => graph.isSettled(),
+        // Reconcile the post-release state: once the release/cancel spring has settled, the session is idle.
+        state: () => {
+            sync();
+            return state;
+        },
+        handoffVelocity: () => lastHandoffVelocity,
+    };
+}

package/dist/gesture/types.cjs

@@ -0,0 +1,5 @@
+"use strict";
+// SPEC-GESTURE §2 — the gesture ingest + constraint types. Host-agnostic (REQ-CORE-003): plain data only,
+// no react/react-native/Gesture-Handler import. A recognizer stream is modeled as a sequence of these
+// samples; the real Gesture Handler / motion-react bindings that produce them are Milestone 2 (deferred).
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/gesture/types.d.cts

@@ -0,0 +1,13 @@
+export interface GestureSample {
+    readonly t: number;
+    readonly translation: number;
+    readonly velocity: number;
+}
+export interface DragConstraints {
+    readonly min: number;
+    readonly max: number;
+    readonly elastic?: number;
+}
+export interface SnapConfig {
+    readonly points: readonly number[];
+}

package/dist/gesture/types.d.ts

@@ -0,0 +1,13 @@
+export interface GestureSample {
+    readonly t: number;
+    readonly translation: number;
+    readonly velocity: number;
+}
+export interface DragConstraints {
+    readonly min: number;
+    readonly max: number;
+    readonly elastic?: number;
+}
+export interface SnapConfig {
+    readonly points: readonly number[];
+}

package/dist/gesture/types.js

@@ -0,0 +1,4 @@
+// SPEC-GESTURE §2 — the gesture ingest + constraint types. Host-agnostic (REQ-CORE-003): plain data only,
+// no react/react-native/Gesture-Handler import. A recognizer stream is modeled as a sequence of these
+// samples; the real Gesture Handler / motion-react bindings that produce them are Milestone 2 (deferred).
+export {};