@qxuken/kui 0.0.0-stage → 0.1.0-alpha.35

package/docs/adr/0035-a-rounded-background-is-joined-by-meeting.md

@@ -0,0 +1,134 @@
+---
+status: accepted
+date: 2026-09-27
+---
+
+# A rounded background is joined by meeting
+
+> **Accepted and built 2026-09-27**, the day it was proposed (backlog
+> F101). Raised by kawoosh's rounded selection. The editor draws a
+> selection as a translucent `bg` on the spans of each row it covers,
+> and wanted it drawn as one rounded outline, the way an editor's
+> selection usually is. Its first cut was a `fragment` under each row's
+> text, told its own extent and its neighbours' by the app (the reason
+> for a6092cc's square fragment and snapped fragment quad). That cut
+> could not reach a markdown paragraph. A paragraph is one text whose
+> lines wrap where layout breaks them, and a row of the view is not a
+> line of the paragraph, so the app did not know the lines to draw
+> under. And it was a frame behind, since the extents came from the last
+> frame's layout.
+
+## Context
+
+- **What a span's background is.** One square quad per line a run of
+  spans of one background covers (`build_decorations`, one rect per run
+  since dfc635b), each edge on a whole pixel from where layout put the
+  text (`on_pixels`). Two rows' backgrounds meet on one pixel line with
+  nothing drawn twice. Only the corners were left to do.
+- **What a rounded outline needs at a corner.** Where a line reaches
+  past the line above, its corner is convex. Where it falls short, the
+  corner is concave: a fillet past its end, filled in the line's own
+  colour. So a line's corners depend on the lines above and below it.
+  Those can be in the same text (a wrap), in another text (an editor's
+  next row), or in another node beside it (the cell an editor draws for
+  a line's newline).
+- **When the lines are known.** A text's quads are emitted in its
+  node's turn of `emit_frame`, in paint order, and at that point the
+  node after it has not been laid out into quads. Every text's lines are
+  known only once the frame's quads are all emitted, and that is still
+  before the frame leaves the core. So a pass there sees every line,
+  from the layout of the frame it draws.
+- **What already draws a shape no quad kind has.** The polygon (ADR
+  0025, decision 6) is a `fragment` quad painted by a WGSL source the
+  core registers itself. Its params are the shape, and every backend
+  that draws fragments draws it with nothing new.
+
+## Decisions
+
+1. **A span's background takes a radius, and nothing else is new on
+   the surface.** `Span::bg_radius(r)` in Rust, `bgRadius` on a
+   `<span>` in JSX, `bg_radius` in a Lua span table and on `KuiSpan` in
+   C, in logical px. At 0, the default, the background is the square
+   one it always was, byte for byte.
+2. **Pieces are joined by meeting, not by a name.** Two rounded
+   backgrounds belong to one shape when they have the same colour and
+   radius and one's edge touches the other's exactly: on the line above
+   or below, overlapping it sideways, or end to end on the same line. It
+   does not matter which node drew either. Nothing groups them, so
+   there is no id to declare, keep stable or clear, and two that touch
+   are one. Meeting is exact because the pieces are on whole pixels
+   already. Pieces that meet end to end on a line are made one extent
+   first. That extent is what the lines above and below are told, and
+   no corner is drawn where the pieces meet.
+3. **The join is a pass after emission.** A rounded background is
+   emitted square, like every background, and noted (`text::JoinBg`:
+   its quad, radius, the clip its text was given, and its text's own
+   box when that box clips, as a no-wrap line's does). At the end of
+   `emit_frame`, `join::shape` finds each piece's neighbour above and
+   below, the one overlapping it most, and rewrites its quad in place.
+   Paint order and the quad count are unchanged, and no backend,
+   adapter or wire learns a new kind. The shape uses the layout
+   of the frame it is drawn in, so it is never a frame behind.
+4. **Each piece is drawn by a stock fragment, `fragment::JOIN`.** The
+   core registers it as it registers the polygon's. A piece's quad is as
+   tall as its line and as wide as its extent plus the fillets its
+   neighbours ask for. Its params are its own extent, the neighbours'
+   extents, the radius and which neighbours there are, in physical px
+   from the quad's left. A corner is convex where the piece reaches past
+   its neighbour, a fillet where the neighbour reaches past it, square
+   where the two end together, and round where nothing meets it. At a
+   join the radius is at most half the step, and both pieces work it out
+   from the same two ends, so the convex half above and the fillet below
+   meet. The fill is the quad's colour. Near the ends and arcs it is
+   sampled sixteen times a pixel, and elsewhere it is solid.
+5. **A piece is clipped as its text's parent is.** A fillet past the
+   end of a short no-wrap line lies outside that text's own box, beside
+   it, so the piece takes the clip the text was given, not its own box.
+   A piece is still no wider than its text's own box shows. An
+   ancestor's clip, such as a scrolled pane, cuts the shape square where
+   it cuts, as it cuts everything.
+
+## Considered options
+
+- **The app draws it (kawoosh's first cut).** A `fragment` a row, the
+  extents from the last frame's layout. A frame behind on every edit
+  and scroll, and blind to a wrapped paragraph's lines, which only
+  layout knows. The square fragment and its snap (a6092cc) stay useful
+  for other stacks. For a selection over text, this ADR replaces that
+  cut.
+- **A named group** (`bgGroup="sel"`). It would let two selections of
+  one colour that touch stay apart. It also needs an id per selection,
+  stable across frames, in four bindings. The pass would still have to
+  find which pieces of a group are neighbours, and only geometry
+  answers that. An editor's selections that touch are one selection.
+  Kept in reserve, as an optional key on the same pass, if an app ever
+  needs two touching shapes of one colour kept apart.
+- **A new quad kind for rounded runs.** Every backend, the C header's
+  `KUI_QUAD_*` and the Node decoder would learn it. The fragment path
+  already carries sixteen params and a registered source, and the
+  polygon showed that path is enough.
+- **Joining in layout.** Layout sizes boxes and does not know a text's
+  line rects in physical px, which is what the join compares. That
+  knowledge would move into layout for a paint effect.
+
+## Consequences
+
+- The first paint that reads across nodes. The pass costs a scan of
+  the frame's rounded pieces against each other. That is the pieces on
+  screen, a few dozen for a selection, and nothing when no span has a
+  radius.
+- A rounded background is a `KUI_QUAD_FRAGMENT` on the wire, and its
+  `color` carries the fill with its alpha, not only the group opacity
+  as a node's fragment quad does. A host that draws fragments itself
+  gets the source from `kui_fragment_source`, as for the polygon. A host
+  that draws no fragments draws no rounded background, where it drew a
+  square one.
+- Two touching selections in one colour and radius are one shape, by
+  design (decision 2).
+- The C `KuiSpan` gains `bg_radius` under the unreleased ABI 20, and the
+  Node frame goes to v17, one slot a span.
+- Pinned by `tests/joined_backgrounds.rs` in kui-core (the pieces and
+  their params across texts, a wrap, colours and radii that do not
+  join, pieces meeting end to end on a line) and in kui-wgpu (the shape
+  composited through `JOIN`'s mirror, `tests/wgsl::join_alpha`), and by
+  the corpus's `joined-backgrounds` scene in four adapters.

package/docs/adr/0036-an-event-handler-gets-its-window.md

@@ -0,0 +1,142 @@
+---
+status: accepted
+date: 2026-09-27
+---
+
+# An event handler gets the window its event came from
+
+> **Accepted and built 2026-09-27**, the day it was proposed (backlog
+> DX9, from the DX sweep of kawoosh's views). The user chose the name
+> `on_event_with`. What the building added: a window that closed after
+> its event was made lends the main window's core, not none, so no
+> event is dropped. The clipboard example moved its copy, paste and
+> selection answer into the handler and lost three model fields. Two
+> things were not built as planned. The runner has no two-window test,
+> since a pane needs a real window; `testing::Drive` pins the handler's
+> core, and `window_core` is the one lookup. The debug assertion against
+> `frame()` in a handler was not added, and the trait's doc says it
+> instead.
+
+A Rust app hears its events in `App::on_event(&mut self, ev: UiEvent)`
+and has nothing else in hand. Everything it wants to *do* about an event
+beyond changing its model — write the clipboard, ask for a paste, move
+focus, reveal a row, scroll, ask for a frame, open a menu — is a call on
+the window's `Core`, and the only place a Rust app reaches a `Core` is
+`view`, through `Ui`. So kawoosh parks each of those in its model for
+the next `view` to carry out:
+
+- `clip_out`, the text to copy, because "`on_event` has no `Ui`"
+  (`kawoosh/src/app.rs:191`);
+- `reclaim_focus`, set by ten handlers (`app.rs:224`; DX10's `keepFocus`
+  removed most of the need);
+- the devtools tab and alignment requests (`app.rs:137`, `:253`).
+
+Each is a field that is not state, a branch in `view` that is not
+drawing, and a frame of delay between the event and its effect. ADR 0008
+(decision 6) and the closed C18 and C33 each met this and wrote around
+it. None of them filed it.
+
+## Context
+
+- **Node already has it.** `update(model, msg, event, surface)` gets the
+  `Ctx` or `KuiWindow` the loop runs on as its fourth argument since D4.
+  `surface.setClipboard(…)` from `update` is the Node spelling of what
+  kawoosh parks. ADR 0013 kept it that way on purpose: kui's effects
+  are calls on the surface, and only the app's own effects are returned
+  as data.
+- **C already has it.** A C host drives its core and polls its events
+  itself, so its handler holds the `KuiCtx`.
+- **Lua is a guest (ADR 0014).** A script's `on_event(ev)` returns
+  replies for its host to act on, and its `env` is a reading of one
+  `view`. That is the design, not a gap: what a script wants done
+  outside its own tree, it asks its host for (kawoosh's `kawoosh.copy`).
+- **The runner can hand one over.** `Shell::route_events` calls
+  `app.on_event(ev)` with `panes` (each window's `Core`) and `app` as
+  separate fields of `Shell`, so it can lend the handler the pane's core
+  while it runs. `ev.window` names the pane. A pumped runner's
+  `route_events(events, to_app)` and `testing::Drive` route the same way.
+- **The core's verbs already work between frames.** `set_clipboard` and
+  `request_paste` queue menu actions the runner drains after routing.
+  `reveal`, `focus_region` and the DX15 labels resolve when the next
+  frame finishes. `set_scroll`, `set_key_focus` and `request_frame` ask
+  for a frame. The verb table (`schema::DOORS`) already lists the
+  between-frames doors a host has, and it is the same list Node's
+  surface is checked against.
+
+## Decisions
+
+1. **`App` gains a handler that takes the window's core, and the old
+   one stays.**
+
+   ```rust
+   fn on_event_with(&mut self, ev: UiEvent, core: &mut Core) {
+       self.on_event(ev)
+   }
+   ```
+
+   The runner calls `on_event_with`. An app that overrides only
+   `on_event` behaves as it does today, so nothing breaks. The name is
+   open: `on_event_with` says what changed, and `update` would match
+   Node's word, but `update` in Rust usually means the model's step.
+
+2. **The surface is the `Core`, not a new context type.** It is the core
+   of the window `ev.window` names: the pane's, or the main window's for
+   an event a host made itself. It is `&mut Core` because the core's
+   between-frames doors already are the curated list. `DOORS` pins them
+   against Node's surface and C's header. A `EventCx` with a chosen
+   subset would be a fourth list to keep in step, and it would drift.
+
+3. **What the handler does lands where the verb says.** A clipboard write
+   goes out with the batch the runner drains after routing. A focus move
+   or a reveal is seen by the next frame, which the verb asks for. The
+   handler adds no ordering of its own.
+
+4. **Every driver passes it.** The winit runner, the pumped runner's
+   `route_events` (its `to_app` becomes `FnMut(&mut A, UiEvent, &mut
+   Core)`, a break for the few hosts that call it), and
+   `testing::Drive`. An event raised while a frame is being built, such
+   as a slot's reply, is routed after the frame like every other, so the
+   core is never lent while `Ui` holds it.
+
+5. **Lua and C are unchanged.** C already holds its context. A Lua
+   script stays a guest and asks through replies (ADR 0014). This is
+   Rust's door catching up with Node's, so no verb is added to the table.
+
+## Considered options
+
+- **Change `on_event`'s signature.** One method, the obvious spelling,
+  and a break for every Rust app on kui (kawoosh has one, the examples
+  thirty-odd). The default method in decision 1 gets the same result
+  without the break. Kept as the thing to do once it has shipped a
+  release, if the old method is to go.
+- **An `EventCx` of chosen verbs** (the backlog's first shape). Easier
+  to document and to keep an app from calling `frame()` from a handler.
+  But it is a second list of the core's verbs, beside the one `DOORS`
+  pins, in Rust only. A verb added to the core would need adding here
+  too or be missing only in Rust handlers. What it would buy — a handler
+  that cannot call `frame()` and build a frame the runner did not ask
+  for — is a rule the core's docs already state for any host holding a
+  `Core` between frames, and a debug assertion can hold it here.
+- **Effects as data** (ADR 0013's shape for Rust). Return
+  `Vec<Effect>` for the runner to apply. kui's effects are core verbs,
+  and ADR 0013 kept those as calls. Only the app's own effects are data.
+  A Rust app's own effects are its own code.
+- **Leave it**, since kawoosh's workaround works. The cost is not
+  kawoosh's three fields but that every Rust app meets the same wall at
+  its first clipboard shortcut, and the Node app next to it does not.
+
+## Consequences
+
+- A Rust handler copies, pastes, focuses, reveals and scrolls in answer
+  to the event, as a Node `update` does. The model fields and `view`
+  branches that parked those go. kawoosh's `clip_out`, the devtools
+  requests and what `reclaim_focus` has left are the first to go.
+- `route_events`' closure gains the core: a break for pumped hosts,
+  listed under What breaks. `testing::Drive` routes the same way, so a
+  test sees what the window does.
+- Nothing in the core, the IR, the schema, the C ABI, Lua or Node
+  changes.
+- Built with a runner test that a handler's `set_clipboard` reaches the
+  drained actions of the same turn and a `reveal` the next frame, and a
+  `Drive` test that the handler's core is the window its event came
+  from when two windows are open.

package/docs/adr/0037-a-family-is-named.md

@@ -0,0 +1,134 @@
+---
+status: accepted
+date: 2026-09-27
+---
+
+# A family is named where the text declares it
+
+> **Accepted and built 2026-09-27**, the day it was proposed (backlog
+> DX17, from the DX sweep of kawoosh's views). The user chose frame v18
+> for decision 4. What the building settled: the parser resolves the
+> name. `NameRefs::family`, over a token lookup that now carries the
+> session, registers it through `Session::register_family`, the body
+> `add_system_font` always had, moved where a parse holding the core's
+> lookup can reach it. So Lua and Node resolve it in the one step they
+> already resolve a `$token` in. A miss is remembered beside the token
+> misses and raised by the same code. The schema gained `Kind::Family`
+> and `Parsed::Family`. C keeps the index and the handle door (decision
+> 5), and its parity sample is the stock family at index 1. `font` and
+> `family` write the same field, so the last one declared wins, and the
+> row's doc says so rather than "the handle wins".
+
+`family` takes `sans`, `serif` or `mono`. Any other face is drawn with a
+handle: the host registers the family by name (`Core::add_system_font`,
+`addSystemFont`, `kui_font_add_system`) and hands the `FontId` down, and
+the text names it as `font`. A Lua view cannot register anything (ADR
+0014: registering is the host's), so a script that shows an installed
+face needs its host to register it and pass it in. kawoosh built that
+door, `kawoosh.fonts.face(NAME)`. Its first cut registered a family
+when a card first asked for it, at the next frame, so every card the
+fonts pane scrolled to drew one frame in kui's mono and then in its own
+face. The fix it shipped registers all 613 installed families at once,
+10 ms once in a debug build (`kawoosh/src/fonts.rs:7-12`,
+`docs/design/fonts.md:48-60`).
+
+## Context
+
+- **Registering a family by name loads nothing.** The font database
+  scans every installed face's metadata when it starts, which is how
+  `system_fonts` (F97) lists them without opening a file. So
+  `add_system_font` is a query against that scan and an idempotent
+  registry entry. The face's bytes are memory-mapped and shaped only
+  when a text first uses it, as for any face. Resolving a name in the
+  frame that declares it costs a lookup. The frame of mono in kawoosh
+  came from its host deferring the registration a frame, not from kui.
+  (Since DX24 the session's first registration of any font also maps
+  the installed files once, ~30 ms on a Mac, so the first frame to name
+  a family pays that; noted by the alpha.22 regression pass.)
+- **`TextStyle` is `Copy`,** and views rely on that everywhere (a
+  closure capturing a style, `style` passed by value). A name cannot
+  live in it. A handle can, which is why `FontFamily::Custom(FontId)`
+  exists.
+- **Every binding lowers a style where the core is at hand.** Lua's
+  parser runs inside `view` with the `Ui`. Node's frame is lowered by
+  the addon (`binary.rs`), with the window's `Core`. C builds a
+  `KuiTextStyle` itself and has `kui_font_add_system`. Rust has the
+  `Ui`.
+- **The weights follow a family, not a handle.** RG59 reweighs text
+  already shaped when a face of its family is loaded, and F100
+  synthesizes bold for a family with none. Both key on the family. A
+  named family resolves to the handle `add_system_font` returns, so
+  both keep working.
+
+## Decisions
+
+1. **`family` takes an installed family's name.** `family = "Berkeley
+   Mono"` in Lua, `family="Berkeley Mono"` in JSX. The stock names
+   `sans`, `serif` and `mono`, lowercase, stay the stock families. Any
+   other string is a family name, matched as `add_system_font` matches
+   it: installed, or loaded with `load_fonts_dir` / `load_font_file`.
+2. **The name is resolved where the style is lowered, to the handle.**
+   The binding's lowering calls `Core::add_system_font(name)` and sets
+   `FontFamily::Custom(id)`, so the text shapes in its face in the frame
+   that declares it. `TextStyle` stays `Copy`, and nothing after
+   lowering knows a name was involved. The registry's answer is
+   idempotent. A name lowered every frame costs a lookup, and a
+   name→handle map in the session makes it constant if a profile asks.
+3. **A name nothing matches is a warning, and sans.** `unknown-family`,
+   keyed by the name, so a typo in a view drawn every frame is one line.
+   The text shapes as sans, as a stale handle does today.
+4. **Node carries the name on the wire.** The frame's `family` slot is
+   an index into `schema::FAMILIES`. A name needs the string table the
+   frame already has for text. So `family` becomes an index for the
+   stock three and a string for anything else, and the frame is v18.
+   The encoder and addon ship together, so this breaks only a stale
+   prebuilt addon, which refuses the stream by its version. The other
+   route is below, with why it is second.
+5. **Rust and C gain nothing new but a pass-through.** Both already hold
+   the door. `Ui::system_font(name) -> Option<FontId>` is added so a
+   Rust view needs no `core()` to reach it. C keeps
+   `kui_font_add_system` and `KuiTextStyle.font`.
+6. **The prop's type says it.** The schema row's kind becomes a family
+   kind, the three stock names or a string. Lua's meta types it
+   `"sans"|"serif"|"mono"|string`, and TS `'sans' | 'serif' | 'mono' |
+   (string & {})`, so an editor still offers the three.
+
+## Considered options
+
+- **Leave it to the host** (today). It works for Rust, C and Node, which
+  can call the door. For Lua it means every host that shows a face
+  builds kawoosh's `fonts.face` and learns about its flicker.
+- **A Lua `env.add_system_font` door.** It would let a script register.
+  But registering is the host's (ADR 0014), and a handle is a thing to
+  keep and pass around. A family by name has nothing to own or free,
+  like `family = "mono"`, so it can be a declaration, not a verb.
+- **Node resolves in JS**, with `ctx.addSystemFont(name)` from the
+  encoder, cached per name, emitting the `font` handle the wire already
+  has. No frame version, but the encoder would need a context. Today
+  there is one encoder per module, built from `protocol()` alone
+  (`index.js:56`) and shared by every window and every test. A string on
+  the wire keeps it that way.
+- **Load asynchronously and swap** (CSS's `font-display: swap`): draw a
+  fallback, register off the frame, reshape when ready. It answers a
+  cost that is not there (decision 2's context). The swap is the flicker
+  kawoosh removed.
+- **A root `fonts = { … }` preload.** A second place to name a family,
+  for the same lookup the prop makes.
+
+## Consequences
+
+- A Lua view draws an installed face by naming it. kawoosh's
+  `kawoosh.fonts.face` and its 613-family registration go, and the fonts
+  pane's cards say `family = name`.
+- The Node frame is v18: one slot's encoding, under What breaks.
+  `schema::FAMILIES` and C's `KUI_FONT_*` are unchanged.
+- One new warning, `unknown-family`, in `diag::WARNINGS`, the TS union
+  and the Lua docs.
+- A family's handles and weights come from one registry. A family named
+  in a view and one registered by the host get the same handle,
+  pinned by a test.
+- Built with a core test that a named family shapes in its face in the
+  frame that names it (no frame of sans), the warning for a name
+  nothing matches, a Lua and a Node scene naming a family the corpus
+  loads from its fixture font, and the reweigh (RG59) still following a
+  named family's new face.

package/docs/adr/0038-a-scroll-gesture-latches-its-target.md

@@ -0,0 +1,188 @@
+---
+status: accepted
+date: 2026-09-28
+---
+
+# A scroll gesture latches its target
+
+> **Accepted and built 2026-09-28**, the day it was proposed (backlog
+> F107). Raised by kawoosh's todo of that day, three items about where
+> the wheel goes. A swipe that moved the pane strip carried a terminal
+> under the pointer, and the terminal took the rest of the swipe, so
+> the strip stopped hard at every terminal it met. A new swipe over a
+> list already at its end moved nothing, where the scroller around it
+> could have moved. And a swipe over a scroller did not always go the
+> scroller's way.
+>
+> **Amended by the alpha.22 regression pass (2026-09-28):** the pick
+> walks the scroller's ancestors in the tree, not the regions painted
+> under the pointer (decision 3), and reads what it needs off the region
+> the last finished frame drew rather than off the tree, so a wheel
+> event that arrives during a build routes by that frame.
+>
+> **Amended 2026-10-02 (backlog F117, from kawoosh's sticky-swipe
+> report):** a finger put down begins a gesture, pause or none
+> (decision 2). A swipe started while the last one still glided was the
+> glide's gesture, its target and its axis, until a pause came.
+>
+> **Amended 2026-10-02 (backlog F118, from the same report):** a wheel
+> handler that is also a scroll container on an axis is answered there
+> by its room (decision 3), so a code view or a table at its sideways
+> edge passes a swipe that way to the strip around it.
+
+## Context
+
+- **Where a delta went.** `InputEvent::Scroll` walked the scroll
+  regions under the pointer, innermost by paint order first. Each
+  scroll container took the axes it scrolls, and the rest went on
+  (DX13, so a `scrollY` list hands `x` to the `scrollX` strip around
+  it). An `on_scroll` node took whatever was left and stopped the walk.
+  Every delta walked afresh, from wherever the pointer was at that
+  moment.
+- **What moves under a still pointer.** A two-finger swipe does not
+  move the pointer. The strip scrolls under it, so a swipe that began
+  over a list ends over a terminal. kawoosh's terminal is an
+  `on_scroll` node that takes every delta for its history, so the
+  moment it arrived under the pointer it took the swipe.
+- **What an `on_scroll` node cannot say.** The core keeps no offset for
+  it and cannot ask whether it has anywhere to go. A container it can
+  ask, from the last layout's geometry.
+- **Where gestures begin.** The core is clock-free, as it is for
+  clicks. The native runner already has a clock and already tells one
+  swipe from the next: F104's axis lock ends a swipe after a 200 ms
+  pause. winit's `TouchPhase` is not usable for this alone. It names a
+  momentum run's start as it names a finger's (F117 tells them apart by
+  order, decision 2).
+- **What browsers do.** A wheel or trackpad gesture latches to the
+  scroller it started on and keeps it until the gesture ends
+  (*latching*). The scroller is picked at the start as the innermost
+  one under the pointer that can scroll the way the gesture goes, so a
+  scroller at its limit passes the gesture to its ancestor
+  (*chaining*). A gesture that reaches a limit partway stops there.
+  CSS's `overscroll-behavior: contain` stops the chaining.
+
+## Decisions
+
+1. **A gesture is delimited by the driver.** `InputEvent::ScrollGesture
+   { delta, begins }` carries a delta and whether it is its gesture's
+   first. A bare `InputEvent::Scroll` is a gesture of its own, so a
+   driver that knows nothing of gestures (C's `kui_input_scroll`, Node's
+   `ctx.scroll`, the corpus) gets per-event targeting, now with
+   chaining. C has `kui_input_scroll_gesture(ctx, dx, dy, begins)` for a
+   host with its own loop.
+2. **The native runner begins a gesture** on its first event, after a
+   pause of 200 ms (F104's `GAP`), on a switch between line and pixel
+   deltas, and, for a wheel only, when the pointer moves.
+   - A wheel spun without a pause is one gesture, as in a browser, so a
+     list reaching its end under a spinning wheel does not hand the
+     rest to the page.
+   - Moving the mouse is aiming somewhere new, so it ends a wheel's
+     gesture.
+   - A swipe's momentum outlives the hand, and moving the pointer
+     during the glide must not move the glide somewhere else, so it
+     does not end a swipe's.
+   - An event the axis lock keeps to zero is not dispatched. The
+     beginning it carried is owed to the next one that is.
+   - *Amended 2026-10-02 (F117):* a finger put down begins a gesture
+     too, however soon after the last event, and ends the axis lock's
+     swipe. A `Started` within 100 ms of a finger's `Ended` is the
+     glide's (macOS starts it on the next event) and keeps the gesture;
+     every other `Started` is a finger's — on nothing lifted, or on a
+     glide, which macOS ends as the finger lands. Before this, a swipe
+     begun mid-glide was the glide's gesture until a 200 ms pause, which
+     a glide's events a frame apart never leave.
+3. **The target is picked per axis, when the gesture first moves on
+   that axis, and latched.**
+   - Picking starts at the topmost region under the pointer and walks
+     out through the regions around it in the tree (amended by the
+     alpha.22 regression pass: it walked every region under the pointer
+     by paint order, so a list at its end in a popover chained to a
+     page it merely floated over). The first to take the axis is the
+     target:
+     - an `on_scroll` node takes it if its `scroll_axes` names it,
+       whether or not it has anywhere to go — *amended 2026-10-02
+       (F118):* unless it scrolls that axis as a container too, its
+       offset the app's to set from what it hears; there the core can
+       ask, and it is answered as a container is, below;
+     - a container takes it if it scrolls on that axis and can still
+       move the way the delta goes (more than half a pixel of room,
+       measured from where the delta would be added);
+     - a container that says `overscroll: contain` takes it in any
+       case.
+   - Later events of the gesture go to the latched target, found by key
+     among the frame's scroll regions wherever the pointer or the
+     content has gone.
+   - A target that is gone from the frame, or is behind a modal now, is
+     dropped, and the axis is picked again under the pointer.
+   - An axis that found nothing stays unlatched, so a gesture that turns
+     back can still find a scroller.
+   - Per axis is what DX13's hand-off becomes: a list's `y` and the
+     strip's `x` are two targets. With F104's lock a swipe has one in
+     practice, and a lock that turns picks the new axis's target at the
+     turn.
+4. **No chaining partway through.** A latched container at its limit
+   keeps the gesture and moves nothing, as a browser's does, and turning
+   back within the gesture moves it again.
+5. **`overscroll: "auto" | "contain"`** (`Overscroll`,
+   `KUI_OVERSCROLL_*`) opts a container out of being chained past. It
+   holds only on the axes the container scrolls. So a contained
+   `scrollY` list still passes a sideways swipe to the strip, where CSS
+   would stop that too. kui's one-axis scrollers are
+   not scroll containers on their other axis.
+6. **`scrollAxes: "both" | "x" | "y"`** (`ScrollAxes`,
+   `KUI_SCROLL_AXES_*`) lets an `on_scroll` node decline an axis. A
+   gesture on an axis it does not take passes it by. This is how a node
+   the core cannot ask about says it does not need a gesture: a
+   terminal that scrolls only its history says `y`. It is declared
+   rather than answered per event, because the pick happens inside
+   `handle_input`, before any app code could answer.
+7. **Programmatic scrolls, scrollbar drags, keyboard scrolling, the
+   primary drag's edge scrolling and `reveal` are untouched.** Only the
+   wheel routes through the latch.
+
+## Considered options
+
+- **Re-target on every event, and let `on_scroll` nodes decline by
+  axis only.** Declining alone fixes a y-only terminal met by a
+  sideways swipe, but a terminal that takes both axes, such as an
+  editor's text column, would still grab a strip swipe partway. The
+  report's item 3 is about the swipe being cut off, and only latching
+  fixes that.
+- **An `on_scroll` node answers whether it can move.** An event whose
+  reply says "not mine" would need the app in the middle of dispatch,
+  and a frame's latency for a question the next delta has already
+  asked. `scrollAxes` covers the case that exists: a node that never
+  wants one axis.
+- **Chain partway, when the target hits its limit.** This is what
+  browsers moved away from. A list flicked to its end would start
+  moving the page behind it mid-flick, which is the surprise item 2
+  asks to avoid by deciding at the start.
+- **Keep the gesture clock in the core** (`Core::set_time`). The
+  frame clock ticks per frame, not per event, and a clock-free core
+  is the rule clicks already follow. The runner has the clock and
+  already draws F104's boundaries.
+- **winit's `TouchPhase`.** It marks a momentum run as a new start, so
+  the momentum would re-target. The gap is what tells a glide from a
+  new swipe. *Amended (F117):* the gap alone kept a swipe begun
+  mid-glide in the glide's gesture; the phases' order now tells the
+  glide's `Started` from a finger's, and both are used.
+
+## Consequences
+
+- A notch over a list at its end now moves the scroller around it (a
+  `Scroll` is its own gesture). That changes behaviour only where there
+  is one to move. kawoosh's lists sit in an `x`-only strip, so nothing
+  moves there.
+- An `on_scroll` node in a `both`-axis layout hears a delta with one
+  component zero when the other axis is latched elsewhere, where it
+  heard the whole delta. F104's lock had already made that the
+  trackpad's case.
+- `KuiSpec` gains `overscroll` and `scroll_axes` under the unreleased
+  ABI 20 (648 bytes on a 64-bit target). `InputEvent` gains a variant,
+  a Rust break for a host that matches it exhaustively.
+- The thresholds are F104's, a first reading to be tuned on a trackpad.
+- Pinned by `tests/scroll_gestures.rs` in kui-core, by
+  `scroll_gesture.rs`'s tests in kui-native, by `surface.c`'s check of
+  the C door, and by the corpus's `scroll-gestures` scene in four
+  adapters. The scene holds a contained list at its limit and a y-only
+  handler met by a sideways notch.