@jsenv/navi 0.29.523 → 0.30.1

package/docs/AI_INSTRUCTIONS.md

@@ -66,7 +66,7 @@ start when unsure which export solves a problem.
   `SlideContainer` read from the URL, what a layer drawn over the screen may say
   in its address. Before any routing code.
 - `route_transitions.md` — a transition states a relation between two pages;
-  `RouteTravel` or a transition, never both on one pair; fixed bars and
+  `RouteTravel` or a transition on one pair; fixed bars and
   `RouteTransitionArea`; the page being left stays mounted, hidden, until the
   movement is over; a test waits for the page, never for its address; what a
   transition costs. Before animating a navigation, and before believing a
@@ -77,8 +77,9 @@ start when unsure which export solves a problem.
   whole document, what cannot be pointed at while one plays. Before
   `document.startViewTransition`, and before putting a value on `:root` for a
   movement.
-- `drag_to_travel.md` — a pointer or a wheel pushing a screen aside, and who owns
-  a press several boxes want. Before putting anything that reads the pointer
+- `drag_to_travel.md` — a hand pushing a screen aside: what a row the browser
+  scrolls answers, what a box pushed aside reads, and who owns a press several
+  boxes want. Before putting anything that reads the pointer
   inside a box that travels.
 
 ### Data

package/docs/create_and_edit.md

@@ -410,30 +410,19 @@ right. **A page left out of `routes` does not travel**: one opens the create
 screen from the list, one does not slide there, so the list is absent and that
 move plays nothing — leaving a page out is how a movement is refused.
 
-A pair with a movement of its own gets a row of its own, on its own axis. The
-game and its edit screen are the same thing seen two ways, so they travel
-vertically inside the place the outer row holds for them — editing above
-(the column's order is the children's), coming down over the game, sent back up
-by saving:
+A pair with a movement of its own takes a route transition rather than a row. The
+game and its edit screen are the same thing seen two ways, so they turn over inside
+the place the outer row holds for them, with `defineRouteTransition`:
 
 ```jsx
-const GameArea = () => (
-  <RouteTravel axis="y">
-    <Route>
-      <Route route={EDIT_GAME_ROUTE} element={EditGamePage} />
-      <Route route={GAME_ROUTE} element={GamePage} />
-    </Route>
-  </RouteTravel>
-);
+defineRouteTransition(GAME_ROUTE, EDIT_GAME_ROUTE, "flip");
 
-// in the outer row: the same element on both branches
+// in the row: the same element on both branches
 <Route route={EDIT_GAME_ROUTE} element={GameArea} />
 <Route route={GAME_ROUTE} element={GameArea} />
 ```
 
-The outer row does not move for it — the edit url is not one of its pages — and
-the same element on both branches keeps the inner row mounted, with something
-to travel between.
+The row does not move for it: the edit url is not one of its pages.
 
 ## The same loop in a dialog
 

package/docs/dialog_shape.md

@@ -49,6 +49,13 @@ screen** for `layer="top"` — the visual viewport minus the app's bands (see
 [`safe_area.md`](./safe_area.md)) — and the positioned ancestor for
 `layer="local"`.
 
+A modal dialog covered by another modal dialog is not in use, so it does not
+follow the keyboard: it stays where it is, and the keyboard covers it as it
+covers anything else behind that sheet. Once back on top it answers the screen
+as it is: at once when the focus landed on a field, since the keyboard stays;
+once the keyboard has left otherwise, so it never jumps up and back down. What
+sits under a non-modal dialog is still usable, and keeps following the keyboard.
+
 ## One dialog, two shapes
 
 `dockedOnSmallTouchScreen` is the whole small-screen story in one prop: on a

package/docs/drag_to_travel.md

@@ -1,78 +1,93 @@
-# Travelling by drag, and who owns the gesture
+# Travelling: a hand, a screen, and who owns the gesture
 
