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

package/dist/gesture/elastic.cjs

@@ -0,0 +1,44 @@
+"use strict";
+// SPEC-GESTURE §2 — drag constraint application: hard clamp and Motion's linear rubber-band transfer. Pure
+// functions (REQ-GESTURE-015/016, G-INV-6/8); host-agnostic (REQ-CORE-003): only a type import.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.elasticTransfer = elasticTransfer;
+exports.assertLegalConstraintBounds = assertLegalConstraintBounds;
+exports.applyConstraints = applyConstraints;
+// Motion's linear rubber-band mix (REQ-GESTURE-016): overshoot = e · excess. Monotone non-decreasing in
+// `excess` for e ≥ 0, exactly 0 at e = 0, continuous at the boundary (excess → 0 ⇒ overshoot → 0).
+function elasticTransfer(excess, elastic) {
+    return elastic * excess;
+}
+// Open-side sentinels for one-sided numeric constraints (REQ-API-024 shipping slice, Motion parity):
+// only `min = -Infinity` and/or `max = +Infinity` mean "no bound on that side". Wrong-polarity
+// infinity (`min = +∞` or `max = -∞`) is illegal — it would make every release target Infinity and
+// start a non-converging spring (G-INV-8). Shared by applyConstraints + selectReleaseTarget so the
+// live clamp and the release seam never disagree on legality.
+function assertLegalConstraintBounds(c, where = 'constraints') {
+    const minOk = Number.isFinite(c.min) || c.min === Number.NEGATIVE_INFINITY;
+    const maxOk = Number.isFinite(c.max) || c.max === Number.POSITIVE_INFINITY;
+    if (!minOk || !maxOk) {
+        throw new Error(`${where}: open-side sentinels must be min=-Infinity and/or max=+Infinity ` +
+            `(got min=${c.min}, max=${c.max}); wrong-polarity or NaN bounds are refused (G-INV-8, REQ-API-024).`);
+    }
+    if (c.min > c.max) {
+        throw new Error(`${where}: min (${c.min}) must be <= max (${c.max})`);
+    }
+}
+// Validate + apply drag constraints (REQ-GESTURE-015/016, G-INV-8). Inside `[min, max]`: pass through. Past a
+// bound: a hard clamp when elastic is 0/absent (`min ≤ value ≤ max`), else `bound ± e·excess` (rubber-band,
+// symmetric on both bounds). Open sides (legal ±Infinity) skip that side's clamp. Malformed config —
+// wrong-polarity sentinels, NaN bounds, `min > max`, or `elastic ∉ [0, 1]` — throws at the call site.
+function applyConstraints(value, c) {
+    const elastic = c.elastic ?? 0;
+    assertLegalConstraintBounds(c, 'applyConstraints');
+    if (!Number.isFinite(elastic) || elastic < 0 || elastic > 1) {
+        throw new Error(`applyConstraints: elastic must be in [0, 1], got ${elastic}`);
+    }
+    if (Number.isFinite(c.max) && value > c.max)
+        return c.max + elasticTransfer(value - c.max, elastic);
+    if (Number.isFinite(c.min) && value < c.min)
+        return c.min - elasticTransfer(c.min - value, elastic);
+    return value;
+}

package/dist/gesture/elastic.d.cts

@@ -0,0 +1,4 @@
+import type { DragConstraints } from "./types.cjs";
+export declare function elasticTransfer(excess: number, elastic: number): number;
+export declare function assertLegalConstraintBounds(c: DragConstraints, where?: string): void;
+export declare function applyConstraints(value: number, c: DragConstraints): number;

package/dist/gesture/elastic.d.ts

@@ -0,0 +1,4 @@
+import type { DragConstraints } from "./types.js";
+export declare function elasticTransfer(excess: number, elastic: number): number;
+export declare function assertLegalConstraintBounds(c: DragConstraints, where?: string): void;
+export declare function applyConstraints(value: number, c: DragConstraints): number;

package/dist/gesture/elastic.js

