@qxuken/kui 0.1.0-alpha.48 → 0.1.0-alpha.50

package/CHANGELOG.md

@@ -21,6 +21,222 @@ listed under both (backlog F61, from the alpha.12 field reports: the list
 is what the release knows it broke, and a fix it did not think of as one
 was the first bare bump to break an app in five releases).
 
+## 0.1.0-alpha.50 (2026-10-09)
+
+**What breaks.**
+
+- `UiEvent::message` reads a core event's `tag` before its payload.
+- A chord a focused editor does not act on reaches the `on_key` sink
+  above it, where it went nowhere.
+- An arrow, Backspace or Delete at the edge of an editor's text emits a
+  `boundary` event, where it emitted nothing.
+- An editor that lost the keyboard no longer draws its selection.
+- `KUI_ABI_VERSION` is 30: `KuiTextStyle` gains `bold` (29) and
+  `KuiMenuItem` `replay` (30). Recompile a C or Odin host.
+- `MenuItem` has a `replay` field: a struct literal of it needs one.
+- A pointer event inside a key sink that draws `role="line"` rows carries
+  `inside` beside `line` and `byte` — a click's own map payload too.
+- `MenuRole` has five more variants (`About`, `Hide`, `HideOthers`,
+  `ShowAll`, `Quit`): an exhaustive `match` on it needs them.
+
+`UiEvent::message` read the payload first and the `tag` second, and a
+core event's payload is `{kind: "key", …}`, `{kind: "open", …}`, `{kind:
+"menu", …}` — so an app whose message enum had a `Key` variant got
+`Msg::Key` back for every key event any of its sinks heard, the sink's
+own tag never consulted (backlog F148, from Noticon, whose root sink
+was tagged `Key` and took the page's keys). A core event — any `kind`
+the events table lists but `click` — now reads as its tag when the tag
+is an `M`, and as the payload otherwise, as before. A click's payload
+is still the app's message as-is, whatever its `kind`. An app that
+matched its own variant against a tagged core event, meaning to or not,
+now gets the tag.
+
+A focused editor kept the whole keyboard: ⌘N, Ctrl+K — any
+press — went to the editor and, if it did nothing with it, nowhere, so an
+app's shortcuts were dead while its search box had focus. ADR 0011
+deferred this until an app wanted it (backlog F144, Noticon's title and
+search fields). An editor now claims what it acts on — the editing keys,
+whatever it types, Space, the clipboard and undo chords — and anything
+pressed without Control or Command, which is typing; any other chord
+goes to the nearest `on_key` sink above it, with its release, as a chord
+bubbles from a control. A shell sink that binds a chord now hears it
+from inside a field, which is the point; one that should not act while
+a field has focus has to check `focused` itself.
+
+An editing key that meets the edge of the text — ↑ on the first line, ↓
+on the last, ← or Backspace at the start, → or Delete at the end, with
+no selection and no Shift — now emits `{kind: "boundary", key, edge,
+word, doc}` on the editor (backlog F145). A handler that counted an
+editor's events, or matched every event on an editor's key as a change,
+sees one more.
+
+An editor that lost the keyboard kept drawing its selection, so a page of
+fields showed a highlight in each and only one of them was what ⌘C
+copied (backlog F147). It now keeps the range and draws none of it until
+focus comes back — and while a context menu or the drawn menu bar opened
+over it is up, since the menu's rows took focus to be chosen and the
+selection is what Copy will copy. A screenshot test of a blurred field
+with a selection changes.
+
+`KuiTextStyle` appends `bold` into its tail padding — the 64-bit size stays
+72 — for F150 below, and `KuiMenuItem` puts `replay` into the padding
+before `submenu`, its stride still 72, for F151; the layouts moved, so
+the ABI did, twice. Zeroed fields are what a text and a row were.
+
+### Added
+
+- **Chords out of a focused editor** (backlog F144, ADR 0011 decision
+  10): see *What breaks*.
+- **`boundary`, an editing key at the edge of the text** (backlog
+  F145): the event a block editor joins blocks and moves between fields
+  by. A field has one line, so its ↑ and ↓ always report.
+- **`keep_tab` on an editor** — `EditOptions::keep_tab`, `keepTab` in
+  JSX, `keep_tab` in Lua, `KUI_EDIT_KEEP_TAB` in C, `.Keep_Tab` in Odin
+  (backlog F146): a field's Tab and Shift-Tab go to the sink above it
+  instead of walking the focus ring, so a list or an outline built from
+  fields indents on Tab. A document keeps Tab either way. A new flag
+  bit, no ABI change.
+- **`inside` on a line sink's pointer events** (backlog F153): whether the
+  point is within the line's own box, false above, below and in the
+  margin beside a row — so a margin gesture is told from a press on the
+  text without comparing `x` to a rect.
+- **The application menu's rows** — `MenuRole::About`, `Hide`,
+  `HideOthers`, `ShowAll`, `Quit`; `"about"`, `"hide"`, `"hideOthers"`,
+  `"showAll"`, `"quit"` as a row's `role`; `KUI_MENU_ABOUT` …
+  `KUI_MENU_QUIT` in C (appended values, no ABI bump) (backlog F152, ADR
+  0018 amended): on a menu bar macOS draws, AppKit's own rows — the About
+  panel, `hide:`, `hideOtherApplications:`, `unhideAllApplications:`,
+  `terminate:` — worded with the app's name, with ⌘H, ⌥⌘H and ⌘Q, posting
+  nothing. In a menu kui draws, Hide, Hide Others and Show All are not
+  offered, and About and Quit post their `menu` event for the app.
+- **A menu row that is its chord** — `MenuItem::replay`, `replay` on a
+  plain-data row (JSX, Lua), `KuiMenuItem.replay` and
+  `KUI_MENU_ITEM_REPLAY` in C, `replay` on Odin's `Menu_Item` (backlog
+  F151, ADR 0018 amended): chosen — by the pointer, or by the key
+  equivalent the macOS bar binds — it plays its `accel` where the
+  keyboard is, as the standard Edit menu's rows do, and posts no `menu`
+  event. A declared Edit menu's Undo is a field's undo while a field has
+  focus and the app's otherwise, with no rebuilding of the bar.
+- **`bold` on a whole text or an editor** — `TextStyle::bold`, `bold` in
+  JSX and Lua, `KuiTextStyle.bold` in C (ABI 29), `bold` on Odin's
+  `Text_Style` (backlog F150): the family's bold — its bold face, or its
+  regular drawn bold where it has none, as a span's `bold` is — so a
+  heading or a title field is bolder, not only bigger. A span inside a
+  bold text is bold too.
+- **A placeholder on an editor** — `EditOptions::placeholder`,
+  `placeholder` in JSX and Lua, `kui_text_edit_placeholder` in C (a new
+  function, no ABI bump), `placeholder` on Odin's `kui.text_edit`
+  (backlog F149): what an empty editor shows where its text would be, in
+  the theme's `faint`. Never part of the value, gone with the first
+  character typed or composed, and the field's accessible description
+  when it declares none.
+
+### Fixed
+
+- **A message variant named like a core event no longer catches it**
+  (backlog F148): see *What breaks*.
+- **One selection on screen among several editors** (backlog F147): see
+  *What breaks*.
+
+**What you can delete.**
+
+- Renaming a message variant, or a sink's tag, away from a core event's
+  kind (`Key`, `Open`, `Menu`, `Changed`) so `message` reads the tag.
+- Routing an app's shortcuts through a declared menu bar, or a field's
+  own key handling, so they work while a field has focus.
+- Comparing a drag's `x` against a line's rect to tell a margin press
+  from a press on its text.
+- Sending `hide:`, `hideOtherApplications:` or `unhideAllApplications:`
+  to `NSApplication` by hand, and quitting from a declared bar by closing
+  the window.
+- Rebuilding a declared menu bar as focus moves, unbinding rows a field
+  needs its key for, and replaying a chosen row's accelerator by hand.
+- A one-span `rich_text` or a registered bold face standing in for a bold
+  heading, and a bold title that could not be an editor.
+- A faint text floated over an empty field and positioned by hand to
+  match the editor's insets, standing in for a placeholder.
+- Collapsing an editor's selection when it loses focus, to keep a page
+  of fields from showing several highlights.
+- Comparing an editor's text before and after an arrow or Backspace to
+  tell whether it reached the edge, or a separate key sink over a field
+  to hear ↑ and ↓.
+
+### Native verification
+
+The by-hand round on 2026-10-09, over Noticon's macOS polish round —
+F144–F153, W23 and the Odin binding checked against the generator — on
+the Mac: the mechanical round as CI runs it, the Odin binding with an
+Odin built locally against LLVM 21 rather than CI's pinned one in its
+image, and the bench guard. The windowed round, the accessibility audit
+and the other checks that need someone at the screen were not run this
+time.
+
+**macOS**, the pre-tag pass. fmt and clippy are clean; `nu
+scripts/test.nu`: **2054 tests over 154 suites**, 0 failed, 4 ignored.
+The C round passes (5 checks), and so do the **58 scenes** through
+Rust, Lua, C, Odin and Node; Node's tests under
+`KUI_CONFORMANCE_REQUIRED=1`, **228 of 228**; `npm run gen` with no
+diff, the examples' typecheck, the headless round (8.0 s), the book's
+examples current. `nu scripts/odin.nu gen --check` says the binding is
+current, `odin.nu check` vets both packages and every example, and
+`odin.nu test` runs its four. The bench guard against the alpha.49 tag:
+**green**, the eight guarded rows within tolerance. Not run: the
+windowed round over every example and the four hosts, and the AX audit.
+No Windows or Linux machine ran this round.
+
+## 0.1.0-alpha.49 (2026-10-09)
+
+### Changed
+
+- **A Lua view lowers in about two-thirds of the time** (backlog F143).
+  kui-lua reads each table in one pass: `Table::for_each` with a key
+  type that copies a string key's bytes off the Lua stack instead of
+  making a registry reference for it (a `pairs` step made one for every
+  key and every string or table value, and dropped it again), the keys
+  matched as bytes, the schema rows looked up in a hash map rather than
+  scanned, `size` and `radius` read in the same pass and still applied
+  before the rows they underlie, a text's `value` and `spans` taken from
+  it, and a span's twelve style keys, a `pad` table's seven edges and
+  the unknown-prop check — a second walk over every table while the
+  core's diagnostics are on — folded into it. Nothing a view writes
+  changes, and a table in an unusual shape (a number for a text's
+  `value`, a span's `size` as a string) is read through `get` as before.
+  Measured over a settings pane's worth of tables (`cargo bench -p
+  kui-lua --bench walk`, medians): **2.55 → 1.64 ms** a frame with the
+  diagnostics off, as a release build of the windowed runner has them,
+  and **3.42 → 1.75 ms** with them on; in kawoosh's settings, themes,
+  theme lab and grammars panes the walk went 3.45 → 2.27, 3.51 → 2.13,
+  2.12 → 1.42 and 1.46 → 1.06 ms on the frames a pane is rebuilt in.
+  The rest of the walk is mlua's own reference for each string and
+  table value, which its safe API does not let a binding skip.
+
+**What you can delete.**
+
+- Hand-flattening a Lua view's tree, or building it in fewer, larger
+  tables, to keep the lowering off the frame: kawoosh's settings pane
+  lowers at about 1.4 µs a table where it took 2.2.
+
+### Native verification
+
+The by-hand round on 2026-10-09, over F143 — kui-lua's walk from a
+view's tables to the tree — on the Mac: the mechanical round as CI runs
+it, the Odin binding checked with CI's pinned Odin in its Debian image,
+the windowed round, the accessibility audit and the bench guard.
+
+**macOS**, the pre-tag pass. fmt and clippy are clean; `nu
+scripts/test.nu`: **2034 tests over 152 suites**, 0 failed. The C round
+passes (5 checks), and so do the **58 scenes** through Rust, Lua, C and
+Node; Node's tests under `KUI_CONFORMANCE_REQUIRED=1`, **225 of 225**;
+`npm run gen` with no diff, the examples' typecheck, the headless round
+(4.0 s). `nu scripts/odin.nu gen --check` says the binding is current
+and `odin.nu check` vets both packages and every example. The windowed
+round with Node's: **55 examples on both bases**, clean on a first run,
+and `counter`, `host`, `c_panel` and `lua_panel` for 120 frames each.
+The accessibility audit: **106 of 106**. The bench guard against the
+alpha.48 tag: **green**, the eight guarded rows within tolerance; the
+new `walk` rows are in docs/performance.md. No Windows or Linux machine
+ran this round.
+
 ## 0.1.0-alpha.48 (2026-10-09)
 
 **What breaks.**

package/docs/adr/0011-keys-bubble-to-the-enclosing-sink.md

@@ -159,6 +159,34 @@ around its content, which is what both reports already wrote.
    pointer's rule is untouched: a click past the clip still finds
    nothing.
 
+10. **An editor claims what it acts on, and a chord it does not bubbles**
+    (amended 2026-10-09, backlog F144–F146; the deferral under
+    *Considered options* met its condition — Noticon wanted ⌘N, ⌘F and
+    its sidebar's chord from inside its title and search fields, which is
+    "⌘K from inside its search box"). `Core::editor_claims` is decision
+    2's claim for an editor, static like it: every press its editing
+    channel acts on (`KeyPress::edit_event` — the editing keys, Space,
+    whatever types), the clipboard and undo chords the runner performs
+    for it (the primary modifier with C, X, V, A, Z or Y, the table
+    `Shell::edit_chord` reads), and every press without Control or
+    Command, which is typing — a Mac's Option composes, and a key with no
+    text yet may be the first half of a composition. Anything else goes
+    to the nearest sink above the editor, exactly as a chord bubbles from
+    a control, its release with it. The runner's chord table did not move
+    into the core: the core claims those chords by name and the runner
+    performs them, and what the ADR feared — ⌘C in a field reaching the
+    shell and copying — cannot happen while the claim names them. With no
+    sink above, the press goes nowhere, as before. Two things came with
+    it. A field declared `keep_tab` does not claim Tab: Tab and Shift-Tab
+    go to the sink above instead of walking the ring, so a list built
+    from fields indents on Tab (a document keeps Tab either way). And an
+    editing key the editor holds but cannot act on — ↑ on its first line,
+    ↓ on its last, ← or Backspace at the start, → or Delete at the end,
+    from a caret with no selection and without Shift — emits `boundary
+    {key, edge}` on the editor, so a block editor joins and moves between
+    its fields; the key itself still never bubbles, since the editor did
+    claim it.
+
 ## Considered options
 
 - **A `keys` allow-list on the sink** (`onKey={handler} keys={['space',
@@ -200,7 +228,9 @@ around its content, which is what both reports already wrote.
   tells those apart from a shell (splitmux's sink encloses focusable
   panes and binds chords; a terminal's encloses nothing and binds Tab).
   Decision 4 gives a shell the same outcome in one line of its own code.
-- **Bubble out of a focused editor too.** Deferred, deliberately. An
+- **Bubble out of a focused editor too.** *Built 2026-10-09 as decision
+  10 (backlog F144); what follows is the deferral as it was written.*
+  Deferred, deliberately. An
   editor claims the whole printable keyboard plus the editing keys, so
   what is left is chords — and the clipboard chords are handled *above*
   the core, in the runner (`crates/kui-native/src/lib.rs`), which the core cannot
@@ -254,5 +284,5 @@ around its content, which is what both reports already wrote.
   modal boundary. The corpus's `keys` scene gains the shell over a ring,
   so all four bindings reproduce it byte for byte.
 - **What is still one keyboard away:** an editor's leftovers (deferred
-  above), and a sink hearing a press that landed on a *window* it does not
+  above; built 2026-10-09 as decision 10), and a sink hearing a press that landed on a *window* it does not
   own, which is ADR 0004's routing and not this one's.

package/docs/adr/0018-a-menu-bar-the-app-declares.md

@@ -164,6 +164,23 @@ does. An app that has to write the menu twice has not been given a menu.
    disabled row's in the disabled colour, since AppKit draws an
    attributed title as given). The rule is unchanged; the Mac keeps it.
 
