@rootnative/impulse 0.0.0-alpha.0 → 0.0.0-alpha.1

package/src/intents/useTap.ts

@@ -1,18 +1,18 @@
 import { useMemo } from 'react'
-import {
-  Gesture,
-  type GestureStateChangeEvent,
-  type TapGesture,
-  type TapGestureHandlerEventPayload,
-} from 'react-native-gesture-handler'
-import { runOnJS, useSharedValue } from 'react-native-reanimated'
+import { Gesture, type TapGesture } from 'react-native-gesture-handler'
+import { useSharedValue } from 'react-native-reanimated'
+import { scheduleOnRN } from 'react-native-worklets'
 import {
   useGestureMemo,
   type GestureMemoOptions,
 } from '../internal/useGestureMemo'
+import { buildIntentResult } from '../internal/intentResult'
 import { useLatestCallback } from '../internal/useLatestCallback'
 import { useStableRecord } from '../internal/useStableRecord'
-import { type HitSlop, type IntentResult, type Point } from '../types'
+import { toTapEvent, type TapEvent } from './tapEvent'
+import { type HitSlop, type IntentEndInfo, type IntentResult } from '../types'
+
+export type { TapEvent } from './tapEvent'
 
 /**
  * Maximum time the finger may stay down and still count as a tap, in
@@ -32,28 +32,11 @@ const DEFAULT_MAX_DURATION = 500
  * and rejected on the other. A fixed number is the behaviour a consumer can
  * reason about. 10 points is roughly a finger's own jitter while pressing.
  *
- * **This number is a design intention, not a measurement.** No hardware pass
- * has happened. See Known gaps in CLAUDE.md.
+ * **This number is a design intention, not a measurement.** The device sweep
+ * of 2026-09-19 did not test it. See Known gaps in docs/docs/roadmap.md.
  */
 const DEFAULT_MAX_DISTANCE = 10
 