@@ -0,0 +1,39 @@
+// SPEC-GESTURE §2 — drag constraint application: hard clamp and Motion's linear rubber-band transfer. Pure
+// functions (REQ-GESTURE-015/016, G-INV-6/8); host-agnostic (REQ-CORE-003): only a type import.
+// Motion's linear rubber-band mix (REQ-GESTURE-016): overshoot = e · excess. Monotone non-decreasing in
+// `excess` for e ≥ 0, exactly 0 at e = 0, continuous at the boundary (excess → 0 ⇒ overshoot → 0).
+export function elasticTransfer(excess, elastic) {
+    return elastic * excess;
+}
+// Open-side sentinels for one-sided numeric constraints (REQ-API-024 shipping slice, Motion parity):
+// only `min = -Infinity` and/or `max = +Infinity` mean "no bound on that side". Wrong-polarity
+// infinity (`min = +∞` or `max = -∞`) is illegal — it would make every release target Infinity and
+// start a non-converging spring (G-INV-8). Shared by applyConstraints + selectReleaseTarget so the
+// live clamp and the release seam never disagree on legality.
+export function assertLegalConstraintBounds(c, where = 'constraints') {
+    const minOk = Number.isFinite(c.min) || c.min === Number.NEGATIVE_INFINITY;
+    const maxOk = Number.isFinite(c.max) || c.max === Number.POSITIVE_INFINITY;
+    if (!minOk || !maxOk) {
+        throw new Error(`${where}: open-side sentinels must be min=-Infinity and/or max=+Infinity ` +
+            `(got min=${c.min}, max=${c.max}); wrong-polarity or NaN bounds are refused (G-INV-8, REQ-API-024).`);
+    }
+    if (c.min > c.max) {
+        throw new Error(`${where}: min (${c.min}) must be <= max (${c.max})`);
+    }
+}
+// Validate + apply drag constraints (REQ-GESTURE-015/016, G-INV-8). Inside `[min, max]`: pass through. Past a
+// bound: a hard clamp when elastic is 0/absent (`min ≤ value ≤ max`), else `bound ± e·excess` (rubber-band,
+// symmetric on both bounds). Open sides (legal ±Infinity) skip that side's clamp. Malformed config —
+// wrong-polarity sentinels, NaN bounds, `min > max`, or `elastic ∉ [0, 1]` — throws at the call site.
+export function applyConstraints(value, c) {
+    const elastic = c.elastic ?? 0;
+    assertLegalConstraintBounds(c, 'applyConstraints');
+    if (!Number.isFinite(elastic) || elastic < 0 || elastic > 1) {
+        throw new Error(`applyConstraints: elastic must be in [0, 1], got ${elastic}`);
+    }
+    if (Number.isFinite(c.max) && value > c.max)
+        return c.max + elasticTransfer(value - c.max, elastic);
+    if (Number.isFinite(c.min) && value < c.min)
+        return c.min - elasticTransfer(c.min - value, elastic);
+    return value;
+}

package/dist/gesture/handoffSession.cjs

