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

package/dist/rotate/index.d.ts

@@ -0,0 +1,263 @@
+import { RotationGesture } from 'react-native-gesture-handler';
+import { SharedValue } from 'react-native-reanimated';
+import { G as GestureMemoOptions } from '../useGestureMemo-BRW1EKcJ.js';
+import { P as Point, H as HitSlop, I as IntentEndInfo, c as IntentResult } from '../types-ChGKY28a.js';
+import 'react';
+
+/** The intent-shaped payload a {@link useRotate} callback receives. */
+interface RotateEvent {
+    /**
+     * How far the thing is turned now, in **degrees**, after `min`, `max` and
+     * `elastic` were applied.
+     *
+     * This accumulates across gestures. A second rotation continues from where
+     * the first one stopped, which is why `min` and `max` can be written as the
+     * travel of the whole control rather than of one gesture.
+     *
+     * Positive is clockwise, which is what React Native's `rotate` transform
+     * also treats as positive.
+     */
+    readonly angle: number;
+    /**
+     * How far the fingers turned during **this gesture alone**, in degrees.
+     *
+     * Untouched by `min`, `max` and `elastic`, and reset to zero at the start of
+     * every gesture. This is RNGH's own `rotation`, converted. Read `angle` for
+     * how far the thing being turned actually sits.
+     */
+    readonly gestureAngle: number;
+    /**
+     * The point the rotation turns about — RNGH's anchor, the centre between
+     * the fingers, relative to the view.
+     *
+     * A rotation applied about the view's own centre turns the content under
+     * the fingers rather than with them. This is the point the transform has to
+     * pivot on, and it is the rotation counterpart of `usePinch`'s `focal`.
+     */
+    readonly anchor: Point;
+    /**
+     * How fast the angle is changing, in degrees per second.
+     *
+     * RNGH's own documentation calls this "point units per second" for the
+     * rotation handler, which is a copy of the pan handler's wording rather
+     * than a description of this value. It is an angular speed.
+     */
+    readonly velocity: number;
+    /**
+     * The nearest angle inside `min` and `max`. Equal to `angle` whenever the
+     * rotation is in range, which with the default `elastic` of `0` is always.
+     *
+     * With `elastic` set, the fingers can turn past an end and Impulse leaves
+     * the angle there on release — moving it back is an animation, and Impulse
+     * owns no animation vocabulary. This field is the destination that
+     * animation needs, so the consumer does not have to re-derive the clamp
+     * from a range it already handed over.
+     */
+    readonly settled: number;
+    /** How many fingers are down. */
+    readonly pointers: number;
+}
+/** Options for {@link useRotate}. */
+interface UseRotateOptions extends GestureMemoOptions {
+    /**
+     * The angle before any rotation, in degrees. Default `0`.
+     *
+     * Read once, at mount. `useSharedValue` keeps its first argument and
+     * ignores every later one, and that is the behaviour this option
+     * documents: after mount `angle` is the rotation's state, and the consumer
+     * moves it by writing it.
+     */
+    initial?: number;
+    /**
+     * The smallest angle, in degrees. Unset by default, which lets the fingers
+     * turn the thing without limit.
+     *
+     * Impulse does not wrap the angle at a full turn. Without `min` and `max`
+     * a second turn reports 360 more degrees than the first, which is what a
+     * dial counting revolutions needs and what a photo editor does not.
+     */
+    min?: number;
+    /**
+     * The largest angle, in degrees. Unset by default, which lets the fingers
+     * turn the thing without limit.
+     */
+    max?: number;
+    /**
+     * How much of the travel past `min` or `max` reaches `angle`, from `0` to
+     * `1`. Default `0`.
+     *
+     * `0` stops dead at the end. `1` ignores the end while the fingers are
+     * down. Anything between is resistance — the rotation keeps turning and
+     * turns less than the fingers do.
+     *
+     * Impulse does not bring the angle back. The end callback carries
+     * `settled` — the angle to animate to — and `@rootnative/inertia` or a
+     * `withSpring` of your own does the rest.
+     */
+    elastic?: number;
+    /**
+     * Extra touchable area around the view, in points.
+     *
+     * Written inline as an object is fine — the gesture is not rebuilt when the
+     * contents are unchanged.
+     */
+    hitSlop?: HitSlop;
+    /**
+     * Whether the gesture is recognized at all. Default `true`.
+     *
+     * Prefer this over unmounting the `<GestureDetector>`: a disabled gesture
+     * keeps its identity and its relations, so re-enabling it does not
+     * re-attach anything.
+     */
+    enabled?: boolean;
+    /**
+     * The rotation now owns the touch. **Runs on the JS thread** — Impulse owns
+     * the `scheduleOnRN` boundary, so this is an ordinary function and may
+     * touch React state.
+     *
+     * This is the first moment the rotation has definitely won. `onBegin` fires
+     * earlier and promises nothing.
+     */
+    onRotateStart?: (event: RotateEvent) => void;
+    /**
+     * The rotation is over. **Runs on the JS thread.**
+     *
+     * Fires only for a rotation that activated, so a touch that never became
+     * one never reaches here on either path.
+     *
+     * It fires for both endings, and `cancelled` says which. `false` is the
+     * fingers lifting, and `velocity` then describes the release. `true` is the
+     * system taking the rotation away — a competing gesture won, or the app
+     * went to the background. **There was no release on that path, so the
+     * velocity describes the last movement rather than a throw.**
+     *
+     * Read `settled` on both paths for where an elastic overshoot belongs.
+     */
+    onRotateEnd?: (event: RotateEvent, info: IntentEndInfo) => void;
+    /**
+     * A finger went down and the gesture is now a candidate. **This is a
+     * worklet** — mark it with the `'worklet'` directive, and do not touch
+     * React state from it.
+     *
+     * Being a candidate is not the same as winning: one finger cannot turn
+     * anything, and a second one may never arrive. Undo whatever it sets in
+     * `onFinalize`.
+     */
+    onBegin?: (event: RotateEvent) => void;
+    /**
+     * The angle changed. **This is a worklet**, and it runs on every frame the
+     * fingers turn.
+     *
+     * `angle` is already written by the time this runs, so a `useAnimatedStyle`
+     * reading it needs nothing from here. Use this for the work that turning
+     * alone does not do — snapping a readout to whole degrees, say.
+     *
+     * There is no JS-thread counterpart on purpose. A per-frame `scheduleOnRN`
+     * is a scheduling cost paid sixty times a second for a value that is
+     * already on the thread that needs it.
+     */
+    onUpdate?: (event: RotateEvent) => void;
+    /**
+     * The gesture is over, whether it activated or not. **This is a worklet.**
+     *
+     * `success` is `true` when the rotation activated and ended normally. This
+     * is the right place to clear anything `onBegin` set, because it runs on
+     * both paths.
+     */
+    onFinalize?: (event: RotateEvent, success: boolean) => void;
+}
+/** What {@link useRotate} returns. */
+interface UseRotateResult extends IntentResult<RotationGesture> {
+    /**
+     * How far the thing is turned, in **degrees**, after `min`, `max` and
+     * `elastic`.
+     *
+     * **This is a position, not a movement.** It accumulates across gestures,
+     * so a second rotation continues from where the first stopped. `usePan` is
+     * the hook whose value zeroes at every gesture.
+     *
+     * Writing it is allowed and is how a release animation, or a reset button,
+     * hands control back. The next rotation continues from whatever it holds.
+     */
+    readonly angle: SharedValue<number>;
+    /**
+     * The point the rotation turns about, relative to the view.
+     *
+     * It keeps the last gesture's anchor after the fingers lift, so a release
+     * animation turns about the same point the gesture did rather than
+     * snapping to the view's centre.
+     */
+    readonly anchor: SharedValue<Point>;
+}
+/**
+ * Recognize a two-finger rotation, and own the angle it produces.
+ *
+ * ```tsx
+ * const rotate = useRotate({ min: -45, max: 45 })
+ *
+ * const style = useAnimatedStyle(() => ({
+ *   transform: [{ rotate: `${rotate.angle.value}deg` }],
+ * }))
+ *
+ * return (
+ *   <GestureDetector gesture={rotate.gesture}>
+ *     <Animated.Image style={style} source={source} />
+ *   </GestureDetector>
+ * )
+ * ```
+ *
+ * **The angle is in degrees, and RNGH's is in radians.** This is the one
+ * place Impulse changes a unit rather than passing one through. A range
+ * written as `min: -45` is a range a person wrote; `-Math.PI / 4` is one they
+ * derived, and deriving it per project is the work this library exists to
+ * remove. A React Native style takes either unit, so the choice costs the
+ * consumer nothing. `gestureAngle` is the same conversion applied to RNGH's
+ * per-gesture value.
+ *
+ * **The angle accumulates; RNGH's does not.** A bare `Gesture.Rotation()`
+ * reports a value that restarts at zero on every gesture, so a control built
+ * on it springs back to upright the moment the fingers lift again. Carrying
+ * the angle across gestures is the stored start that every consumer otherwise
+ * writes, and it is why `min` and `max` can be the travel of the control
+ * rather than of one gesture.
+ *
+ * **It does not wrap at a full turn.** Without `min` and `max`, a second
+ * revolution reports 360 degrees more than the first. That is what a dial
+ * counting turns needs. A control that should read `10` rather than `370`
+ * either sets a range or takes the remainder itself — Impulse does not guess
+ * which, because both are correct for something.
+ *
+ * **`anchor` is the point the turn happens about.** Rotating about the view's
+ * own centre turns the content under the fingers rather than with them. It is
+ * the rotation counterpart of `usePinch`'s `focal`, and it is read at
+ * `onStart` as well as at every update so the first callback does not report
+ * the previous gesture's point.
+ *
+ * **Activation criteria.** There are none to set. RNGH's rotation takes the
+ * touch as soon as two fingers turn, and it exposes no threshold, so Impulse
+ * has none to pass on. `usePinch` is the other intent in this position.
+ *
+ * **Coexistence.** A rotation almost always shares its view with a pinch, and
+ * neither has a threshold to separate them with. Say it: `useGestures` with
+ * `mode: 'simultaneous'` for gestures this screen owns, `alongside` for one
+ * it does not.
+ *
+ * **Web.** RNGH recognizes rotation from pointer events, so it needs two
+ * pointers — a touchscreen, or a device that reports them. A trackpad's
+ * rotation is not a pointer pair and never reaches this hook, so a desktop
+ * browser with a trackpad alone cannot turn anything. Give it a control that
+ * writes `angle` directly, which the accessibility fallback needs anyway.
+ *
+ * **Accessibility.** A rotation is invisible to a screen reader and
+ * unreachable from a keyboard, and this hook does not fix that. Whatever the
+ * rotation turns must be reachable another way: buttons that step the angle
+ * by a documented amount, a control that resets it to zero, or
+ * `accessibilityActions` with `onAccessibilityAction`. A rotate-only
+ * affordance is a bug, not a trade-off.
+ *
+ * @param options - The angle range, callbacks, and the `alongside` /
+ *   `blocks` / `deferTo` coexistence options every Impulse hook accepts.
+ */
+declare function useRotate(options?: UseRotateOptions): UseRotateResult;
+
+export { type RotateEvent, type UseRotateOptions, type UseRotateResult, useRotate };