-/** The intent-shaped payload a {@link useTap} callback receives. */
-export interface TapEvent {
-  /** X of the tap, in points, relative to the view the gesture is attached to. */
-  readonly x: number
-  /** Y of the tap, in points, relative to the view the gesture is attached to. */
-  readonly y: number
-  /**
-   * The same point relative to the window.
-   *
-   * Prefer it over `x` / `y` when the view itself is being transformed by the
-   * gesture — a tap on a view that is mid-animation reports a moving `x`.
-   */
-  readonly absolute: Point
-  /** How many fingers were down when the tap was recognized. */
-  readonly pointers: number
-}
-
 /** Options for {@link useTap}. */
 export interface UseTapOptions extends GestureMemoOptions {
   /**
@@ -94,14 +77,23 @@ export interface UseTapOptions extends GestureMemoOptions {
    */
   enabled?: boolean
   /**
-   * The tap happened. **Runs on the JS thread** — Impulse owns the
-   * `runOnJS` boundary, so this is an ordinary function and may touch React
+   * The tap ended. **Runs on the JS thread** — Impulse owns the
+   * `scheduleOnRN` boundary, so this is an ordinary function and may touch React
    * state.
    *
-   * It fires only for a successful tap. A touch that moved too far or stayed
-   * down too long reaches `onFinalize` with `success: false` instead.
+   * It fires only for a tap the recognizer accepted, and `cancelled` says
+   * what happened after that. `false` is the ordinary tap. `true` means the
+   * system took the recognized tap away before it could be acted on — a
+   * competing gesture in a relation won it, or the app went to the
+   * background.
+   *
+   * **Check `cancelled` before you act on the tap.** A handler that navigates
+   * or submits should do nothing when it is `true`. The path is rare: a touch
+   * that moved past `maxDistance` or stayed down past `maxDuration` was never
+   * a tap at all, so it reaches `onFinalize` with `success: false` and never
+   * gets here.
    */
-  onTap?: (event: TapEvent) => void
+  onTap?: (event: TapEvent, info: IntentEndInfo) => void
   /**
    * The finger went down and the gesture is now a candidate. **This is a
    * worklet** — mark it with the `'worklet'` directive, and do not touch
@@ -132,26 +124,6 @@ export interface UseTapOptions extends GestureMemoOptions {
  */
 export type UseTapResult = IntentResult<TapGesture>
 
-/**
- * Shape RNGH's flat state-change event into the tap payload.
- *
- * A worklet, because every caller is one. Keeping the normalizer out of the
- * gesture callbacks means the four call sites cannot disagree about which
- * RNGH field means what — which is the defect the intent payload exists to
- * remove.
- */
-function toTapEvent(
-  event: GestureStateChangeEvent<TapGestureHandlerEventPayload>,
-): TapEvent {
-  'worklet'
-  return {
-    x: event.x,
-    y: event.y,
-    absolute: { x: event.absoluteX, y: event.absoluteY },
-    pointers: event.numberOfPointers,
-  }
-}
-
 /**
  * Recognize a single tap.
  *
@@ -167,7 +139,7 @@ function toTapEvent(
  *
  * `onTap` runs on the JS thread and may set React state directly. `onBegin`
  * and `onFinalize` are worklets and run on the UI thread — the name states
- * the thread, so there is nothing to configure and no `runOnJS` to write.
+ * the thread, so there is nothing to configure and no `scheduleOnRN` to write.
  *
  * `isActive` is a shared value that is `true` while the finger is down. Drive
  * a pressed state from it without a re-render:
@@ -180,11 +152,22 @@ function toTapEvent(
  * **Activation criteria.** `maxDuration` defaults to 500ms and `maxDistance`
  * to 10 points. The distance default is Impulse's, not RNGH's: RNGH defers to
  * the platform there, so the same tap is accepted on one operating system and
- * rejected on the other. Neither default has been measured on hardware yet.
+ * rejected on the other. The device sweep did not test either default.
  *
- * **Racing a double tap.** A single tap and a double tap on one view is a
- * composition, not an option — `useGestures([tap, double], { mode: 'race' })`.
- * Do not reach for `maxDelay` to build it by hand.
+ * **Pairing with a double tap.** A single tap and a double tap on one view is
+ * a composition, not an option — and the mode is `exclusive`, with the double
+ * tap named first:
+ *
+ * ```tsx
+ * useGestures([double, tap], { mode: 'exclusive' })
+ * ```
+ *
+ * `race` is the wrong mode here and fails quietly. A single tap recognizes on
+ * the first release, so it wins the race every time and the double tap never
+ * fires. `exclusive` is what makes the single tap wait to learn whether a
+ * second tap is coming — at the cost of `useDoubleTap`'s `maxDelay` in
+ * latency on every single tap. Do not reach for `maxDelay` to build the pair
+ * by hand.
  *
  * **Web.** RNGH's web implementation recognizes tap from pointer events, and
  * `pointers` above 1 is unreliable there because a mouse reports one pointer
@@ -241,8 +224,13 @@ export function useTap(options: UseTapOptions = {}): UseTapResult {
         })
         .onEnd((event, success) => {
           'worklet'
-          if (success && hasTapHandler) {
-            runOnJS(handleTap)(toTapEvent(event))
+          // Not guarded on `success`: RNGH calls `onEnd` only when the old
+          // state was ACTIVE, so reaching here at all means the tap was
+          // recognized. `cancelled` then separates the tap the user completed
+          // from the one the system took away. Without it the cancel is
+          // reportable only from `onFinalize`, which is a worklet.
+          if (hasTapHandler) {
+            scheduleOnRN(handleTap, toTapEvent(event), { cancelled: !success })
           }
         })
         .onFinalize((event, success) => {
@@ -281,5 +269,8 @@ export function useTap(options: UseTapOptions = {}): UseTapResult {
   // consumer may put the whole hook result in a dependency list, and a fresh
   // object every render would make that dependency useless. `isActive` is
   // stable for the life of the hook, so `built` is the only real input.
-  return useMemo(() => ({ ...built, isActive }), [built, isActive])
+  return useMemo(
+    () => buildIntentResult(built, { isActive }),
+    [built, isActive],
+  )
 }

package/src/internal/intentResult.ts

@@ -0,0 +1,67 @@
+import { type GestureType } from 'react-native-gesture-handler'
+import { type BuiltGesture } from './useGestureMemo'
+
+/**
+ * Assemble a hook result whose `gesture` and `ref` are **not enumerable**.
+ *
+ * This is a correctness fix, not a tidiness one, and it is the single most
+ * load-bearing line in the library.
+ *
+ * A Reanimated worklet captures the **root identifier** it reads through, so
+ * a consumer writing the obvious thing —
+ *
+ * ```tsx
+ * const style = useAnimatedStyle(() => ({
+ *   transform: [{ scale: pinch.scale.value }],
+ * }))
+ * ```
+ *
+ * — captures `pinch`, the whole hook result, and Worklets then tries to copy
+ * it to the UI thread. `gesture` is an RNGH class instance, which Worklets
+ * cannot serialize, so the component throws at render with
+ * `[Worklets] Cannot copy value of type 'PinchGesture'`. Every intent had
+ * this defect, and every example screen died of it the first time one was run
+ * on a device.
+ *
+ * Worklets copies an object through `cloneObjectProperties`, which iterates
+ * `Object.entries` — own **enumerable** keys only. Hiding `gesture` and `ref`
+ * from enumeration therefore removes them from the copy, and what crosses to
+ * the UI thread is the shared values alone, which is all a worklet ever
+ * wanted. Reading `pinch.gesture` still works: non-enumerable is not private.
+ *
+ * The alternative was to document "destructure before the worklet, or your
+ * app crashes". That is a new sharp edge, and absorbing sharp edges is the
+ * reason this package exists.
+ *
+ * **What this costs.** `gesture` and `ref` do not appear in `Object.keys`, a
+ * spread of the result, `JSON.stringify`, or a `console.log` of the object.
+ * Nothing in Impulse relies on any of those — `useGestures` reads `.gesture`
+ * by property access, which is unaffected — and a consumer who spreads a hook
+ * result to build another object is doing something the `ref` exists to
+ * prevent.
+ *
+ * @param built - The gesture and its ref, from `useGestureMemo`.
+ * @param values - The shared values this intent reports. These stay
+ *   enumerable: a shared value is exactly what a worklet should capture.
+ */
+export function buildIntentResult<G extends GestureType, V extends object>(
+  built: BuiltGesture<G>,
+  values: V,
+): V & BuiltGesture<G> {
+  const result = { ...values } as V & BuiltGesture<G>
+  Object.defineProperty(result, 'gesture', {
+    value: built.gesture,
+    enumerable: false,
+    // Configurable so the object stays describable and a future field can
+    // replace it. Not writable: the result is read-only by type, and a
+    // consumer swapping the gesture would defeat the memoisation that keeps
+    // gesture identity stable.
+    configurable: true,
+  })
+  Object.defineProperty(result, 'ref', {
+    value: built.ref,
+    enumerable: false,
+    configurable: true,
+  })
+  return result
+}

package/src/internal/phaseCallbacks.ts

@@ -0,0 +1,51 @@
+import { isWorkletFunction } from 'react-native-worklets'
+import { isDevBuild, warnOnce } from './warnOnce'
+
+/** The callbacks every intent runs on the UI thread. */
+export const PHASE_CALLBACKS = ['onBegin', 'onUpdate', 'onFinalize'] as const
+
+/** The phase callbacks of any intent's options, read without their types. */
+export type PhaseCallbacks = Partial<
+  Record<(typeof PHASE_CALLBACKS)[number], unknown>
+>
+
+/**
+ * Warn once for each phase callback that is a plain function, not a worklet.
+ *
+ * A plain function reaches the UI thread as a remote function, and the first
+ * time the gesture enters that phase it throws `Tried to synchronously call a
+ * Remote Function. Called "anonymous"`. That error names neither the hook nor
+ * the option, and it arrives on a touch rather than at the call site.
+ *
+ * `isWorkletFunction` reads `__workletHash`, which only the Worklets Babel
+ * plugin writes. A test runner without the plugin marks nothing, so the
+ * shipped Jest setup reports every function as a worklet: its mock has no UI
+ * thread, and a plain function is correct there.
+ */
+export function warnOnPlainPhaseCallbacks(
+  callbacks: PhaseCallbacks,
+  hookName: string,
+): void {
+  // A consumer's own worklets mock can omit this export. A missing check must
+  // not break their tests.
+  if (!isDevBuild() || typeof isWorkletFunction !== 'function') {
+    return
+  }
+
+  for (const name of PHASE_CALLBACKS) {
+    const callback = callbacks[name]
+    if (typeof callback !== 'function' || isWorkletFunction(callback)) {
+      continue
+    }
+    warnOnce(
+      `worklets:plain:${hookName}:${name}`,
+      `${hookName} received an \`${name}\` that is not a worklet, and ` +
+        `\`${name}\` runs on the UI thread. Add the 'worklet' directive as ` +
+        'the first statement of the function. Without it, iOS and Android ' +
+        'throw "Tried to synchronously call a Remote Function" when the ' +
+        'gesture reaches that phase. For code that must run on the JS ' +
+        "thread, such as a React state update, use the hook's intent " +
+        'callback instead.',
+    )
+  }
+}

package/src/internal/useGestureMemo.ts

@@ -1,7 +1,17 @@
-import { useMemo, useRef, type DependencyList, type RefObject } from 'react'
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  type DependencyList,
+  type RefObject,
+} from 'react'
 import { type GestureType } from 'react-native-gesture-handler'