@@ -0,0 +1,161 @@
+"use strict";
+// REQ-GESTURE-022 (FLAG 5a, specs/SPEC-GESTURE.md) — the DRIVER-INTEGRATED
+// handoff session. The M1 session (`session.ts`) runs its release spring on its own graph — the
+// deterministic M1 stand-in. The live public path may not: G-INV-9 puts gesture motion on the
+// worklet/UI-thread path, and REQ-DRIVER-003 makes the driver the integrator. This variant keeps
+// the SAME total state machine and per-event semantics (dead-zone REQ-GESTURE-011, clamp/elastic
+// REQ-GESTURE-015/-016, shared release-target selection REQ-GESTURE-016/-017) but `end`/`cancel`/
+// `fail` RETURN the `ReleaseHandoff` seed — discriminated by `curve`: the snap release and
+// cancel/fail seed the driver's velocity-seeded spring (REQ-DRIVER-023); the free-drag release
+// returns the two-phase inertia descriptor (REQ-GESTURE-023, R16) — and the machine goes
+// straight `active → idle`: the integrator owns settling.
+// A pure event fold — no graph, no clock, no spring; composes ONLY the exported seams the M1
+// session composes, so the semantics can never fork.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGestureHandoffSession = createGestureHandoffSession;
+const elastic_1 = require("./elastic.cjs");
+const projection_1 = require("./projection.cjs");
+function createGestureHandoffSession(options) {
+    // The CONSTRUCTED config is the baseline: a per-grab begin override replaces it for THAT
+    // grab only — an unoverridden later begin restores it (review minor 6; native-motion
+    // re-measures at every grab but never forgets the prop-level config).
+    const baseConstraints = options.constraints;
+    let constraints = baseConstraints;
+    const snap = options.snap;
+    const momentum = options.momentum !== false;
+    let state = 'idle';
+    let current = 0; // the constrained drag value while active; meaningless when idle (integrator-owned)
+    let grabValue = 0; // the value at the 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)
+    // P0 + (translation − activation), then hard-clamp / rubber-band (REQ-GESTURE-011/-015/-016).
+    // Delta-since-activation gives C0 across a non-zero activeOffset dead zone.
+    function applyTranslation(translation) {
+        const raw = grabValue + (translation - activationTranslation);
+        current = constraints === undefined ? raw : (0, elastic_1.applyConstraints)(raw, constraints);
+    }
+    function requireActive(entry) {
+        if (state !== 'active') {
+            throw new Error(`gesture: ${entry} in state '${state}' — begin() a gesture first`);
+        }
+    }
+    // Cancel and fail share one path (REQ-GESTURE-018): a zero-velocity return to the pre-grab value,
+    // handed to the integrator. The ORIGIN is the driver's LIVE value at this instant (`releaseOrigin`),
+    // symmetric to end() — starting the return spring from the finger-tracked `current` would rewind a
+    // contending declarative drift (REQ-DRIVER-026), a visible backward jump violating C0 (r11 major 31,
+    // G-INV-2). In the no-contention case releaseOrigin == current, so this is the pre-fix behavior. The
+    // recognizer cannot cancel after a successful end, so (unlike the M1 session) there is no settling-
+    // phase redirect to model here.
+    function cancelHandoff(entry, releaseOrigin) {
+        requireActive(entry);
+        const handoff = {
+            curve: 'spring',
+            from: releaseOrigin,
+            velocity: 0,
+            target: preGrabValue,
+        };
+        state = 'idle';
+        return handoff;
+    }
+    return {
+        begin(activationTranslation_, seed, beginOptions) {
+            if (state === 'active') {
+                throw new Error('gesture: begin() during an active gesture — end() or cancel() first');
+            }
+            // Per-grab constraints (REQ-GESTURE-028): the grab-time measured bounds replace the
+            // constructed config for THIS grab; an unoverridden begin restores the baseline.
+            constraints =
+                beginOptions !== undefined && 'constraints' in beginOptions
+                    ? beginOptions.constraints
+                    : baseConstraints;
+            grabValue = seed.value;
+            preGrabValue = seed.value;
+            current = seed.value;
+            activationTranslation = activationTranslation_;
+            state = 'active';
+        },
+        active(translation) {
+            requireActive('active()');
+            applyTranslation(translation);
+        },
+        end(platformVelocity, releaseOrigin) {
+            requireActive('end()');
+            // The REQ-GESTURE-010 typed refusal reads the RAW recognizer sample first — the momentum
+            // gate below may zero a FINITE velocity but must never launder a corrupt one into a
+            // silent 0 (R16 review minor 6).
+            const platform = (0, projection_1.normalizeVelocity)(platformVelocity);
+            // dragMomentum (REQ-GESTURE-027): false zeroes the release velocity BEFORE any projection —
+            // the pin's `velocity: dragMomentum ? v : 0` — so a momentumless release settles at the
+            // release point (inertia ideal = origin; snap selection = nearest-to-origin), never slides
+            // to a projected landing.
+            const velocity = momentum ? platform : 0;
+            // REQ-GESTURE-022 release-origin symmetry: the ORIGIN of the handoff is the driver's LIVE value
+            // at release (`releaseOrigin`), passed in by the wiring via REQ-DRIVER-025. It reflects any
+            // contending declarative drift on the axis (REQ-DRIVER-026), which the finger-tracked `current`
+            // does NOT — so the release decision reads the value the element actually reached. Resolve
+            // BEFORE the state transition so a malformed config fails loud and leaves the session active.
+            let handoff;
+            if (snap !== undefined) {
+                // Snap release stays the project-then-snap spring at this rung (R16 recorded residual).
+                handoff = {
+                    curve: 'spring',
+                    from: releaseOrigin,
+                    velocity,
+                    target: (0, projection_1.selectReleaseTarget)(releaseOrigin, velocity, constraints, snap),
+                };
+            }
+            else {
+                // Free-drag (REQ-GESTURE-023, R16): the pinned two-phase inertia generator owns the curve.
+                // The descriptor carries the UNCLAMPED ideal's mirror terminal (the ideal clamped into the
+                // constraints) plus the bounds themselves, so the integrator runs the decay with the
+                // boundary spring at the walls instead of a spring to a pre-clamped target. The mirror
+                // terminal is not the settle point: an out-of-bounds origin settles AT the violated bound
+                // via the t=0 latch, which can diverge from the clamped ideal — harmless, since the
+                // drivers commit the generator's own settle value (see the ReleaseHandoff contract).
+                const ideal = (0, projection_1.project)(releaseOrigin, velocity);
+                let terminal = ideal;
+                if (constraints !== undefined) {
+                    if (Number.isFinite(constraints.max) && terminal > constraints.max) {
+                        terminal = constraints.max;
+                    }
+                    if (Number.isFinite(constraints.min) && terminal < constraints.min) {
+                        terminal = constraints.min;
+                    }
+                }
+                handoff = {
+                    curve: 'inertia',
+                    from: releaseOrigin,
+                    velocity,
+                    target: terminal,
+                    ...(constraints === undefined ? {} : { min: constraints.min, max: constraints.max }),
+                };
+            }
+            state = 'idle';
+            return handoff;
+        },
+        cancel(releaseOrigin) {
+            return cancelHandoff('cancel()', releaseOrigin);
+        },
+        fail(releaseOrigin) {
+            return cancelHandoff('fail()', releaseOrigin);
+        },
+        updateConstraints(constraints_, value) {
+            requireActive('updateConstraints()');
+            constraints = constraints_;
+            // Re-anchor: shift the grab base by the rescale delta so the NEXT update's raw
+            // (grabValue + translation delta) continues FROM the rescaled value — the pin's
+            // originPoint += delta semantics exactly (C0, review major 3).
+            grabValue += value - current;
+            current = value;
+        },
+        value() {
+            // Outside an active drag the INTEGRATOR owns the value; a session read would be stale
+            // state masquerading as truth (the getter/mutator-skew class) — fail loud instead.
+            if (state !== 'active') {
+                throw new Error(`gesture: value() in state '${state}' — the integrator owns the value outside an active drag (REQ-GESTURE-022)`);
+            }
+            return current;
+        },
+        state: () => state,
+    };
+}