+   *Amended 2026-10-09 (backlog F151).* The key equivalent made every
+   bound row a trap: AppKit takes ⌘Z before a focused field sees it, so an
+   app with a declared Edit menu and a field had to unbind its Undo row
+   while the field had focus, and rebuild the bar each time focus moved —
+   Noticon did. A row can now *be* its chord: `MenuItem::replay` (`replay`
+   in the plain-data row, `KuiMenuItem.replay` in C, ABI 30). Chosen — by
+   the pointer, or by the key equivalent — it plays its `accel` where the
+   keyboard is, exactly as the standard Edit menu's rows do (ADR 0030,
+   decision 3): the press to the key sink, then the runner's clipboard
+   half or the editing key, then the release (`Shell::replay_key`, which
+   the standard rows now go through too). It posts no `menu` event; the
+   chord is what it says. In a menu the core draws, or reports for a host,
+   `Core::replay_chord` does the same where the menu took the keyboard
+   from, with the core doing the clipboard and undo chords itself. The
+   core still binds nothing: a replay row on a drawn bar is still only
+   chosen by the pointer, and the key is the app's as it always was.
+
 8. **The bar is per application, and the frontmost window's declaration
    wins.** macOS has one menu bar for the process; kui has a `Core` per
    window. The runner applies the declaration of the window that holds the
