feat(lab): RefreshControl pulls under a pen or a mouse as under a finger (spec:AST-094 FR43) by vjeux · Pull Request #8688 · meta/astryx

vjeux · 2026-10-27T12:42:22Z

Depends on #8175 and #8665 (with #8666's pen driver). Carries #8562 (Core's internal entries) as a dependency; if the entries land differently, this follows her decision. Review only this PR's change: vjeux/astryx@01e856a...2758073; later heads only merge #8175, #8665 and #8666.

Why

With a mouse or a stylus, nothing pulls to refresh: the pull reads only a finger, so a drag at the top of a refreshable list does nothing.

What led to it

Part of the touch-presentations program (spec:AST-094). Its FR43, now on main, has gestures run for every pointer, keeping off only what it lists; the pull to refresh isn't on that list.

Options and tradeoffs

Keep the mouse off, as a row swipe is: FR43 doesn't list it.
Take the top edge under every pointer: under a fine pointer, overscroll-behavior: none would remove the page's own rubber band, with no pull to replace it for a wheel.
One pull for every pointer, leaving the top edge to the browser under a fine pointer.

Why this choice

The third follows FR43 with the least new behavior: every pointer shares one mapping, trigger, settle and drawing. Under a fine pointer the browser keeps its own overscroll at the page's top, and the control watches no scroll (FR24). A pen's or a mouse's pull clears the text selection its drag started, then holds selection off, as a finger's does. Under Reduce Motion a release cross-fades where a finger let go or the primary pointer is coarse (design:reduced-motion DR2) and lands at once elsewhere (DR3). A trackpad's or a wheel's scroll follows in #8697.

How to check it

In a desktop browser, on the RefreshControl story "On the page":

Drag down from the top with the mouse: the content follows, the spinner turns past the trigger, and on release it settles under the spinner until the refresh ends.
Start the drag on text: the selection it began is cleared, and nothing is selected while pulling.
Turn on Reduce Motion and release a pull: the content lands at once.

Evidence

Each step failed before the change and passes now: 27 of 27 in Chromium; 19 in WebKit, where 8 pen and trace cases are skipped (Playwright's WebKit has no pen).
New unit tests fail first: a pen or a mouse pulls as a finger does and clears its drag's selection; under a fine pointer the control holds no scroll listener.
touch-support-bundle fails because this branch carries fix(useScrollLock): keep the page where it is while an overlay is open #8098's scroll lock; test(core): a touch component's import carries its gesture code, and nothing else does #8671's per-component test replaces it and passes here.
Size: RefreshControl 57.4 → 57.5 KB gzip JavaScript; CSS unchanged.

An attach reads the element's own will-change in a task of its own. A shared animator (animatorFor) is never detached, so its node can leave the document with that read still waiting, and the read then forces a style pass on a node with no style: a test run that mounts and unmounts many pagers piled up such reads until a later wait timed out. The read now skips a node out of the document; a promotion that needs it reads it then, as one on a node attached in the same task does. A detach and dispose already cancel it. The new test fails on the previous code (one read of a removed node); the in-task read test now puts its element in the document, where the read happens.

This pull request carried facebook#8561's earlier heads as a dependency. facebook#8561 is on main now, so the lint rule's files (eslint.config.js, the plugin's README, index.js, no-core-internal-import.js and its test) are main's, byte for byte; this pull request's own change (the internal entries, their tests, the export map, sync-exports and two changesets) is unchanged.

…ter the browser takes the touch A host that stopped feeding the finger at the takeover and still delivered the lift would have passed. Each transition now records the list's scrollTop, and the test expects a 'changed' while the list is scrolled (spec:AST-094 FR20: it follows the scroll to the lift).

…keover) into the host line

…her browser test) into the arena fixes The host-owner changeset keeps this PR's own listeners for the scroll lock and finger-scroll watch, with meta#8336's lone-finger scroll-edge hold.

…lues

… pull is reviewed against

… base merge, d32c911) into the refresh pull

…of the document) into meta#8270

…sture system (spec:AST-094 FR24, FR43) utils/pressFeedback.ts reaches gestures/coarsePointer.ts, so a page whose only touch work is press feedback carries a gesture module, and a bundle check that counts gestures/ code finds it in the root and hooks entries. The coarse-pointer query belongs with the environment queries. This test walks the controller's import graph and fails until it reaches no module under gestures/.