package/dist/gesture/handoffSession.d.cts

@@ -0,0 +1,35 @@
+import type { DragConstraints, SnapConfig } from "./types.cjs";
+export type ReleaseHandoff = {
+    readonly curve: 'spring';
+    readonly from: number;
+    readonly velocity: number;
+    readonly target: number;
+} | {
+    readonly curve: 'inertia';
+    readonly from: number;
+    readonly velocity: number;
+    readonly target: number;
+    readonly min?: number;
+    readonly max?: number;
+};
+export interface GestureHandoffSessionOptions {
+    readonly constraints?: DragConstraints;
+    readonly snap?: SnapConfig;
+    readonly momentum?: boolean;
+}
+export type GestureHandoffSessionState = 'idle' | 'active';
+export interface GestureHandoffSession {
+    begin(activationTranslation: number, seed: {
+        readonly value: number;
+    }, options?: {
+        readonly constraints?: DragConstraints;
+    }): void;
+    active(translation: number): void;
+    end(platformVelocity: number, releaseOrigin: number): ReleaseHandoff;
+    cancel(releaseOrigin: number): ReleaseHandoff;
+    fail(releaseOrigin: number): ReleaseHandoff;
+    updateConstraints(constraints: DragConstraints, value: number): void;
+    value(): number;
+    state(): GestureHandoffSessionState;
+}
+export declare function createGestureHandoffSession(options: GestureHandoffSessionOptions): GestureHandoffSession;

package/dist/gesture/handoffSession.d.ts

@@ -0,0 +1,35 @@
+import type { DragConstraints, SnapConfig } from "./types.js";
+export type ReleaseHandoff = {
+    readonly curve: 'spring';
+    readonly from: number;
+    readonly velocity: number;
+    readonly target: number;
+} | {
+    readonly curve: 'inertia';
+    readonly from: number;
+    readonly velocity: number;
+    readonly target: number;
+    readonly min?: number;
+    readonly max?: number;
+};
+export interface GestureHandoffSessionOptions {
+    readonly constraints?: DragConstraints;
+    readonly snap?: SnapConfig;
+    readonly momentum?: boolean;
+}
+export type GestureHandoffSessionState = 'idle' | 'active';
+export interface GestureHandoffSession {
+    begin(activationTranslation: number, seed: {
+        readonly value: number;
+    }, options?: {
+        readonly constraints?: DragConstraints;
+    }): void;
+    active(translation: number): void;
+    end(platformVelocity: number, releaseOrigin: number): ReleaseHandoff;
+    cancel(releaseOrigin: number): ReleaseHandoff;
+    fail(releaseOrigin: number): ReleaseHandoff;
+    updateConstraints(constraints: DragConstraints, value: number): void;
+    value(): number;
+    state(): GestureHandoffSessionState;
+}
+export declare function createGestureHandoffSession(options: GestureHandoffSessionOptions): GestureHandoffSession;

package/dist/gesture/handoffSession.js

