@unrulysystems/native-motion 0.1.0-alpha.0

package/src/native/motion/dragHubStream.ts

@@ -0,0 +1,756 @@
+// REQ-GESTURE-026 / REQ-API-043 (R15 D3) — MotionRoot hub touch stream (packet Finding 8).
+//
+// The pin's DragControls.start creates a window-level PanSession so a sibling handle works.
+// Native has no window pointer tracking: MotionRoot hosts a manual-activation pan that
+// records touches, stays inert until a hub start correlates a touch, then activates and
+// drives the subscribed wiring with the recognizer's own translation/velocity stream
+// (REQ-GESTURE-014 — no estimator).
+//
+// Pure stream state machine — MotionRoot binds it to Gesture.Pan(); MotionView registers
+// its wiring as the hub-start target.
+
+import type { DragControlOptions } from '@unrulysystems/native-motion-core'
+import type { DragGestureWiring } from './dragGestureWiring'
+import type { DragPanEventShape } from './dragHandoffBinding'
+
+/** Screen-space point used for touch↔start correlation. */
+export interface HubTouchPoint {
+  readonly id: number
+  readonly absoluteX: number
+  readonly absoluteY: number
+}
+
+/** A pending down-touch recorded by the root pan before a hub start arms it. */
+export interface RecordedHubTouch {
+  readonly point: HubTouchPoint
+  readonly recordedAtMs: number
+}
+
+/** Page-point correction from MotionConfig (REQ-API-043 ingest boundary). */
+export type HubPagePointTransform = (point: { readonly x: number; readonly y: number }) => {
+  readonly x: number
+  readonly y: number
+}
+
+/** One armed hub session: correlated touch + wiring + start options. */
+export interface ArmedHubSession {
+  readonly touchId: number
+  readonly originAbsoluteX: number
+  readonly originAbsoluteY: number
+  readonly wiring: DragGestureWiring
+  readonly options: DragControlOptions
+  /** True after the first onStart / activation past distanceThreshold. */
+  activated: boolean
+  /**
+   * When true, pan updates are held until snapToCursor's measure lands — the sanctioned
+   * G-INV-2 jump must complete before tracking (REQ-GESTURE-026; seal review major).
+   */
+  pendingSnap: boolean
+  /** Grab-origin absolute position for snapToCursor / dead-zone math (screen-raw). */
+  readonly startAbsoluteX: number
+  readonly startAbsoluteY: number
+  /** Optional page-point transform applied to absolute coords at the event feed. */
+  readonly transformPagePoint: HubPagePointTransform | undefined
+  /** Arm-time report sink for transform/lifecycle failures (G-INV-8; never silent). */
+  readonly report: ((error: Error) => void) | undefined
+  /** Latest translated payload (for hub stop/cancel with real absolute coords). */
+  lastPayload:
+    | (DragPanEventShape & { readonly absoluteX: number; readonly absoluteY: number })
+    | null
+  /** Monotonic arm epoch — stale snap measure callbacks refuse when mismatched. */
+  readonly armEpoch: number
+}
+
+export type HubPanPayload = DragPanEventShape & {
+  readonly absoluteX: number
+  readonly absoluteY: number
+}
+
+// U7d (REQ-API-030 global form, packet F1/F2) — the tap-observation channel. The pin's global
+// press observes window pointer events without competing; the hub stream is its native analog:
+// an ADDITIVE subscriber view of the root touches. Observation is unconditional — a child
+// recognizer claiming the touch (or an armed hub drag) never suppresses it (F2).
+export interface HubTapTouchPoint {
+  readonly id: number
+  readonly absoluteX: number
+  readonly absoluteY: number
+}
+
+export interface HubTapObserver {
+  /** `primary` is true for the FIRST touch of a multi-touch sequence (pin isPrimaryPointer). */
+  onTouchDown(touch: HubTapTouchPoint, primary: boolean): void
+  onTouchUp(touch: HubTapTouchPoint): void
+  onTouchCancel(touch: HubTapTouchPoint): void
+}
+
+export interface DragHubStream {
+  /** Record a down-touch (root pan onTouchesDown). */
+  recordTouch(point: HubTouchPoint, nowMs?: number): void
+  /** Drop a touch that ended without arming (onTouchesUp/Cancelled). */
+  forgetTouch(id: number): void
+  /**
+   * Arm the stream for a hub-originated session.
+   * Correlates `startPoint` against recorded touches (nearest within TOLERANCE_PX).
+   * Ambiguous multi-touch (two equally near) fails loud when severity is development.
+   * Returns false when no touch correlates (fail-closed — no silent free-drag).
+   */
+  arm(input: {
+    readonly wiring: DragGestureWiring
+    readonly options: DragControlOptions
+    readonly startPoint: { readonly absoluteX: number; readonly absoluteY: number }
+    readonly report?: ((error: Error) => void) | undefined
+    /** When true, hold pan feed until `releaseSnapGate()` (snapToCursor measure). */
+    readonly pendingSnap?: boolean | undefined
+    /** Page-point correction applied to absolute coords at the event feed. */
+    readonly transformPagePoint?: HubPagePointTransform | undefined
+  }): boolean
+  /** Current armed session, if any. */
+  readonly armed: ArmedHubSession | null
+  /**
+   * Current arm epoch (0 when never armed). Snap measure callbacks capture the epoch at
+   * start and refuse to apply when it no longer matches (cancel / re-arm raced the measure).
+   */
+  readonly armEpoch: number
+  /**
+   * Root pan activated — feed start to the wiring with translation relative to arm origin.
+   * distanceThreshold gates the first activation (default 3, pin PanSession).
+   */
+  onPanStart(
+    event: DragPanEventShape & { readonly absoluteX?: number; readonly absoluteY?: number },
+  ): void
+  onPanUpdate(
+    event: DragPanEventShape & { readonly absoluteX?: number; readonly absoluteY?: number },
+  ): void
+  onPanEnd(event: DragPanEventShape, success: boolean): void
+  onPanFinalize(event: DragPanEventShape, success: boolean): void
+  /**
+   * Clear the snap gate so tracking may begin (called after snapToCursor measure/write).
+   * Flushes a held first-move if one arrived while pending.
+   */
+  releaseSnapGate(): void
+  /**
+   * Hub cancel/stop terminal: if activated, end the wiring with the latest payload
+   * (absolute coords preserved); always disarm so later moves cannot revive the session.
+   */
+  terminate(success: boolean): void
+  /** Clear armed state without wiring end (prefer `terminate` for product cancel/stop). */
+  disarm(): void
+  /** Bound for recorded-but-unarmed touch retention (ms). */
+  readonly touchTtlMs: number
+  /**
+   * U7d: subscribe to the root tap-observation channel. Returns the unsubscribe. Dispatch is
+   * synchronous from the root pan's touch handlers, never suppressed by recognizer claims.
+   */
+  subscribeTapObserver(observer: HubTapObserver): () => void
+  /**
+   * Root pan onTouchesDown feed — CHANGED touches only (one notification per physical down).
+   * The stream owns the multi-touch law: the first touch of a sequence notifies `primary`.
+   */
+  notifyTapDown(touch: HubTapTouchPoint): void
+  /** Root pan onTouchesUp feed (changed touches). Untracked ids notify nothing. */
+  notifyTapUp(touch: HubTapTouchPoint): void
+  /** Root pan onTouchesCancelled feed (changed touches) — the press's only cancel source. */
+  notifyTapCancel(touch: HubTapTouchPoint): void
+}
+
+/** Correlation radius (screen px) for matching start() to a recorded touch. */
+export const HUB_TOUCH_CORRELATION_PX = 24
+/** Unarmed touches older than this are dropped on the next record (bounded retention). */
+export const HUB_TOUCH_TTL_MS = 2000
+/** Pin PanSession default distanceThreshold. */
+export const HUB_DEFAULT_DISTANCE_THRESHOLD = 3
+
+function hypot(dx: number, dy: number): number {
+  return Math.sqrt(dx * dx + dy * dy)
+}
+
+function eventTranslation(
+  event: DragPanEventShape & { readonly absoluteX?: number; readonly absoluteY?: number },
+  originX: number,
+  originY: number,
+  transform?: HubPagePointTransform,
+): HubPanPayload {
+  // Prefer recognizer translation when present (after activation); otherwise derive from absolute.
+  // ALWAYS carry absoluteX/Y — handlePanStart's buildInfo (REQ-API-020 DragInfo) requires them
+  // (device crash 2026-08-05: stripped absolutes → loud absoluteX undefined on hub touch-feed).
+  const hasTx = typeof event.translationX === 'number' && Number.isFinite(event.translationX)
+  const hasTy = typeof event.translationY === 'number' && Number.isFinite(event.translationY)
+  let ax =
+    typeof event.absoluteX === 'number' && Number.isFinite(event.absoluteX)
+      ? event.absoluteX
+      : hasTx
+        ? originX + (event.translationX as number)
+        : originX
+  let ay =
+    typeof event.absoluteY === 'number' && Number.isFinite(event.absoluteY)
+      ? event.absoluteY
+      : hasTy
+        ? originY + (event.translationY as number)
+        : originY
+  // Ingest-boundary page-point correction (REQ-API-043): absolute coords only — translations
+  // stay screen-delta so dead-zone / distanceThreshold stay correlation-space consistent.
+  // Transform throws are reported then rethrown for the caller to terminate (G-INV-7/8;
+  // seal review r7 major — never silent raw-coordinate fallback).
+  if (transform !== undefined) {
+    const corrected = transform({ x: ax, y: ay })
+    ax = corrected.x
+    ay = corrected.y
+  }
+  if (hasTx && hasTy) {
+    return {
+      absoluteX: ax,
+      absoluteY: ay,
+      translationX: event.translationX,
+      translationY: event.translationY,
+      velocityX: typeof event.velocityX === 'number' ? event.velocityX : 0,
+      velocityY: typeof event.velocityY === 'number' ? event.velocityY : 0,
+    }
+  }
+  return {
+    absoluteX: ax,
+    absoluteY: ay,
+    translationX: ax - originX,
+    translationY: ay - originY,
+    velocityX: typeof event.velocityX === 'number' ? event.velocityX : 0,
+    velocityY: typeof event.velocityY === 'number' ? event.velocityY : 0,
+  }
+}
+
+function originPayload(session: ArmedHubSession): HubPanPayload {
+  // Prefer lastPayload; origin is only used when no move landed. Transform failure here
+  // must not throw out of terminate and must not call report (dev report throws before
+  // cleanup — seal review r8 major). Raw origin is the safe terminal fallback.
+  let ax = session.originAbsoluteX
+  let ay = session.originAbsoluteY
+  if (session.transformPagePoint !== undefined) {
+    try {
+      const corrected = session.transformPagePoint({ x: ax, y: ay })
+      ax = corrected.x
+      ay = corrected.y
+    } catch {
+      // Keep raw origin — never throw / report from this pure helper.
+    }
+  }
+  return {
+    absoluteX: ax,
+    absoluteY: ay,
+    translationX: 0,
+    translationY: 0,
+    velocityX: 0,
+    velocityY: 0,
+  }
+}
+
+function asError(error: unknown, fallback: string): Error {
+  return error instanceof Error ? error : new Error(fallback)
+}
+
+/** Sentinel distinct from every possible thrown value (including `undefined`). */
+const NO_RETAINED = Symbol('dragHubStream.noRetained')
+
+/**
+ * Create a pure hub stream. MotionRoot owns one instance for the tree lifetime.
+ */
+export function createDragHubStream(options?: {
+  readonly touchTtlMs?: number
+  readonly correlationPx?: number
+  readonly now?: () => number
+}): DragHubStream {
+  const touchTtlMs = options?.touchTtlMs ?? HUB_TOUCH_TTL_MS
+  const correlationPx = options?.correlationPx ?? HUB_TOUCH_CORRELATION_PX
+  const now = options?.now ?? (() => Date.now())
+
+  const recorded = new Map<number, RecordedHubTouch>()
+  let armed: ArmedHubSession | null = null
+  let armEpoch = 0
+
+  // U7d tap-observation channel state. Deliberately separate from `recorded` (the drag
+  // correlation store): recorded entries TTL-prune, but an observed touch lives exactly
+  // down→up/cancel — a long-held touch must not age out of the press's primary tracking.
+  const tapObservers = new Set<HubTapObserver>()
+  const activeTapTouches = new Map<number, HubTapTouchPoint>()
+
+  function prune(nowMs: number): void {
+    for (const [id, touch] of recorded) {
+      if (nowMs - touch.recordedAtMs > touchTtlMs) recorded.delete(id)
+    }
+  }
+
+  /** Clear stream arm state after wiring terminal paths (always, G-INV-7). */
+  function clearArmed(session: ArmedHubSession): void {
+    recorded.delete(session.touchId)
+    recorded.delete(-1)
+    armEpoch += 1
+    armed = null
+  }
+
+  /**
+   * Run end then finalize, retaining the first failure. Cleanup always runs first;
+   * report/rethrow only AFTER clear so a throwing dev reporter cannot strand armed (r8).
+   */
+  function endFinalizeRetain(
+    session: ArmedHubSession,
+    payload: HubPanPayload,
+    success: boolean,
+  ): unknown {
+    let retained: unknown = NO_RETAINED
+    if (session.activated) {
+      try {
+        session.wiring.handlePanEnd(payload, success)
+      } catch (error) {
+        retained = error
+      }
+      try {
+        session.wiring.handlePanFinalize(payload, success)
+      } catch (error) {
+        if (retained === NO_RETAINED) retained = error
+      }
+    }
+    return retained
+  }
+
+  function reportAfterClear(session: ArmedHubSession, retained: unknown): void {
+    // NO_RETAINED is the only “none” sentinel — `throw undefined` is still a failure (r9 minor).
+    if (retained === NO_RETAINED) return
+    const err = asError(retained, 'DragControls: terminal wiring callback failed')
+    session.report?.(err)
+    throw retained === undefined
+      ? new Error('DragControls: terminal wiring callback failed (threw undefined)')
+      : retained
+  }
+
+  /** Translate event; on transform throw abort session AFTER cleanup (G-INV-7/8; seal r7/r8). */
+  function translateOrAbort(
+    event: DragPanEventShape & { readonly absoluteX?: number; readonly absoluteY?: number },
+  ): HubPanPayload | null {
+    if (armed === null) return null
+    try {
+      return eventTranslation(
+        event,
+        armed.originAbsoluteX,
+        armed.originAbsoluteY,
+        armed.transformPagePoint,
+      )
+    } catch (error) {
+      // Abort without re-entering transform: use lastPayload or raw origin.
+      // NEVER report before cleanup — development report throws (seal r8 major).
+      const session = armed
+      const payload =
+        session.lastPayload ??
+        ({
+          absoluteX: session.originAbsoluteX,
+          absoluteY: session.originAbsoluteY,
+          translationX: 0,
+          translationY: 0,
+          velocityX: 0,
+          velocityY: 0,
+        } satisfies HubPanPayload)
+      const retained = endFinalizeRetain(session, payload, false)
+      clearArmed(session)
+      // Prefer the transform failure as the primary report; still surface wiring failures.
+      const primary = error
+      try {
+        session.report?.(
+          asError(primary, 'DragControls: transformPagePoint failed during pan feed'),
+        )
+      } catch {
+        // report threw (dev) — still rethrow primary below
+      }
+      if (retained !== NO_RETAINED) {
+        try {
+          session.report?.(asError(retained, 'DragControls: terminal wiring callback failed'))
+        } catch {
+          /* primary rethrow wins */
+        }
+      }
+      throw asError(primary, 'DragControls: transformPagePoint failed during pan feed')
+    }
+  }
+
+  return {
+    touchTtlMs,
+    get armed() {
+      return armed
+    },
+    get armEpoch() {
+      return armEpoch
+    },
+
+    recordTouch(point, nowMs = now()) {
+      prune(nowMs)
+      recorded.set(point.id, { point, recordedAtMs: nowMs })
+      // Same-frame recovery: hub arm may have used synthetic touch id -1 when Pressable
+      // onPressIn beat onTouchesDown. When the real touch lands, rebind armed.touchId so
+      // MotionRoot's touchId-filtered feed accepts moves (seal review r4 major). Drop the
+      // synthetic -1 entry so a later same-frame start is not blocked by recorded.size > 0
+      // with a stale synthetic (seal review r7 major).
+      if (
+        armed !== null &&
+        armed.touchId === -1 &&
+        hypot(point.absoluteX - armed.originAbsoluteX, point.absoluteY - armed.originAbsoluteY) <=
+          correlationPx
+      ) {
+        recorded.delete(-1)
+        armed = { ...armed, touchId: point.id }
+      }
+    },
+
+    forgetTouch(id) {
+      recorded.delete(id)
+      // Do NOT terminate an activated session here — onTouchesUp fires before recognizer
+      // onEnd on Android; ending early drops real velocity (seal review r2 major).
+      // Pre-activation arm for this touch is cleared by terminate from onTouchesUp.
+      // Synthetic -1: any real-touch forget means the press ended before rebind (Issue 3).
+      if (armed !== null && !armed.activated && (armed.touchId === id || armed.touchId === -1)) {
+        recorded.delete(-1)
+        armed = null
+      }
+    },
+
+    arm(input) {
+      const nowMs = now()
+      prune(nowMs)
+      // Same-frame start race (device product walk 2026-08-05): Pressable.onPressIn runs on the
+      // JS thread BEFORE the root pan's onTouchesDown worklet→JS hop lands, so `recorded` can
+      // still be empty when start() arms. The pin's PanSession does not need a prior record —
+      // the start event IS the touch. Synthesize a touch from the start point so arm succeeds;
+      // the next onTouchesMove still activates the recognizer (Finding 8).
+      if (recorded.size === 0) {
+        recorded.set(-1, {
+          point: {
+            id: -1,
+            absoluteX: input.startPoint.absoluteX,
+            absoluteY: input.startPoint.absoluteY,
+          },
+          recordedAtMs: nowMs,
+        })
+      }
+      // Nearest recorded touch within correlation radius.
+      let best: { id: number; dist: number; touch: RecordedHubTouch } | null = null
+      let secondDist = Number.POSITIVE_INFINITY
+      for (const [id, touch] of recorded) {
+        const dist = hypot(
+          touch.point.absoluteX - input.startPoint.absoluteX,
+          touch.point.absoluteY - input.startPoint.absoluteY,
+        )
+        if (dist > correlationPx) continue
+        if (best === null || dist < best.dist) {
+          secondDist = best?.dist ?? Number.POSITIVE_INFINITY
+          best = { id, dist, touch }
+        } else if (dist < secondDist) {
+          secondDist = dist
+        }
+      }
+      if (best === null) {
+        input.report?.(
+          new Error(
+            `DragControls.start: no recorded touch within ${correlationPx}px of the start point ` +
+              `(REQ-GESTURE-026; packet Finding 8).`,
+          ),
+        )
+        return false
+      }
+      // Ambiguous: two touches equally near (within 1px of each other as nearest).
+      if (Number.isFinite(secondDist) && Math.abs(secondDist - best.dist) < 1) {
+        input.report?.(
+          new Error(
+            'DragControls.start: ambiguous multi-touch correlation — refuse rather than guess ' +
+              '(REQ-GESTURE-026; packet Finding 8).',
+          ),
+        )
+        return false
+      }
+      // One session at a time: terminal any prior arm BEFORE overwrite so an activated
+      // session cannot strand the app-global lock (adversarial seal Issue 4).
+      // Multi-subscriber last-writer remains documented; this makes re-arm well-defined.
+      if (armed !== null) {
+        try {
+          terminateSession(false)
+        } catch {
+          // Prior terminal failures are reported inside terminate; still install the new arm.
+        }
+      }
+      armEpoch += 1
+      armed = {
+        touchId: best.id,
+        originAbsoluteX: best.touch.point.absoluteX,
+        originAbsoluteY: best.touch.point.absoluteY,
+        wiring: input.wiring,
+        options: input.options,
+        activated: false,
+        pendingSnap: input.pendingSnap === true,
+        startAbsoluteX: input.startPoint.absoluteX,
+        startAbsoluteY: input.startPoint.absoluteY,
+        transformPagePoint: input.transformPagePoint,
+        report: input.report,
+        lastPayload: null,
+        armEpoch,
+      }
+      return true
+    },
+
+    onPanStart(event) {
+      if (armed === null) return
+      const translated = translateOrAbort(event)
+      if (translated === null) return
+      armed.lastPayload = translated
+      if (armed.pendingSnap) return // hold until snapToCursor lands
+      const threshold =
+        typeof armed.options.distanceThreshold === 'number'
+          ? armed.options.distanceThreshold
+          : HUB_DEFAULT_DISTANCE_THRESHOLD
+      const moved = hypot(
+        typeof translated.translationX === 'number' ? translated.translationX : 0,
+        typeof translated.translationY === 'number' ? translated.translationY : 0,
+      )
+      if (moved < threshold && !armed.activated) {
+        // Below threshold: wait for updates (pin distanceThreshold gate).
+        return
+      }
+      if (!armed.activated) {
+        armed.activated = true
+        armed.wiring.handlePanStart(translated)
+      }
+    },
+
+    onPanUpdate(event) {
+      if (armed === null) return
+      const translated = translateOrAbort(event)
+      if (translated === null) return
+      armed.lastPayload = translated
+      if (armed.pendingSnap) return // hold until snapToCursor lands
+      const threshold =
+        typeof armed.options.distanceThreshold === 'number'
+          ? armed.options.distanceThreshold
+          : HUB_DEFAULT_DISTANCE_THRESHOLD
+      if (!armed.activated) {
+        const moved = hypot(
+          typeof translated.translationX === 'number' ? translated.translationX : 0,
+          typeof translated.translationY === 'number' ? translated.translationY : 0,
+        )
+        if (moved < threshold) return
+        armed.activated = true
+        armed.wiring.handlePanStart(translated)
+      }
+      armed.wiring.handlePanUpdate(translated)
+    },
+
+    onPanEnd(event, success) {
+      if (armed === null) return
+      const translated = translateOrAbort(event)
+      if (translated === null) return
+      armed.lastPayload = translated
+      if (armed.activated) {
+        // End may throw (consumer onDragEnd) — leave armed for finalize (RNGH ordering).
+        armed.wiring.handlePanEnd(translated, success)
+      }
+      // Keep armed until finalize (RNGH ordering).
+    },
+
+    onPanFinalize(event, success) {
+      if (armed === null) return
+      // Always clear armed even if finalize/end wiring throws (G-INV-7; seal review r6 major).
+      // Transform failure still finalizes with lastPayload/raw origin so the app-global lock
+      // releases (seal review r8 major).
+      const session = armed
+      let retained: unknown = NO_RETAINED
+      let transformError: unknown = NO_RETAINED
+      let translated: HubPanPayload
+      try {
+        translated = eventTranslation(
+          event,
+          session.originAbsoluteX,
+          session.originAbsoluteY,
+          session.transformPagePoint,
+        )
+      } catch (error) {
+        transformError = error
+        translated =
+          session.lastPayload ??
+          ({
+            absoluteX: session.originAbsoluteX,
+            absoluteY: session.originAbsoluteY,
+            translationX: 0,
+            translationY: 0,
+            velocityX: 0,
+            velocityY: 0,
+          } satisfies HubPanPayload)
+      }
+      if (session.activated) {
+        try {
+          session.wiring.handlePanFinalize(translated, success)
+        } catch (error) {
+          retained = error
+        }
+      }
+      clearArmed(session)
+      if (transformError !== NO_RETAINED) {
+        try {
+          session.report?.(
+            asError(transformError, 'DragControls: transformPagePoint failed at finalize'),
+          )
+        } catch {
+          /* report may throw in development */
+        }
+      }
+      if (retained !== NO_RETAINED) reportAfterClear(session, retained)
+      if (transformError !== NO_RETAINED) {
+        throw transformError === undefined
+          ? new Error('DragControls: transformPagePoint failed at finalize (threw undefined)')
+          : asError(transformError, 'DragControls: transformPagePoint failed at finalize')
+      }
+    },
+
+    releaseSnapGate() {
+      if (armed === null || !armed.pendingSnap) return
+      armed.pendingSnap = false
+      // If a move was held, flush it as the first start/update so the session begins
+      // after the sanctioned jump (REQ-GESTURE-026).
+      const held = armed.lastPayload
+      if (held === null) return
+      const threshold =
+        typeof armed.options.distanceThreshold === 'number'
+          ? armed.options.distanceThreshold
+          : HUB_DEFAULT_DISTANCE_THRESHOLD
+      if (!armed.activated) {
+        const moved = hypot(
+          typeof held.translationX === 'number' ? held.translationX : 0,
+          typeof held.translationY === 'number' ? held.translationY : 0,
+        )
+        if (moved < threshold) return
+        armed.activated = true
+        armed.wiring.handlePanStart(held)
+      }
+      armed.wiring.handlePanUpdate(held)
+    },
+
+    terminate(success) {
+      terminateSession(success)
+    },
+
+    disarm() {
+      if (armed !== null) armEpoch += 1
+      armed = null
+    },
+
+    subscribeTapObserver(observer) {
+      tapObservers.add(observer)
+      return () => {
+        tapObservers.delete(observer)
+      }
+    },
+
+    notifyTapDown(touch) {
+      // The hub stream's multi-touch law: the FIRST touch of a sequence is the primary
+      // pointer (pin isPrimaryPointer); every concurrent later touch is secondary.
+      const primary = activeTapTouches.size === 0
+      activeTapTouches.set(touch.id, touch)
+      for (const observer of tapObservers) observer.onTouchDown(touch, primary)
+    },
+
+    notifyTapUp(touch) {
+      // Untracked id (a down this channel never saw) notifies nothing — no phantom events.
+      if (!activeTapTouches.delete(touch.id)) return
+      for (const observer of tapObservers) observer.onTouchUp(touch)
+    },
+
+    notifyTapCancel(touch) {
+      if (!activeTapTouches.delete(touch.id)) return
+      for (const observer of tapObservers) observer.onTouchCancel(touch)
+    },
+  }
+
+  /**
+   * Shared terminal path for `terminate` and arm-overwrite (Issue 4).
+   * Always clear armed + bump epoch even if wiring callbacks throw (G-INV-7).
+   * End and finalize run separately so an onDragEnd throw still reaches finalize
+   * (lock release) — seal review r6. Report/rethrow only AFTER clear (seal r8).
+   */
+  function terminateSession(success: boolean): void {
+    if (armed === null) return
+    const session = armed
+    // Flush pending snap gate before terminal: a fast gesture can touch-up before
+    // measureInWindow lands; without this the held threshold-crossing move is dropped
+    // and activated never becomes true so end/finalize are skipped (seal review r11 major).
+    if (session.pendingSnap) {
+      session.pendingSnap = false
+      const held = session.lastPayload
+      if (held !== null && !session.activated) {
+        const threshold =
+          typeof session.options.distanceThreshold === 'number'
+            ? session.options.distanceThreshold
+            : HUB_DEFAULT_DISTANCE_THRESHOLD
+        const moved = hypot(
+          typeof held.translationX === 'number' ? held.translationX : 0,
+          typeof held.translationY === 'number' ? held.translationY : 0,
+        )
+        if (moved >= threshold) {
+          session.activated = true
+          try {
+            session.wiring.handlePanStart(held)
+            // Mirror releaseSnapGate: held sample is also the first update.
+            session.wiring.handlePanUpdate(held)
+          } catch (error) {
+            // Start/update threw after sessions may hold the lock — finalize MUST run
+            // so the app-global lock frees (G-INV-7; adversarial seal Issue 1).
+            const payload = held
+            const finalizeRetained = endFinalizeRetain(session, payload, false)
+            clearArmed(session)
+            // Prefer the start failure as primary; still surface finalize failure.
+            try {
+              session.report?.(
+                asError(error, 'DragControls: handlePanStart failed during pendingSnap flush'),
+              )
+            } catch {
+              /* report may throw in development */
+            }
+            if (finalizeRetained !== NO_RETAINED) {
+              try {
+                session.report?.(
+                  asError(finalizeRetained, 'DragControls: terminal wiring callback failed'),
+                )
+              } catch {
+                /* primary rethrow wins */
+              }
+            }
+            throw asError(error, 'DragControls: handlePanStart failed during pendingSnap flush')
+          }
+        }
+      }
+    }
+    const payload = session.lastPayload ?? originPayload(session)
+    const retained = endFinalizeRetain(session, payload, success)
+    clearArmed(session)
+    reportAfterClear(session, retained)
+  }
+}
+
+/**
+ * Extract a screen-space point from a hub start event (RN GestureResponderEvent or PointerEvent).
+ * Fail-closed: returns null when no usable coordinates.
+ */
+export function extractHubStartPoint(
+  event: unknown,
+): { readonly absoluteX: number; readonly absoluteY: number } | null {
+  if (event === null || event === undefined || typeof event !== 'object') return null
+  const e = event as Record<string, unknown>
+  // React Native: nativeEvent.pageX/pageY
+  const native = e['nativeEvent']
+  if (native !== null && native !== undefined && typeof native === 'object') {
+    const n = native as Record<string, unknown>
+    if (typeof n['pageX'] === 'number' && typeof n['pageY'] === 'number') {
+      return { absoluteX: n['pageX'], absoluteY: n['pageY'] }
+    }
+    if (typeof n['absoluteX'] === 'number' && typeof n['absoluteY'] === 'number') {
+      return { absoluteX: n['absoluteX'], absoluteY: n['absoluteY'] }
+    }
+  }
+  // DOM PointerEvent / React PointerEvent
+  if (typeof e['pageX'] === 'number' && typeof e['pageY'] === 'number') {
+    return { absoluteX: e['pageX'], absoluteY: e['pageY'] }
+  }
+  if (typeof e['clientX'] === 'number' && typeof e['clientY'] === 'number') {
+    return { absoluteX: e['clientX'], absoluteY: e['clientY'] }
+  }
+  return null
+}