-import { applyRelations } from '../relations'
+import { applyRelations, warnOnUnresolvableReferences } from '../relations'
 import { type CoexistenceOptions } from '../types'
+import {
+  warnOnPlainPhaseCallbacks,
+  type PhaseCallbacks,
+} from './phaseCallbacks'
 import { useStableList } from './useStableList'
 
 /** What every hook built on this helper accepts on top of its own options. */
@@ -62,18 +72,22 @@ export interface BuiltGesture<G extends GestureType> {
  * @param deps - What the built gesture depends on. Worklet callbacks belong
  *   here, because a worklet is captured as written. JS-thread callbacks do
  *   not — route those through `useLatestCallback` first.
- * @param options - Coexistence options and `testId`.
+ * @param options - Coexistence options, `testId`, and the hook's phase
+ *   callbacks, which are checked for the `'worklet'` directive.
  */
 export function useGestureMemo<G extends GestureType>(
   hookName: string,
   build: () => G,
   deps: DependencyList,
-  options?: GestureMemoOptions,
+  options?: GestureMemoOptions & PhaseCallbacks,
 ): BuiltGesture<G> {
   const alongside = useStableList(options?.alongside)
   const blocks = useStableList(options?.blocks)
   const deferTo = useStableList(options?.deferTo)
   const testId = options?.testId
+  const onBegin = options?.onBegin
+  const onUpdate = options?.onUpdate
+  const onFinalize = options?.onFinalize
   const ref = useRef<GestureType | undefined>(undefined)
 
   const gesture = useMemo(
@@ -103,6 +117,20 @@ export function useGestureMemo<G extends GestureType>(
     [...deps, alongside, blocks, deferTo, testId, hookName],
   )
 
+  // A relation to a component that owns no gesture is dropped by RNGH without
+  // a word, and this is the only place with both the references and a moment
+  // late enough to read them. It has to be an effect: refs are empty while
+  // the memo above runs, so the same check there would fire for every correct
+  // relation. Dev-only, and `warnOnce` keyed, so a hook that re-renders at
+  // frame rate does not print at frame rate.
+  useEffect(() => {
+    warnOnUnresolvableReferences({ alongside, blocks, deferTo }, hookName)
+  }, [alongside, blocks, deferTo, hookName])
+
+  useEffect(() => {
+    warnOnPlainPhaseCallbacks({ onBegin, onUpdate, onFinalize }, hookName)
+  }, [onBegin, onUpdate, onFinalize, hookName])
+
   // The result object is memoised too, so a consumer can put the whole hook
   // result in a dependency list — `useGestures` does exactly that with its
   // members.

package/src/internal/useLatestCallback.ts

@@ -28,8 +28,8 @@ import { useCallback, useInsertionEffect, useRef } from 'react'
  * dependency of the gesture's `useMemo`, because a worklet is captured as
  * written: swapping its body through a ref would leave the UI thread running
  * the version it was serialized with, silently. That asymmetry is why
- * Impulse splits callbacks by name — `onBegin` / `onUpdate` / `onEnd` are
- * worklets, `onTap` / `onSwipe` / `onLongPress` are not.
+ * Impulse splits callbacks by name — `onBegin` / `onUpdate` / `onFinalize`
+ * are worklets, `onTap` / `onDragEnd` / `onLongPress` are not.
  *
  * The returned function is stable, so it is never a useful dependency. A
  * caller that needs the gesture to change when the callback *appears or

package/src/raw/useRawGesture.ts

@@ -39,7 +39,7 @@ export type RawGestureResult<G extends GestureType> = BuiltGesture<G>
  *   put it through `useLatestCallback` and depend on the stable result.
  * - **The thread.** RNGH decides per callback, by whether it carries the
  *   `'worklet'` directive, and warns in development when a gesture mixes the
- *   two. Impulse does not insert a `runOnJS` boundary for you here; that is
+ *   two. Impulse does not insert a `scheduleOnRN` boundary for you here; that is
  *   something the intent hooks do because they know what each callback means.
  * - **The payload.** You get RNGH's flat event, not an intent-shaped one.
  *

package/src/relations/index.ts

@@ -70,6 +70,100 @@ export function applyRelations(
   }
 }
 
+/**
+ * RNGH's test for a usable handler tag, mirrored rather than inferred.
+ * `extractValidHandlerTags` keeps `tag > 0` and drops everything else, so a
+ * reference this returns `false` for is a reference RNGH silently discards.
+ */
+function hasHandlerTag(candidate: object): boolean {
+  const tag = (candidate as { handlerTag?: unknown }).handlerTag
+  return typeof tag === 'number' && tag > 0
+}
+
+/**
+ * Whether this reference names something RNGH will drop.
+ *
+ * Three states, and only the third is a defect:
+ *
+ * 1. **A gesture object.** It carries its own `handlerTag`. Nothing to check.
+ * 2. **A ref with no `.current`.** The target has not mounted yet, or never
+ *    will. Say nothing — see the timing note on `warnOnUnresolvableReferences`.
+ * 3. **A ref whose `.current` carries no handler tag.** The component is
+ *    mounted and owns no gesture. RNGH resolves it to `-1` and filters it out.
+ */
+function isUnresolvable(reference: GestureReference): boolean {
+  if (typeof reference !== 'object' || reference === null) {
+    return false
+  }
+  if (!('current' in reference)) {
+    return false
+  }
+  const current = reference.current
+  if (current === null || current === undefined) {
+    return false
+  }
+  return !hasHandlerTag(current)
+}
+
+/**
+ * Warn when a relation names a mounted component that owns no gesture.
+ *
+ * This is the silent failure the library exists to remove. RNGH resolves
+ * every relation reference through `convertToHandlerTag`, which reads
+ * `ref.current?.handlerTag ?? -1` and then keeps only tags above zero. A ref
+ * to React Native's own `ScrollView` has no tag, so the relation is dropped —
+ * with no warning, no error, and no way to tell the result apart from a
+ * relation that was never written. The gesture keeps working; it just never
+ * coexists with the scroll view, which is the whole reason the option was
+ * passed.
+ *
+ * **Call this from an effect, never during render.** A ref is empty while the
+ * component that owns it renders and is filled during the commit, so a check
+ * at `applyRelations` time reads `undefined` for a correct relation and a
+ * wrong one alike.
+ *
+ * **A populated ref is a finished ref, which is what makes state 3 above safe
+ * to report.** Both places RNGH fills one do it together with the tag:
+ * `BaseGesture.initialize` assigns `handlerTag` and sets `config.ref.current`
+ * in the same function, and `createNativeWrapper`'s `useImperativeHandle`
+ * copies the tag onto the instance before returning it, and returns `null`
+ * when it cannot. Neither leaves a window where `.current` is set and the tag
+ * is still coming, so a populated ref with no tag is never a timing artifact.
+ *
+ * What this deliberately does not catch: a target that mounts in a *later*
+ * commit than the gesture. Its ref is empty when this runs and nothing
+ * re-checks, so the case stays silent. That is the right trade — RNGH itself
+ * re-resolves relations when a handler mounts late, through `MountRegistry`,
+ * so the relation is installed anyway and a warning here would be wrong.
+ *
+ * The key names the hook and the option rather than the reference, because a
+ * ref has no stable string form and the fix is the same for every instance.
+ */
+export function warnOnUnresolvableReferences(
+  relations: ResolvedCoexistence,
+  hookName: string,
+): void {
+  if (!isDevBuild()) {
+    return
+  }
+
+  for (const [option] of RELATIONS) {
+    if (!relations[option].some(isUnresolvable)) {
+      continue
+    }
+    warnOnce(
+      `relations:untagged:${hookName}:${option}`,
+      `${hookName} received a \`${option}\` reference to a component that ` +
+        'owns no gesture, so gesture-handler dropped the relation. The ' +
+        'gesture still works and the two still conflict — nothing reports ' +
+        "it at runtime. React Native's own `ScrollView` and `FlatList` are " +
+        'the usual cause: they carry no handler tag. Import `ScrollView` or ' +
+        '`FlatList` from `@rootnative/impulse/gesture-handler` and put the ' +
+        'ref on that component instead.',
+    )
+  }
+}
+
 /**
  * Warn when one gesture is named by more than one coexistence option.
  *

package/src/types.ts

@@ -185,3 +185,30 @@ export interface IntentResult<G extends GestureType> {
    */
   readonly isActive: SharedValue<boolean>
 }
+
+/**
+ * How a gesture ended, handed to every intent's end callback as its second
+ * argument.
+ *
+ * The end callbacks — `onTap`, `onDoubleTap`, `onLongPressEnd`, `onDragEnd` —
+ * fire on both paths: a gesture the user completed, and one the system took
+ * away. This says which. Without it, a cancel is reported only by
+ * `onFinalize`, which is a worklet, so a consumer holding phase in React
+ * state has to write `'worklet'` plus `scheduleOnRN` by hand.
+ *
+ * It is an object rather than a bare boolean so a later field — a reason for
+ * the cancel, say — does not break the signature a second time.
+ */
+export interface IntentEndInfo {
+  /**
+   * `true` when the system took the gesture away instead of the user
+   * completing it: a competing gesture won, the app went to the background,
+   * or a relation handed the touch to another recognizer.
+   *
+   * A gesture that never activated at all does not reach an end callback on
+   * either path, so this is never `true` for a touch that was never the
+   * intent. It separates "this ended, but not by the user" from "the user
+   * did it".
+   */
+  readonly cancelled: boolean
+}