@@ -0,0 +1,158 @@
+// REQ-GESTURE-022 (FLAG 5a, specs/SPEC-GESTURE.md) — the DRIVER-INTEGRATED
+// handoff session. The M1 session (`session.ts`) runs its release spring on its own graph — the
+// deterministic M1 stand-in. The live public path may not: G-INV-9 puts gesture motion on the
+// worklet/UI-thread path, and REQ-DRIVER-003 makes the driver the integrator. This variant keeps
+// the SAME total state machine and per-event semantics (dead-zone REQ-GESTURE-011, clamp/elastic
+// REQ-GESTURE-015/-016, shared release-target selection REQ-GESTURE-016/-017) but `end`/`cancel`/
+// `fail` RETURN the `ReleaseHandoff` seed — discriminated by `curve`: the snap release and
+// cancel/fail seed the driver's velocity-seeded spring (REQ-DRIVER-023); the free-drag release
+// returns the two-phase inertia descriptor (REQ-GESTURE-023, R16) — and the machine goes
+// straight `active → idle`: the integrator owns settling.
+// A pure event fold — no graph, no clock, no spring; composes ONLY the exported seams the M1
+// session composes, so the semantics can never fork.
+import { applyConstraints } from "./elastic.js";
+import { normalizeVelocity, project, selectReleaseTarget } from "./projection.js";
+export function createGestureHandoffSession(options) {
+    // The CONSTRUCTED config is the baseline: a per-grab begin override replaces it for THAT
+    // grab only — an unoverridden later begin restores it (review minor 6; native-motion
+    // re-measures at every grab but never forgets the prop-level config).
+    const baseConstraints = options.constraints;
+    let constraints = baseConstraints;
+    const snap = options.snap;
+    const momentum = options.momentum !== false;
+    let state = 'idle';
+    let current = 0; // the constrained drag value while active; meaningless when idle (integrator-owned)
+    let grabValue = 0; // the value at the 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)
+    // P0 + (translation − activation), then hard-clamp / rubber-band (REQ-GESTURE-011/-015/-016).
+    // Delta-since-activation gives C0 across a non-zero activeOffset dead zone.
+    function applyTranslation(translation) {
+        const raw = grabValue + (translation - activationTranslation);
+        current = constraints === undefined ? raw : applyConstraints(raw, constraints);
+    }
+    function requireActive(entry) {
+        if (state !== 'active') {
+            throw new Error(`gesture: ${entry} in state '${state}' — begin() a gesture first`);
+        }
+    }
+    // Cancel and fail share one path (REQ-GESTURE-018): a zero-velocity return to the pre-grab value,
+    // handed to the integrator. The ORIGIN is the driver's LIVE value at this instant (`releaseOrigin`),
+    // symmetric to end() — starting the return spring from the finger-tracked `current` would rewind a
+    // contending declarative drift (REQ-DRIVER-026), a visible backward jump violating C0 (r11 major 31,
+    // G-INV-2). In the no-contention case releaseOrigin == current, so this is the pre-fix behavior. The
+    // recognizer cannot cancel after a successful end, so (unlike the M1 session) there is no settling-
+    // phase redirect to model here.
+    function cancelHandoff(entry, releaseOrigin) {
+        requireActive(entry);
+        const handoff = {
+            curve: 'spring',
+            from: releaseOrigin,
+            velocity: 0,
+            target: preGrabValue,
+        };
+        state = 'idle';
+        return handoff;
+    }
+    return {
+        begin(activationTranslation_, seed, beginOptions) {
+            if (state === 'active') {
+                throw new Error('gesture: begin() during an active gesture — end() or cancel() first');
+            }
+            // Per-grab constraints (REQ-GESTURE-028): the grab-time measured bounds replace the
+            // constructed config for THIS grab; an unoverridden begin restores the baseline.
+            constraints =
+                beginOptions !== undefined && 'constraints' in beginOptions
+                    ? beginOptions.constraints
+                    : baseConstraints;
+            grabValue = seed.value;
+            preGrabValue = seed.value;
+            current = seed.value;
+            activationTranslation = activationTranslation_;
+            state = 'active';
+        },
+        active(translation) {
+            requireActive('active()');
+            applyTranslation(translation);
+        },
+        end(platformVelocity, releaseOrigin) {
+            requireActive('end()');
+            // The REQ-GESTURE-010 typed refusal reads the RAW recognizer sample first — the momentum
+            // gate below may zero a FINITE velocity but must never launder a corrupt one into a
+            // silent 0 (R16 review minor 6).
+            const platform = normalizeVelocity(platformVelocity);
+            // dragMomentum (REQ-GESTURE-027): false zeroes the release velocity BEFORE any projection —
+            // the pin's `velocity: dragMomentum ? v : 0` — so a momentumless release settles at the
+            // release point (inertia ideal = origin; snap selection = nearest-to-origin), never slides
+            // to a projected landing.
+            const velocity = momentum ? platform : 0;
+            // REQ-GESTURE-022 release-origin symmetry: the ORIGIN of the handoff is the driver's LIVE value
+            // at release (`releaseOrigin`), passed in by the wiring via REQ-DRIVER-025. It reflects any
+            // contending declarative drift on the axis (REQ-DRIVER-026), which the finger-tracked `current`
+            // does NOT — so the release decision reads the value the element actually reached. Resolve
+            // BEFORE the state transition so a malformed config fails loud and leaves the session active.
+            let handoff;
+            if (snap !== undefined) {
+                // Snap release stays the project-then-snap spring at this rung (R16 recorded residual).
+                handoff = {
+                    curve: 'spring',
+                    from: releaseOrigin,
+                    velocity,
+                    target: selectReleaseTarget(releaseOrigin, velocity, constraints, snap),
+                };
+            }
+            else {
+                // Free-drag (REQ-GESTURE-023, R16): the pinned two-phase inertia generator owns the curve.
+                // The descriptor carries the UNCLAMPED ideal's mirror terminal (the ideal clamped into the
+                // constraints) plus the bounds themselves, so the integrator runs the decay with the
+                // boundary spring at the walls instead of a spring to a pre-clamped target. The mirror
+                // terminal is not the settle point: an out-of-bounds origin settles AT the violated bound
+                // via the t=0 latch, which can diverge from the clamped ideal — harmless, since the
+                // drivers commit the generator's own settle value (see the ReleaseHandoff contract).
+                const ideal = project(releaseOrigin, velocity);
+                let terminal = ideal;
+                if (constraints !== undefined) {
+                    if (Number.isFinite(constraints.max) && terminal > constraints.max) {
+                        terminal = constraints.max;
+                    }
+                    if (Number.isFinite(constraints.min) && terminal < constraints.min) {
+                        terminal = constraints.min;
+                    }
+                }
+                handoff = {
+                    curve: 'inertia',
+                    from: releaseOrigin,
+                    velocity,
+                    target: terminal,
+                    ...(constraints === undefined ? {} : { min: constraints.min, max: constraints.max }),
+                };
+            }
+            state = 'idle';
+            return handoff;
+        },
+        cancel(releaseOrigin) {
+            return cancelHandoff('cancel()', releaseOrigin);
+        },
+        fail(releaseOrigin) {
+            return cancelHandoff('fail()', releaseOrigin);
+        },
+        updateConstraints(constraints_, value) {
+            requireActive('updateConstraints()');
+            constraints = constraints_;
+            // Re-anchor: shift the grab base by the rescale delta so the NEXT update's raw
+            // (grabValue + translation delta) continues FROM the rescaled value — the pin's
+            // originPoint += delta semantics exactly (C0, review major 3).
+            grabValue += value - current;
+            current = value;
+        },
+        value() {
+            // Outside an active drag the INTEGRATOR owns the value; a session read would be stale
+            // state masquerading as truth (the getter/mutator-skew class) — fail loud instead.
+            if (state !== 'active') {
+                throw new Error(`gesture: value() in state '${state}' — the integrator owns the value outside an active drag (REQ-GESTURE-022)`);
+            }
+            return current;
+        },
+        state: () => state,
+    };
+}

