@qxuken/kui 0.1.0-alpha.42 → 0.1.0-alpha.44

package/CHANGELOG.md

@@ -21,6 +21,426 @@ 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.44 (2026-10-08)
+
+**What breaks.**
+
+- A menu row wider than the window — a recent file's path, a long
+  `<select>` option — draws its label cut short with "…" in a menu as
+  wide as the window less 8 px a side (and never narrower than the
+  metric's menu width, 200 px), where the menu ran off the edge (under
+  Fixed, RG150).
+- With a frame clock (every runner sets one), moving the pointer from an
+  open submenu's row to another row of its menu switches after 0.3 s of
+  rest there, not at once (under Fixed, RG150). A driver that sets no
+  clock switches at once, as before.
+- A `<select>` option given `items` (or a C `KuiMenuItem` with
+  `submenu`) opens no submenu: the rows are dropped, with an
+  `unknown-prop` warning in Node and Lua (under Fixed, RG150).
+- Windows: a `Blur` or `Tinted` window whose environment presents through
+  the window's handle (`WGPU_DX12_PRESENTATION_SYSTEM=hwnd`) or names no
+  D3D12 in `WGPU_BACKEND` draws the wallpaper kui reads and reports
+  `Tinted` (or `Opaque`), where it was translucent over black and
+  reported `Blur`; a transparent window whose `WGPU_BACKEND` lists D3D12
+  among others opens D3D12 alone (under Fixed, RG150).
+- Windows and Linux: a `Blur` or `Tinted` window on a desktop with no
+  wallpaper kui can read (a solid colour, a file it cannot decode) reads
+  `Tinted` for its first frame or frames and `Opaque` once the loader's
+  thread has answered, where alpha.43 read the path on the event loop
+  and said `Opaque` from the first frame (under Fixed, RG150). A view
+  that branches on the backdrop sees it change once, early.
+- An image or a fragment that declares `border` draws it, as a ring over
+  the content, where it drew none (under Fixed, RG152): an app that
+  kept the `border` and drew its own ring around the picture draws two.
+
+### Added
+
+- `MenuItem::stray_keys`, `MenuItem::stray_option_keys` and
+  `MenuBar::stray_keys`: the keys of plain-data menu rows no row reads,
+  a submenu's rows' included, for a binding to warn about (backlog
+  RG150).
+- `kui_wgpu::see_through_by_visual` (and `_with`, its pure form): whether
+  a Windows window can be seen through, by the environment wgpu reads —
+  the one answer the window's surface and the swapchain both take
+  (backlog RG150).
+
+### Fixed
+
+- **A menu has a width ceiling** (backlog RG150, from alpha.43's pre-tag
+  pass). F127 made a menu as wide as its widest row, with nothing above
+  it: a long path or `<select>` option ran the panel and its
+  accelerators off a narrow window. A menu is now never wider than the
+  window less 8 px a side (a narrower ceiling the caller declared in px
+  stands; the metric's menu width is the floor), and a row's label is
+  bounded by what its accelerator leaves it and ends in "…".
+- **A submenu survives the pointer passing over a row on its way in**
+  (backlog RG150). A diagonal path from a row to a lower row of its
+  submenu crosses the rows below it, and each one closed the submenu. A
+  row that would close one now waits 0.3 s of rest on the frame clock,
+  and moving into the submenu cancels it; the frames for the wait are
+  owed. And a submenu the keyboard closed opens again when the pointer
+  leaves the menu and comes back to its row.
+- **A stray key inside a submenu warns** (backlog RG150). Only a select's
+  top-level options were checked, so `{ label, disabled: true }` inside a
+  submenu was silently an enabled row; Node's `openMenu` and `<menuBar>`
+  and Lua's `open_menu` and `menu_bar` now warn for every level.
+- **The backdrop blur's scratch is the size of what it blurs** (backlog
+  RG150). Four surface-sized textures, cleared and stored by every pass,
+  were ~236 MB at 5K and three full-surface stores per blurred node, and
+  were kept by a window gone idle. The scratch is now the largest
+  region's, its passes load rather than clear, the composite rides in the
+  pass that follows, and the first frame without a blur drops it all:
+  65.5 MB → 16.8 MB and ~230 → ~150 µs a frame at 2560×1600 for one
+  toolbar, the output bit-identical.
+- **Windows: one answer for the window's surface and the swapchain**
+  (backlog RG150). `WGPU_BACKEND` decided the first and
+  `WGPU_DX12_PRESENTATION_SYSTEM` the second, so `WGPU_BACKEND=dx12` drew
+  translucency over black while the window reported `Blur`. Compiled and
+  read, not run.
+- **Linux: the wallpaper is found off the event loop** (backlog RG150):
+  up to three `gsettings` runs at window creation on GNOME before the
+  window showed; and Wayland's blur managers are bound once per process,
+  not once per window and never released. A window with no wallpaper to
+  read is `Tinted` until the thread answers, within its first frames,
+  and `Opaque` from then on (see What breaks). Compiled and read, not
+  run; the Linux half built and smoked under WSLg's X11 in the pre-tag
+  pass.
+
+- **A box that becomes a float keeps a float it held above it** (backlog
+  RG151, from berainder). The float stack kept last frame's floats in
+  their order and put a new one on top, so a box that kept its key while
+  turning into a float went over the float inside it: a debug build
+  panicked on the stack's own assertion, a release build painted and hit
+  the inner float under its parent. A float found below the one it is in
+  now moves to just above it.
+- **`border` on an image draws** (backlog RG152, from berainder). The
+  border was painted with the background, under the picture, which
+  covered it; on an image or a fragment it is now a ring over the
+  content, as over a gradient. And an image with a `gradient` and a
+  `border` no longer carries an empty quad where the gradient's own
+  ring went (from the alpha.44 pre-tag pass).
+- **The float stack keeps the order of two floats a box held, and
+  sorts a float moved into one** (backlog RG153, from the alpha.44
+  pre-tag pass). RG151's move put each held float just above the box in
+  turn, so of two — a name panel and a tip opened over it — the first
+  came out on top; and a float that moves into another float under a
+  key the app keeps (`open_key`, `leaf_key`) changed no rank, so the
+  steady path kept it under the float it is now in and the debug
+  assertion tripped by RG151's other road. A held float now waits for
+  the float it is in and goes just above it, in the order it had; and
+  the steady order is checked for nesting and rebuilt when it fails.
+
+**What you can delete.**
+
+- An app's own truncation of menu labels to keep a menu on screen
+  (RG150).
+- A key of its own for a box on each side of becoming a float — the
+  card behind and the card on top — kept only to stop a float inside it
+  falling under it (RG151), or to keep two floats inside it in the order
+  they opened (RG153).
+- A padded box around an image to draw its border (RG152).
+
+### Native verification
+
+The by-hand round alpha.6 introduced (backlog R4), on 2026-10-08, over
+RG150 from alpha.43's pre-tag pass and berainder's RG151 and RG152, with
+alpha.44's pre-tag pass over them on the Windows machine and under WSLg:
+the mechanical round on both, then three read-only reviews of the diff
+since alpha.43 (the menus; the backdrop and the blur, read against
+wgpu's and wayland-client's sources; the floats, the image border and
+the docs), each claim probed. They filed RG153, built before the tag
+(the float stack reversing two floats a box held, and keeping a float
+moved into another under a kept key below it), and RG154, open; and the
+round itself caught F127's width test failing on both platforms under
+RG150's ceiling (its accelerator is a word each there, wider than the
+test's window).
+
+**Windows**, the pre-tag pass. fmt and clippy are clean; `nu
+scripts/test.nu --node`: **2144 tests over 143 suites**, 0 failed. The C round passes (6 checks), and so do the **57 scenes**
+through Rust, Lua, C, Node and Odin; the Odin binding's four steps with
+CI's pinned `dev-2026-09`; Node's tests under
+`KUI_CONFORMANCE_REQUIRED=1` (**218 of 219**, the one skip Windows'),
+`npm run gen` with no diff, the examples' typecheck, the headless round
+(37 drives) and the book's listing. The windowed round with Node's:
+**53 examples on both bases**, every one clean on a first run; `counter`
+and `host` opened by hand after `cbuild`. The bench guard against the
+alpha.43 tag: **green**, the guarded rows −5.9% to +3.6%
+(`frame_10k_rects_with_access_tree`; `frame_10k_rects` itself −5.9%),
+the worst run-to-run spread on a guarded row 5.4%.
+
+**Linux**, under WSLg (llvmpipe), the same commit with the pass's
+fixes: fmt and clippy clean; `cargo test --workspace`: **1921 tests
+over 142 suites**, 0 failed; the C round (5 checks) and the 57 scenes
+through every adapter, the Odin binding's four steps, Node **219 of
+219** with the corpus required, gen clean, the typecheck, the headless
+round. The windowed round under X11 with Node's: 53 examples on both
+bases; eight windows of a first run four at a time died with
+"X connection to :0 broken" — XWayland's, twice — and the four
+examples drew every frame run again one at a time. Nothing opened a
+Wayland window (Weston's decorations crash under winit here) and
+nothing read a wallpaper: F126's Linux half is still compiled and read,
+not met on KDE or GNOME. No Mac ran this round: the AX audit and the
+macOS halves of RG150 are CI's check and the next Mac round's.
+
+## 0.1.0-alpha.43 (2026-10-08)
+
+**What breaks.**
+
+- The drawn menu — a context menu, a select's list, a drawn menu bar's
+  dropdown — is as wide as its widest row needs, where it was always
+  `Metrics::menu_width` (now its floor), and no row's label or
+  accelerator wraps (under Fixed, F127).
+- A menu's accelerator kui can parse is drawn, and read back through
+  `Core::menu` / Node's `menu()` / C's `kui_menu_item`, in the platform's
+  spelling: `"mod+shift+n"` is `⇧⌘N` or `Ctrl+Shift+N`, where it was the
+  string as declared — as the menu bar's already was (under Fixed,
+  F127).
+- Rust: `MenuItem` gains `submenu` (under Added, F128), so a struct
+  literal of one needs the field; `MenuItem::KEYS` is seven keys, with
+  `items`, where it was six.
+- Rust: `WindowEnv` gains `backdrop` (under Added, F126), so a struct
+  literal of one needs the field or `..Default::default()`; so does
+  `kui_devtools::Window`, in the examples' harness.
+- Rust: `QuadKind` gains `Backdrop` (under Added, F129), so a `match` on
+  a quad's kind needs the arm — a renderer of its own draws nothing for
+  it; `InteractSpec` and `NodeInfo` gain `backdrop_blur`, for a struct
+  literal of either. The conformance report's `kinds` line has a tenth
+  column, `backdrop`.
+- C: ABI 26. `KuiSpec` appends `backdrop_blur` (into the tail padding:
+  the 64-bit size stays 704), `KuiMenuItem` appends `submenu` and
+  `submenu_count` (an array element, so its stride moved, to 72), and
+  `KuiRunConfig` appends `backdrop` (44). `KUI_QUAD_BACKDROP` is a new
+  quad kind. `KuiSpan` appends `family`, `size` and `font` (an array
+  element, so its stride moved, to 56), with the `KUI_SPAN_FAMILY` flag
+  (under Added, F130). Recompile; a zeroed tail is what every spec, row,
+  span and config had.
+- Rust: `text::Span` gains `family` and `size` (under Added, F130), for a
+  struct literal of one; `Span::new` and the builders are unchanged.
+- Node: the wire is v22 — a span carries its face and size after its
+  background's radius — so the addon and the package go together, as
+  every wire step has.
+- `Accel::parse` reads a named key's label as that key: `"⌘⌫"` is ⌘
+  Backspace and `"Ctrl+Page Up"` parses, where the first was the
+  character `⌫` and the second nothing (under Fixed, RG146).
+- A host's report of a dead menu row — `Core::activate_menu_bar_item` /
+  `_path`, Node's `activateMenuBarItem`, C's `kui_activate_menu_bar_*`,
+  or a row under a dead submenu row through `activate_menu_path` — is
+  refused and posts nothing, where it was performed (under Fixed,
+  RG147).
+
+`backdropBlur` is a number row like any other, and a row's `items` rides
+in the JSON a row already was.
+
+### Added
+
+- **A window with the desktop behind it** (backlog F126, from Noticon,
+  for a sidebar like an Obsidian theme's on a Mac).
+  `Launcher::backdrop(Backdrop)` — `backdrop` in Node's window options —
+  asks for what shows through the app's windows, named for the effect:
+  `Transparent` (the desktop as it is), `Blur` (a live blur of what is
+  behind the window) or `Tinted` (the desktop's colour, steady). Which
+  regions show it is the app's, by painting them with alpha and the rest
+  opaque. macOS: an `NSVisualEffectView` under the content view, blending
+  behind the window and dimmed with it in the background — the sidebar
+  material for `Blur`, the window-background one for `Tinted`. Windows 11
+  22H2 and later: Acrylic for `Blur`, Mica for `Tinted`
+  (`DWMWA_SYSTEMBACKDROP_TYPE`, the frame extended under the client
+  area), the window without a GDI surface and the device presenting D3D12
+  through DirectComposition (`kui_wgpu::GpuOptions::transparent`,
+  `Renderer::new_with` / `new_in_with`). Linux: `Blur` asked of the
+  compositor — `ext-background-effect-v1` where it is advertised with
+  blur, KWin's `org_kde_kwin_blur`, `_KDE_NET_WM_BLUR_BEHIND_REGION` under
+  X11. Where the OS has no effect to give — GNOME, other Linux, Windows
+  10 — `Blur` and `Tinted` draw the desktop's wallpaper (GNOME's
+  `picture-uri`, Plasma's config, `SPI_GETDESKWALLPAPER`), read on a
+  thread, scaled down and blurred once and cached by path and modification
+  time, as the window's ground under the frame
+  (`Renderer::set_ground` / `set_ground_uv`), aligned to where the window
+  sits on its monitor (centred on Wayland), and report `Tinted`; with no
+  wallpaper, `Opaque`. Where the OS draws the effect the frame is cleared
+  to nothing rather than to the theme's `bg`, and glyphs are grayscale
+  under `TextAa::Auto`. What the window got is `env.window.backdrop`
+  (`window.backdrop` in Node and Lua, `kui_env_set_backdrop` for a C host
+  that makes its own), so a view paints opaque when it says `Opaque`.
+  Every window of the app takes it but a popup and the devtools' own; an
+  app that does not ask opens exactly the window and the swapchain it
+  always did. `KUI_BACKDROP_EMULATE=1` draws the wallpaper for `Blur` and
+  `Tinted` on Windows and Linux, to look at it (macOS reads no wallpaper,
+  so a window there reads `Opaque`). Seen in windows on Windows 11:
+  Acrylic blurring a red window behind the translucent region, Mica, the
+  bare desktop through `Transparent`, the wallpaper drawn by kui under
+  `KUI_BACKDROP_EMULATE`, and an opaque devtools window beside them; on
+  WSLg (Wayland, no blur protocol, no gsettings) a `Blur` reading
+  `Opaque`. On a Mac, built through Noticon, the library column shows the
+  vibrancy. No KDE or GNOME session was at hand: the Linux half compiles
+  and passes clippy there, untried on either desktop. C asks with
+  `KuiRunConfig.backdrop` (a `KUI_BACKDROP_*`) and a view reads what the
+  window got with `kui_ctx_backdrop`, the answer and not the ask; Odin's
+  `Run_Config.backdrop` and `kui.ctx_backdrop`. The `backdrop` example
+  paints a translucent library and an opaque page from the reading.
+  *What you can delete:* nothing — this is new.
+- **A node blurs what is drawn beneath it** (backlog F129, from Noticon,
+  for a frosted toolbar over a scrolling note): CSS's `backdrop-filter:
+  blur()`. `NodeSpec::backdrop_blur(radius)` — `backdropBlur` in JSX,
+  `backdrop_blur` in Lua and Odin, `KuiSpec.backdrop_blur` in C — blurs
+  everything painted before the node, inside its rounded box, by that
+  radius in logical px (the Gaussian's standard deviation, as CSS's):
+  the ancestors' backgrounds, the siblings and the content scrolling
+  under it, and the window's backdrop where it has one. The node's own
+  `bg`, border and children paint over the blur, so a translucent `bg`
+  is frosted glass; it is clipped as the node is and faded by its
+  `opacity`. The core emits a `QuadKind::Backdrop` quad
+  (`KUI_QUAD_BACKDROP`) just before the node's own paint, carrying the
+  shape, the clip, the radius in physical px and the group opacity.
+  kui-wgpu draws a frame that has one into an offscreen copy of the
+  surface, breaks the pass at each, copies out the region under the node
+  plus three radii around it, averages it down by a power of two that
+  leaves a kernel of two to four texels, blurs it along each axis, and
+  writes it back inside the node's rounded rect and its clip, mixing by
+  coverage and opacity with blending off so a transparent window stays
+  premultiplied; then blits the frame to the surface. A frame without
+  one is drawn exactly as before, and the offscreen textures go after
+  120 frames without one. A renderer that cannot read back what it drew
+  draws nothing for the quad, which leaves the node over an unblurred
+  backdrop; a headless core has the quad in its display list and no
+  pixels. `diag::BACKDROP_BLUR_HIDDEN` warns of one under an opaque `bg`
+  of its own, which hides all of it. The devtools inspector and
+  `Core::nodes` (`backdropBlur` in Node) read the radius. Seen on Windows
+  11 in the new `backdrop_blur` example, in an opaque window and over
+  Acrylic: the cards under the toolbar smeared, the edge below it sharp,
+  the badge's blur inside its corners. *What you can delete:* a
+  toolbar's opaque fill over content that scrolls under it.
+- **Submenus** (backlog F128, from Noticon, for "Move to ▸" and "Sort by
+  ▸"). `MenuItem::submenu(label, rows)` — `items` on a row in Node and
+  Lua, read by the one row parser — is a row with a chevron that opens
+  its rows in a menu beside it: when the pointer rests on it, on a click,
+  on Enter or the Right arrow (focus on its first row). Left or Escape
+  closes it, focus back on its row, and Escape again closes the menu.
+  They nest, in the context menu, a select's list and the drawn menu
+  bar's menus alike, and a chosen row inside posts its own `{kind:"menu",
+  role, item}` on the node the menu is about, as any row does; the row
+  that opens one is never chosen. On macOS the context menu and the menu
+  bar build an `NSMenu` submenu, which AppKit opens itself, and report a
+  row inside by its path. A host showing menus itself reports one with
+  `Core::activate_menu_path` / `activate_menu_bar_path` (Node
+  `activateMenuPath` / `activateMenuBarPath`); `menu()` reads a row's
+  `items` back. `Core::menu_submenus` / `menu_bar_submenus` say what is
+  open. The pointer opens and closes on a change of row, with no timer,
+  so a pointer resting on one row does not undo what the keyboard opened.
+  In C a row's `submenu` / `submenu_count` (ABI 26) nest the same
+  `KuiMenuItem`s, in `kui_open_menu`, `kui_select` and `kui_menu_bar`; a
+  row's flags carry `KUI_MENU_ITEM_SUBMENU`, and a host showing its own
+  menus reads and reports a row inside by its path —
+  `kui_menu_submenu_count` / `kui_menu_item_path` /
+  `kui_activate_menu_path`, and the bar's `kui_menu_bar_submenu_count` /
+  `kui_menu_bar_item_path` / `kui_activate_menu_bar_path`; Odin's
+  `Menu_Item.submenu` and the same doors. A C menu nested past 32 levels
+  — a row that is its own submenu — is refused, as an unknown role is.
+  *What you can delete:* a list cut short because a menu could not
+  nest — Noticon's `MOVE_TARGETS` cap on the folders a note can move to.
+
+- **A span in a face and a size of its own** (backlog F130, from
+  Noticon, whose inline `code` was drawn in the body face with a wash).
+  `Span::family(FontFamily)` / `Span::mono()` and `Span::size(px)` —
+  `family`, `font` and `size` on a JSX `<span>` and in a Lua span table,
+  `KuiSpan.family` (with `KUI_SPAN_FAMILY`), `.font` and `.size` in C,
+  the same fields on Odin's `Span`. The paragraph still shapes as one
+  flow; each span's glyphs are shaped in its face, at that family's
+  weights, so a caret, a hit, a selection and the measurement read the
+  glyphs that are drawn and byte positions stay exact across a change of
+  face mid-line. A sized span's line height scales at the paragraph's
+  ratio, a line is as tall as its tallest span (every span then carries
+  its metrics, so a line of only smaller ones never comes out shorter),
+  measurement sums the lines' own heights, a selection and a caret are
+  their line's height, and a span's background is its own height around
+  its glyphs rather than the line's. A paragraph with a sized span is
+  shaped whole, never chunked as a long line. Pinned by
+  `tests/span_face.rs` (the mono width, carets and hits across the
+  change, line heights, the caret, the wash), Node's `a span takes a face
+  and a size of its own`, and the corpus's first scene, which gained a
+  mono span and a sized one in all five adapters; the `text` example
+  shows inline code and a larger word. *What you can delete:* inline code
+  drawn in the body face, or as a box beside the text.
+
+### Fixed
+
+- **A menu's accelerator reads as the platform writes it** (backlog
+  F127, from Noticon). `MenuItem::accel` drew its string verbatim in a
+  context menu, so a row declared with the portable `"mod+shift+n"` —
+  the spelling the docs give for a menu bar, where it was already
+  rewritten — showed those eleven characters. `open_menu` now rewrites
+  an accelerator it can parse into `Accel::display`'s spelling, as
+  `declare_menu_bar` does, and the drawn rows read every accelerator
+  through `Accel::label`, so a menu an app draws itself with
+  `widgets::context_menu` gets the same. A spelling kui cannot parse
+  (`"gd"`) is still drawn exactly as written. `MenuItem::accel_label`
+  is the drawn string; `accel_text` stays the declared one. *What you
+  can delete:* the `Accel::parse(..).display()` an app ran over its own
+  accelerators before handing them to a menu.
+- **A menu is as wide as its rows** (backlog F127). The panel was the
+  metric's 200 px whatever it held, so a long label beside a long
+  accelerator wrapped one of them onto a second line. It is now as wide
+  as its widest label plus its widest accelerator, with at least
+  `widgets::MENU_ACCEL_GAP` between them, and never narrower than
+  `Metrics::menu_width`; labels and accelerators are one line each.
+- **`scripts/npm-approve.nu` takes the version as npm spells it.**
+  Approving alpha.42 as `nu scripts/npm-approve.nu
+  @qxuken/kui@0.1.0-alpha.42` looked for a stage whose version was the
+  whole spec, found none, and said "nothing staged for
+  @qxuken/kui@@qxuken/kui@0.1.0-alpha.42" while the stage sat there. The
+  package prefix is cut off now, and a spec naming another package is
+  refused by name. A release script, so nothing an app sees.
+- **A macOS menu shortcut on a named key works** (backlog RG146). The
+  bar (since alpha.11) and now the context menu build each item's key
+  equivalent from the accelerator in the platform's spelling, and
+  `Accel::parse` read `⌘⌫`'s `⌫` as a character: AppKit drew ⌘⌫ beside
+  the row and the chord did nothing, as with ⌘↩, ⌘← and every named
+  key. `parse` now reads a key as `Accel::display` writes it, in either
+  platform's spelling.
+- **A dead menu row cannot be chosen by reporting it** (backlog RG147).
+  The bar's activate doors performed a disabled row, or one in a
+  disabled menu — kui.h said they refused it — and `activate_menu_path`
+  a row under a disabled submenu row. Every row on the path must be
+  enabled now, as the drawn menus need.
+
+**What you can delete.**
+
+- The `Accel::parse(..).display()` an app ran over its accelerators
+  before handing them to a context menu (F127).
+- A menu cut short, or flattened, because menus could not nest: "Move to
+  …" rows one per folder up to a cap (F128).
+- A toolbar's opaque fill over content that scrolls under it (F129).
+- Inline code drawn in the body face, or as a box beside the text (F130).
+
+### Native verification
+
+The by-hand round alpha.6 introduced (backlog R4), on 2026-10-08, over
+F126–F130 from the Noticon wish list, with alpha.43's pre-tag pass over
+them on the Mac: the mechanical round, then three read-only reviews of
+the diff since alpha.42 (the window backdrop and the blur; the menus and
+the span's face; the docs), each claim probed. They filed RG146–RG149,
+built before the tag (a macOS menu shortcut on a named key binding no
+key, a host's report of a dead menu row performed, an Escape spent on a
+submenu an app-drawn menu had noted, a Node span's family losing to an
+inherited font handle), and RG150, open.
+
+**macOS**, the pre-tag pass. fmt and clippy are clean; `nu
+scripts/test.nu`: **1911 tests over 142 suites**, 0 failed. The C round
+passes, and so do the **57 scenes**; Node's tests under
+`KUI_CONFORMANCE_REQUIRED=1` (**218 of 218**), `npm run gen` with no
+diff, the examples' typecheck, the headless round (with `backdrop_blur`'s
+drive, which the roster had left out) and the book. The windowed round
+with Node's: **128 windows** (one `transition` window hung at the
+timeout on a first run four at a time and drew on eight runs alone and a
+whole second round). The AX audit: **106/106**. The bench guard against the alpha.42 tag:
+**green**, the guarded rows −0.4 to +3.1% (`deep_nesting_64_levels`,
+−2.1% on a second run); the stream, long-line and cell grid rows flat.
+The Odin
+binding's four steps did not run here — the machine's `odin` links an
+`llvm@22` no longer installed — so CI's check on the tag is their run.
+F126's macOS half and F128's macOS menus were compiled and run on a Mac
+the day they were built, through Noticon; F126 has not met KDE or GNOME.
+
 ## 0.1.0-alpha.42 (2026-10-07)
 
 **What breaks.**

package/docs/adr/0007-composite-keyboard-patterns.md

@@ -331,7 +331,14 @@ derived orientation are the whole surface.
   decision 5's warning is where an app feels the missing semantic half.
 - **Submenus.** Left / Right in a `menu` should close and open them. kui
   has no submenu relation (a `menu` inside a `menuItem`), so today those
-  arrows step like any other menu's.
+  arrows step like any other menu's. *Built 2026-10-08 for the core's own
+  menus (backlog F128):* Right on a row with a submenu opens it with focus
+  on its first row, Left inside one closes it with focus back on its row,
+  and Escape closes the innermost before the menu. The relation is the
+  core's state rather than a derived one — a submenu's panel is a `menu`
+  beside its row, not inside the `menuItem` (which is named from its
+  content), and the item walk already stops at a nested `menu` — so an
+  app's own `menu` composites step on Left / Right as before.
 - **`radio-without-group`.** A lone `radio` is invalid ARIA and now also
   means "no arrows here". A warning in the shape of `control-without-name`
   once something in the repo declares radios — the fixture will, so this

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

@@ -189,6 +189,16 @@ does. An app that has to write the menu twice has not been given a menu.
   something wants one, it wants it in the context menu too, and that is one
   change to `MenuItem` rather than two features.
 
+  *Amended 2026-10-08 (backlog F128).* Something wanted one — Noticon's
+  "Move to ▸" and "Sort by ▸", in the context menu first — and it was that
+  one change: `MenuItem::submenu` (`items` in plain data, so every
+  binding's one parser reads it), drawn by the same `menu_panel` beside
+  its row, in the context menu and the drawn bar alike, and an `NSMenu`
+  submenu where the platform draws them. `BarMenu` is still one level;
+  its rows nest. There is no hover timer: the core opens or closes on a
+  *change* of hovered row, which is what keeps a pointer resting on one
+  row from undoing what the keyboard just opened.
+
 - **Standard application-menu roles** (`about`, `quit`, `services`, and
   macOS's `NSApplication` responders). They change what an item *is* — one
   the platform performs rather than one the app hears — so they need their

package/docs/adr/0023-layers-stack-in-the-order-they-open.md

@@ -180,10 +180,17 @@ and none of which the tree order gives:
   declares it under a fresh key. This is the only "raise" and it is not a
   row; see *What was declined*.
 
-A nested float is above its enclosing float without a rule: it opened
-the same frame (appended after its parent, in tree order) or a later one
-(appended above). The key scheme means the reverse cannot happen, and a
-`debug_assert` says so where the stack is rebuilt.
+A nested float is above its enclosing float, and almost always without a
+rule: it opened the same frame (appended after its parent, in tree
+order) or a later one (appended above), and a key derived from its
+parent's cannot have been opened first. Two roads reach the reverse,
+both under a key the app keeps across the change (backlog RG151 and
+RG153, 2026-10-08): a box that becomes a float around a float it already
+held — the box is new to the stack and the held float is not — and a
+float that moves into another float under `open_key`, which changes no
+rank. So the rebuild places each float after the float it is in, the
+held ones in the order they had, and the steady order is checked for the
+same and rebuilt when it fails. A `debug_assert` says the result holds.
 
 The steady state — the same float roots as last frame — is one
 comparison of two short key lists and costs nothing more; the first

package/encoder.js

@@ -735,6 +735,8 @@ export function createEncoder(P) {
   // dotted (v13, backlog K4). A span's own underline colour and style
   // beat the enclosing span's; either implies the underline. Then the
   // background's radius (v17, backlog F101), 0 for a square one; a span's
+  // own beats the enclosing span's. Then the span's own face — `family`
+  // by name, `font` by handle, which wins — and `size` (v22); a span's
   // own beats the enclosing span's.
   function collectSpans(node, st, out) {
     if (node == null || typeof node === 'boolean') return;
@@ -752,7 +754,7 @@ export function createEncoder(P) {
         (st.ul?.ref ? 512 : 0) |
         (st.ulStyle === 'wavy' ? 1024 : 0) |
         (st.ulStyle === 'dotted' ? 2048 : 0);
-      out.push([String(node), flags, st.color?.v ?? 0, st.bg?.v ?? 0, st.ul?.v ?? 0, st.bgRadius ?? 0]);
+      out.push([String(node), flags, st.color?.v ?? 0, st.bg?.v ?? 0, st.ul?.v ?? 0, st.bgRadius ?? 0, st.family ?? null, st.font ?? null, st.size ?? 0]);
       return;
     }
     if (Array.isArray(node)) {
@@ -767,6 +769,12 @@ export function createEncoder(P) {
     if (p.bgRadius != null && !(typeof p.bgRadius === 'number' && p.bgRadius >= 0)) {
       throw new Error(`bad bgRadius ${JSON.stringify(p.bgRadius)} on <span> (a number of logical px, 0 or more)`);
     }
+    if (p.family != null && typeof p.family !== 'string') {
+      throw new Error(`bad family ${JSON.stringify(p.family)} on <span> (sans, serif, mono or an installed family's name)`);
+    }
+    if (p.size != null && !(typeof p.size === 'number' && p.size > 0)) {
+      throw new Error(`bad size ${JSON.stringify(p.size)} on <span> (a number of logical px, above 0)`);
+    }
     collectSpans(
       node.children,
       {
@@ -779,6 +787,11 @@ export function createEncoder(P) {
         ul: spanColor(p.underlineColor, st.ul),
         ulStyle: p.underlineStyle ?? st.ulStyle,
         bgRadius: p.bgRadius ?? st.bgRadius,
+        family: p.family ?? st.family,
+        // A span naming a family drops the handle it inherited, which
+        // would otherwise win over it.
+        font: p.font != null ? String(p.font) : p.family != null ? null : st.font,
+        size: p.size ?? st.size,
       },
       out,
     );
@@ -829,15 +842,18 @@ export function createEncoder(P) {
           collectSpans(el.children, {}, spans);
           f[fi++] = OP.richText;
           props(p, null, false);
-          reserve(8 + spans.length * 8);
+          reserve(8 + spans.length * 14);
           f[fi++] = spans.length;
-          for (const [text, flags, c, bg, ul, radius] of spans) {
+          for (const [text, flags, c, bg, ul, radius, family, font, size] of spans) {
             strRef(text);
             f[fi++] = flags;
             f[fi++] = c;
             f[fi++] = bg;
             f[fi++] = ul;
             f[fi++] = radius;
+            strRef(family);
+            strRef(font);
+            f[fi++] = size;
           }
         } else {
           f[fi++] = OP.text;
@@ -1010,7 +1026,9 @@ export function createEncoder(P) {
         for (const o of p.options) {
           const ok = (typeof o === 'string' && o.length > 0) || (o !== null && typeof o === 'object' && !Array.isArray(o));
           if (!ok) throw new Error('<select> options are non-empty strings or menu item objects { label, id, enabled }');
-          if (typeof o === 'object') for (const k in o) if (!MENU_ITEM_KEYS.has(k)) unknown.push([MENU_ITEM, k]);
+          // An option is chosen, never opened: its `items` are dropped,
+          // so they are reported as any key no option reads (RG150).
+          if (typeof o === 'object') for (const k in o) if (!MENU_ITEM_KEYS.has(k) || k === 'items') unknown.push([MENU_ITEM, k]);
         }
         const current = p.current;
         if (current != null && (!Number.isInteger(current) || current < 0)) {

package/howto.md

@@ -278,6 +278,23 @@ gap, to keep it apart.
 [ADR 0035](docs/adr/0035-a-rounded-background-is-joined-by-meeting.md) ·
 [alpha.22 `### Added`](CHANGELOG.md#010-alpha22-2026-09-28)
 
+### How do I set inline code in monospace inside a paragraph?
+
+Give the span a face of its own: `<span family="mono">cargo test</span>`,
+`Span::new("cargo test").mono()` in Rust, `{ "cargo test", family = "mono" }`
+in Lua, `.flags = KUI_SPAN_FAMILY, .family = KUI_FONT_MONO` on a C
+`KuiSpan` (`.font` for a registered font, which wins). Any family name the
+text's `family` takes works, and `size` gives a span its own size — a
+larger first word, a smaller footnote mark — with the line as tall as its
+tallest span. The paragraph still shapes as one flow, and its carets, hit
+tests and selection are measured in the face each glyph is drawn in, so a
+byte position means the same thing on either side of the change. Add a
+`bg` and a `bgRadius` for the usual wash; it is the span's own height,
+not the line's.
+
+[`text` element](props.md#elements) ·
+[`text.rs`](../examples/rust/widgets/text.rs)
+
 ### How do I list the installed fonts, the monospaced ones first?
 
 `ctx.systemFonts()` (Rust `Core::system_fonts()`, C `kui_system_fonts`)
@@ -558,6 +575,51 @@ message.
 [ADR 0019](docs/adr/0019-a-theme-derived-from-appearance-and-accent.md) ·
 [alpha.10](CHANGELOG.md#010-alpha10-2026-09-09)
 
+### How do I show the blurred desktop through my sidebar, like a Mac app?
+
+Ask the launcher for the effect — `kui_native::app("Notes")
+.backdrop(Backdrop::Blur)`, or `backdrop: 'blur'` in Node's window options
+— and paint the regions that should show it with alpha:
+`bg(t.raised.with_alpha(0.5))` on the sidebar, an opaque `bg` on the page
+beside it. kui puts the effect behind the whole window and knows nothing of
+sidebars; what you paint decides where it shows. `Blur` is a live blur of
+what is behind the window (macOS vibrancy, Windows 11's Acrylic, KDE's
+compositor blur), `Tinted` the desktop's colour, steady (Mica, macOS's
+window-background material), `Transparent` the desktop as it is. Then read
+what the window got, every frame, from `ui.env().window.backdrop` (Node
+`env().window.backdrop`): where the OS has no effect — GNOME, Windows 10 —
+it reads `Tinted`, the wallpaper kui reads, blurs once and draws under the
+frame, or `Opaque` where no wallpaper could be read; paint the sidebar
+opaque then. Hyprland, SwayFX and picom blur translucent windows
+themselves: ask for `Transparent` there. Glyphs are grayscale under a
+backdrop; `KUI_BACKDROP_EMULATE=1` shows the wallpaper path on Windows and Linux
+(macOS reads no wallpaper, so the window there is `Opaque`).
+
+[`window.backdrop` row](props.md#env) ·
+[`backdrop.rs`](../examples/rust/features/backdrop.rs)
+
+In C, `KuiRunConfig.backdrop` asks (`KUI_BACKDROP_BLUR`) and
+`kui_ctx_backdrop(ctx)` in the view reads what the window got.
+
+### How do I frost a toolbar over content that scrolls under it?
+
+Give the toolbar a `backdropBlur` and a translucent `bg`:
+`NodeSpec::row().backdrop_blur(16.0).bg(Color::WHITE.with_alpha(0.25))`
+in Rust, `backdropBlur: 16` in JSX, `backdrop_blur` in Lua, Odin and C's
+`KuiSpec`. What blurs is everything painted before the node — the page,
+the rows scrolling under it, the window's backdrop where there is one —
+inside the node's rounded box and its clip, by the radius in logical px
+(CSS's `backdrop-filter: blur()`). The node's own `bg`, border and
+children lie on top, so an opaque `bg` hides the blur, and a
+`backdrop-blur-hidden` warning says so. Float the toolbar over the
+scroller, after it in the tree, so the scroller paints first. It costs a
+copy and three small passes per blurred node on a frame that has one, and
+nothing on a frame that does not; a renderer of your own that cannot read
+back its frame draws the node unblurred.
+
+[`backdropBlur` row](props.md#container-props) ·
+[`backdrop_blur.rs`](../examples/rust/features/backdrop_blur.rs)
+
 ## Interaction, focus and reading
 
 ### How do I open a popup, and when is a modal enough?
@@ -734,6 +796,33 @@ the same palette from the keyboard and types the same way.
 [ADR 0030](docs/adr/0030-the-standard-menus-the-runner-keeps.md) ·
 [examples/rust/widgets/menu_bar.rs](../examples/rust/widgets/menu_bar.rs)
 
+### How do I put a submenu in a menu — "Move to ▸", "Sort by ▸"?
+
+Give the row `items`: `MenuItem::submenu("Move to", rows)` in Rust,
+`{ label: 'Move to', items: [...] }` in Node and Lua. The row draws a
+chevron and opens its rows beside it when the pointer rests on it, it is
+clicked, or Enter or the Right arrow is pressed; Left or Escape closes
+it, and Escape again closes the menu. It nests, in a context menu and in
+a menu bar, drawn or the platform's. A row inside is chosen like any
+row: one `{kind:"menu", role, item}` with its own `id`, on the node the
+menu is about. Give the rows inside an `id`: a row without one posts its
+label, and "Name" under "Sort by ▸" and "Name" under "Group by ▸" would
+post the same `item`. A host that shows menus itself reports one with
+`Core::activate_menu_path(&[1, 0])` (Node `activateMenuPath`, C
+`kui_activate_menu_path` with a path of `size_t`s). In C a row's
+`submenu` / `submenu_count` nest the same `KuiMenuItem`s, and
+`KUI_MENU_ITEM_SUBMENU` in a row's flags says it has rows, read with
+`kui_menu_item_path`. An
+`accel` in the portable spelling (`"mod+shift+n"`) is drawn the
+platform's way, and the menu widens to its longest row, up to the window
+less a margin (and never below the metric's menu width), where a longer
+label ends in an ellipsis. On the frame
+clock, an open submenu waits 0.3 s before giving way to a row the
+pointer crosses, so a diagonal path into it does not close it.
+
+[ADR 0018](docs/adr/0018-a-menu-bar-the-app-declares.md) ·
+[`tests/submenu.rs`](../crates/kui-core/tests/submenu.rs)
+
 ### How do I take files dropped from the Finder?
 
 Declare `onDrop` (Rust and Lua `on_drop`, C `KuiSpec.on_drop`) on the box

package/index.d.ts

@@ -730,6 +730,10 @@ export interface OpenMenuItem {
    *  own, or its role's default (`⌘C` on a `copy` row that declared none);
    *  null where there is neither. */
   accel: string | null;
+  /** The rows of the submenu this row opens, read the same way; absent on
+   *  a row that opens none. A row with them is never chosen itself: report
+   *  a row inside with `activateMenuPath`. */
+  items?: OpenMenuItem[];
 }
 
 /** The menu a window has open (`Ctx.menu()`): where it opened, the node it
@@ -925,6 +929,12 @@ export type WarningCode =
    *  after every width is. The ratio sizes a fit height from the width, or a
    *  fit width from a fixed height. */
   | 'aspect-ignored'
+  /** A `backdropBlur` under an opaque `bg` of the node's own: the background
+   *  paints over the whole blur, so nothing of it shows and the copy and the
+   *  passes are spent for nothing. Give the `bg` some transparency
+   *  (`#ffffff40`) — frosted glass is a translucent fill over a blur (backlog
+   *  F129). */
+  | 'backdrop-blur-hidden'
   /** A text node sits more than four levels below the `line` row above it,
    *  which is as far as a text's place remembers its ancestors — so `textHit` /
    *  `caretRect` asked by that row's key cannot find the run, and a press
@@ -1369,6 +1379,8 @@ export interface NodeInfo {
   /** `0xRRGGBBAA`. */
   borderColor: number;
   opacity: number;
+  /** Its `backdropBlur` radius in px, 0 for none (backlog F129). */
+  backdropBlur: number;
   /** A scroller's offset; `null` for a node that does not scroll. */
   scroll: { x: number; y: number } | null;
   /** Every handler it declared with the payload it would post: `click`,
@@ -1647,8 +1659,19 @@ export interface WindowEnv {
    *  draws over our content — the macOS traffic lights under custom chrome.
    *  Keep out of it. Null means the OS draws nothing over us. */
   nativeControls: Rect | null;
+  /** What is behind the window's transparent pixels, as the runner got it:
+   *  `'opaque'` (the default), `'transparent'` (the desktop as it is),
+   *  `'blur'` (a live blur of what is behind the window) or `'tinted'`
+   *  (the desktop's colour, steady). Less where the platform has less — a
+   *  blur asked of GNOME reads `'tinted'`, the wallpaper kui draws, or
+   *  `'opaque'` — so a view paints its translucent regions opaque when
+   *  this is `'opaque'`. */
+  backdrop: Backdrop;
 }
 
+/** What is behind a window's transparent pixels (`WindowEnv.backdrop`). */
+export type Backdrop = 'opaque' | 'transparent' | 'blur' | 'tinted';
+
 /** A box in logical px: position and size. */
 export interface Rect {
   x: number;
@@ -1689,6 +1712,8 @@ export interface EnvInput {
     /** `x` and `y` default to the window origin; a zero-sized rect and null
      *  both mean "nothing is drawn over us". */
     nativeControls?: Partial<Rect> | null;
+    /** What a runner would report behind the window's transparent pixels. */
+    backdrop?: Backdrop;
   };
   /** What a driver with a device would report; see `AudioEnv`. */
   audio?: {
@@ -1828,6 +1853,15 @@ export interface WindowOptions {
   maxWidth?: number;
   maxHeight?: number;
   chrome?: 'native' | 'custom' | 'borderless';
+  /** What shows through the window where a frame paints nothing or paints
+   *  with alpha (the launcher's `backdrop`), by effect: `'opaque'` (the
+   *  default), `'transparent'` (the desktop as it is), `'blur'` (macOS
+   *  vibrancy, Windows 11 Acrylic, KDE's compositor blur) or `'tinted'`
+   *  (Windows 11 Mica, macOS's window-background material, the wallpaper
+   *  kui draws where the OS has neither). Paint the regions that should
+   *  show it with alpha and the rest opaque; `env().window.backdrop` says
+   *  what the platform gave, which is less where it has less. */
+  backdrop?: Backdrop;
   /** How outline glyphs are antialiased: `'auto'` (the default) is LCD
    *  subpixel coverage where the GPU blends per channel and grayscale
    *  otherwise. `KUI_TEXT_AA=gray|subpixel` in the environment still
@@ -3280,6 +3314,12 @@ export declare class Ctx {
    * takes. False for a row that is not there.
    */
   activateMenuBarItem(menu: number, item: number): boolean
+  /**
+   * `activateMenuBarItem` for a row inside a submenu of menu
+   * `menu`, by its path through the rows' `items`. False for a
+   * row that is not there or that opens a submenu.
+   */
+  activateMenuBarPath(menu: number, path: Array<number>): boolean
   /**
    * Tells the core this host can show the platform's definition
    * panel. The standard Look Up row is then offered where it
@@ -3295,6 +3335,13 @@ export declare class Ctx {
    * stays open and nothing is posted.
    */
   activateMenuItem(index: number): boolean
+  /**
+   * `activateMenuItem` for a row inside a submenu, by its path
+   * through the rows' `items`: `[2, 0]` is the first row of the
+   * third row's submenu. False where `activateMenuItem` is, and
+   * for a row that opens a submenu, which is never chosen.
+   */
+  activateMenuPath(path: Array<number>): boolean
   /** Closes whatever menu is open; true when there was one. */
   closeMenu(): boolean
   /**
@@ -3481,7 +3528,7 @@ export declare class KuiWindow {
   /**
    * Options: `{width, height, minWidth, minHeight, maxWidth, maxHeight,
    * chrome: "native" | "custom" | "borderless", textAa: "auto" | "gray"
-   * | "subpixel", frameLatency, system, icon}`. The min/max pairs bound what the user can
+   * | "subpixel", frameLatency, system, icon, backdrop}`. The min/max pairs bound what the user can
    * resize the window to; either half may stand alone. `system` pins part of `env.system` over what the OS
    * says, for the life of the window — `{motion: 'reduced'}` is what a
    * user who asked for less motion would get, on a machine whose owner
@@ -4464,6 +4511,12 @@ export declare class KuiWindow {
    * takes. False for a row that is not there.
    */
   activateMenuBarItem(menu: number, item: number): boolean
+  /**
+   * `activateMenuBarItem` for a row inside a submenu of menu
+   * `menu`, by its path through the rows' `items`. False for a
+   * row that is not there or that opens a submenu.
+   */
+  activateMenuBarPath(menu: number, path: Array<number>): boolean
   /**
    * Tells the core this host can show the platform's definition
    * panel. The standard Look Up row is then offered where it
@@ -4479,6 +4532,13 @@ export declare class KuiWindow {
    * stays open and nothing is posted.
    */
   activateMenuItem(index: number): boolean
+  /**
+   * `activateMenuItem` for a row inside a submenu, by its path
+   * through the rows' `items`: `[2, 0]` is the first row of the
+   * third row's submenu. False where `activateMenuItem` is, and
+   * for a row that opens a submenu, which is never chosen.
+   */
+  activateMenuPath(path: Array<number>): boolean
   /** Closes whatever menu is open; true when there was one. */
   closeMenu(): boolean
   /**

package/index.js

@@ -1044,8 +1044,8 @@ runWindowed[PACE] = pacer;
  * is opened as a user who asked for less motion would see it.
  */
 export function windowOptions(opts = {}) {
-  const { width, height, minWidth, minHeight, maxWidth, maxHeight, chrome, textAa, frameLatency, system, icon } = opts;
-  return { width, height, minWidth, minHeight, maxWidth, maxHeight, chrome, textAa, frameLatency, system, icon };
+  const { width, height, minWidth, minHeight, maxWidth, maxHeight, chrome, textAa, frameLatency, system, icon, backdrop } = opts;
+  return { width, height, minWidth, minHeight, maxWidth, maxHeight, chrome, textAa, frameLatency, system, icon, backdrop };
 }
 
 /**

package/jsx-runtime.d.ts

@@ -219,6 +219,11 @@ export interface MenuItemInput {
    *  A declaration kui can parse is rewritten into the platform's own
    *  spelling, so `'mod+s'` reads as `⌘S` on macOS and `Ctrl+S` elsewhere. */
   accel?: string;
+  /** The rows of a submenu: the row draws a chevron and opens them beside
+   *  itself — on hover, a click, Enter or the Right arrow; Left or Escape
+   *  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[];
 }
 
 /** One menu of the application menu bar (the `<menuBar menu={…}/>`
@@ -257,6 +262,8 @@ export interface GeneratedSpecProps {
   animate?: boolean;
   /** Width over height — `16/9`, `1` for a square — CSS's `aspect-ratio`. It sizes the axis left `fit`: a fit height is the final width over the ratio (so `width: grow` and a ratio is a box that keeps its shape as the window resizes), and a fit width under a fixed height is that height times it. With both axes declared, or a fit width under a `grow` or percent height, it has nothing it can set and warns. The derived axis is neither shrunk nor fitted to the children, which overflow it; `minHeight: 'fit'` floors it at them. On an image it wins over the pixels' own aspect. */
   aspectRatio?: LengthProp;
+  /** Blur what was drawn beneath the node, inside its rounded box, by this radius in logical px — CSS's `backdrop-filter: blur()`, the radius its standard deviation (backlog F129). What blurs is everything painted before the node: its ancestors' backgrounds, the siblings under it, content scrolling beneath it, the window's `backdrop` where the window has one. The node's own `bg`, border and children paint over the blur, so a translucent `bg` (`#ffffff40`) makes frosted glass and an opaque one hides it. Clipped as the node is, faded by its `opacity`; 0 is none. The GPU renderer reads back only the box (and a margin of three radii around it) and blurs it at reduced resolution, so it costs a copy and three small passes per blurred node on a frame that has one and nothing on a frame that does not. A renderer that cannot read back what it drew — a host's own, or anything older — leaves the node over an unblurred backdrop; the display list carries it as a `backdrop` quad (`KUI_QUAD_BACKDROP` in C) either way. */
+  backdropBlur?: LengthProp;
   /** Background fill. */
   bg?: ColorProp;
   /** How far a spring overshoots its target: 0 glides in with none, 0.5 bounces visibly, and values past 0.9 are held there (a spring at 1 would never settle). It replaces a spring `easing`'s own bounce (`smooth` 0, `snappy` 0.15, `spring` 0.25, `bouncy` 0.5), and on a timed easing makes the transition a spring — so `transition` plus `bounce` is a spring of that length and bounce. */
@@ -599,6 +606,18 @@ export interface SpanProps extends Keyed {
    *  A selection over rows, or over a paragraph's wrapped lines, is one
    *  outline. Nested spans inherit; 0 (the default) is square. */
   bgRadius?: number;
+  /** The span's own face: `sans`, `serif`, `mono` or an installed family's
+   *  name, as the text's `family` takes — inline code in `mono` inside a
+   *  sans paragraph. Carets, hits and selection are measured in the face
+   *  the glyphs are drawn in. Nested spans inherit. */
+  family?: string;
+  /** A registered font handle (`addFont` / `addSystemFont`), the span's
+   *  face; wins over `family`. Nested spans inherit. */
+  font?: string;
+  /** The span's own size, logical px: its line height scales with it at
+   *  the paragraph's ratio, and a line is as tall as its tallest span.
+   *  Nested spans inherit. */
+  size?: number;
   children?: KuiNode;
 }
 

package/package.json

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

package/props.md

@@ -18,6 +18,7 @@ where they make sense); text props apply to `<text>` and `<edit>`.
 | `anchor` | `anchor` | `anchor` | `Spec.anchor` | boolean | Scroll anchoring on a scrolling node (backlog C26, CSS's `overflow-anchor`): the first child in view keeps its place on screen when the content before it changes size — a chat that prepends history, a log that inserts rows above the viewport, a list whose row heights are corrected as they are measured — with no `setScroll` and no arithmetic in the view. The core remembers which child was first in view and where its edge was, and moves the offset by however far that edge moved in the next layout, before the offset is clamped; a wheel notch or a `setScroll` between the frames is kept and the correction added to it. The child is found by key, so give the rows stable keys (a `key` or an `index`); a child that is gone anchors nothing that frame. On the scroll axis that is the node's main axis only — `scrollY` on a column, `scrollX` on a row — and content appended *after* the anchor moves nothing, so a log that is tailing still asks for the end itself. |
 | `animate` | `animate` | `animate` | `Spec.animate` | boolean | Ask for another frame after this one, every frame this node is declared. What a `fragment` that reads `time` needs, and what anything driving itself off the clock rather than off input needs. Opt-in like `exit`, and for the same reason: it takes the loop off input-driven and onto the display's cadence for as long as it is declared, so a still node must not carry it. One node asking is enough for the whole window. |
 | `aspectRatio` | `aspect_ratio` | `aspect_ratio` | `Spec.aspect_ratio` | number, or a `"$length"` token | Width over height — `16/9`, `1` for a square — CSS's `aspect-ratio`. It sizes the axis left `fit`: a fit height is the final width over the ratio (so `width: grow` and a ratio is a box that keeps its shape as the window resizes), and a fit width under a fixed height is that height times it. With both axes declared, or a fit width under a `grow` or percent height, it has nothing it can set and warns. The derived axis is neither shrunk nor fitted to the children, which overflow it; `minHeight: 'fit'` floors it at them. On an image it wins over the pixels' own aspect. |
+| `backdropBlur` | `backdrop_blur` | `backdrop_blur` | `Spec.backdrop_blur` | number, or a `"$length"` token | Blur what was drawn beneath the node, inside its rounded box, by this radius in logical px — CSS's `backdrop-filter: blur()`, the radius its standard deviation (backlog F129). What blurs is everything painted before the node: its ancestors' backgrounds, the siblings under it, content scrolling beneath it, the window's `backdrop` where the window has one. The node's own `bg`, border and children paint over the blur, so a translucent `bg` (`#ffffff40`) makes frosted glass and an opaque one hides it. Clipped as the node is, faded by its `opacity`; 0 is none. The GPU renderer reads back only the box (and a margin of three radii around it) and blurs it at reduced resolution, so it costs a copy and three small passes per blurred node on a frame that has one and nothing on a frame that does not. A renderer that cannot read back what it drew — a host's own, or anything older — leaves the node over an unblurred backdrop; the display list carries it as a `backdrop` quad (`KUI_QUAD_BACKDROP` in C) either way. |
 | `bg` | `bg` | `bg` | `Spec.bg` | color (`#hex` or `0xRRGGBBAA`), or a `"$color"` token | Background fill. |
 | `bounce` | `bounce` | `bounce` | `Spec.bounce` | number, or a `"$length"` token | How far a spring overshoots its target: 0 glides in with none, 0.5 bounces visibly, and values past 0.9 are held there (a spring at 1 would never settle). It replaces a spring `easing`'s own bounce (`smooth` 0, `snappy` 0.15, `spring` 0.25, `bouncy` 0.5), and on a timed easing makes the transition a spring — so `transition` plus `bounce` is a spring of that length and bounce. |
 | `buttons` | `buttons` | `buttons` (`KUI_BUTTONS_*` bits; zeroed, all three) | `Spec.buttons` | string | Which non-primary buttons `onButton` claims (backlog F105): `"secondary"`, `"middle"` and `"other"` (every button past those), separated by spaces or commas — `"middle"`, `"secondary middle"`. Unset, all three: a node that wants the middle button and leaves the secondary one to its context menu says `"middle"`. A word that is none of the three is skipped, so a string of none of them claims nothing, and a typo never takes the secondary button from a context menu. Meaningless without `onButton`. |
@@ -117,9 +118,9 @@ where they make sense); text props apply to `<text>` and `<edit>`.
 |---|---|---|---|---|---|
 | `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_*`) | `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. |
+| `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. |
 | `features` | `features` | `KuiTextStyle.features` (a `KuiStr`, the same spelling) | `Text_Style.features` | string | OpenType features for the shaper, as `tag=value` pairs separated by spaces or commas — a bare `tag` is 1, `-tag` is 0: `"liga=0 calt=0"` keeps a coding font from joining `->` and `!=` (what a terminal built on runs needs to hold its grid), `"tnum"` lines figures up in a gutter, `"ss01"` picks a stylistic set. Unset, the font's own defaults apply. At most 8; part of what the text is shaped as, so two texts differing only here are shaped twice. |
-| `font` | `font` | `KuiTextStyle.font` (from `kui_font_add*`) | `Text_Style.font` | resource handle | A registered font handle (addFont / addSystemFont); overrides `family`. |
+| `font` | `font` | `KuiTextStyle.font` (from `kui_font_add*`); `KuiSpan.font` | `Text_Style.font` | resource handle | A registered font handle (addFont / addSystemFont); overrides `family`. |
 | `lineHeight` | `line_height` | `KuiTextStyle.line_height` | `Text_Style.line_height` | number, or a `"$length"` token | Line height (logical px); default size * 1.35. |
 | `maxLines` | `max_lines` | `KuiTextStyle.max_lines` | `Text_Style.max_lines` | number, or a `"$length"` token | Lay out at most this many lines (0 = unlimited); with `ellipsis`, a line clamp. |
 | `strikethrough` | `strikethrough` | `KuiTextStyle.decoration` (`KUI_DECO_STRIKETHROUGH`); `KuiSpan.flags` (`KUI_SPAN_STRIKETHROUGH`) | `Text_Style.strikethrough` | boolean | A line through the text, where the face puts its strikeout. Paint only; on a `<span>` the span alone, per line. |
@@ -145,7 +146,7 @@ where they make sense); text props apply to `<text>` and `<edit>`.
 | `pad`, `padX`, `padY`, `padL`, `padR`, `padT`, `padB` | `pad = n` or `pad = { all=, x=, y=, l=, r=, t=, b= }` | `pad_l`, `pad_r`, `pad_t`, `pad_b` | `Spec.pad`: `kui.pad(16)`, `kui.pad(16, 8)`, or `{l = .., r = .., t = .., b = ..}` | Padding; a frontend reports the names it saw and `PadShorthand::resolve` turns them into four edges — an edge falls back to its axis, an axis to the all-round `pad`, and the specific one always wins. |
 | `rowCount` | `row_count` | `kui_row_count` | `Spec.row_count`, a `Maybe(u64)`, which calls `kui.row_count` on the node | How many `index`ed rows this node's virtual list has, built or not. `uniformList` / `uniform_list` / `widgets::uniform_list` and `widgets::list` declare it on their container; a list composed by hand says it beside `scrollY`. What it buys: Select All (Cmd/Ctrl-A, the menu's row) inside a `selectable` virtual list selects the *data*, rows `0..rowCount`, rather than the rows the frame built, and the copy is a `selectionrange` ask whose `to.byte` is past the last row's length when that row is not built — cut it to the row. Without it Select All is the built rows, which is all the core can see. |
 | `secureInput` (root box only) | `secure_input = true` (root table) | `kui_set_secure_input` | `kui.set_secure_input` | Declares that this frame wants the keyboard to this window kept from every other process while the window has it — macOS's Secure Keyboard Entry, what a terminal turns on at a password prompt (backlog F85). Frame state the way `alwaysOnTop` is, default false: declare it on every frame the prompt is up, and the frame that stops is what turns it off, so nothing has to remember to undo it. The runner owns the platform call and its balance: `EnableSecureEventInput` is process-wide and counted, and the runner holds one count while a window whose frame asked has the keyboard, giving it back when that window loses the keyboard, closes or stops asking, and at exit — Apple's rule, since while it is on no other process can read the keyboard at all (a launcher's hotkey, a text expander, an accessibility tool). Nothing on Windows or Linux, which have no such switch. A C host with its own loop reads the ask with `kui_secure_input_get` and makes the call itself. |
-| `size` (text) | `size` | `KuiTextStyle.size` | `Text_Style.size` | Font size in logical px; the text style is constructed from it, so declare it for the other style props to apply at that size. |
+| `size` (text) | `size` | `KuiTextStyle.size`; `KuiSpan.size` | `Text_Style.size` | Font size in logical px; the text style is constructed from it, so declare it for the other style props to apply at that size. |
 | `title` (root box only) | `window_title` (root table) | `kui_window_title` | `kui.window_title` | Declares the window title for this frame; the driver diffs and applies. |
 | `tooltip="hint"` | `tooltip = "hint"` | `KuiSpec.tooltip` (`kui_tooltip` / `kui_tooltip_with` draw a hint that is not hover-gated) | `Spec.tooltip` (`kui.tooltip` / `kui.tooltip_with` draw a hint that is not hover-gated) | Floats a hint below the node while hovered. All three effects — hover tracking, the accessible description, and the float itself — come from `PropsOut::apply_tooltip`, so no frontend can implement two of them; a Rust view has all three in `NodeSpec::tooltip` (`NodeSpec::apply_tooltip` is the spec half, for a caller that floats the hint itself). The `description` row is that middle effect on its own, for a hint that is spoken and never drawn. On a box or a `fragment` the float is the node's last child; a leaf holds no children — a `line`, `polygon`, `path`, `cells` grid, `image` or `edit` — and its hint floats beside it instead, anchored to it, and lands below its box the same way, out of every clip and flipping above near the window's bottom (backlog RG113; `PropsOut::for_leaf`). A leaf draws its description, which is the hint unless a `description` applied after it overwrote the slot. A `line`, `polygon` or `path` is hovered by its shape, so its hint shows while the pointer is on the stroke or inside the outline, not anywhere in its box. |
 | `windows={[{ name, kind?, anchor?, width?, height?, activates? }]}` (root box only; `windows: (model) => [...]` in the loop config) | `windows = { { name=, kind=, anchor=, width=, height=, activates= } }` (root table) | `kui_window_declare` | `kui.window_declare` | Declares which windows exist this frame, by stable name (`docs/adr/0004-multi-window.md`). A window opens on the first frame any window's frame declares it — its config is read then and never again, since the user owns its geometry once it exists — and closes on the first frame none does. The driver drains the `Open` / `Close` that result, and the app sees `{kind:"window", phase, name, id}`. A window the user closed does not reopen while it is still declared: stop declaring it, then declare it again. `kind: "popup"` makes it a menu surface instead: borderless, off the taskbar, owned by the window that declared it and closed with it, placed in screen coordinates against `anchor` — the `{x, y, w, h}` an `onLayout` node reported — and non-activating unless `activates` says otherwise, so the field that opened it keeps the focus ring while the arrows walk the list. A press outside it or Escape raises `{kind:"dismiss", reason, name, id}` and closes nothing, exactly as a `modal` node's does: stop declaring the window. Reach for a popup only for the placements a float cannot make — a list taller than the window, a menu with nowhere in-window to go, a panel beside the app; everything else stays `fit` plus a `modal` float, which costs one tree instead of an OS surface. |
@@ -156,7 +157,7 @@ where they make sense); text props apply to `<text>` and `<edit>`.
 |---|---|---|---|---|
 | `<box>` | `row { }`, `column { }` | `kui_open*` … `kui_close` | `kui.box` / `kui.row` / `kui.column` in an `if`, closed at its end; `kui.open` … `kui.close` unscoped | A container: every container prop applies. |
 | `<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>` children | `text("s", {…})`, `text({ "a", { "b", bold = true, underline = true, bg = 0x.., bg_radius = 4 } })` | `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 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. |
+| `<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. |
 | `<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. |
@@ -172,7 +173,7 @@ where they make sense); text props apply to `<text>` and `<edit>`.
 | `<cells rows cols cells={Uint32Array} cursorAt={[row, col]} cursorShape cursorColor size family lineHeight/>` | `cells { rows=, cols=, lines={"row text", …}, runs={{row, col, len, fg, bg, flags}, …}, cursor_at={row, col}, cursor_shape=, cursor_color=, size=, family= }` | `kui_cells` | `kui.cells` | A terminal's screen as one node (backlog C20): `rows × cols` cells, each a character, a foreground and background as `0xRRGGBBAA` (0 = no background), and attribute bits — 1 bold, 2 italic, 4 underline, 8 strikethrough, 16 wide (the glyph spans this cell and the next, which the app leaves blank), 32 the underline is a wave (a terminal's undercurl, SGR 4:3) and 64 dotted (SGR 4:4), either implying it — plus, optionally, the underline's own colour (SGR 58), 0 for the foreground (backlog K4). A glyph is shaped once per character and style variant and thereafter placed at `col × cell_w` without shaping, so a screen whose every cell is new each frame costs what a still one costs (~60 µs for 200 × 50). The cell width is `M`'s advance in the style's font snapped to whole pixels, the height its `lineHeight`; a cell is a cell, so ligatures never form. A character the family has no glyph for is asked of a monospaced face before the platform's fallback list, shaped smaller where it is still wider than its cells (two under wide), and drawn in their middle (backlog F120); the private use area's icons are left as they fall. Box drawing and block elements (U+2500–U+259F) and the Powerline separators (U+E0B0–U+E0BF: the arrows, and the Powerline Extra half circles and wedges) are not shaped at all but drawn from the cell box — a font's are its own line box tall, a cell is `lineHeight` tall, and through the font every `│` was a dash with a gap under it (backlog F66) and a rounded cap a fallback font's squiggle (F112) — so a TUI's frames and rounded rows are seamless in any font, and bold does not thicken a light line (the set has its heavy variants). JSX passes the cells as a `Uint32Array` (or number array) of four entries per cell — codepoint, fg, bg, flags — or five, with the underline colour, in row-major order; Lua a string per row in `lines` plus `runs` of `{row, col, len, fg, bg, flags, ul}` over them (a run's fg, bg or ul of 0 keeps the default: the style's colour, no background, the foreground); C a `KuiCell` array with `ul`. `cursorAt` (`cursor_at`) names a cell to paint under its glyph in `cursorColor` as a `block` (default), `bar` or `underline` — its own name, since `cursor` is the pointer shape. `originLine` (`origin_line`) is the absolute line number of row 0: a grid is one screenful of the app's own history, so a row number means a different line after every scroll, and stamping where the screen sits is what lets a selection keep its ends across one (`docs/adr/0017-selection-as-a-scope.md`). Saying nothing is 0, and a selection then holds only while the screen does not move. The node's own rows apply — an `onKey` makes it the terminal's sink, an `onClick` or `onDrag` carries `cell: {row, col}` on its events — and its access row is `terminal`, the rows joined as its value. |
 | `<line from={[x,y]} to={[x,y]} width color/>`, `<line points={[[x,y],…]} curve dash={[6, 4]} dashOffset/>` | `line { from={x,y}, to={x,y}, width=, color= }`, `line { points={{x,y},…}, curve=true, dash={6, 4}, dash_offset= }` | `kui_line`, `kui_polyline` | `kui.line`, `kui.polyline` (points, `[][2]f32`) | A round-capped stroke: one segment, a polyline through `points`, or a smooth curve through them with `curve`. Always a float in its parent's box space (`float="viewport"` for viewport space), sized to its own bounding box, so it takes no room in a row or column — but a float for the room alone: in its parent's box space it paints in the parent's layer at its place in the tree, over the siblings declared before it and under those after, as a child does, and opens no layer of its own (backlog F123; a connector meant to sit under two cards is declared before them). A stroke in its parent's box space is held by the parent's clip as a child is, its hit region with it, so it is cut at a scroller's edge with the row it is drawn in; a declared float is held that way only when it declares `clip` with a parent anchor, and a `float="viewport"` stroke escapes, and is a layer of its own (backlog F78, `docs/adr/0010-a-segment-primitive.md` decision 5). `width` is the stroke width (default 1) and `color` the stroke colour; `transition` eases the colour, and with `slide` beside it the stroke's position too — the points ride its box, so a stroke whose ends all move together slides with them, while one whose ends move apart resizes at once (a canvas of floats eases everything or nothing, connectors included). Hit by its shape (`docs/adr/0026-hit-testing-by-shape.md`): with `onClick`, `onDrag`, `onHover` or `hoverable` a press within half the width of any piece hits it — at least 4 px of grab, so a hairline is a target — and a press elsewhere in its bounding box falls through to what is under; with none it takes no input and has no access row, and with input it derives one as a box would (a clickable connector is a button), so name it. What it costs: one quad per segment, and a curve is flattened in the core at one piece per 6 logical px of chord (at most 32 per span) — fixed rather than tolerance-driven so every binding gets the same pieces and the corpus can pin them — so a nine-point curve over ~50 px spans is ~60 quads, and a `quadCount` budget should expect it. `dash` cuts the stroke into marks and gaps (backlog V2): one length (marks and gaps alike), a mark and a gap, or four lengths for a dash-dot, in px **as seen** — every mark is a short stroke with the stroke's round caps, so `dash` 6, 4 is 6 px of ink and 4 px of nothing at any width up to 6 (SVG's `stroke-dasharray` measures the centre line instead, so with round caps its `4 4` at a width of 4 is solid; this pattern is SVG's `mark − width, gap + width`). A mark no longer than the stroke is wide is a dot as wide as the stroke, in the same period, so its gap is that much shorter; where a mark and its gap together come to no more than the width the dots meet and the gap closes — the marks either side of it are one, and a pattern with no gap left, `dash` 2, 2 at a width of 8, draws solid (backlog RG118). The pattern runs along the stroke's whole length, so it keeps its phase round the corners of a polyline and the pieces of a curve, and `dashOffset` starts that far into it — growing it moves the marks towards the first point, a marquee's marching ants; neither tweens. A pattern with no gap, a mark and gap under a physical pixel together, or more than 16384 marks draws solid. A dashed stroke is hit along its whole length, gaps included, and costs a quad per mark per piece the mark lies on. |
 | `<titlebar title>` or `<titlebar>…</titlebar>` | `titlebar { title= }` / `titlebar { … }` | `kui_titlebar`, `kui_titlebar_with` | `kui.titlebar`, `kui.titlebar_with` | Adaptive titlebar for custom chrome: drag strip, native-control inset, window buttons. |
-| `<menuBar menu={[{ label, items: [{ label, id?, role?, accel?, enabled?, checked? }] }]}/>` | `menu_bar { menu = { { label=, items= { { label=, id=, role=, accel=, enabled=, checked= } } } } }` | `kui_menu_bar` | `kui.menu_bar` | The application menu (`docs/adr/0018-a-menu-bar-the-app-declares.md`): `menu` is what it *is*, and where this element sits is where its titles go when they have to be drawn in the window. One call and not two, because declaring the menu and placing the strip are one decision. It draws **nothing** where the platform owns the bar — macOS, where the driver hands the same declaration to the OS — so the frame has still said what the app's menu is and the strip simply is not there; that is the contract `windowButtons` has under native decorations, and it is what makes one view portable. Its rows are the rows a context menu has: the same `role`s the core performs itself (`copy`, `paste`, `selectAll`, `cut`, `lookUp`), the same `id` payload, the same `accel` text, plus `checked` for a setting — and choosing one posts the same `{kind:"menu", role, item}` event, so an app handles one thing whichever menu it came from. Declared every frame and diffed: an unchanged menu costs a comparison, and an empty list takes it away. An accelerator kui can parse is rewritten into the platform's spelling, so `"mod+s"` reads as `⌘S` on macOS and `Ctrl+S` elsewhere and binds that key in the platform's own bar. On macOS the first menu is the application menu, which the OS titles with the app's own name whatever the label says. While a menu is open the bar is the frame's modal scope, so hovering across the titles moves the open menu, a press on the open title closes it, and Escape or a press in the app below closes it and reaches nothing else. |
+| `<menuBar menu={[{ label, items: [{ label, id?, role?, accel?, enabled?, checked?, items? }] }]}/>` | `menu_bar { menu = { { label=, items= { { label=, id=, role=, accel=, enabled=, checked=, items= } } } } }` | `kui_menu_bar` | `kui.menu_bar` | The application menu (`docs/adr/0018-a-menu-bar-the-app-declares.md`): `menu` is what it *is*, and where this element sits is where its titles go when they have to be drawn in the window. One call and not two, because declaring the menu and placing the strip are one decision. It draws **nothing** where the platform owns the bar — macOS, where the driver hands the same declaration to the OS — so the frame has still said what the app's menu is and the strip simply is not there; that is the contract `windowButtons` has under native decorations, and it is what makes one view portable. Its rows are the rows a context menu has: the same `role`s the core performs itself (`copy`, `paste`, `selectAll`, `cut`, `lookUp`), the same `id` payload, the same `accel` text, plus `checked` for a setting — and choosing one posts the same `{kind:"menu", role, item}` event, so an app handles one thing whichever menu it came from. Declared every frame and diffed: an unchanged menu costs a comparison, and an empty list takes it away. An accelerator kui can parse is rewritten into the platform's spelling, so `"mod+s"` reads as `⌘S` on macOS and `Ctrl+S` elsewhere and binds that key in the platform's own bar. On macOS the first menu is the application menu, which the OS titles with the app's own name whatever the label says. While a menu is open the bar is the frame's modal scope, so hovering across the titles moves the open menu, a press on the open title closes it, and Escape or a press in the app below closes it and reaches nothing else. |
 | `<windowButtons/>` | `window_buttons()` | `kui_window_buttons` | `kui.window_buttons` | Just the min/max/close buttons, for fully custom titlebars. |
 | `<tooltip value="hint"/>` / `<tooltip>…</tooltip>` nodes, or the `tooltip="hint"` prop (see composites) | `tooltip("hint")` / `tooltip { … }` nodes, or the prop | `kui_tooltip`, `kui_tooltip_with` | `kui.tooltip`, `kui.tooltip_with` | A float hanging below the parent; the node form always draws, the prop form is hover-gated. |
 | `<latencyGraph/>`, `<latencyHud at/>` | `latency_graph()`, `latency_hud { at= }` | `kui_latency_graph`, `kui_latency_hud` | `kui.latency_graph`, `kui.latency_hud` | Per-phase frame timing (windowed drivers fill it; headless shows the chrome empty). |
@@ -271,6 +272,7 @@ people. In Node the codes are the `WarningCode` union.
 | `wrap-ignored` | `wrapChildren` on a container that cannot break lines: a column, a row whose main axis scrolls, or a row of a table, whose children are the table's columns. All lay out exactly as if the flag were absent, which reads as "wrapping is broken"; see `LayoutSpec::wrap` for why a column cannot have it. |
 | `align-ignored` | An alignment declared where it means nothing: a spread (`spaceBetween` / `spaceAround` / `spaceEvenly`) on `crossAlign`, `baseline` on `mainAlign` or on a column's `crossAlign`, or either as a float's attach point. Each lays out as `start` — the two centring spreads as `center` — which reads as "the value is broken" when it is the axis that is wrong. |
 | `aspect-ignored` | An `aspectRatio` with nothing it can set: both axes are declared, or the width is `fit` under a `grow` or percent height, which is resolved only after every width is. The ratio sizes a fit height from the width, or a fit width from a fixed height. |
+| `backdrop-blur-hidden` | A `backdropBlur` under an opaque `bg` of the node's own: the background paints over the whole blur, so nothing of it shows and the copy and the passes are spent for nothing. Give the `bg` some transparency (`#ffffff40`) — frosted glass is a translucent fill over a blur (backlog F129). |
 | `text-beyond-line` | A text node sits more than four levels below the `line` row above it, which is as far as a text's place remembers its ancestors — so `textHit` / `caretRect` asked by that row's key cannot find the run, and a press inside it reports `byte: 0`. Flatten the wrappers between the row and its text, or ask by a nearer key. |
 | `exit-budget` | One frame removed more nodes declaring `exit` than the exit store will hold (4096, `depart::MAX_NODES`), so none of that frame's removal animated: every departing node of it vanished at once, as a node with no `exit` does, rather than some sliding out and the rest blinking. Correct, and invisible from the outside, which is the whole reason it is a line here: a list that drops a thousand rows wants `exit` on the list, not on every row. A removal that fits the budget but finds earlier exits still in flight evicts those, oldest first, and is not this warning. |
 | `unknown-prop` | A prop name nothing claims: not a schema row, not a composite, not one of the element's own props (see `schema::known_prop`). The binding threw the declaration away — `hoverBg` in a Lua table, `onclick` in JSX — so unlike every other code here this one is raised by the frontend that saw it, through `Core::warn`: by the time a frame is a tree the name is gone. The message names the likely spelling. Also raised for a key a menu row map carried that no row reads — `disabled` on a select's option, where the key is `enabled` — by the binding that read the row. |
@@ -347,6 +349,7 @@ one reading that changes what a view *says* rather than what it draws.
 | `window.fullscreen` | `WindowEnv::fullscreen` | `window.fullscreen` | `window.fullscreen` | `kui_env_set_window(fullscreen)` | `kui.env_set_window(fullscreen)` | The window is fullscreen. |
 | `window.always_on_top` | `WindowEnv::always_on_top` | `window.alwaysOnTop` | `window.always_on_top` | `kui_env_set_always_on_top(always_on_top)` | `kui.env_set_always_on_top(always_on_top)` | The window is above every other app's: the level the driver set after the frame asked for it (`alwaysOnTop` / `always_on_top` / `kui_set_always_on_top`, backlog C30), on a platform that has one. On Wayland winit has no call for it, so a driver there reports false however often the app asks — which is why a pin button draws its state from this and not from the app's own flag. It is the driver's record of what it set and not a query (winit has no level getter), so a level the OS dropped afterwards — a fullscreen space, a tiling manager — is not seen here. A C host reports it through its own setter rather than an argument on `kui_env_set_window`, the way `kui_env_set_assistive` is, so an older host that never applies a level has nothing to recompile. |
 | `window.native_controls` | `WindowEnv::native_controls` | `window.nativeControls` | `window.controls_w` / `window.controls_h` | `kui_env_set_window(controls_w, controls_h)` | `kui.env_set_window(controls_w, controls_h)` | Area (logical px, window coordinates) covered by controls the OS still draws over our content — the macOS traffic lights under custom chrome. Keep out of it. Node hands back the `Rect` the core holds (`{x, y, w, h}`, or `null` for none); Lua and C flatten it to a width and height anchored at the window origin (absent in Lua, `0` in C, for none), which is the shape C's two numbers can express and where the one real instance sits. |
+| `window.backdrop` | `WindowEnv::backdrop` | `window.backdrop` | `window.backdrop` | `kui_env_set_backdrop(backdrop)`; read back with `kui_ctx_backdrop()` | `kui.env_set_backdrop(backdrop)`; read back with `kui.ctx_backdrop()` | What is behind the window's transparent pixels, as the driver got it (backlog F126): `"opaque"` (the default, and every headless core's), `"transparent"` (the desktop as it is), `"blur"` (a live blur of what is behind the window) or `"tinted"` (the desktop's colour, not live) — `KUI_BACKDROP_*` in C, opaque 0. The app asks with `Launcher::backdrop` and decides which regions show it by painting them with alpha; this is the answer, which is less where the platform has less — a blur asked of GNOME reads `"tinted"`, the wallpaper kui draws itself, or `"opaque"` where none could be read — so a view paints its translucent regions opaque when this says so. A C host reports it through its own setter, as `always_on_top` is; a C app asks with `KuiRunConfig.backdrop` and its view reads the answer with `kui_ctx_backdrop`. |
 | `audio.device` | `AudioEnv::device` | `audio.device` | `audio.device` | `kui_env_set_audio(device)` | `kui.env_set_audio(device)` | What the driver's output device is doing: `"closed"` (the default, and a headless driver's answer), `"opening"` (the ~90 ms open, on its own thread), `"open"`, or `"failed"` (it refused, and commands are dropped) — `KUI_AUDIO_DEVICE_*` in C, closed 0. A fact and not a verb: nothing lets a view close it, the driver does that itself once it has been idle a while. Worth reading because an open stream is a real-time thread whether or not anything plays, which is the whole of an idle app's CPU once a session has held a sound. |
 | `audio.live` | `AudioEnv::live` | `audio.live` | `audio.live` | `kui_env_set_audio(live)` | `kui.env_set_audio(live)` | Playbacks started and not yet ended, plus any waiting on the device to open. Zero with the device still `"open"` is the idle stream the row above is about. A play that arrives while the device is `"opening"` counts here from the frame it was asked, until the open answers: if the device refuses, the play is refused on the next apply — `{kind:"sound", phase:"refused"}` for a tagged one — and leaves the count with it, so what a machine with no output device shows is `opening`/1 then `failed`/0 with the refusal between (backlog F63). |
 | `viewport.w` | `Core::viewport()`, the frame's | `viewport.width` | `viewport_w` | `kui_frame_begin(w)` | `kui.frame_begin(w)` | The logical width of the current (or last) frame's viewport — the window less the devtools' dock while the panel is docked (`docs/adr/0024`), the same number a `resize` reports and Node's `KuiWindow.size()` answers — the other host fact a view wants at the same moment, so it rides in the same reading. Zero before the first frame, since the frame establishes it (backlog F43: this row once read the window instead, so an app under `KUI_DEVTOOLS` sized itself to a viewport it did not have). Node's `viewport` is the `WindowSize` shape `runWindowed` already uses. |
@@ -574,12 +577,14 @@ its generator (`nu scripts/odin.nu gen --check`).
 | `Ui::open_menu` | `kui_open_menu` | `open_menu` | `openMenu` | `open_menu` | Opens a context menu on a node at a point. |
 | `Ui::close_menu` | `kui_close_menu` | `close_menu` | `closeMenu` | `close_menu` | Closes it. |
 | `Core::take_menu_actions` | `kui_take_menu_action` | `take_menu_action` | `takeMenuActions` | a chosen row comes back as a `menu` event on the node; the clipboard actions are the host's | Drains what a menu (or a chord, or the standard bar) asked of the host: a clipboard write, a paste, a Look Up. |
-| `Core::menu` | `kui_menu_item_count` / `kui_menu_item`, one row at a time | `menu_item_count` / `menu_item`, one row at a time | `menu` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The open menu, for a host showing it natively. |
+| `Core::menu` | `kui_menu_item_count` / `kui_menu_item`, one row at a time, and a submenu's by path with `kui_menu_submenu_count` / `kui_menu_item_path` | `menu_item_count` / `menu_item`, one row at a time, and a submenu's by path with `menu_submenu_count` / `menu_item_path` | `menu` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The open menu, for a host showing it natively. |
 | `Core::set_native_menus` | `kui_set_native_menus` | `set_native_menus` | `setNativeMenus` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | Whether the host shows menus itself; the core then draws none. |
 | `Core::activate_menu_item` | `kui_activate_menu_item` | `activate_menu_item` | `activateMenuItem` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | Reports that the host's own menu chose a row; a row that cannot be chosen (disabled, a separator) is refused and the menu stays open. |
-| `Core::menu_bar` | `kui_menu_bar_menu_count` / `kui_menu_bar_menu` / `kui_menu_bar_item`, one row at a time | `menu_bar_menu_count` / `menu_bar_menu` / `menu_bar_item`, one row at a time | `menuBar` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The declared menu bar, for a host handing it to the OS. |
+| `Core::activate_menu_path` | `kui_activate_menu_path` | `activate_menu_path` | `activateMenuPath` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | `activate_menu_item` for a row inside a submenu, by its path through the rows' submenus (backlog F128); a row that opens a submenu is refused. |
+| `Core::menu_bar` | `kui_menu_bar_menu_count` / `kui_menu_bar_menu` / `kui_menu_bar_item`, one row at a time, and a submenu's by path with `kui_menu_bar_submenu_count` / `kui_menu_bar_item_path` | `menu_bar_menu_count` / `menu_bar_menu` / `menu_bar_item`, one row at a time, and a submenu's by path with `menu_bar_submenu_count` / `menu_bar_item_path` | `menuBar` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The declared menu bar, for a host handing it to the OS. |
 | `Core::set_native_menu_bar` | `kui_set_native_menu_bar` | `set_native_menu_bar` | `setNativeMenuBar` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | Whether the host owns the bar; the core then draws no strip. |
 | `Core::activate_menu_bar_item` | `kui_activate_menu_bar_item` | `activate_menu_bar_item` | `activateMenuBarItem` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | Reports that the OS bar chose a row. |
+| `Core::activate_menu_bar_path` | `kui_activate_menu_bar_path` | `activate_menu_bar_path` | `activateMenuBarPath` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | `activate_menu_bar_item` for a row inside a submenu, by its path (backlog F128). |
 | `Ui::window` | `kui_window_declare` | `window_declare` | the root's `windows` prop | the root's `windows` field | Declares that a named window exists this frame (ADR 0003 step 3). |
 | `Core::windows` | the ids arrive on `KUI_CMD_OPEN`; a host keeps the list it opened | the ids arrive on `take_window_command`'s `.Open`; a host keeps the list it opened | `windows` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The names of the windows open now. |
 | `Ui::window_name` | `kui_ctx_window_name` | `ctx_window_name` | `windowName` | `env.window.name`, a reading | The name of the window this context draws. |
@@ -649,6 +654,6 @@ its generator (`nu scripts/odin.nu gen --check`).
 | `Core::audio_ended` | `kui_audio_ended` | `audio_ended` | `Ctx.audioEnded` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The device reports a playback over. |
 | `Core::audio_truncated` | `kui_audio_truncated` | `audio_truncated` | `Ctx.audioTruncated` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The device reports a stop that cut a playback short — a one-shot node's removal becomes `truncated-playback`. |
 | `Core::audio_refused` | `kui_audio_refused` | `audio_refused` | `Ctx.audioRefused` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The device reports a play it would not take — a `refused` sound event and `playback-refused`. |
-| `Launcher::size` | `width` / `height` in the `KuiRunConfig` `kui_run_with` takes | `width` / `height` in the `Run_Config` `kui.run` takes | `width` / `height` in `WindowOptions` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The window's opening size; `min_size` / `max_size` / `chrome` / `text_aa` / `diagnostics` / `frame_latency` are the rest of the set, and each binding's form carries them all (`min_w`, `chrome`, `text_aa`, `diagnostics`, `frame_latency` in C; `minWidth`, `chrome`, `textAa`, `diagnostics`, `frameLatency` in Node). `Launcher::devtools` and `Launcher::core` are the two the others reach another way: `kui_set_devtools` / `setDevtools` on the context, and the context handed to `kui_run_with` *is* the core. |
+| `Launcher::size` | `width` / `height` in the `KuiRunConfig` `kui_run_with` takes | `width` / `height` in the `Run_Config` `kui.run` takes | `width` / `height` in `WindowOptions` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The window's opening size; `min_size` / `max_size` / `chrome` / `text_aa` / `diagnostics` / `frame_latency` / `backdrop` are the rest of the set, and each binding's form carries them all (`min_w`, `chrome`, `text_aa`, `diagnostics`, `frame_latency`, `backdrop` in C and Odin; `minWidth`, `chrome`, `textAa`, `diagnostics`, `frameLatency`, `backdrop` in Node). `Launcher::devtools` and `Launcher::core` are the two the others reach another way: `kui_set_devtools` / `setDevtools` on the context, and the context handed to `kui_run_with` *is* the core. |
 | `Launcher::icon` | `kui_set_icon` | `set_icon` | `icon` in `WindowOptions` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The icon every window of the app is created with — RGBA pixels and their size — shown by Windows in the title bar, Alt-Tab and the taskbar and by X11's window manager; macOS (the bundle's `.icns`) and Wayland (the `.desktop` file's) have no window icon (backlog F86). `Launcher::icon_resource` is the Windows executable's own icon resource, which wins there — C's `resource` argument, Node's `icon.resource`. C's is a free function called before `kui_run`, for `kui_on_teardown`'s reason. |
 | `App::teardown` | `kui_on_teardown` | the `teardown` procedure `kui.run` takes | `KuiWindow.onTeardown` | *none: a script is a guest in the host's frame (ADR 0014): its env is the view's reading, and registering, driving, pacing and reading back are the host's* | The window going for good — its close button, Quit from the menu or the dock, a close command on it, a pumped runner ended — heard once, before `run` returns or the process exits, with nothing drawing: the place to keep what the app would lose with the window (backlog F74, the other two hosts under RG1). On macOS a Quit ends the process from inside the loop, so this is the only thing an app runs on ⌘Q — nothing after `run`, `kui_run` or `await runWindowed(...)` does, not even `process.on('exit')`. C's is a free function called before `kui_run`, with the run's `user`, since `kui_run`'s app is three arguments and not a struct. Node's is the window's door, called from inside the pump that saw the window go; `runWindowed` registers its config's `teardown(model)` there, and `createApp`'s `app.teardown()` runs the same one for a headless drive. |