@jsenv/navi 0.29.418 → 0.29.420

package/docs/list_action.md

@@ -29,8 +29,7 @@ refuses in the meantime, which is what you want when the rows are alternatives.
 ```
 
 A press on another row while it runs is refused and says so, in the selection's
-own words ("le choix est en cours d'enregistrement", "la sélection…" in a
-`multiple` list) rather than in a row's.
+own words rather than in a row's.
 
 ## On a row's control: that row waits alone
 
@@ -61,22 +60,20 @@ stay live. Two rows can be in flight at once.
 ```
 
 The command is what marks the row, and it runs **only if the action succeeded**
-— a button given both runs its action first and lets its command follow (see
-[actions.md](./actions.md#a-press-that-opens-something-and-waits-for-the-answer)). So a refused invitation leaves the row unmarked
-without anything to undo.
-
-`selectableArea="manual"` is about the row's own surface, not about the button:
-a control inside a row answers its own press whichever area the row claims.
-What it removes is the row selecting under a press that lands beside the button
-— here what marks the row is the command, once the invitation went through.
+(see [actions.md](./actions.md#a-press-that-opens-something-and-waits-for-the-answer)),
+so a refused invitation leaves the row unmarked without anything to undo.
+`selectableArea="manual"` keeps the row from selecting under a press that lands
+beside the button — here what marks the row is the command, once the invitation
+went through; a control inside a row answers its own press whichever area the
+row claims.
 
 ## Who draws the wait, and who answers a press
 
 **Whatever control is on the row carries the wait and the refusal.** A button,
 a checkbox, a picker — it has a place to draw a spinner and an anchor to hang a
-callout on, and it is what the user pressed. The row itself is the fallback,
-for a row that holds nothing but text: it draws a loading outline, swallows
-presses (its buttons included) and opens the sentence itself.
+callout on, and it is what the user pressed. The row itself is the fallback, for
+a row that holds nothing but text: it draws a loading outline, swallows presses
+(its buttons included) and opens the sentence itself.
 
 That is why a selectable row does not answer a press twice. It swallows the
 press so nothing inside it acts, then asks the control it carries to explain —
@@ -95,13 +92,8 @@ belongs on the button; pressed on the row's own surface, on the row:
 | the button of a row held back by something else | the button                 |
 
 The last one needs nothing special: that row is not blocked, so the press
-reaches the button and the button's own gate answers it.
-
-A row that would rather always take it says so once:
-
-```jsx
-<List.Item data-callout-anchor="item" />
-```
+reaches the button and the button's own gate answers it. A row that would rather
+always take it says so once: `<List.Item data-callout-anchor="item" />`.
 
 ## Read-only, not loading
 
@@ -113,10 +105,10 @@ use, and what says that is `readOnly`:
 ```
 
 `loading` on a row means the ROW is waiting on something — being added to the
-list, removed from it, saved where it is (see the `loading` values on
-`List.Item`). Putting it there for a control's run draws a second wait next to
-the one the button is already drawing, and says the row is being changed when it
-is only being used.
+list, removed from it, saved where it is (the `loading` values of `List.Item`).
+Putting it there for a control's run draws a second wait next to the one the
+button is already drawing, and says the row is being changed when it is only
+being used.
 
 Give the row a `readOnlyMessage` when it is held for a reason that will pass:
 the default sentence is about availability ("this option is not available"),
@@ -125,45 +117,38 @@ which is the wrong thing to say about a wait.
 ## Hold the rows, not the list
 
 It is tempting to write `<List readOnly={pending}>` to keep a second row from
-being pressed while one is in flight. It works, and it works by luck: the
-command the button fires on success (`--navi-select`) is aimed at the list, and
-a list still read-only at that moment refuses it — the call goes through and the
-row is never marked, silently.
+being pressed while one is in flight, and it works by luck: the command the
+button fires on success (`--navi-select`) is aimed at the list, and a list still
+read-only at that moment refuses it — the call goes through and the row is never
+marked, silently. Whether it lands comes down to one tick (the flag cleared in a
+`finally`, or a moment later), and nothing on screen says which you wrote.
 
-Whether it lands comes down to one tick. Clearing the flag in a `finally` clears
-it before the command runs, so the selection arrives; clearing it a moment later
-— a transition, a debounce, one more `await` on the way out — loses it. Nothing
-on screen says which of the two you wrote.
-
-Hold the rows instead. `readOnly` on every row is what "one at a time" looks
-like, it says the same thing on screen, and it leaves the list free to take the
-answer whenever the answer comes:
+Hold the rows instead: `readOnly` on every row says the same thing on screen and
+leaves the list free to take the answer whenever the answer comes.
 
 ```jsx
 <List.Item readOnly={pending !== null} />   // all of them: one at a time
 <List.Item readOnly={pending.includes(name)} />  // this one: each on its own
 ```
 
-## How many at once: `parallelGuard`
+One at a time also needs no state of the app's: `<List parallelGuard={1}>`
+holds every control that would start a run while one is out (below).
 
-A list is a place where the same gesture is available many times over, and
-nothing about a row's own action stops someone from starting one on every row it
-draws — a dozen requests in flight because the list happened to be long.
+## How many at once: `parallelGuard`
 
-So a list allows **four runs at once by default**. While that many are out,
-every control in it that would start another run goes read-only and says how
-many it is waiting on; the next press is possible again the moment one comes
-back.
+Nothing about a row's own action stops someone from starting one on every row a
+list draws — a dozen requests in flight because the list happened to be long. So
+a list allows **four runs at once by default**. While that many are out, every
+control in it that would start another run goes read-only and says how many it
+is waiting on; the next press is possible again the moment one comes back.
 
 ```jsx
 <List parallelGuard={2}>      // stricter
 <List parallelGuard={Infinity}>  // lifted, without taking it out of the tree
 ```
 
-It counts runs, not values — which is the whole difference from `maxLengthGuard`
-next to it: that one says how many things the selection may HOLD, this one how
-many may be HAPPENING. A list can carry either, or both, and they refuse for
-unrelated reasons.
-
-Only a control that would start a run is held: a row with nothing to run, or a
-button that merely fires a command, never waits its turn.
+It counts runs, not values — the whole difference from `maxLengthGuard`, which
+says how many things the selection may HOLD, where this one says how many may be
+HAPPENING. A list can carry either, or both, and they refuse for unrelated
+reasons. Only a control that would start a run is held: a row with nothing to
+run, or a button that merely fires a command, never waits its turn.

package/docs/list_refresh.md

@@ -2,15 +2,15 @@
 
 When a write touches one item of a list, two questions decide what the user
 sees: **what goes back to the network**, and **what stays on screen meanwhile**.
-Getting either wrong turns "pause one row" into a full page reload.
-
-The same two questions decide what a list does when the user leaves it and
-comes back, which is the second half of this file.
+Getting either wrong turns "pause one row" into a full page reload. The same two
+questions decide what a list does when the user leaves it and comes back, which
+is the second half of this file.
 
 The short answer:
 
-- A write that returns the modified item fixes every list containing it, with
-  no request and no loading state at all.
+- A write that returns the modified item fixes every list read through an action
+  that contains it, with no request and no loading state at all — and, in a
+  `<List.Items>` over `GET_RANGE`, every row reading its item with `useById`.
 - `useAsyncData(action, { loading: true })` keeps returning the previous data
   while the action re-runs — the list is never taken away unless the component
   throws it away.
@@ -20,24 +20,17 @@ The short answer:
 ## `loading: true` returns the previous value
 
 During a re-run, `useAsyncData(action, { loading: true })` hands back the
-**previous** data with `loading` up — never `undefined`, which is the first
-load only, for a `GET_MANY` as for anything else — so the emptiness test is
-`data === undefined`, and a list is never blanked for a checkbox ticked on one
-of its rows. Read `loading` as "what you are displaying is from before", not
-"there is nothing to display". The four combinations of `data` and `loading`,
-and what each one draws, are in [data_states.md](./data_states.md).
+**previous** data with `loading` up. Read `loading` as "what you are displaying
+is from before", never as "there is nothing to display": the emptiness test is
+`data === undefined`
+([data_states.md](./data_states.md#data-and-loading-are-independent)), and a
+refresh that failed comes back beside the rows, not in place of them
+([data_states.md](./data_states.md#an-error-is-a-message-on-the-screen-not-the-screen)).
 
 `<List loading>` is the first-load answer, not the refresh one: it replaces the
 rows with skeletons. Pass it while stale rows exist and they disappear — same
 mistake as `loading ? null :`, one level down.
 
-A refresh that failed does not unmake the rows either. With `error: true` the
-failure comes back **beside** them, so the list stays and the failure is said
-over it — a strip above the rows, a retry, `dismissError()` to close the strip
-without asking anything again. Taking the rows away is `<ErrorBoundary>`'s job,
-and only when the screen genuinely cannot be drawn — see
-[data_states.md](./data_states.md#an-error-is-a-message-on-the-screen-not-the-screen).
-
 ## What updates without a request
 
 An action's `data` is a computation over the resource store, not a snapshot of
@@ -50,22 +43,25 @@ The condition is the whole hinge of the system:
 > **the write's callback must return the item, with its key** — `{ id, … }`.
 
 Partial props are fine (`{ id, paused: true }` merges into the stored item); the
-key is what cannot be missing. The corollary matters just as much: a callback
-that returns nothing — a `204`, or a `fetch` whose result is dropped — writes
-nothing to the store, and the change never reaches the screen. There, the only
-way back is a re-read.
+key is what cannot be missing. A callback that returns nothing — a `204`, or a
+`fetch` whose result is dropped — is refused with a `TypeError` naming the verb
+(`game.PATCH must return an object…`), and nothing reaches the store. For a
+`204`, return what was written yourself: `{ id, ...props }`.
 
 `DELETE` is symmetric: returning the id drops the item from the store, and every
 list containing it drops it too.
 
-## A paginated list stays on screen too
+A `<List.Items>` over `GET_RANGE` keeps the objects it was handed, so its rows
+follow a write only where they read their item from the store with `useById`
+([resource.md](./resource.md#get_range-feeding-a-list-that-loads-as-it-scrolls)).
 
-A `<List.Items>` reading through `GET_RANGE` draws places in a collection, not
-a list of ids, so nothing the store does can fix them: a row that changed tab,
-or one that was deleted, moves every row after it one rank up, and only the
-collection knows who fills the last place.
+## A paginated list stays on screen too
 
-It is told, and it re-reads by itself:
+A `<List.Items>` reading through `GET_RANGE` draws places in a collection, not a
+list of ids, so nothing the store does can fix them: a row that changed tab, or
+one that was deleted, moves every row after it one rank up, and only the
+collection knows who fills the last place. It is told, and it re-reads by
+itself:
 
 ```jsx
 <List.Items
@@ -88,11 +84,11 @@ it meanwhile:
 | answer received                 | the new rows         | —            |
 
 The rows, the scroll position and the row being read all stay; the slices
-outside the window are forgotten only once the answer is in, and asked for
-again if the user goes back to them. A re-read that fails leaves the rows from
-before on screen. While it is in flight, the list carries `navi-refreshing` and
-`renderItem` gets `{ refreshing }` — read it as "what you see is from before",
-never as "there is nothing to see".
+outside the window are forgotten only once the answer is in, and asked for again
+if the user goes back to them. A re-read that fails leaves the rows from before
+on screen. While it is in flight, the list carries `navi-refreshing` and
+`renderItem` gets `{ refreshing }` — "what you see is from before", never "there
+is nothing to see".
 
 An app that knows a row is on its way out (it is the one deleting it) says so
 itself: it is the one rendering the row, so it draws it loading, muted, or not
@@ -118,24 +114,19 @@ GAME.GET_RANGE { radar: "R-42" }    →  { count: 18,  byIndex: … }
 
 Ids, never rows: the rows are in the store already, shared and live, and a row
 dropped from the store simply stops resolving — a composition cannot hold a
-stale copy of anything.
-
-A run that finds a composition takes the `refreshing` line of the table above
-rather than the loading one: the rows are on screen while it asks again for the
+stale copy of anything. A run that finds a composition takes the `refreshing`
+line of the table above: the rows are on screen while it asks again for the
 window it draws. So the two lists an app cannot tell apart from the outside —
 one reading `GET_MANY`, one reading `GET_RANGE` — look the same on the way back:
 neither blanks, neither shows a first load. What they do behind that is not the
-same, and the next section is about exactly that.
-
-What a composition is about is the **values** its params hold, not the reader
-instance: `GET_RANGE.bindParams({ scope: "thread" })` called from two places
-reads and writes the same one (and gives back the same reader, memoized the way
-an action's `bindParams` is).
+same (next section).
 
-The rest follows the rules already stated: a verb in `rerunOn.GET_RANGE`, or
-`reader.invalidate()`, drops the compositions — they stand for an order that is
-gone — and `memoryBudget` (1000 ranks by default) trims the ranks far from any
-window, which are asked for again if the user goes back to them.
+A composition is about the **values** its params hold, not the reader instance:
+`GET_RANGE.bindParams({ scope: "thread" })` called from two places reads and
+writes the same one. A verb in `rerunOn.GET_RANGE`, or `reader.invalidate()`,
+drops the compositions — they stand for an order that is gone — and
+`memoryBudget` (1000 ranks by default) trims the ranks far from any window,
+which are asked for again if the user goes back to them.
 
 ### Who decides the re-read — and who does not
 
@@ -144,48 +135,36 @@ playing between the two pages: the **source** the list reads through is what
 answers, and it answers the same way whether the user arrived by a link, by
 `history.back()`, or under a route transition.
 
-| The list reads through          | Coming back to it                                                                                     |
-| ------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `routeAction` over `GET_MANY`   | **nothing goes out** — the action holds its response, and `.run()` on a `COMPLETED` action is a no-op |
-| `<List.Items>` over `GET_RANGE` | **one ask goes out** — the reader kept ranks, not rows, and revalidates the window it draws           |
-
-Both are deliberate, and they are not in tension: an action that kept its answer
-has the answer, while a composition is a claim about an order that any write
-elsewhere may have made false. What a `GET_MANY` list wants on the way back it
-has to say itself — `.rerun()` when the route becomes current again, or a verb
-in `rerunOn` if a write is what makes it stale.
-
-Nothing above changes when `defineRouteTransition` is written for the pair the
-list is walked through. A transition states a relation between two pages (see
-[route_transitions.md](./route_transitions.md)); it takes the document's
-rendering hold for the one frame the browser needs to photograph it, and gives
-it back. It never decides what the page arriving is allowed to ask for. Held by
-`tests/route_transition_list_revisit/`, which mounts the same app twice — with
-and without a relation on the pair — and walks the way back ten times on each,
-counting what goes out at every revisit.
-
-When a list stops refreshing after a transition was added, two things account
-for it, in this order:
-
-1. **The revisit did not happen.** A back taken before the page being opened was
-   ever on screen returns to a list that never left, and a page that never left
-   has nothing to come back from (see
-   [route_transitions.md](./route_transitions.md#waiting-for-a-navigation-the-address-is-not-the-page)).
-   This is what an automated walk does by default, and it is the answer far more
-   often than the next one.
-2. **The list is on the first row of the table.** A `GET_MANY` list never
-   refreshed on its own; what changed is whatever else in the app was doing the
-   re-read.
+| The list reads through          | Coming back to it                                                                                                                               |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `routeAction` over `GET_MANY`   | **nothing goes out** — the action holds its response, and `.run()` on a `COMPLETED` action is a no-op; only `.rerun()` goes back to the network |
+| `<List.Items>` over `GET_RANGE` | **one ask goes out** — the reader kept ranks, not rows, and revalidates the window it draws                                                     |
+
+Both are deliberate: an action that kept its answer has the answer, while a
+composition is a claim about an order that any write elsewhere may have made
+false. What a `GET_MANY` list wants on the way back it has to say itself —
+`.rerun()` when the route becomes current again, or a verb in `rerunOn` if a
+write is what makes it stale.
+
+A `defineRouteTransition` written for the pair changes none of this: a
+transition states a relation between two pages (see
+[route_transitions.md](./route_transitions.md)) and takes the document's
+rendering hold for the one frame the browser needs to photograph it; it never
+decides what the page arriving may ask for. A list that stops refreshing after a
+transition was added most often saw no revisit at all — a back taken before the
+page being opened was ever on screen returns to a list that never left
+([route_transitions.md](./route_transitions.md#waiting-for-a-navigation-the-address-is-not-the-page));
+otherwise it is a `GET_MANY` list, which never refreshed on its own.
 
 ### Watching what the run asks for
 
 A run that decides **not** to ask is invisible from the application's side: it
 sends nothing and changes no state, so the network is silent and
-`onRequestStateChange` — which reports what a request is doing — has no request
-to report. A run that declined and a run that was never mounted look identical.
-`debugScroll` is where that difference is visible; it carries the render window
-and the run's asking, which are one subject. It logs in navi's development build
-only.
+`onRequestStateChange` has no request to report — a run that declined and a run
+that was never mounted look identical. `debugScroll` is where that difference is
+visible, in navi's development build only. Record into an array rather than
+printing: the sink is called during rendering, and a `console.log` in the way
+can move a timing-sensitive symptom.
 
 ```jsx
 window.askLog = [];
@@ -194,7 +173,8 @@ window.askLog = [];
 </NaviDebug>;
 ```
 
-One line per pass of the run, whatever the outcome:
+One line per pass of the run, whatever the outcome — so no line for a revisit
+means the run never rendered:
 
 ```
 ask 0-49: sent (revalidating=true holdPending=false count=412)
@@ -211,26 +191,11 @@ ask 0-49: held on a row not reached yet (revalidating=true holdPending=true coun
 | `a request still covers this window` | what is in flight is still what the list would draw                                                     |
 | `this range was asked for already`   | asking again could only produce the same answer                                                         |
 
-The state that decides is on the line rather than left to be inferred:
-
-- **`revalidating`** — the run knows what it holds is from before. A revisit
-  showing `revalidating=false` never restored a composition, which is a
-  different problem from one showing `revalidating=true` and no `sent`.
-- **`holdPending`** — the list is held somewhere it has not reached.
-- **`count`** — how many rows the run stands for, `undefined` before its first
-  answer.
-
-**Record, do not print.** The sink is called during rendering: push into an
-array. Formatting an object in a console costs far more than what it measures,
-and a timing-sensitive symptom moves under one — a list that fails to refresh on
-the first revisit can start refreshing on the first two as soon as a
-`console.log` is in the way, which makes the log a report about the log.
-
-An absence in the trace is a fact too: no line for a revisit means the run never
-rendered, which is about the list being mounted, not about what it asked for.
-The usual cause is a revisit that never happened — a back taken before the page
-being opened was ever on screen, which returns to a list that never left (see
-[route_transitions.md](./route_transitions.md#waiting-for-a-navigation-the-address-is-not-the-page)).
+The state that decides is on the line: `revalidating` — the run knows what it
+holds is from before, so a revisit showing `revalidating=false` never restored a
+composition, a different problem from `revalidating=true` and no `sent`;
+`holdPending` — the list is held somewhere it has not reached; `count` — how
+many rows the run stands for, `undefined` before its first answer.
 
 ## `rerunOn`, verb by verb
 
@@ -270,7 +235,7 @@ updated item — not client-side refreshing.
 | a field of one item         | no — the write's response is enough                  |
 | membership of the list      | yes (`POST`) — the backend decides who belongs       |
 | the ORDER of the list       | yes — the store stores, it does not sort (see below) |
-| nothing came back (`204`)   | yes — there is nothing to put in the store           |
+| nothing came back (`204`)   | no — the callback returns `{ id, ...props }` itself  |
 | a place in a paginated list | yes — a `GET_RANGE` reads places, and places shift   |
 
 ## The store stores, it does not sort
@@ -286,17 +251,10 @@ comes back in the old order on the next visit. After a reorder, re-read the list
 explicitly:
 
 ```js
-await REORDER_ACTION.run({ … });
+await REORDER_ACTION({ … });
 GET_MANY_ACTION.rerun();
 ```
 
-## `.rerun()`, not `.run()`, to refresh
-
-`.run()` on an action that already `COMPLETED` does nothing: it is a request to
-have the data, and the data is there. Wiring a "check now" button to `.run()`
-therefore checks nothing, silently. Use `.rerun()`, which resets the action and
-runs it again.
-
 ## See also
 
 - [route_transitions.md](./route_transitions.md#waiting-for-a-navigation-the-address-is-not-the-page)

package/docs/mobile_touch.md

@@ -45,26 +45,43 @@ The two engines reach that moment differently:
   them from any point before about 9px keeps the whole touch for the page, and
   so does refusing the first one alone: native scrolling never starts, even
   when the later ones are left alone. If the one at about 9px goes unrefused,
-  Safari pans. It does not wait for the page's
-  answer to a report that jumps over that distance in one go: after a small
-  unrefused report, a report that jumps past 9px is already too late.
+  Safari pans. It does not wait for the page's answer to a report that jumps
+  over that distance in one go: after a small unrefused report, a report that
+  jumps past 9px is already too late.
 
 So **a gesture that shares a surface with the page's pan has to read its
 intent before about 8px**, and measure it as a distance (`Math.hypot`), not per
 axis: the browser measures its slop as a distance, and a per-axis threshold is
 up to 1.4 times later on a diagonal. Waiting for more evidence is not
 available, because whatever is read after the browser's moment is read about
-a pointer that has already been cancelled. The travel reads a finger's intent
-at 6px for exactly this reason (`DRAG_START_THRESHOLD_TOUCH` in
-`@jsenv/dom`'s `drag_to_travel.js`). Its bias toward the box's own axis only
-means something because it is read before the browser reads the same pixels
-evenly.
+a pointer that has already been cancelled. It is why a travel reads a finger at
+6px, leaning towards its own axis before the browser reads the same pixels
+evenly (see [drag_to_travel.md](./drag_to_travel.md#what-the-rules-are)).
 
 Whether a `touchmove` can be refused at all is settled even earlier, when the
-finger lands: a non-passive listener must already be on the touch's path (see
-`keepTouchRefusable`, and
-[drag_to_travel.md](./drag_to_travel.md#on-a-touchscreen-the-browser-takes-the-gesture-unless-it-is-refused)).
-Being refusable is decided at the touchstart; being refused, before 8px.
+finger lands: the non-passive listener that will refuse must already be on the
+touch's path. Registered at the `pointerdown`, it is handed events that are
+`cancelable: false`, and its `preventDefault` does nothing, silently. A refusal
+that only comes after a wait — a long press turning into a carry — also needs
+an explicit `touch-action` other than `auto` on the region (`pan-y` still lets
+the page scroll): left at `auto`, Chrome has taken the touch by the time the
+wait is over. Being refusable is decided at the touchstart; being refused,
+before 8px.
+
+The passive-by-default intervention covers `touchmove` listeners on `window`,
+`document` and `document.body`: one added there says `{ passive: false }`, while
+on any other element a plain listener — a framework's event prop included — is
+non-passive already (navi's travelling boxes render
+`onTouchMove={keepTouchRefusable}`, from @jsenv/dom). And a touch keeps being
+dispatched at the node it started on, even once that node has left the
+document, where nothing above it hears it, the window included: a gesture that
+may replace the DOM under the finger (a page that travels navigates) listens on
+that node too.
+
+Missed, the listener costs the middle of a gesture, not its start: the gesture
+takes the press, then the thumb's arc bends towards the axis `touch-action`
+leaves to the page, the browser starts its own scroll and cancels the pointer,
+and what the hand was carrying snaps back under a finger still down.
 
 ## touch-action stops at the first scroller
 
@@ -112,6 +129,10 @@ first ~8px.
 - **Safari** does not click at all once a `touchmove` has been refused, even
   after 6px. A touch that was never refused still clicks: an unrefused sideways
   movement over `pan-y` clicks even after 20px.
+- **Two taps** in the same place, 120ms apart, give two `pointerup`, ONE `click`
+  and no `dblclick` at all (measured on a phone): the browser keeps the double
+  tap for its own zoom. Whatever means "twice" under a finger counts presses —
+  see [interactions.md](./interactions.md#twice-whichever-hand-it-is).
 
 A gesture that reads its intent early therefore costs the click of a tap that
 shook more than its threshold. Safari drops that click on its own, and on
@@ -125,7 +146,7 @@ On Chrome for Android, the tap that follows a finger-driven drag does not fire
 its `click` when it comes quickly: `pointerdown` and `pointerup` arrive, the
 synthesized `click` (and the `mousedown`/`mouseup` compat events) does not. Wait
 about half a second and the same tap works. It is what makes a wheel feel
-broken — spin it, tap "Définir" at once, and the command never runs.
+broken: a wheel spun, then a button tapped at once, and the command never runs.
 
 It is the browser's, not ours: a bare `div` moved by hand under `pointermove`,
 with no framework, reproduces it. An un-prevented touch drag feeds Chromium's
@@ -141,57 +162,30 @@ active, from a non-passive listener. `touchmove` rather than `touchstart`: the
 move is the event whose default the drag actually owns, and preventing
 `touchstart` also suppresses the surface's own focus and synthesized events.
 
-```js
-const onTouchMove = (e) => {
-  if (drag) {
-    e.preventDefault();
-  }
-};
-viewport.addEventListener("touchmove", onTouchMove, { passive: false });
-```
-
-Two theories were tried first and disproven on the device, so they are not
-worth trying again: pointer capture on touch, and a momentum re-render moving
-the element under the tap.
+Two theories were disproven on the device, not worth trying again: pointer
+capture on touch, and a momentum re-render moving the element under the tap.
 
 Reference: `onTouchMove` in `src/control/wheel/wheel.jsx`; the reductions, one
 variable per row, in `src/control/demos/lab/` (`tap_after_drag_experiment.html`,
-`surface_css_matrix_experiment.html`, `preventdefault_matrix_experiment.html`);
-Chromium's `gesture_provider.cc` (`ignore_single_tap_`, reset on the next down)
-and `tap_suppression_controller.cc` (the tap that stops a fling, 180ms) for the
-two mechanisms that do NOT explain it.
+`surface_css_matrix_experiment.html`, `preventdefault_matrix_experiment.html`).
 
 ## A finger is captured to what it touched, inside shadow trees too
 
 A touch pointer is captured the moment it lands, by the browser, to the element
-it landed on — nobody calls `setPointerCapture`. A mouse and a pen are not.
-That capture is announced like any other, with a `gotpointercapture` just
-before the first pointer event that follows, and a finger resting still sends
-one soon: its contact changes, so `pointermove`s with unchanged coordinates
-come within the first 100ms or so. Nearly every touch press therefore sees a
-`gotpointercapture` it never asked for. Code that reads it as "another gesture
-took this press" gives up on almost every finger.
-
-Recognising that capture is where Chrome misleads: **it goes to the deepest
-element under the finger, shadow trees included.** On an `<input>` or a
-`<textarea>` that is the inner editor, inside the field's own shadow tree; in a
-web component, whatever its shadow root holds there. `hasPointerCapture` on
-what the page sees — the field, the host — answers `false` at `pointerdown`,
-after `gotpointercapture`, and for the whole press. Yet the `gotpointercapture`
-reaches the page retargeted to that same element. An open shadow root shows
-both halves: the host answers `false`, the element inside it `true`.
-
-So the browser's capture is recognised by where it lands, never asked for: on
-a touch press, a capture announced on the press's own target is the browser's,
-whenever it arrives. Compare both events from the same tree: each is
-retargeted to the shadow host from outside. A gesture that takes the press onto
-that same element cannot be told apart from it, so it has to say so another way.
-
-Measured in Chromium 153 through `Input.dispatchTouchEvent`. The capture does
-not depend on the slop, so the desktop path shows it; see
-[Verifying without a device](#verifying-without-a-device). The same `false` on
-a field shows on an Android phone (Chrome 153). Not measured in Safari.
-
+it landed on (a mouse and a pen are not), and a finger resting still announces
+it within about 100ms: nearly every touch press sees a `gotpointercapture` it
+never asked for. Code reading it as "another gesture took this press" gives up
+on almost every finger. Chrome gives that capture to **the deepest element under
+the finger, shadow trees included** — the inner editor of an `<input>`, whatever
+a web component's shadow root holds there: `hasPointerCapture` on the field or
+the host answers `false` for the whole press, while the `gotpointercapture`
+reaches the page retargeted to it. So the browser's capture is recognised by
+where it lands, never asked for: on a touch press, a capture announced on the
+press's own target (compared from the same tree) is the browser's, and a gesture
+taking the press onto that same element has to say so another way.
+
+Measured in Chromium 153 (`Input.dispatchTouchEvent`: the capture does not
+depend on the slop) and on an Android phone (Chrome 153); not in Safari.
 Reference: `implicitCaptureHolder` and `takePress` in `@jsenv/dom`'s
 `press_held.js`.
 
@@ -243,11 +237,11 @@ them exactly as on a phone:
   and a restarted `safaridriver`. The page's `localStorage` does not survive
   that, so whatever must be read is read before the swipe.
 
-What to synthesize is the hand's imperfection, as
-[drag_to_travel.md](./drag_to_travel.md#verifying-a-gesture) says: a slow start
-landing a report between 6 and 9px, steep first pixels, a report that jumps. What
-to read: the `touchmove`s with `cancelable` and `defaultPrevented`, the
-`pointercancel`, `scrollY`, and what the gesture itself says (for a travel,
+What to synthesize is the hand's imperfection — a gesture simulated as clean,
+evenly spaced points passes forever and proves nothing: a slow start landing a
+report between 6 and 9px, steep first pixels, a report that jumps. What to read:
+the `touchmove`s with `cancelable` and `defaultPrevented`, the `pointercancel`,
+`scrollY`, and what the gesture itself says (for a travel,
 `data-drag-travel-walking` on `:root` and the slide that ends up current).
 
 What neither path shows: the lift of a real finger (the last reports before