package/dist/gesture/index.cjs

@@ -0,0 +1,37 @@
+"use strict";
+// SPEC-GESTURE host-agnostic gesture subsystem (REQ-GESTURE-*): the pure gesture math (Milestone 1) — the
+// projection function, project-then-snap selection, velocity normalization, and constraint transfer. The
+// gesture SESSION (state machine + grab/release/cancel over the MotionGraph) joins here as it lands
+// (Milestones 2-4). Host-agnostic — no react/react-native/Gesture-Handler/driver import.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveViewportConstraints = exports.progressWithinSpan = exports.resolveDirectionLockAxis = exports.DIRECTION_LOCK_THRESHOLD_PX = exports.validateMeasureReplacementBox = exports.validateDragControlOptions = exports.resolvedDragAxes = exports.resolveDragConfig = exports.gateOrphanDragCallbacks = exports.dragConfigMountSignature = exports.describeValue = exports.DEFAULT_DRAG_ELASTIC = exports.createGestureHandoffSession = exports.GESTURE_RELEASE_SPRING = exports.createGestureSession = exports.applyConstraints = exports.elasticTransfer = exports.selectReleaseTarget = exports.absoluteDragOrigin = exports.normalizeVelocity = exports.selectSnap = exports.project = exports.PROJECTION_POWER = void 0;
+var projection_1 = require("./projection.cjs");
+Object.defineProperty(exports, "PROJECTION_POWER", { enumerable: true, get: function () { return projection_1.PROJECTION_POWER; } });
+Object.defineProperty(exports, "project", { enumerable: true, get: function () { return projection_1.project; } });
+Object.defineProperty(exports, "selectSnap", { enumerable: true, get: function () { return projection_1.selectSnap; } });
+Object.defineProperty(exports, "normalizeVelocity", { enumerable: true, get: function () { return projection_1.normalizeVelocity; } });
+Object.defineProperty(exports, "absoluteDragOrigin", { enumerable: true, get: function () { return projection_1.absoluteDragOrigin; } });
+Object.defineProperty(exports, "selectReleaseTarget", { enumerable: true, get: function () { return projection_1.selectReleaseTarget; } });
+var elastic_1 = require("./elastic.cjs");
+Object.defineProperty(exports, "elasticTransfer", { enumerable: true, get: function () { return elastic_1.elasticTransfer; } });
+Object.defineProperty(exports, "applyConstraints", { enumerable: true, get: function () { return elastic_1.applyConstraints; } });
+var session_1 = require("./session.cjs");
+Object.defineProperty(exports, "createGestureSession", { enumerable: true, get: function () { return session_1.createGestureSession; } });
+Object.defineProperty(exports, "GESTURE_RELEASE_SPRING", { enumerable: true, get: function () { return session_1.GESTURE_RELEASE_SPRING; } });
+var handoffSession_1 = require("./handoffSession.cjs");
+Object.defineProperty(exports, "createGestureHandoffSession", { enumerable: true, get: function () { return handoffSession_1.createGestureHandoffSession; } });
+var dragConfig_1 = require("./dragConfig.cjs");
+Object.defineProperty(exports, "DEFAULT_DRAG_ELASTIC", { enumerable: true, get: function () { return dragConfig_1.DEFAULT_DRAG_ELASTIC; } });
+Object.defineProperty(exports, "describeValue", { enumerable: true, get: function () { return dragConfig_1.describeValue; } });
+Object.defineProperty(exports, "dragConfigMountSignature", { enumerable: true, get: function () { return dragConfig_1.dragConfigMountSignature; } });
+Object.defineProperty(exports, "gateOrphanDragCallbacks", { enumerable: true, get: function () { return dragConfig_1.gateOrphanDragCallbacks; } });
+Object.defineProperty(exports, "resolveDragConfig", { enumerable: true, get: function () { return dragConfig_1.resolveDragConfig; } });
+Object.defineProperty(exports, "resolvedDragAxes", { enumerable: true, get: function () { return dragConfig_1.resolvedDragAxes; } });
+Object.defineProperty(exports, "validateDragControlOptions", { enumerable: true, get: function () { return dragConfig_1.validateDragControlOptions; } });
+Object.defineProperty(exports, "validateMeasureReplacementBox", { enumerable: true, get: function () { return dragConfig_1.validateMeasureReplacementBox; } });
+var directionLock_1 = require("./directionLock.cjs");
+Object.defineProperty(exports, "DIRECTION_LOCK_THRESHOLD_PX", { enumerable: true, get: function () { return directionLock_1.DIRECTION_LOCK_THRESHOLD_PX; } });
+Object.defineProperty(exports, "resolveDirectionLockAxis", { enumerable: true, get: function () { return directionLock_1.resolveDirectionLockAxis; } });
+var viewportConstraints_1 = require("./viewportConstraints.cjs");
+Object.defineProperty(exports, "progressWithinSpan", { enumerable: true, get: function () { return viewportConstraints_1.progressWithinSpan; } });
+Object.defineProperty(exports, "resolveViewportConstraints", { enumerable: true, get: function () { return viewportConstraints_1.resolveViewportConstraints; } });

