@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/dragHandoffBinding.ts

@@ -0,0 +1,179 @@
+// REQ-GESTURE-022 at the binding altitude (FLAG 5a, specs/SPEC-GESTURE.md) —
+// the per-axis HANDOFF binding: platform Pan events → validated translations/velocities →
+// handoff-session calls. The session owns EVERY semantic (dead-zone, clamp, elastic, release
+// target selection — REQ-GESTURE-011/-015/-016/-017); this layer owns exactly the M2.4 binding's
+// two concerns: (a) fail-loud event-shape validation (never coerce a missing field to 0 — the
+// M2.2/M2.3 boundary lesson) and (b) the A3 axis parametrization: 'x' reads
+// translationX/velocityX, 'y' reads translationY/velocityY — never a cross-axis coercion. No
+// clock: the handoff session is a time-free event fold; the driver owns integration time.
+//
+// RNGH end/finalize routing (review cycle 1 of the M2.4 binding, carried verbatim):
+// gesture-handler fires `onEnd(event, false)` for gestures that FAIL or are CANCELLED — before
+// `onFinalize(event, false)`. Only a SUCCESSFUL end is a release; an unsuccessful end must leave
+// the session active so the finalize path can cancel to the pre-grab value (REQ-GESTURE-018
+// totality). routeEnd/routeFinalize ARE the component's wiring, exported so tests drive the
+// exact routing.
+
+import {
+  createGestureHandoffSession,
+  describeValue,
+  type DragAxis,
+  type DragConstraints,
+  type GestureHandoffSession,
+  type ReleaseHandoff,
+  type ResolvedDragAxisConfig,
+} from '@unrulysystems/native-motion-core'
+
+// The fields this binding reads off a gesture-handler Pan event, both axes. Kept loose (unknown)
+// because the validation IS the contract — a malformed event fails loud at this boundary.
+export interface DragPanEventShape {
+  readonly translationX?: unknown
+  readonly translationY?: unknown
+  readonly velocityX?: unknown
+  readonly velocityY?: unknown
+}
+
+export interface DragHandoffBinding {
+  // `seed.value` is the driver's live value at the grab instant (REQ-DRIVER-025 → REQ-GESTURE-012).
+  // `constraints` are the GRAB-TIME measured bounds for the element-ref channel
+  // (REQ-GESTURE-028): applied to this grab only, replacing the constructed config.
+  onStart(
+    event: DragPanEventShape,
+    seed: { readonly value: number },
+    constraints?: DragConstraints,
+  ): void
+  onUpdate(event: DragPanEventShape): number
+  // `releaseOrigin` is the driver's LIVE value at the release instant (REQ-DRIVER-025), threaded from
+  // the wiring (which owns the driver): the handoff ORIGIN, so a contending declarative drift on the
+  // axis (REQ-DRIVER-026) selects the release/snap target, not the finger-tracked session value.
+  onEnd(event: DragPanEventShape, releaseOrigin: number): ReleaseHandoff
+  // The release edge split into two phases so the wiring can reconcile the DRIVER between them
+  // (r11 major 32). `beginRelease` validates both release fields (fail-loud, no half-apply) and
+  // COMMITS the final drag sample to the session (G-INV-8: the end translation is never dropped — the
+  // M1 session commits it too), returning the finger's final value (so the wiring can catch the driver
+  // up iff the finger moved) and the platform velocity. `finishRelease` then finalizes from the
+  // driver's live origin (contention-aware). `onEnd` is `beginRelease`+`finishRelease` with no driver
+  // reconcile (the test/routing path passes the origin directly).
+  beginRelease(event: DragPanEventShape): {
+    readonly fingerValue: number
+    readonly velocity: number
+    // Whether the finger MOVED since the last update, by RAW translation (r12 major 10): true even
+    // when a hard clamp pins the constrained value, so the caller catches the driver up to the bound.
+    readonly moved: boolean
+  }
+  finishRelease(velocity: number, releaseOrigin: number): ReleaseHandoff
+  // RNGH routing: a successful end releases; an unsuccessful one returns null and leaves the
+  // session active for routeFinalize to cancel.
+  routeEnd(event: DragPanEventShape, success: boolean, releaseOrigin: number): ReleaseHandoff | null
+  // `releaseOrigin` is the driver's LIVE value at the finalize instant (REQ-DRIVER-025): the cancel
+  // return spring starts from it, not the finger, so a contending drift does not rewind (r11 major 31).
+  routeFinalize(success: boolean, releaseOrigin: number): ReleaseHandoff | null
+  readonly session: GestureHandoffSession
+}
+
+// Fail-loud field extraction (the M2.4 binding's rule verbatim): a missing or non-numeric
+// recognizer field is a caller/platform bug — naming the field beats silently coercing to 0.
+function requireNumber(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 produces this typed error naming the field, never a raw JSON.stringify crash.
+    throw new Error(
+      `drag binding: Pan event field '${field}' is ${describeValue(value)} — a finite number ` +
+        'is required and is never coerced (specs/SPEC-GESTURE.md).',
+    )
+  }
+  return value
+}
+
+export function createDragHandoffBinding(
+  axis: DragAxis,
+  config: ResolvedDragAxisConfig,
+  momentum?: boolean,
+): DragHandoffBinding {
+  const session = createGestureHandoffSession({
+    ...(config.constraints === undefined ? {} : { constraints: config.constraints }),
+    ...(config.snap === undefined ? {} : { snap: config.snap }),
+    // REQ-GESTURE-027 (R16): momentum gating moved INTO the session so the projection velocity
+    // itself is zeroed (settle-at-release), not merely the integrator seed.
+    ...(momentum === undefined ? {} : { momentum }),
+  })
+  // Axis field selection (packet A3): exactly the declared axis's fields, never a fallback pair.
+  const translationField = axis === 'x' ? 'translationX' : 'translationY'
+  const velocityField = axis === 'x' ? 'velocityX' : 'velocityY'
+  // The last RAW recognizer translation applied (grab or drag). The release edge decides "did the
+  // finger move" from THIS — the raw translation, not the constrained value: a finger dragging PAST a
+  // hard bound moves while its clamped value stays pinned at the bound (r12 major 10). Null between
+  // gestures; each grab reseeds it.
+  let lastTranslation: number | null = null
+  // Last finite platform velocity applied on an update (or grab). Some recognizers report near-zero
+  // velocity on end after a fling sample already carried momentum on the prior update — seed release
+  // from the larger of |end velocity| and |last update velocity| so free-drag projection and boundary
+  // spring-back are not silently dropped (M2 r2: fling freeze at end pose with ends:1).
+  let lastUpdateVelocity = 0
+
+  function translation(event: DragPanEventShape): number {
+    return requireNumber(event[translationField], translationField)
+  }
+
+  function releaseVelocity(endVelocity: number): number {
+    // Prefer the end sample when it carries magnitude; otherwise the last update's velocity.
+    if (Math.abs(endVelocity) >= Math.abs(lastUpdateVelocity)) return endVelocity
+    return lastUpdateVelocity
+  }
+
+  const binding: DragHandoffBinding = {
+    onStart(event, seed, constraints) {
+      const t = translation(event)
+      session.begin(t, seed, constraints === undefined ? undefined : { constraints })
+      lastTranslation = t
+      lastUpdateVelocity = 0
+    },
+    onUpdate(event) {
+      // Validate BEFORE the session call so a malformed event never half-applies, then return the
+      // constrained value for the caller's driver write (REQ-DRIVER-024).
+      const t = translation(event)
+      const v = requireNumber(event[velocityField], velocityField)
+      session.active(t)
+      lastTranslation = t
+      lastUpdateVelocity = v
+      return session.value()
+    },
+    onEnd(event, releaseOrigin) {
+      // The release edge with NO driver reconcile (the test/routing path supplies the origin directly):
+      // commit the final sample, then finalize from the passed origin.
+      const { velocity } = binding.beginRelease(event)
+      return binding.finishRelease(velocity, releaseOrigin)
+    },
+    beginRelease(event) {
+      // Both fields validate BEFORE any session mutation: a malformed release leaves the session active
+      // at its last good value, never half-released (major 6 law). Then COMMIT the final drag sample
+      // (session.active) so session.value() / the onDragEnd info reflect the finger's final position —
+      // the M1 session commits the end sample too; dropping it violates G-INV-8 (r11 major 32).
+      const t = translation(event)
+      const endV = requireNumber(event[velocityField], velocityField)
+      const v = releaseVelocity(endV)
+      // "Moved" is decided on the RAW translation, not the constrained value (r12 major 10): a finger
+      // dragging past a hard bound changes translation while its clamped value stays pinned. A held
+      // finger reports the same translation ⇒ not moved ⇒ the caller preserves a contending drift.
+      const moved = lastTranslation === null || t !== lastTranslation
+      session.active(t)
+      lastTranslation = t
+      return { fingerValue: session.value(), velocity: v, moved }
+    },
+    finishRelease(velocity, releaseOrigin) {
+      // Finalize from the driver's live origin (contention-aware, REQ-GESTURE-022): the finger's final
+      // position if it moved, or the contending drift if it held.
+      return session.end(velocity, releaseOrigin)
+    },
+    routeEnd(event, success, releaseOrigin) {
+      if (!success) return null
+      return binding.onEnd(event, releaseOrigin)
+    },
+    routeFinalize(success, releaseOrigin) {
+      if (!success && session.state() === 'active') return session.cancel(releaseOrigin)
+      return null
+    },
+    session,
+  }
+  return binding
+}