feat(core): tap and long-press recognizers with UIKit's measured thresholds by vjeux · Pull Request #8059 · meta/astryx

vjeux · 2026-10-24T04:04:52Z

Depends on #8058 (and its predecessors); review the last commit.

Primary intent

Add the first two recognizers on the gesture core: tap and long press, with UIKit's measured thresholds.

User or maintainer impact

Taps, double taps and long presses are re-implemented per component today, with their own slops and timers. A long press can fire late when the main thread is busy, and a single tap can fire alongside a double tap. These recognizers give every component UIKit's numbers. A long press begins at exactly touch-down + 0.5 s, even when the callback runs late.

Problem and solution fit

Why does it happen? Each component keeps its own timers and slops.
Why does that hurt? Taps fail or fire twice, and long presses start late or at the wrong distance.
Why does it matter? These are the commonest gestures on a phone.

Deltas:

TapGestureRecognizer:
- taps and fingers;
- recognized at the lift;
- fails past its allowable movement (a distance), on extra fingers, a hold past the maximum, or a late or far next tap.
LongPressGestureRecognizer:
- the press duration as a deadline on the event clock;
- the movement tolerance as a distance;
- taps before the press;
- a zero duration begins on the touch itself, for selection tracking over a group of actions.
The arena with these real recognizers: tap against double tap with and without require-to-fail, delegate requirements, delivery and deferred clicks, cancellation before and after a long press began.

Authority

spec:AST-094 (FR15–FR17), proposed; pending owner review. Thresholds come from motion/uikit/gestures.ts with their sources.

Change and evidence

Read from UIKit's recognizers in a reference app on the iOS 26.2 simulator, confirmed with HID touches:

tap: 45 pt of movement (Euclidean); taps 0.35 s and 45 pt apart; a 1.5 s maximum hold;
long press: 0.5 s and 10 pt as a distance (a 7, 7 drift begins, 7.2, 7.2 fails).

Mobile Safari, which runs UIKit's tap and double-tap recognizers, agrees:

a click up to 45 px of travel;
a double tap up to about 350 ms and 45 px apart.

The tests use explicit timestamps only.

Scope

This PR has one primary intent.
Independently removable deltas were removed or split.
Public text and artifacts contain no internal Meta context.

Testing

pnpm exec vitest run --project ui packages/core/src/gestures packages/core/src/motion: 184 tests passed.
tsc --project packages/core/tsconfig.json --noEmit: clean.
eslint packages/core/src/gestures: clean.
pnpm check:changesets, node scripts/release/changeset-coverage.mjs pr --base origin/main: clean.
Size: 7 files, 821 lines added.

Stack (merge in this order): #8052 spec → #8053 constants table → #8058 gesture core → #8059 tap and long press → #8060 pan → #8061 other recognizers → #8054 math → #8055 animator → #8056 animator curves; the gesture DOM host, press tracking and browser proof follow the animator.

