@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/dragGestureWiring.ts

@@ -0,0 +1,1168 @@
+// REQ-API-020/-022/-041 + REQ-GESTURE-022/-024 composition (FLAG 5a + R15 D1,
+// specs/SPEC-GESTURE.md) — the drag gesture WIRING: the pure orchestrator MotionView plugs into
+// Gesture.Pan(). It owns the protocol between the recognizer, the per-axis handoff bindings, and
+// the abstract Driver:
+//
+//   grab    → ONE live-read per axis (REQ-DRIVER-025) + ONE interrupting write at the live values
+//             (REQ-DRIVER-024; a grab IS the interruption, REQ-GESTURE-012), sessions seeded C0
+//   update  → per-axis session-constrained values → ONE write per recognizer event
+//             (REQ-GESTURE-002; REQ-GESTURE-024 per-axis channels, one recognizer lifecycle)
+//   release → ONE velocity-seeded `start` whose targets cover EVERY dragged axis
+//             (REQ-DRIVER-023; C0/C1 per REQ-GESTURE-013), spring = core's shared release config
+//   cancel  → the same command shape with the handoffs' zero-velocity pre-grab return
+//
+// Nested drags ride Motion's global drag lock (REQ-GESTURE-024): a non-propagating element
+// acquires the lock at grab and holds it until finalize — a second element's grab is swallowed
+// whole (no read, no write, no callback); `dragPropagation` opts out both ways. Pure over the
+// Driver contract so the reference driver proves the exact protocol the worklet driver receives
+// on device. Callbacks carry Motion's (event, info) shape: DragInfo mirrors motion's PanInfo
+// ({point, delta, offset, velocity}, each 2D) built from the recognizer's own fields —
+// informational payloads validate fail-loud like every other recognizer read.
+
+import {
+  DEFAULT_DRAG_ELASTIC,
+  describeValue,
+  DRAG_INERTIA_DEFAULTS,
+  dragInertiaBounce,
+  GESTURE_RELEASE_SPRING,
+  progressWithinSpan,
+  resolveDirectionLockAxis,
+  resolveViewportConstraints,
+  resolvedDragAxes,
+  validateMeasureReplacementBox,
+  type AxisSpan,
+  type DragAxis,
+  type DragInfo,
+  type Driver,
+  type ElementHandle,
+  type GestureHandoffSession,
+  type MeasureDragConstraintsCallback,
+  type PropTarget,
+  type PropTransition,
+  type ReleaseHandoff,
+  type ResolvedDragConfig,
+  type Transition,
+} from '@unrulysystems/native-motion-core'
+import {
+  createDragHandoffBinding,
+  type DragHandoffBinding,
+  type DragPanEventShape,
+} from './dragHandoffBinding'
+import { sharedDragPropagationLock, type DragPropagationLock } from './dragPropagationLock'
+import { wrapDriverForExternalDragValues, type ExternalDragValues } from './externalDragDriver'
+
+export type { ExternalDragValues }
+
+// `DragInfo` (Motion's PanInfo shape) is the shared core type so the (event, info) callback
+// payload is identical cross-engine (REQ-API-020); built here natively from the recognizer's
+// absolute/translation/velocity fields.
+//
+// The native event object is the recognizer's own payload (the platform-faithful analog of
+// motion's DOM PointerEvent first argument — a recorded platform difference, not a divergence in
+// the info shape).
+export type DragEventCallback = (event: unknown, info: DragInfo) => void
+
+export interface DragCallbacks {
+  readonly onDragStart?: DragEventCallback | undefined
+  readonly onDrag?: DragEventCallback | undefined
+  readonly onDragEnd?: DragEventCallback | undefined
+  // REQ-API-042 (R15 D2): the pin's measure hook — receives the measured viewport constraints
+  // at every grab (layout-relative, per the pin's BoundingBox) and may return a mutated box,
+  // which replaces the measured one for that grab. LATEST like every callback.
+  readonly onMeasureDragConstraints?: MeasureDragConstraintsCallback | undefined
+  // R15 D4 (REQ-API-044 / REQ-GESTURE-025): fires once when the direction lock is acquired.
+  readonly onDirectionLock?: ((axis: DragAxis) => void) | undefined
+}
+
+// The measured boxes the grab-time seam returns: the draggable's CURRENT layout frame and the
+// constraint element's frame, already in the same coordinate space (window coords).
+export interface ConstraintsMeasureBoxes {
+  readonly draggableBox: { readonly x: AxisSpan; readonly y: AxisSpan }
+  readonly containerBox: { readonly x: AxisSpan; readonly y: AxisSpan }
+}
+
+// The grab-time measurement seam (REQ-GESTURE-028): MotionView supplies a closure that
+// measures ITS host (the draggable) and the constraint element via measureInWindow (async —
+// the pin's synchronous page-box read has no native analog). The ref wrapper is passed so the
+// seam resolves `.current` at the measure instant, never earlier.
+export type ConstraintsMeasure = (container: {
+  readonly current: unknown
+}) => Promise<ConstraintsMeasureBoxes>
+
+export interface DragGestureWiringOptions {
+  readonly driver: Driver
+  readonly handle: ElementHandle
+  readonly config: ResolvedDragConfig
+  // U7f: latest resolved config at grab (pin getProps per session). When omitted, `config`
+  // is the session. Empty axes (`drag={false}`) no-op the grab.
+  readonly getConfig?: (() => ResolvedDragConfig) | undefined
+  readonly callbacks?: DragCallbacks
+  // REQ-API-041: default false — this element acquires the pin's per-axis global drag lock at
+  // grab; true skips the lock for itself (never acquires, never blocked).
+  readonly dragPropagation?: boolean | undefined
+  // The lock scope: app-global by default (the pin's module-global analog — review
+  // 97bf73b720a8, never a per-root scope); tests inject their own.
+  readonly lock?: DragPropagationLock | undefined
+  // REQ-GESTURE-028: REQUIRED when any axis carries constraintsRef (a host wiring bug without
+  // it, fail-loud at grab). The grab-time measure seam.
+  readonly measureConstraints?: ConstraintsMeasure | undefined
+  // The deferred-begin failure channel (REQ-GESTURE-028): an unmounted/unmeasurable container
+  // or a snap-vs-measured-bounds contradiction reports here — severity-adapted by the caller
+  // (review r4 major 5): MotionView's DEVELOPMENT adapter throws the typed error, which rides
+  // this async delivery as an unhandled rejection — the dev crash surface; production reports
+  // and refuses that grab, never a half-started session.
+  readonly reportConstraintFailure?: ((error: Error) => void) | undefined
+  // REQ-GESTURE-028 (review major 3): the mid-drag re-measure loop — while a ref-constrained
+  // drag is ACTIVE, re-measure the boxes per frame tick and re-resolve constraints + rescale
+  // the position on change (the pin's ResizeObserver + window-resize path,
+  // scalePositionWithinConstraints). When absent, the mid-drag re-measure simply never runs
+  // (the per-grab law still holds); MotionView injects the platform frame ticker, tests a
+  // manual one. Repeating: the callback fires once per frame until the returned cancel runs.
+  readonly frameTicker?: ((callback: () => void) => () => void) | undefined
+  /**
+   * R15 D5 (REQ-API-046): external `_dragX`/`_dragY` — when set for an axis, session live
+   * reads/writes/release land on the MotionValue instead of the host transform channel.
+   */
+  readonly externalDragValues?: ExternalDragValues | undefined
+}
+
+// The handlers MotionView binds onto Gesture.Pan() (runOnJS(true), the ratified JS routing).
+export interface DragGestureWiring {
+  handlePanStart(event: DragPanEventShape): void
+  handlePanUpdate(event: DragPanEventShape): void
+  handlePanEnd(event: DragPanEventShape, success: boolean): void
+  handlePanFinalize(event: DragPanEventShape, success: boolean): void
+  /**
+   * R15 D3 (REQ-GESTURE-026): pin snapToCursor — re-seat each dragged axis so the pointer is at
+   * the element center. `layoutBox` is the VISUAL frame in page/window space (measure includes
+   * the live transform); formula `value = point − midpoint + current` (pin VisualElementDragControls
+   * snapToCursor — sanctioned G-INV-2 jump at start-invocation only).
+   */
+  snapToCursor(
+    point: { readonly absoluteX: number; readonly absoluteY: number },
+    layoutBox: {
+      readonly x: number
+      readonly y: number
+      readonly width: number
+      readonly height: number
+    },
+  ): void
+  // UNMOUNT teardown (review 1d6e5b08344c): RNGH drops the recognizer's handlers on unmount
+  // without dispatching a JS finalize, so an active drag whose host unmounts would hold the
+  // app-global lock forever — every later non-propagating drag in the tree blocked. MotionView
+  // calls this from its unmount cleanup: the lock releases and every later recognizer event
+  // (a handler can briefly outlive its host) no-ops. The session itself dies with the host —
+  // no cancel command is issued against a dead handle.
+  dispose(): void
+  // The per-axis handoff sessions, exposed for the verification seam (state assertions) — the
+  // wiring owns their lifecycle; consumers never call them directly.
+  readonly sessions: Readonly<Partial<Record<DragAxis, GestureHandoffSession>>>
+}
+
+// The release spring is core's shared constant lifted into the public Transition shape — one
+// config, never a duplicated literal. R15 D5 (REQ-API-045): dragTransition may override
+// bounceStiffness/bounceDamping (pin inertia → spring mapping, curve-parity law).
+function releaseTransitionFor(config: ResolvedDragConfig): Transition {
+  const t = config.dragTransition
+  return {
+    type: 'spring',
+    stiffness: t?.bounceStiffness ?? GESTURE_RELEASE_SPRING.stiffness,
+    damping: t?.bounceDamping ?? GESTURE_RELEASE_SPRING.damping,
+  }
+}
+
+// R16 (REQ-GESTURE-023/-027): the free-drag release's per-target inertia descriptor — the pin's
+// drag-layer physics verbatim (timeConstant 750, power 0.8, restDelta 1, restSpeed 10), the
+// elastic-conditional boundary-spring pair (dragElastic truthy → 200/40, falsy → 1e6/1e7) with
+// `dragTransition` bounce overrides feeding the BOUNDARY spring (their pin meaning; the D5
+// spring-mapping is superseded), and the grab-time bounds for the walls.
+function inertiaTransitionFor(
+  config: ResolvedDragConfig,
+  axis: DragAxis,
+  handoff: ReleaseHandoff & { readonly curve: 'inertia' },
+): PropTransition {
+  const axisConfig = config[axis]
+  // The pin selects the bounce pair from the ELEMENT dragElastic (default 0.35 truthy → 200/40);
+  // the resolved per-constraint elastic carries it when constraints exist.
+  const elastic =
+    axisConfig?.constraints?.elastic ?? axisConfig?.constraintsRef?.elastic ?? DEFAULT_DRAG_ELASTIC
+  const bounce = dragInertiaBounce(elastic)
+  const t = config.dragTransition
+  return {
+    type: 'inertia',
+    power: DRAG_INERTIA_DEFAULTS.power,
+    timeConstant: DRAG_INERTIA_DEFAULTS.timeConstant,
+    bounceStiffness: t?.bounceStiffness ?? bounce.bounceStiffness,
+    bounceDamping: t?.bounceDamping ?? bounce.bounceDamping,
+    restDelta: DRAG_INERTIA_DEFAULTS.restDelta,
+    restSpeed: DRAG_INERTIA_DEFAULTS.restSpeed,
+    ...(handoff.min !== undefined ? { min: handoff.min } : {}),
+    ...(handoff.max !== undefined ? { max: handoff.max } : {}),
+  }
+}
+
+function snapToOriginApplies(config: ResolvedDragConfig, axis: DragAxis): boolean {
+  const s = config.dragSnapToOrigin
+  if (s === true) return true
+  if (s === false) return false
+  return s === axis
+}
+
+// REQ-GESTURE-028 (review r4 minor 7) — the deferred-begin's two bounds. The async measure
+// must never retain the wiring forever: a native measureInWindow callback that never arrives
+// would pin the lock and every buffered event indefinitely. measureInWindow lands in 1–2
+// frames (~16–33ms); 1000ms is generous bounded headroom before the grab/poll fails loud.
+const MEASURE_TIMEOUT_MS = 1000
+// The pending grab's buffered updates are capped: a measure pending longer than 64 recognizer
+// events is pathological — refuse the grab (fail-loud) rather than retain events indefinitely.
+const MAX_BUFFERED_PAN_UPDATES = 64
+
+function measureWithTimeout(
+  measure: ConstraintsMeasure,
+  ref: { readonly current: unknown },
+): Promise<ConstraintsMeasureBoxes> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const racing = new Promise<ConstraintsMeasureBoxes>((_resolve, reject) => {
+    timer = setTimeout(() => {
+      reject(
+        new Error(
+          `dragConstraints measure timed out after ${MEASURE_TIMEOUT_MS}ms — the native ` +
+            'measureInWindow callback never arrived (REQ-GESTURE-028; the bounded-wait law).',
+        ),
+      )
+    }, MEASURE_TIMEOUT_MS)
+  })
+  return Promise.race([
+    measure(ref).finally(() => {
+      if (timer !== undefined) clearTimeout(timer)
+    }),
+    racing,
+  ])
+}
+
+// Same fail-loud field law as the binding: info payloads read the recognizer's 2D fields and a
+// missing field is a platform/caller bug named at the boundary — never coerced.
+function requireInfoNumber(value: unknown, field: string): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    // describeValue (core, single-sourced) is a SAFE formatter (review r4 minor 844ee5e): a BigInt
+    // recognizer field must produce this typed error naming the field, never a raw JSON.stringify
+    // serialization TypeError.
+    throw new Error(
+      `drag wiring: Pan event field '${field}' is ${describeValue(value)} — a finite number ` +
+        'is required for the Motion (event, info) callback payload (REQ-API-020).',
+    )
+  }
+  return value
+}
+
+interface InfoEventShape extends DragPanEventShape {
+  readonly absoluteX?: unknown
+  readonly absoluteY?: unknown
+}
+
+// Where this element stands with Motion's global drag lock across one recognizer stream:
+// 'open' (no grab yet, or propagating), 'acquired' (we hold it until finalize), 'blocked'
+// (another element holds it — our whole stream stays inert).
+type LockState = 'open' | 'acquired' | 'blocked'
+
+export function createDragGestureWiring(options: DragGestureWiringOptions): DragGestureWiring {
+  const handle = options.handle
+  const getConfig = options.getConfig ?? (() => options.config)
+  let config = options.config
+  // R15 D5: optional external-value driver wrap (REQ-API-046) — all live/write/command sites
+  // below use this driver so external axes never touch the host transform channel.
+  const driver =
+    options.externalDragValues !== undefined
+      ? wrapDriverForExternalDragValues(options.driver, handle, options.externalDragValues)
+      : options.driver
+  const callbacks = options.callbacks ?? {}
+  let dragPropagation = options.dragPropagation ?? config.dragPropagation
+  const lock = options.lock ?? sharedDragPropagationLock
+  // One binding per dragged axis (REQ-GESTURE-024: independent per-axis channels sharing this
+  // ONE recognizer lifecycle). Single-axis drags get exactly one binding — no forked path.
+  // U7f: `drag={false}` is zero-axis; bindings install at grab from the live session config.
+  let axes = resolvedDragAxes(config)
+  const bindings: Partial<Record<DragAxis, DragHandoffBinding>> = {}
+  const sessions: Partial<Record<DragAxis, GestureHandoffSession>> = {}
+  const installBindings = (next: ResolvedDragConfig): readonly DragAxis[] => {
+    const nextAxes = resolvedDragAxes(next)
+    config = next
+    axes = nextAxes
+    dragPropagation = options.dragPropagation ?? next.dragPropagation
+    for (const axis of ['x', 'y'] as const) {
+      delete bindings[axis]
+      delete sessions[axis]
+    }
+    for (const axis of nextAxes) {
+      const binding = createDragHandoffBinding(axis, next[axis]!, next.dragMomentum)
+      bindings[axis] = binding
+      sessions[axis] = binding.session
+    }
+    return nextAxes
+  }
+  if (axes.length > 0) {
+    installBindings(config)
+  }
+  // The lock owner's identity: this wiring (one per mounted drag element). A dedicated token —
+  // never the handle (driver-owned) or the callbacks (consumer-owned).
+  const lockOwner: object = {}
+  let lockState: LockState = 'open'
+  // Set by dispose() (unmount): late recognizer events no-op and the held lock is freed.
+  let disposed = false
+  // Per-gesture delta base: the previous event's point; null between gestures.
+  let lastPoint: { x: number; y: number } | null = null
+  // Absolute prop values at grab (per axis) — DragInfo.offset is constrained session value minus
+  // these seeds (element drag displacement), not raw recognizer translation.
+  const grabSeeds: Partial<Record<DragAxis, number>> = {}
+  // R15 D4 (REQ-GESTURE-025): session-scoped direction lock; null until threshold crossed.
+  let lockedAxis: DragAxis | null = null
+  let directionLockNotified = false
+  // The deferred-begin state (REQ-GESTURE-028): a grab carrying element-ref constraints holds
+  // its full validated start event + buffered updates while the grab-time measure is in flight
+  // (native measureInWindow is async; the value holds C0 until the measured bounds land).
+  interface PendingDeferredGrab {
+    readonly event: InfoEventShape
+    readonly info: DragInfo
+    readonly updates: InfoEventShape[]
+    // The recognizer may END before the measure lands (a quick flick — review r6 major 1):
+    // the end (and its finalize) QUEUE here, never silently dropped (G-INV-8). When the
+    // measure lands the FULL lifecycle flushes: begin → buffered updates → the release
+    // handoff → finalize. Only dispose / the buffer cap / a measure failure cancels.
+    endEvent?: { readonly event: DragPanEventShape; readonly success: boolean }
+    finalized?: boolean
+  }
+  let pendingGrab: PendingDeferredGrab | null = null
+  // The deferred begin ABORTED (the grab-time measure failed): the rest of THIS recognizer
+  // stream is dead — trailing updates and ends no-op (the pin's "the element simply does not
+  // drag"), never a session call against an idle session (the 2026-08-04 device crash class:
+  // update after measure failure → active() in 'idle'). The NEXT pan start re-arms.
+  let grabAborted = false
+
+  // Cancel a pending deferred begin (dispose, the bounded-buffer overflow, a host error): drop
+  // the queued lifecycle and free the lock — the drag never began, so no callbacks and no
+  // session (Motion's end-without-start is nothing). The grab-instant interrupt already froze
+  // any in-flight animation AT the grab value — the cancel target equals the frozen value
+  // (pre-grab == grab instant), so no return handoff is owed.
+  function cancelPendingGrab(): void {
+    if (pendingGrab === null) return
+    pendingGrab = null
+    grabAborted = true
+    if (lockState === 'acquired') {
+      lock.release(lockOwner)
+      lockState = 'open'
+    }
+  }
+
+  // The mid-drag re-measure loop (REQ-GESTURE-028, review major 3 — the pin's ResizeObserver +
+  // window-resize scalePositionWithinConstraints path): while a ref-constrained drag is ACTIVE
+  // the boxes re-measure per frame tick; on change the constraints re-resolve AND the position
+  // rescales to preserve the relative progress within the new bounds. `lastResolvedPerAxis`
+  // tracks the bounds the active grab began (or last rescaled) with — the diff + the progress
+  // base. The loop is self-terminating (no active ref session → cancel) and bounded (one
+  // async measure in flight; the stream's abort/dispose paths stop it).
+  let stopMeasurePoll: (() => void) | null = null
+  let pollMeasureInFlight = false
+  let lastResolvedPerAxis: Partial<Record<DragAxis, AxisSpan>> = {}
+
+  function stopPoll(): void {
+    stopMeasurePoll?.()
+    stopMeasurePoll = null
+  }
+
+  function tickMeasurePoll(): void {
+    if (pollMeasureInFlight || pendingGrab !== null) return
+    const activeRefAxes = axes.filter(
+      (axis) =>
+        config[axis]?.constraintsRef !== undefined && bindings[axis]!.session.state() === 'active',
+    )
+    if (activeRefAxes.length === 0) {
+      stopPoll()
+      return
+    }
+    pollMeasureInFlight = true
+    const epoch = gestureEpoch
+    void measureWithTimeout(
+      options.measureConstraints!,
+      config[activeRefAxes[0]!]!.constraintsRef!.ref,
+    ).then(
+      (boxes) => {
+        pollMeasureInFlight = false
+        // Stale resolves die: the stream aborted/disposed, or the epoch moved (a release or a
+        // re-grab happened while this measure was in flight — review r2 major 2).
+        if (disposed || grabAborted || epoch !== gestureEpoch) return
+        try {
+          adoptMeasuredBoxes(boxes, activeRefAxes)
+        } catch (error) {
+          // A throwing measure hook mid-drag: report and stop the poll — the active grab keeps
+          // its last resolved bounds (symmetric to the measure-failure path).
+          stopPoll()
+          options.reportConstraintFailure?.(
+            error instanceof Error ? error : new Error(describeValue(error)),
+          )
+        }
+      },
+      (cause) => {
+        pollMeasureInFlight = false
+        // The same staleness guard as the fulfillment branch (review r4 major 4): a poll
+        // rejected after abort/dispose/epoch-move is DISCARDED — never a stale report, never a
+        // stopPoll on the ticker now serving the next gesture.
+        if (disposed || grabAborted || epoch !== gestureEpoch) return
+        // A mid-drag measure failure (the container unmounted): report through the channel and
+        // stop the poll — the active grab keeps its last resolved bounds (the pin's invariant
+        // surfaces on its own channel; the stream is NOT aborted — the gesture itself is fine).
+        stopPoll()
+        options.reportConstraintFailure?.(
+          cause instanceof Error ? cause : new Error(describeValue(cause)),
+        )
+      },
+    )
+  }
+
+  // Adopt a poll resolve PER AXIS (review r13 major 1): an axis whose container and draggable
+  // boxes moved by the SAME delta is invariant on that axis (unchanged, or a shared ancestor
+  // translate/scroll) — never fabricated by pairing a stale draggable with a moved container.
+  // A container-only change on an axis adopts with the last adopted (coherent) draggable span
+  // for THAT axis; a draggable-only change on an axis is lag (or the deferred app shift) —
+  // never adopted. The rescale diffs per axis, so untouched axes are untouched.
+  function adoptMeasuredBoxes(boxes: ConstraintsMeasureBoxes, refAxes_: readonly DragAxis[]): void {
+    const adopted = lastAdoptedBoxes
+    if (adopted === null) return
+    let adoptX = false
+    let adoptY = false
+    let invX = true
+    let invY = true
+    for (const axis of ['x', 'y'] as const) {
+      const draggableDeltaMin = boxes.draggableBox[axis].min - adopted.draggableBox[axis].min
+      const draggableDeltaMax = boxes.draggableBox[axis].max - adopted.draggableBox[axis].max
+      const containerDeltaMin = boxes.containerBox[axis].min - adopted.containerBox[axis].min
+      const containerDeltaMax = boxes.containerBox[axis].max - adopted.containerBox[axis].max
+      if (draggableDeltaMin === containerDeltaMin && draggableDeltaMax === containerDeltaMax) {
+        continue // invariant on this axis
+      }
+      if (axis === 'x') invX = false
+      else invY = false
+      if (sameSpan(boxes.containerBox[axis], adopted.containerBox[axis])) continue // lag — never adopted
+      if (axis === 'x') adoptX = true
+      else adoptY = true
+    }
+    if (adoptX || adoptY) {
+      // Per axis: invariant axes pair the SAMPLE's boxes (their relative geometry is unchanged);
+      // changed axes — adopting OR lag-only — pair the ADOPTED draggable span (never the
+      // lag-suspect sample side, review r14 major 3) with the current container span.
+      const coherentBoxes: ConstraintsMeasureBoxes = {
+        draggableBox: {
+          x: invX ? boxes.draggableBox.x : adopted.draggableBox.x,
+          y: invY ? boxes.draggableBox.y : adopted.draggableBox.y,
+        },
+        containerBox: boxes.containerBox,
+      }
+      lastAdoptedBoxes = coherentBoxes
+      rescaleAfterBoxChange(applyMeasureHook(coherentBoxes, refAxes_), refAxes_)
+      return
+    }
+    if (invX && invY) {
+      lastAdoptedBoxes = boxes // a shared translate on every axis — track, never fabricate
+    }
+    // else: lag-only changes — keep the baseline (the lag must not poison it).
+  }
+
+  // Re-resolve + rescale after the measured boxes changed (the pin's math: preserve the
+  // relative progress within the old bounds — calcOrigin — applied to the new bounds — mix).
+  // The measure hook already ran (adoptMeasuredBoxes' shared seam).
+  function rescaleAfterBoxChange(
+    finalPerAxis: Partial<Record<DragAxis, AxisSpan>>,
+    refAxes_: readonly DragAxis[],
+  ): void {
+    const values: Record<string, number> = {}
+    let changed = false
+    for (const axis of refAxes_) {
+      const next = finalPerAxis[axis]!
+      const prev = lastResolvedPerAxis[axis]
+      if (prev === undefined || (prev.min === next.min && prev.max === next.max)) continue
+      lastResolvedPerAxis[axis] = next
+      const session = bindings[axis]!.session
+      if (session.state() !== 'active') continue
+      const live = driver.liveFor(handle, axis)
+      // The progress-preserving rescale requires FINITE spans on both sides: an open-sided
+      // span (a legal hook replacement) has no proportional position to preserve — keep the
+      // live value (the constraints still update; review r4 major 3 — never write NaN).
+      const rescaled =
+        Number.isFinite(prev.min) &&
+        Number.isFinite(prev.max) &&
+        Number.isFinite(next.min) &&
+        Number.isFinite(next.max)
+          ? next.min + (next.max - next.min) * progressWithinSpan(live.value, prev)
+          : live.value
+      session.updateConstraints(
+        { min: next.min, max: next.max, elastic: config[axis]!.constraintsRef!.elastic },
+        rescaled,
+      )
+      values[axis] = rescaled
+      changed = true
+    }
+    if (changed) driver.write(handle, values)
+  }
+
+  function startMeasurePoll(): void {
+    if (options.frameTicker === undefined || stopMeasurePoll !== null) return
+    stopMeasurePoll = options.frameTicker(tickMeasurePoll)
+  }
+
+  // The hook's replacement box is a boundary INPUT, validated immediately by CORE's single
+  // cross-engine verdict (review r3 major 3 + r7 major 3): complete, finite or
+  // correct-polarity-infinite, ordered. A malformed replacement is a typed refusal —
+  // severity-adapted by the caller's report channel (the begin aborts the grab; the poll
+  // keeps its last resolved bounds).
+
+  // The pin's measure-hook seam, shared by the grab-time begin AND the mid-drag re-measure
+  // (the pin invokes resolveRefConstraints — hook included — on BOTH paths, review r2 major 1):
+  // compute calcViewportConstraints over BOTH axes of the measured boxes (the complete
+  // geometry, never a fabricated zero span on the non-dragged axis — review r1 major 2),
+  // offer it to onMeasureDragConstraints ONCE (the hasMutatedConstraints seam), and use the
+  // possibly-replaced bounds per ref axis.
+  function applyMeasureHook(
+    boxes: ConstraintsMeasureBoxes,
+    refAxes_: readonly DragAxis[],
+  ): Partial<Record<DragAxis, AxisSpan>> {
+    const measuredBoth = {
+      x: resolveViewportConstraints(boxes.draggableBox.x, boxes.containerBox.x),
+      y: resolveViewportConstraints(boxes.draggableBox.y, boxes.containerBox.y),
+    }
+    let finalPerAxis: Partial<Record<DragAxis, AxisSpan>> = {}
+    for (const axis of refAxes_) {
+      finalPerAxis[axis] = measuredBoth[axis]
+    }
+    if (callbacks.onMeasureDragConstraints !== undefined) {
+      // The hook's box is a boundary input; a THROWING hook or a malformed replacement refuses
+      // the PROPERTY, never the gesture (review r14 major 4, BRIEF's single severity policy —
+      // cross-engine: web's wrapper drops the replacement and keeps motion's own measured box).
+      // The measured bounds stand; the failure reports through the channel per sighting.
+      try {
+        const replaced = callbacks.onMeasureDragConstraints({
+          top: measuredBoth.y.min,
+          left: measuredBoth.x.min,
+          bottom: measuredBoth.y.max,
+          right: measuredBoth.x.max,
+        })
+        if (replaced) {
+          // The pin's truthiness no-op (hasMutatedConstraints = !!userConstraints): any falsy
+          // return means "keep the measured box". A TRUTHY return is validated by core's single
+          // verdict (complete/finite/ordered or the typed refusal).
+          const legal = validateMeasureReplacementBox(replaced)
+          finalPerAxis = {}
+          for (const axis of refAxes_) {
+            finalPerAxis[axis] =
+              axis === 'x'
+                ? { min: legal.left, max: legal.right }
+                : { min: legal.top, max: legal.bottom }
+          }
+        }
+      } catch (error) {
+        options.reportConstraintFailure?.(
+          error instanceof Error ? error : new Error(describeValue(error)),
+        )
+      }
+    }
+    return finalPerAxis
+  }
+
+  // The gesture epoch (review r2 major 2): bumped at every grab and every stream end — an
+  // async poll dispatched under one gesture resolves under the epoch check, so a stale
+  // measure (release + rapid re-grab meanwhile) is discarded, never accepted into the new
+  // gesture's session. The deferred begin's own promise rides the pendingGrab token already.
+  let gestureEpoch = 0
+  // The adoption rule (2026-08-04 walk finding, review r3 major 2 + r5 major 2): only a
+  // CONTAINER-side change is adopted, and only with the LAST ADOPTED draggable span — never
+  // the poll sample's draggable box. The draggable's layout is static under an active drag
+  // (the drag moves via transform), so any sample-side change there is the async measure's
+  // frame lag (the finger moves between the UI measure and the JS delivery; under steady
+  // motion two consecutive lagged samples can coincide, which is why the earlier
+  // two-sightings debounce still drifted). The container side carries no finger lag, and a
+  // continuously animated container re-resolves every frame. An app-driven draggable layout
+  // shift mid-drag is the pin's didUpdate delta-follow path — deferred (Finding D2e).
+  let lastAdoptedBoxes: ConstraintsMeasureBoxes | null = null
+
+  function sameSpan(a: AxisSpan, b: AxisSpan): boolean {
+    return a.min === b.min && a.max === b.max
+  }
+
+  function buildInfo(
+    event: InfoEventShape,
+    offsetOverride?: { readonly x: number; readonly y: number },
+  ): DragInfo {
+    const point = {
+      x: requireInfoNumber(event.absoluteX, 'absoluteX'),
+      y: requireInfoNumber(event.absoluteY, 'absoluteY'),
+    }
+    // Default offset is raw translation (grab path before sessions have advanced). Callers that
+    // have just applied session updates pass constrained element displacement (value − grabSeed).
+    const offset = offsetOverride ?? {
+      x: requireInfoNumber(event.translationX, 'translationX'),
+      y: requireInfoNumber(event.translationY, 'translationY'),
+    }
+    const info: DragInfo = {
+      point,
+      delta:
+        lastPoint === null
+          ? { x: 0, y: 0 }
+          : { x: point.x - lastPoint.x, y: point.y - lastPoint.y },
+      offset,
+      velocity: {
+        x: requireInfoNumber(event.velocityX, 'velocityX'),
+        y: requireInfoNumber(event.velocityY, 'velocityY'),
+      },
+    }
+    lastPoint = point
+    return info
+  }
+
+  function constrainedOffset(): { x: number; y: number } {
+    const axisOffset = (axis: DragAxis): number => {
+      const binding = bindings[axis]
+      const seed = grabSeeds[axis]
+      if (binding === undefined || seed === undefined || binding.session.state() !== 'active') {
+        return 0
+      }
+      return binding.session.value() - seed
+    }
+    return { x: axisOffset('x'), y: axisOffset('y') }
+  }
+
+  function anySessionActive(): boolean {
+    return axes.some((axis) => bindings[axis]!.session.state() === 'active')
+  }
+
+  // Release and cancel share the command shape: the sessions' handoffs ARE the seed
+  // (REQ-GESTURE-022); the driver's spring integrates them on the UI thread (REQ-DRIVER-023).
+  // ONE command covers every handed-off axis (REQ-GESTURE-024) so the release edge is atomic.
+  //
+  // TERMINAL TOTALITY (G-INV-7, review r4 major 759836): mutate-THEN-info. The handoffs are
+  // already computed from the release-critical fields (axis translations/velocities), so the
+  // release/cancel command lands FIRST — the gesture's real outcome (settling to the targets).
+  // Only THEN is the callback `info` built: a malformed INFO-ONLY field (absoluteX/Y) throws
+  // AFTER the gesture has terminated cleanly (sessions idle, driver settling), losing the
+  // callback but never stranding the gesture active. This is deliberately OPPOSITE
+  // handlePanStart (validate-before-mutate): a bad GRAB must not interrupt the in-flight
+  // animation; a bad terminal must still end.
+  function issueHandoffs(
+    handoffs: Readonly<Partial<Record<DragAxis, ReleaseHandoff>>>,
+    event: InfoEventShape,
+  ): void {
+    const targets: Record<string, PropTarget> = {}
+    for (const axis of axes) {
+      const handoff = handoffs[axis]
+      if (handoff === undefined) continue
+      targets[axis] =
+        handoff.curve === 'inertia'
+          ? // Free-drag release (R16): the two-phase inertia generator rides the per-target
+            // transition; `to` is the mirror terminal (the clamped ideal), the descriptor owns
+            // the curve.
+            {
+              to: handoff.target,
+              from: handoff.from,
+              velocity: handoff.velocity,
+              transition: inertiaTransitionFor(config, axis, handoff),
+            }
+          : { to: handoff.target, from: handoff.from, velocity: handoff.velocity }
+    }
+    if (Object.keys(targets).length === 0) return // nothing active handed off (defensive)
+    driver.command(handle, {
+      kind: 'start',
+      targets,
+      transition: releaseTransitionFor(config),
+      // The finger let go (or the gesture cancelled): THIS start is the release edge — it ends
+      // the gesture's ownership of the axis props so the settle spring takes over with the
+      // seeded platform velocity. A declarative `animate`/mount command during the drag never
+      // carries this, so it can never masquerade as the release (review r8 major 24).
+      releasesGesture: true,
+    })
+    const info = buildInfo(event) // AFTER the command — a malformed info-only field throws terminated
+    lastPoint = null // the gesture is over; the next grab starts a fresh delta base
+    callbacks.onDragEnd?.(event, info)
+  }
+
+  // Complete a deferred begin once the grab-time measure lands (REQ-GESTURE-028): compute the
+  // pin's viewport constraints per axis, apply the measure hook, validate snap against the
+  // measured bounds, then run the EXACT grab protocol of the immediate path (live-read →
+  // per-axis begin with the measured bounds → interrupting write → onDragStart) and flush the
+  // buffered updates in order.
+  function beginAfterMeasure(
+    pending: PendingDeferredGrab,
+    boxes: ConstraintsMeasureBoxes,
+    refAxes: readonly DragAxis[],
+  ): void {
+    try {
+      // The complete measured box + the measure hook, through the SHARED seam (review r2
+      // major 1 — the pin applies the hook on every resolveRefConstraints path).
+      const finalPerAxis = applyMeasureHook(boxes, refAxes)
+      // Snap-vs-measured-bounds (the numeric path's contradiction law at the grab-time measure,
+      // REQ-GESTURE-015): a snap outside the measured bounds would settle out of range.
+      for (const axis of refAxes) {
+        const snap = config[axis]?.snap
+        const bounds = finalPerAxis[axis]!
+        if (snap !== undefined) {
+          for (const point of snap.points) {
+            if (point < bounds.min || point > bounds.max) {
+              throw new Error(
+                `dragSnapPoints.${axis} contains ${point}, outside the measured dragConstraints ` +
+                  `[${bounds.min}, ${bounds.max}] — a snap outside the hard bounds would settle ` +
+                  'out of range (REQ-GESTURE-015).',
+              )
+            }
+          }
+        }
+      }
+      const values: Record<string, number> = {}
+      const velocities: Record<string, number> = {}
+      for (const axis of axes) {
+        const live = driver.liveFor(handle, axis)
+        const measured = finalPerAxis[axis]
+        bindings[axis]!.onStart(
+          pending.event,
+          { value: live.value },
+          measured === undefined
+            ? undefined
+            : {
+                min: measured.min,
+                max: measured.max,
+                elastic: config[axis]!.constraintsRef!.elastic,
+              },
+        )
+        values[axis] = live.value
+        velocities[axis] = live.velocity
+      }
+      driver.write(handle, values, velocities)
+      callbacks.onDragStart?.(pending.event, pending.info)
+      for (const update of pending.updates) applyPanUpdate(update)
+      // The grab began with the measured bounds: arm the mid-drag re-measure loop (review
+      // major 3) with THESE bounds as the diff/progress base and the adoption marker.
+      lastResolvedPerAxis = { ...finalPerAxis }
+      lastAdoptedBoxes = boxes
+      startMeasurePoll()
+      // A queued end/finalize (the flick that ended before the measure landed, review r6
+      // major 1) flushes through the NORMAL lifecycle — the release handoff (or the
+      // cancel-to-pre-grab) starts, then finalize runs its totality/lock law. No motion is
+      // ever silently dropped (G-INV-8).
+      if (pending.endEvent !== undefined) {
+        routeEnd(pending.endEvent.event, pending.endEvent.success)
+      }
+      if (pending.finalized === true) {
+        routeFinalize(pending.endEvent?.event ?? pending.event)
+      }
+    } catch (error) {
+      let finalizeFailure: Error | undefined
+      if (anySessionActive()) {
+        // Post-activation failure — a throwing consumer callback during the begin OR the
+        // queued end/finalize replay (review r7 major 1): the immediate path relies on the
+        // LATER recognizer finalize to clean up, but here the queued terminal events were
+        // already consumed — nothing later cancels. Force the totality path NOW: cancel the
+        // active sessions to pre-grab and free the lock, then report through the channel.
+        grabAborted = true
+        try {
+          routeFinalize(pending.event)
+        } catch (secondary) {
+          // The forced finalize can itself fail (review r8 major 3) — capture, never swallow;
+          // it reports after the primary below.
+          finalizeFailure =
+            secondary instanceof Error ? secondary : new Error(describeValue(secondary))
+        }
+      } else {
+        // Pre-activation failure (snap validation, the hook, liveFor): the begin never completed,
+        // so the rest of the recognizer stream is DEAD (review major 1 — a trailing update
+        // crashed active()-in-'idle' here). A POST-activation failure (a throwing consumer
+        // callback) keeps the gesture: the active session owns the lock until finalize (the D1 law).
+        grabAborted = true
+        if (lockState === 'acquired') {
+          lock.release(lockOwner)
+          lockState = 'open'
+        }
+      }
+      options.reportConstraintFailure?.(
+        error instanceof Error ? error : new Error(describeValue(error)),
+      )
+      if (finalizeFailure !== undefined) {
+        // The forced finalize's own failure (driver/command/info/consumer — G-INV-7's own
+        // vocabulary) rides the channel AFTER the primary, never swallowed (review r8 major 3;
+        // a suppressed secondary would hide a terminal-handoff failure).
+        options.reportConstraintFailure?.(finalizeFailure)
+      }
+    }
+  }
+
+  // The update hot path, shared by the recognizer handler and the deferred-begin flush
+  // (REQ-GESTURE-002: one write per recognizer event — both axes in one write,
+  // REQ-GESTURE-024). Validate the full event before mutating (major 6): buildInfo first,
+  // then each session owns its axis's per-event decision (dead-zone, clamp, elastic) and the
+  // constrained values land together. The write carries the recognizer's per-axis velocities
+  // — the platform numbers, no estimator (release-side C1, G-INV-3): liveFor tracks the
+  // finger velocity so the release seam is continuous (review r4 c14e15).
+  function applyPanUpdate(event: InfoEventShape): void {
+    // Pin updateAxis (VisualElementDragControls.ts:320): on→off mid-drag freezes further
+    // writes. Live empty axes means drag={false} this render.
+    const liveAxes = resolvedDragAxes(getConfig())
+    if (liveAxes.length === 0) return
+    // Direction lock uses RAW pointer translation (pin: lock before constraints apply).
+    const rawX = requireInfoNumber(event.translationX, 'translationX')
+    const rawY = requireInfoNumber(event.translationY, 'translationY')
+    if (config.dragDirectionLock) {
+      if (lockedAxis === null) {
+        const next = resolveDirectionLockAxis(rawX, rawY)
+        if (next === null) return
+        lockedAxis = next
+        if (!directionLockNotified) {
+          directionLockNotified = true
+          callbacks.onDirectionLock?.(next)
+        }
+        return
+      }
+    }
+    const activeAxes = (
+      lockedAxis === null ? axes : axes.filter((axis) => axis === lockedAxis)
+    ).filter((axis) => liveAxes.includes(axis))
+    if (activeAxes.length === 0) return
+    const values: Record<string, number> = {}
+    const velocities: Record<string, number> = {}
+    const velX = requireInfoNumber(event.velocityX, 'velocityX')
+    const velY = requireInfoNumber(event.velocityY, 'velocityY')
+    for (const axis of activeAxes) {
+      values[axis] = bindings[axis]!.onUpdate(event)
+      velocities[axis] = axis === 'x' ? velX : velY
+    }
+    driver.write(handle, values, velocities)
+    // DragInfo after session updates: offset is constrained element displacement (value − grab).
+    const info = buildInfo(event, constrainedOffset())
+    callbacks.onDrag?.(event, info)
+  }
+
+  // The successful-release path (REQ-GESTURE-022), shared by handlePanEnd and the
+  // deferred-begin's queued-end flush (review r6 major 1 — one lifecycle, never forked).
+  function routeEnd(event: DragPanEventShape, success: boolean): void {
+    if (!success) {
+      // Unsuccessful end (RNGH fires onEnd(event,false) before onFinalize): NOT a release —
+      // finalize owns the cancel. routeEnd(false) is a no-op, so there is nothing to do here
+      // and nothing to validate (no release fields consumed).
+      return
+    }
+    // Successful release, in three ordered acts PER AXIS that the pin would startAnimation
+    // for (shouldDrag / currentDirection). R15 D4 seal H1/H1′: under dragDirectionLock a locked
+    // session must not free-drag the unlocked axis on end — beginRelease of a never-updated
+    // axis still sees raw finger translation as "moved" and would catch-up + seed velocity.
+    // Unlock axes cancel-to-live in the SAME issueHandoffs batch (pin: one onDragEnd; never
+    // leave them active for routeFinalize to fire a second terminal).
+    const releaseAxes: readonly DragAxis[] =
+      config.dragDirectionLock && lockedAxis !== null
+        ? axes.filter((axis) => axis === lockedAxis)
+        : axes
+    // 1. COMMIT the final drag sample on every release axis (validate-then-apply; a malformed
+    //    field throws WITHOUT ending that axis's session, so finalize — the totality guarantor —
+    //    cancels it). The end translation is never dropped (G-INV-8; the M1 session commits
+    //    it too, r11 major 32).
+    const releases: Partial<
+      Record<DragAxis, { fingerValue: number; velocity: number; moved: boolean }>
+    > = {}
+    for (const axis of releaseAxes) releases[axis] = bindings[axis]!.beginRelease(event)
+    // 2. Catch the driver up to the finger's final position on every MOVED axis — decided by
+    //    the RAW recognizer translation, NOT the constrained value (r12 major 10): a finger
+    //    dragging PAST a hard bound moves while its clamped value stays pinned at the bound,
+    //    and that movement must re-anchor the contention to the bound. A held axis does NOT
+    //    write, so a contending declarative drift (REQ-DRIVER-026) remains its release origin
+    //    — the animate wrote last (last-writer-wins). ONE write covers every moved axis.
+    const catchUp: Record<string, number> = {}
+    const catchUpVelocities: Record<string, number> = {}
+    for (const axis of releaseAxes) {
+      const release = releases[axis]!
+      if (release.moved) {
+        catchUp[axis] = release.fingerValue
+        catchUpVelocities[axis] = release.velocity
+      }
+    }
+    if (Object.keys(catchUp).length > 0) driver.write(handle, catchUp, catchUpVelocities)
+    // 3. A moved axis starts from the validated constrained sample just written. The live
+    //    driver may queue that write on the UI thread, so a synchronous read here can still
+    //    see the pre-sample value. A held axis performs no write and MUST read the actual live
+    //    contending drift (REQ-GESTURE-022/REQ-DRIVER-025). Then issueHandoffs mutates-then-
+    //    info (terminal totality, r4 759836) with ONE atomic release command.
+    const handoffs: Partial<Record<DragAxis, ReleaseHandoff>> = {}
+    for (const axis of releaseAxes) {
+      const release = releases[axis]!
+      const origin = release.moved ? release.fingerValue : driver.liveFor(handle, axis).value
+      // dragMomentum=false is gated INSIDE the session (R16): the projection velocity itself is
+      // zeroed (settle-at-release), so the handoff arrives already gated — no wiring-side gate.
+      let handoff = bindings[axis]!.finishRelease(release.velocity, origin)
+      // R15 D5: dragSnapToOrigin forces the release target to the origin on the named axes.
+      if (snapToOriginApplies(config, axis)) {
+        handoff =
+          handoff.curve === 'inertia'
+            ? // The pin's zero-bounds inertia ({min:0,max:0}): the generator's boundary spring
+              // pulls the decay to 0 (R16 — REQ-GESTURE-027).
+              {
+                curve: 'inertia',
+                from: handoff.from,
+                velocity: handoff.velocity,
+                target: 0,
+                min: 0,
+                max: 0,
+              }
+            : { curve: 'spring', from: handoff.from, velocity: handoff.velocity, target: 0 }
+      }
+      handoffs[axis] = handoff
+    }
+    // Direction-lock unlock axes: cancel-to-live (no free-drag) in this same handoff batch so
+    // finalize sees all sessions idle and does not re-issue onDragEnd (seal H1′).
+    if (config.dragDirectionLock && lockedAxis !== null) {
+      for (const axis of axes) {
+        if (axis === lockedAxis) continue
+        if (bindings[axis]!.session.state() !== 'active') continue
+        const liveOrigin = driver.liveFor(handle, axis).value
+        const cancelHandoff = bindings[axis]!.routeFinalize(false, liveOrigin)
+        if (cancelHandoff !== null) handoffs[axis] = cancelHandoff
+      }
+    }
+    issueHandoffs(handoffs, event)
+  }
+
+  // The finalize totality path (G-INV-7), shared by handlePanFinalize and the deferred-begin's
+  // queued-finalize flush (review r6 major 1).
+  function routeFinalize(event: DragPanEventShape): void {
+    const state = lockState
+    try {
+      if (state === 'blocked') return
+      // Totality guarantor (G-INV-7, review r4 759836): finalize ALWAYS runs last. If any
+      // axis's session is still active — an unsuccessful end, OR a successful end whose
+      // release-critical fields were malformed and threw — force the cancel to the pre-grab
+      // value (event-independent) via issueHandoffs BEFORE any info build. A successful
+      // release already left every session idle, so this returns. (The RNGH `success` flag is
+      // not needed for the decision — session state is the totality signal.)
+      if (!anySessionActive()) return
+      const handoffs: Partial<Record<DragAxis, ReleaseHandoff>> = {}
+      for (const axis of axes) {
+        if (bindings[axis]!.session.state() !== 'active') continue
+        // The cancel ORIGIN is the driver's LIVE value on that axis at this instant
+        // (REQ-GESTURE-022, symmetric to the release path): starting the return spring from
+        // the finger would rewind a contending declarative drift (REQ-DRIVER-026), a visible
+        // backward jump (r11 major 31). The read is harmless (no mutation, never throws for
+        // the registered axis) so it precedes the totality-guaranteed cancel.
+        const releaseOrigin = driver.liveFor(handle, axis).value
+        const handoff = bindings[axis]!.routeFinalize(false, releaseOrigin)
+        if (handoff !== null) handoffs[axis] = handoff
+      }
+      issueHandoffs(handoffs, event)
+    } finally {
+      // The recognizer stream is over (finalize always runs last): free the lock so the
+      // element blocked behind us can drag next, and reset for the next grab.
+      if (state === 'acquired') lock.release(lockOwner)
+      lockState = 'open'
+    }
+  }
+
+  return {
+    snapToCursor(point, layoutBox) {
+      if (disposed) return
+      // Pin: layout measurement includes the current transform — midpoint is the visual center.
+      const midX = layoutBox.x + layoutBox.width / 2
+      const midY = layoutBox.y + layoutBox.height / 2
+      const values: Partial<Record<DragAxis, number>> = {}
+      const velocities: Partial<Record<DragAxis, number>> = {}
+      for (const axis of axes) {
+        const live = driver.liveFor(handle, axis)
+        const mid = axis === 'x' ? midX : midY
+        const pointer = axis === 'x' ? point.absoluteX : point.absoluteY
+        values[axis] = pointer - mid + live.value
+        velocities[axis] = live.velocity
+      }
+      if (Object.keys(values).length > 0) driver.write(handle, values, velocities)
+    },
+
+    handlePanStart(event) {
+      if (disposed) return
+      const live = getConfig()
+      if (installBindings(live).length === 0) return
+      grabAborted = false // a fresh grab re-arms after an aborted deferred begin
+      gestureEpoch += 1 // a new gesture: in-flight polls from any previous one resolve stale
+      // Direction lock is session-scoped — every grab starts unlocked (REQ-GESTURE-025).
+      lockedAxis = null
+      directionLockNotified = false
+      // REQ-GESTURE-028 deferred-begin PRE-GATE: ref constraints REQUIRE the measure seam — a
+      // host wiring bug, fail-loud BEFORE the lock is ever touched (review r4 minor 5: the
+      // error path used to leak the acquired lock and wedge every later drag).
+      const refAxes = axes.filter((axis) => config[axis]?.constraintsRef !== undefined)
+      if (refAxes.length > 0 && options.measureConstraints === undefined) {
+        throw new Error(
+          'drag wiring: constraintsRef requires the measureConstraints seam (REQ-GESTURE-028; host wiring law).',
+        )
+      }
+      // The lock gate precedes EVERYTHING (REQ-GESTURE-024): a lock-blocked grab consumes
+      // nothing — no validation, no read, no write, no callback — exactly Motion's "the element
+      // simply does not drag" while another non-propagating element holds the lock.
+      if (!dragPropagation) {
+        // The pin's per-axis lock (motion-dom set-active): a single-axis drag takes its axis;
+        // a both-axes drag needs BOTH axes free (atomic — never a partial hold).
+        if (lock.acquire(lockOwner, axes)) {
+          lockState = 'acquired'
+        } else {
+          lockState = 'blocked'
+          return
+        }
+      }
+      // REQ-GESTURE-028 deferred-begin branch: element-ref constraints measure at grab and
+      // begin when the bounds land (native-motion re-measures at EVERY grab — the freshness
+      // superset of the pin's cache-and-invalidate machinery; native measureInWindow is
+      // async, so the value holds C0 meanwhile).
+      if (refAxes.length > 0) {
+        try {
+          lastPoint = null
+          const info = buildInfo(event)
+          // The grab-instant interrupt (REQ-GESTURE-012/-022, review r4 major 2): the live read
+          // + interrupting write happen NOW — an in-flight animation freezes AT the grab (the
+          // pin's synchronous start does this inline). The deferred begin re-reads live when
+          // the measure lands (the same frozen numbers unless a declarative drift contended
+          // meanwhile — REQ-DRIVER-026's live-read law covers that).
+          const interruptValues: Record<string, number> = {}
+          const interruptVelocities: Record<string, number> = {}
+          for (const axis of axes) {
+            const live = driver.liveFor(handle, axis)
+            interruptValues[axis] = live.value
+            interruptVelocities[axis] = live.velocity
+          }
+          driver.write(handle, interruptValues, interruptVelocities)
+          const pending: PendingDeferredGrab = { event, info, updates: [] }
+          pendingGrab = pending
+          void measureWithTimeout(
+            // Non-null: the pre-gate above throws when the seam is absent for ref axes.
+            options.measureConstraints!,
+            config[refAxes[0]!]!.constraintsRef!.ref,
+          ).then(
+            (boxes) => {
+              if (pendingGrab !== pending) return // cancelled meanwhile (finalize/end/dispose)
+              pendingGrab = null
+              beginAfterMeasure(pending, boxes, refAxes)
+            },
+            (cause) => {
+              if (pendingGrab !== pending) return
+              pendingGrab = null
+              grabAborted = true
+              if (lockState === 'acquired') {
+                lock.release(lockOwner)
+                lockState = 'open'
+              }
+              options.reportConstraintFailure?.(
+                cause instanceof Error ? cause : new Error(describeValue(cause)),
+              )
+            },
+          )
+        } catch (error) {
+          cancelPendingGrab()
+          // The failure may precede the pending-grab assignment (buildInfo / liveFor / the
+          // interrupt write) — cancelPendingGrab no-ops then, so free the just-acquired lock
+          // directly (review r5 major 1; the immediate path's catch law: release only when no
+          // session is active).
+          if (lockState === 'acquired' && !anySessionActive()) {
+            lock.release(lockOwner)
+            lockState = 'open'
+          }
+          throw error
+        }
+        return
+      }
+      try {
+        // VALIDATE the FULL consumed event BEFORE any driver/session mutation (review major 6,
+        // G-INV-7/-8): buildInfo reads + fail-loud-validates every field the start path consumes
+        // — BOTH axes' translations (for begin) AND the DragInfo fields (translationX/Y,
+        // velocityX/Y, absoluteX/Y) the onDragStart callback needs. A malformed field throws
+        // HERE, before liveFor/begin/write, so the in-flight animation is never interrupted and
+        // no held-active state is established (buildInfo only touches lastPoint, reset first for
+        // a fresh grab's zero delta — never the driver or sessions). Only after full validation
+        // does the write interrupt at the grabbed values (REQ-DRIVER-024) so the element renders
+        // the same numbers the sessions seeded from (C0, REQ-GESTURE-012). The grab preserves
+        // the interrupted animations' velocities (grab-side C1, G-INV-3): the write carries
+        // live.velocity per axis so liveFor stays continuous across the grab edge until the
+        // first update reports the finger velocity (review r4 c14e15).
+        lastPoint = null
+        for (const axis of axes) delete grabSeeds[axis]
+        const info = buildInfo(event)
+        const values: Record<string, number> = {}
+        const velocities: Record<string, number> = {}
+        for (const axis of axes) {
+          const live = driver.liveFor(handle, axis)
+          bindings[axis]!.onStart(event, { value: live.value })
+          grabSeeds[axis] = live.value
+          values[axis] = live.value
+          velocities[axis] = live.velocity
+        }
+        driver.write(handle, values, velocities)
+        callbacks.onDragStart?.(event, info)
+      } catch (error) {
+        // Free the just-acquired lock ONLY when the failure left no session active (a
+        // pre-mutation validation failure). A POST-activation failure — e.g. a throwing
+        // consumer onDragStart after the sessions began — must NOT free it: the active
+        // session owns the lock until its finalize, and releasing here would admit a
+        // second non-propagating drag while the first still runs (review round-4 major —
+        // the global exclusion contract).
+        if (lockState === 'acquired' && !anySessionActive()) {
+          lock.release(lockOwner)
+          lockState = 'open'
+        }
+        throw error
+      }
+    },
+
+    handlePanUpdate(event) {
+      if (disposed || lockState === 'blocked' || grabAborted) return
+      // A deferred begin is in flight (REQ-GESTURE-028): buffer updates — they flush in order
+      // when the measured bounds land (fail-loud validation happens at the flush).
+      if (pendingGrab !== null) {
+        // Bounded buffer (review r4 minor 7): a measure pending past the cap is pathological —
+        // refuse the grab through the channel rather than retain events indefinitely.
+        if (pendingGrab.updates.length >= MAX_BUFFERED_PAN_UPDATES) {
+          cancelPendingGrab()
+          options.reportConstraintFailure?.(
+            new Error(
+              `deferred begin buffered ${MAX_BUFFERED_PAN_UPDATES} pan updates without the ` +
+                'measure landing — the grab is refused (REQ-GESTURE-028; the bounded-buffer law).',
+            ),
+          )
+          return
+        }
+        pendingGrab.updates.push(event)
+        return
+      }
+      applyPanUpdate(event)
+    },
+
+    handlePanEnd(event, success) {
+      if (disposed || lockState === 'blocked' || grabAborted) return
+      gestureEpoch += 1 // the stream ends: an in-flight poll resolves stale from here
+      // An end before the measure lands QUEUES on the pending grab (review r6 major 1 — never
+      // a silent drop): the full lifecycle flushes when the measure resolves.
+      if (pendingGrab !== null) {
+        pendingGrab.endEvent = { event, success }
+        return
+      }
+      routeEnd(event, success)
+    },
+
+    handlePanFinalize(event) {
+      if (disposed) return
+      gestureEpoch += 1 // finalize is the terminal edge: in-flight polls resolve stale
+      // A finalize before the measure lands queues with the pending end (review r6 major 1).
+      if (pendingGrab !== null) {
+        pendingGrab.finalized = true
+        return
+      }
+      routeFinalize(event)
+    },
+
+    dispose() {
+      // Idempotent: MotionView's cleanup and a stray recognizer path may both reach here. The
+      // lock frees only if THIS wiring holds it (release is owner-checked by the lock itself).
+      if (disposed) return
+      disposed = true
+      stopPoll() // the mid-drag re-measure loop dies with its wiring
+      cancelPendingGrab() // a measure in flight never begins after unmount (review r4 major 1)
+      if (lockState === 'acquired') lock.release(lockOwner)
+      lockState = 'open'
+    },
+
+    sessions,
+  }
+}