-A travel is a pointer or a wheel pushing a whole screen aside to bring in the
-next one: slides inside a box (`SlideContainer`), pages that are URLs
-(`RouteTravel`), a docked `Dialog` or a `SidePanel` pushed back the way it came
-to close it, a row swiped aside with `interactions`. One module answers what
-such a gesture IS — `drag_to_travel.js` in @jsenv/dom — and all of them read
-it, so a hand never has to learn two sets of numbers.
+A travel is a hand pushing a whole screen aside to bring in the next one. There
+are two families, and they do not work the same way:
+
+- **A row of screens** (`SlideContainer`, `RouteTravel`) is a real scroller with
+  one snap point per screen. The browser reads the hand. See
+  [The browser scrolls the row](#the-browser-scrolls-the-row).
+- **A box pushed aside** (a docked `Dialog` or a `SidePanel` pushed back to close
+  it, a row swiped with `interactions`) has nothing to scroll to, so the press is
+  read by one module, `drag_to_travel.js` in @jsenv/dom. See
+  [A box pushed aside: the press](#a-box-pushed-aside-the-press).
 
 What an application has to know is who gets a press that lands inside such a
-box. It is decided at the press, from the DOM, before anything moves — so read
+box. It is decided before anything moves, so read
 [Who owns a gesture](#who-owns-a-gesture) before putting anything that reads
 the pointer inside a box that travels.
 
-- [What the rules are](#what-the-rules-are)
+- [The browser scrolls the row](#the-browser-scrolls-the-row)
+- [A box pushed aside: the press](#a-box-pushed-aside-the-press)
 - [Who owns a gesture](#who-owns-a-gesture)
   - [Boxes inside boxes](#boxes-inside-boxes)
   - [Something being carried inside a box](#something-being-carried-inside-a-box)
   - [A surface in the top layer](#a-surface-in-the-top-layer)
   - [A navi component that reads the pointer marks ITSELF](#a-navi-component-that-reads-the-pointer-marks-itself)
   - [What is contained, and what still leaks](#what-is-contained-and-what-still-leaks)
-- [The two consumers that travel between screens](#the-two-consumers-that-travel-between-screens)
-  - [One gesture that bar cannot follow](#one-gesture-that-bar-cannot-follow)
-
-## What the rules are
+- [The two rows](#the-two-rows)
+
+## The browser scrolls the row
+
+A touch pans on the compositor, a trackpad follows the fingers, a wheel is read
+for what it is. So a row answers a hand the way any scroll snap carousel on the
+web does, and these are its rules, not ours:
+
+- **A trackpad or a finger holds the screen.** Let go past half the box, or with
+  momentum, it goes; let go short of that with the hand at rest, it comes back.
+- **One notch of a wheel is one screen**, however small the notch. Only the
+  browser can tell a notch from a trackpad: the page cannot.
+- **A big swipe can cross more than one screen.** `scroll-snap-stop` stops the
+  momentum at the next screen, not a finger still pushing past it. With
+  `mount="near"`, a screen reached ahead of its neighbours is built on the way, so
+  it can show empty for a moment.
+- **A stroke stays on what it started on.** A vertical scroll cannot change
+  screen, whatever it leans towards on the way. The price is the mirror case: a
+  stroke that opens on a sideways crumb is the row's, and the vertical scroll it
+  turns into does nothing until the hand lifts.
+- **A mouse does not drag**, as it does not scroll anything else on the web.
+
+What stays ours:
+
+- **A travel asked for** (a tab, a key, a command, a state) plays in `duration`,
+  one box long whatever the distance, in `SlideContainer`. In `RouteTravel` it is
+  the browser's smooth scroll.
+- **A direction that is refused is the end of the row.** Whatever holds the user
+  where they are (a `<Slide required>` waiting for its answer, a `preventNavNext`)
+  takes what lies beyond off the row, so nothing can be scrolled to. There is no
+  screen walked to and then taken back.
+- **What a box cannot say to a scroller is said per axis.** `travelByDrag` is about
+  a finger, `travelByScroll` about a wheel or a trackpad: off on an axis, that hand
+  is handed on to what scrolls inside, then around.
+
+**`position: sticky` does not stick inside a `RouteTravel` row of two pages or more
+while the document scrolls.** A horizontal scroller cannot let the other axis
+through, so the row is what sticky sticks to, and the row never scrolls vertically.
+A page that scrolls by itself inside the row is not concerned.
+
+## A box pushed aside: the press
 
 - A press is not a gesture until it has wandered 10px with a mouse, 6px with a
-  finger or a pen, and the axis it leans on then is the axis it walks, for good:
-  a diagonal would ask for two travels at once when only one screen can arrive.
-  The reading leans towards the box's own axis — a thumb swiping sideways moves
-  along an arc, and its first pixels lean off-axis far more than the swipe does
-  — so the cross axis takes the press only when it clearly dominates. Where
-  something under the finger scrolls on that axis, the page included, the
-  reading is even, the way the browser's is: a scroll that wobbles stays a
-  scroll, and a swipe whose first pixels are steeper than 45° scrolls too. A
-  finger's 6px is a deadline rather than a feel: the browser commits a touch to
-  its own pan about 8px in, and whatever is read after that is read about a
-  pointer it has already cancelled (see
+  finger or a pen, and the axis it leans on then is the axis it walks, for good.
+  The reading leans towards the box's own axis: a thumb swiping sideways moves
+  along an arc, and its first pixels lean off-axis far more than the swipe does,
+  so the cross axis takes the press only when it clearly dominates. Where
+  something under the finger scrolls on that axis, the page included, the reading
+  is even, the way the browser's is: a scroll that wobbles stays a scroll, and a
+  swipe whose first pixels are steeper than 45° scrolls too. A finger's 6px is a
+  deadline rather than a feel: the browser commits a touch to its own pan about
+  8px in, and whatever is read after that is read about a pointer it has already
+  cancelled (see
   [mobile_touch.md](./mobile_touch.md#the-browser-decides-about-8px-in-and-does-not-wait)).
   Its price is the click of a tap that shook more than 6px.
-- **A page change is asked for a little later than the press is taken.** A
-  `RouteTravel` holds the press at the same 6px, but nothing is asked of the
-  router until the hand has pulled 10px further, 16px in all with a finger: a
-  navigation, a render and the requests of the page arriving are not worth a
-  hand that only shook. Turned around before that, it simply picks the other
-  neighbour. The picture sets off from where it stands rather than jumping those
-  pixels, and let go of before that, nothing has moved.
-- **Letting go asks where the hand is about to put things.** Where the picture
-  stands, plus half a second at the speed the fingertip has as it lifts, against
-  half the box. A flick lands far and goes. A hand thrown back lands short and
-  everything goes back, otherwise a screen caught in flight and thrown back
-  still arrives. A hand that slowed to a stop has no speed left, and the picture
-  answers alone. Speed counts from 25px of finger, a tap that slipped not being
-  a flick, and past 0.4 px/ms it answers on its own, or half a wide box would be
-  out of reach of any flick.
+- **Letting go asks where the hand is about to put things.** Where the box stands,
+  plus half a second at the speed the fingertip has as it lifts, against half the
+  box. A flick lands far and goes. A hand thrown back lands short and everything
+  goes back. A hand that slowed to a stop has no speed left, and the picture
+  answers alone. Speed counts from 25px of finger, a tap that slipped not being a
+  flick, and past 0.4 px/ms it answers on its own, or half a wide box would be out
+  of reach of any flick.
 - Pulling towards nothing follows the finger at a fraction of its distance and
   comes back: a wall one can lean on, never walk through.
-- **A direction that will be refused is one of those walls, and it must be a
-  wall from the first pixel.** Whatever holds the user where they are — a
-  `<Slide required>` waiting for its answer, a `preventNavNext` — is read where
-  the gesture is ARMED, not only when it is let go of. Read at the release
-  alone, the screen one may not reach is walked to, read on the way, and then
-  taken back: a wall that shows what is behind it and pushes you back reads as a
-  bug even when it is a rule. What a lock answers is therefore not "is there a
-  screen that way" but "may I go there".
-- **A hand that walks a whole box and keeps going is asking for the next one**,
-  and the gesture walks on into it without being let go of.
-- **A wheel push moves one screen**, the way an arrow key does — never a
-  distance. What keeps arriving after the fingers are gone is momentum and is
-  not counted: a second screen takes a second push, or one that insists.
-- **A press on a travel still moving is the next swipe first.** A step the way
-  it is going asks for the screen after, and the travel goes on there without
-  ever having stopped; only a step against it, or a finger saying nothing for
-  about 100ms, catches it where it stands. Let go before either — a tap — and
-  the travel was never touched.
 
 How to drive a gesture without a device, and why the obvious way hides the race
 that loses swipes on a phone, is
@@ -80,8 +95,10 @@ that loses swipes on a phone, is
 
 ## Who owns a gesture
 
-Five things can claim a pointer that landed on a travelling box, and all five
-are read at the press, before the box moves:
+A row of screens leaves this to the browser, which hands a touch to the innermost
+scroller that can take it. A box pushed aside reads it itself: five things can
+claim a pointer that landed on it, and all five are read at the press, before the
+box moves:
 
 1. **What says so itself.** What the browser already answers the pointer on — a
    field, a `contenteditable`, a `select`, a range; a dedicated drag handle
@@ -118,20 +135,17 @@ is not pushed back at all. A `SidePanel` is pushed from its whole surface.
 ### Boxes inside boxes
 
 A row of slides inside a page that walks between pages, a carousel inside a
-carousel, a `SlideContainer` inside a `RouteTravel`: they all get the same
-press, and the innermost is the one the hand is pointing at. So it takes the
-gesture on the axis it walks, and the boxes above it are left with whatever axis
-it does not — a row swiped sideways inside a column of screens keeps the
-sideways gesture, and the column still answers a finger going down. Nothing has
-to be declared for this: each box says which axes it travels in the DOM
-(`data-travel-by-drag`, `data-travel-by-wheel`), and that is what the boxes above
-read.
-
-Decided at the press, once and for all: from the first pixel the gesture belongs
-to whoever asked the browser for the pointer last, which is the outermost box.
-So an inner box sitting on its last slide does not hand the gesture over
-mid-drag: it leans on its wall, the way it does when it is alone. Travelling the
-box around it means starting the gesture outside it.
+carousel, a `SlideContainer` inside a `RouteTravel`: the innermost is the one the
+hand is pointing at. It takes the gesture on the axis it walks, and the boxes
+around it keep whatever axis it does not, so a row swiped sideways inside a column
+of screens keeps the sideways gesture, and the column still answers a finger going
+down.
+
+Decided when the stroke starts, once and for all. An inner row sitting on its last
+slide does not hand the gesture over: it leans on its wall, the way it does when
+it is alone. Travelling the box around it means starting the gesture outside it. A
+box pushed aside reads the axes of what is inside it in the DOM
+(`data-travel-by-drag`).
 
 When the boxes say ONE place between them — a row of titles in each slide of a
 column of levels, the address naming a title — they bind one state: see
@@ -199,68 +213,37 @@ than while a finger is down, because a browser decides what a gesture may do
 when the gesture begins; the bounce is refused only while a gesture runs, so a
 page that bounces the rest of the time goes on bouncing.
 
-What still leaks, only on Blink (Chrome, Edge), and only under a box that is not
-a scroll container — a `SlideContainer` (it cuts with `overflow: clip`), a
-`RouteTravel`, a swiped row: a scroller **nobody declared and no tag names** — a
-bare `<div style="overflow: auto">`, a widget from elsewhere. Its leftovers
+What still leaks, only on Blink (Chrome, Edge), and only under a box pushed aside,
+which is not a scroll container: a scroller **nobody declared and no tag names** —
+a bare `<div style="overflow: auto">`, a widget from elsewhere. Its leftovers
 reach the page. Two ways out, per case: give the scroller a `Box` with an
 `overflow` (it is then declared), or contain it by hand
 (`overscroll-behavior-x: contain` under a box travelling sideways). The general
 fix belongs to Blink.
 
-## The two consumers that travel between screens
-
-A popup pushed back towards its edge and a swiped row are travels too, the
-simple kind: one box, one direction, no neighbour to bring in. The two below
-carry screens.
-
-|                         | `SlideContainer`                   | `RouteTravel`                      |
-| ----------------------- | ---------------------------------- | ---------------------------------- |
-| what the screens are    | `<Slide>`s in one box, all mounted | routes — one mounted, ever         |
-| what says which is here | a `signal`, `current` / a command  | the URL                            |
-| what the finger moves   | a translated track                 | the pictures of a view transition  |
-| when the picture moves  | from the press becoming a gesture  | from 10px after that               |
-| letting go too early    | the track comes back               | the transition is played backwards |
-| what says the order     | the layout map                     | the `<Route>` children, in order   |
-| what one wheel push is  | `move(±1)`, as an arrow key        | one travel, as a tab pressed       |
-
-Both expose how far the travel has come, and the way to read it differs because
-what draws an indicator differs. `SlideContainer` writes
-`--slide-travel-progress` — where the picture stands against the current slide,
-in boxes: 0 on it, +1 a whole box before it, -1 one after — on its box, for
+A row of screens is a scroll container, and contains itself.
+
+## The two rows
+
+|                               | `SlideContainer`                  | `RouteTravel`                               |
+| ----------------------------- | --------------------------------- | ------------------------------------------- |
+| what the screens are          | `<Slide>`s in one box             | routes                                      |
+| what says which is here       | a `signal`, `current` / a command | the URL                                     |
+| what a screen not on it shows | itself, built or `mount="near"`   | itself once visited; before that, see below |
+| what says the order           | the layout map                    | the `<Route>` children, or `routes`         |
+| a travel asked for            | plays in `duration`, one box long | the browser's smooth scroll                 |
+
+A `RouteTravel` page not visited yet can only be built by the address moving, since
+a route's actions ask only while it matches. So the address moves once the hand has
+really pulled, 16px, and the page fills in under the finger. See
+[navigation.md](./navigation.md#tabs-that-travel-routetravel).
+
+Both tell what follows them how far the row has come. `SlideContainer` writes
+`--slide-travel-progress` (where the picture stands against the slide it counts
+from, in boxes: 0 on it, +1 a whole box before it, -1 one after) on its box, for
 anything drawn inside it, and on every element marked
-`data-slide-container-follows={id}` outside it (a tab bar above the box). It is
-declared with `@property`, so it interpolates. `RouteTravel` leaves it to the
-browser: give the indicator a `view-transition-name` of its own and it is
-animated from where it was to where it is, even from outside the box (see
-[view_transitions.md](./view_transitions.md#a-name-is-unique-per-document)).
-
-A travel is not a queue: a tab pressed while a page is arriving does not wait
-its turn, and does not start a second travel on top of the first either. The
-travel in flight is aimed there instead. Back where it set off from, it is
-undone — the same pictures, run backwards; further the same way, it costs
-nothing; the other way, the pictures start again from the beginning, and a page
-nearly arrived snaps back first.
-
-A hand that walks a `RouteTravel` page whole and keeps going gets the next page,
-but out of the far end there is a short gap: the page it was leaving is gone,
-the next travel needs pictures of its own (a navigation, a render, a snapshot),
-and over those frames nothing follows the finger before catching up with it.
-Walked back out of the start there is none — the pair in hand is already the
-right one. A `SlideContainer` has every slide mounted and hands over without a
-gap either way.
-
-### One gesture that bar cannot follow
-
-A `RouteTravel` travel that turns around mid-gesture, or is aimed further the
-same way while it plays — a tab pressed two pages along, the next swipe landing
-on a page still arriving — keeps its pages by pointing the router elsewhere
-under the same transition. But everything ELSE the transition carries was
-photographed when it began, on its way to a tab nobody is going to anymore, and
-the thing itself has already moved on in the live page: one would see two bars.
-
-So on those gestures the pictures of everything that is not the pages are
-dropped, and those things are left where they are, live: the bar jumps to the
-tab one is heading for instead of sliding to a tab one is not. A slide would be
-nicer, and it is not available — the browser measured both of its ends before
-the hand changed its mind, and neither can be asked for again.
+`data-slide-container-follows={id}` outside it, a tab bar above the box. It counts
+from the current slide (`data-slide-current`), or once a hand has carried the row
+past it from `data-slide-travel-base`, towards `data-slide-travel-toward`.
+`RouteTravel` needs nothing: a `<Nav currentIndicator>` draws its bar under the hand
+for any row it holds tabs for.

package/docs/dynamic_import.md

@@ -179,7 +179,7 @@ nothing to preload — the navigation itself asks.
 
 A route element still waiting is what the container rendered — its pending
 screen, or the fallback of the boundary it suspended into — so a route transition
-or a `RouteTravel` takes its picture of **that**, code and data alike. navi does
+takes its picture of **that**, code and data alike. navi does
 not hold a navigation for a chunk: the honest answer to "a chunk is a hundred
 milliseconds" is the prefetch above — the code is there before the press — and a
 skeleton in the page's own shape is what gets photographed when it is not.

package/docs/interactions.md

@@ -560,6 +560,12 @@ teardown, so a travelling container above it does not take the gesture (see
   has decided. One gesture cannot mean both. What they leave alone keeps its
   drag: an element inside marked `data-no-drag-travel` reads the pointer itself.
   An element declaring a swipe also gets `draggable={false}`.
+- **A popup is in front of the box it was written in, not part of it.** It stays
+  a DOM descendant of its trigger, so its events bubble through that box, but a
+  hold, a swipe, a counted tap or a `"keyboard:<shortcut>"` pressed in the popup
+  is not read by the box around it. A box inside the popup, or the popup itself,
+  answers as usual. A plain `onKeyDown` still hears the event: it is the
+  browser's, so it asks `event.target` itself if it should not.
 - **A popup can open while the finger is still down** — a menu under a waiting
   finger is the native gesture (see
   [popup_open.md](./popup_open.md#opening-while-the-finger-is-still-down), and

package/docs/mobile_touch.md

@@ -55,11 +55,11 @@ 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. It is why a travel reads a finger at
-6px, before the browser reads the same pixels evenly: leaning towards its own
+a pointer that has already been cancelled. It is why a box pushed aside reads a
+finger at 6px, before the browser reads the same pixels evenly: leaning towards its own
 axis where nothing scrolls on the other one, evenly where something does, and
 waiting for the browser's own pixels when that reading says the pan is the
-browser's (see [drag_to_travel.md](./drag_to_travel.md#what-the-rules-are)).
+browser's (see [drag_to_travel.md](./drag_to_travel.md#a-box-pushed-aside-the-press)).
 
 Whether a `touchmove` can be refused at all is settled even earlier, when the
 finger lands: the non-passive listener that will refuse must already be on the

package/docs/navigation.md

@@ -461,10 +461,11 @@ says once, for the whole row, where the bar that marks the current tab goes:
 </Nav>
 ```
 
-The bar glides from one tab to the next when the change between them plays as a
-view transition — a `RouteTravel` swipe, a route transition — because `<Nav>`
-names it for that movement (`currentIndicatorSlides`, on by default), and only
-for a movement between two tabs of its own row: during any other route movement
+A hand on a `RouteTravel` row carries the bar with it, for any row the `<Nav>` holds
+tabs for. It also glides from one tab to the next when the change between them plays
+as a route transition, because `<Nav>` names it for that movement
+(`currentIndicatorSlides`, on by default), and only for a movement between two tabs
+of its own row: during any other route movement
 the bar leaves or arrives with its row, a named element inside a page that moves
 standing still (see
 [view_transitions.md](./view_transitions.md#a-name-is-unique-per-document)).
@@ -527,9 +528,9 @@ by a button, it is a command carrying the fallback:
 
 ## Tabs that travel: `RouteTravel`
 
-`<RouteTravel>` wraps the `<Route>` tree of a row of tabs and makes every change
-between them a movement — a tab pressed, a key, the back button, and a thumb
-dragging the pages:
+`<RouteTravel>` wraps the `<Route>` tree of a row of tabs and makes it a row the
+browser scrolls, with one snap point per page: a tab pressed, the back button, and
+a hand pushing the pages:
 
 ```jsx
 <SectionNav />
@@ -542,41 +543,63 @@ dragging the pages:
 </RouteTravel>
 ```
 
-The router still mounts only the branch that matches: the page being left is the
-picture the browser keeps of it, and the page arriving mounts during the gesture,
-filling in under the finger as its own loading state. The order of the tabs —
-"one step that way", which no URL says — is the order the children are written;
-the row is on the **first** of its pages that matches, like a `<Route>`; a page
-left out of the row does not travel. A swipe **replaces** the current entry, as
-`<Link replace>` does for a tab pressed: two gestures towards the same neighbour
-must not write two different histories — and a row of tabs is the one place a
-replace moves the scroll
-([below](#a-row-of-tabs-where-a-replace-is-an-arrival)). Several `RouteTravel`
-boxes may live on one page, and only the one travelling is captured.
-
-**The URL says where the hand is heading, not where the reader is.** It changes
-once the hand has really pulled, and comes back if the page is let go of. So a
-counter, a title or a breadcrumb around the box reads
-`routeTravelSettledPageSignal` first, or it moves for a pull that goes nowhere:
+A page is built when its route first matches, since a route's actions only ask
+while it does, and stays once built: a hand brings back the page itself, with where
+it was scrolled to. The order of the tabs — "one step that way", which no URL says —
+is the order the children are written; the row is on the **first** of its pages
+that matches, like a `<Route>`; a page left out of the row does not travel. A swipe
+**replaces** the current entry, as `<Link replace>` does for a tab pressed: two
+gestures towards the same neighbour must not write two different histories — and a
+row of tabs is the one place a replace moves the scroll
+([below](#a-row-of-tabs-where-a-replace-is-an-arrival)).
+
+**A window over something longer** says its pages with `routes`, and its children
+are then one page, rendered once, whatever the address:
+
+```jsx
+<RouteTravel routes={ids.map((id) => ({ route: GAME_ROUTE, params: { id } }))}>
+  <GamePage />
+</RouteTravel>
+```
+
+That is the form for pages that are one route with other params, the same component
+and so only one of it, and for pages that are not children of the box. What a hand
+leaves behind is a picture of it, a clone, in the pane it stood in. `routes` may be
+given again around the page on screen as the reader moves through the list: it is
+taken once the row has come to rest, and nothing is seen moving for it. With fewer
+than two pages, the box is not a scroller at all.
+
+**The box has a height, or the document scrolls.** Pages may scroll themselves in a
+box the page gives a height to. If the document is what scrolls, it goes on doing
+so, and a page brought in stands where the reader is looking; what is lost is
+`position: sticky` inside the row (see
+[drag_to_travel.md](./drag_to_travel.md#the-browser-scrolls-the-row)).
+
+**The URL can say where the hand is heading, not where the reader is.** For a page
+that is not there yet, a page of a window or a tab never visited, it changes once
+the hand has really pulled, and comes back if the page is let go of. A tab already
+built waits for the landing. So a counter, a title or a breadcrumb around the box
+reads `routeTravelSettledPageSignal` first, or it moves for a pull that goes
+nowhere:
 
 ```jsx
 const settledPage = routeTravelSettledPageSignal.value;
 const shownId = settledPage ? settledPage.params.gameId : currentId;
 ```
 
-It holds the `{ route, params }` the travel set off from for as long as the
-pictures move, and is `null` when they stop, the URL being the truth again. A
-page walked whole under the hand has arrived. A tab pressed or a wheel pushed
-holds nothing, and `null` is all they ever read. One signal for the document, as
-there is one transition at a time: on a page with several boxes, `route` says
-which row is travelling.
+It holds the `{ route, params }` the hand set off from, and is `null` when the row
+has come to rest, the URL being the truth again. A tab pressed holds nothing, and
+`null` is all it ever reads. One signal for the document: on a page with several
+boxes, `route` says which row it is.
 
 `RouteTravel` is for pages that form a ROW the finger can push; pages related
 pair by pair are animated with `defineRouteTransition`, and a given pair by one
 of the two, never both (see
 [route_transitions.md](./route_transitions.md#route-transitions-and-routetravel--one-pair-one-system)).
 The gesture itself: [drag_to_travel.md](./drag_to_travel.md). Demos:
-`src/nav/demos/route_travel/route_travel.html`, `src/nav/demos/tabs/tabs.html`.
+`src/nav/demos/route_travel/route_travel.html`,
+`src/nav/demos/route_travel/route_travel_window.html`,
+`src/nav/demos/tabs/tabs.html`.
 
 ## Where a navigation lands: the scroll
 
@@ -773,7 +796,7 @@ The tabs of a `<RouteTravel>` navigate by replacing, and yet each one is another
 route, sharing one scrollport — the document — that the tab on screen makes
 tall: the moment the arriving tab is shorter, the browser clamps, and the
 reader's place is gone. The row is the only thing that knows this, so on every
-travel — a tab pressed, a thumb, a wheel, a travel put back — it gives the
+movement — a tab pressed, a hand, a page let go of and coming back — it gives the
 arriving tab the offset it was read at, once it is really rendered; opens a tab
 never read at its **top**, not wherever its neighbour happened to be; and never
 records the clamp, which, recorded against the arriving tab's url, would destroy

package/docs/popup_open.md

@@ -576,6 +576,13 @@ that must offer a way out that KEEPS what was chosen offers it with a close
 cross, or by letting the click outside close** — not by teaching Escape to say
 something else.
 
+**One Escape closes one popup: the one it was pressed in.** Each popup answers
+Escape itself, and a popup around it never hears the key, so backing out of a
+sheet in a dialog takes two presses. A `popover="manual"` element of your own has
+no Escape to answer with: in a `layer="local"` dialog, the key does nothing while
+the focus is in it. A modal dialog around it still closes, on the browser's own
+close request.
+
 ### What "cancel" actually undoes
 
 Cancelling is not itself an undo: it marks the close, and whoever holds a value

package/docs/route_transitions.md

@@ -315,14 +315,7 @@ answering: the click is caught at the document and handed to it when it fell
 inside its rectangle, and a navigation that is the exact way back of the movement
 playing turns that movement round. Only on furniture that stands still: a control
 travelling with the pages has a rectangle where it will be, not where it is seen
-(navi warns about one inside the area). `RouteTravel` is the opposite case — a
-finger is on the box — and leaves the bars live, so its pictures cover what a bar
-paints outside its box, except two things photographed on their own, which stand
-over the pages: the bar's `shadow`, and a child wearing
-`data-navi-fixed-bar-overhang` (a raised button, the notch around it). That child
-is deaf for the length of the travel, and the rest of the bar for its first frames,
-when a press falls to the document whatever it was aimed at;
-`pressableDuringRouteTransition` on a control keeps it answering in both cases.
+(navi warns about one inside the area).
 
 A **modal `Dialog` open on a page** is furniture of the same kind: it travels with
 its page, or holds if both states have it. One the navigation itself opens or
@@ -461,17 +454,14 @@ once in the console, naming both routes.
 
 ## Route transitions and `RouteTravel` — one pair, one system
 
-- **`RouteTravel`** is a ROW: a total order of tabs, plus the drag gesture that
-  walks it. Use it when the pages are genuinely a row the finger should push.
+- **`RouteTravel`** is a ROW: a total order of pages the browser scrolls. Use it
+  when the pages are genuinely a row the finger should push.
 - **`defineRouteTransition`** declares individual relations, with no gesture and
   no order beyond each pair.
 
-A given PAIR of routes must be animated by one of the two, never both: a travel's
-pictures can be under a finger, and a transition starting on top would skip them
-mid-slide — and a page one can drag has promised a translation, which a
-cross-fade would break. A travel in flight wins and the route transition is
-skipped with a console warning: the sign of a misconfiguration to fix, not a
-mechanism to rely on.
+A given PAIR of routes takes one of the two: a page one can push sideways has
+promised a translation, which a cross-fade would break. What a hand does on the row
+asks for no movement, and a tab pressed goes the way its `<Link>` says.
 
 The two DO live together in one app, on different pairs, including a
 `<RouteTravel>` nested inside a `<RouteTransitionArea>` — a row of sections the

package/docs/scroll.md

@@ -387,7 +387,9 @@ other flush, instead of each arriving already inset.
 
 Pass `travelByKeyboard={false}` when the arrow keys belong to the content (a list
 one walks through, a picker whose slides are steps): otherwise the right arrow
-changes screen mid-reading.
+changes screen mid-reading. A popup opened from a slide does not need it: a key
+pressed in the popup never walks the slides behind it (see
+[interactions.md](./interactions.md#things-worth-knowing-before-guessing)).
 
 Reference: `src/layout/slide_container.jsx`, and the "One slide much taller
 than the others" case in `src/layout/demos/8_slide_container_demo.html`.