Springs, scroll physics, timing curves, navigation values and gesture thresholds for the touch presentations of core components, each with its source (Apple documentation, a WWDC session, WebKit's UIKit-matched source, or a measurement of UIKit on the iOS 26.2 simulator) or labelled a guess with its measurement task. A test enforces the source rules on every domain file, in their JSDoc and typed forms, and checks the list of simulator measurements still owed.

…rena An internal gesture system for touch presentations, not exported from the package. GestureRecognizer carries UIKit's states and allowed transitions, discrete and continuous recognizers, require-to-fail, simultaneous recognition on request, shouldBegin and shouldReceiveTouch, cancelsTouchesInView and the touch delays. GestureArena settles each touch sequence without the DOM: participants, resolution order, claims, delivery to the view, click dispositions (allow, suppress, defer and replay) and timers as deadlines on the event clock. Its rules are tested with scripted recognizers, independent of any real one.

…sholds Tap recognizes at the lift within 45 pt of movement, taps 0.35 s and 45 pt apart, and a 1.5 s hold; long press begins at exactly touch-down + 0.5 s on the event clock within 10 pt, even when the main thread was blocked, and a zero duration begins on the touch itself. The arena tests with these real recognizers cover tap against double tap, delegate requirements, deferred clicks and cancellation.

vercel · 2026-10-24T04:04:56Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
astryx	Ready	Preview	Oct 26, 2026 3:51am UTC

astracat-bot · 2026-10-24T04:05:13Z

AI review status for this pull request.

Review status	Updated
🟢 Reviewed (for maintainers only)	Oct 26, 2026, 4:03 AM UTC

astracat-bot

This pull request is on hold for a spec decision: the tap and long-press recognizers, the gesture core and the UIKit constants table rest only on draft spec:AST-094, so an engineering owner needs to approve FR1, FR2, FR12 and FR15–FR17 (approving the record as written also accepts FR4, FR11 and FR14's changes to theme-tokens, user-states and AST-025) by commenting /approve-spec <full head SHA> on this pull request, which the author may do as an engineering owner, or the change waits until #8052 lands the record. Independently of that decision, please address these points:

A two-finger double tap fails at its second tap because TapGestureRecognizer.ts:93-101 compares the next tap's first finger with the previous tap's last-lift position, so compare centroids (or matching fingers) and add a two-finger double-tap test.
After a long task, if the arena's own timer runs before a queued touchend, GestureArena.ts:831-836 begins a long press whose finger already lifted, so yield to queued input before running a late deadline and test that order.
The diff carries 5,065 lines because #8052, #8053 and #8058 ride along, so land them first to make this pull request its own 821-line commit, and rerun the Lint job, which aborted out of memory.

[Automated review]

astracat-bot · 2026-10-24T04:36:23Z

+      const first = touches[0];
+      if (
+        this.firstTapLocation != null &&
+        distance({x: first.startX, y: first.startY}, this.firstTapLocation) >
+          this.allowableSeparation
+      ) {
+        this.setState('failed');
+        return;
+      }


A two-finger double tap fails here: touches[0] is the next tap's first finger, but firstTapLocation (line 145) is the previous tap's last-lift position, or its centroid when the fingers lift together. The same two-finger tap repeated at the same two points 100 px apart fails at the second tap's first finger. Compare the next tap's centroid once its required fingers are down with the first tap's centroid (or each finger with the nearest first-tap finger), and add a two-finger double-tap test.

astracat-bot · 2026-10-24T04:36:23Z

+    const delay = Math.max(0, earliest - this.clock.now());
+    this.realTimer = this.clock.setTimeout(() => {
+      this.realTimer = null;
+      this.realTimerDeadline = Number.POSITIVE_INFINITY;
+      this.advanceTime(Math.max(earliest, this.clock.now()));
+    }, delay);


After a long task the browser may run this timer task before a queued touchend. advanceTime(Math.max(earliest, this.clock.now())) then runs the long-press deadline first, so a finger that lifted at 300 ms during a 100–900 ms block still begins a press at 500 and ends it at 900 instead of failing at 300. Consider yielding once to queued input before running a late deadline, and add a test whose clock fires the timer before the queued lift.

…ntrant settle fixes) into the tap and long-press recognizers

…recognizer # Conflicts: # packages/core/src/motion/uikit/gestures.ts

No conflicts. Brings main's per-group UIKit table (meta#8468) through meta#8058 and meta#8059, with meta#8060's velocity rows inside UIKIT_VELOCITY.

astracat-bot

Changes requested: the tap and long-press recognizers follow current spec:AST-094, and the taps phase now names its measurement (M-G20) with the second-finger case tested, but two points remain before this can land.

TapGestureRecognizer.ts and LongPressGestureRecognizer.ts import the UIKIT_GESTURES union, which bundles all eleven gesture groups into any component that adopts them (about 0.3 KB gzip of other recognizers' rows), so please import UIKIT_TAP and UIKIT_LONG_PRESS by name, as architecture:component-style-authoring INV6 asks.
The diff is 3,736 lines because #8058 rides along, so land #8058 first to make this pull request its own 948 lines.

A smaller fix would also help: the SYNC notes in GestureArena.ts and GestureRecognizer.ts name files that do not exist.

[Automated review]

astracat-bot · 2026-10-26T02:46:08Z

+ * tap that requires a double tap to fail waits the interval out, as in UIKit.
+ */
+
+import {UIKIT_GESTURES} from '../motion/uikit/gestures';


The UIKIT_GESTURES union bundles every gesture group (object properties do not tree-shake, as motion/uikit/gestures.ts:277-282 notes): an esbuild bundle of this recognizer carries all eleven groups' rows, 2,626 B gzip against 2,301 B with import {UIKIT_TAP} from '../motion/uikit/gestures' and const TAP = UIKIT_TAP; (line 43). architecture:component-style-authoring INV6: "importing a component does not pull in rows only other components read".

astracat-bot · 2026-10-26T02:46:08Z

+ * a blocked main thread delays the callback, not the moment it reports.
+ */
+
+import {UIKIT_GESTURES} from '../motion/uikit/gestures';


Same as the tap recognizer: this reads only the long-press and tap groups (lines 59-64, 165, 173), so import {UIKIT_LONG_PRESS, UIKIT_TAP} from '../motion/uikit/gestures' keeps the other nine groups out of an adopting component's bundle (2,521 B gzip today, 2,222 B with the named imports; INV6).

…ure groups They imported the UIKIT_GESTURES union, whose object properties do not tree-shake, so the first adopter bundled all eleven groups. They now import UIKIT_TAP and UIKIT_LONG_PRESS by name (INV6): the tap recognizer bundles to 2,288 B gzip, the long press to 2,220 B.

astracat-bot

Changes requested: the tap and long-press recognizers follow current spec:AST-094, and both now import only their own UIKit gesture groups, but the diff still carries #8058's gesture core (3,735 lines in all), so please land #8058 first to make this pull request its own 947 lines. Two smaller fixes would also help: the SYNC notes in GestureArena.ts and GestureRecognizer.ts still name files that do not exist (#8058's head already corrects them), and the long press still bundles the two UIKIT_TAP rows it never reads (about 14 B gzip).

[Automated review]

astracat-bot · 2026-10-26T03:15:45Z

+ * SYNC: When modified, update GestureRecognizer.ts, GestureHost.ts,
+ * GestureArena.test.ts and README.md.


This SYNC list names GestureHost.ts, GestureArena.test.ts and README.md, none of which exists under gestures/ at this head (the arena's tests are __tests__/arena.test.ts). #8058's head already lists only the files that exist; bringing it into this branch fixes this. Not blocking.

astracat-bot · 2026-10-26T03:15:45Z

+ * event, so a listener that writes a transform writes it in the same frame
+ * as the input, with no React render in between.
+ *
+ * SYNC: When modified, update GestureArena.ts and README.md.


README.md does not exist under gestures/ at this head; #8058's head already drops it from this SYNC note. Not blocking.

astracat-bot · 2026-10-26T03:15:45Z

+ * a blocked main thread delays the callback, not the moment it reports.
+ */
+
+import {UIKIT_LONG_PRESS, UIKIT_TAP} from '../motion/uikit/gestures';


Importing the whole UIKIT_TAP group to read maximumTapDuration and maximumIntervalBetweenTaps also bundles its allowableMovement and allowableSeparation rows, which only the tap recognizer reads (about 14 B gzip). Not blocking: giving UIKIT_LONG_PRESS the taps phase's own two rows, labelled a guess naming M-G20, would keep a long-press-only adopter to its own rows (architecture:component-style-authoring INV6).

…rena (#8058) Depends on #8053 (and its predecessors); review the last commit.  ## Primary intent Add the core of an internal gesture-recognizer system for touch presentations: UIKit's recognizer state machine and the arena that settles which recognizer owns a touch sequence. Recognizers, the DOM host and component migrations follow in their own pull requests; nothing is exported from the package. ## User or maintainer impact Touch components each carry their own pointer handling (sheet drags, swipe actions, toast dismissal, long press, press feedback), with their own answer to "who owns this touch". Two can act on one touch, and a second finger can break a drag. With one arena every component gets UIKit's answers: exclusive recognition by default, `requireToFail`, simultaneous recognition only on request, a deterministic resolution order, and the view's touches cancelled (no click, no pressed state) once a gesture takes them. ## Problem and solution fit - Why does it happen? Ownership of a touch is decided separately in each component. - Why does that hurt? Ghost clicks, double actions, and rules that differ from component to component. - Why does it matter? Touch presentations aim at UIKit parity, and UIKit settles this in one place. Deltas: - `GestureRecognizer`: - UIKit's states (possible, began, changed, ended, cancelled, failed) and allowed transitions; - discrete and continuous recognizers; - `requireToFail`, `recognizeSimultaneouslyWith`, `shouldBegin`, `shouldReceiveTouch`; - `cancelsTouchesInView`, `delaysTouchesBegan` and `delaysTouchesEnded`, `allowedPointerTypes`. - `GestureArena`, with no DOM: - participants per touch sequence, resolution and claims; - delivery to the view; - click dispositions: allow, suppress, or defer and replay if the recognizer fails; - timers as deadlines on the event clock. ## Authority `spec:AST-094` FR15 (arbitration) and FR16 (the event clock), proposed; pending owner review. ## Change and evidence The arena's rules are tested with scripted recognizers, test doubles that begin, fail or wait on command. The rules hold independently of any real recognizer: - exclusivity and simultaneity; - require-to-fail: waiting, failing, delegate requirements, idle recognizers; - delegate hooks and innermost resolution; - independent touches; - delivery to the view, deferred and replayed clicks, the browser taking a touch; - cancellation; - a deadline that runs at its own time before a late input. Size: 2,198 lines, about 400 of them tests. This is one indivisible intent: the recognizer base and the arena call each other, so neither builds or tests alone, and the doubles-only tests are the smallest proof of the rules. ## Scope - [x] This PR has one primary intent. - [x] Independently removable deltas were removed or split. - [x] Public text and artifacts contain no internal Meta context. ## Testing - `pnpm exec vitest run --project ui packages/core/src/gestures packages/core/src/motion`: 159 tests passed. - `tsc --project packages/core/tsconfig.json --noEmit`: clean. - `eslint packages/core/src/gestures`: clean. - `pnpm check:changesets`, `node scripts/release/changeset-coverage.mjs pr --base origin/main`: clean. - Size: 6 files, 2,205 lines added. Stack (merge in this order): #8052 spec → #8053 constants table → #8058 gesture core → #8059 tap and long press → #8060 pan → #8061 other recognizers → #8054 math → #8055 animator → #8056 animator curves; the gesture DOM host, press tracking and browser proof follow the animator.

The arena and recognizer base take main's landed versions; this branch makes no edits to them.

astracat-bot

Ready for approval: both recognizers follow current spec:AST-094 (FR12, FR15–FR18), read UIKit's measured thresholds from the constants table, and have timestamped tests on both sides of every limit. Nothing else is required; optionally, giving UIKIT_LONG_PRESS its own two taps-phase rows (labelled a guess with @measure M-G20) would put that guess under the table's source check and keep the tap's other rows out of a long-press-only bundle, and the description could drop the stale "proposed" status and file count.

[Automated review]

# Conflicts: # packages/core/src/gestures/LongPressGestureRecognizer.ts # packages/core/src/gestures/TapGestureRecognizer.ts # packages/core/src/motion/MEASUREMENTS.md

No conflicts. Brings main with meta#8059 landed through meta#8060.

No conflicts. Brings main with meta#8059 landed, through meta#8060 and meta#8061.

…listeners only for an enabled consumer) into UIControl press tracking

The touch foundation's fold, mergeable against main cd4aca6: her chain on main (meta#8058, meta#8054, meta#8059, meta#8060) and meta#8258's rework, which keeps touch motion internal (no theme surface): the generated role table, its script and the role kinds file are gone, and a table registers only the roles it lists. The motion doc and its golden take meta#8076's side; the role kinds file stays deleted.

meta#8076's head is F1's fold on the maintainer's chain now on main (meta#8058, meta#8054, meta#8059, meta#8060): touch motion is internal (the tables register their values as internal motion roles, with no theme surface), and the `isRtlElement` resolver. Conflicts, resolved: - The theme-roles changeset and the motion guide take meta#8076's side; their sentence on ChatLayout's Reduce Motion cross-fade goes with the theme surface. - The CLI goldens for the empty icon set take meta#8076's side and regenerate. - keyboardModel.test.ts reads the internal role registry (`motionRoleIn`) now that the generated role-kind table is gone, and no longer names a theme.

…eta#8258 194aab4) into meta#8270 The long press reads its own and the tap's UIKit groups, as main's meta#8059 does, and keeps this PR's lock rule (a hold brings lockSelection; 0 ms and null bring none); the host keeps her coarse-pointer option without the held-selection map this PR dropped.

vjeux added 4 commits October 23, 2026 20:53

spec(AST-094): touch presentations follow UIKit

4076bf3

vjeux requested review from cixzhang, imdreamrunner and josephfarina as code owners October 24, 2026 04:04

This was referenced Oct 24, 2026

feat(core): pan gesture recognizer with UIKit's hysteresis and velocity #8060

Merged

feat(core): swipe, pinch and screen-edge pan recognizers #8061

Merged

feat(core): gesture recognizer core — UIKit's state machine and the arena #8058

Merged

meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Oct 24, 2026

astracat-bot Bot reviewed Oct 24, 2026

View reviewed changes

This was referenced Oct 24, 2026

fix(Item): a list row's touch press release runs on the compositor #8077

Draft

DropdownMenu: under a finger the trigger opens as the finger presses (AST-094 FR29) #8078

Draft

feat(List): a touch press hides the dividers beside the pressed row #8079

Closed

Merge meta#8058 (main with the per-group UIKit table, meta#8468; re-e…

4e0edaf

…ntrant settle fixes) into the tap and long-press recognizers

cixzhang added a commit to vjeux/astryx that referenced this pull request Oct 26, 2026

Merge meta#8059 (4e0edaf: main's per-group UIKit table) into the pan …

411c960

…recognizer # Conflicts: # packages/core/src/motion/uikit/gestures.ts

vercel Bot deployed to Preview October 26, 2026 02:30

View deployment

astracat-bot Bot requested changes Oct 26, 2026

View reviewed changes

vjeux mentioned this pull request Oct 26, 2026

feat(ChatLayout): the composer rides the software keyboard #8176

Draft

vercel Bot deployed to Preview October 26, 2026 03:01

View deployment

astracat-bot Bot requested changes Oct 26, 2026

View reviewed changes

Merge main (meta#8058 landed) into the tap and long-press recognizers

b47bcbc

The arena and recognizer base take main's landed versions; this branch makes no edits to them.

vercel Bot deployed to Preview October 26, 2026 03:51

View deployment

astracat-bot Bot approved these changes Oct 26, 2026

View reviewed changes

cixzhang merged commit 19a7a46 into meta:main Oct 26, 2026
118 of 120 checks passed

vjeux deleted the wip/uikit-pr-g1b branch October 26, 2026 04:42

cixzhang added a commit to vjeux/astryx that referenced this pull request Oct 26, 2026

Merge meta#8060's head (99b47ce) into the gesture recognizers

447db56

No conflicts. Brings main with meta#8059 landed through meta#8060.

cixzhang added a commit to vjeux/astryx that referenced this pull request Oct 26, 2026

Merge facebook#8061's head into browser negotiation

8faa78c

No conflicts. Brings main with meta#8059 landed, through meta#8060 and meta#8061.

cixzhang added a commit to vjeux/astryx that referenced this pull request Oct 26, 2026

Merge 8faa78c (meta#8071 with main, meta#8059 landed) as a dependency

b0c024a

This was referenced Oct 26, 2026

chore(core): UISlider's measured values #8189

Draft

feat(core): one interactive-transition driver, with BottomSheet on it #8341

Draft

cixzhang added a commit to vjeux/astryx that referenced this pull request Oct 26, 2026

Merge meta#8072 (606e815: main through meta#8059, the fixed-bar fix, …

e6548b9

…listeners only for an enabled consumer) into UIControl press tracking

astracat-bot Bot mentioned this pull request Oct 26, 2026

feat(lab): TabBar — disabled tabs, and the collapsed bar as one element #8210

Draft

4 tasks done

astracat-bot Bot mentioned this pull request Oct 26, 2026

feat(core): UIScrollView zoom constants and the zoom stage geometry #8147

Draft

This was referenced Oct 26, 2026

fix(core): one input stream on the window's capture phase for the press feedback and the gesture host #8356

Closed

fix(core): one click guard for the menu press model and the gesture host #8360

Open

astracat-bot Bot mentioned this pull request Oct 26, 2026

fix(useScrollLock): keep the page where it is while an overlay is open #8098

Draft

		* SYNC: When modified, update GestureRecognizer.ts, GestureHost.ts,
		* GestureArena.test.ts and README.md.

Conversation

vjeux commented Oct 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Primary intent

User or maintainer impact

Problem and solution fit

Authority

Change and evidence

Scope

Testing

Uh oh!

vercel Bot commented Oct 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

astracat-bot Bot commented Oct 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

astracat-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

astracat-bot Bot Oct 24, 2026

Choose a reason for hiding this comment

Uh oh!

astracat-bot Bot Oct 24, 2026

Choose a reason for hiding this comment

Uh oh!

astracat-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

astracat-bot Bot Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

astracat-bot Bot Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

astracat-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

astracat-bot Bot Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

astracat-bot Bot Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

astracat-bot Bot Oct 26, 2026

Choose a reason for hiding this comment

Uh oh!

astracat-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vjeux commented Oct 24, 2026 •

edited

Loading

vercel Bot commented Oct 24, 2026 •

edited

Loading

astracat-bot Bot commented Oct 24, 2026 •

edited

Loading