…ries in utils/ (spec:AST-094 FR43) gestures/coarsePointer.ts becomes utils/coarsePointer.ts, beside utils/touchQueries.ts, with its test; the gesture host's selection lock, the press controller and the pointer test helper import it from there. The press controller's import graph now reaches no module under gestures/, so a page whose only touch work is press feedback carries none of the gesture system. No behavior changes.

…/) into meta#8309

…/) into meta#8315

CI's lint rejected the three Array<T> types the previous commit added (@typescript-eslint/array-type); the test now names its record once (WatchTransition) and reuses it.

…e arena's reset The arena resets a recognizer to possible after it ends, as UIKit does, and the transition listener records that too, so the last transition is possible: the test now asserts the ended-then-possible tail.

…sign/core/internal/motion Lab no longer reaches Core's modules by path: Core's internal entries are the route. The import-rewrite codemod moves refreshPull.ts's Bézier, rubber-band and refresh-table imports onto @astryxdesign/core/internal/motion. The entry names the refresh table among its re-exports from the uikit barrel (a shared module may not import one component's table directly), and the entry coverage test lists it.

…/) into meta#8336

…/) into meta#8320

…finger, meta#8589's watcher test, its lint fix; meta#8076 3bfd7c3; the coarse-pointer query in utils/) into meta#8293

…nter query in utils/) into meta#8358

…nter query in utils/) into meta#8356 # Conflicts: # packages/core/src/gestures/GestureHost.ts # packages/core/src/gestures/fingerScroll.ts # packages/core/src/gestures/pageHold.ts # packages/core/src/gestures/selectionLock.ts # packages/core/src/utils/pressFeedback.ts

…nter query in utils/) into meta#8360

… FR19, FR24) Under a fine primary pointer: each element that uses a gesture keeps one passive pointerdown listener and the page none while idle; a mouse or a pen pans, its page listeners lasting only the press; a press consumer takes a mouse press with no feedback-only mode (DEC-21); a pan writes its touch-action for a touchscreen laptop's finger (FR18); perEventPointer is taken as any attach, with no warning; a secondary button starts nothing. All but the last fail until the host attaches for every pointer.

…#8098 280d775): the base useRefreshControl is reviewed against

… into useRefreshControl

… attached, in this host's terms meta#8360's action-group lifetime case pins that an element stays a group while any attachment asks and stops with the last. Here every element that uses a gesture is served as a group under a fine pointer, so the same invariant reads as the element's one passive pointerdown: with two gestures attached, detaching either keeps it, and detaching the last removes it. It passes on this head.

…esture host's subscriptions The gesture host subscribes no click: the one cancelling click subscriber is the click guard's, added at a window's first arm and kept. The release note, the stream's header and the gestures README listed click with the host's touchend and contextmenu; they now name the guard's own.

meta#8360's input-stream notes no longer list click among the gesture host's subscriptions. The merge is clean.

… lift and the browser's menu, keeps a kept press's finger, and goes when the page hides From the review of this pull request, three cases fail on its head: - an armed press installed the page listeners without the claiming ones, so a claimed finger's touchend stayed passive and the browser's menu opened during a claimed long press (spec:AST-094 FR21); - a kept press got its blocking touchmove during an armed press, but its moves were cancelled only where the primary pointer is coarse, so a held stepper on a touchscreen laptop lost its finger (FR11, DEC-21); - a page hidden mid-press cancelled the press but kept the page's listeners until the next lift anywhere (FR24).

…lift and the browser's menu, keeps a kept press's finger, and goes when the page hides - A finger's or a pen's armed press now brings the claiming listeners (the cancelable touchend and the contextmenu canceller) with the page listeners, as wherever the host installs, so a claimed lift clicks nothing and a claimed hold opens no browser menu (spec:AST-094 FR21). A mouse's press needs neither and adds neither. - A kept press keeps its finger under any pointer: its target blocks and its moves are cancelled once its press is delivered, not only where the primary pointer is coarse (FR11, DEC-21). - A page hidden mid-press releases the armed press as a blur does, so the page's listeners go with the cancelled press (FR24).

…'s selection An action group's press is a long press with no minimum duration, so it claims at the press's pointerdown, before any movement. The drag selection hold then cleared the page's selection, so a plain click on a group's button left its Copy or Cut with nothing to act on. The case fails on this head: the selection is gone after the pointerdown.

