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

package/dist/gesture/dragConfig.js

@@ -0,0 +1,624 @@
+// REQ-API-020/-021/-023 (FLAG 5a, specs/SPEC-GESTURE.md) — the drag prop
+// conversion boundary, SINGLE-SOURCED in core so both engines resolve identical accepted sets
+// (BRIEF "one API, one behavior" / "no forked logic"). Motion's public drag shapes
+// (`dragConstraints {left/right/top/bottom}`, `dragElastic`, `dragSnapPoints {x?/y?}`) convert to
+// core's gesture config here; every incompatible-but-valid shape is a TYPED refusal naming what
+// and why — never a silent ignore. Host-agnostic (REQ-CORE-003): no react/react-native/motion
+// import; the severity model is a plain policy enum + callback, adapted by each engine.
+//
+// Native uses the resolved `ResolvedDragConfig` to build the gesture session; the web engine
+// calls this for the VERDICT (identical accept/refuse) then passes Motion's own shapes through to
+// motion/react and maps `dragSnapPoints` to `dragTransition.modifyTarget` from the same points.
+// Adopted from the PINNED oracle, cited not hand-transcribed (BRIEF numeric-constants law):
+// framer-motion/src/gestures/drag/utils/constraints.ts:195 `export const defaultElastic = 0.35`
+// (motion@12.42.2, source SHA 61833240). Applies when dragConstraints are present and
+// dragElastic is omitted — Motion's own default, so omitted-elastic behaves identically on both
+// engines.
+export const DEFAULT_DRAG_ELASTIC = 0.35;
+// The hook's replacement box is a boundary INPUT, validated identically on both engines
+// (review r7 majors 3): complete — all four sides present numbers; legal — never NaN,
+// infinities only with the correct polarity (the constraint legality vocabulary, G-INV-8);
+// ordered per axis. A malformed replacement is a typed refusal — severity-adapted by the
+// caller (native: the grab/poll report channel; web: the forwarded wrapper, which drops the
+// replacement in production).
+export function validateMeasureReplacementBox(replaced) {
+    // TOTAL (review r8 minor 5): a non-object truthy return (number, boolean, string — outside
+    // the declared box shape) is the same typed refusal, never a raw property-access TypeError.
+    // (Falsy returns — undefined/null/false — are the pin's no-op: `!!userConstraints`.)
+    if (typeof replaced !== 'object' || replaced === null) {
+        throw new Error(`onMeasureDragConstraints must return a complete { top, left, bottom, right } box of ` +
+            `finite numbers — got ${describeValue(replaced)} (REQ-API-042, G-INV-8).`);
+    }
+    const side = (name, value, polarity) => {
+        if (typeof value !== 'number' ||
+            Number.isNaN(value) ||
+            (!Number.isFinite(value) && value !== polarity * Number.POSITIVE_INFINITY)) {
+            throw new Error(`onMeasureDragConstraints must return a complete { top, left, bottom, right } box of ` +
+                `finite numbers (an open ${name} side only as ` +
+                `${polarity === -1 ? '-Infinity' : '+Infinity'}) — got ${name}: ` +
+                `${describeValue(value)} (REQ-API-042).`);
+        }
+        return value;
+    };
+    const left = side('left', replaced.left, -1);
+    const right = side('right', replaced.right, 1);
+    const top = side('top', replaced.top, -1);
+    const bottom = side('bottom', replaced.bottom, 1);
+    if (left > right || top > bottom) {
+        throw new Error(`onMeasureDragConstraints returned inverted bounds (left ${left} > right ${right} or ` +
+            `top ${top} > bottom ${bottom}) — an inverted box is a malformed replacement, refused ` +
+            '(REQ-API-042, G-INV-8).');
+    }
+    return { top, left, bottom, right };
+}
+const DRAG_CONTROL_OPTION_KEYS = new Set(['distanceThreshold', 'snapToCursor']);
+/**
+ * Runtime-validate DragControls.start options (G-INV-8; seal review r6/r7/r8).
+ * Shared by native and web so both engines refuse malformed options identically.
+ * Omitted options stay undefined (pin defaults at the session); present keys must match shape.
+ * Closed plain-object shape only — unknown keys and non-plain objects refuse loud.
+ */
+export function validateDragControlOptions(options) {
+    if (options === undefined)
+        return undefined;
+    if (typeof options !== 'object' ||
+        options === null ||
+        Array.isArray(options) ||
+        Object.getPrototypeOf(options) !== Object.prototype) {
+        throw new Error(`DragControls.start options must be a plain object, got ${describeValue(options)} ` +
+            '(REQ-GESTURE-026; G-INV-8).');
+    }
+    const record = options;
+    // ONE ownKeys snapshot (seal review r10 major): never call getOwnPropertyNames and
+    // getOwnPropertySymbols separately — a Proxy can change between the two reads.
+    const ownKeys = Reflect.ownKeys(record);
+    for (const key of ownKeys) {
+        if (typeof key === 'symbol') {
+            throw new Error(`DragControls.start options: symbol keys are not accepted (REQ-GESTURE-026; G-INV-8).`);
+        }
+        if (!DRAG_CONTROL_OPTION_KEYS.has(key)) {
+            throw new Error(`DragControls.start options: unknown key '${key}' — only distanceThreshold and ` +
+                `snapToCursor are accepted (REQ-GESTURE-026; G-INV-8).`);
+        }
+    }
+    // ONE snapshot per key (seal review r9 major): never re-read an accessor that can change.
+    const out = {};
+    if (Object.prototype.hasOwnProperty.call(record, 'distanceThreshold')) {
+        const value = record.distanceThreshold;
+        if (value !== undefined) {
+            if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) {
+                throw new Error(`DragControls.start distanceThreshold must be a finite non-negative number, got ` +
+                    `${describeValue(value)} (REQ-GESTURE-026; G-INV-8).`);
+            }
+            out.distanceThreshold = value;
+        }
+    }
+    if (Object.prototype.hasOwnProperty.call(record, 'snapToCursor')) {
+        const value = record.snapToCursor;
+        if (value !== undefined) {
+            if (typeof value !== 'boolean') {
+                throw new Error(`DragControls.start snapToCursor must be a boolean, got ` +
+                    `${describeValue(value)} (REQ-GESTURE-026; G-INV-8).`);
+            }
+            out.snapToCursor = value;
+        }
+    }
+    return out;
+}
+// The dragged axes in recognizer-field order (deterministic for every consumer loop).
+export function resolvedDragAxes(config) {
+    return ['x', 'y'].filter((axis) => config[axis] !== undefined);
+}
+// The fixed-at-mount comparison signature (REQ-API-016, shared by BOTH engines so the verdict
+// is identical by construction): the resolved config canonicalized for STABLE equality. The
+// element-ref channel (REQ-API-042) contributes the ref OBJECT'S identity via a process-local
+// token, never its payload — `.current` is a live host element (a DOM node on web: circular
+// under JSON.stringify; a host component ref on device), and the measured box re-resolves per
+// grab regardless (REQ-GESTURE-028). Passing the same ref object every render (the universal
+// useRef pattern) is a NO-OP; swapping the ref object IS a config change → the refusal fires.
+const refIdentityTokens = new WeakMap();
+let nextRefIdentityToken = 0;
+function refIdentityToken(ref) {
+    const existing = refIdentityTokens.get(ref);
+    if (existing !== undefined)
+        return existing;
+    const token = (nextRefIdentityToken += 1);
+    refIdentityTokens.set(ref, token);
+    return token;
+}
+export function dragConfigMountSignature(config) {
+    if (config === null)
+        return 'null';
+    const axis = (axisConfig) => axisConfig === undefined
+        ? undefined
+        : {
+            ...(axisConfig.constraints === undefined ? {} : { constraints: axisConfig.constraints }),
+            ...(axisConfig.snap === undefined ? {} : { snap: axisConfig.snap }),
+            ...(axisConfig.constraintsRef === undefined
+                ? {}
+                : {
+                    constraintsRef: {
+                        ref: refIdentityToken(axisConfig.constraintsRef.ref),
+                        elastic: axisConfig.constraintsRef.elastic,
+                    },
+                }),
+        };
+    return JSON.stringify({
+        ...(config.x === undefined ? {} : { x: axis(config.x) }),
+        ...(config.y === undefined ? {} : { y: axis(config.y) }),
+        dragPropagation: config.dragPropagation,
+        dragListener: config.dragListener,
+        dragControlsToken: config.dragControlsToken,
+        dragDirectionLock: config.dragDirectionLock,
+        dragMomentum: config.dragMomentum,
+        dragTransition: config.dragTransition,
+        dragSnapToOrigin: config.dragSnapToOrigin,
+    });
+}
+function describeShape(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'an array';
+    return typeof value;
+}
+// A SAFE value formatter for typed error messages (review minor): the inputs are `unknown`, so
+// `JSON.stringify` would THROW on a BigInt (and drop `undefined`/functions/symbols) — a raw
+// serialization TypeError instead of the typed drag error naming the property. This never throws:
+// primitives stringify directly, BigInt gets an `n` suffix, everything else falls back to the shape.
+// Exported (review r4 minor 844ee5e) so the native drag wiring + handoff binding format recognizer
+// fields through this ONE safe formatter — no duplicated JSON.stringify that a BigInt field crashes.
+export function describeValue(value) {
+    // TOTAL even for hostile objects (M3 r2 major 830433fc74f2): the SHAPE probe itself can
+    // throw — including an Error's hostile `message` getter or Array.isArray on a REVOKED PROXY
+    // — and a throwing formatter turns every typed refusal built over it into a raw crash with
+    // zero reports. The catch is the formatter's totality contract, not error suppression: the
+    // refusal that carries this description is the loud path.
+    try {
+        const t = typeof value;
+        if (t === 'bigint')
+            return `${String(value)}n`;
+        if (t === 'string')
+            return `"${String(value)}"`;
+        if (t === 'number' || t === 'boolean' || t === 'undefined' || t === 'symbol')
+            return String(value);
+        if (value instanceof Error)
+            return value.message;
+        return describeShape(value);
+    }
+    catch {
+        return 'an unreadable object (a revoked proxy or a throwing probe trap)';
+    }
+}
+// Motion's constraint keys per axis: the drag value is a single axis, so exactly that axis's
+// bound pair applies; the other pair is an axis-inconsistent config (REQ-API-021), refused.
+const AXIS_BOUNDS = {
+    x: { lower: 'left', upper: 'right' },
+    y: { lower: 'top', upper: 'bottom' },
+};
+function requireFiniteBound(value, key) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`dragConstraints.${key} must be a finite number, got ${describeValue(value)} (REQ-API-021).`);
+    }
+    return value;
+}
+// Motion's dragElastic: number in [0, 1]; R15 D5 also ships boolean (true → pin 0.35, false → 0).
+// Per-side object form stays deferred until a demand case. Omitted = pinned oracle default (0.35).
+function resolveElastic(elastic) {
+    if (elastic === undefined)
+        return DEFAULT_DRAG_ELASTIC;
+    // R15 D5 (REQ-API-045): bare true/false are the pin's boolean forms.
+    if (elastic === true)
+        return DEFAULT_DRAG_ELASTIC;
+    if (elastic === false)
+        return 0;
+    if (typeof elastic !== 'number') {
+        throw new Error(`dragElastic ${describeShape(elastic)} forms (per-side object) are deferred — ` +
+            'a number in [0, 1] or boolean is the D5 shape (REQ-API-045).');
+    }
+    if (!Number.isFinite(elastic) || elastic < 0 || elastic > 1) {
+        throw new Error(`dragElastic must be in [0, 1], got ${elastic} (REQ-API-021).`);
+    }
+    return elastic;
+}
+// The constraints record shape checks shared by every drag form (review major: a typo like
+// `typoBound` must fail loud, never be an accepted-but-ignored config — REQ-API-013/-015,
+// G-INV-8). The numeric form accepts only the four bound keys; the ref form is recognized
+// structurally by `current` and may carry unrelated metadata (review r9 minor 2), never a
+// bound key. Single-axis resolution catches the wrong-axis pair below with a more specific
+// message.
+function requireConstraintsRecord(constraints) {
+    if (typeof constraints !== 'object' || constraints === null || Array.isArray(constraints)) {
+        throw new Error(`dragConstraints must be a { left/right/top/bottom } object or an element ref ({ current }), got ${describeShape(constraints)} (REQ-API-020/-042).`);
+    }
+    const record = constraints;
+    const keys = Object.keys(record);
+    if ('current' in record) {
+        // REQ-API-042 (R15 D2): the element-ref form ships — recognized STRUCTURALLY by `current`
+        // (upstream Motion's isRefObject). The exclusivity law prohibits mixing `current` with
+        // NUMERIC BOUNDS (left/right/top/bottom) — never merged into one config (fail-loud,
+        // REQ-API-015); unrelated ref metadata rides along ignored (review r9 minor 2 — upstream
+        // recognizes a ref by `current` alone, so a metadata-carrying ref is valid input).
+        for (const key of keys) {
+            if (key === 'left' || key === 'right' || key === 'top' || key === 'bottom') {
+                throw new Error("dragConstraints with 'current' is the element-ref form — it never merges with numeric " +
+                    `bounds (got '${key}' alongside); pass either a ref ({ current }) or { left/right/top/bottom } (REQ-API-042).`);
+            }
+        }
+        return record;
+    }
+    for (const key of keys) {
+        if (key !== 'left' && key !== 'right' && key !== 'top' && key !== 'bottom') {
+            throw new Error(`dragConstraints has an unknown key '${key}' — only { left, right, top, bottom } or an ` +
+                'element ref ({ current }) are valid (REQ-API-015/-042); an unrecognized bound is a typo, refused not ignored.');
+        }
+    }
+    return record;
+}
+// Narrow a validated constraints record to the element-ref form (REQ-API-042): `requireConstraintsRecord`
+// already refused any numeric bound key alongside `current`, so the presence check IS the
+// discrimination (unrelated metadata is tolerated — review r9 minor 2). The resolved config
+// carries this object BY IDENTITY — the grab-time measure reads `.current` lazily
+// (native-motion's per-grab measure channel); a re-wrap would freeze the pre-commit null.
+function isConstraintsRefRecord(record) {
+    return 'current' in record;
+}
+// Resolve one axis's bound pair to core's `DragConstraints {min, max, elastic}`. Presence =
+// defined value, not `key in record` (exactOptionalPropertyTypes + Motion parity):
+// `{ left: 0, right: undefined }` is a legal public shape meaning "right omitted / open upper".
+// One-sided numeric form (REQ-API-024 shipping slice): open side is ±Infinity so
+// applyConstraints skips that side. Authored bounds still require finite numbers.
+function resolveAxisBounds(axis, lowerRaw, upperRaw, elastic) {
+    const bounds = AXIS_BOUNDS[axis];
+    const hasLower = lowerRaw !== undefined;
+    const hasUpper = upperRaw !== undefined;
+    const min = hasLower ? requireFiniteBound(lowerRaw, bounds.lower) : Number.NEGATIVE_INFINITY;
+    const max = hasUpper ? requireFiniteBound(upperRaw, bounds.upper) : Number.POSITIVE_INFINITY;
+    if (hasLower && hasUpper && min > max) {
+        throw new Error(`dragConstraints.${bounds.lower} (${min}) must be <= dragConstraints.${bounds.upper} (${max}) (REQ-API-021).`);
+    }
+    return { min, max, elastic: resolveElastic(elastic) };
+}
+// Convert Motion's `dragConstraints {left/right/top/bottom}` + `dragElastic` to core's
+// `DragConstraints {min, max, elastic}` for the declared axis.
+function resolveConstraints(axis, constraints, elastic) {
+    const record = requireConstraintsRecord(constraints);
+    const bounds = AXIS_BOUNDS[axis];
+    const other = AXIS_BOUNDS[axis === 'x' ? 'y' : 'x'];
+    // Same defined-value presence as open-side omission (review major 4ec3a607f2bd): public types
+    // mark cross-axis keys as `?: undefined`, so `{ left: 0, top: undefined }` is a legal pass-through
+    // shape. `key in record` would refuse it; only a DEFINED off-axis number is inconsistent.
+    if (record[other.lower] !== undefined || record[other.upper] !== undefined) {
+        throw new Error(`dragConstraints declares ${other.lower}/${other.upper} but drag is '${axis}' — bounds for ` +
+            'a non-dragged axis are inconsistent with the declared axis and are refused, never ' +
+            'ignored (REQ-API-021).');
+    }
+    const lowerRaw = record[bounds.lower];
+    const upperRaw = record[bounds.upper];
+    if (lowerRaw === undefined && upperRaw === undefined) {
+        throw new Error(`dragConstraints declares no bound for axis '${axis}' — expected ${bounds.lower} and/or ` +
+            `${bounds.upper} (REQ-API-020; one-sided numeric form ships).`);
+    }
+    return resolveAxisBounds(axis, lowerRaw, upperRaw, elastic);
+}
+// R15 D1 (REQ-API-041 / REQ-GESTURE-024): both-axes constraints — every bound key is legal and
+// each axis resolves independently; an axis with no defined bound drags free (no channel entry).
+function resolveBothAxesConstraints(constraints, elastic) {
+    const record = requireConstraintsRecord(constraints);
+    // ONE read per bound, captured before presence checks AND resolution (review round-12 major):
+    // an accessor-backed bound must be checked and resolved from the SAME snapshot.
+    const left = record['left'];
+    const right = record['right'];
+    const top = record['top'];
+    const bottom = record['bottom'];
+    const hasX = left !== undefined || right !== undefined;
+    const hasY = top !== undefined || bottom !== undefined;
+    if (!hasX && !hasY) {
+        throw new Error('dragConstraints declares no bound for either axis — expected at least one of ' +
+            'left/right/top/bottom (REQ-API-020/-041; one-sided numeric form ships).');
+    }
+    return {
+        ...(hasX ? { x: resolveAxisBounds('x', left, right, elastic) } : {}),
+        ...(hasY ? { y: resolveAxisBounds('y', top, bottom, elastic) } : {}),
+    };
+}
+// dragSnapPoints — the ratified Native-Motion extension: ABSOLUTE positions, one array per axis.
+function resolveSnap(axis, snap) {
+    if (typeof snap !== 'object' || snap === null || Array.isArray(snap)) {
+        throw new Error(`dragSnapPoints must be an object with per-axis arrays ({x?, y?}), got ${describeShape(snap)} (REQ-API-020).`);
+    }
+    const record = snap;
+    // Reject UNKNOWN keys (review major): a typo like `typoAxis` must fail loud, never be an
+    // accepted-but-ignored config (REQ-API-013/-015, G-INV-8). Only `x`/`y` are valid axes.
+    for (const key of Object.keys(record)) {
+        if (key !== 'x' && key !== 'y') {
+            throw new Error(`dragSnapPoints has an unknown key '${key}' — only per-axis arrays { x?, y? } are valid ` +
+                '(REQ-API-015); an unrecognized axis is a typo, refused not ignored.');
+        }
+    }
+    const declaredAxes = ['x', 'y'].filter((key) => record[key] !== undefined);
+    if (declaredAxes.length === 0) {
+        throw new Error('dragSnapPoints declares no axis — expected absolute snap positions under x and/or y (REQ-API-020).');
+    }
+    const offAxis = declaredAxes.find((key) => key !== axis);
+    if (offAxis !== undefined) {
+        throw new Error(`dragSnapPoints.${offAxis} is declared but drag is '${axis}' — snap points for a ` +
+            'non-dragged axis are refused, never ignored (REQ-API-021).');
+    }
+    const points = record[axis];
+    if (!Array.isArray(points)) {
+        throw new Error(`dragSnapPoints.${axis} must be an array of finite numbers, got ${describeShape(points)} (REQ-API-020).`);
+    }
+    if (points.length === 0) {
+        throw new Error(`dragSnapPoints.${axis} must declare at least one snap point (REQ-API-020).`);
+    }
+    for (const point of points) {
+        if (typeof point !== 'number' || !Number.isFinite(point)) {
+            // describeValue (safe) not String() (review r5 major 21): String(Object.create(null)) throws
+            // a raw "No default value" TypeError; the typed error must name the field for any bad member.
+            throw new Error(`dragSnapPoints.${axis} must contain only finite numbers, got ${describeValue(point)} (REQ-API-020).`);
+        }
+    }
+    // SNAPSHOT the points (review r8 major 25): return a COPY, never the caller's array by reference.
+    // The resolved config is retained as the fixed-at-mount config and compared against re-resolves; an
+    // aliased array would let a later in-place mutation change the "mounted" config too (comparison
+    // bypassed → dynamic gestures silently enable, post-mount out-of-constraints validation bypassed, and
+    // native — which drives the gesture session off this array — diverges from web). One copy at the
+    // boundary makes every downstream holder independent of the caller.
+    return { points: [...points] };
+}
+// The measure hook requires the element-ref constraints form (R15 D2 review r3 major 1): the
+// pin fires it only inside resolveRefConstraints — with numeric or absent constraints it would
+// be a silently dead callback (G-INV-8). Called after constraints resolution in every drag
+// branch; the function SHAPE stays entry-gated (a malformed callback drops there).
+function requireMeasureHookHasRefConstraints(onMeasureDragConstraints, constraintsRef) {
+    if (onMeasureDragConstraints !== undefined && constraintsRef === undefined) {
+        throw new Error('onMeasureDragConstraints requires an element-ref dragConstraints ({ current }) — the pin ' +
+            'fires the measure hook only inside resolveRefConstraints; with numeric or absent ' +
+            'constraints it would be a silently dead callback (REQ-API-042, G-INV-8).');
+    }
+}
+function isDragControlsHandle(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const hub = value;
+    // subscribe is required: web motion.div and native MotionView both subscribe; a structural
+    // start/cancel/stop-only object is not a hub (seal review r8 major — shared parity).
+    return (typeof hub['start'] === 'function' &&
+        typeof hub['cancel'] === 'function' &&
+        typeof hub['stop'] === 'function' &&
+        typeof hub['subscribe'] === 'function');
+}
+function resolveOrThrow(input) {
+    // ONE read per member, captured at the boundary (reviews round-8 / round-11): a mutating
+    // getter must validate and resolve the SAME snapshot — never two reads that can disagree.
+    const { drag, dragConstraints, dragElastic, dragSnapPoints, dragPropagation, onMeasureDragConstraints, dragControls, dragListener, dragDirectionLock, dragMomentum, dragTransition, dragSnapToOrigin, } = input;
+    if (drag === undefined) {
+        // Config without the capability is refused, never ignored.
+        const orphan = dragConstraints !== undefined
+            ? 'dragConstraints'
+            : dragElastic !== undefined
+                ? 'dragElastic'
+                : dragSnapPoints !== undefined
+                    ? 'dragSnapPoints'
+                    : onMeasureDragConstraints !== undefined
+                        ? 'onMeasureDragConstraints'
+                        : dragControls !== undefined
+                            ? 'dragControls'
+                            : dragListener !== undefined
+                                ? 'dragListener'
+                                : dragDirectionLock !== undefined
+                                    ? 'dragDirectionLock'
+                                    : dragMomentum !== undefined
+                                        ? 'dragMomentum'
+                                        : dragTransition !== undefined
+                                            ? 'dragTransition'
+                                            : dragSnapToOrigin !== undefined
+                                                ? 'dragSnapToOrigin'
+                                                : 'dragPropagation';
+        throw new Error(`${orphan} requires drag to be 'x', 'y', or true (REQ-API-021).`);
+    }
+    if (dragPropagation !== undefined && typeof dragPropagation !== 'boolean') {
+        throw new Error(`dragPropagation must be a boolean, got ${describeValue(dragPropagation)} (REQ-API-021).`);
+    }
+    // R15 D3 (REQ-API-043 / G-INV-8): shared severity boundary — never accept-but-inert.
+    if (dragListener !== undefined && typeof dragListener !== 'boolean') {
+        throw new Error(`dragListener must be a boolean, got ${describeValue(dragListener)} (REQ-API-043).`);
+    }
+    if (dragControls !== undefined && !isDragControlsHandle(dragControls)) {
+        throw new Error(`dragControls must be a DragControls hub (start/cancel/stop/subscribe), got ${describeValue(dragControls)} (REQ-API-043).`);
+    }
+    // R15 D4 (REQ-API-044): direction lock is boolean; omitted === false.
+    if (dragDirectionLock !== undefined && typeof dragDirectionLock !== 'boolean') {
+        throw new Error(`dragDirectionLock must be a boolean, got ${describeValue(dragDirectionLock)} (REQ-API-044).`);
+    }
+    // R15 D5 (REQ-API-045): release physics props.
+    if (dragMomentum !== undefined && typeof dragMomentum !== 'boolean') {
+        throw new Error(`dragMomentum must be a boolean, got ${describeValue(dragMomentum)} (REQ-API-045).`);
+    }
+    if (dragSnapToOrigin !== undefined &&
+        dragSnapToOrigin !== true &&
+        dragSnapToOrigin !== false &&
+        dragSnapToOrigin !== 'x' &&
+        dragSnapToOrigin !== 'y') {
+        throw new Error(`dragSnapToOrigin must be boolean | 'x' | 'y', got ${describeValue(dragSnapToOrigin)} (REQ-API-045).`);
+    }
+    let resolvedDragTransition = null;
+    if (dragTransition !== undefined) {
+        if (dragTransition === null ||
+            typeof dragTransition !== 'object' ||
+            Array.isArray(dragTransition)) {
+            throw new Error(`dragTransition must be an object with bounceStiffness/bounceDamping numbers, got ${describeValue(dragTransition)} (REQ-API-045).`);
+        }
+        const t = dragTransition;
+        // Allowlist only bounce fields (seal H3): unknown keys refuse, never silent strip (G-INV-8).
+        for (const key of Object.keys(t)) {
+            if (key !== 'bounceStiffness' && key !== 'bounceDamping') {
+                throw new Error(`dragTransition unknown key '${key}' — only bounceStiffness/bounceDamping ship at D5; ` +
+                    'other InertiaOptions stay deferred (REQ-API-045 / G-INV-8).');
+            }
+        }
+        if (t.bounceStiffness !== undefined && typeof t.bounceStiffness !== 'number') {
+            throw new Error(`dragTransition.bounceStiffness must be a number, got ${describeValue(t.bounceStiffness)} (REQ-API-045).`);
+        }
+        if (t.bounceDamping !== undefined && typeof t.bounceDamping !== 'number') {
+            throw new Error(`dragTransition.bounceDamping must be a number, got ${describeValue(t.bounceDamping)} (REQ-API-045).`);
+        }
+        if ((typeof t.bounceStiffness === 'number' && !Number.isFinite(t.bounceStiffness)) ||
+            (typeof t.bounceDamping === 'number' && !Number.isFinite(t.bounceDamping))) {
+            throw new Error(`dragTransition bounceStiffness/bounceDamping must be finite numbers (REQ-API-045).`);
+        }
+        // R16 review minor 7: the bounce pair names the inertia generator's boundary spring
+        // (REQ-GESTURE-027). The pin accepts 0, but core's solver degenerates on a non-positive pair
+        // (a silent NaN trajectory on the external channel, a late release-time throw on the host
+        // path) — refuse it HERE, at mount, the fail-loud altitude (a tightening, not a parity break).
+        if ((typeof t.bounceStiffness === 'number' && t.bounceStiffness <= 0) ||
+            (typeof t.bounceDamping === 'number' && t.bounceDamping <= 0)) {
+            throw new Error(`dragTransition bounceStiffness/bounceDamping must be greater than zero, got ` +
+                `bounceStiffness=${describeValue(t.bounceStiffness)} bounceDamping=${describeValue(t.bounceDamping)} (REQ-API-045).`);
+        }
+        resolvedDragTransition = {
+            ...(typeof t.bounceStiffness === 'number' ? { bounceStiffness: t.bounceStiffness } : {}),
+            ...(typeof t.bounceDamping === 'number' ? { bounceDamping: t.bounceDamping } : {}),
+        };
+    }
+    // Canonicalize omission vs the explicit default (review round-3 minor): omitted and
+    // `dragPropagation={false}` are the SAME configuration — the fixed-at-mount comparison must
+    // never split them (the dragElastic default-normalization precedent).
+    // R15 D3: dragListener default true (pin); dragControls identity via WeakMap token.
+    // R15 D4: dragDirectionLock default false.
+    // R15 D5: dragMomentum default true (pin); dragSnapToOrigin default false; dragTransition null.
+    const hubFields = {
+        dragPropagation: dragPropagation === true,
+        dragListener: dragListener !== false,
+        dragControlsToken: dragControls !== undefined && typeof dragControls === 'object' && dragControls !== null
+            ? refIdentityToken(dragControls)
+            : null,
+        dragDirectionLock: dragDirectionLock === true,
+        dragMomentum: dragMomentum !== false,
+        dragTransition: resolvedDragTransition,
+        dragSnapToOrigin: dragSnapToOrigin === true || dragSnapToOrigin === 'x' || dragSnapToOrigin === 'y'
+            ? dragSnapToOrigin
+            : false,
+    };
+    if (dragElastic !== undefined) {
+        // Validate even when constraints are absent (U7f no-op uses the value only if
+        // constraints exist). Out-of-range / per-side object still refuse.
+        resolveElastic(dragElastic);
+    }
+    if (drag === false) {
+        return hubFields;
+    }
+    if (drag === true) {
+        // R15 D1 (REQ-API-041): both-axes drag ships. Snap stays refused with it: the web mapping
+        // projects release targets through Motion's single axis-blind modifyTarget (REQ-WEB-013),
+        // which per-axis snap sets cannot pass faithfully — a recorded fidelity divergence deferred
+        // to its own rung, identical on both engines by construction (this single verdict).
+        if (dragSnapPoints !== undefined) {
+            throw new Error('dragSnapPoints with both-axes drag (drag={true}) is deferred — the release ' +
+                "projection routes through Motion's single axis-blind modifyTarget, which cannot " +
+                'express per-axis snap sets faithfully (REQ-WEB-013; recorded fidelity divergence, ' +
+                'its own rung).');
+        }
+        const constraintsRecord = dragConstraints !== undefined ? requireConstraintsRecord(dragConstraints) : undefined;
+        const constraintsRef = constraintsRecord !== undefined && isConstraintsRefRecord(constraintsRecord)
+            ? { ref: constraintsRecord, elastic: resolveElastic(dragElastic) }
+            : undefined;
+        const both = constraintsRecord !== undefined && constraintsRef === undefined
+            ? resolveBothAxesConstraints(constraintsRecord, dragElastic)
+            : undefined;
+        requireMeasureHookHasRefConstraints(onMeasureDragConstraints, constraintsRef);
+        return {
+            x: constraintsRef !== undefined
+                ? { constraintsRef }
+                : both?.x === undefined
+                    ? {}
+                    : { constraints: both.x },
+            y: constraintsRef !== undefined
+                ? { constraintsRef }
+                : both?.y === undefined
+                    ? {}
+                    : { constraints: both.y },
+            ...hubFields,
+        };
+    }
+    if (drag !== 'x' && drag !== 'y') {
+        throw new Error(`drag must be 'x', 'y', true, or false, got ${describeValue(drag)} (REQ-API-020/-023).`);
+    }
+    const constraintsRecord = dragConstraints !== undefined ? requireConstraintsRecord(dragConstraints) : undefined;
+    const constraintsRef = constraintsRecord !== undefined && isConstraintsRefRecord(constraintsRecord)
+        ? { ref: constraintsRecord, elastic: resolveElastic(dragElastic) }
+        : undefined;
+    // Ref + snap is REFUSED identically on both engines (review r7 major 2): the pin's web
+    // engine applies its axis-blind modifyTarget with NO measurement-time bounds check, while
+    // native's law is the typed grab-time contradiction refusal (r5 major 20) — the two engines
+    // cannot validate the combination identically, so both refuse it at resolve (recorded
+    // fidelity divergence, its own rung — the both-axes snap precedent). The wiring keeps a
+    // grab-time snap-vs-measured check as the deep defense for host-constructed configs.
+    if (constraintsRef !== undefined && dragSnapPoints !== undefined) {
+        throw new Error("dragSnapPoints with element-ref dragConstraints is deferred — the pin's web engine " +
+            'applies its axis-blind modifyTarget with no measurement-time bounds check, so the ' +
+            'snap-vs-bounds contradiction law cannot run identically on both engines; the ' +
+            'combination is refused on BOTH (recorded fidelity divergence, its own rung).');
+    }
+    const constraints = constraintsRecord !== undefined && constraintsRef === undefined
+        ? resolveConstraints(drag, constraintsRecord, dragElastic)
+        : undefined;
+    requireMeasureHookHasRefConstraints(onMeasureDragConstraints, constraintsRef);
+    // Free-drag (REQ-GESTURE-023): snap is optional. When present, resolve axis/shape; when absent,
+    // release uses projected landing (optionally constrained). Empty/wrong-axis snap still fails in
+    // resolveSnap.
+    const snap = dragSnapPoints !== undefined ? resolveSnap(drag, dragSnapPoints) : undefined;
+    // A snap point OUTSIDE the declared hard constraints is a CONTRADICTORY config (review r5 major 20,
+    // REQ-GESTURE-015): selectReleaseTarget returns the projected-then-snapped point UNCLAMPED when the
+    // release is within bounds, so an out-of-bounds snap would settle the box outside the allowed
+    // region — and diverge from the web engine's constrained inertia path. Reject the incompatible set
+    // at THIS boundary (both engines call resolveDragConfig) so every terminal state stays within the
+    // hard bounds by construction. Bounds are inclusive: a snap AT min/max is valid. The ref form's
+    // bounds are measured per grab — snap-vs-ref-bounds validates at the grab-time measure instead.
+    if (constraints !== undefined && snap !== undefined) {
+        for (const point of snap.points) {
+            if (point < constraints.min || point > constraints.max) {
+                throw new Error(`dragSnapPoints.${drag} contains ${point}, outside the declared dragConstraints ` +
+                    `[${constraints.min}, ${constraints.max}] — a snap outside the hard bounds would settle ` +
+                    'out of range; every snap point must lie within the constraints (REQ-GESTURE-015).');
+            }
+        }
+    }
+    const axisConfig = {
+        ...(constraints === undefined ? {} : { constraints }),
+        ...(constraintsRef === undefined ? {} : { constraintsRef }),
+        ...(snap === undefined ? {} : { snap }),
+    };
+    return drag === 'x' ? { x: axisConfig, ...hubFields } : { y: axisConfig, ...hubFields };
+}
+// REQ-API-016: an onDrag* callback on an element with no `drag` axis would be an
+// accepted-but-ignored prop — it can never fire. Refused under the severity law, never silent.
+export function gateOrphanDragCallbacks(callbackName, severity, report) {
+    const error = new Error(`${callbackName} requires drag to be 'x', 'y', or true — a drag callback without a drag axis can ` +
+        'never fire and is refused, never silently ignored (REQ-API-016/-021).');
+    if (severity === 'development')
+        throw error;
+    report(error);
+}
+// The resolver catches values from user-owned proxy traps as well as ordinary Errors. Normalize
+// every catch at this boundary; even an Error instance can have a hostile `message` getter.
+// `describeValue` owns every property read under its total guard, so both severity lanes retain
+// their typed drag refusal instead of leaking a secondary coercion failure.
+function normalizedResolverError(error) {
+    return new Error(`drag configuration resolution failed: ${describeValue(error)} (REQ-API-021).`);
+}
+// The severity gate (REQ-API-021): development throws through; production reports the typed error
+// and refuses the whole gesture surface for this element (null) — fail-closed, no partial config.
+export function resolveDragConfig(input, severity, report) {
+    try {
+        return resolveOrThrow(input);
+    }
+    catch (error) {
+        const normalized = normalizedResolverError(error);
+        if (severity === 'development')
+            throw normalized;
+        report(normalized);
+        return null;
+    }
+}