@@ -205,6 +222,22 @@ does. An app that has to write the menu twice has not been given a menu.
   own answer for what the *drawn* bar does with each. An app spells ⌘Q
   today with an item and a close in its handler.
 
+  *Built 2026-10-09 (backlog F152).* A declared bar replaces the
+  application menu winit made, so an app that declared one lost Hide,
+  Hide Others, Show All and Quit, and Noticon sent `hide:` to
+  `NSApplication` itself. The answer for the drawn bar is the one Look Up
+  already had: `MenuRole::About`, `Hide`, `HideOthers`, `ShowAll` and
+  `Quit`, appended to `ALL` (`KUI_MENU_ABOUT` … `KUI_MENU_QUIT`, no ABI
+  bump). Where macOS draws the bar each is the platform's own row, sent
+  up the responder chain to `NSApplication` (`orderFrontStandardAboutPanel:`,
+  `hide:`, `hideOtherApplications:`, `unhideAllApplications:`,
+  `terminate:`), worded with the process's name where the Mac words it so
+  and given the Mac's ⌘H, ⌥⌘H and ⌘Q, posting nothing. Where kui draws
+  the menu, Hide, Hide Others and Show All are not offered (there is no
+  application to hide), and About and Quit are drawn and post their
+  `menu` event like the app's own rows — the app's about box, the app's
+  close. `services` stays declined.
+
 - **A row in `env.system`.** Decision 4.
 
 ## Consequences

package/docs/adr/0030-the-standard-menus-the-runner-keeps.md

@@ -127,7 +127,9 @@ date: 2026-09-14
   under another name would have no way to say so. Naming a menu `Window`
   costs one word.
 
-- **`MenuRole::Minimize` / `Zoom` / `FullScreen` / `Quit`.** ADR 0018's
+- **`MenuRole::Minimize` / `Zoom` / `FullScreen` / `Quit`.** (*`Quit`
+  built 2026-10-09 with the application menu's other rows, backlog F152;
+  see ADR 0018.*) ADR 0018's
   decline, unchanged: each needs a drawn-bar answer, an ABI bump and four
   bindings, for rows the platform performs on its own responder chain.
   The condition that would build them is an app that wants to compose a

package/encoder.js

@@ -1002,7 +1002,8 @@ export function createEncoder(P) {
         f[fi++] = OP.edit;
         strRef(label);
         strRef(p.initial ?? '');
-        f[fi++] = (p.multiline ? 1 : 0) | (p.autofocus ? 2 : 0);
+        f[fi++] = (p.multiline ? 1 : 0) | (p.autofocus ? 2 : 0) | (p.keepTab ? 8 : 0);
+        strRef(p.placeholder ?? null);
         props(p, null, false);
         return;
       }
@@ -1018,6 +1019,7 @@ export function createEncoder(P) {
         strRef(String(label));
         strRef(p.initial ?? '');
         f[fi++] = 4;
+        strRef(null);
         props({}, null, false);
         return;
       }

package/index.d.ts

@@ -149,9 +149,11 @@ export type ButtonMsg<T = AppMsg> = {
   /** On a `cells` grid: the cell under the pointer, clamped to the grid. */
   cell?: { row: number; col: number };
   /** Inside an `onKey` sink that draws `role="line"` rows: the line and
-   *  the byte in its text, as a drag carries them. */
+   *  the byte in its text, as a drag carries them, and whether the point
+   *  is within that line's own box (false in the margin beside it). */
   line?: number;
   byte?: number;
+  inside?: boolean;
   tag?: T;
 };
 