…age's selection The drag selection hold cleared the page's selection when any mouse or pen contact was claimed, but an action group's press claims at its pointerdown, before it has moved or selected anything, so a plain click on a group's button left its Copy or Cut with nothing to act on. A claim before any movement now keeps the page's selection: the hold still refuses a new one, and puts the page's back over a selection that appears while it runs. A claim after movement clears what its drag selected, as before (spec:AST-094 FR41). The case before the new one now waits for its hold to end a task after the lift, so no hold outlives that test.

…t every pointer does - GestureHost's header, the gestures README and coarsePointer.ts no longer describe the coarse-only host: a finger or a pen takes the touch-down lock under any primary pointer, a kept press's finger is kept during a fine pointer's press too, and recognizers attach for every pointer while the page listeners last a press (spec:AST-094 FR19, FR24, FR41, FR43). - The fine-pointer selection case asserted the replaced rule and passed only because it read iOS WebKit's inline lock without iOS WebKit: it now asserts the lock a fine pointer's finger and pen take, and that a mouse takes none. - FR41's sentence and its verification row say that a press claimed at its own pointerdown, before it moves, keeps the page's selection, while a drag that moved before its claim loses what it selected.

…ion, in the present tense The sentence said a drag that moved before its claim loses the selection it started, but the hold clears the page's selection then, whatever made it; and an unclaimed mouse drag kept "today's" behavior, a phrase that ages. It now says a claim after movement clears the page's selection, a press claimed at its own pointerdown keeps it, and an unclaimed mouse drag keeps its released behavior.

…6c02fc, the harness README, spec and index.ts as in 801dfa6750 (meta#8666 on meta#8360)

…nto the pen and mouse pull The harness README and browser spec take the helper's verified versions.

…he page presented Two proofs failed on a loaded machine with no defect in the control: - the busy-main-thread settle counted the screencast's delivered frames against its cadence. It now hands the compositor's own frame record to busyWindowProof, whose verdict alone judges the settle; a settle paused before the block fails it. - the catch read the settle's position before the touch, which lands later under load. A capture listener now records where the settle stood as the finger landed; a catch that restarts from zero travel fails it.

The harness browser spec takes meta#8676's version (35445d0), which already carries meta#8666 and meta#8665; the merge had dropped meta#8676's spec timing change.

astracat-bot

This needs an engineering owner's decision before it can be approved: the branch adds a requirement to spec:AST-094 FR41 that main does not have (a mouse or pen drag that a recognizer claims takes no new selection; an unclaimed one keeps the browser's). RefreshControl's pull never claims, yet it still clears a mouse or pen drag's selection, which neither FR41 text allows. An engineering owner records the decision by commenting /approve-spec <full head SHA> on this pull request, or by asking for a different FR41 text; the author may do so as an engineering owner. Separately from that decision:

Rebase onto main once the carried pull requests land, so the diff holds only the 7 RefreshControl files (537 authored lines instead of 37,012).
A mouse pull ends with the browser's click on the row it started on, because nothing claims the mouse or suppresses that click. A mouse case over a row that acts on click would pin the fix.
Under a fine pointer, a pull during a refresh the app started jumps the list 60 px down over an empty band and leaves it there until the refresh ends (refreshTouchController.ts:788-793).

[Automated review]

astracat-bot · 2026-10-30T00:28:12Z

+  (`spec:AST-017` FR59; DEC-9). A mouse or pen drag that a recognizer claims
+  takes no new text selection for that drag only. A claim made after the
+  drag has moved clears the page's selection; a press claimed at its own
+  pointerdown, before it moves, keeps it. An unclaimed mouse drag keeps its
+  released behavior.


This adds a normative FR41 requirement and, at line 663, narrows its verification row; main states neither. It needs an engineering owner's exact-head approval (/approve-spec <full head SHA>). As written it keeps an unclaimed mouse drag's released behavior, which RefreshControl's pull (a watcher that never claims) does not keep.

astracat-bot · 2026-10-30T00:28:12Z

+          if (pan.pointerType !== 'touch') {
+            clearDragSelection();
+          }


RefreshPullRecognizer never claims (claimsTouches returns false), so under FR41 on main, and under this branch's amendment, a mouse drag keeps its selection. Clearing it here, and refusing selection until the pull ends, waits on an engineering owner's FR41 decision.