package/dist/rotate/index.js

@@ -0,0 +1,4 @@
+export { useRotate } from '../chunk-YZHAQ4XK.js';
+import '../chunk-2UZTAWUQ.js';
+import '../chunk-NYDDZD4G.js';
+import '../chunk-ZX7WNICB.js';

package/dist/swipe/index.d.ts

@@ -0,0 +1,254 @@
+import { PanGesture } from 'react-native-gesture-handler';
+import { SharedValue } from 'react-native-reanimated';
+import { G as GestureMemoOptions } from '../useGestureMemo-BRW1EKcJ.js';
+import { P as Point, H as HitSlop, I as IntentEndInfo, c as IntentResult } from '../types-ChGKY28a.js';
+import 'react';
+
+/** Which way a swipe went. The same vocabulary as the `directions` option. */
+type SwipeDirection = 'left' | 'right' | 'up' | 'down';
+/** The intent-shaped payload a {@link useSwipe} callback receives. */
+interface SwipeEvent {
+    /**
+     * Which way the swipe went, or `null` when the release did not commit.
+     *
+     * `onSwipe` receives a payload whose direction is never `null` — that is
+     * the whole meaning of that callback. `onSwipeEnd` fires on every release
+     * of a swipe that activated, so it is the one that has to read this.
+     */
+    readonly direction: SwipeDirection | null;
+    /**
+     * How far the finger travelled along the dominant axis, in points, always
+     * positive.
+     *
+     * Compare it against `commitDistance` to see how close a release that did
+     * not commit came.
+     */
+    readonly distance: number;
+    /**
+     * How fast the finger was moving along the dominant axis, in points per
+     * second, always positive. The scalar counterpart of `velocity`, and what
+     * `commitSpeed` is compared against.
+     */
+    readonly speed: number;
+    /**
+     * How far the finger moved since the swipe activated, signed and per axis.
+     *
+     * Measured from the activation point, so it does not include the
+     * `threshold` travel the finger spent before the swipe existed.
+     */
+    readonly translation: Point;
+    /** Finger speed, in points per second, signed and per axis. */
+    readonly velocity: Point;
+    /** The touch point relative to the window. */
+    readonly absolute: Point;
+    /** How many fingers are down. */
+    readonly pointers: number;
+}
+/**
+ * A {@link SwipeEvent} that committed, so its direction is known.
+ *
+ * `onSwipe` takes this rather than `SwipeEvent`, which is what saves every
+ * consumer of that callback a null check for a case it cannot be in.
+ */
+type CommittedSwipeEvent = SwipeEvent & {
+    readonly direction: SwipeDirection;
+};
+/** Options for {@link useSwipe}. */
+interface UseSwipeOptions extends GestureMemoOptions {
+    /**
+     * Which directions may commit. Every direction by default.
+     *
+     * **This also sets the activation criterion**, which is the reason to
+     * narrow it even when the extra directions would never fire. A list that is
+     * entirely horizontal gives the gesture a directional threshold on the x
+     * axis, so a vertical scroll view under it keeps working; an entirely
+     * vertical list does the same on y. A mixed list has no axis to lock, so
+     * the threshold is radial and the swipe competes with a scroller for every
+     * touch.
+     *
+     * Written inline as an array is fine — the gesture is not rebuilt when the
+     * contents are unchanged.
+     */
+    directions?: readonly SwipeDirection[];
+    /**
+     * How far the finger must travel before the swipe activates and starts
+     * tracking, in points. Default `10`.
+     *
+     * This is not the commit test. It is the point at which the swipe takes the
+     * touch and `x` and `y` start reporting — see `commitDistance` for what
+     * decides that a release counts.
+     */
+    threshold?: number;
+    /**
+     * How far the finger must travel for a release to commit, in points.
+     * Default `80`.
+     *
+     * Measured along the dominant axis, from the activation point.
+     */
+    commitDistance?: number;
+    /**
+     * How fast the finger must be moving for a release to commit, in points per
+     * second. Default `800`.
+     *
+     * The flick: a release this fast commits even when it never travelled
+     * `commitDistance`. Either test is enough on its own.
+     */
+    commitSpeed?: number;
+    /**
+     * Movement across the axis that makes the swipe fail, in points. Unset by
+     * default, which leaves RNGH's own behaviour in place.
+     *
+     * Ignored when `directions` has no single axis, which has no cross axis.
+     */
+    failOffset?: number;
+    /**
+     * How many fingers must be on the view. Unset by default, which leaves
+     * RNGH's range of one to ten in place.
+     */
+    pointers?: number;
+    /**
+     * Extra touchable area around the view, in points.
+     *
+     * Written inline as an object is fine — the gesture is not rebuilt when the
+     * contents are unchanged.
+     */
+    hitSlop?: HitSlop;
+    /**
+     * Whether the gesture is recognized at all. Default `true`.
+     *
+     * Prefer this over unmounting the `<GestureDetector>`: a disabled gesture
+     * keeps its identity and its relations, so re-enabling it does not
+     * re-attach anything.
+     */
+    enabled?: boolean;
+    /**
+     * The swipe committed. **Runs on the JS thread** — Impulse owns the
+     * `scheduleOnRN` boundary, so this is an ordinary function and may touch
+     * React state.
+     *
+     * This is the callback almost every consumer wants, and it fires only for
+     * the thing it is named after: a release that passed `commitDistance` or
+     * `commitSpeed` in a direction `directions` allows. It never fires for a
+     * cancelled gesture, because a swipe the system took away did not happen.
+     *
+     * `event.direction` is never `null` here.
+     */
+    onSwipe?: (event: CommittedSwipeEvent) => void;
+    /**
+     * The swipe ended, committed or not. **Runs on the JS thread.**
+     *
+     * Fires on every release of a swipe that activated, which is what a view
+     * that followed the finger needs: `onSwipe` says to act, and this says to
+     * put the view back. Read `event.direction` for whether it committed —
+     * `null` is the release that did not.
+     *
+     * It fires for both endings, and `cancelled` says which. A cancelled
+     * gesture never commits, so its direction is always `null`.
+     */
+    onSwipeEnd?: (event: SwipeEvent, 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
+     * React state from it.
+     *
+     * The swipe has not passed `threshold` yet and may never. Undo whatever it
+     * sets in `onFinalize`.
+     */
+    onBegin?: (event: SwipeEvent) => void;
+    /**
+     * The finger moved. **This is a worklet**, and it runs on every frame.
+     *
+     * `direction` is `null` on every one of these: a swipe is decided at
+     * release, not while the finger is down. Read `translation` to show the
+     * view following, and `distance` to show how close a commit is.
+     */
+    onUpdate?: (event: SwipeEvent) => void;
+    /**
+     * The gesture is over, whether it activated or not. **This is a worklet.**
+     *
+     * `success` is `true` when the swipe activated and ended normally — which
+     * is not the same as committing. A release that stopped short is a
+     * successful gesture with no direction.
+     */
+    onFinalize?: (event: SwipeEvent, success: boolean) => void;
+}
+/** What {@link useSwipe} returns. */
+interface UseSwipeResult extends IntentResult<PanGesture> {
+    /**
+     * How far the finger has moved along the x axis since the swipe activated.
+     *
+     * **This is movement, not a position**, on the same terms as `usePan`: it
+     * is zeroed at the start of every gesture and keeps its final number after
+     * the gesture ends, so a release animation has something to animate from.
+     *
+     * Impulse does not put it back. That is an animation, and Principle 5 keeps
+     * animation out of this library — `onSwipeEnd` is where a consumer springs
+     * it home or off the screen.
+     */
+    readonly x: SharedValue<number>;
+    /**
+     * How far the finger has moved along the y axis since the swipe activated.
+     * Same terms as `x`.
+     */
+    readonly y: SharedValue<number>;
+}
+/**
+ * Recognize a directional swipe.
+ *
+ * ```tsx
+ * const swipe = useSwipe({
+ *   directions: ['left'],
+ *   onSwipe: () => archive(item.id),
+ *   onSwipeEnd: () => {
+ *     swipe.x.value = withSpring(0)
+ *   },
+ * })
+ *
+ * return (
+ *   <GestureDetector gesture={swipe.gesture}>
+ *     <Animated.View style={style} />
+ *   </GestureDetector>
+ * )
+ * ```
+ *
+ * A swipe is a pan that is judged at release. The finger moves, `x` and `y`
+ * report it so the view can follow, and on release the travel and the speed
+ * along the dominant axis decide whether it counted. `onSwipe` fires only for
+ * a release that counted, in a direction `directions` allows.
+ *
+ * **Narrowing `directions` is the coexistence setting, not only a filter.**
+ * An all-horizontal list gives the gesture a directional threshold on x, so a
+ * vertical scroll view under it keeps working without a relation. A mixed
+ * list has no axis to lock, so the threshold is radial and the swipe competes
+ * for every touch — declare `deferTo` or `blocks` there.
+ *
+ * **Two thresholds, and they mean different things.** `threshold` is when the
+ * swipe takes the touch and starts reporting. `commitDistance` and
+ * `commitSpeed` are what a release is measured against. A swipe that
+ * activates and stops short reaches `onSwipeEnd` with a `null` direction, and
+ * never reaches `onSwipe`.
+ *
+ * **No style, and no animation.** This hook returns numbers and stops there.
+ * Whether a committed row leaves the screen and an uncommitted one springs
+ * back is the consumer's decision, taken in `onSwipeEnd`.
+ * `@rootnative/inertia-gestures` has a `useSwipe` that owns both, and needs
+ * `@rootnative/inertia` to do it.
+ *
+ * **Web.** RNGH recognizes pan from pointer events, so a mouse drag commits
+ * the same way a touch does, and `speed` is reported in the same units. A
+ * trackpad's two-finger swipe is a scroll, not a pan, and never reaches this
+ * hook.
+ *
+ * **Accessibility.** A swipe is invisible to a screen reader and unreachable
+ * from a keyboard. Whatever it commits must be reachable another way: a
+ * visible button for a row action, a paging control for a carousel, or
+ * `accessibilityActions` with `onAccessibilityAction`. A swipe-only action is
+ * a bug, not a trade-off.
+ *
+ * @param options - Directions, activation and commit criteria, callbacks, and
+ *   the `alongside` / `blocks` / `deferTo` coexistence options every Impulse
+ *   hook accepts.
+ */
+declare function useSwipe(options?: UseSwipeOptions): UseSwipeResult;
+
+export { type CommittedSwipeEvent, type SwipeDirection, type SwipeEvent, type UseSwipeOptions, type UseSwipeResult, useSwipe };

package/dist/swipe/index.js

@@ -0,0 +1,4 @@
+export { useSwipe } from '../chunk-MWCIEVTA.js';
+import '../chunk-2UZTAWUQ.js';
+import '../chunk-NYDDZD4G.js';
+import '../chunk-ZX7WNICB.js';

package/dist/tap/index.d.ts

@@ -1,25 +1,10 @@
 import { TapGesture } from 'react-native-gesture-handler';
-import { G as GestureMemoOptions } from '../useGestureMemo-Ccv8rB0C.js';
-import { P as Point, H as HitSlop, I as IntentResult } from '../types-Ch2HM3aP.js';
+import { G as GestureMemoOptions } from '../useGestureMemo-BRW1EKcJ.js';
+import { T as TapEvent } from '../tapEvent-KSSojt_l.js';
+import { H as HitSlop, I as IntentEndInfo, c as IntentResult } from '../types-ChGKY28a.js';
 import 'react';
 import 'react-native-reanimated';
 
-/** The intent-shaped payload a {@link useTap} callback receives. */
-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}. */
 interface UseTapOptions extends GestureMemoOptions {
     /**
@@ -60,14 +45,23 @@ 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
@@ -111,7 +105,7 @@ type UseTapResult = IntentResult<TapGesture>;
  *
  * `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:
@@ -124,11 +118,22 @@ type UseTapResult = IntentResult<TapGesture>;
  * **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.
+ *
+ * **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' })
+ * ```
  *
- * **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.
+ * `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
@@ -147,4 +152,4 @@ type UseTapResult = IntentResult<TapGesture>;
  */
 declare function useTap(options?: UseTapOptions): UseTapResult;
 
-export { type TapEvent, type UseTapOptions, type UseTapResult, useTap };
+export { TapEvent, type UseTapOptions, type UseTapResult, useTap };

package/dist/tap/index.js

@@ -1,4 +1,5 @@
-export { useTap } from '../chunk-IG5RXCYR.js';
-import '../chunk-5BMRKYVY.js';
-import '../chunk-F4RHM4ZK.js';
+export { useTap } from '../chunk-IH7SQ5X6.js';
+import '../chunk-VEPUHGPN.js';
+import '../chunk-2UZTAWUQ.js';
+import '../chunk-NYDDZD4G.js';
 import '../chunk-ZX7WNICB.js';

package/dist/tapEvent-KSSojt_l.d.ts

@@ -0,0 +1,28 @@
+import { P as Point } from './types-ChGKY28a.js';
+
+/**
+ * The intent-shaped payload a tap callback receives.
+ *
+ * Shared by `useTap` and `useDoubleTap`, because the two recognize the same
+ * touch and differ only in how many times it happens. One payload rather than
+ * two identical ones means a consumer who already knows `useTap`'s event
+ * knows this one, and a field added later cannot reach one hook and miss the
+ * other.
+ */
+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;
+}
+
+export type { TapEvent as T };