@@ -468,6 +470,19 @@ export type ModifiersMsg = {
  *  key is on the event, so `editText(ev.key)` reads it back. */
 export type EditMsg = { kind: 'changed' } | { kind: 'submit' };
 
+/** An editing key that met the edge of an editor's text and did nothing
+ *  (backlog F145): ↑ on the first line, ← or Backspace at the start, ↓ on
+ *  the last line, → or Delete at the end — from a caret with no selection
+ *  and without Shift. On the editor's key. `word` and `doc` are the
+ *  editing modifiers the key carried. */
+export type BoundaryMsg = {
+  kind: 'boundary';
+  key: 'up' | 'down' | 'left' | 'right' | 'backspace' | 'delete';
+  edge: 'start' | 'end';
+  word: boolean;
+  doc: boolean;
+};
+
 /** A tagged playback (`play(id, { tag })` or `<audio tag>`) finished on its
  *  own — never when something stopped it. On an `<audio>` node's key, or the
  *  root for `play`. `'refused'` is the device declining to start it at all
@@ -506,6 +521,7 @@ export type CoreMsg =
   | WindowMsg
   | ModifiersMsg
   | EditMsg
+  | BoundaryMsg
   | SoundMsg
   | AccessMsg
   | ChangeMsg

package/jsx-runtime.d.ts

@@ -209,7 +209,8 @@ export interface FloatProp {
  *  the standard rows the core performs itself. The same spelling a
  *  `menu` message reports back. */
 export type MenuItemRole =
-  | 'custom' | 'separator' | 'cut' | 'copy' | 'paste' | 'selectAll' | 'lookUp';
+  | 'custom' | 'separator' | 'cut' | 'copy' | 'paste' | 'selectAll' | 'lookUp'
+  | 'about' | 'hide' | 'hideOthers' | 'showAll' | 'quit';
 // -- end generated --
 
 /** One row to put in a context menu (`Ctx.openMenu`). Everything but
@@ -236,6 +237,13 @@ export interface MenuItemInput {
    *  closes it — and is never chosen itself. A chosen row inside posts its
    *  own `menu` event, on the node the menu is about. */
   items?: MenuItemInput[];
+  /** The row *is* its `accel`: chosen — by the pointer, or by the key
+   *  equivalent a platform menu bar binds — it plays that chord where the
+   *  keyboard is and posts no `menu` event, as the standard Edit menu's rows
+   *  do. A field with focus undoes or copies through its own key, a sink
+   *  that binds the chord hears it. A row whose `accel` kui cannot parse is
+   *  an ordinary row. */
+  replay?: boolean;
 }
 
 /** One menu of the application menu bar (the `<menuBar menu={…}/>`
@@ -473,6 +481,8 @@ export interface GeneratedSpecProps {
 }
 
 export interface GeneratedStyleProps {
+  /** The family's bold, on a whole text or an editor (backlog F150) — a heading, a table's header, a title field: its bold face, or its regular drawn bold where the family has none, as a `<span bold>` is. A span inside a bold text is bold too. */
+  bold?: boolean;
   /** Text color; default foreground when omitted. */
   color?: ColorProp;
   /** End the last line with an ellipsis when the text is cut off: a single line unless `maxLines` says otherwise. */
@@ -733,6 +743,14 @@ export interface EditProps extends TextProps, GeneratedSpecProps, CustomSpecProp
    *  while nothing holds focus (ADR 0022, decision 9); a blur afterwards
    *  stands. `focus(key)` moves it at any other time. */
   autofocus?: boolean;
+  /** A field's Tab is the app's: Tab and Shift-Tab do not walk the focus
+   *  ring from it, and the press goes to the `onKey` sink above it — so a
+   *  list built from fields indents on Tab. A `multiline` editor keeps Tab
+   *  either way. */
+  keepTab?: boolean;
+  /** What the editor shows, faint, while it is empty: never part of its
+   *  text, and its accessible description when it declares none. */
+  placeholder?: string;
 }
 
 type Component<P> = (props: P) => KuiNode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qxuken/kui",
-  "version": "0.1.0-alpha.48",
+  "version": "0.1.0-alpha.50",
   "description": "kui for Node: JSX views lowered into the kui IR, Elm-style messages as data",
   "license": "MIT",
   "repository": {

package/props.md

@@ -121,6 +121,7 @@ where they make sense); text props apply to `<text>` and `<edit>`.
 
 | JSX | Lua | C | Odin | type | description |
 |---|---|---|---|---|---|
+| `bold` | `bold` | `KuiTextStyle.bold`; `KuiSpan.flags` (`KUI_SPAN_BOLD`) | `Text_Style.bold` | boolean | The family's bold, on a whole text or an editor (backlog F150) — a heading, a table's header, a title field: its bold face, or its regular drawn bold where the family has none, as a `<span bold>` is. A span inside a bold text is bold too. |
 | `color` | `color` | `KuiTextStyle.color` | `Text_Style.color` | color (`#hex` or `0xRRGGBBAA`), or a `"$color"` token | Text color; default foreground when omitted. |
 | `ellipsis` | `ellipsis` | `KuiTextStyle.ellipsis` | `Text_Style.ellipsis` | boolean | End the last line with an ellipsis when the text is cut off: a single line unless `maxLines` says otherwise. |
 | `family` | `family` | `KuiTextStyle.family` (`KUI_FONT_*`); `KuiSpan.family` (with `KUI_SPAN_FAMILY`) | `Text_Style.family` | `sans` \\| `serif` \\| `mono` \\| a family name | Font family: `sans`, `serif` or `mono`, kui's own, or the name of an installed family or one loaded with `loadFontsDir` / `loadFontFile` — `"Berkeley Mono"` — drawn in its face in the frame that names it (ADR 0037). A name is matched as `addSystemFont` matches it and registered in the session on first sight, exactly as the font database spells it (`"menlo"` is not `"Menlo"`); the session's first registration of any font maps the installed font files once (~30 ms on a Mac, backlog DX24), which a family named in a view pays in that frame. `systemFonts()` lists the names there are. A name nothing matches shapes as sans and raises `unknown-family`. It and `font` set the same thing, so declare one. |