package/dist/gesture/index.d.cts

@@ -0,0 +1,12 @@
+export type { GestureSample, DragConstraints, SnapConfig } from "./types.cjs";
+export { PROJECTION_POWER, project, selectSnap, normalizeVelocity, absoluteDragOrigin, selectReleaseTarget, } from "./projection.cjs";
+export { elasticTransfer, applyConstraints } from "./elastic.cjs";
+export type { GestureSession, GestureSessionOptions, GestureSessionState } from "./session.cjs";
+export { createGestureSession, GESTURE_RELEASE_SPRING } from "./session.cjs";
+export type { GestureHandoffSession, GestureHandoffSessionOptions, GestureHandoffSessionState, ReleaseHandoff, } from "./handoffSession.cjs";
+export { createGestureHandoffSession } from "./handoffSession.cjs";
+export type { DragAxis, DragCallback, DragConfigInput, DragConfigSeverity, DragConstraintsBoth, DragConstraintsInput, DragConstraintsRef, DragConstraintsX, DragConstraintsY, DragControlOptions, DragControlsHandle, DragInfo, DragProp, TapCallback, TapInfo, DragProps, DragSnapPointsInput, DragSnapPointsX, DragSnapPointsY, MeasuredDragConstraints, MeasureDragConstraintsCallback, ResolvedDragAxisConfig, ResolvedDragConfig, } from "./dragConfig.cjs";
+export { DEFAULT_DRAG_ELASTIC, describeValue, dragConfigMountSignature, gateOrphanDragCallbacks, resolveDragConfig, resolvedDragAxes, validateDragControlOptions, validateMeasureReplacementBox, } from "./dragConfig.cjs";
+export { DIRECTION_LOCK_THRESHOLD_PX, resolveDirectionLockAxis } from "./directionLock.cjs";
+export type { AxisSpan } from "./viewportConstraints.cjs";
+export { progressWithinSpan, resolveViewportConstraints } from "./viewportConstraints.cjs";