astracat-bot · 2026-10-30T00:28:12Z

+      releaseSelection();
+      dispatch({type: pan.state === 'ended' ? 'pullEnd' : 'pullCancel'});


Under a mouse nothing claims this drag or takes it from the browser, so the arena resolves the lift as 'allow' and arms no click guard. The content travels with the pointer (10 px behind it), so the browser's click then lands on the row the drag began on, and a row that is a link or a button opens at the end of a pull to refresh. Arming the shared click guard (armClickGuard) when a mouse or pen pull ends, with a mouse case over a clickable row, would prevent it.

…kes meta#8688's text, with this PR's sentence

…dy part The proof failed on a loaded machine with one long task: it judged long tasks over the whole trace, the pull's trigger and the release's render included, while Layout and Paint were judged only in the steady part. Under a 4x CPU throttle the release's last commit frame also landed past the fixed 50 ms start. The steady part now starts once the page has rendered three frames after the settle began, counted in frames, and long tasks are judged there too. It passes 4 of 4 under the throttle; a paint on every frame of the settle, or an 80 ms block inside it, still fails it.

astracat-bot

This needs an engineering owner's decision before it can be approved: the branch adds a requirement to spec:AST-094 FR41 that main does not have (a mouse or pen drag that a recognizer claims takes no new selection; an unclaimed one keeps the browser's), and RefreshControl's pull, which never claims, still clears a mouse or pen drag's selection, which neither FR41 text allows. An engineering owner records the decision by commenting /approve-spec <full head SHA> on this pull request, or by asking for a different FR41 text; the author may do so as an engineering owner. Separately from that decision:

Rebase onto main once the carried pull requests land, so the diff holds only the 7 RefreshControl files (537 authored lines instead of 37,052).
A mouse pull released while the content still tracks the pointer ends with the browser's click on the row it started on, because nothing claims the mouse or suppresses that click; a mouse case over a row that acts on click would pin the fix.
Under a fine pointer, a pull during a refresh the app started jumps the list 60 px down over an empty band and leaves it there until the refresh ends (refreshTouchController.ts:788-793).

[Automated review]

vjeux and others added 30 commits October 26, 2026 21:34

Merge facebook#8589 (the watcher's browser test checks moves after th…

21347b3

…keover) into the host line

Merge meta#8336 (vjeux's two-finger scroll-edge fix; meta#8589's watc…

528e3e1

…her browser test) into the arena fixes The host-owner changeset keeps this PR's own listeners for the scroll lock and finger-scroll watch, with meta#8336's lone-finger scroll-edge hold.

Merge meta#8562 abb3e0f (Core's internal entries) into the refresh va…

f40a806

…lues

Merge meta#8076 3bfd7c3 (the isConnected guard): the base the refresh…

d32c911

… pull is reviewed against

Merge meta#8086 537fadc, meta#8562 abb3e0f and meta#8076 3bfd7c3 (one…

c53d0b7

… base merge, d32c911) into the refresh pull

Merge facebook#8076 (3bfd7c3: the animator reads no style for a node …

2119cfa

…of the document) into meta#8270

Merge meta#8270 (meta#8076 3bfd7c3; the coarse-pointer query in utils…

9db6af5

…/) into meta#8309

Merge meta#8309 (meta#8076 3bfd7c3; the coarse-pointer query in utils…

999afb7

…/) into meta#8315

test(gestures): the watcher's browser test names its record type (lint)

b57ac07

CI's lint rejected the three Array<T> types the previous commit added (@typescript-eslint/array-type); the test now names its record once (WatchTransition) and reuses it.

Merge meta#8589 (the watcher browser test's lint fix) into the host line

6cca0de

Merge meta#8336 (meta#8589's lint fix) into the arena fixes

ea8531c

Merge meta#8320 0567e2c (F2's line, wave 2) into the scroll lock's base

99b0a4f

Merge meta#8320 0567e2c (one base merge, 99b0a4f) into the scroll lock

280d775

Merge meta#8315 (meta#8076 3bfd7c3; the coarse-pointer query in utils…

790c65e

…/) into meta#8336

Merge meta#8336 (meta#8076 3bfd7c3; the coarse-pointer query in utils…

2fd9697

…/) into meta#8320