@@ -164,7 +165,7 @@ where they make sense); text props apply to `<text>` and `<edit>`.
 | `<box dir="table">` | `grid { }` | `kui_open*` with `dir = KUI_TABLE` | `kui.box` with `dir = .Table` | A column whose rows' children line up in columns (`docs/adr/0033-a-table-is-a-column-whose-cells-align.md`): its children are the rows, each row's in-flow children its cells, the nth cell of every row column n, and a column as wide as its widest cell — so a label column sits at its longest label with nothing measured and no width picked by hand, in every binding, since the alignment is the layout's and not a widget's. A cell's `width` says how its column sizes: `fit` (the default) and a fixed number are content the column's fit width is the max of; `grow` makes the whole column grow with the table, `grow` factors splitting the room the fit columns leave; a percent takes its cut of the row; and a column's `minWidth` / `maxWidth` are the strictest its cells declared. Fit columns that overflow the row are compressed toward their floors largest first, as a row's children are, unless the table scrolls x; a fixed column never is. A bare text is a cell too, held at its column's width, so a text straight inside a row is a column; an image straight in a row is a cell the same way, its box the column wide and its own aspect tall, the pixels meeting the box by its `fit` row (wrap an icon in a box to keep its own width). The rows are the table's `row` children, ordinary rows — give them `width="grow"` for the columns to grow into (a `fit` row sits at the columns' width) — with their own `gap` between cells, their own padding, background, click, hover and access rows; a row of a table never wraps (`wrap-ignored`). Anything else straight under the table — a text, a `column` section, another table — is a child with its own width and no cells. The table's own `fit` width is its columns', whatever its rows' sizing, so a table with no width is the aligned list; a `scrollX` table's rows are at least as wide as its columns, and it scrolls to them. Everything else is a column's: `gap` is the space between rows, `scrollY` scrolls them, a float in a row is not a cell. Spelled `grid { }` in Lua, since `table` is Lua's own. |
 | `<text>` with `<span bold italic underline strikethrough bg bgRadius color family font size>` children | `text("s", {…})`, `text({ "a", { "b", bold = true, underline = true, bg = 0x.., bg_radius = 4 }, { "code", family = "mono", size = 13 } })` | `kui_text`, `kui_rich_text` | `kui.text`, `kui.rich_text` | Plain or rich text; spans shape as one paragraph, so wrapping crosses style boundaries. A text is content plus a style and no box of its own, so the rows it reads are the style rows (`size`, `lineHeight`, `color`, `family`, `font`, `wrap`, `maxLines`, `ellipsis`, `underline`, `strikethrough`, `features`) and nothing else: a container row, an access row (`label`, `role`, `live`), `key` or `onClick` on a text is dropped with an `unknown-prop` warning naming the rows it does take — put them on the box around it. `wrap`, `maxLines` and `ellipsis` control line breaking. A span's `bg` is a background behind its glyphs alone, one rect per line it spans, so it follows the span across a wrap the way a box around a run cannot. With `bgRadius` (`bg_radius` in Lua, `KuiSpan.bg_radius` in C, `Span::bg_radius` in Rust; logical px) the background is rounded and joined into one shape with every rounded background of the same colour and radius it meets: a piece whose edge touches it exactly on the line above or below and overlaps it sideways, or that meets it end to end on its own line, in this text or another. Its corners are then convex where a line reaches past its neighbour, a fillet where it falls short, and round where nothing meets it — a selection over many rows, or over the wrapped lines of a paragraph, is one rounded outline, joined after every text of the frame is laid out and painted, so it is never a frame behind. Nothing names the shape: two that touch are one; `underline` and `strikethrough` on a span or on the whole text are lines where the face puts them. A span takes a face and a size of its own: `family` (a stock name or an installed family's, as the text's) or `font` (a handle, which wins) — inline code in `mono` inside a sans paragraph — and `size` in logical px, its line height scaled at the paragraph's ratio (`Span::family` / `Span::mono` / `Span::size` in Rust, `KuiSpan.family` with `KUI_SPAN_FAMILY`, `.font` and `.size` in C). Its glyphs are shaped in that face, so a caret, a hit, a selection and the measurement read the same glyphs and byte positions stay exact across the change; a line is as tall as its tallest span, and a span's background is its own height around its glyphs. A paragraph with a sized span is shaped whole, never in chunks. A text with no line breaks that is 4096 bytes or longer (and no `maxLines` or `ellipsis`), plain or spans alike, is shaped in ~1 KB chunks as they come on screen, so a minified bundle or a log line with a blob in it costs the screenful it shows and a keystroke into it — or a span moving along it, an editor's caret — costs the chunk it lands in; wrapped, the rows are broken from the chunks' positions, so a 100k-character paragraph costs the rows it shows. Its size is estimated from the first chunk until the rest shape (exact under monospace), and the access tree carries its value without its runs. |
 | `<button onClick key\|index label description tooltip disabled accent>` | `button { label=, on_click=, key= \| index=, text=, description=, tooltip=, disabled=, accent= }` | `kui_button`, `kui_button_with` | `kui.button` | The stock button: `widgets::button_spec(&theme, &metrics)` — the theme's accent trio as its three backgrounds, declared on the node and resolved by the core — keyed by its text (`key` overrides). It paints from the palette like every stock widget (backlog AR41): the OS's accent where the host reports one, the app's where it set or pinned one, kui's blue otherwise; the label goes black or white by the background's luminance. Its look is its spec, so the layout and paint rows are closed — declared, they are dropped with an `unknown-prop` warning naming the rows it does read — and those are the access rows: `label` when the text is not the name, `description`, `tooltip`, and `disabled` (inert, and dimmed to half). The one paint row it takes is `accent`, which on a button changes nothing (it is the accent already) and is kept for the box's sake. In Lua `label` is the name and the text both unless `text` says otherwise; in C the rows ride a `KuiSpec` whose other fields `kui_button_with` ignores. A button that needs any other row is a box with `role="button"` and the same rows spelled out. |
-| `<edit key initial multiline autofocus>`, `<input label initial>` | `edit { key=, initial=, … }`, `input { label=, initial= }` | `kui_text_edit`, `kui_text_input` | `kui.text_edit`, `kui.text_input` | Retained editor state by key; read it back with `editText(key)` after a `changed` event. `initial` seeds a new editor only — a key declared again keeps the draft the user typed, and `setEditText(name, text)` is what resets one (it leaves the caret at the end). Name it by the label its `key` prop declares — `setEditText('note', text)` — or by the hex key an event carried. It reaches an editor that does not exist yet: the text is held for the frame that declares that name and seeds it there, over `initial`, so the `update` that opens a rename field can fill it in the same turn, which is what the label spelling is for — the hex key comes from an event an editor being opened has not fired. A name nothing declares on that frame drops its text with an `edit-text-without-editor` warning. A single-line editor is a field and a `multiline` one a document, which decides how each is laid out as well as how it reads: a field takes one line whatever its box, sizes to the text it holds when its width is `fit`, and scrolls that line under the caret when it is not, while a document wraps to its box. The one exception is a field with `wrap` declared (`wrap="word"` or `"glyph"`): it folds to its width the way a document does and keeps a field's keyboard — Enter still submits, a newline is still never admitted, the caret still opens at the end — so a rename field breaks where the label it renames breaks, and with `width="fit"` plus `maxWidth` it sizes to its wrapped draft on the keystroke frame. A single-line editor opens with the caret after its seeded text, as a native field does; a multiline one is a document and opens at its top — a held `setEditText` is the call, not a seed, so it opens at the end either way. State is kept while the key is declared; an undeclared one is kept until the budget needs the room (256 undeclared editors, longest-undeclared evicted first). `autofocus` asks once: the editor takes focus on the frame the flag starts being declared — a new editor, or one whose flag just turned on — and only while nothing holds focus, so a blur afterwards stands and a focused control is never robbed (`docs/adr/0022-focus-regions.md`, decision 9); `focus(key)` is the call for taking it at any other time. |
+| `<edit key initial multiline autofocus keepTab placeholder>`, `<input label initial>` | `edit { key=, initial=, keep_tab=, placeholder=, … }`, `input { label=, initial= }` | `kui_text_edit`, `kui_text_edit_placeholder`, `kui_text_input` | `kui.text_edit`, `kui.text_input` | Retained editor state by key; read it back with `editText(key)` after a `changed` event. `initial` seeds a new editor only — a key declared again keeps the draft the user typed, and `setEditText(name, text)` is what resets one (it leaves the caret at the end). Name it by the label its `key` prop declares — `setEditText('note', text)` — or by the hex key an event carried. It reaches an editor that does not exist yet: the text is held for the frame that declares that name and seeds it there, over `initial`, so the `update` that opens a rename field can fill it in the same turn, which is what the label spelling is for — the hex key comes from an event an editor being opened has not fired. A name nothing declares on that frame drops its text with an `edit-text-without-editor` warning. A single-line editor is a field and a `multiline` one a document, which decides how each is laid out as well as how it reads: a field takes one line whatever its box, sizes to the text it holds when its width is `fit`, and scrolls that line under the caret when it is not, while a document wraps to its box. The one exception is a field with `wrap` declared (`wrap="word"` or `"glyph"`): it folds to its width the way a document does and keeps a field's keyboard — Enter still submits, a newline is still never admitted, the caret still opens at the end — so a rename field breaks where the label it renames breaks, and with `width="fit"` plus `maxWidth` it sizes to its wrapped draft on the keystroke frame. A single-line editor opens with the caret after its seeded text, as a native field does; a multiline one is a document and opens at its top — a held `setEditText` is the call, not a seed, so it opens at the end either way. State is kept while the key is declared; an undeclared one is kept until the budget needs the room (256 undeclared editors, longest-undeclared evicted first). `autofocus` asks once: the editor takes focus on the frame the flag starts being declared — a new editor, or one whose flag just turned on — and only while nothing holds focus, so a blur afterwards stands and a focused control is never robbed (`docs/adr/0022-focus-regions.md`, decision 9); `focus(key)` is the call for taking it at any other time. A focused editor keeps the keys it acts on — the editing keys, what it types, the clipboard and undo chords — and a chord it does not (⌘N, Ctrl+K) goes to the nearest `onKey` sink above it, as a chord bubbles from a control (`docs/adr/0011-keys-bubble-to-the-enclosing-sink.md`, amended 2026-10-09). `keepTab` makes a field's Tab the app's: Tab and Shift-Tab do not walk the focus ring from it, and the press goes to the sink above it the same way, so a list or an outline built from fields indents on Tab; a `multiline` editor keeps Tab for indentation either way. An arrow, Backspace or Delete that meets the edge of the text emits `boundary` (see the events). `placeholder` is what an empty editor shows where its text would be, in the theme's `faint` — never part of the value, gone with the first character typed or composed, and read as the field's accessible description when it declares none. |
 | `<select label options={[…]} current>` | `dropdown { label=, options={…}, current= }` | `kui_select` | `kui.select` | The stock select (`widgets::select_items`, backlog F72): a field showing the choice in force that, clicked, opens the core's own menu of the options under it with the current one checked — the menu a right-click opens, drawn in the frame or the platform's where the host shows menus itself, dismissed by Escape or a press outside, its rows walked by the arrows and read as a menu. `label` is the key and the accessible name both; `options` is a list whose entries are strings (an option by its label, posting it) or menu-item objects `{ label, id, enabled }` (posting `id`), and a `{ role: "separator" }` is a separator; `current` is the index in force, counted from 0 in JSX and C and from 1 in Lua, or none — one past the options or on a separator is none, with a `select-current-ignored` warning on the field; an empty `options` is refused, and a key of an option object no row reads (`disabled`, where the key is `enabled`) is an `unknown-prop` warning. The app holds no open state: the choice arrives as the `menu` event a menu row posts, on the field's key — `{kind: "menu", role: "custom", item: <the option>}` — and drawing the field again with the new `current` is the whole loop. A reader hears a button named by the field, described by its choice, expanded while the menu is open. Its look is its spec, so it reads no other row: a layout, paint or access row on it is dropped with an `unknown-prop` warning. Lua spells it `dropdown`, since `select` is Lua's own. |
 | `<checkbox checked mixed onClick key label description tooltip disabled>text</checkbox>` | `checkbox { label=, checked=, mixed=, on_click=, key=, text=, description=, tooltip=, disabled= }` | `kui_checkbox` | `kui.checkbox` | The stock checkbox (`widgets::toggle_with`, ADR 0034): a box drawn from the state the view declares — `checked`, or `mixed` for the select-all box over a list some of whose rows are selected, drawn as a dash and read as mixed — and its label beside it, keyed by its text (`key` overrides). The state is the app's: a press by the pointer, Space, Enter or assistive technology posts `onClick`, and the view flips its model and draws it again. Its look is its spec, so the layout and paint rows are closed and dropped with an `unknown-prop` warning; the rows it reads are its state and the access rows. In Lua `label` is the name and the text both unless `text` says otherwise. The box is the metrics' control text plus one (16 px comfortable), so `compact` and `scaled` move it with the stock button. |
 | `<radio checked onClick key label description tooltip disabled>text</radio>` | `radio { label=, checked=, on_click=, key=, text=, description=, tooltip=, disabled= }` | `kui_radio` | `kui.radio` | The stock radio (`widgets::toggle_with`, ADR 0034): a circle drawn from `checked`, and its label, keyed by its text. Put radios in a `radioGroup`, which makes them one Tab stop whose arrows, Home and End move the choice and press the radio they land on (ADR 0007), so radios whose `onClick` each set the choice answer the keyboard with no more code. The state is the app's, as a checkbox's is; the rows are the checkbox's, `mixed` aside. |
@@ -195,8 +196,8 @@ one field. The payload shapes:
 
 | kind | payload | when |
 |---|---|---|
-| click | the `onClick` payload as-is | A press and release on the node (suppressed when a drag moved past the slop). A map payload gains fields where the node can say more: `cell: {row, col}` on a `cells` grid, and inside an `onKey` sink that draws `role="line"` rows, `line`, `byte` and `clicks` as a `drag` inside one carries them. |
-| drag | `{ kind: "drag", phase: "start" \| "move" \| "end", x, y, dx, dy, parent: { x, y, w, h }, tag }` | A pointer-captured drag on an `onDrag` node. `x`/`y` are where the pointer is; `dx`/`dy` are its displacement **from the press point**, in every phase — `start` carries zero, a `move` how far the pointer is from where it pressed, `end` the whole distance — so a handler sets `value = start + dx` rather than summing deltas, and can commit from `end` alone. Nothing is dropped under the click slop (3 px, measured from the press): the first `move` already carries the whole distance. `parent` is the container rect, so fractions need no geometry query. On a `cells` grid every phase also carries `cell: {row, col}`. Inside an `onKey` sink that draws `role="line"` rows — an editor the app owns — every phase carries `line` (the ordinal among the sink's lines, the numbering its `access` events use), `byte` (where the point falls in that line's text, what `textHit` would answer) and `clicks` (the press's count), so click-to-caret, drag-select and double-click-word are arithmetic on the event with no query and no frame of lag; a point above the first line is the first, below the last the last, and one in a `role="none"` gutter is the line beside it. Nothing is added where the sink draws no lines. |
+| click | the `onClick` payload as-is | A press and release on the node (suppressed when a drag moved past the slop). A map payload gains fields where the node can say more: `cell: {row, col}` on a `cells` grid, and inside an `onKey` sink that draws `role="line"` rows, `line`, `byte`, `inside` and `clicks` as a `drag` inside one carries them. |
+| drag | `{ kind: "drag", phase: "start" \| "move" \| "end", x, y, dx, dy, parent: { x, y, w, h }, tag }` | A pointer-captured drag on an `onDrag` node. `x`/`y` are where the pointer is; `dx`/`dy` are its displacement **from the press point**, in every phase — `start` carries zero, a `move` how far the pointer is from where it pressed, `end` the whole distance — so a handler sets `value = start + dx` rather than summing deltas, and can commit from `end` alone. Nothing is dropped under the click slop (3 px, measured from the press): the first `move` already carries the whole distance. `parent` is the container rect, so fractions need no geometry query. On a `cells` grid every phase also carries `cell: {row, col}`. Inside an `onKey` sink that draws `role="line"` rows — an editor the app owns — every phase carries `line` (the ordinal among the sink's lines, the numbering its `access` events use), `byte` (where the point falls in that line's text, what `textHit` would answer) and `clicks` (the press's count), so click-to-caret, drag-select and double-click-word are arithmetic on the event with no query and no frame of lag; a point above the first line is the first, below the last the last, and one in a `role="none"` gutter is the line beside it, and `inside` says whether the point is within that line's own box at all — false above, below and in the margin beside a row, so a margin gesture (block selection) is told from a press on the text without comparing `x` to a rect. Nothing is added where the sink draws no lines. |
 | key | `{ kind: "key", phase: "down" \| "up", code, physical, shift, ctrl, alt, super, text, repeat, location, caps_lock, num_lock, tag }` | A key press or release on the focused `onKey` sink; `code` is a character or a name (`"left"`, `"f5"`) and is what a keymap binds against. `physical` is the US-QWERTY key at that *position*, spelled the same way — bind it instead when you want the finger rather than the label (WASD stays a square on every layout). `code` follows the layout while the layout speaks ASCII, so a chord lands on the key the user can see (Dvorak's `⌥v` on the key printed V); on a layout that does not (Cyrillic, Greek, Hebrew, Arabic) the position's US key stands in, as Shift prints it (`J`, `:`; unshifted under Alt, as a chord reads it), so a Latin keymap keeps matching instead of matching nothing. A shifted letter arrives as the upper-case letter — `Z` with `shift` set for ⇧⌘Z, `physical` staying `z` — so a keymap that binds letters folds a one-character `code` to lower case under a chord; a headless press is spelled the same way, since no door re-spells it (`"z"` with `shift` is a chord no keyboard produces). `repeat` marks a press the OS auto-repeated; `text` is what the press would insert — always the layout's own character — and is null on every release. A key only comes up where it went down: a release whose press the sink never got is dropped, and focus leaving while a key is held delivers the `up` first, so a held-key binding (WASD, press-and-hold) cannot be left stuck down. `location` says which of a key's twins it was (backlog F108): `"left"` or `"right"` for a modifier, `"numpad"` for the keypad's digits, operators, Enter and (Num Lock off) arrows — `code` still `"1"`, `"enter"` — else `"standard"`; `caps_lock` and `num_lock` what the lock keys held. The keys F13–F35, `printscreen`, `pause`, `menu`, `clear` and the media keys (`mediaplaypause`, `volumeup`, …) are keys like any other; the modifier and lock keys themselves (`shift`, `ctrl`, `alt`, `super`, `capslock`, `numlock`, `scrolllock`) reach only a sink that says `modifierKeys`. |
 | text | `{ kind: "text", text, pasted?: true, concealed?: true, transient?: true, tag }` | Text an IME committed at the end of a composition — or the clipboard's text, when the app asked for a paste with `requestPaste` / `request_paste` / `kui_request_paste` — on the focused `onKey` sink (or the nearest one above the focused control, or the root sink with nothing focused) — the one committed text the platform never reports as a key press carrying `text`, so a custom editor inserts it as it would a key's `text`. Plain typing does not arrive this way: the `key` event already carries what the press would insert, and a sink hearing both would type every character twice. A focused `<edit>` takes the commit itself and reports `changed`. A paste's answer carries `pasted: true` (backlog DX14) — an answer being the host's paste reply, or any commit while a paste is outstanding — so a sink that asked tells the clipboard's text from an IME's commit without keeping its own flag; an IME commit has no `pasted`. It also says what the pasteboard marked it (backlog F84): `concealed: true` for a secret — a password manager's copy, which a view should not show, log or keep — and `transient: true` for text not to keep in a history, after the nspasteboard.org convention (on Windows the clipboard's exclusion formats); a marker that is not set is absent, never false. The runner reads them on macOS and Windows; on Linux, and from a host that answers with a bare commit, a paste arrives unmarked. |
 | preedit | `{ kind: "preedit", text, cursor: [start, end] \| null, tag }` | An in-progress IME composition on the focused `onKey` sink: `text` is the uncommitted string to show inline at the caret, `cursor` the byte range inside it the IME's own caret covers (null when it does not say), and an empty `text` means the composition ended without a commit, so what was shown goes away. The OS candidate window is anchored for you: the `line` carrying `caret` says where. A focused `<edit>` draws the composition itself. |
@@ -204,7 +205,7 @@ one field. The payload shapes:
 | contextmenu | `{ kind: "contextmenu", x, y, tag }` | A secondary-button press on an `onContextMenu` node, on the press rather than the release; `x`/`y` are logical viewport coordinates — where the menu goes. The core opens nothing: the app declares the menu (a `modal` float) and stops declaring it on `dismiss`. |
 | menu | `{ kind: "menu", role, item }` | A row of the core's own context menu was chosen (`openMenu` / `open_menu` / `kui_open_menu`), on the node the menu was about. `item` is the row's `id`, or its label when it declared none; `role` is the row's standard role or `custom`. Every chosen row posts, the standard ones included: a `cut` or `paste` role is carried out by the core (its clipboard work queued for the host) *and* reported, so an app can hear its editor being cut from and is free to ignore it (`docs/adr/0017-selection-as-a-scope.md`, decision 5). |
 | forceclick | `{ kind: "forceclick", x, y, tag }` | A press that deepened past the second stage of a Force Touch trackpad, on an `onForceClick` node, at the logical viewport point it happened at. Routed as a secondary press is — no focus moved, no caret placed, no click — but asked of the topmost node only, and the ordinary click the press is still producing arrives afterwards. Text needs none of this: over an `edit` or a `selectable` scope the core selects the word under it and asks the host for its Look Up panel instead. macOS-only in practice. |
-| button | `{ kind: "button", phase: "press" \| "move" \| "release", button: "secondary" \| "middle" \| number, x, y, clicks, cell?: { row, col }, line?, byte?, tag }` | A non-primary button on an `onButton` node that claims it (`buttons`), backlog F105: `press` where it went down — with the driver's click count, `clicks`, which the native runner keeps for the primary button alone and so always reports as 1 here — then `move` for every pointer move while it is held and `release` where it came up, both on the same node wherever the pointer went, since the press captured the button. `button` is the button's name, or for one past the middle button its number (`3 + n`, as `kui_input_mouse_button` takes it; Node's `ctx.mouse` takes the three names only); `x`/`y` are logical viewport coordinates. On a `cells` grid each carries `cell: {row, col}`, clamped to the grid, and inside an `onKey` sink that draws `role="line"` rows `line` and `byte` as a drag does. A claimed secondary press is this event instead of `contextmenu`; the press moves no focus, caret, selection or scrollbar. |
+| button | `{ kind: "button", phase: "press" \| "move" \| "release", button: "secondary" \| "middle" \| number, x, y, clicks, cell?: { row, col }, line?, byte?, inside?, tag }` | A non-primary button on an `onButton` node that claims it (`buttons`), backlog F105: `press` where it went down — with the driver's click count, `clicks`, which the native runner keeps for the primary button alone and so always reports as 1 here — then `move` for every pointer move while it is held and `release` where it came up, both on the same node wherever the pointer went, since the press captured the button. `button` is the button's name, or for one past the middle button its number (`3 + n`, as `kui_input_mouse_button` takes it; Node's `ctx.mouse` takes the three names only); `x`/`y` are logical viewport coordinates. On a `cells` grid each carries `cell: {row, col}`, clamped to the grid, and inside an `onKey` sink that draws `role="line"` rows `line`, `byte` and `inside` as a drag does. A claimed secondary press is this event instead of `contextmenu`; the press moves no focus, caret, selection or scrollbar. |
 | scroll | `{ kind: "scroll", x, y, dx, dy, lines, mods?: { shift, ctrl, alt, super }, tag }` | The wheel over an `onScroll` node, or a drag-select held past a `cells` grid's top or bottom edge: `dx`/`dy` the delta in logical px as the driver reported it (positive `dy` is the wheel rolling up, toward earlier content), `x`/`y` the pointer in logical viewport coordinates, `lines` the whole lines a `cells` grid's `dy` covers — positive is later history, the sign `originLine` grows in, the fraction carried to the next notch — and null on any other node. The core scrolls nothing for it: the app re-declares the grid's `originLine`, or zooms its canvas. From the edge drag it comes once a frame while the pointer is held past the edge, with the lines that frame's step covers, and the selection's absolute lines survive the scroll the app answers with (`docs/adr/0029-a-selection-follows-the-pointer-past-the-edge.md`). |
 | focus | `{ kind: "focus", phase: "in" \| "out", by: "pointer" \| "keyboard" \| "assistive" \| "program", tag }` | Keyboard focus entered or left an `onFocus` node's subtree (backlog DX18). `by` is what moved it — a press, a key, a screen reader's request, or the view and the app — so a pane that follows a click into its sink tells that apart from a move the app made itself. |
 | hover | `{ kind: "hover", phase: "enter" \| "leave", by: "pointer" \| "content", tag }` | The pointer entered or left an `onHover` node — also when a new frame moved it under a still cursor. `by` says which (backlog DX20): `pointer` when the pointer moved or left the window, `content` when it stayed and what is under it changed — a list scrolled by the wheel or the keys, a row that grew, a float that opened. A picker whose selection follows the pointer ignores `content`, or the rows sliding under a still pointer as the keys scroll the list drag the selection with them. |
@@ -219,6 +220,7 @@ one field. The payload shapes:
 | modifiers | `{ kind: "modifiers", shift, ctrl, alt, super }` | The physical modifier state changed (delivered to the host on the root). |
 | changed | `{ kind: "changed" }`, with the editor's key on the event | An editor's text changed. |
 | submit | `{ kind: "submit" }`, with the editor's key on the event | Enter in a single-line editor. |
+| boundary | `{ kind: "boundary", key: "up" \| "down" \| "left" \| "right" \| "backspace" \| "delete", edge: "start" \| "end", word, doc }`, with the editor's key on the event | An editing key that met the edge of an editor's text and did nothing: ↑ on the first line, ← or Backspace at the start (`edge: "start"`), ↓ on the last line, → or Delete at the end (`"end"`) — from a caret with no selection and without Shift. What a block editor joins blocks and moves between fields by. A field has one line, so its ↑ and ↓ always report. `word` and `doc` are the editing modifiers the key carried (Option or Ctrl, ⌘ or Ctrl — `docs/adr/0002`). |
 | sound | `{ kind: "sound", phase: "ended" \| "refused", playback, tag }` | A tagged playback (`play(id, { tag })` or `<audio tag>`) finished on its own — never when something stopped it. `phase: "refused"` instead when the device would not take the play at all (its 128 voices are all held, or the sound did not decode): that playback never starts and so never ends, so this is what arrives in place of the `ended` a view would otherwise wait forever for. |
 | dismiss | `{ kind: "dismiss", reason: "escape" \| "outside", tag }` on a node; `{ kind: "dismiss", reason, name, id }` on the root for a popup window | The user asked for a surface to go away — Escape, or a press that landed outside it. The core closes nothing: the app stops declaring the surface (or asks first). A `modal` node gets one on the node, carrying its tag, and only the modal in effect does; a `kind: "popup"` window gets one on the root, carrying the window's `name` and `id`, reported by the driver because a press outside a window and a key sent to a non-activating one are both facts only the OS has. The two are the same event, so a dropdown that graduates from a modal float to a popup window changes its declaration and not its handler. |
 | access | `{ kind: "access", action, tag, text?, value?, anchor?: { line, offset }, focus?: { line, offset } }` | Assistive technology — or the keyboard — asked for what only the app can do: `increment` / `decrement` on a `slider` role that declared no `onChange` (a reader's nudge, or the arrow keys on the focused slider), and `setValue` there with the number asked for as `value` (Windows' UI Automation sets a slider rather than nudging it); `setValue` / `replaceSelectedText` (with `text`) / `setTextSelection` (with `anchor` and `focus` as line ordinals and byte offsets) on a custom editor. `tag` is the node's `onClick` payload (or its `onDrag` / `onKey` tag). Every other request resolves in the core and arrives as the events a pointer would have produced. |