package/dist/gesture/index.d.ts

@@ -0,0 +1,12 @@
+export type { GestureSample, DragConstraints, SnapConfig } from "./types.js";
+export { PROJECTION_POWER, project, selectSnap, normalizeVelocity, absoluteDragOrigin, selectReleaseTarget, } from "./projection.js";
+export { elasticTransfer, applyConstraints } from "./elastic.js";
+export type { GestureSession, GestureSessionOptions, GestureSessionState } from "./session.js";
+export { createGestureSession, GESTURE_RELEASE_SPRING } from "./session.js";
+export type { GestureHandoffSession, GestureHandoffSessionOptions, GestureHandoffSessionState, ReleaseHandoff, } from "./handoffSession.js";
+export { createGestureHandoffSession } from "./handoffSession.js";
+export type { DragAxis, DragCallback, DragConfigInput, DragConfigSeverity, DragConstraintsBoth, DragConstraintsInput, DragConstraintsRef, DragConstraintsX, DragConstraintsY, DragControlOptions, DragControlsHandle, DragInfo, DragProp, TapCallback, TapInfo, DragProps, DragSnapPointsInput, DragSnapPointsX, DragSnapPointsY, MeasuredDragConstraints, MeasureDragConstraintsCallback, ResolvedDragAxisConfig, ResolvedDragConfig, } from "./dragConfig.js";
+export { DEFAULT_DRAG_ELASTIC, describeValue, dragConfigMountSignature, gateOrphanDragCallbacks, resolveDragConfig, resolvedDragAxes, validateDragControlOptions, validateMeasureReplacementBox, } from "./dragConfig.js";
+export { DIRECTION_LOCK_THRESHOLD_PX, resolveDirectionLockAxis } from "./directionLock.js";
+export type { AxisSpan } from "./viewportConstraints.js";
+export { progressWithinSpan, resolveViewportConstraints } from "./viewportConstraints.js";

package/dist/gesture/index.js

@@ -0,0 +1,11 @@
+// SPEC-GESTURE host-agnostic gesture subsystem (REQ-GESTURE-*): the pure gesture math (Milestone 1) — the
+// projection function, project-then-snap selection, velocity normalization, and constraint transfer. The
+// gesture SESSION (state machine + grab/release/cancel over the MotionGraph) joins here as it lands
+// (Milestones 2-4). Host-agnostic — no react/react-native/Gesture-Handler/driver import.
+export { PROJECTION_POWER, project, selectSnap, normalizeVelocity, absoluteDragOrigin, selectReleaseTarget, } from "./projection.js";
+export { elasticTransfer, applyConstraints } from "./elastic.js";
+export { createGestureSession, GESTURE_RELEASE_SPRING } from "./session.js";
+export { createGestureHandoffSession } from "./handoffSession.js";
+export { DEFAULT_DRAG_ELASTIC, describeValue, dragConfigMountSignature, gateOrphanDragCallbacks, resolveDragConfig, resolvedDragAxes, validateDragControlOptions, validateMeasureReplacementBox, } from "./dragConfig.js";
+export { DIRECTION_LOCK_THRESHOLD_PX, resolveDirectionLockAxis } from "./directionLock.js";
+export { progressWithinSpan, resolveViewportConstraints } from "./viewportConstraints.js";