Merge meta#8320 (cixzhang's ea8531c: the scroll-edge hold for a lone …

45b25e4

…finger, meta#8589's watcher test, its lint fix; meta#8076 3bfd7c3; the coarse-pointer query in utils/) into meta#8293

Merge facebook#8356 (facebook#8320 ea8531c; facebook#8076 3bfd7c3; th…

e95a4e2

…nter query in utils/) into meta#8358

Merge meta#8358 (meta#8320 ea8531c; meta#8076 3bfd7c3; the coarse-poi…

741787a

…nter query in utils/) into meta#8360

Merge the refresh pull (meta#8170 0eef716) with the scroll lock (meta…

69ed044

…#8098 280d775): the base useRefreshControl is reviewed against

Merge useRefreshControl (meta#8171 f666ef2) into RefreshControl

689e80e

Merge facebook#8098 280d775 and facebook#8170 0eef716 (one base merge, …

8f40fab

… into useRefreshControl

vjeux added 19 commits October 29, 2026 10:32

Merge meta#8360 045f666 into meta#8665

1adb531

meta#8360's input-stream notes no longer list click among the gesture host's subscriptions. The merge is clean.

Merge meta#8360 045f666 into the refresh values

1125110

Merge meta#8360 045f666 into the scroll lock

5d9fc1a

Merge meta#8086 1125110 (with meta#8360) into the pull and state machine

f2b0269

Merge meta#8170 f2b0269 into useRefreshControl

0684c9b

Merge meta#8098 5d9fc1a into useRefreshControl

338dc33

Merge meta#8171 338dc33 into RefreshControl

189b98b

Merge meta#8666 08a2a28 (wheel and pen input drivers) into meta#8665 c…

8d35612

…6c02fc, the harness README, spec and index.ts as in 801dfa6750 (meta#8666 on meta#8360)

Merge the harness helper 8d35612 (meta#8665 c6c02fc with meta#8666) i…

9fa633d

…nto the pen and mouse pull The harness README and browser spec take the helper's verified versions.

Merge meta#8175 2c7fc52 into the pen and mouse pull

0c05d6e

vjeux marked this pull request as draft October 29, 2026 22:39

vercel Bot deployed to Preview October 30, 2026 00:04

View deployment

astracat-bot Bot reviewed Oct 30, 2026

View reviewed changes

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

Merge meta#8688 (0c05d6e) into this PR's base, with meta#8251 (6b391ad)

304fec5

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

Merge meta#8251 (6b391ad) and meta#8688 (0c05d6e): the spec header ta…

8fae365

…kes meta#8688's text, with this PR's sentence

vjeux added 2 commits October 29, 2026 18:31

Merge meta#8175 16f8df7 into the pen and mouse pull

079927a

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

Merge meta#8688 079927a into the trackpad and wheel pull

fa05917

vercel Bot deployed to Preview October 30, 2026 01:51

View deployment

astracat-bot Bot reviewed Oct 30, 2026

View reviewed changes

Navigation Menu

Repository navigation

feat(lab): RefreshControl pulls under a pen or a mouse as under a finger (spec:AST-094 FR43) - #8688

feat(lab): RefreshControl pulls under a pen or a mouse as under a finger (spec:AST-094 FR43)#8688
vjeux wants to merge 1999 commits into
meta:mainfrom
vjeux:uikit/c28-refresh-every-pointer

vjeux commented Oct 27, 2026 •

edited

Loading

Uh oh!

astracat-bot Bot left a comment

Uh oh!

astracat-bot Bot Oct 30, 2026

Uh oh!

astracat-bot Bot Oct 30, 2026

Uh oh!

astracat-bot Bot Oct 30, 2026

Uh oh!

astracat-bot Bot left a comment

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		releaseSelection();
		dispatch({type: pan.state === 'ended' ? 'pullEnd' : 'pullCancel'});

Conversation

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

Uh oh!

Why

What led to it

Options and tradeoffs

Why this choice

How to check it

Evidence

Uh oh!

astracat-bot Bot left a comment

Choose a reason for hiding this comment

Uh oh!

astracat-bot Bot Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

astracat-bot Bot Oct 30, 2026

Choose a reason for hiding this comment

Uh oh!

astracat-bot Bot Oct 30, 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!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vjeux commented Oct 27, 2026 •

edited

Loading