kerfjs 5.0.0-beta.11 → 5.0.0-beta.111

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/CHANGELOG.md +2981 -107
  2. package/README.md +96 -37
  3. package/ai/cursorrules +111 -62
  4. package/ai/manifest.json +17 -7
  5. package/ai/skill.md +121 -76
  6. package/dist/actions.d.ts +1 -1
  7. package/dist/actions.js +10 -6
  8. package/dist/actions.js.map +1 -1
  9. package/dist/array-signal.js +1 -1
  10. package/dist/async.js +24 -21
  11. package/dist/async.js.map +1 -1
  12. package/dist/attach.js +1 -66
  13. package/dist/attach.js.map +1 -1
  14. package/dist/{chunk-HW7KSM2Y.js → chunk-3C6F6NM4.js} +1 -1
  15. package/dist/{chunk-HW7KSM2Y.js.map → chunk-3C6F6NM4.js.map} +1 -1
  16. package/dist/{chunk-GY4XV2UV.js → chunk-4TX6YJDM.js} +10 -3
  17. package/dist/chunk-4TX6YJDM.js.map +1 -0
  18. package/dist/{chunk-QIP723L4.js → chunk-5WRGJZV6.js} +3 -2
  19. package/dist/chunk-5WRGJZV6.js.map +1 -0
  20. package/dist/{chunk-V46JKE44.js → chunk-6LXUC4ZY.js} +29 -2
  21. package/dist/chunk-6LXUC4ZY.js.map +1 -0
  22. package/dist/{chunk-KZJXHFIB.js → chunk-BI4HGICV.js} +3 -3
  23. package/dist/chunk-BI4HGICV.js.map +1 -0
  24. package/dist/chunk-FM6N2B4N.js +70 -0
  25. package/dist/chunk-FM6N2B4N.js.map +1 -0
  26. package/dist/{chunk-LVH3GC6B.js → chunk-H7WTRM6F.js} +3 -3
  27. package/dist/chunk-H7WTRM6F.js.map +1 -0
  28. package/dist/{chunk-U6FK33SG.js → chunk-IHMDBBUJ.js} +2 -2
  29. package/dist/chunk-IHMDBBUJ.js.map +1 -0
  30. package/dist/chunk-JN7EJM3B.js +86 -0
  31. package/dist/chunk-JN7EJM3B.js.map +1 -0
  32. package/dist/{chunk-UZJ6I4T6.js → chunk-MK42GLPV.js} +1 -1
  33. package/dist/chunk-MK42GLPV.js.map +1 -0
  34. package/dist/{chunk-ZDCJZCNO.js → chunk-VX3RCRGG.js} +161 -90
  35. package/dist/chunk-VX3RCRGG.js.map +1 -0
  36. package/dist/{chunk-SVATPF5R.js → chunk-YVBK73GU.js} +612 -178
  37. package/dist/chunk-YVBK73GU.js.map +1 -0
  38. package/dist/{delegate-CL9VTZFb.d.ts → delegate--CrfgYtC.d.ts} +0 -34
  39. package/dist/dev.d.ts +31 -13
  40. package/dist/dev.js +101 -35
  41. package/dist/dev.js.map +1 -1
  42. package/dist/html.js +20 -8
  43. package/dist/html.js.map +1 -1
  44. package/dist/index.d.ts +14 -9
  45. package/dist/index.js +29 -20
  46. package/dist/index.js.map +1 -1
  47. package/dist/jsx-runtime.d.ts +22 -7
  48. package/dist/jsx-runtime.js +1 -1
  49. package/dist/list.d.ts +7 -3
  50. package/dist/list.js +153 -46
  51. package/dist/list.js.map +1 -1
  52. package/dist/overlay.d.ts +278 -133
  53. package/dist/overlay.js +1034 -368
  54. package/dist/overlay.js.map +1 -1
  55. package/dist/remount.js +2 -2
  56. package/dist/router.d.ts +13 -4
  57. package/dist/router.js +37 -10
  58. package/dist/router.js.map +1 -1
  59. package/dist/scope.d.ts +35 -8
  60. package/dist/scope.js +61 -30
  61. package/dist/scope.js.map +1 -1
  62. package/dist/testing.js +1 -1
  63. package/dist/timing.d.ts +3 -2
  64. package/dist/timing.js +1 -1
  65. package/dist/timing.js.map +1 -1
  66. package/llms.txt +14 -6
  67. package/package.json +35 -8
  68. package/setup/cli.mjs +90 -0
  69. package/setup/index.d.mts +37 -0
  70. package/setup/index.mjs +1347 -0
  71. package/setup/jsonc.mjs +201 -0
  72. package/setup/state.schema.json +56 -0
  73. package/dist/chunk-GY4XV2UV.js.map +0 -1
  74. package/dist/chunk-KPXIOG2C.js +0 -54
  75. package/dist/chunk-KPXIOG2C.js.map +0 -1
  76. package/dist/chunk-KZJXHFIB.js.map +0 -1
  77. package/dist/chunk-LVH3GC6B.js.map +0 -1
  78. package/dist/chunk-QIP723L4.js.map +0 -1
  79. package/dist/chunk-SVATPF5R.js.map +0 -1
  80. package/dist/chunk-U6FK33SG.js.map +0 -1
  81. package/dist/chunk-UZJ6I4T6.js.map +0 -1
  82. package/dist/chunk-V46JKE44.js.map +0 -1
  83. package/dist/chunk-ZDCJZCNO.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -6,6 +6,2959 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ### Added
10
+
11
+ - **`DialogSurface` `closeEmphasis`.** Set it to `quiet` for a smaller, quieter close glyph within the existing 40px native button. Accessible naming, focus, forced colors, and close requests remain intact; `normal` keeps the established default (`KF-GJ4GTJ`).
12
+ - **`Button` `currentStep`.** A setup or progress step can mark its native button or link with `aria-current="step"` through a typed prop, including when disabled, without changing its label or visual state (`KF-TGEW3B`).
13
+ - **`each()` keeps a uniquely keyed row across item-object replacement.** Replacing an item with a new object that renders the same unique `id` or `data-key` now morphs its same-tag row in place, including during a reorder, so live children such as an open popover anchor stay connected. Ambiguous keys and tag changes still replace the row; the per-item HTML cache remains based on object identity (`KF-GS850A`).
14
+ - **Kerf Button in TabBar action zones.** The published TabBar composition contract now accepts one standalone Kerf `Button` in either `trailing` or `end`, alongside the existing `ToolbarControlGroup` and `wa-button` cases. The catalog, doctor, and examples agree with the already supported rendering and fixed action placement (`KF-535H1M`: TabBar Kerf Button composition).
15
+ - **`--kui-color-brand`.** An application sets one opt-in token on `:root` to change its brand: Kerf derives the brand fill (and the quiet and normal fills and borders mixed from it), on-loud text, brand text and links, brand text on brand fills, and the focus ring, clamping lightness so every pair keeps WCAG AA for any hue and chroma; Web Awesome's `--wa-color-brand-*` and `--wa-color-focus` follow. Unset, every brand token keeps its tuned default exactly. Previously an app that overrode only the brand fill kept the default blue brand text and focus ring (`KF-EM1T5S`).
16
+ - **A wrapped `Toolbar` keeps its height beside a long scroller.** In a `List` shell (a filling List holding a `Toolbar` above a `flex` `scrollable` List), a toolbar that wraps or stacks onto two rows at a phone width no longer shrinks to one control band when the scroller below holds a long page, which clipped its second row. A Toolbar in a List no longer shrinks; the app wrapper (`List flex="none"`) is unnecessary (`KF-0A7B8D`).
17
+ - **`wireWorkbench` focuses an overlay opened from an external toggle.** An overlay rail or drawer opened from a persistent toggle outside the Workbench (an app-bar button whose `aria-controls` names the panel) now receives focus once it becomes focusable. Previously the opening `focus()` ran while the app's render had not yet shown the panel, and the only retry waited for the Workbench's own toggle to be removed, so focus stayed on the toggle behind the overlay. Focus the person has moved elsewhere is never taken (`KF-7QMRFN`).
18
+ - **`ToolbarControlGroup` `visibility="yield-to-priority-row"`.** A trailing group yields exactly while its Toolbar's `responsive="trailing-priority"` row is active, from the same container query as the row at the Toolbar's `responsiveAt`, so an app no longer restates that breakpoint with `hideBelow`. `hideBelow` is strict where the Toolbar's widths are inclusive, so at exactly 704px the row was active while `hideBelow={rem(44)}` still showed the group, which wrapped onto a third row. The contract and selection docs now say so (`KF-Y19A2V`).
19
+ - **A `fill` SearchField keeps a `sizing="grow"` group's basis.** Opening a collapsible `fill` SearchField inside a `ToolbarControlGroup` with `sizing="grow"` no longer makes the group take the whole line, which wrapped every sibling group onto a second row at any toolbar width; the grow basis sizes the group, and `fill` fills the group (`KF-3P3GNH`).
20
+ - **`Toolbar` and `List` `id`; `Chip` `rootAttributes`.** `Toolbar` and `List` take an `id`, so a toolbar above a scrolling list can be named as its chrome in `wireScrollDividers({ targets })` instead of falling back to a permanent `dividerSides`. `Chip` takes safe `data-*` `rootAttributes` on its plain, link, and action roots, for tests and delegated handlers; Chip-owned attributes stay protected (`KF-Q2MKX9`).
21
+ - **`DialogSurface` `alert`.** `alert` marks a confirmation before a destructive action as an alert dialog: the native `<dialog>` renders `role="alertdialog"`, described by its message through `describedBy`. A `rootAttributes` role is still ignored. The catalog shows an Alert Dialog example (`KF-Z0EFSY`).
22
+ - **`SegmentedControl` `disabled`.** A group-level `disabled` makes the whole control unavailable: every segment is disabled and dimmed like an author-disabled choice, the current selection stays visible, and the group reports `aria-disabled`. A choice's own `disabled` still disables just that segment, and a disabled control's `placeholder` stays dimmed. The catalog shows a Disabled example (`KF-DJN15J`).
23
+ - **`KUI-L204`: inset-bearing children inside an embedded `Disclosure`.** `kerf-ui-doctor` (through `eslint-plugin-kerfjs`'s `ui-composition` rule) now reports a block `Text`, or any other child whose catalog geometry owns its margin, border, and padding, written directly inside `Disclosure appearance="embedded"`, where it re-adds the 1px border and 8px padding the owner chrome already provides; the message names `Text flush` / `variant="span"` or inline content as the fix. The check is catalog-driven: composition entries declare `insetFreeChildren` (prop conditions under which direct children must be inset-free) and `insetFreeWhen` (a child's inset-free forms), so a third-party catalog can declare the same contract (`KF-E8PGDQ`).
24
+ - **Inset-free metadata in `create-kerf-component`.** A component package's `kerf.components.json` can now declare `composition.insetFreeChildren` (prop conditions under which a container's direct children must bring no content-item inset) and `composition.insetFreeWhen` (a component's own inset-free forms). `kerf-component-catalog` validates each `{ prop, equals }` condition at its exact metadata path, accepting the same shapes as `@kerfjs/ui`'s catalog validator, and copies both fields into the generated `component-composition.json`, so `kerf-ui-doctor` reports `KUI-L204` for a package-declared inset-free container (`KF-3CCTAQ`).
25
+ - **`Button` `fill`.** `fill` spans a Button across its parent's available inline width instead of sizing it to its label, for a full-width primary action in a form, sheet, or narrow column; it is the same `fill` `SplitButton` takes. The icon and label stay centered as one group, the label ellipsizes once the column is narrower than it, a link Button (`href`) fills the same way, and the default outside focus ring and `focusRingInset` keep their geometry. `data-fill` is protected from `rootAttributes`. The catalog's Button demo and design template show a Full-Width Primary Action (`KF-FXKCHW`).
26
+ - **`Disclosure` `appearance="embedded"`.** A Disclosure inside a `ContentItem` (or other chrome that already owns the content-item inset) no longer frames its content twice: `embedded` drops the Disclosure's own 8px inline margin, 1px border, and 8px summary padding, so the summary row and its `DisclosureArrow` sit on the item's content inset, and the summary becomes a compact 24px-minimum row without a hover fill. The native `<details>` state, Enter/Space toggling, and the arrow's rotation are unchanged; the content (a `flush` `Text`) starts on the title's text column 8px below the summary. The UX catalog shows it in a framed ContentItem (`KF-2JTH1A`).
27
+ - **`ListHeader` `wrap`.** A `ListHeader` label is one ellipsized line by default; `wrap` breaks it onto further lines instead, for a heading whose whole label must stay readable in a narrow column. Wrapped lines keep a 4px block inset inside the unchanged minimum height, and `data-wrap` is protected from `rootAttributes` (`KF-12WBGR`).
28
+ - **`openPopupMenuAt` placement.** `openPopupMenuAt(menu, x, y, { placement })` takes an optional `PopupMenuPlacement` for that opening, so a button-triggered menu (a `ListActionRow` trailing menu opened from the row's `contextmenu`) can open `top-start` above the pointer instead of `bottom-start` below it; the viewport flip, shift, and height cap still apply, and the next opening returns to its trigger and its own placement. Omitted, nothing changes: a button-triggered menu opens `bottom-start` at the point and a context menu at its `placement` (`KF-QGT77X`).
29
+ - **`Button` and `SplitButton` `focusRingInset`.** Inside an ancestor that clips overflow, `focusRingInset` draws the focus ring inside the box (each half's, on a SplitButton) instead of 1px outside it, the same option `Select` takes. The inset ring is two-tone, a 3px surface-colored line inside the ring color, so it keeps 3:1 contrast on a loud fill of its own hue (a single-color inset ring measured 1.0:1 on the brand fill); `data-focus-ring-inset` is protected from `rootAttributes`. The default outside ring is unchanged (`KF-BZE90H`). The line paints the surface the control sits on, through a new foundation surface context (`--kui-color-surface-current`, `--kui-color-surface-current-region`, `--kui-color-surface-current-tint`) that `SunkenPanel`, sunken `Disclosure`, `FramedList`, quiet `ContentItem`s, `List` `surface`, `AnchoredSurface`, dialogs, and sunken `Pane`/`Workbench`/`TabNavigator` regions publish on their own elements, so on a lowered or tinted surface it no longer reads as a light halo (`KF-40SSN2`). Highlighted `FramedList` rows, `TabBar` strips, `Pane` and `TabNavigator` app `background` colors, and glass chrome at rest (overlay Pane headers, NavStack chrome and bottom toolbars, TabNavigator bars, floating dialog headers) publish it too (`KF-MWN5CW`).
30
+ - **Dialog accessible descriptions.** `DialogSurface` takes an optional `describedBy` id, rendered as `aria-describedby` on its native `<dialog>`, so a modal dialog can name its heading `ToolbarText`'s `descriptionId` or app-owned summary copy in its body as its accessible description; `rootAttributes` still takes only `data-*` attributes and cannot set it. `WorkbenchDialog` now describes itself by its title `description` automatically (id `<id>-description`) and takes `describedBy` for other content; `ListDetailDialog` takes `describedBy` (its detail description describes the selection, not the dialog). The catalog's Viewport-Bounded Modal and Floating Title Bar dialogs demonstrate it (`KF-JNV47V`).
31
+ - **`CheckboxGroup` in `@kerfjs/ui`.** `@kerfjs/ui/checkbox-group` puts a labeled set of related options in a native fieldset of `Checkbox`es: a `choices` array with per-choice hints and disabled choices, an array `value` of checked values that all submit under `name`, a group `hint` and `error` (marking the group invalid), `default` or `compact` size, and a stacked or wrapping horizontal `orientation`. It is named by `label`, `ariaLabel`, or `labelledBy` and laid out exactly like `RadioGroup`: each box on the inline-start edge, choices at the shared 28px pitch, hints on the label column. `wa-checkbox-group` now points to it (`KF-JJ80V3`).
32
+ - **`SplitButton` `shape`.** `shape="pill"` fully rounds both outer ends of a SplitButton, the same `rounded` (default) or `pill` choice `Button` takes; the divider between the halves stays square, and each half's hover fill and focus ring follow its rounded end (`KF-4GC1J4`).
33
+ - **`wirePaneChrome`.** `@kerfjs/ui/wire-pane-chrome` makes a Pane's open `overlay` compact chrome transient: Escape or a press outside it closes it through the app's `compactChromeOpen` signals, and focus returns to the control that opened it (`KF-EEGAT7`).
34
+ - **ChoiceChips icon picker.** `presentation="icons"` renders square 36px icon-only choices, each named by its label (hidden, and its hover title), and `maxHeight` scrolls a long grid, with native radio (or toggle, or listbox) semantics unchanged (`KF-K60RRM`).
35
+ - **`Pane` `compactChrome`.** A Pane declares what its header and footer do when its container presents compactly: `fixed` (default), `scroll` (inline with the content; a footer settles at the end and scrolls past long content), or `overlay` (over the content on the chrome material, shown while the app's `compactChromeOpen` says so). NavStack views, TabNavigator scenes, full-screen dialogs, and compact Workbenches apply it; roomy containers ignore it. `PaneConfig` forwards both props (`KF-Q8EMWE`). The UX catalog's NavStack Compact Chrome example now pushes a message thread from each row, whose own Pane scrolls its sender line away and keeps its reply hint fixed, so the policy visibly applies per view as the stack pushes and pops (`KF-C891G3`).
36
+ - **Vertical `Slider`.** `orientation="vertical"` stands a Slider up with its minimum at the bottom, `length` tall (default 160px), drawn the same in Chromium, Firefox, and WebKit; the AnchoredSurface media volume popup is vertical again (`KF-SVDPSR`).
37
+ - **`FileDropZone` `dropScope`.** A selector for an enclosing element (an attachments panel) that also takes drops: `wireFilePickers` highlights the zone while files are dragged over any part of it and reports drops there for the zone with `via: 'drop'`, so an app no longer writes the zone's `data-dragging` itself (`KF-HNRWM9`).
38
+ - **`PopupMenu` `triggerContent`.** App content, such as a `Badge` showing a status, can be the whole trigger: Kerf owns the bare button around it (no chrome, a pill focus ring, the pointer cursor, `aria-haspopup`), `label` names it, the caret is off by default, and no help tag repeats the name. Submenus and checked choices work as on any PopupMenu (`KF-PHGQ6D`).
39
+ - **Corner count badges.** `Badge` takes `placement="corner"` to straddle the top-trailing corner of the control it sits in (an icon-only `Button` or a button in a `ToolbarControlGroup`, which positions itself for it). `Button` takes `badge` (a count, short text, or `true` for a dot), `badgeLabel` (added to the button's name; the count stays out of it otherwise), and `badgeTone` (default `danger`) (`KF-WT2EMZ`).
40
+ - **`Text` `size="medium"`.** A heading at the 16px body size keeps its heading weight and wraps, for an in-list group title with a long user-authored name (`KF-43XH56`).
41
+ - **`List` `contentWidth` and `contentAlign`.** A page column caps its content at a readable measure (`compact` 440px, `medium` 640px, `wide` 864px) plus its own insets and centers it (or keeps it at the start), composing with `inset="document"`, so a settings page needs no application `max-width` CSS (`KF-P3069N`).
42
+ - **`Select` `maxTriggerWidth` and `minTriggerWidth`.** Typed `CssLength` bounds on the closed trigger under any presentation (title and inline included). The value or `renderSelected` content ellipsizes inside the cap and the caret stays, so an app no longer wraps a Select in its own sized element (`KF-DQANHZ`).
43
+ - **`LucideIcon` `title`.** An icon takes hover text as an SVG `<title>` over its whole box (not just its strokes), so a labeled status icon carries its own explanation without an application wrapper (`KF-2V9XJQ`).
44
+ - **`Button` `title`.** A Button takes native hover text that says more than its name ("Delete the Selected Draft" on an icon-only Delete). An icon-only Button already shows its `ariaLabel` as a help tag; a `title` replaces that tag (`KF-8MYB8B`).
45
+ - **`WorkbenchDialog` in `@kerfjs/ui`, the modal workbench dialog type.** `@kerfjs/ui/workbench-dialog` renders a header-less modal around a `Workbench`. The work area's toolbar carries the dialog's title, actions, and close control; the side rails keep their own toolbars and run the dialog's full height. On compact devices the dialog fills the screen and its rails become overlays over the work area, shown by their toolbar toggles; with `wireWorkbench`, Escape closes an open rail before the dialog (`KF-Q9ERQ6`).
46
+ - `WorkbenchMainToolbar` gains `end`: groups after a hidden right rail's relocated toggle, so a dialog's close control stays outermost.
47
+ - **`ColorField` in `@kerfjs/ui`.** `@kerfjs/ui/color-field` puts a color in a form or inspector: a label above a trigger that shows the color as a swatch (over a checkerboard) and its hex value, with a hint or error, compact size, and a hidden input under `name`.
48
+ - `wireColorFields(root, { onInput, onChange, pickers })` (`@kerfjs/ui/wire-color-fields`) opens a `ColorPicker` in an `AnchoredSurface` below the trigger, with per-field presets and samples. Edits preview on the trigger at once; Escape or a press outside closes the picker and returns focus.
49
+ - `wa-color-picker` is now `Discouraged` (47 in all), and the profile defaults avoid it (`KF-PZBW7F`).
50
+ - **`ColorPicker` in `@kerfjs/ui`.** `@kerfjs/ui/color-picker` is a full inline picker: a saturation and brightness area, hue and opacity sliders, an RGB/HSL/HSB/Grayscale model menu with channel fields, a hex field (8 digits below full opacity), an opacity field, a screen sampler where the EyeDropper API exists, and optional preset and sample swatches with an "Add to Samples" action.
51
+ - `wireColorPickers(root, { onInput, onChange })` (`@kerfjs/ui/wire-color-pickers`) makes it interactive: pointer drags and arrow keys on the area, native range sliders, field commits, model switching, and swatches.
52
+ - Each change reports `#rrggbb` or `#rrggbbaa` through bubbling `kui-color-input`/`kui-color-change` events and the callbacks, and the picker adopts a new controlled value.
53
+ - Hue survives gray colors, and conversions round-trip without drift (`KF-HBE31H`).
54
+ - **`ColorSwatches` in `@kerfjs/ui`.** `@kerfjs/ui/color-swatches` chooses one color from a fixed palette. It is a native radio group of round swatches with no visible text: one Tab stop, arrow keys to move, and the chosen value submitted under `name`. Each swatch is named by its color label, also shown as its hover hint. The chosen swatch wears a ring in the text color, so the choice never depends on hue. A `'transparent'` swatch offers no color. It has `default` and `compact` sizes, a disabled state, and the shared block-content inset (`KF-E4GC0B`).
55
+ - **`TagField` in `@kerfjs/ui`.** `@kerfjs/ui/tag-field` collects short values as removable tags, each submitted as a hidden input under `name`. It is built on SearchField's token editor in its `form-field` presentation, with a label, a hint or `error`, a tag glyph, a clear button, `max`, and `required`/`disabled`.
56
+ - `wireTagFields(root, { onChange })` (`@kerfjs/ui/wire-tag-fields`) adds a tag on Enter or a delimiter (and several from pasted text), and adds the typed text on Tab or when focus leaves the editor.
57
+ - It enforces duplicates, `max`, and `normalize`, reporting each refusal to `onReject`.
58
+ - Removing: a chip's × or Backspace at the start removes a tag, a chip's label moves it back to edit, and the clear button empties the list.
59
+ - Moving: arrows move between the chips and the editor. A `wireSearchFields` on the same root leaves a TagField's keys to `wireTagFields`.
60
+ - `wa-tag-input` is now `Discouraged` (46 in all), and the profile defaults avoid it (`KF-PZ5J93`).
61
+ - **`Slider` in `@kerfjs/ui`.** `@kerfjs/ui/slider` is a native `<input type="range">` drawn as a track, a brand fill up to the value, and a round thumb, the same in Chromium, Firefox, and WebKit. It has a label row, an optional live readout (`showValue`, `unit`, also spoken as the value text), labeled `ticks`, a `hint`, a `compact` size, and a disabled state. It fills its width on the shared block-content inset. `wireSliders(root)` (`@kerfjs/ui/wire-sliders`) keeps the fill and readout in step with a drag before the app re-renders. `wa-slider` is now `Discouraged` (45 in all), and the profile defaults avoid it (`KF-0R9G4Y`).
62
+ - **`ProgressBar` and `ProgressRing` in `@kerfjs/ui`.**
63
+ - `@kerfjs/ui/progress-bar` is a native `<progress>`. It is determinate (`value` of `max`) or, without a `value`, an indeterminate sweep. A visible `label` names it through `aria-labelledby`, or `ariaLabel` does without one. `showValue` adds a readout, and `valueText` replaces the spoken percentage. It takes brand and status `tone`s and a `compact` 4px track.
64
+ - `@kerfjs/ui/progress-ring` is an SVG `role="progressbar"` in `small`, `medium`, and `large` sizes for a line of text, a row, or a toolbar. It is determinate (filling clockwise from the top) or a spinning arc.
65
+ - Both hold still under reduced motion and draw `Highlight` fills in forced colors.
66
+ - `wa-progress-bar` and `wa-progress-ring` are now `Discouraged` (44 in all), and the profile defaults avoid them (`KF-87B2KV`).
67
+ - **`Disclosure` in `@kerfjs/ui`.** `@kerfjs/ui/disclosure` renders a native `<details>` whose `<summary>` carries a `DisclosureArrow`, a title, and an optional quiet `detail`. It sits on the shared content-item geometry, with `plain`, `framed`, and `sunken` appearances, and Kerf block content lands on the title's text column. Disclosures that share a `name` form a native exclusive accordion. The open state is the platform's: `open` renders it open, a re-render never closes it, and the arrow follows the live state; `toggleAction` names it for a captured `toggle` listener. It neutralizes page-wide `<details>` styling such as Web Awesome's `native.css`. `wa-details`, `wa-accordion`, and `wa-accordion-item` are now `Discouraged` (42 in all), and the profile defaults avoid them (`KF-CXCQE9`).
68
+ - **Styled tooltips for `kerfjs/overlay`'s `tooltip()` in `@kerfjs/ui`.** Import `@kerfjs/ui/overlay-tooltip.css` once. A tooltip on any element then takes the help tag's look (loud neutral fill, on-loud 14px text, 3px radius), wraps at 40 characters, never takes the pointer, fades in on its own, and fades out through `exitClass: 'kui-tooltip-exit'` with `exitDuration: 100`. Reduced motion, the static-effects switch, and forced colors are handled. `wa-tooltip` is now `Discouraged` (39 in all), and the package profile defaults avoid it (`KF-VKDRWA`).
69
+ - **Styled toasts for `kerfjs/overlay`'s `toast()` in `@kerfjs/ui`.** Import `@kerfjs/ui/overlay-toast.css` once. Toasts then stack above the bottom edge, clear of the safe area, at most 480px wide, on the raised surface. They take `variant` tones, take the chrome of a `StateBanner` passed as their only content, rise in on their own, and leave through `exitClass: 'kui-toast-exit'` with `exitDuration: 200`. Reduced motion, the static-effects switch, and forced colors are handled. Put `data-placement="top"` on an app-owned region to stack from the top. `wa-toast` and `wa-toast-item` are now `Discouraged` (38 in all), and the package profile defaults avoid them, so `KUI-L301` reports them (`KF-FYTF2Z`).
70
+ - **`ListDetailDialog` in `@kerfjs/ui`, the modal list-detail dialog type.** `@kerfjs/ui/list-detail-dialog` renders a modal whose list and detail columns each run its full height, so the divider runs from top to bottom. The list column carries its own default-size title and controls (`list.title`, `list.toolbar`). The detail column carries the dialog's primary xl title, its `actions`, and the close control, and each column has a pinned `footer`. Pass `compact` from `deviceClass()` and it becomes a full-screen `NavStack` drill-down (`detailActive`, `backLabel`), keeping the close control on every view. It replaces wrapping a `SplitView` in a `DialogSurface` by hand, whose header spanned both columns. The List-detail dialog recipe and the catalog use it. `SplitViewCompactViewToolbars` now also takes a `footer` (`KF-P9VSX1`, `KF-ZZRDDY`, `KF-HZHG4X`).
71
+ - **Non-selectable rows and a single Tab stop for multi-select `List` and `Grid` in `@kerfjs/ui`.** A non-interactive `ContentItem` with `gridRow` renders `role="row"` around a `gridcell`, with no `aria-selected` and no Tab stop. It holds content between selectable rows, such as an activity group or a "messages skipped" divider, so apps no longer hand-write grid roles. `wireContentItems` now makes each multi-select grid one Tab stop through a roving `tabindex`: the last focused row, else the first selected, else the first enabled. The stop survives re-renders. Arrow keys skip non-selectable rows, whose controls stay reachable by Tab (`KF-RAEXQ7`).
72
+ - **Desktop multi-select for `ChoiceChips`, `List`, and `Grid` in `@kerfjs/ui`.** `ChoiceChips` takes `multiple?: boolean | 'toggle'`. With `multiple: true` the group becomes an ARIA multi-select listbox: a click selects one chip, Cmd (Apple platforms) or Ctrl (elsewhere) toggles one, and Shift extends a range. It is one Tab stop: arrows, Home, and End move the selection, Shift with them extends it, Cmd/Ctrl with them moves focus alone, Space toggles, and Cmd/Ctrl+A selects all. Hidden inputs submit each selected value. Wire it with `wireChoiceChips` (`@kerfjs/ui/wire-choice-chips`), which fires `change` on the group; `readChoiceChips` returns the set. The same model is public as `applySelection`, `selectionGesture`, and `isApplePlatform` (`@kerfjs/ui/selection`) for `List`/`Grid` `selectionMode="multiple"` cards, whose activations carry their modifier keys. Without an anchor, a Shift range starts at the first selected item. **Breaking:** the checkbox behavior that `multiple: true` used to select is now `multiple: 'toggle'` (`KF-346HEG`).
73
+ - **`Catalog` secondary groups can hide tagged entries behind a switch.** `CatalogSecondaryGroup` takes an optional `tagFilter: { tag, label, show }`. It adds a compact `Switch` at the top of the open group, and entries carrying `tag` (plus any section they would leave empty) stay hidden until `show` is true. The active entry is always listed. The app owns `show`, and `wireCatalog` reports the switch through `onToggleSecondaryFilter(show)` (action `catalog-toggle-secondary-filter`, configurable with `toggleSecondaryFilterAction`). The UX catalog uses it to hide `Discouraged` Web Awesome entries by default (`KF-8M9QTZ`).
74
+ - **More Web Awesome elements are `Discouraged` in `@kerfjs/ui`.** A review against what Kerf now provides tags six more elements a Kerf component replaces, and moves `wa-button-group` from conditional to avoid: `wa-popover` and `wa-popup` (use `AnchoredSurface`, or `positionAnchored()` from `kerfjs/overlay`), `wa-callout` (`StateBanner`), `wa-card` (`ContentItem` or `SunkenPanel`), `wa-drawer` (`DialogSurface`'s side or bottom sheet, or `CollapsiblePanel`), and `wa-page` (`Workbench`, `SplitView`, `NavStack`, or `TabNavigator`). 34 elements are now `Discouraged`, and the package profile defaults avoid each new one, so `KUI-L301` reports it. `wa-tooltip`, `wa-toast`, and `wa-toast-item` followed once `@kerfjs/ui/overlay-tooltip.css` and `@kerfjs/ui/overlay-toast.css` shipped. The UX catalog's own demos no longer render `wa-card` (`KF-AJFRTE`).
75
+ - **Web Awesome 3.14 elements in the `@kerfjs/ui` catalog.** The optional Web Awesome peer range is now `^3.14.0` (was `^3.12.0`), and the catalog, the `@kerfjs/ui/webawesome` JSX declarations, and the UX catalog's Web Awesome Integration section cover the three elements 3.14 adds: `wa-stepper` and `wa-step` (a multi-step process indicator) and `wa-tag-input` (a form field that submits a list of tags). No Kerf component replaces them, so they are supported integration elements and `KUI-L301`'s profile defaults are unchanged; `wa-tag-input`'s entry points search filters to `TokenSearchField` (`KF-38B7VP`).
76
+ - **Keyboard multi-selection through `wireContentItems`.** Enter and Space on an interactive `ContentItem` now activate it with a click that carries the key's Shift, Ctrl, and Cmd state (Space uses the state at press), and Ctrl- or Cmd-modified Enter and Space are no longer ignored. One delegated click handler that reads `shiftKey`, `ctrlKey`, and `metaKey` now serves range and toggle selection for keyboard and pointer alike. Alt-modified keys are still left to the platform (`KF-45RNDS`).
77
+ - **Design templates for `@kerfjs/ui`'s native form controls.** `docs/design/templates/` now has light and dark SVG templates for `Button`, `TextField`, `Checkbox`, `RadioGroup`, `Switch`, and `Select`, linked from each catalog detail. `Button` now resets the platform's native button appearance like the other Kerf controls; it renders pixel-identically in Chromium, Firefox, and WebKit, and its templates capture as vectors (`KF-97MFYM`).
78
+ - `kerf-ui-doctor`'s `KUI-D040` title-style check now reads Kerf's native form components: the `label` and `ariaLabel` of `TextField`, `Select`, and `RadioGroup`, `TextField`'s `clearLabel`, and the text of a `Button`. `Checkbox` and `Switch` labels and `RadioGroup` choice labels are option text, which stays sentence style and is not read, as before for `wa-checkbox`, `wa-switch`, and `wa-radio` (`KF-MPXMSX`).
79
+ - **`@kerfjs/ui` guidance treats Web Awesome as an optional integration.** Kerf components and native elements are now the only default answer. The catalog tags the 28 Web Awesome elements a Kerf component replaces `Discouraged` (newly `wa-button`, `wa-input`, `wa-textarea`, `wa-checkbox`, `wa-checkbox-group`, `wa-radio`, `wa-radio-group`, `wa-switch`, `wa-dialog`, `wa-tag`, `wa-badge`, `wa-spinner`, and `wa-skeleton`) and lists all 70 under a collapsed `Web Awesome Integration` sidebar section. The package profile defaults avoid each replaced element, so `KUI-L301` (`ui-preferences`, also run by `kerf-ui-doctor`) reports a raw tag and names its Kerf replacement. The selection guide, AI skill, `llms.txt`, design philosophy, and theme contract no longer send applications to `wa-*` when no Kerf component fits. A new migration guide (`docs/webawesome-migration.md`) maps every replaced element to its Kerf component and lists the steps to remove Web Awesome (`KF-F52B04`).
80
+ - **`@kerfjs/ui` no longer needs Web Awesome anywhere.** `@awesome.me/webawesome` stays an optional peer, and `@kerfjs/ui/webawesome.css` (with the type-only `@kerfjs/ui/webawesome`) is now the only entry that touches it. Every Kerf component stylesheet reads only `--kui-*` tokens (`TokenSearchField`, `Text`'s field label and list-header heading, and `Composer` no longer read `--wa-*` variables, three of them without a fallback). `foundation.css` keeps no `wa-*` selectors, and the two tokens whose standalone fallback differed from the Kerf theme now match it: `--kui-font-weight-semibold` falls back to 500 (was 650) and `--kui-font-sans` to `ui-sans-serif, system-ui, sans-serif`. A Kerf-only application renders exactly like the catalog; consumer-bundle tests and a browser parity spec enforce it (`KF-3558JM`).
81
+ - **`Checkbox`, `RadioGroup`, and `Switch` for `@kerfjs/ui`.** Kerf's own toggles instead of `wa-checkbox`, `wa-radio-group` / `wa-radio`, and `wa-switch`: native inputs inside their labels, drawn as a box, circle, or track that matches the old look in every engine and scheme, with `hint` and `error` text on the label column (the input's or group's `aria-description`; an error sets `aria-invalid`), `disabled`, `name`/`value`/`form`, a delegated `action`, and a default or compact size. `Checkbox` takes `checked`, `required`, and `indeterminate` (`wireCheckboxes(root)` from `@kerfjs/ui/wire-checkboxes` sets the native mixed state); `RadioGroup` is a fieldset named by `label` or `ariaLabel` over a `choices` array (per-choice `hint` and `disabled`), stacked or `orientation="horizontal"`, with `value` and `required`; `Switch` is a `role="switch"` checkbox for settings that apply immediately (`KF-5RCPT6`).
82
+ - **`TextField` for `@kerfjs/ui`.** A text field, Kerf's own instead of `wa-input` and `wa-textarea`: a native `<input>` (or, with `multiline`, a `<textarea>`) inside one labeled box, named by `label` or `ariaLabel`, with a `hint` and an `error` below it (together its `aria-description`; an error sets `aria-invalid` and draws the danger border), a leading `icon`, a `clearable` button, `rows` and an optional growing `maxRows`, a live `maxLength` count (`showCount`), `type`, `required` (with an asterisk), `disabled`, `readOnly`, and `autocomplete`, at the 44px control height or `size="compact"` (33px, with a 16px text floor on touch screens). `wireTextFields(root)` (`@kerfjs/ui/wire-text-fields`) makes the clear button empty the field and announce `input` and `change`, and keeps counts current. It matches the old `wa-input` look in every engine and scheme, and the catalog demos and recipes use it instead of `wa-input` and `wa-textarea` (`KF-1DHMP9`).
83
+ - **`Button` for `@kerfjs/ui`.** A standalone action button, Kerf's own instead of `wa-button`: a native `<button>` (or, with `href`, a link) in a `tone` (`neutral`, `brand`, `danger`) and an `emphasis` (`primary`, `secondary`, `plain`), at the 44px control height or `size="compact"` (33px), with an optional leading `icon`, `loading` (a spinner in place of the label, which still names it, and `aria-busy`), `disabled`, a form `type` (default `button`, which never submits) with `name`, `value`, and `form`, a delegated `action`, and an icon-only square form (no label, `ariaLabel` required). It matches the old `wa-button` look pixel for pixel in Chromium, Firefox, and WebKit, light and dark, follows the shared `--kui-layout-rounded-radius`, and keeps the control band in a `Toolbar` trailing zone and a `TabBar` action zone. The catalog's demos and recipes use it (and plain `<button>`s inside toolbar groups) instead of `wa-button`. Import `@kerfjs/ui/button` and `@kerfjs/ui/button.css` (`KF-9HV3B2`).
84
+ - **Action `Chip`.** `Chip` takes an `action` (with the existing `itemId`), and its whole body then renders as a native `<button type="button" data-action data-item-id>` for an application's delegated handler, such as a filter token in a search syntax help popover that inserts itself into the query. The button keeps Chip geometry and adds hover, press, `:focus-visible`, and `disabled` states; an optional `actionLabel` names it when the visible label alone is unclear. A compact, rounded action chip in a wrapping `Row` inside a compact `ValueTable` cell keeps the row height of the compact `Badge` it replaces, even with Web Awesome's native button styles loaded. `action` cannot be combined with `href` or `removeAction`, at the type level or at runtime, because nested interactive content is invalid. The Chip catalog shows a search filter table, and the new Chip design templates cover tags and action chips.
85
+
86
+ - **`@kerfjs/ui/overlay-sheet.css`.** An opt-in stylesheet for core `kerfjs/overlay` dialogs presented with `presentation: 'bottom-sheet'`, matching `DialogSurface`'s sheet:
87
+ - the bottom edge, full width up to 560px and centered beyond;
88
+ - square bottom corners under the dialog radius;
89
+ - the 8px surface inset, padded by the larger of the safe area and the core's `--kerf-keyboard-inset`;
90
+ - a cap below the top safe area;
91
+ - a slide up as it opens.
92
+
93
+ The `kui-overlay-sheet-exit` class (passed as `exitClass`) slides it back down as it closes. It covers the plain and `native: true` hosts and honors reduced motion, the static-effects switch, and forced colors.
94
+
95
+ - **Resizable core bottom sheets in `@kerfjs/ui`.** `wireOverlaySheets()` (from `@kerfjs/ui/wire-overlay-sheets`) gives a core `kerfjs/overlay` bottom sheet with the `kui-overlay-sheet-resizable` class the grabber of a resizable `DialogSurface` sheet. It resizes the visible height by drag or keyboard (arrows, Page Up/Down, Home, End), between `--kui-overlay-sheet-min-height` (160px) and the cap, and reports the height in its ARIA values. The grabber sticks to the top edge while the content scrolls and stays first across re-renders. Call it once for each container sheets open in. Covered in Chromium, Firefox, and WebKit.
96
+
97
+ - **Tint accents.** A `@kerfjs/ui` `tint` takes an optional `accent`: `{ color, scheme, accent }`. Inside the scope, the brand ramp re-derives from it: loud fills and their on-loud text, brand text and links, text on brand fills, and the focus ring. Lightness is clamped so every pair keeps WCAG AA for any accent; an accent seed sweep checks this in Chromium, Firefox, and WebKit.
98
+ - **`npm run dev:lan` for device checks.** From the repo root or `ui/`, it serves the `@kerfjs/ui` development catalog on every network interface. It prints the LAN and Tailscale URLs and accepts Tailscale MagicDNS (`*.ts.net`) and mDNS (`*.local`) host names, so a phone can test what a desktop browser cannot: the virtual keyboard, safe areas, and touch. Plain `npm run dev` stays on `127.0.0.1`. The catalog page now sets `viewport-fit=cover`, so a notched phone reports its real safe-area insets. The device checks are listed in `ui/docs/manual-test-plan.md`.
99
+ - **Exit motion for `kerfjs/overlay` dialogs.** `overlay()`, `confirm()`, `prompt()`, `form()`, and `choice()` take `exitClass` / `exitDuration`, named and defaulted like `toast()`'s, so CSS can animate an overlay out (for example, slide a bottom sheet down). On `close()` everything else still happens immediately: the result settles, the overlay leaves the stack (an overlay opened during the exit is topmost), a `native` dialog leaves the top layer, the wrapper turns `inert`, and focus returns. Only the node's removal waits, until the exit's CSS animations finish or `exitDuration` passes, whichever is first. `prefers-reduced-motion: reduce` skips the exit. `OverlayHandle.close(result, { instant: true })` (new `OverlayCloseOptions` type) skips the exit or ends one in progress. A second `close()` is still a no-op. Without the new options, behavior is unchanged.
100
+ - **Exit motion for `popover()` and `tooltip()`.** Both take `exitClass` / `exitDuration` and use the same exit as `overlay()`. A popover plays it on `close()` and on an outside-click dismissal, and a tooltip plays it when it hides after `hideDelay`. Teardown when the anchor leaves the document stays instant, and so does the tooltip disposer, which also ends an exit in progress. A tooltip shown again while the previous one is still exiting replaces the leaving node at once, so an anchor never has two tooltips. A popover or tooltip anchored inside an overlay now closes at that overlay's `close()`, instead of lingering until an exiting overlay's node is removed.
101
+ - **Bottom-sheet presentation for `kerfjs/overlay` dialogs.** `overlay()`, `confirm()`, `prompt()`, `form()`, and `choice()` take `presentation: 'bottom-sheet'` (the new `OverlayPresentation` type, named after `DialogSurface`'s prop). The wrapper gets `data-presentation="bottom-sheet"` on both the plain and `native` hosts. While the sheet is open, kerf follows `visualViewport` and publishes the virtual keyboard's overlap as `--kerf-keyboard-inset` on the wrapper. The value is cleared when the keyboard hides, while pinch-zoomed, and on close. kerf still ships no CSS: rest the sheet on the bottom edge and add `max(env(safe-area-inset-bottom), var(--kerf-keyboard-inset, 0px))` to its bottom padding (the API reference has the recipe). The default `'modal'` presentation is unchanged. Covered in Chromium, Firefox, and WebKit.
102
+ - **Media Detail recipe for `@kerfjs/ui`.** `?component=recipe-media-detail` composes an Apple-Music-style album page from components only: `NavStack` clear chrome with the scroll-edge material, a scoped `tint` from the artwork's bottom color, an `underChrome` `BackdropImage` with parallax and progressive blur fading into the tinted surface, and glass control groups. Under clear chrome, a `NavStack`'s own back control now sits in a glass control group, so it stays legible over imagery. The recipe has end-to-end coverage in Chromium, Firefox, and WebKit.
103
+ - **`BackdropImage` runs beneath clear chrome.** `underChrome` pulls the image up beneath the Pane's block-start inset: an overlay or clear header's clearance, NavStack chrome handed to a view's Pane, and the top safe area. Artwork fills the screen behind transparent chrome, as on a media detail page. The visible image keeps its `height` below the chrome and its `overlay` stays clear of it. `Pane` now publishes that inset as `--kui-pane-content-inset-block-start`, beside the inline insets.
104
+ - **Clear chrome for `@kerfjs/ui` layouts.** `Pane` `headerPresentation`, `NavStack` `chromePresentation` and `bottomToolbarPresentation`, and `TabNavigator` `barPresentation` take `clear`: an overlay bar with the same measuring and scroll clearance as `overlay`, but fully transparent, for chrome over imagery whose controls sit in glass `ToolbarControlGroup`s. A clear bar stays clear while content scrolls beneath it. `scrollEdge: 'material' | 'surface'` (on `Pane`, also in `PaneConfig`, and on the two layouts) fades the chrome material or the opaque surface in gradually instead, the iOS scroll-edge effect: fully clear at rest, fully in once content has scrolled `scrollEdgeDistance` pixels (default 60) beneath the bar, and only the backing's opacity changes. `wireScrollDividers` publishes the progress from the scroll it already tracks, so it works in every engine. Clear bars draw no scroll divider, turn opaque under reduced transparency or increased contrast, paint `Canvas` in forced colors, and snap on the scroll state instead of tracking it under the static-effects switch or on a slow-updating display. A `Toolbar`'s leading zone no longer clips the shadow of a glass control group.
105
+ - **Scoped tints for `@kerfjs/ui` layout surfaces.** `Pane` (and `PaneConfig`), `NavStack`, `TabNavigator`, and `TabNavigatorTab` take `tint: { color, scheme }`: an app color, typed with `@kerfjs/ui/css-values`, and the `'light'` or `'dark'` scheme it belongs to. Kerf does no color detection. The region paints the tinted surface, and its surface, raised surface, text, quiet text, link and brand text, quiet fills, chrome material, and popup rows re-derive from the color through `color-mix()` and relative color syntax. Lightness is clamped so text keeps WCAG AA over any color: a seed sweep across hue and lightness holds every text token at 4.5:1 or better in Chromium, Firefox, and WebKit, with and without the Web Awesome theme. The scope sets its `color-scheme` and Web Awesome scheme class, so Web Awesome components inside re-derive too. Under `prefers-contrast: more`, or without relative color syntax, it keeps the plain palette in the declared scheme.
106
+ - `@kerfjs/ui` `DialogSurface` gains `presentation="bottom-sheet"`: a dialog attached to the bottom edge of the screen, with square bottom corners, the top corners on the dialog radius, and a panel that runs behind the home indicator and the virtual keyboard while its content stays above them (the larger of the bottom safe area, the keyboard overlap measured from `visualViewport`, and `env(keyboard-inset-height)`). `height`, `maxHeight`, and the new `minHeight` size its visible height. The new `resizable` prop adds a top grabber, a focusable "Resize sheet" separator you drag or move with the arrow, Page Up/Down, Home, and End keys between `minHeight` and the viewport cap. The sheet slides up when it opens and down when it is dismissed; `enterMotion` / `exitMotion` (`"slide"` or `"standard"`) choose per transition, and reduced motion keeps Web Awesome's own animation. The centered `modal` presentation remains the default. The grabber, keyboard clearance, and slide need `@kerfjs/ui/surface-scaffold/register`.
107
+
108
+ ### Changed
109
+
110
+ - **A `Switch` hint sits directly under its label.** The `Switch` hint no longer leaves a 7px gap below the switch row; it sits flush under it on the label's column, the same offset as a `Checkbox` hint or a grouped choice hint, so every toggle control reads alike (`KF-YG5CM2`).
111
+ - **A standalone `Checkbox` hint sits directly under its label.** `Checkbox` hint and error text no longer leave a 7px gap below the label row; they sit flush under it, exactly as a `CheckboxGroup` or `RadioGroup` choice hint does, so a lone Checkbox and a grouped choice read the same (`KF-X8F2K5`).
112
+ - **`ColorPicker` hue track is a fixed rainbow.** In HSL and HSB the hue slider now always paints the full-saturation, full-brightness rainbow instead of the hues at the current saturation and brightness, so a dark or nearly gray color still shows which hue each position picks. Its thumb still shows the current color, every other channel and the opacity track keep their live preview, and the rainbow follows the writing direction like every other track (`KF-2AX5T7`).
113
+ - **Stacked checkboxes and radio choices share one 28px pitch.** `RadioGroup` choices now stack 8px apart (`--kui-space-xs`) instead of 12px, the same 20px-control-plus-8px pitch as standalone `Checkbox`es in a `List gap="xs"`, which the guidance now names as the way to stack them; horizontal groups keep their 24px column gap. This deliberately departs from Web Awesome's radio spacing, so the `@kerfjs/ui/webawesome.css` theme gives stacked `wa-radio`s `0.25em` block margins (the first and last stay flush) and a Web Awesome Radio Group keeps matching Kerf (`KF-9R49CW`).
114
+ - **`ColorPicker` sliders follow the color model.** RGB shows red, green, and blue sliders; HSL hue, saturation, and lightness; HSB hue, saturation, and brightness; Grayscale one gray-level slider; each with the opacity slider when `alpha` is on, and each track previews the colors its channel produces while the others hold. The saturation and brightness area stays in every model. Sliders are named for their channel with unit value text (`210°`, `40%`), and a channel edit keeps every other channel exact, so switching models and editing round-trips without drift (an HSL saturation survives black or white). The fixed `kui-color-picker__hue` class gives way to `kui-color-picker__sliders` and `kui-color-picker__slider`; `COLOR_PICKER_CHANNELS` entries gain `unit`, and `colorPickerSlider()` exposes a slider's state (`KF-ZNKCWX`).
115
+ - `@kerfjs/ui` marks two more Web Awesome elements `Discouraged`, for 36 in total; the profile defaults avoid both, so `KUI-L301` reports them. `wa-include` injects fetched markup outside kerf's `SafeHtml` escaping; fetch with `resource()` from `kerfjs/async` and render Kerf content instead. `wa-scroller` gives way to a `Pane`'s scroll edges or `ColumnTrack` (`KF-F5MPVE`).
116
+ - **Breaking: one `Button` replaces `IconButton` and `IconToggleButton` in `@kerfjs/ui`.** `Button` gains `shape` (`rounded` by default, or `pill`) and `pressed`, which makes any Button a toggle: `aria-pressed` reports the state, and a pressed look draws on top of its tone and emphasis (secondary and plain take the quiet tone fill with a doubled outline; primary darkens with an inset ring). An icon-only button is a `Button` with an `icon` and an `ariaLabel` and no label, and help tags now name it on hover and focus. `IconButton`, `IconToggleButton`, and their subpaths and stylesheets are removed with no aliases; migrate `IconButton({ icon, iconName, label })` to `Button({ icon: <LucideIcon …/>, ariaLabel })`, and `IconToggleButton` to that plus `pressed` (and `shape="pill"` for its former default shape). `kerf-ui-doctor` now checks an icon-only Button's `ariaLabel` capitalization (`KF-TQCJSS`).
117
+ - **Breaking: `Composer` is now `MessageComposer` in `@kerfjs/ui`, and its action row is a `Toolbar`.** The new name says what it is: a composer for messages, prompts, and replies. There are no compatibility aliases: `MessageComposer`, `MessageComposerProps`, `wireMessageComposers`, `@kerfjs/ui/message-composer` (and `.css`), `@kerfjs/ui/wire-message-composers`, and `kui-message-composer*`; the catalog id is `message-composer`. The row below the field is now a compact `Toolbar` footer named "<label> Actions", so every toolbar convention applies: control groups and responsive relocation. A new `leading` prop holds controls such as an attach button or a model `Select`, and the `actions` prop is now `trailing` (`KF-ANFPGA`).
118
+ - **Breaking: `AppTab` is now `TabBarItem` in `@kerfjs/ui`.** The item inside a `TabBar` is named after its container, with no compatibility alias: `TabBarItem`, `TabBarItemProps`, `TabBarItemPresentation`, `TabBarItemSize`, and `TabBarItemNameOverflow`; the subpath `@kerfjs/ui/tab-bar-item` (and `.css`); `kui-tab-bar-item*` classes, `data-component="tab-bar-item"`, and `--kui-tab-bar-item-*` tokens (`KF-HAXNZ8`).
119
+ - **Breaking: `TokenSearchField` is now `SearchField` in `@kerfjs/ui`.** Tokens are optional, and it is Kerf's only search control, so the component and everything named after it lose the `Token` prefix, with no compatibility aliases. Exports: `SearchField`, `wireSearchFields`, `readSearchField`, `placeSearchFieldCaret`, `createSearchFieldModel`, and `SearchField*` types (`SearchFieldToken`, `SearchFieldModel`, `SearchFieldState`, …). Subpaths: `@kerfjs/ui/search-field`, `/search-field-model`, `/wire-search-fields`, `/search-field.css`. Markup: `data-component="search-field"`, `kui-search-field*` classes, `data-search-field-*` attributes, and `--kui-search-field-*` tokens. The catalog id is `search-field` (`KF-TF4N13`).
120
+ - **Breaking (`@kerfjs/ui`, 5.0 beta): `PopupMenu` no longer uses Web Awesome's dropdown.** The menu is now Kerf's own: a native trigger `<button>` and a `role="menu"` panel that opens as a manual popover in the browser top layer. `@kerfjs/ui/popup-menu/register` wires every PopupMenu in the document: opening and placement (flip, shift, and a height cap at the viewport edges), keyboard navigation (arrows, Home/End, typeahead, Enter/Space, ArrowRight/Left for submenus), hover-opened submenus with a pointer safe triangle, outside-press and Escape dismissal, and focus return. Its props are unchanged and it looks the same; menus no longer depend on Web Awesome's prototype patches, and a clipping `ResizableRegion` or `Workbench` panel no longer needs to release its clipping for one. Migration for code that reached into the old markup (`KF-EMJJGV`):
121
+ - Query `.kui-popup-menu` (a `<span>`), `.kui-popup-menu__trigger`, `.kui-popup-menu__menu`, and `.kui-popup-menu__item` instead of `wa-dropdown`, its `[slot="trigger"]` `wa-button`, its shadow `menu` part, and `wa-dropdown-item`. The open state is the trigger's `aria-expanded`, not an `open` attribute; `PopupMenuElement` is now plain `HTMLElement`, so open and close a menu with `openPopupMenu`, `openPopupMenuAt`, and `closePopupMenu`.
122
+ - Delegated `data-action`s run as before. The `wa-select` choice event is now a bubbling, cancelable `kui-menu-select` on the root, with `detail.item`, `detail.value`, and `detail.checked`; `wa-show`, `wa-hide`, and `wa-after-hide` are gone.
123
+ - A checkbox item no longer toggles itself: `detail.checked` is the state it asks for, and the item shows it once the application renders it.
124
+ - Escape closes the current submenu first, then the menu.
125
+ - The register no longer registers `wa-dropdown`, `wa-dropdown-item`, `wa-button`, or `wa-divider`. Import those Web Awesome modules yourself where you render them raw.
126
+ - **Breaking (`@kerfjs/ui`, 5.0 beta): `Select` no longer uses Web Awesome's select.** It renders a `kui-select` root holding a native trigger `<button role="combobox">` and a `role="listbox"` that opens as a manual popover in the browser top layer. `@kerfjs/ui/select/register` defines `kui-select` as a form-associated element (it submits under `name` like a native select, `multiple` values included, and returns to its rendered choice on form reset) and wires every Select: placement below the trigger (flipping above when short, capped at the viewport edges), keyboard navigation with typeahead, choosing, the select-all and clear actions, and dismissal by Escape, Tab, or an outside press. Its props are unchanged and it looks the same, with two deliberate fixes: a `title` Select's caret is no longer clipped, and an `inline` Select's box is 20px tall rather than 23.2px. Migration for code that reached into the old markup (`KF-CF0FEN`):
127
+ - Query `kui-select.kui-select`, `.kui-select__trigger`, `.kui-select__popup`, `.kui-select__listbox`, and `.kui-select__option` (`data-value`, `aria-selected`, `aria-disabled`) instead of `wa-select`, its shadow `combobox` / `listbox` parts, and `wa-option`. The open state is the root's `open` attribute and the trigger's `aria-expanded`.
128
+ - `input` and `change` still bubble from the root, and the root's `value` is the chosen value (an array with `multiple`). `wa-show`, `wa-hide`, `wa-after-show`, and `wa-after-hide` are gone; the select-all and clear actions report a `change` only.
129
+ - The `kui-select--label-hidden` class is gone: an `ariaLabel`-only Select now names its trigger with `aria-label` and renders no label element.
130
+ - The register no longer registers `wa-select`, `wa-option`, or `wa-divider`. Import those Web Awesome modules yourself where you render them raw.
131
+ - **Breaking (`@kerfjs/ui`, 5.0 beta): `DialogSurface` is the dialog itself, a native `<dialog>`, instead of a wrapper around a `wa-dialog` you write.** It renders Kerf's header (title, header actions, and a close button), the body, and an optional footer from props, keeps every size, presentation, inset, height, and floating header or footer prop, and looks the same. Open it with `openDialog(dialog)` and close it with `closeDialog(dialog)`, both from `@kerfjs/ui/surface-scaffold`: it opens modally in the top layer with the page inert and focus on an `autofocus` element or the panel, scales and fades in and out, and returns focus to its opener. The close button, any element inside with `data-dialog-close`, Escape, and (with `lightDismiss`) a press on the backdrop dispatch a cancelable `kui-request-close` (`detail.source`: `close-button`, `escape`, or `backdrop`); cancel it to keep the dialog open, and the panel pulses. The native `close` event fires once it has closed. While open, it measures a floating header or footer, follows a bottom sheet's keyboard and grabber, and keeps that state across application re-renders. It renders the host `kerfjs/overlay` uses for popovers and tooltips opened inside it. The four Web Awesome dialog patches are gone, and `surface-scaffold/register` no longer registers `wa-dialog`. Migration (`KF-JR9YFX`):
132
+
133
+ | Before (`wa-dialog` inside `DialogSurface`) | Now (`DialogSurface` props) |
134
+ | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
135
+ | `<wa-dialog label="Edit">` inside `<DialogSurface>` | `<DialogSurface label="Edit">`, with the dialog's content as its children |
136
+ | `id` on the `wa-dialog` | `id` |
137
+ | `slot="label"` content, such as a `ToolbarText` | `heading` (keep `label`, or name it with `labelledBy`) |
138
+ | `slot="header-actions"` content | `headerActions` |
139
+ | `slot="footer"` buttons or `Composer` | `footer` |
140
+ | `without-header`, `light-dismiss` | `withoutHeader`, `lightDismiss` |
141
+ | `dialog.open = true` / `false`, or `open={…}` in the template | `openDialog(dialog)` / `closeDialog(dialog)` |
142
+ | `data-dialog="close"` on a button | `data-dialog-close` |
143
+ | `wa-request-close` (cancelable) | `kui-request-close` (cancelable), `detail.source` |
144
+ | `wa-show`, `wa-after-show`, `wa-hide`, `wa-after-hide` | the native `close` event (after closing); nothing fires on open |
145
+ | `::part(dialog \| header \| body \| footer)` | `.kui-dialog-surface` and its `__header`, `__body`, and `__footer` (configure through props) |
146
+
147
+ A raw `wa-dialog` outside `DialogSurface` keeps Web Awesome's own behavior and the theme in `@kerfjs/ui/webawesome.css`; import its module yourself where you render it.
148
+
149
+ - **Breaking (`@kerfjs/ui`, 5.0 beta): `IconButton` is an icon-only `Button`, not a `wa-button`.** It takes the same `tone`, `emphasis`, and `size` as `Button` instead of Web Awesome's `variant`, `appearance`, and `size` (`variant` → `tone`: `neutral`, `brand`, `danger`; `appearance` `outlined` → `emphasis="secondary"`, `plain` → `emphasis="plain"`; `size` `xs`–`xl` → `default` or `compact`), renders a native `button[data-icon-only]` named by `label`, and needs no Web Awesome registration. The `kui-icon-button` class is gone; select the icon-only button by `.kui-button[data-icon-only]` (`KF-9HV3B2`).
150
+ - A `Composer`'s Enter-to-send treats a send action with `aria-busy="true"` (a busy `Button`) as unavailable, as it already did a disabled or `loading` one (`KF-9HV3B2`).
151
+ - `@kerfjs/ui` help tags (the names icon-only `Select` and `PopupMenu` triggers and icon-only toolbar buttons show on hover and keyboard focus) are Kerf's own element instead of a Web Awesome `wa-tooltip`, and they look and behave the same. `select/register`, `popup-menu/register`, and `help-tags/register` no longer register `wa-tooltip`: import its module yourself where you render one raw. A theme that restyled `wa-tooltip.kui-help-tag` targets `.kui-help-tag` instead (`KF-9VNFSG`).
152
+ - `@kerfjs/ui` no longer patches any Web Awesome internals, so it supports every Web Awesome 3.x from 3.12 (the optional peer range, `^3.12.0`) rather than effectively one exact version. Its CI runs the ui unit and Chromium browser suites against the newest 3.x as well as the 3.12.0 floor, and both pass on 3.14.0 (`KF-F3FY5G`).
153
+
154
+ ### Fixed
155
+
156
+ - **Quiet and danger Text contrast on lowered surfaces.** The shared light quiet and dark danger colors now clear WCAG AA when `Text` appears in a lowered `ValueTableRow` or `ListHeader` status over the document baseline, in both the foundation fallback and Web Awesome theme (`KF-CQWA7G`).
157
+ - **`require-data-key-in-each` recognizes component `rootAttributes` keys.** A statically named `"data-key"` or `id` in a component row's `rootAttributes` object now satisfies the rule. Dynamic objects and ambiguous later spreads remain diagnostic; native and fragment roots retain their checks (`KF-PD9ZGA`).
158
+ - **Web Awesome Carousel specimens show full slides in Firefox.** A `wa-carousel`'s scroll container is a `grid-auto-columns: 100%` track under an aspect ratio, so it has no definite intrinsic width. In the catalog's shrink-to-fit specimen column Chromium and WebKit resolved it from the aspect ratio (a 457px carousel at 1100px), but Firefox sized it to the first slide's text: a 191px carousel with a 103×34px track that clipped "Foundation" and "Focused carousel item" at every width. The Carousel and Carousel Item specimens now take the medium width tier, as the Zoomable Frame specimen does, so every engine renders the same full slides. A three-engine check asserts the track holds the whole slide at 1100px and 320px (`KF-0TGNQG`).
159
+ - **Web Awesome OTP Input cells render whole.** Upstream caps the OTP Input's segments box, which reserves its focus-ring bleed with 4px padding and an equal negative margin, at 100% of the host. In a shrink-to-fit host (the catalog's start-aligned example grid, any start-aligned grid or flex item) the host is only the cells' width minus that bleed, so the padded box was 8px too narrow and silently clipped the last cell's inline-end edge inside its scroll container at every width. `@kerfjs/ui/webawesome.css` caps it at the host's width plus the bleed its negative margins reserve: a host narrower than the code still scrolls, and the `contained` appearance keeps upstream's cap. The catalog's phone-width check now measures the cells inside the shadow root (`KF-SPEQPY`).
160
+ - **Row and Grid catalog specimens fit a 320px phone.** The Row catalog's vertical-alignment rows now `wrap`, so the Baseline Alignment row's taller chips move the third chip to a second line instead of running 13px past the example, and the non-wrapping Default, Distribution, and Side-Selectable Insets rows use short `One` / `Two` / `Three` chips, which fit 320px with room to spare even in Linux's wider fallback font (the prefixed `Default three` ran about 15px past the example there) (`KF-JWT4QZ`). The Grid catalog's Four Columns example shows short quarter tiles (`Q1` … `Q4 est.`) that fit a phone-width track instead of process-stage words that ran past their own tiles and up to 11px past the example; its note now says a fixed count suits short content and points longer labels at `minColumnWidth`. Both catalogs join the phone-width overrun check (`KF-37ERTC`).
161
+ - **Catalog labels and specimens fit a 320px phone.** A `CatalogExample` label is a content-width `ListHeader`, and its single unbreakable line set the header's minimum width, so about twenty long labels ("Sunken Workbench Regions Without Pane Chrome", "Accessible Name Without a Visible Label", …) ran past the example and were cut off at the stage edge instead of truncating. The label now wraps through the new `ListHeader` `wrap`. The Web Awesome OTP Input specimen uses the small size, whose six grouped cells fit the 280px specimen column (the default size needs 292px), and the ListHeader catalog's inline-header row wraps its trailing status instead of running 16px past the example (`KF-12WBGR`).
162
+ - **Aligned `CatalogExample` specimens no longer run past the example's end edge.** An aligned example (`align="glyph"`, `"inline-control"`, or `"text-trigger"`) inset each specimen with a start margin, so a full-width specimen — the SearchField catalog's Disabled field, the Select catalog's fill-width Visible Label select, the SegmentedControl catalog's control-width Rounded Rectangle frame — kept its full width and ran 8px past the example at every stage width. The inset is now the example's own grid column: the label and note span the full width and every specimen sits in the inset column, so a percentage width resolves against that column and ends on the example's edge, while specimens keep their own width caps. A page-fixed specimen (the EdgeActivityIndicator strip) no longer picks up the inset either (`KF-EE4WEN`).
163
+ - **`ColorPicker` dark design templates draw a solid opacity track end.** The templates' opacity-track stand-in drew its translucent dark checker squares straight onto the template's transparent background, so in the dark templates they took on the viewer's backdrop and showed through the track's opaque end. The checkerboard now sits on an opaque surface underlay, like the component's own, and fades out toward full opacity in light and dark alike (`KF-MV5GE6`).
164
+ - **`ColorPicker` area edge and thumb outline.** The saturation and brightness area had no boundary, so its black bottom vanished into a dark surface and its white corner into a light one; it now draws the same 1px inner edge as the slider tracks (halfway to the text color, the full text color under increased contrast, `CanvasText` in forced colors). Every thumb's outline outside its white border is now dark enough (60% black, was 20–30%) that a light thumb over a light area or track keeps at least 3:1 against it, while the white border holds against dark colors (`KF-F4J2GD`).
165
+ - **The Web Awesome Known Date and Slider catalog specimens have a field width.** Both size to their container, so in the shrink-to-fit specimen column Known Date measured 0px wide (its segments stacked and its hint wrapped a word per line) and Slider about 90px. The catalog now gives Known Date a compact field column and Slider the Kerf Slider demo's medium width, and the Slider specimen takes the field demos' `inline-control` alignment so its label and track land on the Kerf Slider's column. The theme contract notes that both need a width from their container (`KF-ZVA2S2`).
166
+ - **The Web Awesome Progress Bar, Skeleton, and Zoomable Frame catalog specimens no longer collapse.** They also size to their container, so the specimen column shrank Progress Bar to a 30px stub, Skeleton to 0px, and Zoomable Frame to an empty 16px panel. The catalog now gives Progress Bar the Kerf ProgressBar demo's medium width, Skeleton a compact text column, and Zoomable Frame a medium media frame (`KF-J214TZ`).
167
+ - **`wa-tag-input` follows the Web Awesome field theme.** `@kerfjs/ui/webawesome.css` now gives a raw `wa-tag-input` the same treatment as the other bordered fields: its label is uppercase on the 9px text column, its hint shares that column, its box takes Kerf's 44px control height (2.75em), its border sits on the host's inline-start edge, and a small one keeps a 16px editable text size on coarse touch devices. It stays Discouraged in favor of `TagField`; the catalog specimen now uses the field demos' `inline-control` alignment (`KF-S5XTY4`).
168
+ - **`kerf-ui-doctor` reads raw `wa-checkbox-group` labels.** `KUI-D040`'s title-style check already read `CheckboxGroup` and raw `wa-radio-group` labels; the `label` of a raw `wa-checkbox-group` is now read the same way, while `wa-checkbox` option text stays sentence style and unread (`KF-ZJ28W4`).
169
+ - **Every Kerf field demo shares one border and label column.** The UX catalog's ColorField, TagField, and Slider specimens now use `align="inline-control"` like the TextField, Select, Switch, Checkbox, RadioGroup, and CheckboxGroup demos, so field borders and label text line up across the catalog instead of sitting 8px apart. A `CatalogExample` `viewport` that is aligned now takes that offset out of its width, so a full-width specimen frame no longer runs 8px past the example's inline-end edge at narrow widths (`KF-ZPDYQW`).
170
+ - **The ColorSwatches catalog demo joins the field column.** ColorSwatches is a field — a person picks a value with it inline — so its specimens now use `align="inline-control"` and its legend text lands on the field label column with the other form fields. ColorPicker and FilePicker are panels (a multi-part picker and a drop zone) and stay flush; `ui/docs/catalog.md` now states the field-versus-panel rule (`KF-8YAGME`).
171
+ - **Width-sized catalog specimens join the field column.** The ProgressBar demo, the group-title `Text` specimen, the Grid and saved-view SearchField field compositions, and the Web Awesome Progress Bar, Skeleton, and Pagination specimens sat flush at the example's edge, so a bar's "Uploading Files" label started 8px left of the example label and note text. They now use `align="inline-control"` like the form fields, and their sized frames still end at the example's inline-end edge. Panels (ColorPicker, FilePicker, Zoomable Frame) and edge-to-edge compositions stay flush; `ui/docs/catalog.md` states the rule (`KF-WH27TY`).
172
+ - **Web Awesome control and text specimens align like their Kerf counterparts.** The catalog's Web Awesome Button, Button Group, Dropdown, Dropdown Item, Tab family, Badge, Tag, Avatar, Progress Ring, Toast, Toast Item, Animation, observer, and dialog/drawer/popover/tooltip trigger specimens sat flush at the example's edge while the Kerf Button demo puts its control box on the 8px column; they now use `align="inline-control"`. Specimens led by bare text or a glyph (Copy Button, Breadcrumb, Divider, Markdown, Relative Time, Pagination's summary, Stepper and Step, Spinner, Icon) now use `align="glyph"`, so their text sits on the text column as Kerf's flush Text demo does instead of at x=0. The CornerStatus "Embedded" example's banners now sit on the same 8px column as the standalone StateBanner demos. Panels and framed media (Page, Split Panel, Popup, Zoomable Frame, QR Code, Animated Image, Carousel) keep their own geometry (`KF-44TDSF`).
173
+ - **A tall `PopupMenu` or `Select` popup never covers its trigger.** When a popup fit on neither side of its trigger (a toolbar overflow menu at 1024×600), it was shifted across the trigger to stay in the viewport, so a second press on the trigger landed on a row instead of closing the popup. The shared popup placement now shifts only along the trigger's edge: when neither side fits, the popup opens on the side with more room and scrolls inside its capped height. `PopupMenu` menus, `Select` and `Combobox` listboxes, and help tags all share it (`KF-F22WMW`).
174
+ - **A context `PopupMenu` honors its `placement`.** A `context` menu always opened `bottom-start` at its anchor point whatever `placement` it was rendered with, so a menu anchored to a footer or composer could not open above the point. Its placement now applies at the point (`top-start` opens above it, `top-end` above it at its end), with the same viewport flip, shift, and height cap; a button-triggered menu opened at a pointer with `openPopupMenuAt` still opens `bottom-start` from the point for that opening (`KF-MXM1SH`).
175
+ - **A group-owned `Select` draws one focus ring.** A `Select` with `focusRingOwner="group"` inside a `ToolbarControlGroup` that draws the pill ring still painted its own trigger outline on focus, because the trigger's focus rule outranked the owner rule, so keyboard focus showed two rings. The trigger's focus ring now applies only when the Select owns it; a select-owned trigger and a per-control-ring group are unchanged (`KF-GWSEWC`).
176
+ - **`ColorPicker` slider tracks follow the writing direction.** In right-to-left text a native range runs right to left, but every channel and opacity track still painted its gradient left to right, so the thumb at a channel's minimum sat over the color of its maximum. Each track now runs in the writing direction (`to left` under `:dir(rtl)`), and a browser test checks that the thumb at the minimum sits over the gradient's start in both directions (`KF-KKMMJV`).
177
+ - **`ColorPicker` slider tracks keep their edge on a matching surface.** A dark track (a hue at low brightness, a faint opacity) used to vanish into a dark surface, and a light one into a light surface, because each drew only a faint black inner line. Every track now draws a 1px inner edge halfway to the text color, at least 3:1 against the surrounding surface in light and dark; increased contrast draws it in the full text color and forced colors in `CanvasText` (`KF-JN1ZH6`).
178
+ - **`kerf-ui-doctor` no longer reports a false `KUI-L203` for every `MessageComposer`.** The shipped composition catalog still declared the removed `actions` zone; it now declares a required `trailing` zone and an optional `leading` zone, and a test keeps every component's composition zones aligned with its real props (`KF-Z00DKT`).
179
+ - **`SplitButton` focus ring is visible on every tone.** Each half drew its keyboard focus ring inside its loud fill, where it all but vanished on the brand fill in light mode and matched the brand fill exactly in dark mode. The ring now sits outside the focused half, offset 1px like `Button`'s, so it is drawn against the surrounding surface on every tone and in both schemes (`KF-V0HSNG`).
180
+ - **`RadioGroup` circles line up with Checkbox boxes.** Each radio circle now sits on the group's inline-start edge, where a `Checkbox` draws its box, instead of 8px further in, so stacked checkboxes and radios share one control column; the group label and hint keep the text column (`KF-F68AZ9`).
181
+ - **Web Awesome Checkbox Group and Radio Group follow the same control column.** The `@kerfjs/ui/webawesome.css` theme no longer insets a `wa-checkbox-group` or `wa-radio-group` option region by 8px, so each box or circle sits on the group's inline-start edge like Kerf's `Checkbox` and `RadioGroup`, and both groups' hints now join their label on the 9px text column. The unbordered Color Picker trigger keeps its 8px inset (`KF-2X0Z47`).
182
+ - **Web Awesome fields, Switch, and Color Picker share Kerf's field columns.** The `@kerfjs/ui/webawesome.css` theme no longer insets the `wa-color-picker` swatch trigger by 8px, so it sits on the host's inline-start edge like a Kerf `ColorField` trigger, with its label on the 9px text column. The guidance now states the placement rule for every themed field: a bordered `wa-input`, `wa-select`, `wa-textarea`, `wa-number-input`, `wa-time-input`, `wa-known-date`, or `wa-otp-input`, and a `wa-switch` track, start on the host edge exactly where Kerf's `TextField`, `Select`, and `Switch` draw theirs, so place a Web Awesome field where the Kerf field would go. The catalog's field specimens now use the Kerf field demos' alignment, so their borders, labels, and hints land on the same columns in every engine (`KF-6SM43M`).
183
+ - **`NavStack` overlay chrome keeps its material during a push or pop.** The overlay top chrome and bottom toolbar used to fade as a whole while their contents cross-faded, which faded the backdrop blur with them (Safari dropped it outright), so the sliding views showed through the bars mid-transition. Now the live bar keeps the material at full opacity while its new contents fade in, and the copy fading out above it carries only the old contents (`KF-H3NNP6`).
184
+ - **Anchored surfaces follow an anchor that changes size.** `autoReposition()` (and so `popover()`, `tooltip()`, and `AnchoredSurface`) also repositions when the anchor itself resizes, where `ResizeObserver` exists, not only on scroll and resize, so a surface below a field moves down as the field grows a line. The UX catalog's Structured Ticket Search help now anchors to the whole SearchField instead of its help button, so at phone width it no longer covers the field's wrapped second line, and typing in the field leaves it open (`KF-37TGXB`).
185
+ - **Anchored surfaces follow their own size changes.** `autoReposition()` (and so `popover()`, `tooltip()`, and `AnchoredSurface`) also repositions when the positioned element itself resizes, where `ResizeObserver` exists, so an end-aligned surface that grows wider keeps its right edge on the anchor's, and an above-placed one that grows taller keeps hanging just above the anchor instead of growing over it until the next scroll. A resize that the positioning's own writes caused is not acted on again, so repositioning never feeds itself (`KF-S92WX8`).
186
+ - **A scrolled `fitHeight` surface keeps its scroll position in Safari.** To honor the element's own `max-height`, `positionAnchored()` briefly lifts the room it published around a style read. WebKit lays the element out for that read when a size container sits inside it (a `Toolbar`, a `ValueTable`), and the uncapped layout clamped the element back to its top; every scroll inside it repositions it, so wheel scrolling an `AnchoredSurface` jumped back to the first row. The element's current height is now pinned for the read, and a scroll position the read still moves is put back (`KF-PVBPJM`).
187
+ - **`Combobox` suggestions are no longer clipped inside popups.** The listbox is a top-layer popover placed below the field at its width (flipping above when short), so an `AnchoredSurface`, a dialog, or a scrolling `List` around the field no longer cuts it off. The `--kui-combobox-z-index` token is gone; the top layer needs none (`KF-C558Z9`).
188
+ - **`List` `vAlign="middle"` and `Row` `hAlign="center"` gather their children in the middle** with their `gap`, instead of spreading them with `space-around`. `space-around` is now its own explicit value (`data-*-align="around"`), and `center`/`middle` on the cross axis center wrapped lines (`KF-3ZJ9PF`).
189
+ - **A SearchField no longer shows its placeholder over typed text after an unrelated re-render.** Re-rendering the host for another reason, such as an error message beside the field, reset the field's placeholder state from the app's query while the editor still held typed text. `wireSearchFields` now re-derives it from the live editor (`KF-PZ5J93`).
190
+ - **`<details name>` typechecks in kerf JSX.** The intrinsic `details` element now accepts `name`, the native exclusive-accordion group, so `<details name="faq">` no longer fails to typecheck (`KF-KFH2VT`).
191
+ - **A `SplitView` column's only `Pane` now fills the column in `@kerfjs/ui`.** It used to take only its content height, so the Pane's footer sat right below its content instead of at the column's end (`KF-P9VSX1`).
192
+ - A busy `ToolbarControlGroup` whose control shows text (`content="text"` or `"mixed"`) now hides the whole control under its spinner, label included, while keeping its size. Before, only icons were hidden, so the spinner drew over the label ("Pric◌ Check") (`KF-HCN9BH`).
193
+ - `@kerfjs/ui/webawesome.css` draws a loading active `wa-step`'s spinner in the marker's on-accent color. Web Awesome 3.14 colors that spinner with the same accent that fills an active marker, so it was invisible. The fix goes through the step's public `spinner` part (`KF-AW993A`).
194
+ - A `@kerfjs/ui` `Toolbar` with a single zone now gives that zone its whole content box. A leading-only toolbar kept the empty trailing track and its 8px column gap, so leading content set to fill the row (a flex `Row` of controls) stopped 8px short of the inline-end inset; a trailing-only toolbar had the same gap on the leading side. A lone leading, center, or trailing zone now spans every column track. Covered in Chromium, Firefox, and WebKit.
195
+ - Typing in a model-managed `@kerfjs/ui` `TokenSearchField` no longer re-runs the host `mount()` render on every keystroke. The field read the model's per-keystroke `state` during render, so an app that renders it from one large mount re-rendered and morphed the whole app per key. It now subscribes only to the new `model.structure` signal, which changes when a token is committed, removed, or reordered, when the text becomes empty or non-empty, or when the editor revision changes; the live text stays owned by the editor and `wireTokenSearchFields`. `model.suggestions` now publishes only when the suggestion list's content changes, and a model action that changes state publishes its state, result, and suggestions as one batch. Hosts that read `model.state.value` in their own render still subscribe per keystroke by choice: read `model.state.peek()` there, or bind `model.result` (or a `computed`) as a fine-grained text or attribute hole. An app that coalesced the field's per-keystroke projection to work around this can remove it.
196
+ - A `kerfjs/overlay` `initialFocus` that targets a custom element that cannot take focus yet no longer aborts the open. Before, a Web Awesome `wa-button` whose `focus()` throws before it has rendered made `overlay()` (and `confirm()`, `prompt()`, `form()`, `choice()`) roll back and rethrow. Now focus holds on the overlay itself, then moves to the element once it is defined and rendered, unless the overlay has closed or the user has moved focus in the meantime. The same applies to `initialFocus: true` when the first tab stop is such an element. Covered in Chromium, Firefox, and WebKit.
197
+ - `wireNavStack` keeps fallback focus on a pushed view with nothing focusable (an inert loading placeholder, say) across re-renders. The temporary `tabindex="-1"` it adds to the view was morphed away by the next render, which made the view unfocusable and dropped focus to the page body. It is now restored while the view holds that focus, and focus moves to the view's first focus target once content with one arrives under the same key. Focus the person moved elsewhere is left alone.
198
+ - Clearing a collapsible `TokenSearchField` with its ✕ button while focus is outside the field now collapses the emptied field and leaves focus where it was. Previously the clear re-expanded the field and claimed the caret, so it stayed open until it was focused and blurred again. A clear started from inside the field still returns the caret to the editor; that is now decided by where focus was when ✕ was pressed, which also covers WebKit, where the press drops focus to the page before the click.
199
+ - A `DialogSurface` bottom sheet with no `height` now opens at its content height, as documented. A modal dialog sits between both block insets, so the sheet's auto height stretched to its cap. The catalog's resizable sheet now relies on content height: its fixed height sat a few pixels short of the form and clipped the textarea's bottom border on a phone.
200
+ - A title over a `BackdropImage` `scrim` is now light in both color schemes. The scrim is dark in both schemes, so the overlay now takes the dark color scheme and default-tone titles and controls resolve their light foregrounds. `ToolbarText tone="dark"` is unchanged: it matches dark control groups on a loud-filled toolbar and inverts with the scheme, so the guidance no longer recommends it for photo-backed toolbars. Under reduced transparency or increased contrast, where the overlay sits on a solid `fadeTo` band, the overlay keeps the page's scheme.
201
+ - `kerf-ui-doctor --full` and `kerf-ui-analyze` no longer report findings in gitignored, generated output. A local Playwright run's `playwright-report/` (its trace viewer ships CSS) produced about a hundred `KUI-L006` review findings in one app, so running the tests changed the doctor result. Inside a Git work tree, full traversal now skips every path the project's ignore rules ignore, across TypeScript, the isolated ESLint pass, analyzer discovery, and cache inputs; Playwright's `playwright-report`, `test-results`, and `blob-report` directories are also skipped by name, which covers projects outside Git.
202
+ - A dark-tone `AnchoredSurface` (`tone: 'dark'`) now follows a live color-scheme switch while it is open. It picked its inverse scheme once, on open, so an OS preference change or an app theme toggled on an ancestor left the popup on the old side until it was reopened. It now flips with the page. `openAnchoredSurfaceAt` also reads the dark tone's scheme from `point.context`, the element under the pointer, instead of from the body or dialog that holds its temporary anchor, so a region with its own forced `color-scheme` is honored.
203
+ - A keyboard move made as a long `PopupMenu` submenu (or menu) opens now leaves the chosen item in view, not just focused. When Web Awesome's late first-item focus landed after the move (say `End` pressed right after `ArrowRight`), it scrolled the menu back to the top, and kerf's restore refocused the chosen item without scrolling, so the focused last choice sat out of view below the clip. The restore now scrolls the item into view within its own menu, leaving the page alone.
204
+ - A default-tone `ToolbarControlGroup` in an overlay `Pane` header (`headerPresentation="overlay"`) or in a `DialogSurface` floating header's `header-actions` (`headerPresentation="floating"`) now keeps its controls at WCAG AA over content passing beneath the translucent chrome material. Its quiet control color over its own translucent fill measured about 3.0:1 (light) and 3.5:1 (dark) over the worst case; its controls now take the normal text color there, as they already did in overlay `NavStack` chrome.
205
+ - A dark `ToolbarControlGroup` (`tone="dark"`) holding one control no longer hides its icon on hover over a light page. A lone control's hover replaces the whole group's fill, and the dark tone's hover was a translucent surface wash meant to lie over that fill, so the white icon sat on a near-white circle (about 1.3:1). The wash now paints over the group's loud fill, as it does on one control of a multi-control dark group, and it is 14% instead of 28%: at 28% even that layered paint measured about 2.7:1. Hovered dark controls now keep about 3.4:1 over a light page and about 5.8:1 in dark.
206
+ - An unframed scrollable `List` now stops a row focused or scrolled into view with its whole focus ring inside the scroll clip. Only a framed List carried ring-room scroll padding, so in an unframed one the ring of a row brought into view ended flush against the clip and was cut off. Every `scrollable` List now has 6px of block scroll padding (the ring's 4px reach plus 2px of slack), which moves nothing at rest. An unframed List's first and last rows still meet the clip at the scroll extremes; `frame`'s 4px inset is the answer when they must show a whole ring.
207
+ - An overlay `Pane` header (`headerPresentation="overlay"`) now clears its forced-colors edge. In forced colors the header gains a 1px `CanvasText` bottom border, but `wireScrollDividers` observed the header's content box, so the border alone reported no resize and `--kui-scroll-clearance-block-start` stayed 1px short: the content's first item rested under the edge. The wiring now observes each overlay header's border box, the same box it publishes.
208
+ - `positionAnchored({ fitHeight: true })` (and so `autoReposition()`, `popover()`, `tooltip()`, and `@kerfjs/ui`'s `openAnchoredSurface()`) now keeps an element placed above its anchor growing upward. It set `top` from the height the element had at the reposition, so an element still growing afterwards — say an expand-from-0 `max-height` entrance placed above mid-expand — slid its bottom edge down over the anchor until the next scroll or resize. An above placement now pins the element's bottom edge at the gap above the anchor (`bottom`, with `top: auto`), so it grows and shrinks upward, away from the anchor, whatever height it goes on to lay out; a below placement sets `top` with `bottom: auto`. Placement without `fitHeight` is unchanged (`KF-MZ03RG`).
209
+ - An overlay `Pane` header (`headerPresentation="overlay"`) no longer covers the top of a classic, space-taking scrollbar (Windows and Linux, or macOS with "always show scrollbars"). Its thumb and arrow buttons ran beneath the translucent header. `wireScrollDividers` now also measures the content's vertical scrollbar and publishes a classic one's inline size on the Pane as `--kui-pane-scrollbar-inline-size`, and the header ends where the scrollbar's track begins. Overlay scrollbars take no space and still pass beneath the header like the content.
210
+ - A `ToolbarText` in an overlay `Pane` header (`headerPresentation="overlay"`) now keeps WCAG AA over the translucent chrome material. Over worst-case content passing beneath, its quiet `description` measured about 3.2:1 (light) and 4.1:1 (dark), and a default-size title about 3.8:1 (light). In that header an untoned `ToolbarText` now takes the normal text color for its title at every size and mixes its description halfway toward it (about 5.9:1 in both themes), so the description stays readable and still reads as secondary.
211
+ - A framed `List` (`frame`) now keeps a focused middle row's ring inside its scroll clip in Chromium. The frame's scroll padding equaled the ring's 4px reach, but Chromium's focus scroll stops 1px short of the padded target and a row's fractional position can cost another fraction of a pixel, so about 1px of the ring was cut. The scroll padding is now the ring reach plus 2px; the frame's 4px visual inset and its first- and last-row resting positions are unchanged.
212
+ - `positionAnchored({ fitHeight: true })` now measures an element whose `max-height` is mid-animation at the cap it is headed to. An app transition already running on `max-height` (say an expand-from-0 entrance to `max-height: 300px`) or a `@keyframes` animation of `max-height` made the cap read report the current frame, so a reposition mid-expand judged the element by a height it was about to outgrow and could open it on a side its settled cap does not fit. kerf now reads the cap from the running effect instead — its last `max-height` keyframe, or its first while the current iteration plays in reverse — and, for that case, never touches the element's style, so the app's animation keeps running uninterrupted. A finished animation that still fills is read from computed style as before, and a keyframe `var()` kerf cannot resolve outside the element counts as no cap (`KF-YW3PRD`).
213
+ - `eslint-plugin-kerfjs`'s `ui-css-values` rule now recognizes CSS-value helpers imported from any `@kerfjs/ui` subpath, including the documented `@kerfjs/ui/css-values`. It only knew helpers imported from the package root, so `iconTile={{ color: foregroundColor('#000') }}` with `foregroundColor` from `@kerfjs/ui/css-values` passed lint while `kerf-ui-analyze` reported `KUI-L014` (and likewise `KUI-L015` for a bare `plus()`). Lint now resolves a helper exactly as the analyzer does: by its imported name, from the component's package or any subpath of it, through a named, aliased, or namespace import. A same-named helper from another package is still ignored (`KF-HKGK2C`).
214
+ - `positionAnchored({ fitHeight: true })` now honors a relative `max-height` cap and is no longer fooled by a `max-height` transition. A cap that stays relative after computing — `max-height: 60%`, `calc(50% - 2rem)`, `min(300px, 60%)`, `clamp()` — was treated as no cap, so an element that fit the preferred side at that cap still opened on the roomier side. kerf now resolves it against the element's fixed-position containing block (normally the viewport) with an unpainted probe beside the element, so the element's scroll position and layout are untouched. And an app `transition` on `max-height` made the cap read report the transition's running value (the room kerf last published) and fire `transitionrun` / `transitionstart` events, so the cap was ignored again; kerf now holds off only the `max-height` transition for that read, and every other transition keeps running (`KF-53GEGN`).
215
+ - A `StateBanner`'s side action no longer squeezes or covers its copy on a narrow banner. The banner laid out as a three-track grid whose action track took the action's full width, so on a phone a pair of buttons (say Retry Save and Discard Changes in a wrapping `Row`) left the title about 65px, and a word wider than that ran underneath the buttons. The banner is now a wrapping row: the default `actionPlacement="trailing"` keeps the action beside the copy while the copy has at least 12rem, and otherwise moves it to its own end-aligned trailing row. The choice follows the banner's own width rather than a breakpoint, so it also works in a narrow sidebar on a wide screen and inside an intrinsically sized `CornerStatus`. `actionPlacement="below"` still always uses the trailing row (`KF-PXCKVZ`).
216
+ - `positionAnchored({ fitHeight: true })` (and so `autoReposition()`, `popover()`, `tooltip()`, and `@kerfjs/ui`'s `openAnchoredSurface()`) now honors the element's own `max-height` when choosing a side. It measured a scrolling element at its full content height, so an element the app caps below that height — say `max-height: min(300px, var(--kerf-anchor-available-height))` with 500px of content — fit neither side and opened on the roomier one, even when its 300px capped height fit the preferred side. kerf now reads that cap with its own published room swapped for an unbounded one, so it never mistakes its last cap for the app's, and the read is style-only, so the element's scroll position is kept (`KF-878W6T`).
217
+ - A keyboard move made just as a `PopupMenu` submenu finishes opening is no longer undone. Web Awesome hands focus to the submenu's first item from a timer it queues when the show animation settles, and a browser may dispatch a keypress before that timer runs. So pressing `End` (or an arrow key) at that moment focused the chosen item, and the late handoff then snapped focus back to the first item. PopupMenu now keeps the keyboard or pointer choice through that handoff; a deliberate `Home` to the first item still stands (`KF-XMDR2Q`).
218
+ - An open `PopupMenu` is now announced with a name. Web Awesome renders the `role="menu"` panel in a shadow root, and the trigger's name never reached it: a `context` menu's `label` sat only on its `aria-hidden` anchor, and no ID reference can cross into or out of the shadow roots involved. So a screen reader announced an unnamed menu, and `getByRole('menu', { name })` found nothing. The panel now takes the trigger's name (the `context` or icon-only `label`, or the visible `text`), and each submenu is named by its parent item's label (`KF-AB4ZVD`).
219
+ - A `TabBar` with `snapTabs` no longer grows its tab strip past its allocation. The snap mode reserves end scroll room so the last tab can settle at the strip's start, and it reserved that room as end padding on the strip. A flex item can't shrink below its own padding, so room measured at one width held the strip open after the bar narrowed. This happened, for example, when a drawer opened or lost space to a neighboring panel. The strip then pushed an adjacent `trailing` action and the `end` zone out of the bar, where they could not be clicked; a twelve-tab drawer strip measured 1584px against a 1088px edge. The room is now scrollable content after the last tab, inside the strip. It lengthens only the scroll range, so the strip shrinks to its allocation and the last tab can still snap to the start. Writing the room no longer resizes the strip, so `wireTabBars` now re-measures it on the next frame until the value holds. This replaces the follow-up measurement that a resize used to trigger (`KF-3Q98FJ`).
220
+ - In Safari, closing a `Select` inside a scrolling dialog body no longer leaves blank scroll space below the content. WebKit kept the closed listbox's last box in the body's scrollable overflow, so the body scrolled into an empty band the height of the listbox. The Select now relayouts its popup once after it closes, which keeps focus and the keyboard on the Select (`KF-C3523R`).
221
+ - In a divided list, `ListItem`, `ListItemLink`, and `ListActionRow` corners now follow the row's position. A corner is flat wherever a divider line meets it, whether the row draws that line or its neighbor does, so with lines between rows the first row rounds only its top, middle rows are flat, and the last row rounds only its bottom. Previously each row squared only the edges it drew itself, so in a `divider="after"` list every hovered or selected row was rounded on top and flat on the bottom, including the last. A single divided row is unchanged (`KF-AQN4H7`).
222
+
223
+ - A collapsible `TokenSearchField` in a `ToolbarControlGroup` with `content="search"` and `sizing="grow"` now opens and closes as one surface. The group snapped straight to its grown width (its `width: auto` cannot transition) while the field animated its own width inside it, so for about 250ms the pill showed an empty band and the query wrapped onto several lines. The group now animates its flex size, and the field fills it on every frame, laid out at least basis-wide while the group clips it. In a toolbar 480px wide or narrower, where the grown group takes its own row, and under reduced motion, both open in one frame (`KF-50K0JM`). A plain collapsible search group (no `sizing="grow"`) had the same defect in a milder form: its field ran a second width transition that lagged the group's by up to 90px, and the query wrapped onto as many as 19 lines for about 100ms. The group now owns that motion too. The field follows it on every frame and keeps the query on one line until the opening ends, then wraps normally again (`KF-CXQB30`).
224
+
225
+ - A tooltip or popover outside a Web Awesome `wa-dialog` / `wa-drawer` is no longer painted beneath it. Those elements keep their modal `<dialog>` in a shadow root, which kerf's modal checks never saw: a surface opened while one was open was not lifted into the top layer, and surfaces already showing were not re-hosted above one that opened later (its `toggle` event stays inside the shadow root). kerf now also checks the open shadow roots when a surface opens, and watches them for `toggle` while any surface is open; a surface hosted inside the dialog stays where it is. A closed shadow root remains invisible (`KF-1FGTX1`).
226
+
227
+ - A `ToolbarControlGroup` now dims a native button marked `aria-disabled="true"` (one kept focusable while unavailable) exactly as it dims a `disabled` one: half opacity, a `not-allowed` cursor, and no hover surface, including a lone group's whole-group hover. It used to look and hover like an enabled control. A disabled raw `wa-button` in a group also no longer paints the group's hover surface (`KF-Y3ZZ10`).
228
+
229
+ - A focused `scrollable` `List` now draws the theme focus ring inset by the ring width and rounded with the standard control radius. Chromium makes a scroller without focusable rows keyboard-focusable, and a dialog may focus it first. It used to show the UA's square outline outside its box, which a rounded or `overflow: hidden` parent clipped (`KF-AJNFTT`).
230
+
231
+ - Typing quickly into a `TokenSearchField` whose app commits typed grammar to chips from `onEdit` (or removes a chip from `keyboard.onRemoveToken`) no longer loses keys. The token change re-keys the editor, so the controlled render replaced the focused element, and keys typed before the app refocused it went nowhere: `site:north site:annex` became `[site:north] ite:annex`. `wireTokenSearchFields` now hands focus and caret to the replacement at the same mutation checkpoint, as it already did for Clear and native deletion. A caret at the end stays at the end, and any other caret keeps its place in the remaining text (`KF-96TEF4`).
232
+
233
+ - `DialogSurface` no longer names a `wa-dialog`'s native panel when the host is itself an explicit, named dialog (`role="dialog"` or `"alertdialog"`). Both used to carry the same name, so the accessibility tree had two dialogs with one name and role queries such as Playwright's `getByRole('dialog', { name })` failed in strict mode. Removing or changing the host role restores the panel name (`KF-A0NF2S`).
234
+
235
+ - A nested `PopupMenu` submenu's pointer "safe triangle" now spans the gap to the placed submenu. Web Awesome measured the submenu for that triangle before its asynchronous placement landed, so the triangle kept the submenu's pre-placement edge (often the viewport origin): its fixed, viewport-sized hit region fanned away from the submenu and could cover the parent menu's rows, swallowing their hover and clicks. PopupMenu now re-measures once the placement lands and again when the submenu's show animation settles, so applications need no `::part(submenu)::before` override (`KF-YAHAZK`).
236
+
237
+ - A `scrollable` `List` bounded by a `max-height` ancestor now scrolls its rows instead of compressing them. Its children kept the default `flex-shrink: 1`, and a `ListItem` clips its own overflow, so multiline rows shrank into one another and their descriptions overlapped the next row. A scrollable List's direct children no longer shrink, and `docs/layout.md` documents bounding one with `flex` inside a max-height flex column (`KF-93GZC1`).
238
+
239
+ - A `popover()`, `tooltip()`, or `openAnchoredSurface()` opened from inside a Web Awesome `wa-dialog` or `wa-drawer` is now interactive. Those elements keep their modal `<dialog>` in a shadow root, so kerf found no dialog above the slotted trigger and appended the surface to `document.body`, where the modal made it inert: it painted above the dialog, but its controls took no focus or input. kerf now resolves the modal context across shadow boundaries: a shadow host whose slot renders the trigger inside an open modal `<dialog>` counts as that dialog, and kerf creates the overlay host slot in the host's light DOM, so the surface is slotted inside the dialog. A surface inside a modal context, through its host slot or an explicit `container`, now also closes when that dialog closes. Escape still closes only the surface. `openAnchoredSurface()` accepts a `container` for any other modal context, and `openAnchoredSurfaceAt()`'s `context` resolves a `wa-dialog` / `wa-drawer` too (`KF-F52T5D`).
240
+
241
+ - Re-renders of a large page whose rows come from a memoized `each()` now scale with the change instead of the row count. The change-scoped morph now also runs on renders that contain `each()` lists: a change beside the list, such as a details pane that follows the selection, is re-parsed and morphed without visiting the rows, and kerf falls back to the full diff when the change sits in the element that holds the rows. After such a render, the scan for list markers skips the bound rows. `SafeHtml` also builds its HTML string on first read instead of at construction, so each element above a list no longer copies every row's markup. A one-row selection on a 300-row memoized keyed page drops from about 3.7 ms to 0.3 ms per render in Chromium (about 29 ms to 3 ms in happy-dom). An attribute set imperatively on an element outside the changed markup now survives such a render, as it already did on list-free pages (`KF-03KWNV`).
242
+
243
+ - On the same kind of page, a mount that also has a fine-grained binding outside the list (for example `class={signal}` on a page wrapper) no longer searches every row for binding markers after a render that changed the page. Rows carry only their own row-scoped markers, so kerf now skips them. A selection flip on the 300-row keyed fixture with one such binding drops from about 3.7 ms to 0.4 ms in Chromium (about 66 ms to 6 ms in happy-dom) (`KF-5S9XPH`).
244
+
245
+ - `wireTabBars` no longer re-measures every tab strip after every DOM mutation in the root it watches. It used to read computed style and layout for each strip whenever anything under the root changed, such as terminal output or a list update. In Hot Sheet's terminal profile that work was the single hottest function. Now only the bars a mutation touches are re-measured: a change inside a bar, a newly inserted bar, or a `dir` change on an element above one. A strip with a pinned tab also re-measures when its own size changes (`KF-8H2MH2`).
246
+
247
+ - `resource().run()` can be called inside an `effect()`. `run()` read the resource's own state through a tracking read, so an effect that re-ran a resource from an input signal subscribed to that state, wrote it, and threw `Cycle detected`. `run()` and its progress and failure paths now read the state untracked; `resource.value` stays a tracking read (`KF-H5PNHK`).
248
+
249
+ - Re-renders of a large list-free page now scale with the change instead of the page. When a `mount()` render has no `each()` list and no fine-grained bindings, kerf compares the previous and next static HTML, finds the innermost element around the change whose markup parses on its own, and re-parses and morphs only that element's changed children; anything it cannot prove identical to a full diff still takes the full diff. A one-row selection on a 300-row, ~1.4 MB page drops from about 23 ms to 13.5 ms per render in Chromium. One documented behavior narrows: an attribute set imperatively on an element whose markup did not change now survives a render that changed something else, as it already did on a no-op render. The core grows by about 2 KB min+gzip (~13 KB to ~15 KB) (`KF-HA8R27`).
250
+
251
+ - The morph no longer strips the defaults a custom element reflects onto its host. Web Awesome reflects `variant`, `appearance`, `size`, `attention`, and similar defaults onto `wa-button`, `wa-tag`, `wa-badge`, `wa-textarea`, and others; a template that omitted them lost them on every re-render that reached the element, and Lit put them straight back with a full update (one row selection on a 300-row page flipped 1,200 attributes). On custom elements the morph now removes an attribute the template omits only when the previous template rendered it; a template that stops rendering an attribute still removes it, and plain elements are unchanged. An attribute set imperatively on a custom element now survives re-renders (`KF-K8S4RX`). Elements kerf creates (a mount's first render, a morph insertion, a new `each()` row) start with their template's record, taken before they connect, so even the first re-render leaves their reflected defaults alone; only an element kerf did not create uses the ordinary rule on its first attribute sync (`KF-G7N4PK`).
252
+
253
+ - `KUI-L017` (exceptional spacing shorthand, such as `<List gap="s" />`) now has one severity everywhere: a review finding. `eslint-plugin-kerfjs` reported it from the `error`-level `ui-css-values` rule, so a deliberate off-scale choice failed lint while `kerf-ui-analyze` queued it for review, and `kerf-ui-doctor` counted every occurrence twice (error plus review) with a `KUI-D003` conflict warning. The finding moves to a new `ui-exceptional-shorthands` rule, `warn` in both `recommended-ui` and `strict-ui`; `ui-css-values` keeps `KUI-L013`–`KUI-L016` at `error`. The doctor reads an ESLint warning for an analyzer review code as that review finding, and the analyzer's `KUI-L014`–`KUI-L017` messages now match ESLint's word for word, so the doctor merges each CSS-value finding into one diagnostic. A new `@kerfjs/ui` contract test fails if any ESLint UI rule's preset severity disagrees with the analyzer's classification of the codes it reports (`KF-P3945Y`).
254
+
255
+ - `mount()` no longer walks the whole live tree for `each()` list markers after a re-render that changed the page when the render has no `each()` lists and no list is bound. A large list-free page (one `mount()` with plain `.map()`) paid a full DOM traversal per render for markers kerf never emitted (`KF-VBQJAX`).
256
+
257
+ - Faster JSX attribute serialization on large pages: the runtime remembers, per attribute name, that the name passed the `on*` / malformed-name check and whether it is URL-bearing, instead of re-running those regexes for every attribute of every render, and the URL screen returns early for values without a `:` (no scheme to screen). Rejected names still throw their exact message on every render, and every URL value is still screened. Building a 300-row, ~1.4 MB list-free page drops from about 13.7 ms to 10.8 ms of CPU (`KF-VBQJAX`).
258
+
259
+ - `wireScrollDividers` no longer forces a synchronous layout after a render. A content mutation used to re-measure the scrollers in the next animation frame, and a structural one at once in the mutation callback, both before the browser had laid out the new tree. Both now re-measure once the frame has laid out and before it paints: the wiring toggles an inert, zero-size probe outside the app tree, and its `ResizeObserver` reports the probe after layout. Without `ResizeObserver` the previous timing remains. In a 300-row work area, `measure` self time drops from about 408 ms to under 1 ms over 16 segment switches and 8 row selections; the layout itself now runs once, in the browser's frame (`KF-4XYQ95`).
260
+
261
+ - `wireWorkbench` no longer forces a document-wide style recalculation after ordinary renders and presses. It caches each responsive panel's computed overlay state until a Workbench resize, a root font-size change, or a presentation attribute change on that panel, and its observer re-syncs only for a new Workbench, an added or removed panel, or an attribute change on a panel rather than any `data-collapsed` or `data-presentation` change below the root. In a 300-row work area with Web Awesome menus, the overlay check's forced style time drops from about 150 ms to 0 over 16 segment switches and 8 row selections (`KF-CRRD70`).
262
+
263
+ - Faster `PopupMenu` and `LucideIcon` re-renders in large lists. `LucideIcon` returns the same `SafeHtml` for the same icon and props instead of rebuilding its `<svg>` every render (up to 64 prop variants per icon), and builds its child markup as a Fragment instead of wrapping joined strings in `raw()` (`KF-XW15D6`). `PopupMenu` hashes icon and details markup of 64 or more characters as a memoized digest of the whole string instead of reading every character every render. A 300-row list with a nine-entry menu per row drops from about 12.7 ms to 2.1 ms per render when the icons are rebuilt each render, and from 3.9 ms to 1.3 ms when they are prebuilt. A menu with such a part now has a different `data-key` value than before; the key is still stable across renders, and every other byte of the rendered HTML is unchanged (`KF-V2ZBHT`).
264
+
265
+ - `PopupMenu` hashes its content key with a streaming `charCodeAt` loop instead of joining every field (including icon markup) into one string and iterating its code points, and caches each menu's trigger and entry markup in a bounded least-recently-used cache keyed by that hash and an independent check hash. An unchanged menu now costs one hash pass instead of rendering every entry again for the morph to skip. Rendered HTML, including the `data-key` digest, is byte-identical (`KF-GVCMC7`).
266
+
267
+ - Faster attribute serialization for large static values: `LucideIcon` caches each icon node's rendered child markup by node identity, and the JSX runtime's HTML/attribute escaping skips its replace passes when a value has nothing to escape. A 138-icon render pass drops from about 0.80 ms to 0.45 ms (`KF-JPP0Z5`). `jsx()` also iterates props without the rest-spread and `Object.entries` allocations, and the URL screen checks lowercase attribute names without allocating a lowercased copy, about 25% faster for an attribute-heavy list row (`KF-YHNV84`).
268
+
269
+ - `wireTokenSearchFields` collapses an empty field blurred by a pointer press in the click's own task, after the click reaches the window, instead of a separate task, so the click's render and the collapse share one style recalculation; a click that stops propagating still falls back to the next task (`KF-AS24QP`).
270
+
271
+ - `wireScrollDividers` no longer re-collects pairings and re-measures every scroller for mutations that cannot change a pairing, such as a row's selection class or a list morph inside scrolled content; it still refreshes when structural elements or target ids are added, removed, re-classed, or renamed (`KF-50PA0Y`). Those content mutations instead re-measure the known scrollers once in the next animation frame, so an absolutely positioned descendant that extends the scroll area still updates its dividers (`KF-E29N3W`).
272
+
273
+ - The UX Catalog filter keeps its placeholder hidden when a controlled state change rerenders the sidebar while filter text remains (`KF-4EA9R6`).
274
+
275
+ - Inspector TabBars use the shared rounded rectangle radius on the strip and inset tabs while ordinary segmented TabBars retain their pill geometry (`KF-K3RDN1`).
276
+
277
+ - **`KUI-L103` no longer flags a component's classes inside its own source.** `ui-public-boundaries` treats a catalog entry's `source` file as the owner of that entry's public classes, so an app component writing its own root class is not reported as recreating itself. Apps no longer need to mark those classes `placeableClasses` to silence it. Any other file, including another component's source, is still checked (`KF-G6FR6V`).
278
+
279
+ ### Documentation
280
+
281
+ - The `@kerfjs/ui` UX catalog's Structured Ticket Search help is lighter: a short title and line, then grouped filter chips (action `Chip`s) that insert their filter into the field, instead of a key/value table. The SearchField examples' notes are shorter too (`KF-XP8742`).
282
+
283
+ - New recipe in the `kerfjs/async` API reference: move heavy app compute (fuzzy search, CSV or markdown parsing, aggregation) into a Worker by having a `resource()` fetcher post a message to the worker and resolve with its reply. It covers request/reply ids, dropping superseded results, worker errors, transferring `ArrayBuffer`s, and keeping the render on the main thread (`KF-04KHT9`).
284
+
285
+ - Clarify for AI consumers that sunken/lowered token names resolve to a translucent tint, and explain intentional nested layers versus duplicate surface paint (`KF-9CM6D8`).
286
+
287
+ - **`layout.roles` vocabulary for app components.** The component-packages guide documents the eleven roles `@kerfjs/ui` uses, what each covers, and how to map application dialogs, rows, status indicators, and composed views onto them. The `kerf.components.json` schema description lists them, and the `create-kerf-component` template now uses `controls` instead of a one-off `counter` role (`KF-4E04HF`).
288
+
289
+ ### Removed
290
+
291
+ - **Breaking (`@kerfjs/ui`, 5.0 beta):** remove the Catalog geometry highlight overlay, its `geometryOverlay` prop, `wireCatalogGeometryOverlay` helper, and specimen skip marker. Catalog previews retain their component borders, outlines, and focus states (`KF-E3WKA5`).
292
+
293
+ - **Breaking (`@kerfjs/ui`, 5.0 beta):** remove the deprecated `TabScaffold` component and type aliases, `wireTabScaffold` and `WireTabScaffoldOptions`, and the `tab-scaffold`, `wire-tab-scaffold`, and `tab-scaffold.css` package subpaths. Use `TabNavigator`, `TabNavigatorTab`, `TabNavigatorProps`, `wireTabNavigator`, and their corresponding subpaths. The rendered DOM classes and data attributes remain stable. See `ui/docs/tab-navigator.md` for migration steps (`KF-CMK0W8`).
294
+
295
+ ### Added
296
+
297
+ - **Typed background colors on `@kerfjs/ui` layout surfaces.** `Pane` takes `background`, a `CssColor` from `@kerfjs/ui/css-values` (`uiColor(...)`, `fillColor(...)`, or `colorVar(...)`). It paints the whole pane and replaces the default or sunken fill, and it is in `PaneConfig`, so Workbench panels, `CollapsiblePanel`, and `NavStack` view panes forward it. `NavStack` and `TabNavigator` take their own `background` for the stack or navigator surface and their docked bars, and each `TabNavigatorTab` takes one for its scene. Overlay chrome keeps the translucent material, and forced colors paint `Canvas`. Omitted, every surface keeps its current color.
298
+ - **Static-effects switch for `@kerfjs/ui`.** Set `data-kui-effects="static"` on the root element (`document.documentElement.dataset.kuiEffects = 'static'`) to turn every backdrop effect opaque and stop every scroll-driven animation. Use it when the app detects a low-power device itself, since CSS has no reliable signal for one. A slow-updating display (`@media (update: slow)`, such as e-ink) gets the same result automatically. The translucent chrome material (overlay `Pane` headers, `NavStack` and `TabNavigator` overlay bars, floating `DialogSurface` headers) resolves to the opaque surface, as it already does under reduced transparency.
299
+ - `ToolbarControlGroup` takes `material: 'solid' | 'glass'` (default `solid`). A `glass` group paints the translucent chrome material (`--kui-chrome-material`, blurred and saturated by `--kui-chrome-material-filter`), replaces its gray border with a specular edge highlight, and floats on a soft shadow. Use it for per-control glass pills over imagery or a clear (transparent) toolbar, for example inside a `FloatingToolbar`. Its controls take the normal text color, and a raised or outline selection paints an opaque surface pill. Rest, hover, and selected controls keep WCAG AA over worst-case content in light and dark: the bare material leaves the brand selected color at about 3.2:1 over black. The fill turns opaque under reduced transparency, increased contrast, static effects, or without `backdrop-filter`, and the edge gives way to the normal border there. A dark-toned glass group's loud fill turns opaque too. Forced colors paints `Canvas`/`CanvasText` with no filter or shadow. A borderless group ignores the material.
300
+ - **`BackdropImage`.** `@kerfjs/ui/backdrop-image` opens a scrolling Pane or NavStack view with a hero or tiled image (`src`/`srcset`/`alt`, `fit`, `position`, `repeat`, typed `height`). `parallax` (`subtle` or a 0 to 1 factor) lags the image on a compositor-only scroll-driven timeline with no scroll listener or `background-attachment: fixed`; a typed `fadeTo` color dissolves it through a mask and keeps painting under its `children`, so the page reads as one surface; `overlay` content sits over its block end with an optional `scrim`. It is static without scroll-driven animation support, under reduced motion, `data-kui-effects="static"`, or on slow-update displays, and ends on a hard edge over solid `fadeTo` under reduced transparency or increased contrast.
301
+ - **`BackdropImage` progressive blur.** `blur={{ radius?, blurredSrc?, dim? }}` stacks a copy of the image blurred once (a CSS `filter` of `radius`, default 24px, overhanging the block so its fringe is clipped) or an app-supplied pre-blurred `blurredSrc`, and fades only its opacity (plus an optional black `dim` layer) in over the first half of the image's scroll exit, so the blur is at full strength while most of the image is still in view; the filter never animates. A Chromium trace across 200 scroll frames recorded no `Paint` events and no per-frame raster. Static and sharp wherever the parallax is static.
302
+ - `TabNavigator` takes `barPresentation: 'docked' | 'overlay'` (default `docked`). With `overlay`, the tab bar lies over the active scene on the translucent chrome material, so content scrolls visibly beneath it, as under an iOS tab bar. `wireTabNavigator` measures the live bar (bottom safe area included), and the scenes hand its height to their content as the block-end edge inset: a plain scene, a sole `Pane`, or a `NavStack` (whose own overlay bottom toolbar then sits just above the bar) rests its last item clear of it. Unselected and selected labels lift to keep AA over the material. The bar is opaque under reduced transparency, increased contrast, or without `backdrop-filter`, and paints `Canvas` with a `CanvasText` edge in forced colors. Unwired, the bar stays docked. Like the NavStack overlay bars, the tab bar ends where the active scene's classic (space-taking) scrollbar begins, so the thumb and buttons stay visible.
303
+ - `@kerfjs/ui/wire-list-focus-scroll`'s `wireListFocusScroll(root)` brings a keyboard-focused row of a `scrollable` List fully into view, focus ring included, in every engine. Firefox's `focus()` leaves a partly hidden row alone until about half of it is hidden and then centers it, and Safari's never scrolls it, so arrow-key or Tab navigation could rest on a row that was mostly clipped. The wiring calls `scrollIntoView({ block: 'nearest' })` only when a `:focus-visible` element's ring crosses the List's clip, honoring its ring-room scroll padding; pointer focus is left alone, so a click never scrolls its row from under the pointer.
304
+ - **`AnchoredSurface` dark tone for popups anchored to media chrome.** `openAnchoredSurface` and `openAnchoredSurfaceAt` take `tone: 'dark'`, the same loud, inverse tone as a `ToolbarControlGroup` or `ToolbarText` `tone="dark"`. A volume popup anchored to a dark media control group over a video preview is dark beside a light page and light beside a dark one, matching the group that opened it. The surface takes the opposite of its anchor's color scheme when it opens and is marked `data-tone="dark"`. Every semantic token is a `light-dark()` pair, so the content inherits the inverse text, border, and focus colors without tone props or overrides: a `ListItem` mute row and a `wa-slider` included. Measured on the catalog demo in Chromium, Firefox, and WebKit, the row label reads 12.8:1 and its focus ring 8.1:1 on a light page, and 16.8:1 and 4.0:1 on a dark one. The default tone is unchanged.
305
+ - A floating `DialogSurface` title bar (`headerPresentation="floating"`) now draws its divider as scroll state, like an overlay `Pane` header: a 1px line along its bottom edge while the body, or a filling child that reaches beneath it (a transcript `List` or `Pane` with block-start `scrollClearance`), is scrolled away from its top, and none at rest. In light mode the title bar over white bubbles had little separation. `@kerfjs/ui/surface-scaffold/register` follows those scrollers; a nested scroller that starts below the title bar never counts.
306
+ - **Analyzer and lint check row icon-tile colors.** Catalog `cssValueProps` paths now reach a member of an object-valued prop (`iconTile.color`) as well as each array item's member (`choices[].swatch`); a prop given a non-object value, such as a tone string `iconTile="brand"`, is skipped. `ListItem`, `ListItemLink`, and `ListActionRow` record `iconTile.color` as a color fill (`fillColor()`, `uiColor()`, `colorVar()`) and `iconTile.foreground` as a foreground (`uiColor()`, `foregroundColorVar()`, `foregroundColor()`), so the Kerf UI analyzer, `kerf-ui-doctor`, and the `kerfjs/ui-css-values` ESLint rule report `foregroundColor()` on a tile fill (`KUI-L014`) and keep accepting it as the glyph color. The catalog and composition schemas' `path` pattern accepts the same grammar, so consumer catalogs can publish object-member paths (`KF-R02RDK`).
307
+ - **Catalog frames can be a named anchor with a centered content column.** `CatalogExample`'s `viewport` takes `anchorName`, a CSS dashed-ident (`"--app-shell-main"`) that becomes the frame's `anchor-name`, so a top-layer specimen (a `popover="manual"` request popup, say) whose own CSS sets `position-anchor` to that name positions against the frame exactly as it does against its production anchor. An invalid name throws a `TypeError`. `minHeight` adds `"app"` (592px, a floor the frame can grow past), and `contentWidth` (`"compact"` 440px, `"medium"` 640px, or `"wide"` 864px, capped at the frame) with `contentAlign` (`"start"` or `"center"`) gives each in-flow child a centered or start-aligned reading column; `[popover]` children keep their own geometry. An app no longer needs a wrapper stage element to name the anchor and center the column. The catalog's Application Layout page shows a request popup docked to the bottom of its frame (`KF-D532S2`).
308
+ - **`fillColor()` for application fill colors.** `@kerfjs/ui/css-values` adds `fillColor(value)`, the fill twin of `foregroundColor()`: it accepts one application-chosen CSS color (`#3b82f6`, `rgb(20 40 60 / 0.8)`, `rebeccapurple`) with the same single-declaration check, but returns a plain `CssColor` rather than a `CssForegroundColor`, so a fill literal is rejected by props that paint text or an icon (`SelectChoice.color`, `LucideIcon.color`, `Text.color`, an `iconTile` `foreground`). Use it for a `ChoiceChips` `swatch` and a list row's `iconTile` `color`; every example, demo, and design template now does. A `CssForegroundColor` is still a `CssColor`, so an existing `foregroundColor()` fill keeps compiling, and the `ChoiceChips` catalog entry now records `choices[].swatch` as a color fill so the Kerf UI analyzer reports `foregroundColor()` there (`KUI-L014`) with `fillColor()` as the fix (`KF-7JA25S`).
309
+ - **Framed result pickers without app CSS.** `List` takes `frame`, `maxHeight`, and `minHeight` (typed `CssLength`s from `@kerfjs/ui/css-values`). `frame` draws a 1px neutral border with the `--kui-radius-m` control radius and a 4px inset on every side, replacing `inset`, `textInsets`, and `controlInsets`. That inset is exactly a row's focus-ring reach, and the frame adds it to its scroll padding, so the first and last rows' rings stay inside the clip. With `scrollable`, the height bounds work without a flex-column ancestor. `<List scrollable frame gap="2xs" minHeight={rem(4.25)} maxHeight={rem(14)}>` is a bounded list of `ListItem` candidates, such as Hot Sheet's duplicate-ticket picker. The catalog's List page shows it as "Result Picker" (`KF-SHW2J9`).
310
+ - **Transcripts scroll beneath a floating composer.** A `scrollable` `List` and a `Pane` take `scrollClearance` (`"block-start"`, `"block-end"`, or `"both"`; the `ScrollClearance` type). It clears chrome laid over the scroller's block edge inside its own scroll area: the scroller adds the inherited `--kui-scroll-clearance-block-start` / `--kui-scroll-clearance-block-end` context that the chrome publishes to its block padding and `scroll-padding`. Content then passes visibly beneath the chrome, while the first and last items, and anything focused or scrolled into view, still rest clear of it. A `DialogSurface` with `footerPresentation="floating"` publishes block-end clearance for a `fill` or `fill-last` child that opts in. That clearance is the footer's measured height plus its offset. The body stops reserving the footer below that child, so a chat transcript reaches the panel's end and scrolls beneath the transparent composer. Without the opt-in, the transcript still ends at the composer's top. Every dialog body clears clearance inherited from the page. An app that overlays its own translucent chrome on a scrolling region publishes the same context, so header clearance works today. The catalog's chat dialog now scrolls its transcript beneath the composer (`KF-ET0EX8`). `PaneConfig` carries `scrollClearance` too, so a composed Pane opts in through a Workbench `mainPane` or panel `pane`, a `CollapsiblePanel` `pane`, or a `NavStack` view's `pane`; the composites now forward every `PaneConfig` field through one exhaustively typed helper, so a new field can no longer be silently dropped (`KF-574HQV`).
311
+ - **Translucent overlay Pane headers.** `Pane` takes `headerPresentation` (`"docked"`, the default, or `"overlay"`; the `PaneHeaderPresentation` type, also in `PaneConfig`). An overlay header is laid over the top of the scrolling content on the new chrome material. The material is `--kui-chrome-material`, the surface at 80% opacity, behind `--kui-chrome-material-filter`, a blur and saturation backdrop filter, so content scrolls visibly beneath the header. `wireScrollDividers` measures each overlay header with a `ResizeObserver` and publishes its height on the Pane as `--kui-scroll-clearance-block-start`. The Pane's content clears that automatically, so the first item rests just below the header and anything scrolled into view stays clear of it. The clearance follows the header as its title wraps or its text grows. Until the wiring runs, and with `chromePlacement="auto"`, the header stays docked. The material turns opaque under `prefers-reduced-transparency: reduce` or `prefers-contrast: more`, and without `backdrop-filter`. In forced colors the header paints `Canvas` with a `CanvasText` edge. Normal text keeps WCAG AA over any content beneath the material. Quiet text does not, so overlay-header text uses the normal text color (`ui/docs/accessibility.md` "Chrome material"). The catalog's Pane page shows an inbox scrolling beneath its header (`KF-DT6C3F`).
312
+ - **Translucent dialog title bars.** `DialogSurface` takes `headerPresentation` (`"docked"`, the default, or `"floating"`; the `DialogSurfaceHeaderPresentation` type). A floating header lies over the body's block start on `--kui-chrome-material-raised`, a new token for chrome on a raised surface: the raised panel color at 80% opacity behind `--kui-chrome-material-filter`. The `surface-scaffold/register` import now measures the header as well as the footer, and the body reserves the header's height before its own inset, with matching scroll padding, so flowing content starts below the title bar and scrolls beneath it. Without the register, the header stays docked. When the body's only child fills it and opts into block-start `scrollClearance`, the body publishes the header's height as `--kui-scroll-clearance-block-start` instead. With a floating composer and `scrollClearance="both"`, a transcript then scrolls beneath both the title bar and the composer while its first and last messages rest clear of them. The material has the same opaque fallbacks as the Pane overlay header, and normal text keeps WCAG AA over any content beneath it. An untoned `ToolbarText` slotted as the dialog's label (or into its header actions) takes the same AA lift it gets in an overlay Pane header: a normal-color title and a description mixed halfway toward it. The catalog's surface scaffold page adds a "Floating Title Bar" thread dialog (`KF-REH2T2`).
313
+ - **Translucent NavStack top bar.** `NavStack` takes `chromePresentation` (`"docked"`, the default, or `"overlay"`; the `NavStackChromePresentation` type). An overlay top chrome lies over the active view on the same chrome material as an overlay Pane header, so content scrolls visibly beneath it, as under an iOS navigation bar. `wireNavStack` measures the live chrome (never a cross-fading copy) with a `ResizeObserver`, publishes its height on the stack root with a `data-chrome-overlay="measured"` gate, and restores both before paint if a re-render strips them. The measured height, top safe area included, becomes the viewport's block-start edge inset, so a plain view, a sole `Pane`, or a nested layout clears the bar automatically: the first item rests just below it, and focused or scrolled-to content stops clear of it. A classic, space-taking scrollbar in the active view stays uncovered: the chrome ends where its track begins. Unwired, or with `hideToolbar`, the chrome stays docked. The material keeps its opaque fallbacks (reduced transparency, increased contrast, no `backdrop-filter`) and its forced-colors edge, and an untoned `ToolbarText` in the chrome lifts its title and description to AA exactly as in an overlay Pane header. `SplitView` forwards the option through `compactStack`, and a Workbench navigation panel through `navStack`. The catalog's NavStack page adds an **Overlay Chrome** example; `ui/tests/browser/overlay-nav-stack.spec.ts` covers it in Chromium, Firefox, and WebKit.
314
+ - **Translucent NavStack bottom toolbar.** `NavStack` takes `bottomToolbarPresentation` (`"docked"`, the default, or `"overlay"`; the `NavStackBottomToolbarPresentation` type), a separate prop from `chromePresentation`, which keeps governing only the top chrome. An overlay bottom toolbar lies over the active view's bottom edge on the same chrome material, as an iOS toolbar does. `wireNavStack` measures the live toolbar (never a cross-fading copy), publishes its height with a `data-bottom-toolbar-overlay="measured"` gate, and the measured height, bottom safe area included, becomes the views' block-end edge inset: a plain view's or a sole `Pane`'s last item (or the Pane's footer) rests just above the toolbar while content scrolls visibly beneath it, and the toolbar's scroll divider keeps working. Unwired, or while no bottom toolbar is shown, it stays docked; inside a `TabNavigator` scene it sits just above the tab bar. It keeps the material's opaque fallbacks, and in forced colors its top border becomes a `CanvasText` edge. A default-tone `ToolbarControlGroup` in either overlaid bar now lifts its controls to the normal text color, so they keep AA over the content beneath (the top chrome's back control measured about 3.0:1 before). A non-scrolling `List` directly in a `Pane`'s content no longer shrinks below its rows, so the content's block-end padding (a bottom safe area or the toolbar's clearance) follows the last row. `SplitView` forwards the option through `compactStack`, and a Workbench navigation panel through `navStack`. The catalog's **Overlay Chrome** example now overlays both bars; `ui/tests/browser/overlay-nav-stack-bottom.spec.ts` covers it in Chromium, Firefox, and WebKit.
315
+
316
+ - **Anchored surfaces fit beside their anchor.** `positionAnchored()` / `autoReposition()` (and so `popover()` and `tooltip()`) take `viewportMargin`, a gutter in px that the horizontal clamp and the vertical fit test keep from the viewport edges (default `0`, the bare edge as before), and `fitHeight` for an element that scrolls its overflow: when neither side has room for its full height it opens on the roomier side, and every placement publishes that room as the `--kerf-anchor-available-height` custom property on the element, so CSS can cap it (`max-height: var(--kerf-anchor-available-height); overflow: auto`). Scrolling inside the element keeps its scroll position. Without the new options placement is unchanged. `@kerfjs/ui`'s `openAnchoredSurface()` uses both: the surface stays 8px inside the viewport (`viewportMargin` overrides it), caps its height to the room beside its anchor, scrolls its content, and exposes that room to its content as `--kui-anchored-surface-available-height`, refreshed on scroll and resize, so a tall help surface fits beside a field on a phone with no application media queries (`KF-K4GE6K`).
317
+
318
+ - **Stateful `TokenSearchField` trailing action.** `trailingAction` now takes `expanded` (a disclosure such as a help toggle; renders `aria-expanded`) or `pressed` (a toggle; renders `aria-pressed`), which are mutually exclusive at compile time, plus `controls` (`aria-controls`), `haspopup` (`aria-haspopup`), and `attributes` for domain `data-*` metadata (the field keeps `data-action`). An open or pressed button keeps its hover fill and reads at full text strength. In the `toolbar-group` presentation it now takes the clear button's control-highlight radius, so the compact 24px help glyph beside the clear button matches it in every presentation with no application CSS. The catalog's Structured Ticket Search help toggle opens syntax help in an `openAnchoredSurface` (`KF-R056AJ`).
319
+
320
+ - **Link `Chip` for downloadable files.** `Chip` takes an `href`, with an optional `download` (`true` or a suggested file name) and `external` (new tab, `rel="noopener noreferrer"`, and an "(opens in new tab)" accessible-name suffix, as on `ListItemLink`). It then renders a native `<a>` with the chip's geometry, icon slot, truncation, focus ring, and hover feedback, so an app no longer styles its own file-link chips. A link chip cannot also carry a remove button, and a disabled one drops its destination and leaves the tab order. The new `inherit` tone (`ChipTone`) follows the surrounding foreground, for a chip inside a `brand-loud` or `neutral` `ContentItem` bubble. It draws a currentColor border and no fill, so the label keeps the bubble's text contrast, and its focus ring follows the foreground too. The Chip catalog shows file chips in both bubble kinds (`KF-H658D6`).
321
+
322
+ - **Multi-select `ChoiceChips`.** Set `multiple` with a `readonly Value[]` `value` and the same wrapping pills, swatches, and icons become native checkboxes in a named `role="group"`: each pill is its own Tab stop, Space toggles it, assistive technology reads its native checked state, and every checked value submits under `name` (`FormData.getAll(name)`). The props are a discriminated union, so a multiple group rejects a single value (and a single group an array), and a multiple group takes no `required`. Every chip color is a theme token, so on dark inverse chrome, such as a media viewer's annotation intents, place the chips in a dark appearance scope (`.wa-dark`) rather than restyling them. The UX catalog adds Multiple Selection and On Dark Chrome examples, and the design templates add a Multiple Selection variant.
323
+ - `ListItem`, `ListItemLink`, and `ListActionRow` take an `iconTile` prop that presents the leading icon in a filled 32px rounded tile holding an 18px glyph, for settings and command rows identified by color. Pass a tone (`neutral`, `brand`, `success`, `warning`, or `danger`, the same quiet palette as `ToolbarControlGroup.tileTone`) or `{ color, foreground? }` with a typed `CssColor` fill (`uiColor()`, `colorVar()`, or `foregroundColor('#e5484d')`) and an optional `CssForegroundColor` glyph; without a foreground, the glyph is black or white, whichever contrasts with the fill. The tile keeps 6px clear of a standard 44px row, a compact row is at least 42px tall, the label moves to the tile's edge, and hover and selection leave the tile's colors alone.
324
+
325
+ - **A chat composer without app chrome.** The new `Composer` (`@kerfjs/ui/composer`) is a raised frame (the standard border, large radius, and `shadow-l`) whose border turns brand while focus is within. It holds a borderless textarea that grows with `field-sizing: content` between `minRows` (default 1) and `maxRows` (default 8) lines and then scrolls. Below the textarea sits an action row with an optional quiet `hint`, which describes the field when you pass an `id`, and the trailing `actions` (a Send button). Engines without `field-sizing` show a fixed three-line field that scrolls. Slot it into a `DialogSurface` floating footer to float it over a transcript; the catalog's chat dialog now does (`KF-S5EG5K`).
326
+ - **Enter-to-send for `Composer`.** Set `submitOnEnter` and call `wireComposers(root)` (`@kerfjs/ui/wire-composers`) once: Enter, or Cmd/Ctrl+Enter, in the field clicks the composer's first trailing action, so a keyboard send runs the same delegated `data-action` handler as a click. Shift+Enter still inserts a newline. An Enter that commits an IME composition (`isComposing`, keyCode 229, or between `compositionstart` and `compositionend`) is left to the input method, and an empty or whitespace-only message, an auto-repeating key, a disabled field, or a disabled or loading action sends nothing. The field announces the shortcut with `aria-keyshortcuts="Enter"`. The catalog's Composer and chat dialog examples use it (`KF-DGD5QS`).
327
+ - `PopoverDialogSurface` takes an optional `describedBy` id, rendered as `aria-describedby` on its `role="dialog"` root. Pair it with a title `ToolbarText`'s `descriptionId` so a non-modal dialog keeps its accessible description; `rootAttributes` accepts only `data-*` attributes, so there was no way to set it before. `DialogSurface` is unchanged, because it wraps a `wa-dialog` that the app authors and does not render the dialog root itself (`KF-SKVEQW`).
328
+ - A compact `ListActionRow` is 36px tall, as documented, instead of 44px. Its label kept the standard row's minimum height and its primary button kept the standard 8px block padding, so `density="compact"` had no effect on a single-line row. Compact rows now use 4px block padding like a compact `ListItem`, so the two row kinds stay level in a dense list; a compact row with an `iconTile` is exactly 42px. The ListActionRow catalog adds a Compact Rows example (`KF-4Q5MJ5`).
329
+ - `ListActionRow` leading icons default to 18px (they were 24px), the same size as `ListItem` icons, so a `List` that mixes the two row kinds starts their labels on one edge, not 6px apart. Both read a new shared `--kui-list-row-icon-size`: set it on a containing `List` to resize both row kinds' untiled icons together. `--kui-list-item-icon-size` still wins for `ListItem` rows that set it, and an `iconTile` keeps its 32px tile and 18px glyph. An app that wants the old 24px `ListActionRow` glyphs sets `--kui-list-row-icon-size: 24px` on the list (`KF-KWFMM1`).
330
+ - `ListItem` and `ListActionRow` share one leading inline inset. Set `--kui-list-row-padding-inline` on a containing `List` and both row kinds move their content and reorder insertion lines together; a `ListActionRow` adds the 1px a `ListItem` border takes, so their leading icons stay on one edge at any value. It defaults to `--kui-layout-item-padding`, so unset lists render as before. Previously only `ListItem` had an inline padding token, and overriding it moved `ListItem` icons away from `ListActionRow` icons in the same list. `--kui-list-item-padding-inline` still wins for `ListItem` rows that set it. The List catalog's new Shared Row Inset example shows mixed rows on a customized inset (`KF-N3TDV3`).
331
+ - `@kerfjs/ui` now has one capitalization rule for interface copy, taken from Apple's guidance and documented in the new `ui/docs/writing.md`. Text that names a command, control, view, or field is title style ("Save Draft", "Back to Inbox", "Workspace Settings"): buttons, menu items, segments, `Select` choices, tabs, titles, `ListHeader` labels, and field labels. Text that describes, explains, or reports is sentence style: descriptions, messages, tooltips, placeholders, option text, and status lines. The AI skill, `llms.txt`, and the design docs carry the rule. `kerf-ui-doctor` reports a lowercase word in a known title-style label as the warning `KUI-D040`, with the repaired label. The catalog demos, recipes, and design templates now follow the rule (`KF-6VWSV4`).
332
+ - **Chat-style dialogs without `::part()` rules.** `DialogSurface` gains `footerPresentation="floating"`, which lays the footer over the body's block end, a typed `footerOffset` from the panel's inline and block-end edges (default the 16px container inset), on a transparent background. The `surface-scaffold/register` import measures the footer, and the body reserves that height plus the offset, so a growing composer never hides the transcript's last message. `bodyLayout="fill-last"` (also on `PopoverDialogSurface`) keeps the body's leading children at their natural height and gives the last child the remaining height and its own scrolling: a notice above a scrolling transcript. The catalog's new chat dialog example composes both (`KF-913AT2`).
333
+ - `@kerfjs/ui`'s title-style rule now reaches the names the doctor could not see. `TokenSearchField`'s default `clearLabel` is `Clear Search` (it was `Clear search`); a test or app that addresses the clear control by its default accessible name needs the new spelling, and `clearLabel` still overrides it. The catalog shell (`Filter Catalog`, `Clear Filter`, `Reduce Motion`, `Vertical Stripes`, `Layout Guide`, `Related Entries`, `Capture Region`, the `Demo Source` / `Component Source` / `Design Template` / `Integration Guidance` resource links, and the `Used By` related group), the catalog entry names that render as page titles (`Foundation Tokens`, `Surface Scaffolds`, `List Workspace States`, …), and the demos' and recipes' accessible region, control, field, dialog, tab, and list-item names are title style. `kerf-ui-doctor`'s `KUI-D040` now also reads the accessible names of icon-only controls: `IconButton` / `IconToggleButton` / `PopupMenu` `label`, `SplitButton` `optionsLabel`, `TokenSearchField` `clearLabel`, and the `aria-label` of a `button` or `wa-button` whose only content is an icon (`KF-ZAD6EJ`).
334
+ - `@kerfjs/ui` catalog example and stack labels are headings, so they now use title style across every UX-demo page ("Heading Identity Stays Whole", "Icon Trigger in a Toolbar Group"); their notes stay sentence style. Demo content item titles ("Build Output", "Work Area") follow, with mirrored `ariaLabel`s. `kerf-ui-doctor`'s `KUI-D040` now reads `CatalogExample` and `CatalogExampleStack` `label`, and keeps a minor word inside a longer hyphenated compound lowercase ("Edge-to-Edge"). A test that addresses a demo specimen by its region name needs the new spelling (`KF-4TXTVV`).
335
+ - A labelled `CatalogExample` now names its `section` with its label, so each specimen is a named region that assistive technology and `getByRole('region', { name })` can address. An unlabeled example stays an ordinary grouping (`KF-ZQMXK1`).
336
+ - `CatalogExampleStack` takes a `width` option: `reading` (default) keeps the 736px reading measure, and `full` lets the stack span the stage so a catalog can show application-width compositions such as boards, app shells, drawers, and split views without clipping them (`KF-HKVT5S`).
337
+ - `CatalogExample` `viewport.width` takes `sidebar`: a 272px production-rail width, capped at the stage, so sidebar-pane specimens render at their real width without a wrapper (`KF-DH5MH8`).
338
+ - In a `PopupMenu` level (the top menu or one submenu) that holds a checkbox choice, plain commands now reserve the check column too, so check, icon, and label columns line up across checked, unchecked, and plain rows; a level without a choice keeps the compact start. Submenu checkbox rows drop an extra 1em label inset, so their icon-to-label gap matches the top level (`KF-31QHPE`).
339
+ - Hovering a selected (`aria-current`) or pressed `ListItem` likewise keeps its selected tint instead of the neutral hover colors (`KF-84AGE5`).
340
+ - Hovering a selected or pressed `ListActionRow` keeps its selected tint instead of switching to the neutral hover colors, so a freshly selected row no longer looks unselected while the pointer stays on it (`KF-Z737D0`).
341
+ - A `width="full"` `CatalogExampleStack` now spans the whole catalog stage on wide screens; the stage's 1120px canvas cap no longer stops it short of the right edge (`KF-WDSFWH`).
342
+ - **Chat-bubble `ContentItem`s.** `bubble="start" | "end"` lays a `ContentItem` out as a transcript bubble: it fits its message up to 80% of the row, sits at the start (other participants) or end (the person's own messages), and wraps long unbroken text. The new `appearance="brand-loud"` paints the solid brand fill with its on-loud foreground for the person's own messages (`KF-M3HJK8`).
343
+
344
+ - **`DialogSurface rootAttributes`.** `DialogSurface` takes safe `data-*` `rootAttributes`, such as a `data-key`, on its root; its own configuration attributes stay protected. Sibling dialogs that render conditionally then morph by identity rather than by position. Before, a re-render could reuse one open dialog's element for another, swapping its accessible name and suppressing `wa-after-hide`. Apps no longer wrap each dialog in a keyed `div` (`KF-D7H0WN`).
345
+
346
+ - **Heading supporting text.** A read-only `ToolbarText` takes `description`: quiet, single-line, truncating copy under the title ("Changes save automatically."). It starts at the title's text whether or not a leading icon group is present, and shares the control band so trailing actions stay aligned. `descriptionId` gives it an id for `aria-describedby`. With a description, `id` and `headingLevel` apply to the title span alone, so `aria-labelledby` names only the title. Apps no longer recompute the title inset from toolbar tokens (`KF-DXVMBN`).
347
+
348
+ - **Drag-to-reorder list rows in `@kerfjs/ui`.** `ListItem`, `ListItemLink`, and `ListActionRow` take `draggable`, `dragging`, and `dropPosition: 'before' | 'after'`: a draggable row is a native HTML drag source (never while it is a loading placeholder), a dragging row dims, and a drop position draws a 2px brand insertion line on that edge of the row (`--kui-list-item-drop-indicator` / `--kui-list-action-row-drop-indicator` and matching width and dragging-opacity tokens; system `Highlight` in forced colors). The new `@kerfjs/ui/wire-list-reorder` subpath adds `wireListReorder(root, { onReorder })`, which paints those states during a pointer drag, moves rows with Alt+Shift+ArrowUp/ArrowDown and restores focus after the re-render, and reports `{ listId, sourceIds, target: { id, position }, source }`; dragging a selected or pressed row moves every selected row of its `List`. `reorderListItems` applies the change to an array. Apps no longer hand-style dragged rows and insertion lines (`KF-HWYE11`).
349
+
350
+ - **Compact `Toolbar` density.** `Toolbar density="compact"` makes a 40px header for a panel embedded in a card or inspector: a 34px control band (the compact `ToolbarControlGroup` size) with 3px block insets, keeping the 8px inline insets and zone gap. Fill it with `size="compact"` groups. `--kui-toolbar-inset` still overrides the block inset Composite toolbars forward `density` from their `ToolbarConfig` (Workbench panel, main, and bottom toolbars, CollapsiblePanel, NavStack, SplitView) and size the groups they compose (panel and relocated toggles, the back button) to match; `CollapsiblePanelRelocated` takes `density` for its destination toolbar (`KF-0QDF0V`, `KF-QPSTTA`).
351
+
352
+ - **`ChoiceChips` for a wrapping exclusive choice.** `@kerfjs/ui/choice-chips` renders one choice from a visible set too large for a `SegmentedControl` track, such as a nine-color palette in a 560px dialog, as separate pills that wrap with the standard 8px gap at any width. Each pill is backed by a native radio in a named `role="radiogroup"`, so the group is one Tab stop, arrow keys move the selection, and the checked radio submits under `name`. A choice may lead with a `swatch` (a `CssColor`, or `'transparent'` for an outlined dot struck through diagonally) or a decorative `icon`; the group takes `label` or `labelledBy`, a controlled `value`, a delegated `action` for `change`, `size="compact"`, `required`, and group or per-choice `disabled`. Use it instead of wrapping a segmented control or button-appearance `wa-radio` set, whose joined borders turn ragged across rows (`KF-EJPYWD`).
353
+
354
+ - **Viewport-locked app root.** In the opt-in `@kerfjs/ui/document.css` baseline, `data-viewport="locked"` on a body-child `.kui-app-root` gives `html`, `body`, and the root `height: 100dvh` and `overflow: clip`. Mobile browser toolbars can then never leave the root taller than the visible area, and the document itself never scrolls; only the shell's panes do. `docs/document-baseline.md` covers the on-screen keyboard (`KF-1XNQYP`).
355
+
356
+ - **Semantic cursors in `document.css`.** The opt-in `@kerfjs/ui/document.css` baseline now gives native controls semantic cursors with zero specificity: `pointer` on enabled buttons, links, `role="button"`, `summary`, selects, checkbox/radio/button-type inputs, and labels around checkboxes or radios; `not-allowed` on disabled controls, `aria-disabled` role buttons, and a disabled `wa-button`'s `base` part (Web Awesome 3.12 leaves a pointer there); and `text` on text-like inputs and textareas. Components and applications keep their own cursors (`KF-C336VV`).
357
+
358
+ - **`Badge maxWidth`.** A text `Badge` takes `maxWidth` (a `CssLength`). Longer text truncates with an ellipsis inside a new `kui-badge__label`, the badge may shrink below the cap in a tight row, and string or number content becomes the native `title` tooltip unless `title` is supplied (`KF-0WKZY2`).
359
+
360
+ - **`Text align`.** `Text` takes `align="start" | "center" | "end"` (default `start`), so centered status copy that wraps in a narrow surface, or an end-aligned value, uses `Text` directly instead of an app rule on `.kui-text`. Start and middle truncation align their single line to match (`KF-MMAWEG`).
361
+
362
+ - **`SummaryRow`.** `@kerfjs/ui/summary-row` is a selectable, focusable summary of one item (`role="option"`) as a list `row` (bottom divider, `listEdge` rounding for rounded sections) or a board `card`. It has a leading glyph, a semantic `rail`, an identity `title` clamped to `titleLines` (two for rows, four for cards) with `trailingMeta` floated at its end, and a wrapping `metadata` line. Kerf owns hover, focus, `selected`, `dimmed`, narrow compaction, and optional `deferRendering` for long lists (`KF-XCFMX8`).
363
+ - **`Combobox`.** `@kerfjs/ui/combobox` is a free-text field with filtered suggestions that can also create a new value (tags, labels): a native input with the themed field chrome and a 16px font floor on touch devices, on the ARIA combobox pattern (`role="combobox"`, `aria-activedescendant`, a listbox of options). `wireComboboxes(root, { onCommit })` from `@kerfjs/ui/wire-comboboxes` filters as people type, moves the active option with the arrow keys, and reports `{ id, value, created, input }` on Enter, a comma, or a click; `createLabel={false}` allows only suggestions (`KF-XDVAMR`).
364
+ - **File picking and dropping.** `@kerfjs/ui/file-picker` adds `FilePickerTrigger` (a compact, link-toned browse control) and `FileDropZone` (a dashed target that also opens the chooser), both around visually hidden native file inputs with visible focus rings. `wireFilePickers(root, { onFiles })` from `@kerfjs/ui/wire-file-pickers` reports browsed and dropped files, filters drops by `accept` (exported as `fileMatchesAccept`), marks a zone `data-dragging` while files are over it, and resets the input so the same file can be chosen again (`KF-RDV6V9`).
365
+ - **`ContentSwap`.** `@kerfjs/ui/content-swap` swaps two contents in one shared cell (a dialog's two steps, a footer's changing actions) with a `push` (forward or backward, mirrored in right-to-left documents), a `crossfade`, or no motion. Kerf owns the keyframes, the reduced-motion fade, and the inactive side's `inert` and `aria-hidden`; `label` makes it a named region and `slot`/`fill` place it in a dialog label or footer (`KF-V7MZY9`).
366
+ - **`ColumnTrack` for boards.** `@kerfjs/ui/column-track` is a horizontal scroll owner for columns that share the width equally but never narrow below `minColumnWidth` (250px), so a narrow board scrolls instead of crushing them. `layout="paged"` shows one near-full-width column per page with a `peek` of the next, mandatory start snapping, a hidden scrollbar, and smooth scrolling unless reduced motion is preferred (`KF-9WEWRF`).
367
+ - **`EdgeActivityIndicator`.** `@kerfjs/ui/edge-activity-indicator` is a layout-free, pointer-inert activity strip pinned below the top safe area (or flush). While `busy` its thin bars ripple in a traveling wave, drawn by one gradient and an animated mask with no per-bar elements or resize script, and an optional `message` hangs from the edge as a polite status pill. It takes a semantic `tone`, scales in from the edge, and only fades under reduced motion (`KF-CS729Y`).
368
+ - **`ValueTable` layout props.** `labelWidth` (a typed length) gives labels a minimum column and the value the rest of the row; `presentation="stacked"` puts each value under its label, starting at the label's text; and `stackBelow="compact" | "narrow"` stacks only while the table itself is narrower than 512px or 576px (a stacking table fills its container's width). Apps no longer override `--kui-value-table-row-columns` and the row gap/padding tokens for this (`KF-BTMDH5`).
369
+ - **`SplitButton`.** `@kerfjs/ui/split-button` renders a primary action and an attached options trigger on one loud semantic fill (`tone`: brand, neutral, success, warning, danger) with `fill` for full width, `busy` (a spinner and `aria-busy`), and separate `disabled`/`optionsDisabled`. Both halves are native buttons, so the options trigger's `aria-expanded`, `aria-haspopup`, and name reach assistive technology, which a `wa-button-group` could not (`KF-KFC7C2`).
370
+ - **`IconToggleButton` for standalone icon toggles.** `@kerfjs/ui/icon-toggle-button` renders a native `aria-pressed` button with a single contained `ToolbarControlGroup`'s 44px geometry and raised pressed face (pill or rounded), for content and pane footers where a `Toolbar` does not belong and `ToolbarControlGroup`'s toolbar-parent rule (`KUI-L201`) applies. Its required `label` names it and, with help tags registered, shows on hover and focus (`KF-HBWDHE`).
371
+ - **Selected-chrome opt-out for icon-state toggles.** `ToolbarControlGroup` `selectedChrome="none"` keeps pressed controls looking like their neighbors, and `data-selected-chrome="none"` on one button opts out just that control, for a toggle whose glyph already shows its state (an empty or filled star). Hover and focus treatment are unchanged (`KF-GGDABA`).
372
+ - **`FramedList` for inset-grouped rows.** `@kerfjs/ui/framed-list` draws `ValueTable`'s rounded, bordered frame (lowered or base surface) around `FramedListRow`s of arbitrary content, with each row owning its 8px inset, a 44px minimum height, the inset divider above it, and an optional `highlighted` tint. Settings, account, and shortcut lists no longer need a hand-rolled `ul` stylesheet (`KF-2HB7RT`).
373
+ - **ARIA root attributes and a document inset for `List`/`Row`.** `rootAttributes` on a `List` or `Row` now also accepts `aria-*` attributes and a structural `role` (`region`, `group`, `list`, `status`, landmarks, …), so a labeled drop-target region or an `aria-busy` stack needs no wrapper; widget roles are dropped, and a multi-select List keeps owning its grid role and name. `List` `inset="document"` adds a reading inset (24px block, 32px inline, 16px inline below 576px) for reader views (`KF-DNZJCG`).
374
+ - **`Badge` icon, title, and identity.** A text `Badge` takes a decorative leading `icon` (4px before its text, like `Chip`), and every Badge takes a `title` tooltip and safe `data-*` `rootAttributes`, so apps no longer wrap a Badge for status identity or nest a `Row` inside it for icon spacing. A text Badge with a `label` is now a labeled image (`role="img"`), so that name is actually exposed in place of its abbreviated visible text (`KF-2YKKK5`).
375
+ - **`IconButton` for icon-only Lucide buttons.** Web Awesome gives a `wa-button` its square icon-button geometry only when its label holds a lone `wa-icon`, so a button whose only child was a `LucideIcon` kept text-button padding and did not match an adjacent field. `IconButton` (`@kerfjs/ui/icon-button`) renders a `wa-button` with a `LucideIcon` as a square one form-control height on each side, takes a required `label` that names it, and keeps that square beside a field in a `ListInsetControl` (`KF-1315VN`).
376
+ - **`List` surface.** `surface="base"` or `"raised"` paints `--kui-color-surface` or `--kui-color-surface-raised` behind a List and its insets, so a banner strip above a sunken work area no longer needs an app wrapper whose only CSS is a background. A lowered region remains a `SunkenPanel` (`KF-ZKYYH1`).
377
+ - **`CornerStatus` for non-dismissible app-level progress.** The new `@kerfjs/ui/corner-status` component hosts one or more `StateBanner`s at a viewport corner (`placement`: `bottom-end` by default, `bottom-start`, `top-end`, or `top-start`, RTL-aware) with a 16px gutter plus device safe-area insets. It is a native `popover="manual"` in the top layer, so it sits above fixed and z-indexed page chrome, and it has no close button, light dismiss, Escape handling, or focus change. `wireCornerStatus` (`@kerfjs/ui/wire-corner-status`) opens each host as renders insert it; the app removes the host when the work ends. Inside it, a banner drops its inline margin, gains elevation, and paints its tone fill over the opaque surface. `presentation="embedded"` renders the same stack in flow. This replaces fixed-position app CSS around a `StateBanner` and hiding a toast's close button (`KF-PZCPHQ`).
378
+ - **`StateBanner` strip presentation.** `presentation="strip"` renders a full-width status band for a layout edge, such as above a workspace: flush (no inline margin), square, with its copy on the shared content-text column and only tone-colored `dividerSides` edges (bottom by default; `''` draws none). Apps no longer zero the card's margin, radius, padding, and border tokens and draw their own per-tone rule. The default `card` presentation is unchanged (`KF-JQ8FB0`).
379
+ - **Dialogs that fill, and a non-modal dialog surface.**
380
+ - `DialogSurface` gains `height`: a definite modal height bounded by the dynamic viewport minus both gutters, like `maxHeight`. It also gains `bodyLayout="fill"`, which gives the body's whole height to one child (a `SplitView` or `Pane`) that owns its scrolling.
381
+ - The new `PopoverDialogSurface` in `@kerfjs/ui/surface-scaffold` is the non-modal counterpart. It is a native `popover="auto"` `role="dialog"` section that light-dismisses on Escape or an outside press and leaves the page interactive.
382
+ - It owns Kerf's dialog chrome and takes the same `size` / `preferredWidth` / `viewportGutter` / `height` / `maxHeight` / `bodyLayout` props, and it centers in the top layer whatever alignment its host sets. `presentation="embedded"` renders it in flow for catalogs and inline previews.
383
+ - Apps no longer hand-build popovers with their own chrome, viewport math, `:popover-open` grid, and embedded resets (`KF-XHECB9`).
384
+
385
+ - **Sunken surfaces have a fine grain texture.** Every sunken surface paints the new `--kui-sunken-surface`: a seeded 100px monochrome Gaussian grain tile at 4% maximum opacity, over the lowered color. That covers `SunkenPanel`, sunken `Pane`, Workbench regions, TabNavigator scenes, Web Awesome `appearance="sunken"`, and the catalog's lowered specimen viewport. The tile is generated once per page at runtime by the first sunken surface that renders, so no asset ships. `ensureSunkenTexture()` (exported from `@kerfjs/ui` and `@kerfjs/ui/sunken-panel`) covers pages with only Web Awesome sunken surfaces. Set `--kui-sunken-texture: none` at `:root` for the previous flat surface. An app's `--kui-sunken-panel-background` / `--kui-wa-sunken-background` override still wins (`KF-GMAK3H`).
386
+
387
+ - **Required wiring can be root-delegated actions.** Composition catalogs and `kerf.components.json` accept `wiring.actions`, the `data-action` values the app must handle with its own root `delegate()` / `delegateActions()` listener. Required wiring now names at least one helper _or_ action, so an app no longer has to mark such wiring `required: false` and weaken the check. `eslint-plugin-kerfjs`'s `ui-wiring` reports each unhandled action as `KUI-L401`. An action counts as handled when a reachable module imports a Kerf delegation API and names it as a string, selector, or table key. Comments and the component's own source do not count (`KF-AF5KD5`).
388
+
389
+ - **`kerf.components.json` declares where app-owned wiring helpers live.** `composition.wiring.sources` lists each application helper's `{ export, source }`. The generator verifies that the helper is in `helpers`, that the file exists, and that the file exports it. `ui-wiring` then resolves the app's relative imports of that helper, so page-root wiring with helpers such as `wireTicketSearchFields` no longer raises `KUI-L401`. `composition.wiring.scope` (`application` or `module`) is now authorable too. Both fields were previously expressible only in a hand-written catalog (`KF-YZE3DP`).
390
+
391
+ - **`kerf.components.json` zones can name their JSX prop.** A zone may declare `jsx: { prop }` (`children` for the default slot). The prop must be unique per component, and the generated composition catalog keeps it, so `ui-composition` maps a prop's value to its zone exactly as it does for `@kerfjs/ui`'s own catalog (`KF-99Z95S`).
392
+
393
+ - **Context `PopupMenu` owns its anchor.** A context-mode menu takes an `anchor: { x, y }` prop in viewport pixels and renders the point into its own template, so the point survives re-renders and a menu rebuilt with changed items. Open it with the new `openPopupMenu(menu)`; `openPopupMenuAt` still works for menus without `anchor`. The menu's root is now out of flow (`position: fixed`, 0×0). Previously its 0×0 `inline-block` added a line box in block layout and an extra gap slot in a flex row. Apps no longer need a fixed, 1px, z-indexed wrapper, and no z-index is needed because the open menu is in the top layer (`KF-FXGW0C`).
394
+
395
+ - **`SplitView` `listWidth`.** Size the fixed list column with a prop instead of a raw token: a number of CSS pixels, or `{ size, maxFraction }` to cap it at that share of the split's own width (`{ size: 432, maxFraction: 0.5 }` is 432px until the split is narrower than 864px). A narrow dialog then always leaves the detail in view. It is validated, and it throws when combined with `resizable`, which already sizes the list. The guide now states, and browser tests pin, that a SplitView fills any container with a definite height: a block box, a fixed-size popover, a flex column below a header, or a grid. Apps do not need a `display: grid` / `minmax(0, 1fr)` wrapper (`KF-7R5NWM`).
396
+
397
+ - **`Text` truncates at the start or in the middle.** With `wrap="truncate"`, the new `truncate` prop places the ellipsis at the `end` (default), the `start` (keeping the tail, for branch names), or the `middle` (keeping a suffix, for file paths). `truncateKeep` chooses that suffix: the last path segment (default) or a number of trailing characters. Start truncation uses an isolated left-to-right run instead of a bare `direction: rtl`, so punctuation stays in place. Both positions keep the whole value in the DOM and show it as the `title` unless the app sets one. Apps no longer need split spans or rtl CSS for this (`KF-XYA6VR`).
398
+
399
+ - **A trailing overflow menu for `ListActionRow`.** Pass `trailingMenu: { label, icon, items, placement?, disabled? }` instead of the `trailingAction*` props and the row renders a real `PopupMenu` (icon-only, no caret, opening `bottom-end` by default) as its sibling trailing control, so a command row with a "…" menu of Edit and Delete no longer needs a control inside dormant content or an override. The types accept exactly one trailing control. `trailingActionVisibility="interaction"` reveals the menu trigger on hover or focus and keeps it visible while the menu is open; a placeholder row disables it. `openPopupMenuAt` now also opens a button-triggered `PopupMenu` at a pointer position: for that opening the menu anchors at the point and opens `bottom-start`, then returns to its trigger and placement once it closes. A row can therefore open its trailing menu from its own `contextmenu` handler (`KF-VWTCYB`).
400
+
401
+ - **UX Review capture for catalogs served without Vite.** `@kerfjs/ui/vite-ux-review` now also exports the endpoint behind the catalog's **Capture region** link in server-neutral forms: `resolveUxReviewProject({ root?, projectDirectory? })`, `uxReviewProjectResponse(request, projectDirectory)` for Fetch API servers (Hono, Bun, Deno), and `uxReviewMiddleware(projectDirectory)` for Node/connect servers (Express, `node:http`). An app that serves its UX catalog from its own backend mounts one on its development server instead of hand-rolling the route. `uxReviewPlugin()` is now built on the same middleware, with unchanged behavior (`KF-PFF721`).
402
+
403
+ - **A per-entry settings pane in `@kerfjs/ui/catalog`.** Pass an entry's variant and state controls as `Catalog`'s new `settings` prop and the Catalog renders a **Settings** pane beside the stage, with the standard collapse toggle: in the pane's header while open, at the end of the entry toolbar while collapsed. Entries without settings render neither the pane nor the toggle. The app owns `settingsCollapsed`; hand the same signal to `wireCatalog`'s new `settingsCollapsed` option and it flips the signal from the toggle (`onToggleSettings` reports it) and wires the pane as a Workbench rail, so below the `narrow` breakpoint it starts collapsed and opens as an overlay that Escape or an outside press closes, exclusive with the sidebar overlay. `settingsPanel` sets the title, width, resizing, and overlay options (`settingsSize` / `settingsStorageKey` remember a resized width). The UX catalog's Badge entry demonstrates it with a playground. Consumers no longer build their own settings aside and toggle (`KF-0AY6AE`).
404
+
405
+ - **`kerf-component-catalog` generates the selection catalog too.** Packages and apps that keep `kerf.components.json` no longer hand-maintain a second selection JSON (`useWhen`, `avoidWhen`, `publicClasses`, `publicTokens`, …) for `@kerfjs/ui`'s component-catalog extension. Set `package.json#kerfComponentCatalog.selectionOutput`, add a top-level `description` and a per-component `selection` block (`useWhen`, `avoidWhen`, optional `uses`, `styleSources`, `demoSource`, `documentation`, and a `geometry` override), and `--write` / `--check` emit and verify the selection catalog beside the composition catalog. `name`, `kind`, `purpose`, `source`, `publicClasses`, `publicTokens`, and `geometry` come from the existing metadata; the composition catalog's `compatibility.componentCatalog` points at the selection file. The output is validated against the canonical selection schema, which `create-kerf-component` now ships. Recipes are not selection entries, `composed` geometry needs an explicit override, and `uses` must name this package's components or installed `@kerfjs/ui` catalog ids (`KF-K1SY5X`).
406
+
407
+ - **UX Review capture in any `@kerfjs/ui/catalog` app.** The catalog's **Capture region** header link, which starts a UX Review region screenshot preset with the project and the active entry, now ships in the package instead of living in Kerf's own demo. Add `uxReviewPlugin()` from the new Node-only `@kerfjs/ui/vite-ux-review` subpath to the Vite config. Report the project with `wireCatalog`'s new `onUxReviewProject` callback, and pass it to `Catalog`'s new `uxReview` prop. The link appears on local dev and preview servers and stays hidden on static hosting. `uxReviewCaptureUrl` and `loadUxReviewProject` are exported from `@kerfjs/ui/catalog` for custom placements (`KF-XB1G3S`).
408
+
409
+ - Deep-inset Pane content supports `--kui-pane-scrollbar-gutter: stable` for opaque edge-to-edge content, and Pane/Workbench focus rings paint above such scrollers without blocking their controls (`KF-9NVNGT`).
410
+
411
+ - NavStack now has `separator="auto" | "hidden"`. Automatic separators frame a sunken active Pane at the top chrome and optional bottom toolbar; hidden suppresses stack-owned lines (`KF-1XRSRW`).
412
+
413
+ - The UX catalog remembers its background, light or dark theme, contrast, and reduced-motion choices across reloads.
414
+
415
+ - The UX catalog can show a layout guide background with three one-pixel vertical rules at 15px, 23px, and 32px.
416
+
417
+ - `Row`, `Grid`, and `List` accept `gap={{ column, row }}` with independent typed spacing values, while their existing single-value gaps continue to apply to both axes (`KF-8HJFWC`).
418
+
419
+ - `ListHeader` accepts `badge` and `status` together, including explicit `undefined` for either when app state changes; a semantic `count` remains separate.
420
+
421
+ - `Pane`, `SunkenPanel`, plain `TabNavigator` scenes, `Workbench` regions, and static `ContentItem` surfaces can opt into keyboard or programmatic focus; `outlined` holds the standard focus ring for application states such as drop targets. Inactive scenes and collapsed panels suppress their focus stop and outline.
422
+
423
+ - `TabNavigator`, `TabNavigatorTab`, `TabNavigatorProps`, and `wireTabNavigator` name the complete persistent bottom-tab layout. The matching module, wiring, and CSS subpaths are available; former `TabScaffold` names and paths were deprecated aliases in earlier 5.0 betas.
424
+
425
+ - `Pane` exposes its resolved logical inline content insets to child CSS, so a table can paint edge to edge while its cell text stays aligned, with or without `deepInset`.
426
+
427
+ - `Pane` and plain `TabNavigator` scenes accept `deepInset` for a 16px outer content gutter while nested Row, List, and Grid spacing remains at its normal 8px.
428
+
429
+ - The TabNavigator catalog now demonstrates a NavStack with a view-owned top toolbar and Pane above the persistent tab bar, including push, tab switch, and return.
430
+
431
+ - UI Doctor now checks component root class names, stylesheet names, and CSS selectors that reach into another local component.
432
+
433
+ - Configure modal `DialogSurface` viewport gutters and typed maximum heights, including a dynamic viewport cap, without application shadow-part overrides.
434
+
435
+ ### Changed
436
+
437
+ - **SVG data URLs are allowed where they load as images.** The URL screen now keeps `data:image/svg+xml` in `<img src>` and in SVG `<image href>` / `<image xlink:href>`, where the browser renders the SVG as an image in secure static mode and runs no script, on the JSX, `html` tagged template, and live-binding paths. Every other sink (`<iframe src>`, `<embed src>`, `<object data>`, `<a href>`, …) still drops it, and no other scheme or `data:` rule changes. Generated SVG artwork no longer needs a `blob:` URL or `raw()`.
438
+ - `@kerfjs/ui` dialog corners are now concentric with a pill `ToolbarControlGroup` (22px) resting at the body inset, in place of Web Awesome's 12px panel radius: 30px by default (a bare `wa-dialog`, `PopoverDialogSurface`, and `DialogSurface` with a `compact` or `none` body inset) and 38px for `bodyInset="comfortable"`. A side sheet's leading corners follow the same radius (`KF-1FNWQG`).
439
+
440
+ - A resizable `@kerfjs/ui` `Workbench` panel without a `label` now names its resize handle in title style, as `ui/docs/writing.md` asks for region names: "Resize Left Rail", "Resize Right Rail", and "Resize Bottom Drawer" (previously "Resize left rail" and so on). A test or locator that matched the old accessible name needs the new one (`KF-NWS9GB`).
441
+
442
+ - `kerf-ui-doctor`'s `KUI-D040` now also checks template literals passed to title-style props, judging only their static words: ``label={`Edit ${name} shortcut`}`` is reported with the suggestion `` `Edit ${name} Shortcut` ``. Interpolated values and words joined to an interpolation are never judged. The UX demos' dynamic control names follow it ("Edit … Shortcut", "Open Ticket …", "New Tab …"), and the NavStack demo's detail item is named by its visible title alone (`KF-8B6JES`).
443
+
444
+ - `kerf-ui-doctor`'s `KUI-D040` now also reads region and landmark names, which `ui/docs/writing.md` makes title style, and raw Web Awesome field labels. The new region names are:
445
+ - the `label` of `Pane`, `Workbench`, `Toolbar`, `ToolbarControlGroup`, `TabBar`, `NavStack`, `CollapsiblePanel`, `FloatingToolbar`, and `ResizableRegion`;
446
+ - the `ariaLabel` of `SunkenPanel` and `List`;
447
+ - a `Pane`'s `contentLabel`;
448
+ - the panel, toolbar, and pane labels in Workbench, CollapsiblePanel, and NavStack configuration;
449
+ - the `aria-label` of `section`, `nav`, `aside`, `main`, `header`, `footer`, `form`, `search`, or an element with a landmark role.
450
+
451
+ The field labels it reads are the `label` of a raw `wa-input`, `wa-select`, `wa-textarea`, or `wa-radio-group`. `wa-checkbox`, `wa-switch`, and `wa-radio` option text, and `LoadingSpinner` and `Skeleton` labels, stay unread. Expect new warnings on lowercase names such as `<Pane label="Workspace pages">` ("Workspace Pages"). The package's own fixtures and examples are fixed. The catalog shell's sidebar navigation is now named "Kerf Components" (it was "Kerf components") (`KF-8JR7EC`).
452
+
453
+ - A panel toolbar's `toggle: { action, name }` (Workbench panels, `CollapsiblePanel`) now documents `name` as the panel's title-style name. Pass `name: "Navigator"`, not `"navigator"`: `name` labels the toggle group and completes the default "Show …" / "Hide …" label, which kerf never recapitalizes. The docs, demos, and recipes passed lowercase names, which produced sentence-style accessible names such as "Show output". They now pass title-style names. The catalog shell names its sidebar "Kerf Catalog" and its settings rail toggle reads "Hide Settings" (they read "Kerf catalog" and "Hide settings"). `KUI-D040` now reports a lowercase `name` in a `toggle` object literal that also has an `action` (`KF-EJ32ZH`).
454
+ - A `NavStack` root view's title now defaults to the `xlarge` page-heading size, and steps down to `large` once a back control shares the bar. An explicit `titleSize` still wins. A Workbench panel's stack keeps `large` at every depth, so narrow rails stay quieter than the work-area title (`KF-2XWXFR`).
455
+ - The built-in close control of a `wa-dialog` or `wa-drawer` now matches a borderless single `ToolbarControlGroup` button, the close a toolbar-composed dialog uses: a 40px circle with no border and the neutral hover fill, instead of Web Awesome's 35px rounded square (`KF-5B5C4W`).
456
+ - A capped, scrolling `Select` listbox, `PopupMenu` menu, or phone-width `PopupMenu` submenu now shows that it scrolls: a soft shadow lines each edge with more choices beyond it. With overlay scrollbars (macOS, iOS, Android), a capped submenu whose bottom edge fell between rows looked like a complete short list. The cue is CSS only, the same on every popup in the shared popup contract, and absent when every choice fits (`KF-B6BTHW`).
457
+ - A centered `NavStack` title (and any lone `ToolbarText` in a `centerAlign="balanced"` center) now keeps the full-strength text color the root title has, instead of dimming to the quieter `large`-size color as it centers (`KF-DX3739`).
458
+ - Once a `NavStack` shows a back control, the view title centers on the toolbar like a platform navigation bar. It stays on the midpoint while the sides leave room, moves away from a wider side when they do not, and truncates with an ellipsis before it reaches the back control or a trailing group. At the root, and on a view that supplies `toolbar.center`, the title stays left-aligned. A lone `ToolbarText` in a `centerAlign="balanced"` toolbar gets this navigation-bar layout in any `Toolbar` (`KF-9YD9KV`).
459
+ - The `NavStack` back control is now a contained, bordered `ToolbarControlGroup` (the default pill), so it reads as a real control instead of a bare chevron beside the title (`KF-TBRP2P`).
460
+ - HTML and attribute escaping in the JSX runtime now runs one pass over a value instead of one `replace` pass per special character, about 2x faster on values that need escaping. Output is unchanged (`KF-3SHRTR`).
461
+
462
+ - Rename the internal TabNavigator implementation folder, files, and focused test files from `tab-scaffold` to `tab-navigator`; public imports and rendered DOM hooks stay stable.
463
+
464
+ - `deepInset` now adds the same 8px to the top and bottom of Pane and plain TabNavigator scroll content, including scroll padding; Pane header and footer still own their safe-area edges.
465
+
466
+ - Toolbar composition guidance and catalog metadata now allow direct `KerfUiContent` in every zone; `ToolbarControlGroup` remains the recommended shared chrome for related controls.
467
+
468
+ - The UI composition lint rule checks component parent requirements for direct content passed through a named zone prop.
469
+
470
+ - Toolbar zones center direct content by default while keeping ToolbarText, control groups, and standalone primary actions on their established control-band axis.
471
+
472
+ ### Fixed
473
+
474
+ - Catalog Pane's documented `--kui-pane-scrollbar-gutter` token so downstream doctor and ESLint checks accept the supported setting (`KF-W5VXQF`).
475
+
476
+ - The actionable ToolbarText catalog example uses the standard TokenSearchField toolbar presentation for its search control, and an empty TokenSearchField shows its placeholder.
477
+
478
+ - Preserve toolbar visibility and measurement state across app renders to prevent geometry-driven render loops and repeated observer/layout work (`KF-58HBRR`).
479
+
480
+ - Restore accessible native dialog names through `@kerfjs/ui/surface-scaffold/register`, preserving live title slots and headerless labels.
481
+
482
+ - Validate remote CI freshness through newer-run searches and exact-run details before warning about a failed main build (`KF-X4PTHF`).
483
+
484
+ - Select menus now shift their complete visible surface inside narrow viewport edges while preserving `fitMenu` trigger width (`KF-H4JBQP`).
485
+
486
+ - Toolbar visibility probes stop rewriting unchanged styles, allowing catalog geometry overlays and responsive controls to settle after updates (`KF-JVWC92`).
487
+
488
+ - Busy toolbar groups preserve their relocation annotation, so the inert action and live status remain available when a panel closes.
489
+
490
+ - Navigation stacks now visibly slide pushed views over the previous screen and cross-fade both header and footer across repeated or interrupted push/pop transitions.
491
+
492
+ ### Added
493
+
494
+ - Add typed toolbar item `hideBelow`/`showBelow` lengths and `wireToolbarVisibility`, including complementary container-width overflow and dynamic font/token updates (`KF-MXE9YV`).
495
+
496
+ - Expanded grouped search supports `expandedOverflow="visible"` for application-owned surfaces below its positioning anchor.
497
+
498
+ - `@kerfjs/ui` ToolbarControlGroup adds `tileTone` quiet semantic palettes for non-interactive heading icon tiles.
499
+
500
+ - ToolbarText supports `tone="dark"` for filenames, headings, and actionable titles on loud toolbar surfaces.
501
+ - `@kerfjs/ui` Text accepts `controlMargins` for selected exterior control gutters, avoiding a Row wrapper around isolated text.
502
+
503
+ - Make lowered surfaces and decorative neutral fills/borders translucent, and replace the SunkenPanel prototype with direct component compositions.
504
+
505
+ - **UI components share `SemanticTone`.** Badge, Chip, StateBanner, and ContentItem
506
+ use `neutral`, `info`, `pop`, `success`, `warning`, and `danger`. Replace
507
+ Badge/Chip `tone="brand"` with `tone="info"`; the existing brand color tokens
508
+ still supply its palette. `BadgeTone` and `StateBannerTone` are deprecated aliases.
509
+
510
+ - **Catalog sidebars filter by item or heading name.** The shared catalog
511
+ shell now searches primary and ecosystem sections as you type, including
512
+ collapsed groups, and keeps the query when the active preview changes.
513
+
514
+ - **ListHeader has five label sizes.** `size="xs|sm|m|l|xl"` controls visual
515
+ scale separately from the semantic heading level; `sm` preserves the existing
516
+ uppercase treatment and `FieldLabel` remains unchanged.
517
+
518
+ - **The pinned TabBar catalog example scrolls with native momentum.** It no
519
+ longer reserves a long blank strip after the final tab; applications can
520
+ still opt into whole-tab settling with `snapTabs`.
521
+
522
+ - **Doctor reports foreign CSS restyles of co-owned classes.** A stylesheet
523
+ outside every co-owner now receives one `KUI-L019` per subject rule, including
524
+ inferred BEM modifiers, with the co-owner set in the diagnostic evidence.
525
+
526
+ - **Doctor respects explicit ownership groups with implicit ownership enabled.**
527
+ A group's stylesheet remains owned by the group even when one of its source
528
+ modules, or an unrelated module, imports that CSS directly.
529
+
530
+ - **LucideIcon supports filled glyphs.** Pass `appearance="solid"` to use the
531
+ icon's current text color as its fill; outline remains the default.
532
+
533
+ - **Doctor detects borrowed component markup.** Source modules that place a
534
+ foreign public class in JSX, raw HTML, or DOM class writes now receive
535
+ `KUI-L023`; documented placeable classes remain allowed.
536
+
537
+ - **Doctor offers strict same-package selector context checks.**
538
+ `ownershipContext: "any"` reports a sibling component's class even when it is
539
+ only used as selector context; cross-package composition stays available.
540
+
541
+ - **Doctor catches classless descendants of composed components.** Component
542
+ mode uses JSX evidence to identify element selectors below component hooks,
543
+ sibling roots, and direct composed child roots.
544
+
545
+ - **Doctor component ownership recognizes source evidence.** Selection-only
546
+ components and literal BEM classes rendered by a component are protected
547
+ when its stylesheet styles their block. CSS imports can supply the owned
548
+ stylesheet, and uncataloged modules can opt into the same inference.
549
+
550
+ - **`createScope().dispose` is typed as a bound function property.** Consumers
551
+ can store or return it as a teardown without a wrapper or an unbound-method
552
+ lint suppression.
553
+
554
+ - **ToolbarControlGroup grow sizing keeps its basis in wide toolbars.** An
555
+ expanded grow search now contributes its minimum width to the trailing zone's
556
+ intrinsic size, keeping sibling groups beside it instead of wrapping early.
557
+
558
+ - **TabBar can settle overflowing peers at whole-tab starts.** Opt into
559
+ `snapTabs` beside a pinned leading AppTab; selection and scroll gestures
560
+ align peers after the pin in LTR and RTL, with enough end room for the final
561
+ tab instead of leaving a clipped sliver at rest.
562
+
563
+ - **The pre-push check no longer adds timing metadata to Hot Sheet tickets.**
564
+ It still runs the repository gate or skips an identical verified clean tree;
565
+ historical timing notes remain readable through `ticket:timing summary`.
566
+
567
+ - **Wrapping catalog resource groups align with the toolbar control band.** A
568
+ single row centers in the band, while multiple rows start at its top.
569
+
570
+ - **UI browser checks cover the current catalog specimens.** Select, toolbar,
571
+ tab, and control group browser assertions now address the expanded demos;
572
+ a focused toolbar search field restores its default surface color when no
573
+ background override is set.
574
+
575
+ - **Pinned tabs cover the full leading edge of their scroll strip.** The
576
+ backing now includes the strip border as well as its padding, preventing a
577
+ sliver of a scrolling tab label from showing beside the pinned tab.
578
+
579
+ - **Catalog resource links remain readable at phone widths.** The resource
580
+ group wraps whole actions onto another row instead of clipping the Guidance
581
+ label at the right edge; `ToolbarControlGroup overflow="wrap"` is available
582
+ for the same independent-link pattern.
583
+
584
+ - **The UI analyzer resolves application component imports through TypeScript
585
+ path aliases.** `KUI-L022` now catches a styled hook class when an imported
586
+ cataloged component uses an exact or wildcard `paths` mapping; Doctor uses
587
+ the same resolution.
588
+
589
+ - **TabBar accepts standalone Web Awesome actions in `trailing` and `end`.**
590
+ A single `wa-button` can sit beside the scrolling tabs or at the far edge
591
+ without ToolbarControlGroup chrome; the composition rule recognizes the
592
+ cataloged custom element in these zones.
593
+
594
+ - **FieldLabel matches form-control labels over field previews.** The
595
+ `@kerfjs/ui/text` export gives a read-only field the same label typography
596
+ and inset as a themed Web Awesome input, with an id for accessible grouping.
597
+
598
+ - **TokenSearchField form fields match adjacent Web Awesome inputs.** The
599
+ control uses the form-control radius, and its required marker uses the
600
+ same neutral color and offset tokens as `wa-input`.
601
+
602
+ - **Grid supports labeled multi-select ContentItem tiles.** Opt into
603
+ `selectionMode="multiple"` with `ariaLabel`; `wireContentItems` follows the
604
+ rendered columns with four arrow keys and keeps nested controls independent.
605
+
606
+ - **Collapsible TokenSearchField can fill a stretched Toolbar center.** The
607
+ `fill` prop expands the field and its search group to the available width
608
+ while preserving the compact collapsed action.
609
+
610
+ - **TokenSearchField has a typed trailing icon action.** `trailingAction`
611
+ renders an accessible button with Kerf owned chrome and a full 24px wide hit
612
+ target; the existing `trailing` content slot remains for passive content.
613
+
614
+ - **PopupMenu and registered PopupSurface dropdowns preserve fast keyboard
615
+ navigation during opening.** Item focus gained while Web Awesome animates
616
+ the menu is restored after its initial focus handoff, so Enter acts on the
617
+ item the user reached.
618
+
619
+ - **PopupMenu submenu checkmarks stay inside the menu surface.** Checked
620
+ submenu rows align their checkmark beside the label instead of letting the
621
+ Web Awesome negative check margin paint beyond the submenu border.
622
+
623
+ - **Filled SegmentedControl labels keep contrast while switching themes.**
624
+ Web Awesome's native button color transition no longer interpolates the
625
+ label against the already-switched track fill.
626
+
627
+ - **Workbench numeric overlays no longer restyle the full work area on unrelated changes.**
628
+ The overlay wiring mirrors active presentation and open state onto the Workbench
629
+ root for CSS, and avoids layout measurements when no wired panel uses a numeric
630
+ breakpoint.
631
+
632
+ ## [5.0.0] - 2026-09-29
633
+
634
+ - **`ui-public-boundaries` inspects `kerfjs/html` tagged templates.** The
635
+ no-build `html` template writes the same markup as JSX, so its static
636
+ `class` attributes now carry `KUI-L101` (private `kui-*` anatomy) and
637
+ `KUI-L103` (a component's anatomy on your own element):
638
+ ``html`<aside class="kui-pane">` `` is reported with `Pane` to render, and a
639
+ plain ``html`<div class="kui-content-item">` `` with `ContentItem`, while a
640
+ `<ul>` carrier keeps the placeable class. The template's static parts are
641
+ read by the runtime's own rules; a class a hole supplies (`class=${cls}`)
642
+ is unknown and skipped.
643
+
644
+ - **`KUI-L103`'s "render X instead" answer has one implementation.**
645
+ `@kerfjs/ui` ships `ai/component-class-owners.cjs`, the rule that decides
646
+ which cataloged classes are a component's anatomy and which export renders
647
+ each. `eslint-plugin-kerfjs`'s `ui-public-boundaries` loads it beside
648
+ `application-ui-profile-sync.cjs`, and the generated `ai/components/*.md`
649
+ pages use it too, so the lint message and the component reference can no
650
+ longer name different components (a test pins their agreement over the whole
651
+ shipped catalog). A vendored `profileContractPath` directory must now also
652
+ hold `component-class-owners.cjs`; an `@kerfjs/ui` without it reports
653
+ `KUI-L090`.
654
+
655
+ - **A delegated click no longer re-fires on a target the re-render recycled.**
656
+ A delegated handler that writes a signal makes `mount()` re-render
657
+ synchronously, inside the same event dispatch; when the morph recycled the
658
+ clicked element in place into a control with a different `data-action`,
659
+ delegates registered later for the same event matched the recycled element
660
+ and fired too (a `request` click immediately ran `cancel` and undid itself).
661
+ `delegate()`, `delegateCapture()`, and `kerfjs/actions`' `delegateActions()`
662
+ now resolve every delegate's match against the DOM as it stood when the
663
+ event reached the first kerf delegate listener, like per-element listeners:
664
+ a delegate that matched at dispatch start still fires (unless an earlier
665
+ handler removed its element), one that matches only after a re-render does
666
+ not, and `delegateActions()` dispatches by the action value the element
667
+ carried at dispatch start. `mount()` stays synchronous. The
668
+ wrap-it-in-a-distinct-element workaround is no longer needed. Cost: about
669
+ 0.11 KB min+gzip, which moves the advertised core size from ~12 KB to
670
+ ~13 KB.
671
+
672
+ - **Component packages declare `placeableClasses`, and `KUI-L103` covers
673
+ their anatomy classes.** `create-kerf-component`'s `kerf.components.json`
674
+ accepts optional `boundaries.placeableClasses` (a subset of
675
+ `publicClasses`) and `boundaries.rootElement`, validates them, and copies
676
+ them into the generated `component-composition.json`.
677
+ `eslint-plugin-kerfjs`'s `ui-public-boundaries` now checks every class the
678
+ application or third-party catalogs in `.kerf-ui-profile.json` declare, not
679
+ only `kui-*` names: `<div class="acme-meter">` is reported with the
680
+ package's component to render (`Meter`), while its placeable classes stay
681
+ allowed. The scaffold template's README explains the field, and
682
+ `@kerfjs/ui/ai/skill.md` (1.50.0) applies the rule to package entries.
683
+
684
+ - **`eslint-plugin-kerfjs` `ui-public-boundaries` reports a plain
685
+ `<div class="kui-content-item">` as `ContentItem` recreated (`KUI-L103`).**
686
+ The `kui-content-item` classes stay placeable on another carrier (a `<ul>`, a
687
+ `Text`, a control-cluster `<footer>`), but a plain `<div>` carrying them is
688
+ exactly what `ContentItem` renders; the diagnostic now says to render
689
+ `ContentItem`. The `@kerfjs/ui` catalogs gain an additive `rootElement`
690
+ field (selection entry and composition `boundaries.rootElement`) naming the
691
+ element a component renders around its own placeable classes, and
692
+ `check:guidance` derives its repository check from the same fields, so the
693
+ package check and the downstream diagnostic cannot drift. The rule also
694
+ inspects the static class names of a template-literal `class` /
695
+ `className` value.
696
+
697
+ - **`eslint-plugin-kerfjs` `ui-public-boundaries` reports a component's
698
+ anatomy class written onto an application-owned element (`KUI-L103`).**
699
+ `<div class="kui-toolbar">`, `<aside class="kui-pane">`, or
700
+ `<wa-dropdown class="kui-popup-menu">` recreates a component by class and
701
+ inherits (and invites restyling of) its CSS; the diagnostic names the
702
+ component to render instead (`Toolbar`, `Pane`, `PopupMenu`). The
703
+ `@kerfjs/ui` catalogs gain `placeableClasses` (selection entry field and
704
+ composition `boundaries.placeableClasses`) naming the public classes an
705
+ application may place itself — the layout utilities, `kui-app-root`, the
706
+ `kui-content-item` geometry on a non-div carrier, and Web Awesome
707
+ `hide-actions` — and `check:catalog` requires every class-only entry to list
708
+ its classes there. A component's own element (`<Toolbar className="kui-toolbar">`)
709
+ is not reported. The README pane example and `@kerfjs/ui/ai/skill.md`
710
+ (1.47.0) now render `Pane` instead of writing its classes, and each generated
711
+ `ai/components/*.md` page states which classes are placeable and which
712
+ component renders the rest.
713
+
714
+ - **`kerf-ui-analyze` retires `KUI-L005` ("forced component dimension").**
715
+ `KUI-L019` already reports any application rule whose subject is a cataloged
716
+ component, dimensions included, so `.kui-pane { width: 300px }` was reported
717
+ twice (an error and a review finding). L005's only other shape, a public
718
+ class as an ancestor (`.kui-pane .app-sidebar { width: 240px }`), sizes the
719
+ application's own element and is allowed. The analyzer no longer emits it;
720
+ the id stays in the diagnostic registry (now listing it under `retired`) so
721
+ existing profile exceptions that name it still load.
722
+
723
+ - **`KUI-L301` now reports every `Discouraged` Web Awesome element rendered
724
+ directly.** The `@kerfjs/ui` package-default application profile avoids all
725
+ fifteen Discouraged entries (Dropdown/Dropdown Item → `PopupMenu`,
726
+ Select/Option → `Select`, Tab Group/Tab/Tab Panel → `TabBar`, Icon →
727
+ `LucideIcon`, Split Panel → `ResizableRegion`, Button Group →
728
+ `SegmentedControl`, Tree/Tree Item → `List`, and Animated Image, Comparison,
729
+ and Zoomable Frame → `ContentItem`), each with a rationale, and
730
+ `eslint-plugin-kerfjs` `ui-preferences` (and `kerf-ui-doctor`, which runs it)
731
+ now resolves a custom-element JSX tag such as `<wa-dropdown>` to its catalog
732
+ entry, not only an imported component. A declared component's own source
733
+ stays exempt because it is the wrapper that owns the element. A test keeps
734
+ the profile's avoid set equal to the catalog's Discouraged set in both
735
+ directions and lints the UX demo, recipes, and catalog shell clean;
736
+ `@kerfjs/ui/ai/skill.md` (1.46.0) names the diagnostic.
737
+
738
+ - **New (`@kerfjs/ui`): `NavStack` and `TabScaffold` take `chromeDividers`
739
+ (`'scroll' | 'always' | 'none'`), like `Pane`.** `scroll` (the default) keeps
740
+ today's behavior: the stack's top-chrome and bottom-toolbar lines and the
741
+ scaffold's bar line follow the scroll once `wireScrollDividers` is installed.
742
+ `always` draws them permanently without the wiring; `none` never draws them,
743
+ even when wired. The top `Toolbar`'s own `toolbarConfig.dividerSides` is
744
+ unaffected. `SplitView` forwards it to its compact stack through
745
+ `compactStack.chromeDividers`.
746
+
747
+ - **Fix (`@kerfjs/ui`): a `Pane` that is the only content of a `NavStack` view
748
+ or a `TabScaffold` scene fills it.** It used to size to its content, so the
749
+ view scrolled the whole Pane and its header scrolled away. Now the Pane's own
750
+ content scrolls under its pinned header and footer, the Pane's slots take the
751
+ safe-area edges the view or scene still reaches, and scroll dividers key on
752
+ the Pane's content. The rule lives in `pane.css`, as the Workbench-region fill
753
+ does.
754
+
755
+ - **The `@kerfjs/ui` suite-v3 AI-regression protocol test runs in every gate
756
+ again.** `ui/tests/integration/ai-regressions-v3.test.ts` was selected by no
757
+ package script, so neither `npm --prefix ui run check` nor CI executed it. It
758
+ now runs as `test:ai-regressions` inside the package's `npm test`, and a new
759
+ unit guard fails when any file under `ui/tests` is selected by no script
760
+ reachable from `check` or `test:e2e`.
761
+
762
+ - **Importing `@kerfjs/ui/catalog` or `@kerfjs/ui/workbench` now ships every
763
+ stylesheet those composites render.** `catalog`, `workbench`, `nav-stack`,
764
+ `split-view`, `tab-scaffold`, and `collapsible-panel` gain a CSS-aware
765
+ `browser` export condition whose generated wrapper imports the foundation, the
766
+ CSS of each internally rendered component (Pane, Toolbar, ToolbarText, List,
767
+ ListItem, ListInsetText, Row, PopupMenu, …) in dependency order, and the
768
+ composite's own CSS. Apps no longer hand-import `pane.css`, and a Catalog
769
+ sidebar's styling no longer depends on whether the app happens to import
770
+ `ListInsetText` elsewhere. The list is derived from the source import graph
771
+ (now following parent-relative imports), the `import` condition stays
772
+ CSS-free, and the companion `.css` subpaths remain for pipelines without the
773
+ `browser` condition. `@kerfjs/ui/ai/skill.md` is 1.46.0.
774
+
775
+ - **The `@kerfjs/ui` AI guidance now states every maintainer design rule
776
+ explicitly.** An audit of the package's tickets folded the missing rules into
777
+ `@kerfjs/ui/ai/skill.md` (1.45.0), `llms.txt`, and the design docs: prefer a
778
+ Kerf UI component over a Web Awesome component over a raw tag and never render
779
+ a `Discouraged` Web Awesome element directly (only through the Kerf component
780
+ that wraps it); nothing wraps inside a `ToolbarControlGroup` and a
781
+ `ToolbarText` is one ellipsized line unless `wrap`/`maxLines` is set; a
782
+ `Select` or `PopupMenu` trigger drops its focus ring while its popup is open
783
+ and the ring follows the control's shape (never add ring CSS); dividers earn
784
+ their place (`dividerSides=""` over self-spacing content or between a pane's
785
+ header and its list, never padded around); a control sits near where its
786
+ effect appears; and text aligns to text and icons to icons — a border is
787
+ never the alignment anchor. The ToolbarControlGroup catalog entry no longer
788
+ points at a hand-written `wa-dropdown` trigger, and the bundled kerf app
789
+ configs (`ai/skill.md` 1.25.0, `ai/cursorrules` 1.23.0) name the List family
790
+ and carry the "components own their styles; configure, never override" rule.
791
+
792
+ - **Applications and component packages are held to the component-ownership
793
+ rules `@kerfjs/ui` enforces internally: components own their styles and are
794
+ configured, never overridden.** `kerf-ui-analyze` and `kerf-ui-doctor` add
795
+ four error diagnostics (review findings under `--adoption`):
796
+ - `KUI-L019` — a CSS rule whose subject is another package's cataloged
797
+ component: a public class (`.kui-toolbar`, `.acme-meter`), its
798
+ `[data-component]` root, or a Web Awesome tag the package themes
799
+ (`wa-button`). Your own element in a component's context
800
+ (`.kui-toolbar > .my-widget`), keying on its state inside `:has()`, and
801
+ setting its public tokens stay allowed.
802
+ - `KUI-L020` — reading or writing another component's private `--_*`
803
+ variable (`--_kui-list-gap`).
804
+ - `KUI-L021` — overriding a token a typed prop sets (`--kui-list-gap` is
805
+ `<List gap>`); the message quotes the prop's example.
806
+ - `KUI-L022` — a class placed on a component's root (`<Toolbar
807
+ className="header" />`) that the application then styles.
808
+
809
+ Each message names the component's configuration (typed props, public
810
+ tokens, variants) and ends by routing a need with no prop to a component-gap
811
+ report instead of an override. Ownership is per package, from the nearest
812
+ `package.json`, so a component package styling its own components — including
813
+ in a Kerf UI parent's context — passes, and third-party catalogs declared in
814
+ `.kerf-ui-profile.json` get the same protection. `eslint-plugin-kerfjs` adds
815
+ `ui-component-ownership` (in `recommended-ui` and `strict-ui`, `error`),
816
+ reporting `KUI-L020` / `KUI-L021` in style strings, style objects, and
817
+ `style.setProperty()`. The `create-kerf-component` scaffold now ships a
818
+ `counter.css` that styles only Counter (configured by a typed `size` prop and
819
+ a `--kerf-counter-gap` token, with context named after Counter and a
820
+ Toolbar-context rule in its own stylesheet), plus `npm run check:styles`
821
+ (`kerf-ui-analyze`, from a new `@kerfjs/ui` dev dependency) in
822
+ `prepublishOnly`.
823
+
824
+ - **Behavior change (`@kerfjs/ui`): `NavStack` and `TabScaffold` chrome
825
+ dividers follow the scroll.** The `NavStack` bottom toolbar's and the
826
+ `TabScaffold` bar's top borders are no longer permanent. With `wireScrollDividers`
827
+ installed, a `NavStack`'s top chrome draws a line along its bottom edge only
828
+ while the active view's content is scrolled beneath it, its bottom toolbar a
829
+ line along its top edge only while more content lies below, and a
830
+ `TabScaffold` bar a line along its top edge only while the active scene's
831
+ content continues below it — none when the content fits. The line follows
832
+ the active view across a push or pop and the active scene across a tab
833
+ switch, and keys on whichever element actually scrolls: the view or scene
834
+ itself, or, through a sole child with no chrome of its own on that edge, a
835
+ `Pane`'s content or a nested `NavStack`'s active view (a sole `Pane`'s own
836
+ header or footer draws that boundary instead). Each layout draws the line
837
+ from its own stylesheet (an overlaid pseudo-element on the stack's chrome; the
838
+ bottom toolbar and bar keep their 1px top border, transparent until shown),
839
+ so nothing moves; the wiring
840
+ writes only its `data-scroll-overflow` / `data-scroll-divider` state. Without
841
+ the wiring those edges draw no line.
842
+
843
+ - **Behavior change (`@kerfjs/ui`): toolbars no longer draw a divider by
844
+ default; dividers between pinned chrome and scrolling content follow the
845
+ scroll.** `Toolbar`'s `dividerSides` now defaults to `''` (was `'b'`), and
846
+ the `Workbench` (`mainToolbar`, `mainBottomToolbar`, panel toolbars, and the
847
+ `mainHeader` / `mainFooter` lists), `CollapsiblePanel`, and `Catalog`
848
+ toolbars no longer place dividers of their own. Instead a `Pane` draws one
849
+ line under its header and one over its footer, wherever that chrome ends:
850
+ the header's only while content is scrolled beneath it, the footer's only
851
+ while more content lies below, and neither when the content fits. The new
852
+ `@kerfjs/ui/wire-scroll-dividers` subpath's `wireScrollDividers(root, {
853
+ targets? })` reports that state — call it once at the app root and keep its
854
+ disposer (`wireCatalog` installs it for its own root). It also marks each
855
+ side of a `TabBar` strip with tabs scrolled out of view, and lets a
856
+ `Toolbar` or `List` named as chrome in `targets` draw the divider facing an
857
+ app-owned scroller. The wiring only writes the `data-scroll-overflow` /
858
+ `data-scroll-divider` state attributes; each component draws its own line,
859
+ and no state moves the chrome, the content, or a tab. `Pane` gains
860
+ `chromeDividers` (`scroll` default, `always`, `none`; also in `PaneConfig`,
861
+ so `mainPane` and a panel's `pane` forward it) and TabBar the
862
+ `--kui-tab-bar-divider-color` token. To keep a permanent line, set
863
+ `chromeDividers: "always"` on the pane or an explicit `dividerSides`.
864
+
865
+ - **`@kerfjs/ui`: `Pane`, `NavStack`, `SplitView`, and `TabScaffold` fill a
866
+ Workbench region from their own stylesheets.** As a Workbench main area's
867
+ or panel's only child, each sets its own `height: 100%` in that context,
868
+ which the Workbench marks on its regions (`data-workbench-main`, and the new
869
+ `data-workbench-panel-content` on each panel's content); `workbench.css` no
870
+ longer sizes another component's root (it still fills a nested Workbench).
871
+ Rendering is unchanged.
872
+
873
+ - **`@kerfjs/ui`: layouts name the covered-floating-controls context after
874
+ themselves, and no longer write `FloatingToolbar`'s inset token.** Workbench,
875
+ CollapsiblePanel, and ResizableRegion each provide their own private
876
+ `--_kui-<layout>-covered` context in place of the shared
877
+ `--_kui-floating-covered` flag; `FloatingToolbar` and every restore corner
878
+ read all three. A restore corner no longer sets
879
+ `--kui-floating-toolbar-inset: 0px`; `FloatingToolbar` zeroes its own inset
880
+ inside a restore corner (a toolbar's own `inset` still wins). Rendering is
881
+ unchanged. One edge case changes: a floating control inside an open overlay
882
+ of one layout type that is itself covered by another layout type's open
883
+ overlay (for example, a ResizableRegion overlay in a Workbench work area
884
+ under an open rail overlay) now stays hidden.
885
+
886
+ - **`@kerfjs/ui`: `ListHeader`, `NavStack`, `Select`, and `StateBanner` no
887
+ longer restyle a composed child through a class on its root.** Each child
888
+ now styles itself: `Text` sets a `ListHeader` label from `text.css`, `Badge`
889
+ spaces a `Select` count and a `StateBanner` badge from `badge.css`, and a
890
+ `NavStack` title uses `ToolbarText`'s new `fill` option. Rendering is
891
+ unchanged. `ToolbarText` gains `fill` (grow into the free space of its
892
+ toolbar zone and truncate there). The `kui-list-header__label`,
893
+ `kui-nav-stack__title`, `kui-select__count`, and `kui-state-banner__badge`
894
+ classes are removed; select a ListHeader label with
895
+ `.kui-list-header__title > .kui-text` and a NavStack title with
896
+ `.kui-toolbar-text[data-fill="true"]` if a test needs to find them.
897
+
898
+ - **`@kerfjs/ui` ships a markdown component reference for AI assistants.**
899
+ `@kerfjs/ui/ai/components/README.md` indexes every catalog entry in one line,
900
+ and `@kerfjs/ui/ai/components/<id>.md` gives each entry a short page: when to
901
+ use and avoid it, imports and CSS/registration side effects, a link to its
902
+ exact props, legal parents and zones (JSX prop and child count), app- and
903
+ wiring-owned state, geometry, accessibility obligations, its styling boundary
904
+ (configure through props; do not override internals), and its diagnostics.
905
+ `llms.txt` and the shipped skill now send assistants there instead of to the
906
+ 263 KB `component-catalog.json` and 221 KB `component-composition.json`,
907
+ which remain the canonical sources for tools. The pages are generated from
908
+ those two files and a package check fails when they drift.
909
+
910
+ - **Breaking (`@kerfjs/ui` and `create-kerf-component`): the composition
911
+ catalog files are renamed so they no longer read as a "v2" of the component
912
+ catalog.** The composition catalog is a generated composition layer beside
913
+ `component-catalog.json`, not a newer version of it. Update any import,
914
+ `$schema`, `$ref`, or `.kerf-ui-profile.json` catalog location that names an
915
+ old path:
916
+
917
+ | Old path | New path |
918
+ | -------------------------------------------------------------- | --------------------------------------------------------------- |
919
+ | `@kerfjs/ui/ai/component-catalog-v2.json` | `@kerfjs/ui/ai/component-composition.json` |
920
+ | `@kerfjs/ui/ai/component-catalog-v2.schema.json` | `@kerfjs/ui/ai/component-composition.schema.json` |
921
+ | `@kerfjs/ui/ai/component-catalog-v2.d.ts` | `@kerfjs/ui/ai/component-composition.d.ts` |
922
+ | `@kerfjs/ui/ai/component-catalog-v2-overrides.json` | `@kerfjs/ui/ai/component-composition-rules.json` |
923
+ | `@kerfjs/ui/ai/component-catalog-extension-v2.schema.json` | `@kerfjs/ui/ai/component-composition-extension.schema.json` |
924
+ | `@kerfjs/ui/ai/component-catalog-extension-v2.d.ts` | `@kerfjs/ui/ai/component-composition-extension.d.ts` |
925
+ | `@kerfjs/ui/docs/examples/component-catalog-extension-v2.json` | `@kerfjs/ui/docs/examples/component-composition-extension.json` |
926
+ | scaffolded package `component-catalog-v2.json` | scaffolded package `component-composition.json` |
927
+
928
+ The exported types follow: `ComponentCatalogV2` → `ComponentComposition`,
929
+ `CatalogCompositionEntryV2` → `CatalogCompositionEntry`,
930
+ `ConsumerComponentCatalogV2` → `ConsumerComponentComposition`, and
931
+ `ConsumerCatalogEntryV2` → `ConsumerCompositionEntry`. In the repository,
932
+ `npm run catalog:v2:sync` is now `npm run composition:sync`
933
+ (`catalog:sync` still runs both generators). The file contents and their
934
+ `schemaVersion` are unchanged.
935
+
936
+ - **Breaking (`@kerfjs/ui`, `create-kerf-component`, and `kerfjs setup`): the
937
+ composition catalog's own fields no longer read as a "v2" of the component
938
+ catalog.** In `component-composition.json` (and any consumer composition
939
+ catalog), `"schemaVersion": 2` is now `"schemaVersion": 1` — the composition
940
+ format's own first version, independent of `component-catalog.json`'s — and
941
+ `compatibility.v1Catalog` is now `compatibility.componentCatalog`. A
942
+ scaffolded package's `kerf.components.json` renames its `v1Catalog` field to
943
+ `componentCatalog` the same way. Regenerate scaffolded catalogs
944
+ (`npm run catalog:generate`), and change any `.kerf-ui-profile.json` `composition`
945
+ location from `"schemaVersion": 2` to `"schemaVersion": 1`; a catalog still
946
+ carrying the old fields fails validation with a message naming the rename.
947
+ The `ComponentComposition` type follows (`schemaVersion: 1`,
948
+ `compatibility.componentCatalog`).
949
+
950
+ - **`@kerfjs/ui` `NavStack` bars use the standard `Toolbar` padding.** The
951
+ navigation bar dropped its toolbar's block padding to stay 44px tall, so its
952
+ title and controls touched the bar's edges. It now keeps the 8px above and
953
+ below that every other toolbar has (60px plus any top safe-area inset).
954
+
955
+ - **`@kerfjs/ui` multiline list rows break long camelCase names at word
956
+ boundaries.** A string label in a `multiline` `ListItem` or `ListActionRow`
957
+ (such as a Catalog sidebar entry) gets `<wbr>` break opportunities at its
958
+ camelCase and acronym boundaries, so `QuickTicketComposer` wraps as
959
+ `QuickTicket` / `Composer` instead of `QuickTicketComp` / `oser`. Breaking
960
+ mid-word remains the fallback for a single word that is still too wide.
961
+ - **`wbr` is a typed JSX intrinsic element.** The runtime already rendered it
962
+ as a void element; `JSX.IntrinsicElements` now declares it.
963
+
964
+ - **`@kerfjs/ui` `Badge` has a text-free dot, and `TabScaffold` tabs can show
965
+ it.** `Badge` takes `size="dot"`: an 8px solid circle in the badge's tone,
966
+ with no children, appearance, or shape. Because a dot has no text, its props
967
+ require either a `label` (announced as an image, for example
968
+ `label="New activity"`) or `ariaHidden` when the owning component already
969
+ announces it. `TabScaffoldTab` accepts `badge: true` for the iOS tab-bar dot
970
+ (new content without a count), centered on the icon's top-trailing corner;
971
+ its `badgeLabel` is required and joins the tab's accessible name
972
+ ("Settings, Update available"). `BadgeTextProps` and `BadgeDotProps` are
973
+ exported from the root barrel.
974
+
975
+ - **`@kerfjs/ui` `Toolbar` truncates the leading title instead of letting the
976
+ center zone cover it.** When a leading identity, a `center` group, and
977
+ trailing actions no longer fit one row, the center zone keeps its whole
978
+ content width and the leading title ends in an ellipsis. Previously the
979
+ center track could shrink below its group, which then painted over the
980
+ title — a pushed `NavStack` view with a center group did this at 390px. The
981
+ fix holds under every `responsive` policy and both `centerAlign` values, and
982
+ a toolbar that fits lays out exactly as before.
983
+
984
+ - **`@kerfjs/ui` `ValueTableRow` keeps its value readable beside a long
985
+ label.** A long single-word label (such as `ConnectionStateBanner` in a
986
+ 390px-wide table) no longer squeezes the value to 0px wide, where it wrapped
987
+ one character per line while the label ran underneath it. The label and value
988
+ now share the row as two content-sized columns: a short value stays whole on
989
+ one line, the label wraps at its spaces and ends an over-long word in an
990
+ ellipsis before the value, and when both are long they split the row.
991
+
992
+ - **`@kerfjs/ui` pinned chrome can give way in a short pane.** `Pane` takes
993
+ `chromePlacement="auto"`: its header and footer stay pinned while the pane is
994
+ at least 480px (30rem) tall, and below that the whole pane scrolls as one
995
+ column so tall chrome never squeezes the content to nothing.
996
+ `WorkbenchChromePlacement` gains `"auto"` for `mainHeaderPlacement` /
997
+ `mainFooterPlacement`, and `Catalog` now defaults `headerPlacement` /
998
+ `footerPlacement` to `"auto"`. Its entry description is pinned under the
999
+ toolbar, which at 200% text size on a short window had left the preview 0px
1000
+ tall.
1001
+
1002
+ - **`@kerfjs/ui` `TabScaffold` tabs can show a badge.** Give a
1003
+ `TabScaffoldTab` a `badge` (a count or short string) to show the iOS tab-bar
1004
+ badge — a compact, solid danger `Badge` at the top-trailing corner of the
1005
+ tab's icon. The badge is hidden from assistive technology; the tab's
1006
+ accessible name becomes `"<label>, <badgeLabel>"` (for example
1007
+ "Inbox, 3 unread"), with `badgeLabel` defaulting to the badge text. Tabs
1008
+ without a badge are unchanged.
1009
+
1010
+ - **`@kerfjs/ui` `ListItem` and `ListActionRow` labels stay out of the
1011
+ trailing slot.** A long single-word primary label (such as a Catalog sidebar
1012
+ entry named `ConnectionStateBanner` in a narrow rail) no longer runs
1013
+ underneath trailing status text. Single-line rows now end the primary label
1014
+ and description with a real ellipsis (previously the text was cut mid-glyph
1015
+ with no "…"), and `multiline` rows break a word wider than the label column
1016
+ onto the next line.
1017
+
1018
+ - **Custom elements keep the `role` and `aria-*` they set on themselves across
1019
+ re-renders.** Web components conventionally own their host's ARIA (Web
1020
+ Awesome's `wa-option` sets `role="option"` / `aria-selected`, `wa-divider`
1021
+ sets `role="separator"`; Shoelace and FAST do the same), but a template never
1022
+ mentions them, so the morph and the keyed-list attribute fast path stripped
1023
+ them on the next re-render. On any custom element (hyphenated tag), `role`
1024
+ and `aria-*` are now element-owned like `open`: never removed just because
1025
+ the template omits them. The template can still set or change them, a signal
1026
+ binding set to `null` / `false` still removes them, and plain elements are
1027
+ unchanged. Trade-off: omitting one from a static template no longer removes
1028
+ it from a custom element — render an explicit value (`aria-pressed="false"`)
1029
+ instead.
1030
+
1031
+ - **`@kerfjs/ui` layout regions no longer slow edits to long lists inside
1032
+ them.** The rule that clears the safe-area context for the children of a
1033
+ Workbench main area or panel, SplitView list or detail, NavStack view,
1034
+ TabScaffold scene, or CollapsiblePanel content made each child re-check the
1035
+ region in Chromium on every DOM change. A 1000-row list placed directly in
1036
+ one of these regions took about 46ms per style recalculation (2ms with the
1037
+ list one level down), and now takes about 0.2ms. Layout and insets are
1038
+ unchanged.
1039
+
1040
+ - **`@kerfjs/ui` `CollapsiblePanel` no longer slows insertions into long
1041
+ lists.** An expanded inline panel clears its screen edge for its siblings;
1042
+ the rules that did so selected the siblings themselves
1043
+ (`:has(~ panel)` and `panel ~ *`), which in Chromium made each row inserted
1044
+ into or removed from a long list restyle the list's other rows — about
1045
+ 14.6ms instead of 0.2ms per insertion beside a 1000-row list. The panel's
1046
+ container now carries a flag that a CSS style query reads, so a list pays
1047
+ nothing. The edge still clears for the panel's siblings and returns when it
1048
+ collapses; the one difference is that a sibling placed before a left panel
1049
+ or after a right or bottom panel now loses the edge too.
1050
+
1051
+ - **`@kerfjs/ui` restore corners and covered floating controls no longer slow
1052
+ every style recalculation.** The `CollapsiblePanel` / `ResizableRegion`
1053
+ restore-corner anchor scope (`:has(> restore) > * > * > *`) and the static
1054
+ side-overlay covered flag (`:has(> open overlay) > :not(overlay)`) put a
1055
+ universal selector after a `:has()` container, which in Chromium restyled
1056
+ the children of every ancestor of each DOM change — about 85ms instead of
1057
+ 1ms per edit beside a 1000-row list. The drawer now publishes its anchor
1058
+ only beside a restore control's container (or its work-area column), and
1059
+ the covered flag is set on the overlay's container and cleared on its
1060
+ overlay children. Restore-corner placement and covered-control hiding are
1061
+ unchanged; a new CSS unit test rejects the costly `:has()` shapes.
1062
+
1063
+ - **`@kerfjs/ui` adds `ContentItem`.** Import it from
1064
+ `@kerfjs/ui/content-item` to render one self-contained pane child with the
1065
+ shared 8px margin, 1px border, and 8px padding. Framing and shape are typed
1066
+ props instead of hand-written modifier classes:
1067
+ - `frame="framed"` paints the neutral border in the 1px the item always
1068
+ reserves, so its geometry does not change (replacing
1069
+ `class="kui-content-item kui-content-item--framed"`);
1070
+ - `shape="pill"` selects the 22px radius.
1071
+ - `ariaLabel` names a distinct region, and `focusTarget` makes the item a
1072
+ programmatic focus target (`tabindex="-1"`), such as a NavStack view's
1073
+ `data-nav-focus` target.
1074
+
1075
+ The `.kui-content-item` classes stay public for elements that must carry the
1076
+ geometry themselves; their CSS now lives in `content-item.css`, which
1077
+ `layout.css` still imports. There is no filled variant — use `SunkenPanel`
1078
+ for a lowered surface. The catalog, demos, and recipes use the component.
1079
+
1080
+ - **`@kerfjs/ui` icon-only toolbar buttons show the same help tag.** An
1081
+ icon-only `<button>` or link inside a `ToolbarControlGroup`, named by
1082
+ `aria-label` with no visible text, now shows the help tag icon-only Selects
1083
+ and PopupMenus show, with the same 500ms hover delay, keyboard-focus-only
1084
+ display, press/Escape dismissal, and quick scanning along a toolbar. The tag
1085
+ is `aria-hidden` and never renames the button. A button with a native
1086
+ `title`, or with its own Web Awesome tooltip, keeps that and gets no second
1087
+ tag. The `select/register` and `popup-menu/register` imports install it; a
1088
+ toolbar with icon-only buttons but neither control imports the new
1089
+ `@kerfjs/ui/help-tags/register` subpath, which registers only the tooltip.
1090
+
1091
+ - **`@kerfjs/ui` icon-only Select and PopupMenu triggers show a help tag.**
1092
+ An icon-only `Select` (single or `multiple` with `triggerIcon`) and an
1093
+ icon-only `PopupMenu` now show a Web Awesome tooltip naming the control on
1094
+ hover (after 500ms) and on keyboard focus: a filter reads "Filter by label:
1095
+ Bug, Docs", a single Select its name and current choice, a menu its `label`.
1096
+ It hides while the popup is open, on a press, and on Escape. The tag repeats
1097
+ the accessible name, so it is `aria-hidden` and never joins
1098
+ `aria-labelledby`; screen readers still hear the name once. It is installed
1099
+ by the existing `select/register` and `popup-menu/register` imports, needs no
1100
+ props, and never appears for labeled Selects or text menu triggers.
1101
+
1102
+ - **`@kerfjs/ui` toolbar groups drop their focus ring while a popup is open.**
1103
+ A `ToolbarControlGroup` that owns the ring (`focusRing="outline"` or
1104
+ `"halo"`) no longer paints it while a Select listbox or `PopupMenu` inside it
1105
+ is open; the open popup shows focus, and the ring returns when the popup
1106
+ closes with focus still in the group. This matches the per-control Select
1107
+ and PopupMenu triggers.
1108
+
1109
+ - **`@kerfjs/ui` multiple `Select` can be an icon-only toolbar filter menu.**
1110
+ Set `selectedPresentation: 'icon-only'` on a `multiple` Select together with
1111
+ a fixed `triggerIcon` (for example a funnel `LucideIcon`); the types require
1112
+ `triggerIcon` there and reject it everywhere else. The trigger keeps the
1113
+ icon-only caret pill used in a `ToolbarControlGroup`, and:
1114
+ - shows the fixed icon whatever is chosen;
1115
+ - adds a compact count `Badge` while any choice is chosen;
1116
+ - ends the combobox's accessible name with the chosen labels in choice order
1117
+ ("Filter by label: Bug, Docs"), leaving the hidden value text empty so the
1118
+ list is not announced twice.
1119
+
1120
+ The popup still stays open while choices toggle.
1121
+
1122
+ - **`@kerfjs/ui` `Select` options keep their accessibility semantics across
1123
+ re-renders.** Re-rendering a Select (for example after its `change` handler
1124
+ updates the controlling signal) removed the `role="option"` and
1125
+ `aria-selected` Web Awesome sets on each option, so screen readers lost every
1126
+ option's role and selected state. They now survive in single and `multiple`
1127
+ Selects through the core rule below (custom elements own their `role` /
1128
+ `aria-*`), with no Select-specific restore.
1129
+
1130
+ - **`@kerfjs/ui` `Select` dividers keep their separator role across
1131
+ re-renders.** The `wa-divider` a `separatorBefore` choice adds lost the
1132
+ `role="separator"` and `aria-orientation` Web Awesome sets on it the first
1133
+ time the enclosing mount re-rendered, and never got them back, so assistive
1134
+ technology stopped announcing the break between option runs. The Select now
1135
+ renders both attributes itself.
1136
+
1137
+ - **`@kerfjs/ui` `Select` and `PopupMenu` re-renders no longer force Web
1138
+ Awesome updates.** Web Awesome reflects its default `size`, `appearance`,
1139
+ `placement`, and `orientation` onto `wa-select`, `wa-dropdown`, and
1140
+ `wa-divider`; the templates omitted them, so every re-render of the enclosing
1141
+ mount stripped them and each host ran a full Lit update to put them back. The
1142
+ templates now render those defaults (`wa-select size="m"
1143
+ appearance="outlined" placement="bottom"`, `wa-dropdown size="m"`, divider
1144
+ `orientation="horizontal"`), so an unchanged re-render leaves the hosts
1145
+ alone. No visual change. The `@kerfjs/ui/webawesome` JSX declarations type
1146
+ these attributes.
1147
+
1148
+ - **`@kerfjs/ui` Workbench and CollapsiblePanel panes and chrome lists are
1149
+ configurable.** The `Pane`s these layouts compose around app content now
1150
+ take the new `PaneConfig` type (`contentElement`, `contentLabel`,
1151
+ `separators`, `safeAreaEdges`): a Workbench panel's or `CollapsiblePanel`'s
1152
+ `pane`, and the Workbench's `mainPane`. The `List`s holding `mainHeader` /
1153
+ `mainFooter` take the new `ListConfig` type (`gap`, `hAlign`, `vAlign`,
1154
+ `dividerSides`, `textInsets`, `controlInsets`) through `mainHeaderList` /
1155
+ `mainFooterList`. Previously this configuration was hard-coded, so, for
1156
+ example, a navigator rail could not render its content as a `nav` landmark
1157
+ without restyling. Omitted or `undefined` fields keep today's defaults, and
1158
+ the default markup is unchanged.
1159
+
1160
+ - **`@kerfjs/ui` `SplitView` forwards its `ResizableRegion` and compact
1161
+ `NavStack` configuration.** `resizable` now also takes the list region's
1162
+ `separator`, `handleIcon`, `contentOverflow`, and collapse options
1163
+ (`collapsed`, `transitioning`, `collapseMotion`, `restoreControl`,
1164
+ `restorePosition`), so an app can hide the list and float a restore control
1165
+ without leaving `SplitView`. The new `compactStack` prop forwards the compact
1166
+ stack's `toolbarConfig`, `backIcon`, `backText`, `hideToolbar`, and
1167
+ persistent `bottomToolbar`, and gives the list and detail views their own
1168
+ toolbar groups (`list` / `detail`: `leading`, `center`, `toolbar`,
1169
+ `bottomToolbar`). Omitted options keep today's defaults.
1170
+
1171
+ - **`@kerfjs/ui` `NavStack` renders its top chrome as a real `Toolbar`.** The
1172
+ back control is a borderless `ToolbarControlGroup` and the title a
1173
+ `ToolbarText` in the leading zone, and the stack now forwards:
1174
+ - `toolbarConfig` — the `Toolbar` configuration (`dividerSides`,
1175
+ `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`) plus `label`,
1176
+ `titleSize` (default `large`), and `headingLevel`;
1177
+ - per-view `leading` and `center` groups beside the existing trailing
1178
+ `toolbar`;
1179
+ - `backIcon` and visible `backText` for the back control.
1180
+
1181
+ The defaults keep today's bar: no divider, one 44px band, and the top and
1182
+ side safe-area edges claimed. The hand-rolled `kui-nav-stack__lead` and
1183
+ `kui-nav-stack__actions` wrappers are gone (their content now sits in the
1184
+ toolbar's zones), and `kui-nav-stack__back` / `kui-nav-stack__back-icon`
1185
+ are no longer styled by the stack.
1186
+
1187
+ - **`@kerfjs/ui` configures with props instead of token overrides.** Five
1188
+ settings apps previously reached through raw `--kui-*` overrides now have a
1189
+ typed prop or modifier; each defaults to today's rendering, and the
1190
+ underlying tokens keep working:
1191
+ - `FloatingToolbar` `inset` (a `CssLength`, default `--kui-space-m`) moves
1192
+ it from the container edges. Omit it inside a restore corner, which owns
1193
+ the inset.
1194
+ - `DisclosureArrow` `size` (a `CssLength`, default 18px root-scaled).
1195
+ - `ListHeader` `headingLevel` (1–6, default 2) sets the label's native
1196
+ heading element for passive and trailing-action headers; a toggle header
1197
+ has no heading and rejects it at compile time.
1198
+ - `TokenSearchField` `clearIcon` replaces the clear action's glyph.
1199
+ - `.kui-content-item--framed` paints the standard neutral border on a
1200
+ content item that marks a real distinction, with no geometry change.
1201
+
1202
+ The docs and AI guidance also stop recommending `--kui-edge-inset-*`
1203
+ overrides: an app-owned arrangement passes `safeAreaEdges` to its panes and
1204
+ edge-claiming toolbars (including the layout toolbar configurations, which
1205
+ forward it).
1206
+
1207
+ - **`@kerfjs/ui` hides a work area's floating controls under an open side
1208
+ overlay.** While a side overlay is open — a Workbench rail (static
1209
+ `presentation: "overlay"`, or a responsive overlay whose breakpoint applies),
1210
+ a `wireSidebar` compact overlay or `presentation="overlay"`
1211
+ `CollapsiblePanel`, or a horizontal `presentation="overlay"`
1212
+ `ResizableRegion` — the covered work area's `FloatingToolbar`s and the
1213
+ layouts' restore corners are now hidden (`visibility: hidden`, so they also
1214
+ leave the tab order and the accessibility tree) instead of relying on
1215
+ stacking order alone. A phone-width app could otherwise paint the main
1216
+ column's floating drawer toggle over its open inspector. They come back as
1217
+ the overlay closes; the overlay's own floating controls and a bottom
1218
+ drawer's overlay are unaffected.
1219
+
1220
+ - **`@kerfjs/ui` `Select` supports multiple selection.** Set `multiple: true`
1221
+ and pass the chosen values as an array `value`; the props are typed so an
1222
+ array value requires `multiple`. Behavior:
1223
+ - The popup stays open while the person toggles choices with the pointer,
1224
+ Enter, or Space, and closes only on an outside press, Escape, or focus
1225
+ leaving.
1226
+ - Each chosen option shows a check.
1227
+ - The closed control summarizes the chosen labels in choice order as a short
1228
+ localized list, or shows `placeholderText` when none are chosen.
1229
+ - `change` / `input` report the value array, and a form submits every chosen
1230
+ value under `name`.
1231
+ - Re-rendering with a different `value` updates the selection even after the
1232
+ person has interacted.
1233
+
1234
+ `renderSelected` and `selectedPresentation="icon-only"` stay single-value
1235
+ only.
1236
+
1237
+ - **`@kerfjs/ui` `PopupMenu` now looks exactly like `Select`.** Both read one
1238
+ shared popup contract, so a command menu beside a value list in a toolbar
1239
+ draws the same popup. `PopupMenu` changes:
1240
+ - its caret turns to face the open menu;
1241
+ - its menu fades in without scaling;
1242
+ - it takes the Select listbox's 4px inset (also under the default
1243
+ `menuInset="standard"`);
1244
+ - its rows use the Select option's height, padding, and reserved check
1245
+ column, and its icons use the same 16px size and 8px gap;
1246
+ - a keyboard-focused item takes the Select's current-option fill instead of
1247
+ a focus ring;
1248
+ - headings render as the Select's uppercase group titles rather than slotted
1249
+ `h3` elements.
1250
+
1251
+ An open `Select` also no longer paints its trigger focus ring. The open
1252
+ listbox shows focus, and the ring returns when it closes.
1253
+
1254
+ - **`@kerfjs/ui` `Catalog` exposes its sidebar and toolbar configuration.** New
1255
+ `sidebar` prop (size, `resizable`, `separator`, `collapseMotion`,
1256
+ `presentation`, `responsiveOverlayAt`, `compactOverlay`, and the header
1257
+ `toolbar`'s `ToolbarConfig`) forwarded to its Workbench rail, plus
1258
+ `mainToolbar` / `footerToolbar` `ToolbarConfig` props. `wireCatalog` takes
1259
+ `sidebarSize` / `sidebarStorageKey` to wire a resizable sidebar. Today's
1260
+ 288px fixed sidebar and toolbar policies remain the defaults.
1261
+
1262
+ - **`@kerfjs/ui` composed toolbars are configurable.** `WorkbenchMainToolbar`,
1263
+ `WorkbenchMainBottomToolbar`, and the panel `toolbar` of a Workbench panel or
1264
+ `CollapsiblePanel` now take the `Toolbar`'s configuration: the new
1265
+ `ToolbarConfig` type, covering `dividerSides`, `centerAlign`, `responsive`,
1266
+ `responsiveAt`, and `safeAreaEdges`. Previously their dividers were
1267
+ hard-coded, so for example dropping the line between a toolbar and its
1268
+ content took CSS. Today's dividers remain the defaults. Also:
1269
+ - `mainBottomToolbar` and panel toolbars take a `center`;
1270
+ - panel toggles take localized `showLabel` / `hideLabel`;
1271
+ - a Workbench panel's floating restore controls follow its
1272
+ `restorePosition`.
1273
+
1274
+ - **Breaking (`@kerfjs/ui`): removed the pre-release compatibility surface.**
1275
+ - The `DividerSides` type is gone; use `Sides`, from the renamed `sides`
1276
+ module.
1277
+ - `ListInsetText.horizontalOnly` and its `kui-list-inset-text--horizontal`
1278
+ class are gone; pass `sides="rl"` instead.
1279
+ - The legacy color tokens are gone, both as `--kui-color-*` properties and
1280
+ as `uiColor()` names. Replace them with their canonical tokens:
1281
+
1282
+ | Removed | Use instead |
1283
+ | --------------------------------------------- | ----------------------- |
1284
+ | `border` | `neutral-border-normal` |
1285
+ | `border-quiet` | `neutral-border-quiet` |
1286
+ | `accent` | `brand-fill-normal` |
1287
+ | `accent-text` | `brand-on-quiet` |
1288
+ | `pop` | `pop-fill-quiet` |
1289
+ | `pop-text` | `pop-on-fill` |
1290
+ | `success`, `warning`, `danger` | `*-fill-quiet` |
1291
+ | `success-text`, `warning-text`, `danger-text` | `*-on-quiet` |
1292
+
1293
+ - **New `@kerfjs/ui` `PopupMenu` (`@kerfjs/ui/popup-menu`).** It renders a
1294
+ trigger and typed commands, headings, and dividers over the Web Awesome
1295
+ dropdown. Put it in a `single` `ToolbarControlGroup` with `nestedDropdown`, or
1296
+ wrap it in a `PopupSurface`. Register it once with
1297
+ `@kerfjs/ui/popup-menu/register`. It replaces hand-written `wa-dropdown`
1298
+ markup, which the catalog discourages: the guidance, the toolbar demos, and
1299
+ the Catalog's "Components" menu now use it. It also fixes two defects that
1300
+ hand-written menus had:
1301
+ - Icon-only triggers were unnamed, because a Web Awesome button ignores an
1302
+ `aria-label` on its host. PopupMenu renders `label` as visually hidden text
1303
+ inside the button.
1304
+ - A keyboard choice (Enter or Space) never reached click-delegated
1305
+ `data-action` handlers. PopupMenu's registration routes it through the
1306
+ item's click.
1307
+ - The UX catalog's application-layout demo no longer uses the discouraged
1308
+ `wa-button-group`.
1309
+
1310
+ - **`@kerfjs/ui`'s `TokenSearchField` takes a `revision` prop for programmatic
1311
+ text replacement.** The editor's text is DOM-owned, so a new `query` with the
1312
+ same tokens was silently ignored, for example when reseeding a persistent
1313
+ dialog's field on reopen. Changing `revision` rebuilds the editor from `query`
1314
+ and `tokens`, so consumers no longer need to re-key a wrapper element.
1315
+
1316
+ - **`@kerfjs/ui`'s `TabBar` strip no longer scrolls vertically.** The strip set
1317
+ only `overflow-x: auto`, so any vertical excess (consumer padding, focus-ring
1318
+ insets, taller tabs under larger text) let it scroll up and down on touch. It
1319
+ now scrolls only horizontally, and it takes a `min-height` so it grows to fit
1320
+ taller tabs instead of clipping them.
1321
+
1322
+ - **The `@kerfjs/ui` desktop app-shell recipe is a `Workbench`.** The old
1323
+ pane switcher that showed one pane at a time below desktop sizes is gone. The
1324
+ navigation and inspector are now resizable Workbench rails with their own
1325
+ toolbars, and their show toggles relocate into the work-area toolbar. On a
1326
+ narrow container the rails overlay the task list one at a time. The
1327
+ collapsible-sidebar recipe composes each panel's `toolbar` and uses
1328
+ `CollapsiblePanelRelocated` for its restore controls.
1329
+
1330
+ - **`@kerfjs/ui`'s `CollapsiblePanel` composes a panel toolbar and relocates its
1331
+ controls.** A panel takes the same `toolbar` roles as a `Workbench` panel
1332
+ (`title`, `panelOnly`, `constant`, and a standard `toggle`) plus a `footer`,
1333
+ and the new `CollapsiblePanelRelocated` renders a collapsed panel's constant
1334
+ groups and toggle wherever the app's work-area toolbar holds them.
1335
+ `wireSidebar` hands focus to that relocated toggle when the panel closes, even
1336
+ when the app renders it a frame late. `collapsiblePanelToggleIcon` is
1337
+ unchanged.
1338
+
1339
+ - **`@kerfjs/ui`'s `Catalog` is built on `Workbench` and dogfoods the package's
1340
+ components.** The sidebar is a Workbench left rail with the standard toggle
1341
+ (labels "Show/Hide {brand} catalog"), which moves into the entry toolbar while
1342
+ collapsed; on a small screen the sidebar overlays the stage instead of the
1343
+ former stacked two-column navigation, which is gone. The sidebar, sections,
1344
+ footer, and example notes are `List` / `ListHeader` / `ListInsetText` / `Text`
1345
+ compositions, and most catalog CSS (and every viewport media query in the
1346
+ shell) is removed. New: `Catalog`'s `id`, `headerPlacement`, and
1347
+ `footerPlacement`; `wireCatalog`'s `collapsed` and `id` options (the sidebar is
1348
+ wired like a Workbench rail and an open overlay closes on a selection);
1349
+ `Workbench`'s `mainHeader`, `mainFooter`, `mainHeaderPlacement`,
1350
+ `mainFooterPlacement`, and `mainToolbar.responsive` / `responsiveAt`;
1351
+ `ListInsetText`'s `rootAttributes`. `wireWorkbench` now also re-checks panel
1352
+ breakpoints when the root font size changes, and hands focus to a panel's
1353
+ relocated toggle when an unfocused click on its own toggle closes it (WebKit).
1354
+
1355
+ - **`@kerfjs/ui`'s `Workbench` rails overlay the work area on small screens by
1356
+ default.** A rail's `responsiveOverlayAt` now defaults to `"narrow"` (704px
1357
+ of Workbench width; the new `"never"` keeps it inline), so a sidebar covers
1358
+ the work area and any open drawer instead of squeezing it, one at a time
1359
+ with `wireWorkbench`. On a compact (448px) Workbench an open overlay rail
1360
+ fills the width less a 44px dismiss strip
1361
+ (`--kui-workbench-overlay-dismiss-margin`) on the side away from its edge;
1362
+ the new per-rail `compactOverlay: "full"` fills it. The bottom drawer's
1363
+ behavior is unchanged. `WorkbenchPanelToolbar` and the other panel-toolbar
1364
+ types are now exported from `@kerfjs/ui/workbench`.
1365
+
1366
+ - **`@kerfjs/ui`'s `Workbench` composes panel toolbars and moves a closed
1367
+ panel's controls into the work area.** A panel takes an optional `toolbar`
1368
+ (`title`, `panelOnly`, `constant`, and a standard `toggle: { action, name }`
1369
+ the Workbench renders) and `footer`; the Workbench takes `mainToolbar` and
1370
+ `mainBottomToolbar`. While a panel is closed its constant groups and toggle
1371
+ move to the work area — a left rail's lead the main toolbar, a right rail's
1372
+ end it, a drawer's trail the bottom toolbar or float in a corner
1373
+ `FloatingToolbar` — and its panel-only groups stay behind. `wireWorkbench`
1374
+ keeps focus with the toggle as it moves. Panels without a `toolbar` render
1375
+ exactly as before, and a region's only-child `Pane` or layout now fills it.
1376
+
1377
+ - **`@kerfjs/ui`'s list-detail dialog guidance is Workbench-shaped.** On roomy
1378
+ devices the list is a full-height sidebar and the detail a full-height main
1379
+ column, each a `Pane` with its own top `Toolbar`; the main column carries
1380
+ the primary title, the close control (`data-dialog="close"` in a
1381
+ `without-header` Web Awesome dialog), and the record actions, instead of a
1382
+ dialog header spanning both columns. The recipe, `docs/recipes.md`, and the
1383
+ shipped AI skill say so; compact devices keep the full-screen drill-down
1384
+ sheet.
1385
+
1386
+ - **`@kerfjs/ui`'s `ToolbarControlGroup` centers a direct icon tile.** A
1387
+ non-interactive icon placed directly in a group — a heading's identity
1388
+ glyph — now takes an icon button's 40px slot and 16px visual, so it centers
1389
+ in the group. It previously sat at the group's start edge, which pushed
1390
+ apps to wrap it in a focusable `<button>` that did nothing.
1391
+
1392
+ - **`@kerfjs/ui`'s `Toolbar` keeps its controls in a top control band.** A
1393
+ toolbar now reserves one 44px band at its top: each zone item no taller than
1394
+ the band is centered in it by its own size, and a taller item — a wrapped
1395
+ `ToolbarText` title, a multi-line search, a second trailing row — starts at
1396
+ the band's top and grows down without moving the others. A wrapped title
1397
+ centers its first line in the band, so trailing controls stay beside that
1398
+ line instead of dropping to the middle of the whole title.
1399
+
1400
+ - **`@kerfjs/ui`'s segmented `TabBar` ends its strip concentric with the pill
1401
+ track.** The first tab's leading corners, and with `allocation="fill"` the
1402
+ last tab's trailing corners, now follow the track's curve instead of keeping
1403
+ the small segment radius, and compact tabs are inset from the track's ends
1404
+ by the same distance as from its top and bottom. Corners between tabs are
1405
+ unchanged.
1406
+
1407
+ - **`@kerfjs/ui`'s `StateBanner` keeps its title, badge, and detail on one
1408
+ baseline in Safari.** The truncating detail was a clipped `inline-block`,
1409
+ which WebKit baselines at its bottom edge: the detail rose about 2px above
1410
+ the title and pushed the title and badge down, so the banner's contents
1411
+ looked vertically misaligned. The detail is now an inline flex wrapper
1412
+ around a clipped inner `<span>`, which takes its text baseline in every
1413
+ engine; truncation and the narrow-width detail line are unchanged.
1414
+
1415
+ - **`@kerfjs/ui`'s `wireTabBars` reveals a tab the application selects.** A
1416
+ tab added and selected by the app in an overflowing `TabBar` stayed
1417
+ off-screen, because the wiring revealed a selection only at wire-up, on
1418
+ focus, and after its own keyboard/drag changes. A change of a bar's selected
1419
+ tab now scrolls that bar's strip (never the page) to show it; re-renders that
1420
+ keep the selection leave a user-scrolled strip alone.
1421
+
1422
+ - **`eslint-plugin-kerfjs`'s `ui-composition` rule resolves application
1423
+ wrappers imported through a barrel.** A cataloged wrapper registered only by
1424
+ its defining source file, so `import { DemandSegmentsControl } from
1425
+ './components/index.js'` (where `index.ts` re-exports it) was an unknown
1426
+ element and reported `KUI-L202` in a toolbar zone despite its `rendersAs`.
1427
+ Relative re-exports — `export { X } from`, `export { X as Y } from`,
1428
+ `export * from`, and chains of them — are now followed to the cataloged
1429
+ source file. Type-only and namespace re-exports and non-cataloged components
1430
+ stay unresolved.
1431
+
1432
+ - **A collapsed `@kerfjs/ui` `Workbench` panel or `ResizableRegion` leaves
1433
+ the accessibility tree.** Only its content was `inert`, so the labeled
1434
+ `aside` / `section` stayed behind as an empty complementary or region
1435
+ landmark that a screen-reader user could still land on. The collapsed
1436
+ region itself now renders `inert` and `aria-hidden="true"`, like a
1437
+ collapsed `CollapsiblePanel`; its separator was already hidden, and each
1438
+ `restoreControl` renders outside it and stays reachable.
1439
+
1440
+ - **An expanded `@kerfjs/ui` `CollapsiblePanel` holds its size in a flex
1441
+ layout.** The panel shrank like any flex item beside a work area with wide
1442
+ content, while its content kept the panel's fixed size for the slide-out, so
1443
+ the panel's edge clipped the content — in the collapsible-sidebar recipe at
1444
+ 1280px, the rail showed 211 of its 232px and cut off the selected Inbox
1445
+ row's count. The panel is now `flex-shrink: 0`; the sibling work area gives
1446
+ way instead.
1447
+
1448
+ - **`@kerfjs/ui` overlay panels span their host on the fixed axis.** The
1449
+ 85vw / 85vh overlay maximums (`--kui-resizable-region-overlay-max-*`,
1450
+ `--kui-workbench-overlay-max-*`) applied to both axes, so an overlay bottom
1451
+ drawer stopped about 15% short of its host's width and an overlay side rail
1452
+ in a full-height layout stopped short of the bottom. Each maximum now caps
1453
+ only the panel's resizable axis: side overlays cap their width, drawers
1454
+ their height.
1455
+
1456
+ - **An overlay `@kerfjs/ui` `ResizableRegion` paints the surface.** With
1457
+ `presentation="overlay"` the region floated over the work area with a
1458
+ shadow but no background, so the content beneath — and a collapsed rail's
1459
+ restore control stacked under it — showed through. It now paints
1460
+ `--kui-color-surface`, like an overlay `CollapsiblePanel`; an inline region
1461
+ stays transparent over its host.
1462
+
1463
+ - **A pinned `@kerfjs/ui` resize separator no longer overwrites the
1464
+ remembered size.** When a container squeezes a `Workbench` rail, drawer, or
1465
+ `ResizableRegion` below its `min` (or its reachable range collapses to one
1466
+ size), the separator cannot move it, yet an arrow/Home/End key or a drag
1467
+ still committed the configured `min` to the app's size signal and storage:
1468
+ a rail remembered at 280px silently became 180px and came back at 180px
1469
+ when the window widened. A pinned separator now commits nothing, so the
1470
+ track returns at its remembered size once there is room.
1471
+
1472
+ - **A `pending` `@kerfjs/ui` `AppTab` is selectable and no longer dimmed.**
1473
+ A known tab that is still opening now keeps its select button enabled and
1474
+ in the roving tab order, so a user can switch to it and the application can
1475
+ show placeholder content in its panel until loading completes. With
1476
+ `webawesome.css` loaded, Web Awesome's native `button:disabled` no longer
1477
+ dims the pending pill to 50%; it shows only its quiet name color and
1478
+ trailing spinner, as documented. Close and dragging stay disabled while
1479
+ pending, and it stays `aria-busy`. An unknown `placeholder` tab is
1480
+ unchanged: disabled and out of the tab order.
1481
+
1482
+ - **Closing a `@kerfjs/ui` `Workbench` panel from its own control by mouse
1483
+ returns focus in Safari.** Safari never focuses a clicked button, so
1484
+ pressing an open panel's Hide control blurred the focused control to the
1485
+ page before the click collapsed the panel, and `wireWorkbench` — which
1486
+ returns focus only when it is inside the closing panel — left focus on the
1487
+ page body instead of the toggle that opened it. A press that starts inside
1488
+ the panel while focus is there now counts as focus inside, so the close
1489
+ returns it; focus the user has moved to another element since is left
1490
+ alone.
1491
+ - **A collapsed `@kerfjs/ui` `CollapsiblePanel` or `ResizableRegion` leaves
1492
+ the Tab order.** Both kept collapsed content in the DOM, only slid out and
1493
+ clipped, so Tab still reached its controls; focusing one scrolled the clipped
1494
+ panel, and a `CollapsiblePanel`'s `aria-hidden` put those focusable controls
1495
+ inside a hidden subtree. A collapsed `CollapsiblePanel` now renders `inert`
1496
+ beside its `aria-hidden`, and a collapsed `ResizableRegion` renders its
1497
+ content wrapper `inert`, with no wiring needed. The slide-out still animates,
1498
+ each `restoreControl` stays outside the inert subtree and reachable, and
1499
+ `wireSidebar` still hands focus to the panel's toggle when it collapses from
1500
+ inside.
1501
+
1502
+ - **A collapsed `@kerfjs/ui` `Workbench` rail's restore control no longer
1503
+ covers an expanded bottom drawer.** A `leftRail` / `rightRail`
1504
+ `restoreControl` floats in the Workbench's bottom corner, which the bottom
1505
+ drawer's column reaches once the rail collapses, so with the drawer expanded
1506
+ the control sat on the drawer's content. An expanded inline drawer now
1507
+ publishes its top edge as a CSS anchor scoped to its Workbench, and the
1508
+ rail's control floats the restore inset above it, returning to the corner
1509
+ when the drawer collapses. An overlay drawer (static or `responsiveOverlayAt`)
1510
+ still covers the control as every open overlay does, a nested Workbench's
1511
+ drawer moves only its own rails' controls, and engines without anchor
1512
+ positioning keep the corner.
1513
+
1514
+ - **A collapsed `@kerfjs/ui` `Workbench` panel's content leaves the Tab order.**
1515
+ A collapsed rail or bottom drawer kept its content in the DOM, only slid out
1516
+ and clipped, so Tab still reached its controls; focusing one (at a narrow
1517
+ width, the collapsed inspector's or output drawer's own Hide control)
1518
+ scrolled the clipped panel and slid its hidden content back over the work
1519
+ area. The panel's content wrapper now renders `inert` while `collapsed`, with
1520
+ no wiring needed, so neither Tab nor assistive technology reaches it; the
1521
+ slide-out still animates and the `restoreControl`, which lives outside the
1522
+ content, stays reachable.
1523
+
1524
+ - **A `kerfjs/overlay` popover or tooltip in a transformed or filtered modal
1525
+ `<dialog>` now lands against its anchor.** A surface rendered into a
1526
+ dialog's `[data-kerf-overlay-host][data-morph-skip]` slot is
1527
+ `position: fixed`, and a dialog styled with `transform`, `filter`,
1528
+ `perspective`, `contain`, or `will-change` becomes the containing block for
1529
+ fixed descendants, so the surface used to land offset by the dialog's
1530
+ position (and scale). `positionAnchored` (and so `autoReposition`,
1531
+ `popover()`, and `tooltip()`) now measures the element's fixed-position
1532
+ containing block with a transient 1px probe and maps its viewport
1533
+ coordinates into it, compensating translation and scale. Rotated or skewed
1534
+ containing blocks are not compensated.
1535
+ - **The `@kerfjs/ui` UX catalog demonstrates a standalone restore control.**
1536
+ The CollapsiblePanel route gains a "Restore control" example: a bottom
1537
+ drawer that collapses to a `FloatingToolbar` `restoreControl` in its frame's
1538
+ corner, wired with `wireSidebar` so the control restores the drawer and
1539
+ focus moves between it and the drawer's own hide toggle.
1540
+
1541
+ - **A `@kerfjs/ui` collapsed rail's restore control no longer covers an open
1542
+ bottom drawer beside it.** When a `CollapsiblePanel` or `ResizableRegion`
1543
+ with a `restoreControl` shared its container with an expanded bottom
1544
+ drawer — a bottom `CollapsiblePanel` or bottom `ResizableRegion` — as a
1545
+ sibling or inside the app's work-area column, the control floated in the
1546
+ container's bottom corner, on top of the drawer. It now floats the same
1547
+ inset above the drawer's top edge, follows the drawer as it resizes, and
1548
+ returns to the corner when the drawer collapses. A drawer nested deeper,
1549
+ inside the work area's own content, does not move it. This uses CSS anchor
1550
+ positioning; engines without it keep the container corner.
1551
+
1552
+ - **An open `@kerfjs/ui` `CollapsiblePanel` or `ResizableRegion` overlay now
1553
+ covers other panels' restore controls, as a `Workbench` overlay does.** A
1554
+ collapsed panel's `restoreControl` stacked at z-index 42, above
1555
+ `wireSidebar`'s compact overlay and its backdrop and above an overlay
1556
+ `ResizableRegion`, so it floated over an open overlay and stayed clickable
1557
+ behind the overlay's focus trap. `--kui-collapsible-panel-restore-z` now
1558
+ defaults to two less than `--kui-collapsible-panel-overlay-z` (38),
1559
+ `--kui-resizable-region-restore-z` to two less than
1560
+ `--kui-resizable-region-overlay-z` (39), and the compact backdrop's
1561
+ `--kui-collapsible-panel-backdrop-z` to one less than the overlay (still
1562
+ 39), so an app that moves the overlay z-index keeps the order. When the
1563
+ overlay closes, the control shows and works again.
1564
+ - **An open `@kerfjs/ui` `Workbench` overlay now covers other panels'
1565
+ restore controls.** Restore controls stacked above every overlay, so a
1566
+ collapsed drawer's corner restore control floated over an open right-rail
1567
+ overlay's content. An open overlay is now the top layer, like a sheet over
1568
+ the view beneath it: `--kui-workbench-restore-z` defaults to two less than
1569
+ `--kui-workbench-overlay-z` (39 by default, previously 42), below the
1570
+ drawer and rail overlays. When the overlay closes, the control shows and
1571
+ works again; a collapsed overlay passes pointer events through to it.
1572
+ - **`@kerfjs/ui` `wireWorkbench` overlay panels now take focus and keep Tab
1573
+ inside them,** like `wireSidebar`'s compact overlay (the ARIA dialog
1574
+ pattern). An open overlay covers the work area, yet focus stayed on the
1575
+ control that opened it and Tab walked through the covered editor. A wired
1576
+ panel that opens while it presents as an overlay now focuses its first
1577
+ focusable control (usually the close control in its header); while it is
1578
+ open, Tab and Shift+Tab cycle through its controls, and Escape, its own
1579
+ close control, or an outside press leaves it, returning focus to the
1580
+ opener. Panels opening inline never move focus. Focus returned on close
1581
+ also skips an opener inside another panel that has closed since.
1582
+ `dismissOverlays: false` leaves all of this to the app.
1583
+ - **`@kerfjs/ui` `Workbench` keeps its work-area minimum beside fixed rails
1584
+ and above the bottom drawer.** `mainMinSize` used to apply only beside a
1585
+ resizable rail, so two fixed 280px rails on a ~730px Workbench left the
1586
+ editor 174px; now every inline rail, fixed or resizable, shrinks in
1587
+ proportion (its content following the shown width) to keep the work area
1588
+ `mainMinSize` px wide. A new `mainMinHeight` prop (default 120, `0` turns it
1589
+ off) is the drawer's counterpart: an inline drawer, fixed or resizable,
1590
+ shrinks when the Workbench gets shorter, and `wireWorkbench` stops a
1591
+ resizable drawer where the work area would drop below that height (reported
1592
+ in `aria-valuemax`) instead of only at the drawer's own `max`.
1593
+ - **A `@kerfjs/ui` Workbench rail squeezed below its minimum now reports the
1594
+ width it shows.** When the Workbench was too narrow for a rail's `min`
1595
+ beside the work-area minimum, the rail showed about 172px while its
1596
+ separator still announced `aria-valuenow="180"`. The separator now reports
1597
+ the shown width, with `aria-valuemin` and `aria-valuemax` pinned to it: the
1598
+ WAI-ARIA window splitter's value is the separator's actual position and must
1599
+ sit inside its range, and the separator cannot move a rail the container
1600
+ holds there. Resizing still commits no less than `min`, and the configured
1601
+ range returns once there is room. A `ResizableRegion` a parent clamps below
1602
+ its `min` reports the same way.
1603
+ - **`KUI-L018` (`kerf-ui-analyze` / `kerf-ui-doctor`) now measures contrast and
1604
+ follows the cascade.** When a `--wa-color-{tone}-fill-loud` override and its
1605
+ `on-loud` are both literal colors (including `light-dark()`), a pair below
1606
+ 4.5:1 in either color scheme is reported with its ratio, and an unpaired
1607
+ literal fill that still clears 4.5:1 against the theme's default `on-loud`
1608
+ is no longer reported. An `on-loud` set in an ancestor scope (`:root`, or the
1609
+ leading selector of a descendant chain) or in another stylesheet the same
1610
+ entry loads now counts as the pair.
1611
+ - **`kerf-component-catalog` lets a private application declare components
1612
+ without a fake `exports` map.** In a private package
1613
+ (`"private": true`), a component's `publicExports` items may omit `subpath`; the generator
1614
+ verifies each name against the component's `source` file instead of
1615
+ requiring a `./dist/<path>.js` export the bundled app never emits. Publishable
1616
+ packages still need every subpath in `exports`. The v2 catalog schema makes
1617
+ `subpath` optional to match, and the `kerfjs/ui-composition` rule resolves a
1618
+ subpath-less export only by its source file.
1619
+ - **`kerf-ui-doctor` and the `kerfjs/ui-public-boundaries` ESLint rule no
1620
+ longer flag the documented `class="kui-app-root"` as KUI-L101 private
1621
+ anatomy.** The `@kerfjs/ui` component catalog now has a `document-baseline`
1622
+ composition entry for `@kerfjs/ui/document.css` that lists `kui-app-root`
1623
+ as its public class, with a catalog demo route showing a `SplitView` filling
1624
+ the root's definite height.
1625
+ - The `@kerfjs/ui` heading guidance (`ai/skill.md`, `llms.txt`,
1626
+ `docs/component-selection.md`, `docs/layout.md`) now sizes a panel title to
1627
+ its track: extra-large `ToolbarText` stays the title size for a page, view,
1628
+ dialog, or pane that holds it, while a narrow peripheral rail or drawer
1629
+ names itself with the default size, since extra-large truncated "Inspector"
1630
+ to "Ins…" in a 160px Workbench rail.
1631
+ - **A `@kerfjs/ui` `Workbench` panel open when `wireWorkbench` wired up no
1632
+ longer drops focus to the page when it closes from inside.** Such a panel
1633
+ had no recorded opener, so without a restore control closing it from its
1634
+ own header left focus on `<body>`. Focus now falls back to a control
1635
+ outside the panel whose `aria-controls` names it (or an element inside it).
1636
+ Each panel renders a stable `id` for that — `<id>-left-rail`,
1637
+ `<id>-right-rail`, and `<id>-bottom-drawer` — so a toggle can name the
1638
+ panel it controls.
1639
+ - **`@kerfjs/ui` `wireWorkbench` keeps overlay panels exclusive.** At a narrow
1640
+ width two overlay rails could both be open and, together wider than the
1641
+ Workbench, the right rail covered the left rail's own close control. Opening
1642
+ a panel while it presents as an overlay now closes every other open overlay
1643
+ panel, the bottom drawer included, like `wireSidebar`'s compact overlays;
1644
+ panels presenting inline are never closed by it. New option
1645
+ `exclusiveOverlays` (default `true`); pass `false` to let overlays stay open
1646
+ together.
1647
+ - **A `@kerfjs/ui` `CollapsiblePanel` or `ResizableRegion` restore control
1648
+ stays inside its container.** `restoreControl` was `position: fixed` to the
1649
+ viewport, so a panel or region embedded in a page floated it over unrelated
1650
+ page content. It now floats in the `restorePosition` corner of the element
1651
+ that holds the panel (or region), scrolls with it, and is inset by the
1652
+ component's restore inset plus the unsafe area of the edges that container
1653
+ reaches, so a full-viewport shell still places it clear of them. While the
1654
+ control is shown, that container isolates its stacking and becomes its
1655
+ containing block; an app that positions the container itself keeps its own
1656
+ `position`. As in `Workbench`, the corner owns the inset, so a
1657
+ `FloatingToolbar` hosting the control no longer doubles it.
1658
+ - The `@kerfjs/ui` UX catalog's Workbench page gains a responsive overlay
1659
+ drawer example: an output drawer with `responsiveOverlayAt: "narrow"` that
1660
+ takes its own track beside a wide editor and becomes a transient overlay
1661
+ over the editor's bottom once the Workbench is 704px or narrower, starting
1662
+ hidden there and closing from its own header, on Escape, or on a press
1663
+ outside it. The Workbench guide shows the pattern.
1664
+ - A `@kerfjs/ui` `Workbench` now stacks overlay rails above an overlay bottom
1665
+ drawer. With the drawer and a rail both presented as overlays, their order
1666
+ followed the markup, so the drawer covered the left rail while the right
1667
+ rail covered the drawer. Both rails now stack above the drawer, mirroring
1668
+ the inline layout where rails span the full height beside the drawer's
1669
+ column, and the right rail stacks above the left; restore controls stay
1670
+ above every overlay. The drawer's overlay z-index is now one less than
1671
+ `--kui-workbench-overlay-z`.
1672
+ - **A `@kerfjs/ui` `Workbench` overlay rail can always be closed from inside
1673
+ itself.** At a narrow width, the UX catalog's inspector overlay covered the
1674
+ editor toolbar's "Hide inspector" toggle, leaving only Escape or an outside
1675
+ press to close it. The catalog's resizable rails now carry their own close
1676
+ control in their `Pane` header, and the Workbench guide recommends the same
1677
+ for any panel that may present as an overlay. `wireWorkbench` now returns
1678
+ focus stranded in a panel however the panel closed — including through the
1679
+ app's own control inside it, and for inline panels — to the control that
1680
+ opened it, else to its restore control; before, only an Escape, an outside
1681
+ press, or a breakpoint collapse returned it.
1682
+ - **A `@kerfjs/ui` `Workbench` restore control stays inside its Workbench.**
1683
+ `restoreControl` was `position: fixed` to the viewport, so an embedded
1684
+ Workbench (the UX catalog's, for one) floated it over the page footer. It is
1685
+ now anchored to a corner of the Workbench itself — the drawer's in the
1686
+ corner of the work-area column, so it never covers an expanded rail — inset
1687
+ by `--kui-workbench-restore-inset` plus the unsafe area of the edges that
1688
+ corner reaches, and it scrolls with the Workbench. The Workbench now
1689
+ isolates its own stacking, so its overlays and restore controls never stack
1690
+ against the page around it. A `FloatingToolbar` can host the control
1691
+ without doubling the inset: the corner owns it, and `FloatingToolbar` now
1692
+ honors `--kui-floating-toolbar-inset` set on an ancestor as well as on
1693
+ itself. The catalog's collapsed console restores from such a toolbar.
1694
+ - **`@kerfjs/ui` `wireWorkbench` makes overlay panels transient.** A rail
1695
+ whose `responsiveOverlayAt` breakpoint applied stayed expanded over the
1696
+ editor until the user found its toggle. Pass a panel's app-owned
1697
+ `collapsed` signal (`panels: { leftRail: { collapsed } }`; `size` is now
1698
+ optional, so a panel need not be resizable) and, like `wireSidebar`'s
1699
+ compact overlay, the wiring collapses it when the breakpoint begins to
1700
+ apply (without the collapse motion) and gives back its inline state when
1701
+ the breakpoint stops applying or the wiring is disposed. An open overlay
1702
+ panel, responsive or `presentation: "overlay"`, closes on Escape or on a
1703
+ press that starts and ends outside it, and focus stranded inside returns to
1704
+ the control that opened it, else to its restore control. It is on by
1705
+ default for panels given `collapsed`; `dismissOverlays: false` turns it
1706
+ off. The UX catalog's resizable example wires its rails this way.
1707
+ - A `@kerfjs/ui` `Workbench` rail with `presentation: "overlay"` now renders
1708
+ exactly its size. Out of flow, it sized to its content plus its 1px
1709
+ separator border, so a 280px rail measured 281px; it now takes its size
1710
+ explicitly, as the responsive overlays do. Rails and the drawer are also
1711
+ `border-box` now, so a panel's `size` is its whole track, border included,
1712
+ even in an app without a global `box-sizing` reset, and overlay content
1713
+ fills the panel inside its separator instead of painting over it.
1714
+ - **A `@kerfjs/ui` `Workbench` bottom drawer with `presentation: "overlay"`
1715
+ is visible again.** Its content is positioned against the drawer's bottom
1716
+ edge, so the out-of-flow overlay box had no height of its own and collapsed
1717
+ to its 1px border. An overlay drawer now takes its configured height (220px
1718
+ by default, or its `size`), covers the bottom of the work-area column, and
1719
+ clamps its content to the overlay maximum height. The drawer also accepts
1720
+ `responsiveOverlayAt: "narrow" | "compact"` like the rails: below that
1721
+ Workbench width it presents as the same overlay, without a separator and
1722
+ never resizable, while the work area takes the full height and keeps its
1723
+ bottom safe-area inset beneath it.
1724
+ - The bundled AI assistant configs (`ai/skill.md`, `ai/cursorrules`) now
1725
+ explain the `data-kerf-overlay-host` opt-in next to the one-`mount()`-per-root
1726
+ rule: a modal `<dialog>` of your own that anchors kerf popovers or tooltips
1727
+ needs `<div data-kerf-overlay-host data-morph-skip></div>`, the one allowed
1728
+ nested-mount boundary. The `kerfjs/ai-assistant-configs` lint rule reports
1729
+ installed copies as stale until they are refreshed.
1730
+ - The opt-in `rebuiltListeners` dev warning no longer reports a popover or
1731
+ tooltip closing inside a modal dialog's host slot. Removals inside a
1732
+ `[data-kerf-overlay-host][data-morph-skip]` slot belong to the surface's own
1733
+ mount, so the enclosing mount now ignores them, as its re-renders already
1734
+ did. A listener lost to a re-render inside the surface is still reported,
1735
+ once.
1736
+ - **A popover or tooltip in a modal `<dialog>` no longer lingers after the
1737
+ dialog is removed when its anchor was moved out first.** A surface rendered
1738
+ into a dialog's host slot left with the dialog, but because its anchor was
1739
+ still in the document, kerf kept it registered as open, and a tooltip on
1740
+ that anchor never showed again. A slot-hosted surface now closes itself
1741
+ (without calling `onDismiss`) when it leaves the document, and the tooltip
1742
+ shows again on the next hover or focus.
1743
+ - **A popover inside a modal `<dialog>` is reachable by Tab in Safari on
1744
+ macOS.** A popover or tooltip rendered into a dialog's host slot follows the
1745
+ dialog's own Tab order, and WebKit on macOS skips buttons and links there
1746
+ unless the system keyboard-navigation setting is on. kerf now gives each
1747
+ implicitly tabbable control in a slot-hosted surface an explicit
1748
+ `tabindex="0"` when it opens and again before each Tab keypress, the same
1749
+ way its focus trap already did. Authored tabindexes, disabled controls, and
1750
+ surfaces outside a slot are left alone.
1751
+ - `@kerfjs/ui` `Workbench` rails gain `responsiveOverlayAt: "narrow" |
1752
+ "compact"`, mirroring `ResizableRegion`'s `responsiveFillAt`: below the
1753
+ Workbench's own 704px (`narrow`) or 448px (`compact`) width the rail
1754
+ presents as an overlay over the work area, without a separator and never
1755
+ resizable, and inline above it — the CSS decides, so apps no longer derive
1756
+ `presentation` from a `deviceClass()` check. The bottom drawer ignores it.
1757
+ A collapsed overlay rail (with `presentation: "overlay"` too) now drops its
1758
+ surface and shadow instead of leaving an empty panel-sized box over the work
1759
+ area. The UX catalog's resizable example uses it and now renders at phone
1760
+ widths, and its collapsed console's restore control is a `ToolbarControlGroup`
1761
+ toggle that actually restores the console.
1762
+ - `@kerfjs/ui` `Workbench` keeps a minimum work area beside resizable rails.
1763
+ Two rails dragged near their 480px maximum on a ~1024px Workbench used to
1764
+ leave the editor a sliver; now the work area keeps at least `mainMinSize`
1765
+ px (a new `Workbench` prop, default 320, `0` turns it off). `wireWorkbench`
1766
+ stops drag and keyboard resizing where the work area would drop below it
1767
+ (and reports that reachable maximum in `aria-valuemax`), and when the
1768
+ Workbench narrows, resizable rails shrink in proportion to their sizes, with
1769
+ their content following the shown width, instead of squeezing the work
1770
+ area. Workbenches without a resizable rail render exactly as before. The UX
1771
+ catalog's resizable example adds a resizable inspector to show it.
1772
+ - `@kerfjs/ui`'s static analyzer (`kerf-ui-analyze`, and the analyzer stage of
1773
+ `kerf-ui-doctor`) reports a new review finding, `KUI-L018`, when a
1774
+ stylesheet overrides a loud tone fill (`--wa-color-{tone}-fill-loud` for
1775
+ neutral, brand, success, warning, danger, or pop) without setting the
1776
+ matching `--wa-color-{tone}-on-loud` in the same scope. The theme pairs each
1777
+ loud fill with a foreground that clears WCAG AA, and an unpaired override
1778
+ keeps that foreground on a fill it was never checked against. The pair must
1779
+ share a selector (after resolving nesting and splitting selector lists) and
1780
+ at-rule scope in the same stylesheet, in one rule or separate ones; another
1781
+ tone's `on-loud` does not count. It is a review finding because it checks
1782
+ the pairing, not the contrast; pass `--fail-on-review` to gate it. The
1783
+ `webawesome-theme.md` customization example now sets both halves of each
1784
+ pair.
1785
+ - **Tooltips and popovers also stay visible when your own code opens a modal
1786
+ `<dialog>`.** `kerfjs/overlay` already moved every open tooltip and popover
1787
+ above a modal dialog it opened itself, but a dialog opened with a bare
1788
+ `dialog.showModal()` went unnoticed and left them inert beneath it. While
1789
+ any kerf surface is open, one capture-phase listener on the document now
1790
+ catches the dialog's `toggle` event and re-hosts them the same way, one task
1791
+ after the `showModal()` call. The listener is removed once nothing is open.
1792
+ An engine that fires no `toggle` event for `<dialog>` still misses such a
1793
+ dialog; open it through `overlay()` there.
1794
+ - **A popover inside a modal `<dialog>` is clickable.** Browsers make
1795
+ everything outside an open modal dialog inert, so a popover lifted above the
1796
+ dialog was visible but its buttons could not be clicked or focused, and
1797
+ kerf's one-mount-per-tree rule kept it from rendering inside a kerf-mounted
1798
+ dialog. `popover()` and `tooltip()` whose anchor sits inside an open modal
1799
+ `<dialog>` now render into the dialog's host slot, an element marked
1800
+ `data-kerf-overlay-host data-morph-skip`, so they are part of the modal and
1801
+ fully interactive: Tab reaches them, and Escape closes the popover before the
1802
+ dialog. A dialog `kerfjs/overlay` opened gets the slot automatically (an
1803
+ empty `display: contents` element added on first use). For your own
1804
+ `<dialog>`, add `<div data-kerf-overlay-host data-morph-skip></div>` to its
1805
+ markup, or pass `container`. The slot is the one place a second `mount()`
1806
+ may live inside a mounted tree: the enclosing mount's morph, nesting guard,
1807
+ and binding and `each()` marker scans all stop there. The `kerfjs/dev`
1808
+ `inert` warning now fires only when no slot was used.
1809
+ - `@kerfjs/ui` `Workbench` rails and the bottom drawer can be drag-resized,
1810
+ as an opt-in per panel. `WorkbenchPanel` gains `resizable: true | { min, max }`
1811
+ (off by default, so existing Workbenches render unchanged); a resizable panel
1812
+ gets a separator on its inner edge with the same focusable
1813
+ `role="separator"` contract, grip, and 20px hit target as a
1814
+ `ResizableRegion` handle. The new `@kerfjs/ui/wire-workbench` subpath's
1815
+ `wireWorkbench(root, { id, panels, deviceClass?, storage?, onResize? })`
1816
+ drives it: live pointer drags, arrow / Shift+arrow / Home / End keys,
1817
+ clamping to the limits, and commits to the app-owned size signals, with
1818
+ optional `storageKey` persistence. Collapsing keeps a panel's size, so it
1819
+ expands back to the size it had, and resizing is suspended on compact device
1820
+ classes and for overlay or hidden panels. The UX catalog's Workbench page
1821
+ adds a resizable example. `wireResizableRegions` now drives only handles that
1822
+ are direct children of a `ResizableRegion`, so it never double-drives a
1823
+ Workbench separator under the same root.
1824
+ - `@kerfjs/ui` elevation shadows follow the color scheme, with or without the
1825
+ optional `@kerfjs/ui/webawesome.css` theme. Kerf's theme layer set
1826
+ `--wa-shadow-s` / `-m` / `-l` to fixed light-mode shadows (14%, 11%, and 9%
1827
+ black), which all but vanished against the dark page, and the
1828
+ `--kui-shadow-s` / `--kui-shadow-l` foundation fallbacks copied those fixed
1829
+ values. The theme now pairs each light alpha with a stronger dark one (50%,
1830
+ 40%, 32%) through `light-dark()`, and the foundation fallbacks mirror them, so
1831
+ selected segments and app tabs, compact overlay panels, and Web Awesome
1832
+ surfaces that read `--wa-shadow-*` keep their elevation in dark mode. Light mode is unchanged. The browser parity test
1833
+ now compares every `--kui-shadow-*` token with and without the theme in both
1834
+ schemes.
1835
+ - `@kerfjs/ui` text on loud tone fills clears WCAG AA in both color schemes,
1836
+ with or without the optional `@kerfjs/ui/webawesome.css` theme. White
1837
+ `on-loud` text reached about 2.2:1 on the success fill, 3.5:1 on the light
1838
+ brand fill (`#0088ff`), and 3.6:1 on the danger fill (`#ff383c`) in both
1839
+ schemes. Kerf's theme layer and the foundation fallbacks now pair each
1840
+ fill with a foreground chosen to keep the tone's look: success keeps its
1841
+ bright green with dark text (`#1d1d1f`, 7.6:1), as warning already did; light
1842
+ brand and danger keep white text on a slightly deeper fill of the same hue
1843
+ (`#0075db`, 4.6:1; `#eb0005`, 4.6:1); dark danger keeps its fill with dark
1844
+ text (`#111113`, 5.3:1), as dark brand already did. Web Awesome accent
1845
+ buttons, badges, and checked controls pick this up, and accent `wa-badge`s now
1846
+ use their variant's `on-loud` foreground by default instead of a fixed dark
1847
+ color (`--kui-wa-badge-accent-foreground` still overrides it). The browser
1848
+ contrast test asserts every tone's `on-loud` over `fill-loud` pair, including
1849
+ pop and neutral, in both schemes with and without the theme.
1850
+ - `@kerfjs/ui` brand, success, and warning text clears WCAG AA on the lowered
1851
+ page background in light mode, with or without the optional
1852
+ `@kerfjs/ui/webawesome.css` theme. Their light `on-quiet` values (`#1e6ef4`,
1853
+ `#008932`, `#a16a00`) passed on the white surface but reached only about
1854
+ 4.1:1 on `#f2f2f7`. Kerf's theme layer and the foundation fallbacks now use
1855
+ the same hues a step darker: `#0c62f3` (4.64:1), `#007f2e` (4.62:1), and
1856
+ `#966200` (4.65:1) on the page, about 5.2:1 on white. Links, selected tabs,
1857
+ segmented and toolbar selections, and token-search accents that read
1858
+ `brand-on-quiet` darken with it. Dark mode is unchanged. The browser contrast
1859
+ test no longer skips light text over the page background.
1860
+ - `@kerfjs/ui` surfaces, links, and focus rings match the optional
1861
+ `@kerfjs/ui/webawesome.css` theme without it. Three foundation fallbacks
1862
+ pointed at a different token than the theme: `--kui-color-surface-raised`
1863
+ fell back to the surface color (the theme's dark raised surface is
1864
+ `#2c2c2e`), `--kui-color-text-link` fell back to the brand fill (`#0088ff`,
1865
+ about 3.5:1 on white) instead of the brand on-quiet text color, and the focus
1866
+ ring used the brand fill instead of the theme's focus color (`#007aff`). Each
1867
+ now falls back to the theme's value. The browser parity test now covers every
1868
+ `--kui-color-*` token the foundation declares, plus the focus ring, instead of
1869
+ only the tone tokens.
1870
+ - The `@kerfjs/ui` UX catalog's `StateBanner` route adds a placeholder with a
1871
+ badge for every tone, next to the existing badge-less placeholder, so visual
1872
+ review and captures show the solid badge's loading skeleton on each tone's
1873
+ fill. A browser test checks that each tone's badged placeholder is present.
1874
+ - `@kerfjs/ui` toned text stays readable in dark mode without the optional
1875
+ `@kerfjs/ui/webawesome.css` theme. The foundation's fallbacks for the
1876
+ success, warning, and danger `on-quiet` and `on-normal` tokens were single
1877
+ light-mode colors, so dark danger `Text` rendered dark red on a dark surface
1878
+ (under 3:1). Every tone token now falls back to the same light and dark
1879
+ pair the theme assigns, including `brand-on-loud` (dark text on the pale dark
1880
+ brand fill instead of white) and `neutral-border-quiet`. Light-mode colors
1881
+ are unchanged. A browser test bundles the package with and without the theme
1882
+ and asserts that every tone token resolves identically in both color schemes
1883
+ and that toned text clears WCAG AA in dark mode.
1884
+ - `@kerfjs/ui` danger text and badges are readable in dark mode, and every
1885
+ tone's `StateBanner` detail and quiet or outline `Badge` text now clears
1886
+ WCAG AA. The danger tone was the only one without an on-fill foreground: its
1887
+ solid badge fill and `StateBanner` text reused `danger-on-quiet`, a mid red
1888
+ in dark mode (banner detail 4.0:1, badge placeholder skeleton 2.25:1). A new
1889
+ `--kui-color-danger-on-fill` token (also accepted by `uiColor()`) matches the
1890
+ other tones' pale dark values, lifting the dark danger banner text to 8.2:1.
1891
+ The banner detail no longer dims to 78% opacity, which left the light info,
1892
+ success, warning, and danger details at 3.4 to 4.3:1; it reads as secondary
1893
+ through its smaller type, and the neutral detail uses the quiet text color.
1894
+ Quiet and outline badges use their tone's on-fill text, lifting light brand,
1895
+ success, and warning from about 4.1:1 to at least 5:1.
1896
+
1897
+ - A `@kerfjs/ui` placeholder skeleton inside a solid `Badge`, such as the
1898
+ badge of a `StateBanner` placeholder, is now clearly visible. The generic
1899
+ skeleton tint, 12% of the text color, almost disappeared on the badge's
1900
+ saturated fill in every tone. A solid badge now tints its skeleton from its
1901
+ own foreground color, which contrasts with the fill in every tone in light
1902
+ and dark mode. Quiet and outline badges keep the generic tint, which already
1903
+ reads on their pale fills. Geometry is unchanged.
1904
+ - The `@kerfjs/ui` SVG design templates render badges as filled pills: the
1905
+ `StateBanner` badge and the `ListHeader` and `List` count pills used to show
1906
+ as plain text, because the template build loaded only a hand-written list of
1907
+ stylesheets that omitted `badge.css`. The build now loads each component's
1908
+ full stylesheet set from its generated browser entry, the same set a
1909
+ consumer's browser import loads, so a nested component's CSS can no longer be
1910
+ missed. The `ListHeader` and `List` templates also pick up the label inset
1911
+ from `text.css`, so a header label now lines up with the list items below it,
1912
+ as it does in the live component.
1913
+ - A `@kerfjs/ui` `StateBanner` placeholder's badge sits at the live badge's
1914
+ height on every platform. With a skeleton instead of text, the badge took a
1915
+ baseline from the skeleton's bottom edge and sat about a pixel higher, by an
1916
+ amount that depended on the platform's font metrics.
1917
+ - A `@kerfjs/ui` `StateBanner` with a long, wrapping title keeps its badge
1918
+ one item gap after the title's last word, and its detail uses the full copy
1919
+ width. The wide flex layout shrank the title and detail together, which left
1920
+ a large gap before the badge and truncated the detail early. The title,
1921
+ badge, and detail now flow as inline text: the detail stays beside the title
1922
+ while it fits whole, and otherwise moves to its own line, truncating only at
1923
+ the full width. A wrapped title's lines stay evenly spaced.
1924
+ - A `@kerfjs/ui` `ListHeader` disclosure toggle disabled with `actionDisabled`
1925
+ is dimmed by the component itself, at the same tone as a disabled action
1926
+ button, and shows the `not-allowed` cursor. It used to rely on Web Awesome's
1927
+ native `button:disabled` dimming, so without `webawesome.css` it looked
1928
+ enabled. Disabled toggles and action buttons also no longer show hover
1929
+ feedback without `webawesome.css`.
1930
+ - A `@kerfjs/ui` `ListActionRow` placeholder keeps its `busy` spinner. The
1931
+ whole status line used to collapse into one skeleton, dropping the spinner
1932
+ the component draws from a known prop. Now only the `status` text becomes a
1933
+ skeleton, matching `ListItem`.
1934
+ - **A tooltip or popover already showing stays visible when a modal opens.**
1935
+ Lifting a surface above an open modal `<dialog>` was decided only when the
1936
+ surface opened, so a tooltip or popover already on screen when a modal
1937
+ dialog opened was left inert beneath it. Whenever `kerfjs/overlay` opens a
1938
+ modal `<dialog>` (a `native: true` modal, or one it lifted), it now moves
1939
+ every open tooltip and popover into the top layer above the new dialog. One
1940
+ that is already a `[popover]` is re-shown so it stacks on top. The existing
1941
+ `kerfjs/dev` warnings still report an engine without the Popover API, and a
1942
+ surface with controls the modal keeps inert. A modal `<dialog>` the app
1943
+ opens itself, outside kerf, is not observed.
1944
+ - Moved `mount()`'s list-binding lifecycle (turning list markers into
1945
+ bindings, first-render row-contract validation, orphan pruning) into its own
1946
+ internal module, so `mount.ts` holds only the render orchestration. No
1947
+ behavior or public API change.
1948
+ - A narrow (576px and below) `@kerfjs/ui` `StateBanner` keeps its badge
1949
+ sized to its content, one item gap after the title and on the title's
1950
+ baseline, as in the wide layout. The narrow grid stretched the badge across
1951
+ the free column into a wide pill that sat less than 1px from the title.
1952
+ - Hovering a `@kerfjs/ui` `ListActionRow` placeholder with
1953
+ `trailingActionVisibility="interaction"` no longer reveals its disabled
1954
+ trailing button. A placeholder is inert, so it keeps the live row's resting
1955
+ state, with the trailing action hidden until an interaction it cannot take.
1956
+ - A `@kerfjs/ui` `ListItem` placeholder keeps its `busy` spinner. The whole
1957
+ trailing slot used to collapse into one skeleton, dropping the spinner the
1958
+ component draws from a known prop and shifting the label's width. Now only
1959
+ the values in that slot become skeletons: `status` text in its status line
1960
+ and author-supplied `trailing` content (always a value, since the component
1961
+ cannot tell a chevron from a count) each get their own.
1962
+ - `@kerfjs/ui` placeholders keep the live disabled tone of a control the
1963
+ author disabled. A disabled `ListItem` or `ListActionRow`, a
1964
+ `trailingActionDisabled` button, a disabled `SegmentedControl` choice, or a
1965
+ `ListHeader` with `actionDisabled` rendered at full opacity as a
1966
+ placeholder, because the placeholder reset could not tell its own
1967
+ `disabled` attribute from the author's. Those controls now carry a
1968
+ component-owned `data-kui-disabled="true"` marker whenever their disabled
1969
+ prop is set; the disabled tone keys on it and the placeholder reset skips
1970
+ it. The marker is reserved: the extension-attribute props cannot set it.
1971
+ - `@kerfjs/ui` adds a browser test that renders every placeholder-capable
1972
+ component live and as a placeholder from identical props and diffs each
1973
+ element's geometry and computed chrome, so any future drift outside a value
1974
+ slot fails. It caught one more: a `ListActionRow` placeholder's `status`
1975
+ line was 3.5px shorter than the live line; the status line now always
1976
+ keeps a full line height.
1977
+ - `@kerfjs/ui`'s `Select` placeholder hint now matches the live hint: 14px
1978
+ text at a 1.6 line height, 7px below the box. It was 12px / 1.4 with a 4px
1979
+ gap, so a placeholder with a `hint` was 8.6px shorter than the loaded
1980
+ control and the content below it jumped when loading finished.
1981
+ - `@kerfjs/ui`'s `StateBanner` placeholder adds a detail skeleton only when
1982
+ `detail` is set, matching the live banner. Previously every placeholder
1983
+ showed a detail line, so a banner without one changed shape when loading
1984
+ finished. Pass the banner's real `title` and `detail` with `placeholder`;
1985
+ an empty `detail` now means no detail line.
1986
+ - `@kerfjs/ui`'s `AppTab` placeholder pill is no longer dimmed to 50% with a
1987
+ `not-allowed` cursor when `webawesome.css` is loaded; it keeps the live
1988
+ tab's tone, and only its name is a skeleton.
1989
+ - `@kerfjs/ui`'s `ListHeader` placeholder no longer dims its action button
1990
+ (48%) or, in `toggle` mode, the whole title and label (Web Awesome's native
1991
+ 50%), and its inert action and toggle give no hover feedback. A live
1992
+ `actionDisabled` header still dims its action.
1993
+ - `@kerfjs/ui`'s `SegmentedControl` placeholder now keeps its choices. The
1994
+ choices are known; only the selection is unknown, so a placeholder renders
1995
+ every choice's live label or icon at its live size, selects none, and stays
1996
+ inert. Previously every segment became a 4em text skeleton (widening icon
1997
+ segments from 40px to 60px) and was dimmed to 45%.
1998
+ - `@kerfjs/ui`'s `ListItem` and `ListActionRow` placeholders now match the
1999
+ live row. They are no longer dimmed (the rows' own `:disabled` tone and
2000
+ hover highlight skip placeholders), and a row with a `description` (or a
2001
+ `ListActionRow` `status`) keeps that line as a second, smaller skeleton, so
2002
+ the row keeps its live height instead of collapsing to one line. The
2003
+ `ListActionRow` icon placeholder is an 18px block centered in its icon slot,
2004
+ like `ListItem`'s.
2005
+ - `@kerfjs/ui` placeholders no longer look disabled. A component's
2006
+ `placeholder` keeps its controls `disabled` (inert and out of the keyboard
2007
+ order), but `skeleton.css` now neutralizes generic disabled chrome under
2008
+ `[data-placeholder="true"]`: full opacity and the default cursor instead of
2009
+ Web Awesome's native `button:disabled` dimming to 50% with a `not-allowed`
2010
+ cursor. A component's own opacity (a control hidden until interaction) still
2011
+ applies.
2012
+ - `toElement('<image href="…" />')` now returns an SVG `<image>`. The HTML
2013
+ parser rewrites an orphan `<image>` to an HTML `<img>` before kerf sees the
2014
+ tag, so it previously came back as an XHTML `img` that no `<svg>` would
2015
+ render. kerf now recognizes a leading `<image` tag in the raw input
2016
+ (case-insensitive, after leading whitespace) and parses it through the SVG
2017
+ wrapper. A genuine `<img>` is unchanged.
2018
+ - `delegateActions()` (`kerfjs/actions`) dispatches only the table's own
2019
+ entries. It used to look the action up with a plain property read, so a
2020
+ `data-action` naming an inherited `Object.prototype` member resolved:
2021
+ `"__proto__"` or `"hasOwnProperty"` threw a `TypeError` from the listener,
2022
+ and `"toString"` or `"constructor"` silently ran the inherited function.
2023
+ Those values are now ignored like any other action absent from the table.
2024
+ An own entry with such a name (`{ toString: … }`) still dispatches.
2025
+ - `toElement()` now puts orphan camelCase SVG fragments in the SVG namespace.
2026
+ `toElement('<linearGradient>…</linearGradient>')`, and likewise `clipPath`,
2027
+ `radialGradient`, and `foreignObject`, previously returned an XHTML
2028
+ `LINEARGRADIENT` element that no `<svg>` would render, because the lookup
2029
+ compared the HTML parser's lowercased tag against camelCase names. The
2030
+ fragment is now wrapped in `<svg>` and XML-parsed like `<path>` or `<g>`,
2031
+ and the returned element keeps its camelCase `localName`.
2032
+ - **A tooltip or popover no longer outlives its anchor.** When the anchor left
2033
+ the document, most commonly because the modal containing it closed, the
2034
+ `tooltip()` or `popover()` stayed on screen: a removed element fires no
2035
+ `pointerleave` or `blur`. Both now watch their anchor with the same removal
2036
+ tracking as `kerfjs/attach`. The tooltip hides, and the popover closes
2037
+ without calling `onDismiss`, as soon as the anchor leaves the document.
2038
+ Moving the anchor within the document keeps them open. A tooltip show still
2039
+ pending when its anchor is removed never appears.
2040
+ - **Overlays opened over a modal `<dialog>` are visible and usable.** A browser
2041
+ makes everything outside an open modal dialog inert and paints a plain
2042
+ element beneath it, so a `tooltip()`, `popover()`, or `confirm()` opened
2043
+ from inside a `native: true` dialog without `native` itself was invisible and
2044
+ could not be used. While a modal `<dialog>` is open, `kerfjs/overlay` now
2045
+ hosts such a surface in the top layer anyway: a tooltip or popover becomes a
2046
+ `[popover]`, and a nested modal becomes its own `<dialog>`. The browser's
2047
+ default `[popover]` / `<dialog>` styles then apply, as they do with `native:
2048
+ true`. Browsers keep a popover outside the modal dialog inert even in the top
2049
+ layer, so a lifted popover with buttons is visible but not clickable. A new
2050
+ always-on `kerfjs/dev` warning reports that case, and an engine without the
2051
+ needed API.
2052
+ - **A tooltip shown inside a modal no longer disables the modal.** `kerfjs/overlay`
2053
+ used to treat the most recently opened overlay as the only one that could
2054
+ react to input, so a `tooltip()` (which handles no input) inside an open
2055
+ modal left Escape doing nothing and let Tab leave the dialog. Every overlay,
2056
+ native or fallback, now joins one open-order stack, and each Escape, backdrop
2057
+ click, outside click, or trapped Tab goes to the topmost surface that handles
2058
+ it. A modal still blocks everything beneath it, and a surface that handles
2059
+ nothing never intercepts. A popover that dismisses on Escape gets it before
2060
+ the modal beneath. One click that is both outside a popover and on a modal's
2061
+ backdrop now closes only the popover. A native `<dialog>` is arbitrated with
2062
+ the fallback surfaces: one Escape closes one surface, and a fallback modal
2063
+ beneath an open dialog no longer takes the dialog's Tab. Closing a lower
2064
+ overlay first leaves focus in the overlay that holds it. An overlay opened
2065
+ from inside it then restores focus to the closed overlay's opener, not a
2066
+ detached node.
2067
+ - `kerfjs` now exports the `EachOptions<T>` type (`{ cacheKey?, key? }`), the
2068
+ options-object form of `each()`'s third argument, so a helper that builds or
2069
+ forwards those options can import the shape instead of restating it:
2070
+ `import { type EachOptions } from "kerfjs"`. Type-only; no runtime or bundle
2071
+ change.
2072
+ - Documentation: the companion-utility reference now matches the code. The
2073
+ router's `match()` / `activeClass()` compare a literal path prefix, so
2074
+ `match('/users/:id')` is never true. Link interception still applies to
2075
+ `target="_self"`, the no-match `outlet()` is `null` with `params` `{}`,
2076
+ components receive `(params, route)`, and hash mode keeps `route.hash` at
2077
+ `''`. Invalid `bindList` configuration throws only `RangeError`. `popover()`
2078
+ defaults `className` to `'kerf-popover'`, and the toast region is a reused
2079
+ `.kerf-toasts` element when one exists. A `resource()` `cacheKey` applies
2080
+ only to `run(input, fetcher)`, and throttle's `flush()` leaves the cooldown
2081
+ running. `delegate()` / `delegateCapture()` throw on an invalid selector at
2082
+ registration. The reference also now lists the `kerfjs/jsx-dev-runtime`
2083
+ alias, the `DEV_HOOKS` export of `kerfjs/dev`, and `Signal#peek()`.
2084
+ - Documentation: `morph(liveRoot, template)` is now described as it behaves.
2085
+ It reconciles only the root's children and never touches the root's own
2086
+ attributes, so `template` describes the content inside the root (an
2087
+ `Element` template contributes its child nodes). The examples no longer
2088
+ nest a duplicate `<article>` inside the live one. An `each()` list parent is
2089
+ not a children-only short-circuit: the diff still walks it and skips only
2090
+ the owned rows. The user-agent-owned `open` exception covers custom elements
2091
+ as well as `<details>` / `<dialog>`, and a content-only row change inside an
2092
+ `each()` list keeps its DOM node (and focus) unless the row's top-level tag
2093
+ changes or the same render also inserts, removes, or moves rows.
2094
+ - Every opt-in `kerfjs/dev` warning now ends with a silence hint that leads
2095
+ with the browser-reachable switch, for example "Silence it with
2096
+ enableWarnings({ narrowSet: false }) from kerfjs/dev, or set
2097
+ KERF_DEV_WARN_NARROW_SET=0 (or unset it) under Node." Previously the
2098
+ messages named only the environment variable, which a browser cannot reach.
2099
+ The docs now teach `enableWarnings()` wherever they showed an env-only
2100
+ switch, and name all three creation-time boundaries: `signal()`
2101
+ (`untrackedSignals`), `effect()` (`delegateInEffect`), and `mount()`
2102
+ (`rebuiltListeners`) decide once when created, so anything created before
2103
+ the install or the opt-in stays uncovered.
2104
+ - The `kerfjs/dev` rebuilt-listeners warning (`rebuiltListeners` /
2105
+ `KERF_DEV_WARN_REBUILT_LISTENERS`) now dedups once per `mount()`, as
2106
+ documented. Previously the first warning silenced every other mount for
2107
+ the life of the process, so a second mount with the same bug stayed quiet.
2108
+ - `kerfjs/router`: a second router on the same document no longer diverges
2109
+ from the URL after a link click. The first router's interceptor navigates
2110
+ with `pushState`, which fires no `popstate`, so the second router ignored
2111
+ the already-handled click and kept the old route. An already-handled click
2112
+ now re-syncs the route from the URL; when nothing navigated, it is a no-op.
2113
+ One router per document remains the supported shape: a second router does
2114
+ not follow another router's programmatic `navigate()` (no `popstate` fires
2115
+ and routers do not broadcast to each other) until the next `popstate` or
2116
+ link click. This is now documented and pinned by a test.
2117
+ - `kerfjs/scope`: a disposed `Scope` handle no longer leaks registrations.
2118
+ Previously `add` / `mount` / `effect` / `delegate` on a handle after its
2119
+ `dispose()` (or from a disposer while `dispose()` ran) pushed into a list
2120
+ nothing would ever run, leaving the effect subscribed or the listener
2121
+ attached. Such a registration now tears down at once: `add(fn)` calls `fn`
2122
+ immediately, and the wrappers create and immediately dispose.
2123
+ - `bindList` measured-height virtualization no longer applies a stale
2124
+ scroll-anchor correction. A `setHeight()` report for a row above the viewport
2125
+ is now resolved when the animation frame runs: if the source removed the key,
2126
+ moved it below the fold, or the user scrolled the row into view first,
2127
+ `scrollTop` is left alone, and several reports for one key in a frame net
2128
+ out. Fixed-height windows also clamp to the source length, so a list that
2129
+ shrinks while scrolled deep no longer pads far past its content.
2130
+ - `create-kerf-component` accepts an explicit `boundaries.rootClass: null` as
2131
+ an author decision, as its schema always allowed. A wrapper whose root
2132
+ element belongs to another catalog (a `rendersAs` wrapper) no longer has to
2133
+ invent a class to satisfy the generator. An absent `rootClass` still fails
2134
+ as undecided.
2135
+ - `@kerfjs/ui`'s `Select` placeholder now matches the live control. The label
2136
+ uses the field-label style (uppercase, extra-small, quiet, inset to line up
2137
+ with the value), and the chevron is the same glyph at the same size.
2138
+ Previously the placeholder drew a larger, regular-weight label at a
2139
+ different inset and a different, smaller chevron. Only the value is a
2140
+ skeleton; the chrome no longer changes when loading finishes.
2141
+ - **Wrapper components can declare the cataloged root they render.** A
2142
+ `kerf.components.json` component may set `composition.rendersAs`, for
2143
+ example `["@kerfjs/ui:toolbar-control-group"]`: a list of the roots it
2144
+ renders, any one of them, or nothing. `kerf-component-catalog` copies it
2145
+ into the generated v2 entry and fails unless every key resolves to a
2146
+ cataloged entry. `eslint-plugin-kerfjs`'s `ui-composition` rule, and so
2147
+ `kerf-ui-doctor`, now loads the application and third-party catalogs a
2148
+ `.kerf-ui-profile.json` declares. It resolves their components by package
2149
+ subpath or source file and checks a wrapper as each declared root: a zone
2150
+ must accept every root, each root's parent contract applies where the
2151
+ wrapper is placed, and a wrapper counts as zero or one child. Undeclared
2152
+ wrappers keep reporting `KUI-L202`.
2153
+ - `@kerfjs/ui`'s `AppTab` adds `pending` for a known tab that is still
2154
+ opening. It keeps the name visible in the quiet text color and uses it as
2155
+ the tab's accessible name, so a trailing spinner's label is not folded in.
2156
+ Like `placeholder`, it disables select and close, turns off dragging, and
2157
+ sets `aria-busy`, and it shows the consumer's `trailing` spinner. It keeps
2158
+ the live tab's pill geometry, so it swaps in place without shifting the bar.
2159
+ Dormant tabs (placeholder or pending) no longer reveal their disabled close
2160
+ button on hover.
2161
+ - `@kerfjs/ui`'s `wireSidebar` moves focus into an opening panel without
2162
+ scrolling it. A plain `focus()` scrolled the panel's clipped content to the
2163
+ target while it was still sliding in, then the slide unwound that scroll:
2164
+ a bottom drawer's content jumped up past its top and drifted back. The
2165
+ collapsible-sidebar recipe also floats the drawer's expand toggle in a
2166
+ `FloatingToolbar` at the bottom edge the drawer opens from, and drops the
2167
+ divider under the drawer's toolbar.
2168
+ - `@kerfjs/ui`'s `Skeleton` takes `block` (default `false`). It lays the
2169
+ placeholder out as `display: block` instead of `inline-block`, for a
2170
+ skeleton that stands in for a box rather than text: no text line and no
2171
+ baseline gap of its own. `ListItem`'s placeholder icon uses it.
2172
+ - `@kerfjs/ui/css-values` adds `remify(px)`, the runtime twin of source
2173
+ CSS's `remify(<px>)`. It turns a pixel count into a rem `CssLength` against
2174
+ the fixed 16px baseline, so `remify(18)` is `1.125rem`. `ListItem`'s
2175
+ placeholder icon now uses it at 18px, and `Skeleton` no longer forces a
2176
+ 24px minimum width, so small placeholders keep the size they ask for.
2177
+ - `@kerfjs/ui/catalog`'s application-sized (`height: "app"`) example frame
2178
+ no longer loses taps in Safari/WebKit. The frame became the containing block
2179
+ for screen-fixed chrome through `contain: layout`. Combined with its clip,
2180
+ that made WebKit mis-hit-test any transformed element inside an open compact
2181
+ overlay. Every pressed `ListItem` scales, so taps on an overlay rail's items
2182
+ went to their section instead. The frame now uses an identity transform,
2183
+ which docks the same chrome without the bug and renders identically.
2184
+ - **Breaking (`@kerfjs/ui/catalog`):** `CatalogExample`'s viewport drops
2185
+ `height: "fill"` and `fillChildren`. The catalog lays examples out at their
2186
+ content height, so neither could give a specimen a definite height, and a
2187
+ child sized with `height: 100%` (a horizontal `ResizableRegion`, say)
2188
+ collapsed to its content. Use a fixed `height` (`short` through `app`) when
2189
+ a specimen must fill its frame. `minHeight` remains, documented as a minimum
2190
+ rather than a fill.
2191
+ - `create-kerf-component`'s `kerf.components.json` now accepts an optional
2192
+ `composition.wiring.stateAttributes` declaration (the wiring-owned state
2193
+ attributes `@kerfjs/ui`'s catalog now carries), so third-party
2194
+ component authors can list the `data-*` attributes their wiring helpers write
2195
+ (`{ name, on, helper, meaning }`). `kerf-component-catalog` passes them
2196
+ through to the generated `component-catalog-v2.json` and reports a non-`data-*`
2197
+ name, a duplicate name, an empty `on` or `meaning`, or a helper missing from
2198
+ `wiring.helpers` at its exact path.
2199
+ - `@kerfjs/ui`'s component catalog now declares **wiring-owned state
2200
+ attributes**. A new optional `wiring.stateAttributes` in
2201
+ `component-catalog-v2` (and per wiring item in v1) lists each `data-*`
2202
+ attribute a wiring helper writes at runtime, such as `data-handle-inset` and
2203
+ `data-resizing` from `wireResizableRegions`. For each one it records the
2204
+ element, the helper, and the meaning, so AI consumers and tools can tell
2205
+ them apart from attributes the app writes. Every first-party wiring helper
2206
+ is declared. `check:catalog` fails when a helper's declarations differ from
2207
+ what its source writes.
2208
+ - `@kerfjs/ui`'s `wireSidebar` no longer leaves focus inside a panel it just
2209
+ collapsed. When the collapse was triggered from a toggle inside the panel
2210
+ (the documented placement), focus now moves to that panel's toggle outside
2211
+ it, including one the app renders only once the panel is collapsed. The
2212
+ collapsible-sidebar recipe now shows one control per action: each panel's
2213
+ own collapse toggle while it is open, and the main header's expand toggle
2214
+ only while it is collapsed. Wide widths no longer show two rail toggles.
2215
+ - `@kerfjs/ui`'s `wireSidebar` keeps a compact overlay intact when the app
2216
+ re-renders the wired root without changing a panel. Previously, selecting a
2217
+ destination in an open compact rail morphed the root, which removed the
2218
+ overlay attributes and the backdrop, and the "overlay" rail fell back into
2219
+ the layout. The wire now re-applies its host attributes and backdrop after
2220
+ any such re-render, and the backdrop carries `data-morph-preserve`.
2221
+ - `@kerfjs/ui`'s `wireSidebar` now opens a compact overlay only on a user
2222
+ action. Wiring on a compact device, or crossing from a wide device class to
2223
+ a compact one, collapses every panel. The page is no longer covered by a
2224
+ backdrop and focus trap until dismissed. Crossing back to a wide class, or
2225
+ disposing the wire, restores each panel's remembered inline state.
2226
+ Persistence now stores only that inline choice, never an overlay's
2227
+ open/closed state. A new optional `WireSidebarPanel.inlineCollapsed`
2228
+ declares the inline default when an app seeds its signal from the device
2229
+ class, which avoids an open first frame on a compact device. The
2230
+ collapsible-sidebar recipe no longer opens its rail as a blocking overlay
2231
+ on load at compact widths.
2232
+ - `@kerfjs/ui`'s `ResizableRegion` handle keeps its hit target and focus ring
2233
+ whole at a clipping edge. When a parent clamps the region to its own edge
2234
+ (the catalog's 390px stage, an app shell with a `max-width` container),
2235
+ `wireResizableRegions` marks the region `data-handle-inset` and the handle
2236
+ moves inside it instead of overhanging the edge by 10px, where the frame cut
2237
+ its focus ring in half. The ring is now drawn inside the handle's box
2238
+ (`outline-offset: -3px`), so it is also no longer shaved where the region's
2239
+ ends meet a clipping edge.
2240
+ - `@kerfjs/ui`'s `wireResizableRegions` keeps a clamped separator's
2241
+ `aria-valuenow`/`aria-valuemax` current at rest. Previously, after a size was
2242
+ saved at a wider width, narrowing the parent or any unrelated re-render left
2243
+ the handle reporting the unclamped rendered size until it was next focused or
2244
+ resized. A `ResizeObserver` on each region and its parent and a
2245
+ `MutationObserver` for re-renders now re-clamp the report; the disposer
2246
+ disconnects both.
2247
+ - The `@kerfjs/ui` catalog's `height: "app"` example frame is now the
2248
+ containing block for screen-fixed chrome, so a compact `CollapsiblePanel`
2249
+ overlay, its backdrop, and restore controls dock to the frame's edges. The
2250
+ collapsible-sidebar recipe's compact rail was fixed to the page's left edge,
2251
+ 24px outside the inset frame, so its leading edge looked cut off at 390px.
2252
+ - The `CollapsiblePanel` compact-overlay backdrop now covers its whole
2253
+ containing block. As a `<button>`, it did not stretch between its insets and
2254
+ scrimmed only a 35px strip.
2255
+ - `@kerfjs/ui`'s `wireResizableRegions` now bounds a resize to the space the
2256
+ region's parent actually leaves. When a parent clamps the track (a
2257
+ `max-width` stage, a narrow container), pointer and keyboard resizing stop at
2258
+ the visible size, and the separator reports that size in `aria-valuenow` and
2259
+ its visible maximum in `aria-valuemax`. Previously a region resized to 420
2260
+ inside a 340px stage announced 420 and needed several key presses before the
2261
+ separator moved. Focusing the handle reports a stale larger committed size as
2262
+ the shown size without committing it.
2263
+ - The UI evaluator's `KUI-B050` target-size rule now accepts a 44×36 target
2264
+ inside compact density (`[data-density="compact"]`), matching the 36px
2265
+ compact row height; standard density still requires 44×44, and the width
2266
+ floor is unchanged.
2267
+ - Fixed `kerf-ui-analyze` and the `eslint-plugin-kerfjs` UI rules treating
2268
+ every name in a catalog entry's `publicExports` as that entry's component,
2269
+ so a helper such as `uiColor` or `flex` called with an object whose keys
2270
+ matched a contract path (`uiColor({ choices: [...] })`) was checked as a
2271
+ `Select` or `List` call. Only component exports, whose names start with an
2272
+ uppercase letter as JSX component tags do, now resolve to an entry; the
2273
+ `@kerfjs/ui` catalog check fails if a cataloged `SafeHtml` render function
2274
+ is lowercase or any other runtime export is uppercase.
2275
+ - The `@kerfjs/ui` component catalog's `ToolbarText` entry now lists every
2276
+ token its `xlarge` size reads (`--kui-color-text`, `--kui-font-l`,
2277
+ `--kui-font-2xl`) in `publicTokens`; previously it named only the tokens of
2278
+ the smaller sizes.
2279
+ - The `@kerfjs/ui` browser evaluator's target-size check (`KUI-B050`) now
2280
+ measures the pointer-reachable area instead of only the border box: an
2281
+ undersized control is hit-tested outward from its center, so a transparent
2282
+ `::before`/`::after` hit layer (such as the `ListHeader` action's) counts,
2283
+ while `pointer-events: none` decoration, clipping, and overlapping
2284
+ neighbors do not. Diagnostic evidence now carries the measured size plus
2285
+ the border `box`.
2286
+ - Fixed the `eslint-plugin-kerfjs` `ui-css-values` messages (`KUI-L013`,
2287
+ `KUI-L014`, `KUI-L017`) listing suggested helpers with unbalanced backticks
2288
+ (``use `uiColor() or `foregroundColorVar().``); each helper is now wrapped
2289
+ as `` `uiColor()` ``.
2290
+ - Fixed `kerf-ui-analyze` skipping the CSS-value contracts of `@kerfjs/ui`
2291
+ `Select` and `Skeleton`. Its component lookup was keyed by display name, so
2292
+ the same-named Web Awesome catalog entries (`wa-select`, `wa-skeleton`) —
2293
+ which carry no CSS-value props — shadowed them, and a wrong-grammar helper
2294
+ such as `colorVar()` for `SelectChoice.color` went unreported although the
2295
+ ESLint rule caught it. Entries now resolve by `package:id`, using the
2296
+ selection catalog's public exports and import subpaths.
2297
+ - Fixed `@kerfjs/ui` monospace text rendering in the generic face (Courier on
2298
+ macOS Chromium) whenever Web Awesome was loaded: `--kui-font-mono` deferred to
2299
+ Web Awesome's `ui-monospace, monospace`, which Chromium does not resolve, and
2300
+ the trailing generic `monospace` kept Kerf's named fallbacks from ever
2301
+ applying. `--kui-font-mono` is now Kerf's own stack (`ui-monospace,
2302
+ SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace`),
2303
+ and the Web Awesome theme points `--wa-font-family-code` at it so Kerf `Text
2304
+ font="monospace"` and Web Awesome code text match.
2305
+ - The `@kerfjs/ui` Web Awesome theme now gives default-size single-line
2306
+ controls Kerf's 44px control height, so a plain `wa-input` or `wa-button`
2307
+ sits flush beside a Kerf `Select` instead of about 9px shorter. It sets
2308
+ `--wa-form-control-height` to `2.75em` (44px at the default size) on Button,
2309
+ Color Picker, Input, Known Date, Number Input, Radio Group, Select, Textarea,
2310
+ and Time Input; `size="large"` scales proportionally, `size="small"` keeps Web
2311
+ Awesome's compact height, and buttons inside a `ToolbarControlGroup` keep the
2312
+ group's 40px (32px compact) height. Tags, copy buttons, and toasts are
2313
+ unchanged.
2314
+ - Fixed an `@kerfjs/ui` `Select` menu drawing two separators when a choice with
2315
+ `separatorBefore` opened a separated group: the group's border plus a
2316
+ `wa-divider` left an empty band between the group title and its first
2317
+ choice. `separatorBefore` now only divides a choice from the previous choice
2318
+ in the same list; a group boundary is already the single separator.
2319
+ - Fixed `@kerfjs/ui` compact `ToolbarControlGroup` end highlights not being
2320
+ concentric with the group: controls sat 2px from the sides but 1px from the
2321
+ top and bottom. A compact group now has no padding, so its 32px controls sit
2322
+ on a 1px inset on every side with a radius of the group radius minus 1px
2323
+ (pill and rounded). In compact mixed groups the raised selection still paints
2324
+ over the border with the group's radius, neighboring controls still abut, and
2325
+ the trailing dropdown trigger keeps the 1px end inset instead of running onto
2326
+ the border. Compact groups are 2px narrower as a result.
2327
+ - Added `Toolbar.safeAreaEdges` to `@kerfjs/ui` so an app bar or bottom bar
2328
+ that sits at a screen edge, outside any `Pane` header or footer, can claim
2329
+ those edges for device safe areas. A toolbar there used to take only the
2330
+ inline edges an owner handed it, so the app-shell recipe's top bar never
2331
+ cleared the status area. Each claimed side pads by the routed
2332
+ `--kui-edge-inset-*` context, or the full device inset when nothing routes
2333
+ it, while the bar's surface and divider still paint through; the minimum
2334
+ height grows with the claimed block insets so a shrinking flex column keeps a
2335
+ whole control row clear. A claim inside a `Pane` header or footer adds
2336
+ nothing, since the pane already owns those edges. The app-shell recipe's app
2337
+ bar now claims the top edge and both sides.
2338
+ - Fixed `@kerfjs/ui` slide-motion `ResizableRegion` content overflowing its
2339
+ separator when a parent clamps the region. The expanded content kept the
2340
+ committed size even when a `max-width` or narrow container held the track
2341
+ smaller, so in the catalog at 390px a region resized to 420px showed text
2342
+ running past its handle. Expanded content now follows the region's actual
2343
+ track on both axes; the fixed expanded size still applies while collapsing, so
2344
+ the collapse keeps reading as a slide.
2345
+ - Fixed `@kerfjs/ui` `ResizableRegion` panes stopping at their content's
2346
+ height. The region's content now spans the whole region, like its separator,
2347
+ and a lone child (normally a `Pane`) fills it, so the app-shell recipe's
2348
+ navigation and inspector panes reach the bottom edge and scroll long content
2349
+ inside their own content slot instead of ending partway down the region.
2350
+ Several children still stack at their natural height.
2351
+ - Fixed `@kerfjs/ui` `Toolbar responsive="center-priority"` leaving an
2352
+ expanded center control at roughly half the row on narrow toolbars. The
2353
+ policy set the toolbar's own grid template inside a container query on the
2354
+ toolbar itself, which can never match, so the center kept only the first
2355
+ column track once the leading and trailing zones left. The dead rule is gone
2356
+ and the expanded center now spans every column track, filling the toolbar's
2357
+ content width at phone widths.
2358
+ - Fixed a nested `@kerfjs/ui` `List`, `Row`, or `Grid` inheriting its
2359
+ ancestor's `gap` and `flex`. Those props travel through private custom
2360
+ properties, which inherit, so a nested `List` without its own `gap` took the
2361
+ enclosing `List`'s gap (a heading unit inside a form got a 24px gap between
2362
+ its title and supporting line) and any nested instance without `flex` took the
2363
+ ancestor's flex growth. Every instance now resets its private values, so an
2364
+ omitted prop means that component's own default. The workspace-header recipe's
2365
+ breadcrumb now sits directly above its title and the List demo's section rows
2366
+ sit flush under their header, as intended.
2367
+ - Fixed `@kerfjs/ui` slide-motion `ResizableRegion` content staying at its
2368
+ previous width during a live resize until the app re-rendered the committed
2369
+ size. `wireResizableRegions` now applies the live size to the sliding content
2370
+ as well as the track, for pointer drags and key presses, so the content fills
2371
+ the region (including a safe-area edge extent) throughout the drag and a later
2372
+ collapse still slides it out at the resized width.
2373
+ - Fixed the `@kerfjs/ui` `ListHeader` action's pointer target being only its
2374
+ fitted 36px square although the guidance promises 44px. A transparent hit
2375
+ layer now extends the target to at least 44 × 44 around the square without
2376
+ moving layout or enlarging the painted hover surface. Compact headers are
2377
+ 36px tall like the rest of the compact List family, so their action target is
2378
+ 44px wide and clamped to the header height, never reaching into a neighboring
2379
+ row.
2380
+ - Fixed re-renders closing open Web Awesome popups: the morph (and the keyed-list
2381
+ attribute fast path) no longer removes a live `open` attribute from custom
2382
+ elements (`wa-select`, `wa-dropdown`, `wa-dialog`, …) when the template omits
2383
+ it — the same user-agent-owned treatment `<details>` / `<dialog>` already
2384
+ had. A template can still set `open`; closing stays imperative.
2385
+ - The `@kerfjs/ui` composer-form recipe's supporting line now sits directly
2386
+ under its toolbar title instead of 24px lower, because a nested `List` no
2387
+ longer inherits the form's section gap (see the nested `List`/`Row`/`Grid`
2388
+ fix above). The guidance now
2389
+ also states that `ToolbarText` below `xlarge` is intentionally quiet identity
2390
+ text with no tone option. A normal-color subsection title is `Text` with an
2391
+ `h2`–`h6` variant, or `ListHeader` for a list or menu section.
2392
+ - Fixed `@kerfjs/ui` `ToolbarText size="small"` labels rendering in a
2393
+ monospace fallback face in Chromium. The small size used the code-font token,
2394
+ which resolves through Web Awesome's `ui-monospace, monospace` stack; Chromium
2395
+ does not recognize `ui-monospace`, so labels such as a pane's "Workspace" or
2396
+ "Ready" fell back to the generic monospace font. Every `ToolbarText` size now
2397
+ keeps the inherited UI sans stack.
2398
+ - Fixed `@kerfjs/ui` `ListInsetControl` not stretching its control as
2399
+ documented. Its `justify-content: stretch` is a no-op on a flex row, so a
2400
+ `Select`, `wa-input`, or `wa-button` inside stayed at its natural width. Each
2401
+ direct child now grows to fill the inset row (several children share it with
2402
+ the 8px gap) and may shrink below its intrinsic width instead of overflowing.
2403
+ - `@kerfjs/ui` `List`, `Row`, and `Grid` can now be the layout root of a
2404
+ fixed-height parent. New `fill` takes the parent's full height (use `flex`
2405
+ inside a flex layout as before), and new `rootAttributes` carries safe
2406
+ `data-*` metadata while the component's structural attributes stay
2407
+ protected. The app-shell and collapsible-sidebar recipes now use a filling
2408
+ List or Row root instead of a frame `Pane` whose scroll owner never scrolled;
2409
+ the collapsible sidebar's rail and drawer now reach the real frame edges, so
2410
+ they paint through safe areas as the layout model intends. The UX catalog
2411
+ adds an application-sized `height: "app"` (592px) specimen frame, and both
2412
+ recipes use it instead of the cramped 360px `tall` frame.
2413
+ - Fixed a `@kerfjs/ui` stacked `Toolbar` clipping its last trailing action at
2414
+ phone widths (the compact-toolbar recipe's "More" button at 390px). A
2415
+ toolbar's trailing zone now wraps whole control groups onto another
2416
+ trailing-aligned row under every `responsive` policy, and a
2417
+ `responsive="stack"` toolbar wraps its stacked center and trailing groups the
2418
+ same way, so no action is ever clipped or shrunk. Stacked zones also span the
2419
+ full toolbar width; they previously lost 16px to empty column tracks. New:
2420
+ `responsive="wrap"` keeps a heading on one row while everything fits and
2421
+ otherwise moves the trailing zone below a whole title instead of truncating
2422
+ it. The loading-inspector recipe uses it, so its narrow heading shows the
2423
+ whole record title instead of an ellipsis.
2424
+ - `@kerfjs/ui` layouts and `Pane` now handle device safe areas as one model.
2425
+ Pane and panel backgrounds, separators, and dividers paint through unsafe
2426
+ areas; content is padded only on the edges a region actually reaches, and
2427
+ block insets become scroll padding so content can scroll under the status bar
2428
+ or home indicator but always scroll clear. `Workbench` rails and drawer,
2429
+ `CollapsiblePanel`, and the `SplitView` list grow by the inset they dock to.
2430
+ A center pane picks up the inset when an adjacent rail collapses, and
2431
+ interior or nested edges are never double-inset. A header or footer `Toolbar`
2432
+ keeps its dividers edge to edge. New: `Pane.safeAreaEdges` (default all
2433
+ sides; `[]` opts out), the `--kui-safe-area-*` device-inset tokens (default
2434
+ `env(safe-area-inset-*)`), the inherited `--kui-edge-inset-*` edge context for
2435
+ app-owned layouts, and `--kui-resizable-region-edge-extent`. Nothing changes
2436
+ on devices or pages without safe-area insets.
2437
+ - Fixed a `@kerfjs/ui` `ListHeader` action sitting about 4px outside the
2438
+ trailing toolbar action of the Pane header above it. Its fitted action now
2439
+ centers in the same 44px slot a toolbar control occupies at the 8px inline
2440
+ margin, so trailing icon actions share one axis. The action's size, 18px
2441
+ visual, and hover square are unchanged.
2442
+ - **Breaking (`@kerfjs/ui`, 5.0 beta):** `SelectChoice.color` now accepts only
2443
+ a foreground color, the new `CssForegroundColor` brand from
2444
+ `@kerfjs/ui/css-values`. `uiColor()` returns it for foreground token names
2445
+ (the new `UiForegroundColorName`: the `*-on-*` roles, `text`, `text-quiet`,
2446
+ `text-link`, and the `*-text` aliases), and the new
2447
+ `foregroundColorVar('--app-icon-color', fallback?)` returns it for an
2448
+ application-owned property. The `--kui-color-success` / `warning` / `danger`
2449
+ / `pop` / `accent` compatibility aliases are quiet fills that read like
2450
+ foreground colors; colored with one, an icon rendered at about 1.2:1
2451
+ contrast. `uiColor('success')` and the other fill, border, and surface tokens
2452
+ still return a plain `CssColor` and no longer type-check as an icon color,
2453
+ and neither does a plain `colorVar()` value. Migrate
2454
+ `color: uiColor('success')` to `uiColor('success-on-quiet')` and
2455
+ `color: colorVar('--app-color')` to `foregroundColorVar('--app-color')`;
2456
+ `uiColor('…-on-…')` calls keep compiling unchanged. The catalog's CSS-value
2457
+ contract for `choices[].color` lists `uiColor` and `foregroundColorVar`, so
2458
+ `eslint-plugin-kerfjs` also reports `colorVar()` there (`KUI-L014`), and
2459
+ the source and packed consumer type contracts pin the rejected fills.
2460
+
2461
+ - Fixed an `@kerfjs/ui` icon-only `Select` beside other controls in one
2462
+ `ToolbarControlGroup`. A compact Select no longer eats 1px of the group's
2463
+ 4px gap on each side (the lone-trigger padding overlap now applies only when
2464
+ it is the group's only child), a compact rounded Select uses its siblings'
2465
+ item radius instead of the lone-slot radius, and the Select now shows the
2466
+ same hover pill as its sibling buttons (a lone Select lifts the whole group,
2467
+ like a popup-menu dropdown). In a group with per-control focus rings
2468
+ (`focusRing="control"`, the default) the Select paints the same ring as its
2469
+ siblings even when `focusRingOwner="group"` was set, which previously left it
2470
+ with no visible focus. A compact icon-only `<button>` is now a 32px circle,
2471
+ so a selected compact segment is no longer a 34x32 oval. The
2472
+ ToolbarControlGroup catalog adds a "Select beside actions" example.
2473
+
2474
+ - Changed the `@kerfjs/ui` icon-only `Select`
2475
+ (`selectedPresentation="icon-only"`) to keep its disclosure caret. The
2476
+ selected icon and caret now form one pill with the same geometry as a
2477
+ `ToolbarControlGroup` popup-menu `wa-dropdown` trigger: 8px inline padding on
2478
+ both sides, 12px from the icon to the caret, the same caret glyph size, and a
2479
+ 40px default or 32px compact control height, so the icon sits left of center
2480
+ to balance the caret. In a single `ToolbarControlGroup` the group now sizes to
2481
+ the trigger (a 70x44 default or 68x34 compact pill, wider than it is tall)
2482
+ with an even inset on every side and a concentric radius, for pill and
2483
+ rounded shapes, so the group-owned outline or halo ring follows the pill while
2484
+ focused and while the listbox is open. Before, a default-size trigger was a
2485
+ 32px square left-aligned in its 44px group, and the caret was hidden. The
2486
+ Select catalog adds a default-size "Toolbar icon" example beside the compact
2487
+ one.
2488
+
2489
+ - Fixed the `@kerfjs/ui` icon-only `Select` focus ring in a
2490
+ `ToolbarControlGroup` not matching the control: the compact trigger grew its
2491
+ group into a 36x34 oval and its disclosure caret overflowed the trailing edge.
2492
+ The group-owned ring now stays concentric with the trigger while focused and
2493
+ while the listbox is open. The Select demo's "Quiet" option icon also used the success fill alias
2494
+ as its color and was nearly invisible; it now uses `success-on-quiet`, and the
2495
+ `SelectChoice.color` guidance names foreground tokens.
2496
+
2497
+ - `@kerfjs/ui` UX catalog: the ten production recipes now compose Kerf
2498
+ components, layouts, and Web Awesome surfaces through their public
2499
+ configuration alone, with no route stylesheets, inline styles, or
2500
+ styling-only classes. The list-detail dialog is rebuilt from `DialogSurface`,
2501
+ the dialog's own labeled header and close control, `SplitView` (a full-screen
2502
+ list-to-detail drill-down on compact devices), aligned `ListHeader`s, a
2503
+ `ValueTable`, and footer actions. The desktop application shell switches to one
2504
+ pane at a time below desktop sizes through `deviceClass()`. Page and pane
2505
+ headings stack instead of hiding their titles at narrow widths, and supporting
2506
+ copy, content-item text, and loading skeletons sit on the shared 17px text
2507
+ inset. The catalog frames each recipe in a `CatalogExample` viewport that the
2508
+ recipe declares through an exported `presentation`, and recipe ownership notes
2509
+ render as that example's note. `npm run check:recipes` now fails on a recipe
2510
+ stylesheet, an inline style, a class outside the published layout and Web
2511
+ Awesome vocabulary, a non-public stylesheet import, or recipe-specific rules in
2512
+ the catalog shell stylesheet.
2513
+ - Fixed `@kerfjs/ui/webawesome.css` `wa-dialog` titles given as a plain-string
2514
+ `label` sitting at the bare surface inset; they now inset by one bordered
2515
+ item step (`--kui-layout-item-padding` + 1px) so the header label lines up
2516
+ with body text and icons. Slotted label elements are unaffected.
2517
+ - Fixed icon + label `wa-button`s inside `ToolbarControlGroup` stacking the
2518
+ icon above the label; their label part now lays out as a single nowrap row,
2519
+ matching native mixed buttons.
2520
+ - `prompt()` / `form()` now reject with a `TypeError` when a validator returns
2521
+ a promise (validators are synchronous), instead of resolving the value and
2522
+ leaving an unhandled rejection. `prompt()` also re-reads its input on every
2523
+ OK, so a reactive `render` that replaces the input no longer submits the
2524
+ detached original's stale value, and a removed input rejects the promise.
2525
+ - A local `npm run check` run with `KERF_SKIP_PACKAGE_GATES=1` no longer
2526
+ records a verified tree, so the pre-push hook cannot skip the sibling-package
2527
+ gates that run left out.
2528
+ - `kerfjs/overlay`: a `prompt()` `validate` or `form()` `field.validate` that
2529
+ throws now closes the dialog (full teardown, focus restored) and rejects the
2530
+ returned promise with the original error. Previously the error escaped the
2531
+ OK click or Enter handler, and the dialog stayed open with an OK button that
2532
+ could never succeed. Validators are synchronous; this is the error channel
2533
+ for a validator bug.
2534
+ - `kerfjs/overlay`: when a `form()` field input disappears after the dialog
2535
+ opens (for example a reactive `render` re-render drops it), OK and Enter now
2536
+ close the dialog and reject the promise with an error naming the missing
2537
+ field. Previously `form()` resolved `null`, which
2538
+ reads as a Cancel, and threw from the click handler.
2539
+ - `@kerfjs/ui`: a multiline `ListItem` whose label fits on one line now
2540
+ centers its icon on that line. The row's 44px minimum used to stretch the
2541
+ grid track, which centered the label but left the start-aligned icon about
2542
+ 1.4px above it.
2543
+ - `@kerfjs/ui`: a `ToolbarControlGroup` with `focusRing="outline"` or
2544
+ `"halo"` keeps its group focus ring while a `Select` inside it has its
2545
+ listbox open. Chromium and WebKit did not carry `:focus-within` from the
2546
+ focused option to the group, so the ring disappeared.
2547
+ - UX catalog: the foundation palette's Brand swatch uses the brand on-fill
2548
+ color again, the Spacer demo gives its flexible spacer room to grow again,
2549
+ and the TokenSearchField adoption demo again wires its chip keyboard and
2550
+ `onEdit` readout. The catalog demo rework had broken all three.
2551
+ - Documented and pinned how `tooltip()` surfaces a failed show from its delay
2552
+ timer: the half-built tooltip is rolled back, the original error escapes the
2553
+ timer for the host to report (a window `error` event in browsers, matching
2554
+ kerf's other deferred callbacks), and the tooltip stays armed so the next
2555
+ hover or focus tries again.
2556
+ - Fixed the dialog helpers (`confirm` / `prompt` / `form` / `choice`) leaving
2557
+ wiring behind when a step after the overlay opened failed. Their post-open
2558
+ wiring (required-slot checks, the click-table `delegate()`, the Enter-key
2559
+ listener) is now part of construction: a failure removes the listeners
2560
+ already wired, closes the overlay (including a `native` `<dialog>`), restores
2561
+ focus, and rethrows the original error, so no pending promise is left
2562
+ attached to an on-screen dialog.
2563
+ - Added `ticket:timing summary --all`, a read-only cross-ticket timing report
2564
+ (median/p90 per phase, gate, and check step) that counts one push shared by
2565
+ a batch of tickets once and detects and excludes fan-out backfill, such as
2566
+ the first timed push that attached one check interval to 374 historical
2567
+ tickets.
2568
+ - Ticket timing now records per-step durations of the root `npm run check`
2569
+ chain (printed at the end of every run), interrupted gate attempts, active
2570
+ time through `ticket:timing claim`/`release` wrappers around `hotsheet-cli`,
2571
+ and CI/publication intervals imported idempotently from GitHub Actions with
2572
+ `ticket:timing import-ci`.
2573
+ - The pre-push hook no longer reruns `npm run check` when a local run already
2574
+ passed on the exact clean tree being pushed; the skip is recorded in ticket
2575
+ timing, and any dirty worktree, different tree, Node.js change,
2576
+ failed/interrupted rerun, or `KERF_FORCE_CHECK=1` runs the full gate.
2577
+ - The pre-push hook no longer fans its timing record out to every ticket in a
2578
+ push that names more than 25 of them (a first push of a long history, a
2579
+ force-push). It prints a notice and records only the explicit
2580
+ `KERF_TICKET_TIMING_TICKETS` list, or nothing, so it can no longer write the
2581
+ backfill shape the cross-ticket summary has to exclude.
2582
+ - The pre-push hook's "already verified" skip now also requires the same
2583
+ platform, architecture, and installed dependencies as the passing run: a
2584
+ fingerprint of every `package-lock.json` and `node_modules/.package-lock.json`
2585
+ across the root, `ui/`, `eslint-plugin/`, `create-kerf-component/`, and
2586
+ `site/`. A reinstall, a lockfile change, or a missing `node_modules` now runs
2587
+ the full gate.
2588
+ - `ticket:timing record` accepts `--run-id <n>`, and `import-ci` no longer
2589
+ imports a GitHub run a second time when it was already recorded by hand:
2590
+ an interval with that run id, or one with no run id for the same phase and
2591
+ gate whose span overlaps the run's (within 60 seconds), counts as imported.
2592
+ - `bindList()` now rolls back when its first render throws: rows that pass
2593
+ already created are disposed (content mounts and element-mode `dispose`
2594
+ callbacks) and removed before the original error is rethrown, instead of
2595
+ leaking live row effects with no handle to release them.
2596
+ - `bindList()` virtualization now validates its dimensions: heights (fixed,
2597
+ estimated, callback-returned, and `setHeight` reports) must be finite and
2598
+ non-negative, a fixed window-mode `rowHeight` must be positive, and
2599
+ `overscan` / `minRows` must be non-negative integers. Invalid values throw a
2600
+ descriptive error instead of producing blank windows or a corrupted scroll
2601
+ anchor.
2602
+ - `bindList()` now rejects a source that carries the `arraySignal` brand but
2603
+ has no patch queue with a descriptive error at bind time, instead of failing
2604
+ with a generic `TypeError` on its first render.
2605
+ - Added `wa-dialog.hide-actions` support to `@kerfjs/ui/webawesome.css`, hiding
2606
+ Web Awesome's directly exported `header-actions` shadow part for dialogs that
2607
+ provide their own dismissal affordance.
2608
+ - Fixed `mount()` leaving an element permanently "already mounted" when its
2609
+ first render throws. The first render is now transactional: the original
2610
+ error is rethrown, every binding effect and the dev listener observer
2611
+ acquired so far are released, the element's pre-mount child nodes are
2612
+ restored, and a retry on the same element succeeds.
2613
+ - Fixed `overlay()` construction leaking a live wrapper, mount, dismissal
2614
+ listeners, and concurrent-overlay stack entry when setup failed partway. A
2615
+ malformed `initialFocus` selector now throws a descriptive `overlay()` error
2616
+ before anything is touched, and a throwing first render or `native`
2617
+ `showModal()` / `showPopover()` call rolls back everything already installed
2618
+ (restoring focus) before rethrowing. `popover()` and `tooltip()` roll back the
2619
+ same way when positioning fails; the dialog helpers inherit the guarantee.
2620
+ - Added an opt-in `@kerfjs/ui/document.css` baseline for border-box sizing,
2621
+ token-backed body and link presentation, and a `.kui-app-root` full-height
2622
+ chain for application shells.
2623
+ - Added an inline `Text` span variant for secondary copy inside rows, labels,
2624
+ and table cells, preserving tone, size, and font roles without box geometry.
2625
+ - Reworked every focused UX catalog demo to dogfood Kerf components, Web
2626
+ Awesome surfaces, and semantic HTML without route-local stylesheets, inline
2627
+ styles, styling-only classes, or shared icon/button render helpers. Added
2628
+ catalog-owned specimen viewport constraints and a nonwaivable conformance
2629
+ gate that prevents those styling shortcuts from returning.
2630
+ - Fixed `ToolbarControlGroup` dropdown triggers that were sized to fixed 48px/66px boxes,
2631
+ which clipped popup icons and let compact mixed-control carets overflow in
2632
+ Safari while distorting longer catalog controls.
2633
+ - Added a `TabBar.end` action zone for layouts that need a tab-local adjacent
2634
+ `trailing` action and a separate far-edge action; the tab strip now owns the
2635
+ shrink/scroll geometry while all action regions remain visible.
2636
+ - Moved the UX catalog checkerboard to the preview scroll owner and replaced
2637
+ its four gradients with one repeated SVG tile, so the pattern continues
2638
+ through below-fold content.
2639
+ - Added explicit native `slot` support to every stable single-root
2640
+ `@kerfjs/ui` visual component, including alternate render branches, while
2641
+ keeping multi-root `ResizableRegion` and `CollapsiblePanel` excluded.
2642
+ - Fixed the UX catalog's desktop grid sizing so both the sidebar and component
2643
+ detail can scroll all the way to their final content while narrow layouts
2644
+ retain normal document scrolling.
2645
+ - Fixed single-line `ToolbarText` clipping glyph descenders while retaining its
2646
+ horizontal ellipsis behavior.
2647
+ - Formalized UX catalog demos as components, compositions, or recipes; catalogs
2648
+ now group and order those kinds consistently and label compositions with a
2649
+ visible tag instead of title suffixes.
2650
+ - Removed stale Web Awesome guidance that still advertised the deleted
2651
+ aggregate theme route; focused component routes remain the supported catalog
2652
+ surface.
2653
+ - Aligned Web Awesome Accordion and Details disclosure geometry: plain Details
2654
+ keep a flush body, plain Accordion items use the 8px surface inset throughout,
2655
+ framed Details use 16px on the trigger and 8px on the body, and framed
2656
+ Accordion items use 16px throughout.
2657
+ - Added a first-class `@kerfjs/ui/grid` layout primitive for any positive
2658
+ equal-width column count, with typed gap and flex values and zero-minimum
2659
+ fractional tracks that stay equal when child content has different intrinsic
2660
+ widths.
2661
+ - Made accent and filled-outlined Web Awesome badge variants meet WCAG AA at
2662
+ their compact text size while preserving loud accent fills and outlined
2663
+ borders.
2664
+ - Added independent typed `tone`, `size`, and `font` presentation roles to
2665
+ `@kerfjs/ui/text`, covering quiet/danger copy, compact metadata, and monospace
2666
+ identifiers without global utility classes or appearance-only heading levels.
2667
+ - Made filled Web Awesome badges use a quiet semantic fill with normal text by
2668
+ default, preserving variant tint while meeting WCAG AA for their compact text.
2669
+ - Fixed nested Rows and Lists inheriting inset values for sides that were not
2670
+ selected on the inner layout component.
2671
+ - Fixed migrated `Text` instances in Catalog and passive `ListHeader` labels
2672
+ retaining nested padding or border geometry that offset their visible content.
2673
+ - Added `Row.vAlign="baseline"` for native flex cross-axis baseline alignment;
2674
+ `List.vAlign` remains limited to values supported by vertical main-axis
2675
+ distribution.
2676
+ - Added a first-class `@kerfjs/ui/text` component for native `h1`–`h6` and
2677
+ paragraph semantics with standard transparent-border and content-padding
2678
+ geometry and margin-neutral defaults; it renders `p` when `variant` is omitted,
2679
+ and Kerf UI's headings and prose now use it.
2680
+ - Added the shared physical `Sides` contract to `List` and `Row` text/control
2681
+ insets and to `ListInsetText` / `ListInsetControl`; inset wrappers now default
2682
+ to all four sides, while `ListInsetText.horizontalOnly` remains a deprecated
2683
+ compatibility alias for `sides="rl"`.
2684
+ - Added `ListHeader.inline` for shrink-wrapped section labels that remove the
2685
+ component root's outer margin, border, and padding while preserving title,
2686
+ count, action, and disclosure behavior.
2687
+ - Added a catalog-driven public-component integration validator for
2688
+ `@kerfjs/ui`, including an all-at-once dry-run report across package, build,
2689
+ barrel, CSS, demo, route, signature, and compatibility surfaces.
2690
+ - Added one change-local `@kerfjs/ui` verification command that synchronizes
2691
+ generated projections, runs component/bundle/type coverage, builds the demo,
2692
+ reports exact gzip deltas, and records reviewed budget updates with reasons.
2693
+ - Made every `@kerfjs/ui` Playwright invocation build current catalog source
2694
+ after fast preflights, with a served source digest that rejects stale preview
2695
+ output during focused browser runs.
2696
+ - Added durable Hot Sheet phase timing for active work, local verification,
2697
+ push hooks, CI, and publication, including safe failure aggregation and
2698
+ per-ticket summaries.
2699
+ - Added typed flex participation to `Row`, matching `List`'s boolean, finite
2700
+ keyword, and branded `CssFlex` contract.
2701
+ - Added a first-class horizontal `Row` with typed spacing, physical-axis
2702
+ alignment, and opt-in wrapping; `List` now supports the same alignment
2703
+ vocabulary while retaining its existing defaults.
2704
+ - Refined compact mixed `ToolbarControlGroup` selections to retain standard
2705
+ horizontal padding, remove the internal separator, and raise the selected
2706
+ surface over the outer border; avatar group hover now preserves image fitting.
2707
+ - Moved the comprehensive local `npm run check` gate from pre-commit to
2708
+ pre-push so coherent commit batches pay its cost once; pre-commit now performs
2709
+ only Git's staged whitespace check, and multi-source AI guidance files are
2710
+ excluded from repository-wide Prettier enforcement.
2711
+ - Fixed `create-kerf-component` releases carrying a stale composition-catalog
2712
+ schema by generating the bundled copy from `@kerfjs/ui`'s canonical schema
2713
+ and gating both the root check and interactive release flow against drift.
2714
+ - Added catalog-driven CSS value diagnostics across `eslint-plugin-kerfjs`,
2715
+ `kerf-ui-analyze`, and `kerf-ui-doctor`. Stable `KUI-L013`–`KUI-L017`
2716
+ findings now identify raw or unknown values, wrong-dimension helpers,
2717
+ incomplete expressions, declaration-list escapes, and review-worthy
2718
+ off-scale spacing from first- or third-party component catalogs.
2719
+ - Extended the property-specific `@kerfjs/ui/css-values` contracts: `List.flex`
2720
+ now uses finite keywords or `flex()`, `Skeleton` dimensions use `CssSize` and
2721
+ `CssLength`, and `SelectChoice.color` uses `uiColor()` or `colorVar()`.
2722
+ Removed the unrestricted `style` escape hatches from `ListItem` and
2723
+ `ListActionRow` before the 5.0 stable release; use `className`, public tokens,
2724
+ and cataloged props instead.
2725
+ - Added typed, CSS-free `@kerfjs/ui/css-values` builders and branded complete
2726
+ versus expression length types. `List.gap` now accepts direct spacing-token
2727
+ shorthands or complete `CssLength` values and rejects unrestricted CSS strings.
2728
+ - Added the public recursive `JSXChildren` type from both `kerfjs` and
2729
+ `kerfjs/jsx-runtime`, giving third-party function components a canonical
2730
+ declaration for nullable, signal-backed, and arbitrarily nested readonly
2731
+ child content that matches the runtime.
2732
+ - Added the public recursive `KerfUiContent` type across semantic UI content
2733
+ zones, so nullable conditionals and mutable or readonly nested component
2734
+ arrays compose directly without a `Fragment` while raw strings, numbers, and
2735
+ signals remain rejected outside explicit text positions.
2736
+ - Fixed bottom `Workbench` drawers overshooting and snapping during collapse
2737
+ transitions by anchoring fixed-height content to the shell's stable bottom
2738
+ edge.
2739
+ - Fixed bottom `CollapsiblePanel` drawers overshooting their open position and
2740
+ snapping back by anchoring fixed-height content to the panel's stable bottom
2741
+ edge throughout the transform transition.
2742
+ - Formalized named `SafeHtml` prop slots as explicit `zone.jsx.prop` bindings
2743
+ in the UI composition catalog and generalized `ui-composition` linting beyond
2744
+ Toolbar, including statically visible `children`, cardinality, aliases,
2745
+ namespaces, arrays, fragments, and branches.
2746
+ - Added `ToolbarControlGroup.avatarImage`, painting contained avatar imagery on
2747
+ a lone group or on the pressed highlight when the group has multiple buttons.
2748
+ - Split the AppTab and TabBar catalog routes into focused component specimens,
2749
+ and moved their controlled selection, tabpanel, overflow, add/close, and
2750
+ reorder lifecycle into a separate application-tabs composition demo.
2751
+ - Fixed `wireNavStack` focus ownership across controlled navigation: pushes
2752
+ focus the new top view, pops restore its remembered descendant, and removed
2753
+ targets fall back through `data-nav-focus`, the first enabled control, and
2754
+ the view container.
2755
+ - Fixed compact mixed-content `ToolbarControlGroup` dropdown triggers being
2756
+ forced into an icon-only width, which painted the label across its separator
2757
+ and the Web Awesome caret outside the group.
2758
+ - Made `ListItem` clip label, status, and dormant trailing painting to its
2759
+ rounded row boundary so compact and constrained rows cannot visibly overflow;
2760
+ described rows now grow enough to keep their owned two-line label readable.
2761
+ - Fixed compact toolbar `Select` focus to follow its owning group's pill or
2762
+ rounded geometry and restored consistent spacing between popup icons and labels.
2763
+ - Fixed the compact-toolbar recipe's independent overflow action to use the
2764
+ same full-height pill geometry as its adjacent toolbar controls.
2765
+ - Fixed the catalog footer's `Components` relationship selector to fit its icon
2766
+ and plural label and give popup headings/items consistent border clearance.
2767
+ - Fixed a collapsible `TokenSearchField` inside a rounded
2768
+ `ToolbarControlGroup` retaining its independent pill radius instead of using
2769
+ the group's shared concentric highlight radius.
2770
+ - Updated the header-composition catalog demo's supporting copy to use the
2771
+ horizontal `ListInsetText` geometry, aligning it with the value-table content
2772
+ edge across responsive, RTL, and zoomed layouts.
2773
+ - Updated the `Pane` catalog demo's secondary header copy to use
2774
+ `ListInsetText`, aligning it with the standard pane content gutter at wide and
2775
+ narrow sizes instead of maintaining demo-only padding.
2776
+ - Completed `NavStack` navigation transitions by cross-fading top and bottom
2777
+ chrome alongside content slides, added per-view bottom toolbars with a
2778
+ persistent fallback, and replaced the static focused demo with a working
2779
+ push/pop flow.
2780
+ - Replaced the static compact `SplitView` detail specimen with a controlled,
2781
+ interactive list-to-detail drill-down whose Back action restores the list;
2782
+ the roomy example now demonstrates controlled selection as well.
2783
+ - Documented and demonstrated list-first dialog bodies: use `List` with
2784
+ `bodyInset="none"`, and wrap bare dialog copy in `ListInsetText` so content
2785
+ shares the standard list gutter without double-insetting.
2786
+ - Fixed `@kerfjs/ui`'s collapsible `TokenSearchField` keep-open ownership in
2787
+ WebKit: when `focusout.relatedTarget` is missing during pointer activation of
2788
+ an external `data-token-search-keep-open` surface, the helper now uses the
2789
+ actual pointer target instead of collapsing and removing the target before
2790
+ its click handler runs.
2791
+ - Added a first-class vibrant `pop` semantic color for attractive non-status
2792
+ emphasis, with complete light/dark/increased-contrast token roles and typed
2793
+ StateBanner, ListHeader indicator, and ToolbarControlGroup selected tones.
2794
+ - Fixed canonical `Select` popup animation reversals so an earlier close cannot
2795
+ hide a reopened menu after resizing. Canceled transitions retain the accepted
2796
+ state, and removed controls cannot receive stale completion or deferred focus.
2797
+ - Fixed managed `TokenSearchField` Clear focus before the next input task, so
2798
+ immediate typing stays in the replacement editor instead of triggering page
2799
+ shortcuts; genuine later focus handoffs and selections remain untouched.
2800
+ - Fixed `@kerfjs/ui/tab-scaffold` bottom-tab labels being vertically clipped by
2801
+ flex shrinkage while retaining horizontal ellipsis for long labels.
2802
+ - Made inset selection and hover highlights follow their owning control's pill
2803
+ or rounded shape, with concentric inner radii derived from the full inset.
2804
+ - Fixed animated `ResizableRegion` overlays so remembered desktop dimensions
2805
+ cannot make their content overflow the responsive panel cap on narrow screens.
2806
+ - Added configuration-first application-panel policies across `ResizableRegion`,
2807
+ `Workbench`, and `CollapsiblePanel`: separator visibility, instant-track
2808
+ collapse with optional composited content motion, popup-safe overflow,
2809
+ inline/overlay/hidden responsive presentations, and safe-area restore-control
2810
+ placement. `wireResizableRegions` now suppresses motion during pointer drags
2811
+ and ignores unavailable regions; `wireSidebar` supports hidden compact
2812
+ replacements and exclusive overlays.
2813
+ - Added typed `TabBar` allocation/presentation/action-placement and `AppTab`
2814
+ presentation/size/label-width variants for segmented inspector strips,
2815
+ compact drawer tabs, icon-only accessible tabs, and truncating labels.
2816
+ - Added typed `ToolbarControlGroup` size, density, content anatomy, selected
2817
+ chrome/tone, nested-dropdown, and avatar scrim variants.
2818
+ - Added typed `Select` form, borderless-toolbar, intrinsic-navigation, compact,
2819
+ icon-only-selected, truncation, and composed focus-ring variants.
2820
+ - Added `DialogSurface` and `PopupSurface` composition APIs for standard dialog
2821
+ sizes/presentations, independent body/footer insets, and list-compatible popup
2822
+ menu insets without consumer `::part()` overrides.
2823
+ - **Breaking (`@kerfjs/ui`):** removed `PanelHeader` and its subpath/CSS export.
2824
+ Compose page, panel, and dialog headings directly with `Toolbar`, a direct
2825
+ extra-large `ToolbarText`, and optional `ToolbarControlGroup` icon/action zones;
2826
+ keep supporting copy as app-owned content below the toolbar.
2827
+ - Fixed controlled TokenSearchField Select All + Backspace/Delete collapsing the
2828
+ editor: managed deletion keeps the adopted open signal and restores replacement
2829
+ focus before another keystroke, without a stale animation-frame caret reset.
2830
+ The adoption demo now persists both edited text and remaining tokens.
2831
+ - Fixed `Select` controls using only `ariaLabel` being unnamed to assistive
2832
+ technology. Ordinary and custom selected content retain their geometry while
2833
+ the actual shadow combobox receives its accessible name.
2834
+ - Added first-class `Select` hint text below interactive and loading-placeholder
2835
+ controls while keeping empty-value `placeholderText` semantically distinct.
2836
+
2837
+ - Changed the Web Awesome Dialog theme to use 8px body padding and 16px footer
2838
+ padding, independently of the component's shared `--spacing` value.
2839
+
2840
+ - Fixed `kerf-ui-doctor` so its isolated Kerf ESLint pass preserves applicable
2841
+ consumer core rules and suppression reporting options. Playwright's required
2842
+ `no-empty-pattern` fixture suppression no longer becomes a false unused
2843
+ directive while consumer plugin rules remain outside the doctor boundary.
2844
+
2845
+ - Cataloged `SplitView` and its documented
2846
+ `--kui-split-view-list-width` override so `kerf-ui-doctor --full` accepts the
2847
+ public token in downstream application stylesheets.
2848
+
2849
+ - Added the first-class `List` vertical-layout component with gap, flex, scroll,
2850
+ and multi-edge divider options; `Toolbar` now uses the same typed
2851
+ `dividerSides` contract instead of a boolean divider.
2852
+
2853
+ - Added an optional tone-tinted pill badge beside `StateBanner` titles, including
2854
+ loading skeleton behavior and per-instance badge color overrides.
2855
+
2856
+ - Fixed pending `wireTabBars` and `wireTokenSearchFields` controlled-render
2857
+ callbacks moving focus after their owning wiring had been disposed.
2858
+
2859
+ - Changed the default `ListItem` leading icon visual from 24px to a root-scaled
2860
+ 18px while retaining the row's 44px minimum target and first-line alignment.
2861
+
2862
+ - Fixed managed `TokenSearchField` clear losing focus or collapsing when an
2863
+ application replaces its controlled editor; continued typing now works without
2864
+ an application reopen callback.
2865
+
2866
+ - Fixed `@kerfjs/ui` automatic TabBar keyboard activation losing focus when a
2867
+ controlled selection replaces the strip; navigation restores the same logical tab.
2868
+
2869
+ - Updated the published setup runtime to patched `minimatch` 9.0.9 and `yaml`
2870
+ 2.9.1 releases, resolving the known regular-expression denial-of-service and
2871
+ deeply nested YAML denial-of-service advisories without narrowing Kerf's
2872
+ supported Node.js range.
2873
+ - Fixed `kerf-ui-doctor --full` so its isolated ESLint stage shares the same
2874
+ generated-directory exclusions as TypeScript, static analysis, and cache
2875
+ hashing; populated `dist`, `coverage`, dependency, cache, evidence, and nested
2876
+ worktree directories no longer produce application diagnostics.
2877
+ - Changed `@kerfjs/ui` component-library design templates to compose their
2878
+ individual variant SVGs through HTML and `domotion capture
2879
+ --flatten-nested-svg`, eliminating the hand-built nested-SVG compositor and
2880
+ making top-level template sheets reliable in Sketch.
2881
+ - Added a typed `shape` option to `SunkenPanel`: `rounded` remains the default,
2882
+ while `square` produces a lowered surface with `border-radius: 0` for flush or
2883
+ edge-to-edge application areas. Both shapes now appear in the UX catalog.
2884
+ - Made the Catalog geometry overlay derive both margin bands and border
2885
+ edges/radii from each live specimen's computed CSS. Public example helpers now
2886
+ mark their generated labels and notes for automatic exclusion, and stylesheet,
2887
+ theme, DOM, and resize changes refresh the overlay without duplicated demo
2888
+ measurements.
2889
+ - Updated the `@kerfjs/ui` SVG design-template generator to `domotion-svg`
2890
+ 0.30.1 and enabled `--flatten-nested-svg`, so inline component icons are
2891
+ emitted as Sketch-compatible groups without changing their browser rendering.
2892
+ The offline template gate now rejects variant captures that reintroduce nested
2893
+ `<svg>` elements.
2894
+ - Fixed `kerf-ui-doctor` and `kerf-ui-analyze` recursive discovery so nested
2895
+ `.claude/worktrees` checkouts are excluded from source diagnostics, doctor
2896
+ cache inputs, TypeScript, and ESLint.
2897
+ - Added `npx kerfjs setup` and the `kerfjs/setup` automation API for safe,
2898
+ AI-first initialization and migration of core and UI projects. The command
2899
+ provides bounded dry-run diffs, explicit per-conflict keep/Kerf choices,
2900
+ package-scoped hash-backed upgrades, monorepo selection, transactional
2901
+ rollback, shipped guidance, strict TypeScript/ESLint, and UI catalog/profile
2902
+ and doctor discovery. Empty application component metadata now emits a valid
2903
+ empty v2 catalog. Existing JSONC TypeScript configuration is structurally
2904
+ merged without discarding comments, trailing commas, authored fields, or line
2905
+ endings; malformed roots and compiler-option containers require an explicit
2906
+ keep/Kerf decision. Workspace selection now evaluates ordered globstar,
2907
+ brace, exclusion, and re-inclusion patterns deterministically across npm,
2908
+ Yarn, and pnpm declarations, rejects path/symlink/name ambiguity, and uses
2909
+ manager-correct offline commands with explicit Yarn Classic/Berry detection
2910
+ and network-disabled Berry installs.
2911
+ - Added `@kerfjs/ui/doctor` and the `kerf-ui-doctor` command: a versioned, redacted repair-loop report that merges catalog/profile validation, TypeScript, Kerf UI ESLint, static analysis, and opt-in browser evaluation with changed/full modes, monorepo selection, reasoned suppressions, caching, and deterministic exits.
2912
+ - Added the public Playwright-backed `kerf-ui-evaluate` CLI and `@kerfjs/ui/evaluator` Node API. It resolves application profiles and composition catalogs, exercises wide/intermediate/narrow/200%-zoom, light/dark, and reduced-motion contexts across Chromium, Firefox, and WebKit, and emits versioned repair-oriented `KUI-B###` diagnostics plus focused DOM/style evidence and hashed screenshots. Subjective visual quality remains an explicitly separate unrecorded reviewer rubric.
2913
+ - Added `kerf-ui-analyze`, a profile- and catalog-aware static evaluator for Kerf UI integrations. It resolves directory policy per source, follows project-local CSS import graphs without cross-package class leakage, and evaluates shared stylesheets against every consuming source policy before deduplicating findings. Stable portable text, JSON, or SARIF diagnostics cover private selectors, unknown tokens, competing geometry/scroll owners, repeated insets, forced dimensions, off-scale spacing, and dynamic-class review, with exact scoped profile exceptions, a public report schema, and configurable CI review failure.
2914
+ - Added catalog/profile-aware `recommended-ui` and `strict-ui` flat presets to `eslint-plugin-kerfjs`. Toolbar zone acceptance/cardinality and valid wiring imports come from the shipped catalogs; intrinsic or unknown zone children, root/subpath/namespace wiring, and the non-colliding `KUI-L090` load diagnostic are covered by real packed downstream installs on every supported ESLint major.
2915
+ - **Breaking (`@kerfjs/ui` TypeScript declarations):** strengthened invalid-integration contracts for ListHeader modes, Select naming and literal choice identity, SegmentedControl/TabScaffold literal identity, collapsible TokenSearchField props, protected editor metadata, PanelHeader summary ids, ToolbarText line caps, and token-removal callbacks. Added named public unions for previously anonymous finite variants plus source and packed-tarball positive/negative compilation gates. See `ui/docs/type-contracts.md` for the compatibility review and dynamic-data widening syntax.
2916
+ - `create-kerf-component` now scaffolds explicit `kerf.components.json` AI metadata and a deterministic `kerf-component-catalog` generator/checker. Generated v2 entries carry package identity, purpose, verified named exports, composition and geometry ownership, tokens, accessibility, and source links; publishing rejects missing author decisions, schema-invalid source/output fields, deleted sources, renamed exports, duplicate ids, or output drift, including multi-package workspaces. Syntax-aware TypeScript/TSX export discovery prevents JSX text, nested scopes, comments, and literals from impersonating public exports.
2917
+ - Added a versioned application UI profile for AI tools and static evaluators. Shipped package defaults, schema, TypeScript types, Node discovery/merge/validation APIs, and a workspace example now make catalog locations, preferred components/recipes, theme/density policy, semantic token overrides, responsive/layout conventions, and narrow source-located exceptions explicit. Composition-only generated consumer catalogs load without a fabricated v1 selection artifact, while Kerf retains its required v1 selection catalog. Deterministic package → workspace → parent-to-child directory precedence validates every raw layer before merge, attributes resolved diagnostics through field provenance, and rejects stale catalogs, unknown components/tokens/rules, conflicts, malformed value shapes, and broad exemptions.
2918
+ - Fixed `CatalogExampleStack` accessible labels: the helper now renders a semantic `section`, so a supplied `label` exposes the documented named region to assistive technology while an unlabeled stack remains an ordinary grouping.
2919
+ - Added first-class `Pane` and `SunkenPanel` primitives to `@kerfjs/ui`. `Pane` standardizes semantic header/content/footer columns, explicit logical-edge separators, and one content scroll owner; `SunkenPanel` supplies one lowered surface with an 8px inset and vertical rhythm. The Catalog shell now dogfoods `Pane`, and both components ship focused demos, catalog metadata, documentation, and three-engine browser coverage.
2920
+ - Added the package-qualified component catalog v2 alongside the compatible v1 artifact. Its schema and generated metadata formalize child zones, cardinality, exclusivity, wiring, state, responsive behavior, layout and accessibility boundaries, stable validation diagnostics, provenance, and consumer extension catalogs, so AI tools can join Kerf and application components without guessing composition contracts.
2921
+ - Added an AST-based Catalog demo conformance gate. It checks every first-party demo for public helper usage, package imports, focused specimen structure, geometry-overlay metadata, and reviewed schema-checked exceptions, with adversarial fixtures and authoring guidance that makes the same contract available to downstream AI tools.
2922
+ - Made `ui/docs/catalog.md` the authoritative Catalog demo authoring contract, covering focused versus composition previews, public row/group nesting, exact specimen selection, conditional geometry overlays, skip-marker behavior, metadata ownership, and an explicit overlay legend. A shipped `ai/catalog-authoring.json` discovery artifact now routes AI tools to that contract and exact signatures, with schema, link-integrity, and browser-consumer fixture coverage.
2923
+ - Extended `CatalogExample` and `CatalogExampleStack` with typed, runtime-filtered `rootAttributes` for catalog-authoring `data-*` metadata such as `data-demo` and `data-catalog-geometry-overlay-skip`, while preserving helper-owned structural and alignment markers. The UX catalog now composes its example stacks through these public helpers instead of copying private `kui-catalog-*` markup.
2924
+ - Added `revealCatalogEntry` and opt-in `wireCatalog({ revealSelection })` support to the exported Catalog tool. Sidebar or related-entry selection can now reveal the matching row after the controlled render settles, using a desktop-safe media guard, exact id matching, configurable scroll alignment/behavior, focus-preserving scrolling, and cancellation of stale rapid selections; the Kerf UX demo now uses the public behavior.
2925
+ - Added a reusable consumer component-catalog extension schema and checked app-component example. Downstream packages can now publish the same selection facts and margin/border/padding ownership vocabulary as Kerf, and the README, component contract, Catalog guide, `llms.txt`, and AI skill explain how to combine package-qualified app entries with Kerf's shipped catalog for alignment decisions.
2926
+ - Added an opt-in geometry inspector to the exported `@kerfjs/ui/catalog` tool. `geometryOverlay` plus `wireCatalogGeometryOverlay` now marks transparent component bounds with a dashed outline and positive intrinsic margins with devtools-style bands, excludes example labels/alignment scaffolding, stays synchronized across preview changes, and replaces the Kerf UX demo's private implementation.
2927
+ - Added machine-readable margin, border, and padding ownership to every visual entry in the `@kerfjs/ui` component catalog. The additive schema distinguishes self-, parent-, child-, conditional-, and unowned geometry, and enforces complete metadata plus explanatory notes for conditional cases.
2928
+ - Refreshed the standalone reactivity demo lockfile to Vite 6.4.3, PostCSS 8.5.28, and nanoid 3.3.19, clearing its development-toolchain audit advisories.
2929
+ - Overrode the development toolchain's transitive esbuild dependency to 0.28.2, resolving GHSA-g7r4-m6w7-qqqr while current tsup still constrains its declared range to 0.27.x.
2930
+ - Added repository-wide Prettier formatting for TypeScript, JavaScript, Astro, shell, CSS, HTML, Markdown, YAML, and JSON source and structured-content files. Root and `@kerfjs/ui` lint gates now reject formatting drift, while generated, binary, and parser-incompatible fixtures remain explicitly excluded.
2931
+ - Added reusable sidebar tags to `@kerfjs/ui` Catalog entries and marked the 15 Web Awesome components superseded by preferred Kerf patterns or reserved for exceptional cases as `Discouraged` in the UX catalog. The tag is deterministically projected from the canonical recommendation metadata; Popup remains an available conditional positioning primitive.
2932
+ - Aligned Web Awesome Accordion, Card, Details, Callout, and Include surfaces with Kerf content-item geometry: each complete surface now has an overridable 8px logical inline margin and 8px inner padding, Accordion keeps connected items under one group margin, and Card's header/body/footer share the full inset. Tab Panel intentionally retains the roomier 16px container inset.
2933
+ - Fixed `@kerfjs/ui` Web Awesome Slider geometry: its complete interactive region now receives the shared 8px logical inline outer inset without shifting the already-aligned label.
2934
+ - Styled `@kerfjs/ui` Web Awesome OTP Input like a bordered text field: its label now uses the shared uppercase xs/650 field-label treatment, and both label and hint align at the 9px border-plus-padding inset.
2935
+ - Aligned `@kerfjs/ui` Web Awesome Known Date's Month/Day/Year captions and bordered text-like field hints with their values using the shared 9px border-plus-padding inline inset.
2936
+ - Fixed `@kerfjs/ui` Web Awesome Color Picker geometry: its unbordered trigger now receives the shared 8px inline outer inset, aligning it with Kerf content-item spacing.
2937
+ - Fixed `@kerfjs/ui` Web Awesome Checkbox Group and Radio Group option geometry: each group's unbordered option region now receives the shared 8px inline outer inset, aligning it with Kerf content-item spacing without padding the individual controls.
2938
+ - Aligned the remaining bordered/padded Web Awesome chrome in `@kerfjs/ui/webawesome.css` to explicit Kerf spacing tiers: `--kui-wa-control-inset` (8px) drives tabs, inset tree selection, tags, and dropdown items; `--kui-wa-surface-margin` / `--kui-wa-surface-inset` drive bordered surface geometry; and `--kui-wa-container-inset` (16px) retains roomier Tab Panel content. Buttons already inherit the 8px form-control inset; compact badges, unframed Breadcrumb, and slotted Scroller item chrome deliberately retain their native geometry. The tiers are overridable by scope and pinned by three-engine computed-style coverage plus light/dark wide and narrow visual QA.
2939
+ - Tightened the `@kerfjs/ui` Web Awesome theme's form fields to the Kerf content-item inset — a 1px border with 8px inside it (`--wa-form-control-border-width` / `--wa-form-control-padding-block` / `--wa-form-control-padding-inline` now follow `--kui-layout-item-border-width` / `--kui-layout-item-padding`), replacing Web Awesome's larger default pad, so fields land at the standard ~40px height and 9px value inset. Each field's top label is now inset by that same border + padding (9px) so it aligns with the value inside the field, and is styled exactly like a `ListHeader` label — uppercase, xs, weight 650, quiet foreground (`::part(form-control-label)` across Input/Number Input/Textarea/Select/Checkbox Group/Radio Group/Color Picker/Known Date/Time Input, plus the Slider's `::part(label)`). Inline Checkbox/Switch labels keep their sentence case.
2940
+ - Added overflow controls to `@kerfjs/ui`'s `ToolbarText`: `wrap` (flow onto multiple lines instead of a single line), `ellipsis` (show the trailing … at the truncation, or hard-clip when false), and `maxLines` (cap wrapped text to N lines, ellipsizing past it). The default is unchanged — one line, ellipsized when it does not fit. `maxLines` takes effect only with `wrap`. Driven by `data-wrap` / `data-ellipsis` / `data-max-lines` attributes plus a `--kui-toolbar-text-max-lines` var; no new public classes. The UX catalog gains ellipsis/wrap/capped examples.
2941
+ - Fixed a `@kerfjs/ui` `TokenSearchField` bug where selecting all content and pressing Delete (or Backspace) left a stray newline in the field. A `contenteditable` host inserts a bogus `<br>` when emptied that way in every engine — it renders as a newline and `readTokenSearchField` read it back as a space. `wireTokenSearchFields` now strips that line break after any delete input and, when the field is otherwise empty, restores the canonical empty text span and places the caret in it so typing resumes cleanly. Also clears any leftover chips in the select-all case. Regression-tested in unit (happy-dom) and across all three browser engines.
2942
+ - Hardened that full `TokenSearchField` deletion for platform-specific selection
2943
+ ranges whose endpoints sit inside the first and last text spans instead of at
2944
+ the editor boundary—or whose cloned Linux range omits an atomic chip entirely.
2945
+ Full logical text-and-token selection is recognized from its value, while an
2946
+ explicit Ctrl/Cmd+A intent survives only until the next delete and is
2947
+ consumed by that delete even when the browser omits `beforeinput`, and is
2948
+ retained across a controlled editor replacement before or after
2949
+ `beforeinput`. It is captured before propagation can be stopped and
2950
+ invalidated by selection-moving keys, pointer input, blur, or another edit.
2951
+ The explicit shortcut-to-delete transition is handled deterministically:
2952
+ the helper prevents the unreliable mixed-contenteditable native mutation,
2953
+ canonicalizes the empty editor, and emits the corresponding bubbling input
2954
+ event so controlled application state clears before it can restore a chip.
2955
+ A browser can no longer preserve a controlled chip merely because its range
2956
+ shape or native deletion timing differs.
2957
+ - Added a `horizontalOnly` prop to `@kerfjs/ui`'s `ListInsetText`. When true it keeps the horizontal geometry (8px inline margin, 1px left/right border, 8px left/right padding — so the text edge still lands at the 17px inset) but drops the vertical margin, border, and padding, for tight text layout that still aligns with bordered items. It applies a `kui-list-inset-text--horizontal` modifier class; the default (vertical box space intact) is unchanged. The UX catalog gains a horizontal-only example.
2958
+ - Fixed a WCAG AA color-contrast failure on `@kerfjs/ui`'s selected list rows. The selected `ListItem` and `ListActionRow` used the brand accent (`brand-on-quiet`, `#1e6ef4`) for their text, which resolved to only **3.77:1** over the selected `brand-fill-normal` background (`#d6ecff`) — below the 4.5:1 minimum for normal text (flagged by axe downstream). Both now use the normal neutral foreground over the brand-tinted fill, so selection is carried by the fill and border while the text stays readable in light and dark themes. Computed-ratio browser tests pin both selected rows at ≥4.5:1 in both themes across all three engines.
2959
+ - Fixed the same brand-accent contrast failure on `@kerfjs/ui`'s info `StateBanner` tone and `Select`'s current option, where the blue is a semantic (not a selection cue), so the text stays blue rather than going neutral: a new darker `--kui-color-brand-on-fill` token (`#1a5dcf` light; the compliant `#8acbff` in dark) replaces `brand-on-quiet` for brand text placed directly on a brand fill. The info banner (was 4.15:1) now clears ~5.4:1 and the current Select option (was 3.77:1) ~4.9:1. Computed-ratio browser assertions guard both.
2960
+ - Completed the `@kerfjs/ui` `StateBanner` contrast pass: the `success` (was 4.05:1) and `warning` (was 4.39:1) tones failed WCAG AA the same way via their own `*-on-quiet` tokens over the tinted banner fills. New darker `--kui-color-success-on-fill` (`#00792c`) and `--kui-color-warning-on-fill` (`#8f5e00`) tokens (each keeping its semantic hue, dark values unchanged and already compliant) now back the success/warning banner text, clearing ~5.0:1 and ~5.3:1. Every `StateBanner` tone now clears 4.5:1 in both themes, guarded by an all-tone computed-ratio browser assertion.
2961
+ - Added two structure primitives to `@kerfjs/ui` for aligning bare content inside a `.kui-content` list: `ListInsetControl` (`@kerfjs/ui/list-inset-control` + `.css`) wraps a control that owns its own border and padding but no outer margin (a search input, a `SegmentedControl`) with the standard 8px inline margin plus a stretch flex row and an 8px gap, so it lines up with the bordered items around it without double-insetting; `ListInsetText` (`@kerfjs/ui/list-inset-text` + `.css`) gives a bare string or inline content the content-item geometry (8px inline margin, 1px transparent border, 8px padding) so its text edge lands at the same 17px inset as bordered rows. Both are additive, take an optional `className`, and appear in the UX catalog and the component-selection guidance.
9
2962
  - `@kerfjs/ui`'s `wireTokenSearchFields` `onEdit` callback now also receives the originating `InputEvent` (`onEdit({ id, editor, event })`), so a consumer can gate token-commit behavior on `event.inputType` / `event.data` (e.g. commit a chip only on whitespace-terminated input) and drop its own `input` listener entirely — completing the goal `onEdit` was added for. Additive; existing `{ id, editor }` destructuring is unaffected.
10
2963
  - Added a CI-only visual-drift gate for the `@kerfjs/ui` SVG design templates (`check:design-templates:drift`): it re-renders every template in a browser and fails if any regenerated SVG differs from the committed one (normalizing run-to-run noise — XML comments and auto-minted ids/font names). It closes the gap the offline `check:design-templates` cannot cover and runs in CI's browser-capable job, not the offline pre-commit `check`.
11
2964
  - Added `FloatingToolbar` to `@kerfjs/ui` (`@kerfjs/ui/floating-toolbar` + `.css`): a transparent, forced-dark toolbar that floats over the content of its nearest positioned ancestor — a drawer-restore / floating-controls pattern — without covering dialogs or overlays (it is not top-layer). It exposes `role="toolbar"` with a required `label`, floats to a customizable `position` (`bottom-end` default, plus the other corners/edges), and is inset by `--kui-floating-toolbar-inset` (default 8px past a top toolbar's own inset). The app owns the controls and their visibility. Includes a UX-catalog demo with a show/hide toggle that auto-hides on leaving the demo.
@@ -137,9 +3090,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
137
3090
  - Added the lockstep `@kerfjs/ui` package: accessible toolbar, menu, tab, header, resize, select, and feedback primitives; semantic CSS tokens and browser component subpaths that automatically include only reachable component styles; CSS-free root/SSR entries and an optional complete stylesheet; opt-in Web Awesome registration; AI-oriented docs; a production-backed UX catalog; bundle/unit/three-engine browser gates; and a least-privilege release workflow.
138
3091
  - The virtual-list demo animation opens on the full app again (header, the "N in the DOM" badge, and the list) before the scroll; the list now scrolls inside its own box while the header stays put (previously the whole frame was a full-bleed list strip), holds at row 0 before gliding instead of starting a few rows down, and the loop stays in phase on every pass. Captured with domotion-svg 0.28.2.
139
3092
 
140
- ## [4.4.1] - 2026-08-26
141
-
3093
+ - @kerfjs/ui panel toolbars now place groups in leading, center, and trailing zones; relocateOnCollapse keeps chosen groups available when a panel closes.
142
3094
 
3095
+ ## [4.4.1] - 2026-08-26
143
3096
 
144
3097
  - Overhauled the README landing page: new one-line tagline, npm/size/license/TypeScript-types badges, a hoisted "Quick start" (install + `tsconfig`) right under the hook, and a jump nav (Quick start · Why kerf · Quick tour · Docs). The counter example now shows `delegate()` wiring the click handler.
145
3098
  - Reworked the homepage hero to lead with the value proposition ("Reactive UI that touches only the bytes that changed"), with "Introducing Kerf" demoted to an eyebrow, a right-sized logo, tighter vertical spacing, and "Get started" as the single filled primary action ("View examples" now a secondary/outline button).
@@ -148,7 +3101,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
148
3101
  - Rewrote the site's docs pages as hand-authored consumer content (cleaner headings, no internal section numbers) rather than verbatim copies of the internal design docs.
149
3102
  - Renamed the migration guides' "Side-by-side code" heading to "Section by section" (the sections stack code blocks rather than showing true columns), across all framework pages.
150
3103
 
151
-
152
3104
  - The getting-started and Markdown-editor demo animations now open on a non-blank frame — real code and a rendered heading are visible immediately instead of an empty pane.
153
3105
  - Added a horizontal-scroll shadow affordance to wide tables so off-screen columns are discoverable on narrow viewports.
154
3106
  - Shortened the longest demo alt text on the router and virtual-list pages for more concise screen-reader output.
@@ -156,29 +3108,23 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
156
3108
 
157
3109
  ## [4.4.0] - 2026-08-23
158
3110
 
159
-
160
-
161
3111
  - Reworked the router example app to run inside a fake browser window — traffic-light chrome, working Back/Forward buttons wired to `router.back()`/`forward()` via one delegated listener, and a live address bar bound to `router.route` that updates as you navigate — making the URL-driven, no-reload story clearer.
162
3112
 
163
3113
  - **New `kerfjs/router` subpath — a client-side router (the "postcard router").** `createRouter({ routes, mode?, base?, interceptLinks? })` returns a handle over three things kerf already has: a reactive `route` signal (`{ path, params, query, hash }`), `delegate()`-based `<a href>` link interception, and a keyed **outlet** — `router.outlet()` renders the matched route in a `data-key`ed wrapper, so kerf's keyed morph **replaces the page wholesale on a route change** (fresh DOM) and **reconciles in place on a same-route param change** (preserving scroll / focus). Route patterns are static, `:param`, a trailing `*rest` wildcard, and `*` catch-all; the handle also gives `navigate(path, { replace?, state? })`, `back()`/`forward()`, `match(pattern)` / `activeClass(pattern, className)` reactive active-link helpers, hash **or** history mode, an optional base path, and `dispose()`. Link interception is automatic (same-origin, left-click, no modifier/`target`/`download`, opt out per-link with `data-router-ignore` / `rel="external"` or globally with `interceptLinks: false`). **Deliberately scoped** — no nested layouts, data loaders, lazy routes, guards, or SSR matching; compose those with kerf primitives (`resource` for loading, an `effect` on `route` for guards). The kerf **core stays router-free** — this is opt-in and tree-shakeable, adding nothing to the main barrel until imported, and docs/1's "Not a router" is about the runtime. See [`docs/20-router.md`](docs/20-router.md).
164
3114
 
165
3115
  ## [4.3.0] - 2026-08-22
166
3116
 
167
-
168
-
169
3117
  - KF-529: refresh README for the 4.3 cycle (prep-major-release) (`909c82a`)
170
3118
  - KF-530: extract promise-dialog helpers into overlay-dialogs.ts (`5d4ac38`)
171
3119
  - KF-528: sync llms.txt with docs/19 + 4.3 features (`1d9c004`)
172
3120
 
173
3121
  - **`kerfjs/overlay` gains opt-in native top-layer backing (`native: true`).** Every overlay surface (`overlay`, `confirm`, `prompt`, `form`, `choice`, `popover`, `tooltip`) now takes `native?: boolean` (default `false`). When `true` and the engine supports it, a **modal** surface (`trap: true`) is hosted in a `<dialog>` opened with `.showModal()` — real document inerting (pointer + focus + AT) and guaranteed stacking above any `z-index` — and a **non-modal** surface (`trap: false`) uses the **Popover API** (`[popover]` + `showPopover()`). Feature-detected (`HTMLDialogElement.prototype.showModal`, `HTMLElement.prototype.showPopover`), falling back to today's plain `<div>` where unsupported, so `native: true` is always safe to pass. The `render` slot + promise API are unchanged — kerf just hosts your markup in a `<dialog>` / `[popover]`. **Opt-in on purpose:** the native elements carry UA default styles (a `::backdrop`, centering, border, padding) that kerf does **not** reset (a reset would violate the zero-CSS contract) — style the element and its `::backdrop` via `className` (`.kerf-overlay::backdrop { … }`, the stable contract); and `container` becomes a visual no-op in native mode (the top layer ignores DOM position). See [`docs/19-native-overlay-backing.md`](docs/19-native-overlay-backing.md).
174
- - **`bindList` virtualization gains a `content-visibility` mode.** `virtualize: { rowHeight, mode: 'content-visibility' }` is a second virtualization strategy alongside the default `mode: 'window'` (today's JS windowing). It keeps **every** row in the DOM and sets `content-visibility: auto` + `contain-intrinsic-size: 0 <rowHeight>px` on each row, so a supporting engine (Chromium, Safari 18) skips the *layout/paint* of off-screen rows while **all rows stay findable** — find-in-page (Cmd/Ctrl+F), the accessibility tree, and anchor links / `scrollIntoView` all work on any row (the exact guarantee `mode: 'window'` can't give, since it removes off-window rows from the DOM). The `mode` choice is the app's and it's about list size: pick `'content-visibility'` for medium lists where findability beats the node ceiling, keep `'window'` for very large (100k-row) lists. In this mode `rowHeight` is only the `contain-intrinsic-size` placeholder (no windowing math), `setHeight` / `observeRowHeights` are no-ops (the browser owns measurement), `minRows` is ignored (all rows already render), and no scroll listener / `ResizeObserver` is installed — while `handle.container` / `containerClass` / `containerId` still work. There is deliberately **no feature detection**: on an engine without `content-visibility` the CSS is inert, so all rows still render (correct, still findable) — only the off-screen-skip optimization is absent. See [`docs/17-list-virtualization.md`](docs/17-list-virtualization.md) §17.11.
3122
+ - **`bindList` virtualization gains a `content-visibility` mode.** `virtualize: { rowHeight, mode: 'content-visibility' }` is a second virtualization strategy alongside the default `mode: 'window'` (today's JS windowing). It keeps **every** row in the DOM and sets `content-visibility: auto` + `contain-intrinsic-size: 0 <rowHeight>px` on each row, so a supporting engine (Chromium, Safari 18) skips the _layout/paint_ of off-screen rows while **all rows stay findable** — find-in-page (Cmd/Ctrl+F), the accessibility tree, and anchor links / `scrollIntoView` all work on any row (the exact guarantee `mode: 'window'` can't give, since it removes off-window rows from the DOM). The `mode` choice is the app's and it's about list size: pick `'content-visibility'` for medium lists where findability beats the node ceiling, keep `'window'` for very large (100k-row) lists. In this mode `rowHeight` is only the `contain-intrinsic-size` placeholder (no windowing math), `setHeight` / `observeRowHeights` are no-ops (the browser owns measurement), `minRows` is ignored (all rows already render), and no scroll listener / `ResizeObserver` is installed — while `handle.container` / `containerClass` / `containerId` still work. There is deliberately **no feature detection**: on an engine without `content-visibility` the CSS is inert, so all rows still render (correct, still findable) — only the off-screen-skip optimization is absent. See [`docs/17-list-virtualization.md`](docs/17-list-virtualization.md) §17.11.
175
3123
  - **Docs: `bindList` virtualization findability/a11y tradeoff is now a first-class caveat.** Off-window rows are removed from the DOM (not just hidden), so with `virtualize` set, find-in-page (Cmd/Ctrl+F), screen readers / the accessibility tree, and anchor links / `scrollIntoView` reach only the visible window. New `docs/17-list-virtualization.md` §17.10 spells out the consequences and the guidance (don't virtualize, or use `minRows` above the list length, when full findability matters more than the DOM node ceiling), and the `bindList` JSDoc + `docs/8-api-reference.md` §8.11 carry the same note. Behavior unchanged — documentation only.
176
3124
  - **State-preserving row moves via `moveBefore()` (transparent optimization).** When a keyed list reorders — `each()` (snapshot and granular paths), `bindList`, and `morph()`'s keyed / positional / list-marker moves — kerf now relocates an already-connected row with `Node.prototype.moveBefore()` where the engine supports it (Chromium 133+, spreading to other engines), falling back to `insertBefore()` everywhere else. `moveBefore()` is an atomic move: the node is never disconnected, so a moved row keeps its focus, text selection, `<iframe>` document state, playing media, running CSS transitions/animations, and open `popover`/`dialog` state across the reorder — richer state than the existing focus snapshot in the reconciler could ever restore, and it needs no snapshot at all where it runs. No API change and no behavior change on engines without `moveBefore()`; the focus-preservation snapshot stays in place for them. Fresh (not-yet-connected) rows still use `insertBefore()` — only genuine moves of connected rows take the new path. See [`docs/18-state-preserving-moves.md`](docs/18-state-preserving-moves.md).
177
3125
 
178
3126
  ## [4.2.0] - 2026-08-20
179
3127
 
180
-
181
-
182
3128
  - Added a **Virtual list** example app — a 10,000-row virtualized list showcasing the companion subpaths together: `kerfjs/list` viewport virtualization (only a screenful in the DOM), `kerfjs/timing` debounced search, and `kerfjs/overlay` confirm-to-delete with a toast. Includes a live "in the DOM" counter that stays flat as you scroll all 10,000 rows.
183
3129
  - Expanded the README with a companion-subpaths spotlight covering `list`, `overlay`, `async`, `scope`, `timing`, `remount`, `attach`, and `actions`, with `bindList` fixed and measured-height virtualization examples.
184
3130
  - Corrected the complete-apps index to accurately describe the eight standalone showcase apps and note that the cart and counter-store apps live in the migration guides.
@@ -192,86 +3138,70 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
192
3138
  - **New `kerfjs/remount` subpath** — `remountOn(parent, key, render)`, the opposite of kerf's morph-by-default: **replace** a subtree wholesale when `key` changes instead of morphing it. Names the hand-rolled `data-key={`gen-${n}`}` + `data-morph-skip` counter trick, for library-owned subtrees (a highlighted diff, a chart, an editor) that must tear down and re-initialize on fresh DOM. `key` is a signal or a thunk `() => K`; an unchanged key (including a thunk whose inputs moved but whose value stayed equal) leaves the subtree alone, so per-row reactivity inside `render` still updates in place. An optional `onMount(root)` callback runs after each (re)mount with the live subtree — the place to bind an imperative widget (`kerfjs/attach`) to the fresh DOM; returning `attach`'s disposer from it makes teardown synchronous. `remountOn` owns `parent`'s children and returns a disposer. Optional and tree-shakeable.
193
3139
  - **New `kerfjs/timing` subpath** — the `let timer; clearTimeout(timer); timer = setTimeout(…)` pattern every app hand-rolls, blessed with disposer-shaped ergonomics. `debounce(fn, ms)` is trailing-edge (runs once `ms` after calls stop, latest args); `throttle(fn, ms)` is leading-plus-trailing (fires immediately, then at most once per `ms`, collapsing a burst to one trailing call). Both return a callable with `cancel()` / `flush()`. `debouncedSignal(source, ms)` is a read-only signal that trails `source` by `ms` so it composes inside the reactive graph (`computed`/`effect`/`mount`) instead of beside it. `debounce`/`throttle` are dependency-free; `debouncedSignal` pulls in signals only (no render core). Optional and tree-shakeable; tiny.
194
3140
  - **New `kerfjs/scope` subpath** — tie disposers to a DOM element's lifetime, so append-heavy UIs stop leaking detached-but-subscribed effects/listeners. `disposeScope(el)` returns a WeakMap-keyed, accumulating scope whose `add(disposer)` (plus convenience `mount` / `effect` / `delegate` wrappers that register their own disposer) collects teardown; `dispose()` runs it all best-effort and idempotently. `disposeSubtree(root)` sweeps a subtree before removal; `observeRemovals(root)` installs one `MutationObserver` that auto-disposes on removal. No module-level mutable state. Optional and tree-shakeable.
195
- - **New `kerfjs/overlay` subpath** — the blessed modal/overlay + dismiss manager that every real kerf app hand-rolls. `overlay(content, options?)` appends a wrapper, `mount()`s content inside it (owning the disposal), wires dismissals (Escape / backdrop / outside-click, with `outsideIgnore`), a focus trap (`role="dialog"` / `aria-modal`, Tab wrap-around, restore-focus-on-close), and returns `{ el, close(result?), result }`. `confirm(message, options?)` is a promise-based `window.confirm` replacement, and `prompt(message, options?)` → `Promise<string | null>` its `window.prompt` counterpart (both globals are no-ops in Tauri webviews); `form(fields, options?)` → `Promise<Record<string, string> | null>` collects a two-or-three-field dialog. `choice<R>(message, actions, options?)` → `Promise<R | null>` is the **N-way** sibling of `confirm` — one button per action resolves that action's `value` (or `null` on dismissal), and `options.defaultValue` makes **Enter** (anywhere in the dialog) resolve a default action (the "global Enter-to-confirm" model) without holding the overlay handle. `prompt`/`form` submit on Enter and take an inline `validate`; all auto-escape their content. `confirm` / `prompt` / `form` also accept a **`render` slot option** for design-system teams — return your own markup and spread the provided `ok`/`cancel` (+ `input`/`error`) wiring onto it; kerf keeps owning the promise, `validate`, Enter-submit, dismiss, focus-trap, and focus-restore, so you adopt the batteries-included dialogs without a CSS rewrite. `popover(anchor, content, options?)` → `OverlayHandle` is a non-modal **anchored** overlay: it positions the content relative to `anchor` (below by default, flipping above on viewport overflow, clamped horizontally), defaults to dismiss-on-outside with the anchor exempt, and repositions on scroll / resize. `popover`'s placement core is also exported standalone: **`positionAnchored(el, anchor, options?)`** (one-shot) and **`autoReposition(el, anchor, options?)`** (keeps an element positioned on scroll/resize, returns a disposer) position *your own* element with no overlay lifecycle. **`tooltip(anchor, content, options?)`** is a hover/focus-triggered, non-modal, auto-hiding tooltip built on them. `toast(content, options?)` now returns a **`ToastHandle` (`{ el, dismiss }`)** instead of a bare dismiss function, so callers can inspect the node, wire an action button, or run entrance/exit transitions; new options: `mode: 'replace'` (collapse a rapid sequence to the latest) with `collapse: 'fade'` (default — run the prior toast's exit transition, good for a stacking region) or `'instant'` (remove it synchronously, what a single centered slot wants so messages never cross-fade in place), `variant` (`'info'`/`'success'`/`'warning'` → a `${className}--${variant}` accent class), `enterClass` (added on the next animation frame for a CSS entrance) and `exitClass` + `exitDuration` (CSS owns the exit — on dismiss the `enterClass` is **removed** so `exitClass` needn't out-specify it, and a symmetric single-class fade works with just `enterClass` + `exitDuration`; the node is removed after the delay). `dismiss({ instant: true })` removes the toast **synchronously** (skipping the exit transition), and `mode: 'replace'` `collapse: 'instant'` also force-removes a toast that is already mid-fade — so an action button that dismisses itself and shows a replacement in a single centered slot doesn't cross-fade the two. **Breaking (beta):** `toast()`'s return type changed from `() => void` to `{ el, dismiss }` — call `toast(...).dismiss()` or destructure `{ dismiss }`. Structural only — kerf ships no CSS. Optional and tree-shakeable; shares the core with the main barrel via code-splitting.
3141
+ - **New `kerfjs/overlay` subpath** — the blessed modal/overlay + dismiss manager that every real kerf app hand-rolls. `overlay(content, options?)` appends a wrapper, `mount()`s content inside it (owning the disposal), wires dismissals (Escape / backdrop / outside-click, with `outsideIgnore`), a focus trap (`role="dialog"` / `aria-modal`, Tab wrap-around, restore-focus-on-close), and returns `{ el, close(result?), result }`. `confirm(message, options?)` is a promise-based `window.confirm` replacement, and `prompt(message, options?)` → `Promise<string | null>` its `window.prompt` counterpart (both globals are no-ops in Tauri webviews); `form(fields, options?)` → `Promise<Record<string, string> | null>` collects a two-or-three-field dialog. `choice<R>(message, actions, options?)` → `Promise<R | null>` is the **N-way** sibling of `confirm` — one button per action resolves that action's `value` (or `null` on dismissal), and `options.defaultValue` makes **Enter** (anywhere in the dialog) resolve a default action (the "global Enter-to-confirm" model) without holding the overlay handle. `prompt`/`form` submit on Enter and take an inline `validate`; all auto-escape their content. `confirm` / `prompt` / `form` also accept a **`render` slot option** for design-system teams — return your own markup and spread the provided `ok`/`cancel` (+ `input`/`error`) wiring onto it; kerf keeps owning the promise, `validate`, Enter-submit, dismiss, focus-trap, and focus-restore, so you adopt the batteries-included dialogs without a CSS rewrite. `popover(anchor, content, options?)` → `OverlayHandle` is a non-modal **anchored** overlay: it positions the content relative to `anchor` (below by default, flipping above on viewport overflow, clamped horizontally), defaults to dismiss-on-outside with the anchor exempt, and repositions on scroll / resize. `popover`'s placement core is also exported standalone: **`positionAnchored(el, anchor, options?)`** (one-shot) and **`autoReposition(el, anchor, options?)`** (keeps an element positioned on scroll/resize, returns a disposer) position _your own_ element with no overlay lifecycle. **`tooltip(anchor, content, options?)`** is a hover/focus-triggered, non-modal, auto-hiding tooltip built on them. `toast(content, options?)` now returns a **`ToastHandle` (`{ el, dismiss }`)** instead of a bare dismiss function, so callers can inspect the node, wire an action button, or run entrance/exit transitions; new options: `mode: 'replace'` (collapse a rapid sequence to the latest) with `collapse: 'fade'` (default — run the prior toast's exit transition, good for a stacking region) or `'instant'` (remove it synchronously, what a single centered slot wants so messages never cross-fade in place), `variant` (`'info'`/`'success'`/`'warning'` → a `${className}--${variant}` accent class), `enterClass` (added on the next animation frame for a CSS entrance) and `exitClass` + `exitDuration` (CSS owns the exit — on dismiss the `enterClass` is **removed** so `exitClass` needn't out-specify it, and a symmetric single-class fade works with just `enterClass` + `exitDuration`; the node is removed after the delay). `dismiss({ instant: true })` removes the toast **synchronously** (skipping the exit transition), and `mode: 'replace'` `collapse: 'instant'` also force-removes a toast that is already mid-fade — so an action button that dismisses itself and shows a replacement in a single centered slot doesn't cross-fade the two. **Breaking (beta):** `toast()`'s return type changed from `() => void` to `{ el, dismiss }` — call `toast(...).dismiss()` or destructure `{ dismiss }`. Structural only — kerf ships no CSS. Optional and tree-shakeable; shares the core with the main barrel via code-splitting.
196
3142
  - **New `kerfjs/actions` subpath** — the blessed delegated action-table helper. `action(value)` returns a `data-action` `AttrSpec` (a thin specialization of `attr()`); `delegateActions(root, eventType, table, options?)` wires a whole table of `data-action` handlers with one delegated listener (built on `delegate()`) and returns a disposer. Formalizes the most-reinvented idiom in real kerf apps — one `attr('data-action', …)` table as the single source of truth for both the JSX attribute and the delegate dispatch. Optional and tree-shakeable; adds nothing to the main barrel.
197
3143
 
198
3144
  ## [4.1.1] - 2026-08-14
199
3145
 
200
-
201
-
202
3146
  - Added a CDN / importmap quickstart (`docs/6-jsx-runtime.md` §6.11.1) covering three no-install ways to load kerf from an ESM CDN: a direct `esm.sh` import, and jsDelivr / unpkg behind an importmap that also maps `@preact/signals-core`. Explains why a raw `dist/*.js` path fails (its unrewritten bare `@preact/signals-core` import won't resolve in the browser) and recommends pinning to a major version.
203
3147
  - Updated the README no-build example to use version-pinned CDN URLs (`kerfjs@4`) and noted that jsDelivr / unpkg need an importmap while esm.sh works with a direct import.
204
3148
 
205
3149
  ## [4.1.0] - 2026-07-31
206
3150
 
207
-
208
-
209
3151
  - ESLint 10 is now supported: `eslint-plugin-kerfjs` declares `peerDependencies.eslint` as `^9.0.0 || ^10.0.0`, and every named major is exercised by the rule suite in CI.
210
3152
  - The plugin now runs its rule suite against each supported ESLint major via `npm run test:eslint-matrix`, which also fails if the declared peer range, the tested set, and the CI matrix disagree — or if the range is left open-ended.
211
3153
 
212
-
213
3154
  - **ESLint 8 is no longer supported by `eslint-plugin-kerfjs`.** The package is ESM-only and ESLint 8 resolves `.eslintrc` plugins with `require()`, so `extends: ["plugin:kerfjs/…"]` could never load it.
214
3155
  - **Legacy `.eslintrc` configuration is documented as unsupported.** Use flat config (`eslint.config.js`); the `legacy-recommended` export remains in the package but is unreachable through any config system and should be treated as deprecated.
215
3156
 
216
-
217
3157
  - Generated Hot Sheet skill and rule files no longer hardcode a machine's local API port or shared secret. The curl fallbacks read `$HOTSHEET_PORT` / `$HOTSHEET_SECRET` from `.hotsheet/settings.local.json` and `.hotsheet/secret.json` instead, with `.hotsheet/settings.json` as the fallback for older projects.
218
3158
  - A new `npm run check:audit` gate runs `npm audit --omit=dev --audit-level=high` against the published dependency tree and is wired into the pre-push `check:full` gate.
219
3159
 
220
-
221
3160
  - Test tooling moved to vitest 4 and ESLint 10; coverage thresholds were recalibrated to 98.5% branches / 99.5% statements (lines and functions stay at 100%) after vitest 4's sharper AST-based coverage mapping resolved seventeen previously-miscredited defensive branches.
222
3161
  - Removed the `hs-m` marketing-ticket skill and Cursor rule.
223
3162
 
224
3163
  ## [4.0.0] - 2026-07-28
225
3164
 
226
-
227
-
228
3165
  - `draggable`, `spellCheck`, and `contentEditable` no longer accept booleans — they are enumerated HTML attributes, so write the keyword string (`draggable="true"`, `spellCheck="false"`). The boolean forms rendered markup that meant the opposite of what was written; real boolean attributes like `hidden`/`checked`/`disabled` are unchanged.
229
3166
  - `<select value>` / `<textarea value>` (and their `defaultValue` forms) no longer typecheck — neither element has a `value` content attribute, so kerf was emitting markup no browser reads. Use `<option selected>` and `<textarea>{draft}</textarea>`.
230
- - Lowercase `autofocus` no longer accepts `"true"` / `"false"` — it is a real boolean attribute, so `autofocus="false"` turned autofocus *on*. Use `autofocus={false}` or omit it.
231
-
3167
+ - Lowercase `autofocus` no longer accepts `"true"` / `"false"` — it is a real boolean attribute, so `autofocus="false"` turned autofocus _on_. Use `autofocus={false}` or omit it.
232
3168
 
233
3169
  - `href="javascript:void(0)"` and its five sibling spellings are no longer dropped by the URL screen. Dropping the `href` unmade the anchor — it lost `:link` styling, keyboard focus, and its pointer cursor. Matching is against the whole normalized value, so nothing can ride along after an inert body.
234
3170
  - `defaultSelected` rendered as `defaultselected`, an attribute no browser reads, so the option it named was never pre-selected. It now correctly emits `selected`.
235
3171
 
236
-
237
3172
  - Typed JSX gained a wide set of modern attributes: globals `inert`, `popover`, `nonce`, `part`/`exportparts`, `enterKeyHint`, `translate`, `autocorrect`, and the full microdata family; per-element `<button popoverTarget/popoverTargetAction/command>`, `<input popoverTarget/popoverTargetAction>`, `<form rel>`, `<source width/height>`, and `writingsuggestions`.
238
3173
  - `<button command>` is now typed to the spec keywords (`show-modal`, `close`, `request-close`, `toggle-popover`, `show-popover`, `hide-popover`) plus any `--custom` command, catching a custom command written without its required `--` prefix.
239
3174
  - `<a download>` and `<area download>` accept the bare boolean form as well as a string filename, so `<a href="/report.pdf" download>` compiles.
240
3175
 
241
-
242
3176
  - The advertised bundle size is corrected everywhere: ~12 KB min+gzip for a realistic import, ~13 KB with `arraySignal` (previously stated as ~11/~12 KB, and ~6.1 KB in the Cursor rules). Every migration page's delta row was recomputed against the new figure.
243
3177
  - The JSX runtime doc gained a section on enumerated vs. boolean attributes, and the API reference now records where the JSX types come from (WHATWG HTML Living Standard + SVG 2, not another framework's property table).
244
3178
  - The dev-warning sections in the dev-warnings doc were renumbered by family so the `11.2.N` headings run in document order; cross-references elsewhere in the docs were updated to match.
245
3179
 
246
-
247
- - The bundle-size check now gates the *prose* as well as the build: every place the docs advertise a size is matched against the measured figure, and a reworded claim that stops matching fails rather than going silently unchecked.
3180
+ - The bundle-size check now gates the _prose_ as well as the build: every place the docs advertise a size is matched against the measured figure, and a reworded claim that stops matching fails rather than going silently unchecked.
248
3181
  - New repo checks wired into `npm run check`: `check:docs:dev-warns` (the dev-warning doc and `ENV_NAME` must name the same set, with monotonic section numbers), `check:design-rule-5` (every top-level `let` in `src/` must be accounted for by the documented rule), and `check:skills` (a skill file restating a threshold its owner disagrees with fails).
249
3182
 
250
3183
  ## [3.0.0] - 2026-07-27
251
3184
 
252
-
253
-
254
3185
  - **kerf no longer infers development mode — add one line to your entry to keep the dev diagnostics.**
255
3186
 
256
3187
  ```js
257
- if (import.meta.env.DEV) await import('kerfjs/dev'); // Vite
258
- if (process.env.NODE_ENV !== 'production') await import('kerfjs/dev'); // webpack / Node
3188
+ if (import.meta.env.DEV) await import("kerfjs/dev"); // Vite
3189
+ if (process.env.NODE_ENV !== "production") await import("kerfjs/dev"); // webpack / Node
259
3190
  ```
260
3191
 
261
3192
  Without it you get production shape: no dev warnings, no read-only `defineStore` `get()`
262
3193
  snapshot, and a screened dangerous URL warns-and-drops instead of throwing. Nothing else
263
3194
  changes, and if you never used the dev warnings you get a smaller bundle for free.
264
3195
 
265
- **Why it changed.** kerf inferred its own dev/prod mode by reading `globalThis.process?.env?.NODE_ENV`. Bundlers substitute the *bare* `process.env.NODE_ENV` token and never create a `globalThis.process` object for browser targets, so that read was `undefined`, `undefined !== 'production'` was `true`, and every production browser build silently took the development path. Consequences that were shipping: every `defineStore` `get()` returned a deep read-only `Proxy` (an allocation on every store read), a screened `javascript:`/`data:` URL **threw** instead of the documented warn-and-drop, and the always-on list-key warnings printed to production consoles. Server/Node builds, where `process` exists, were unaffected.
3196
+ **Why it changed.** kerf inferred its own dev/prod mode by reading `globalThis.process?.env?.NODE_ENV`. Bundlers substitute the _bare_ `process.env.NODE_ENV` token and never create a `globalThis.process` object for browser targets, so that read was `undefined`, `undefined !== 'production'` was `true`, and every production browser build silently took the development path. Consequences that were shipping: every `defineStore` `get()` returned a deep read-only `Proxy` (an allocation on every store read), a screened `javascript:`/`data:` URL **threw** instead of the documented warn-and-drop, and the always-on list-key warnings printed to production consoles. Server/Node builds, where `process` exists, were unaffected.
266
3197
 
267
3198
  Removing the inference also shrinks production bundles by **~4.7 KB min+gzip (27%)** — a realistic import (`signal`/`computed`/`effect`/`batch`/`mount`/`each`/`delegate`) goes from 16.91 KB to **12.24 KB**. Previously the dev-warning modules were imported unconditionally by `mount()`/`each()` and gated at runtime, so they shipped to production regardless of build mode and no amount of tree-shaking could reclaim them. With the dev entry absent they are unreachable, and the `import()` statement itself is eliminated — the chunk is never emitted, let alone fetched.
268
3199
 
269
3200
  `globalThis.KERF_DEV` is no longer consulted — not importing the dev entry is now the (compile-time) way to opt out. One ordering note: `signal()` picks its constructor at creation time, so put the import first if you rely on the untracked-signal warning.
270
3201
 
271
- - The `KERF_DEV_WARN_*` diagnostics no longer consult `NODE_ENV` or `globalThis.KERF_DEV` at all. Whether they run is decided in exactly one place: whether you imported `kerfjs/dev`. The previous release stopped kerf's core from inferring dev mode but left a second, inherited gate inside each warner, so a Node/SSR consumer who *deliberately* installed the diagnostics under `NODE_ENV=production` got silence — and `globalThis.KERF_DEV = false` still silenced warnings the consumer had explicitly opted into. Both are gone; each warning is now gated only by its own env var. If you were using `globalThis.KERF_DEV` to turn diagnostics off, remove the dev import instead (which is also what sheds the ~4.7 KB from your bundle).
272
-
3202
+ - The `KERF_DEV_WARN_*` diagnostics no longer consult `NODE_ENV` or `globalThis.KERF_DEV` at all. Whether they run is decided in exactly one place: whether you imported `kerfjs/dev`. The previous release stopped kerf's core from inferring dev mode but left a second, inherited gate inside each warner, so a Node/SSR consumer who _deliberately_ installed the diagnostics under `NODE_ENV=production` got silence — and `globalThis.KERF_DEV = false` still silenced warnings the consumer had explicitly opted into. Both are gone; each warning is now gated only by its own env var. If you were using `globalThis.KERF_DEV` to turn diagnostics off, remove the dev import instead (which is also what sheds the ~4.7 KB from your bundle).
273
3203
 
274
- - **New:** `each()` accepts an options object — `each(items, render, { cacheKey, key })` — and `key` gives a list a **stable identity**. Without one a list is identified by its position among the `each()` calls in a render, so adding or removing a conditional list above it made kerf rebuild it from scratch: rows lost their DOM nodes, and with them focus, scroll position and in-progress IME composition. Keying a list removes that dependency; because a keyed list doesn't occupy a positional slot, keying just the *conditional* list usually stabilizes its siblings too. The existing three-argument `each(items, render, cacheKey)` form is unchanged. In development kerf now warns once per list when it detects such a shift and names the fix.
3204
+ - **New:** `each()` accepts an options object — `each(items, render, { cacheKey, key })` — and `key` gives a list a **stable identity**. Without one a list is identified by its position among the `each()` calls in a render, so adding or removing a conditional list above it made kerf rebuild it from scratch: rows lost their DOM nodes, and with them focus, scroll position and in-progress IME composition. Keying a list removes that dependency; because a keyed list doesn't occupy a positional slot, keying just the _conditional_ list usually stabilizes its siblings too. The existing three-argument `each(items, render, cacheKey)` form is unchanged. In development kerf now warns once per list when it detects such a shift and names the fix.
275
3205
 
276
3206
  - **`kerfjs/dev` now exports `enableWarnings()`** — and it fixes a defect: until now, none of the
277
3207
  `KERF_DEV_WARN_*` diagnostics could be switched on in a browser at all. Every one of them read `globalThis.process.env`, which does not exist in a browser realm — and a bundler `define` cannot reach it either, because the read goes through `globalThis.process` into a local binding rather than the substitutable `process.env.X` token. So in a Vite/webpack dev server, the environment where these warnings are most wanted, the entire opt-in family was permanently and silently off. Only Node/SSR (and kerf's own vitest suite, which is why nothing caught it) could turn any of them on.
@@ -280,8 +3210,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
280
3210
 
281
3211
  ```js
282
3212
  if (import.meta.env.DEV) {
283
- const dev = await import('kerfjs/dev');
284
- dev.enableWarnings({ staleBinding: true, narrowSet: true, invariants: 'throw' });
3213
+ const dev = await import("kerfjs/dev");
3214
+ dev.enableWarnings({
3215
+ staleBinding: true,
3216
+ narrowSet: true,
3217
+ invariants: "throw",
3218
+ });
285
3219
  }
286
3220
  ```
287
3221
 
@@ -295,8 +3229,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
295
3229
 
296
3230
  - New opt-in dev warning `KERF_DEV_WARN_LIST_REBIND=1`: fires (once per list) when an `each()` list's container is rebuilt by the morph — an ancestor's tag changed across renders, so the subtree was replaced and the list self-healed by re-binding and repopulating. The recovery is correct but discards row DOM state (focus, scroll, IME, imperative listeners); the warning names the list and points at keeping ancestor tags stable. Follows the standard `KERF_DEV_WARN_*` family rules: off by default, dev-mode only, zero production cost.
297
3231
 
298
-
299
- - `KERF_DEV_WARN_UNTRACKED_SIGNALS=1` now tells you what it can and cannot see. The warning picks its machinery when a signal is *created*, so it only covers signals created after `kerfjs/dev` is installed — and because static imports are hoisted above a top-level `await import('kerfjs/dev')`, the module-scope signals it most wants to catch are usually created first. Previously that failed silently: you set the env var, saw nothing, and concluded your code was clean. Opting in now prints the coverage boundary once, along with the fix (make `import 'kerfjs/dev'` the first static import of a dev-only entry file). The boundary itself can't be removed — `Signal.prototype`'s `value` accessor is non-configurable, so already-created signals can't be retro-fitted without kerf keeping a registry of every signal, which production would pay for.
3232
+ - `KERF_DEV_WARN_UNTRACKED_SIGNALS=1` now tells you what it can and cannot see. The warning picks its machinery when a signal is _created_, so it only covers signals created after `kerfjs/dev` is installed — and because static imports are hoisted above a top-level `await import('kerfjs/dev')`, the module-scope signals it most wants to catch are usually created first. Previously that failed silently: you set the env var, saw nothing, and concluded your code was clean. Opting in now prints the coverage boundary once, along with the fix (make `import 'kerfjs/dev'` the first static import of a dev-only entry file). The boundary itself can't be removed — `Signal.prototype`'s `value` accessor is non-configurable, so already-created signals can't be retro-fitted without kerf keeping a registry of every signal, which production would pay for.
300
3233
 
301
3234
  - An `each()` of `<tr>` written directly inside `<table>` now fails with a clear error instead of silently duplicating rows: the HTML parser inserts a `<tbody>` around the rows, which kerf cannot bind through. The message names both tags and shows the supported shape (`<table><tbody>{each(...)}</tbody></table>`). Previously this also mis-reported the rows as missing `data-key`.
302
3235
 
@@ -304,8 +3237,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
304
3237
 
305
3238
  - Toolchain: the repo now type-checks with the native **TypeScript 7** compiler across every gate (`typecheck`, the dist `.d.ts` typing gates, the docs code-block compile — a full-repo `tsc --noEmit` now takes ~0.3 s), with `typescript@6` (the JS-API bridge release) retained for tsup's `.d.ts` emit and typescript-eslint, which still require the JS compiler API. `@typescript-eslint/*` bumped to 8.65. No shipped-code changes — `dist/` output is unaffected.
306
3239
 
307
-
308
- - Fixed: passing a **function** as an `each()` item through an `arraySignal` insert/update (an unusual mistake, but functions are valid `WeakMap` keys so the per-item cache silently accepted them) rendered the row and then threw `each(): items must be objects…` on a *later, unrelated* re-render — far from the cause. The granular path now enforces the same objects-only item contract the snapshot path does, so the error is thrown on the render the offending mutation triggered, naming the type and index. Primitive items already behaved this way; functions now match.
3240
+ - Fixed: passing a **function** as an `each()` item through an `arraySignal` insert/update (an unusual mistake, but functions are valid `WeakMap` keys so the per-item cache silently accepted them) rendered the row and then threw `each(): items must be objects…` on a _later, unrelated_ re-render — far from the cause. The granular path now enforces the same objects-only item contract the snapshot path does, so the error is thrown on the render the offending mutation triggered, naming the type and index. Primitive items already behaved this way; functions now match.
309
3241
 
310
3242
  - `arraySignal.update(i, fn)` now works when `fn` mutates the row object and returns it (not only when it returns a fresh object). Previously such a same-ref update rendered correctly in one list but left every other view of the same signal — a second list, a second `mount()`, a `filter()`ed plain-array view — permanently stale, and was lost outright when the update was batched with a selection change or a `replace()`. kerf now tracks a per-item content version so the change reaches every consumer. Returning a fresh object remains the idiomatic style; both are supported. (Fixed in the same line of work: the per-item version tracking briefly made `arraySignal.update()` throw on a signal of primitives — `arraySignal<number>` used as a plain signal — because a primitive can't key the internal version map; primitive items are now simply skipped, since only object rows are ever memoized.)
311
3243
 
@@ -317,13 +3249,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
317
3249
 
318
3250
  - Fixed: an `arraySignal.update()` that mutated a row object in place (returning the same reference) could be silently reverted to its old content by the next unrelated re-render. The granular update path now keeps kerf's per-row HTML cache in sync with what it rendered, so the two never disagree. (Immutable updates — returning a fresh object — were unaffected, and remain the recommendation.)
319
3251
 
320
- - Fixed: showing an empty conditionally-rendered `each()` list in the same batch as an update to a *sibling* list could empty the sibling entirely — it rendered zero rows. When the conditional list reappeared, its list-marker comment landed next to the sibling's, and the diff overwrote the sibling marker's internal id with the reappearing one's, so the sibling's binding could no longer find its own marker. Marker comments (kerf's internal list and binding anchors) now pair only with the identical marker, never with a different one that happens to be the same kind. Ordinary comments in your markup are unaffected.
3252
+ - Fixed: showing an empty conditionally-rendered `each()` list in the same batch as an update to a _sibling_ list could empty the sibling entirely — it rendered zero rows. When the conditional list reappeared, its list-marker comment landed next to the sibling's, and the diff overwrote the sibling marker's internal id with the reappearing one's, so the sibling's binding could no longer find its own marker. Marker comments (kerf's internal list and binding anchors) now pair only with the identical marker, never with a different one that happens to be the same kind. Ordinary comments in your markup are unaffected.
321
3253
 
322
3254
  - Fixed: when an element rendered by a condition came back, the diff could pair it with an unrelated sibling that happened to have the same tag, and then whatever protects that sibling's contents kept the wrong contents alive inside it. A `data-morph-skip` widget **swallowed** the reappearing element — its content never rendered — and the widget was duplicated, which for a library-owned subtree (an editor, a chart, a terminal) means a second live instance attached to a node the library has no reference to. A `data-morph-preserve` child ended up under the foreign host and appeared twice. A bound hole's text leaked into the reappearing element and rendered twice. Three rules now gate that pairing: an element with an `id`/`data-key` is only ever matched to a live element with the same key; a `data-morph-skip` element only ever matches another one (so a library-owned subtree is never adopted as a stand-in, whether or not you use keys); and a comment anchoring kerf's own state only matches an anchor of the same kind. Ordinary elements without a key still match positionally exactly as before.
323
3255
 
324
- - Fixed: when the number of `each()` calls in a render changed — a conditional list appearing or disappearing — a *surviving* list could render the departed list's rows, or render its own rows inside the wrong container. Lists without a `key` are identified by their position among the `each()` calls, and both the per-item HTML cache and the live list binding were being read as belonging to whichever list now held that position. Two lists over the same collection hit each other's cache exactly, so nothing could detect it from the data. A shift now discards that state and re-renders, which is what the documentation already described it as costing: a rebuild, never wrong output. Lists given a `key` are unaffected, and a render that doesn't change the call count is unaffected. One related improvement falls out: an unrelated list no longer loses its row nodes when a nested `each()` shifts the count.
3256
+ - Fixed: when the number of `each()` calls in a render changed — a conditional list appearing or disappearing — a _surviving_ list could render the departed list's rows, or render its own rows inside the wrong container. Lists without a `key` are identified by their position among the `each()` calls, and both the per-item HTML cache and the live list binding were being read as belonging to whichever list now held that position. Two lists over the same collection hit each other's cache exactly, so nothing could detect it from the data. A shift now discards that state and re-renders, which is what the documentation already described it as costing: a rebuild, never wrong output. Lists given a `key` are unaffected, and a render that doesn't change the call count is unaffected. One related improvement falls out: an unrelated list no longer loses its row nodes when a nested `each()` shifts the count.
325
3257
 
326
- - Fixed: a row added to an `each()` list could land in the wrong place whenever the list wasn't the last thing inside its parent. A list ends at its last row, but kerf was looking for the next *element* after it and skipping everything else on the way — so static content following the list (a footer row, a totals line, an "add item" control) got jumped, and a new row appeared after it instead of before. The same skip crossed a neighboring list's internal anchor: with two `each()` lists in one parent, rows from the first could be placed inside the second's region, and when both lists started empty their rows came out **in the wrong order** — the second list's rows rendered first. Both were correct on the initial paint and only went wrong on a later update, which made them read as intermittent. Lists now anchor on the next node of any kind, so a list's rows always stay within its own region.
3258
+ - Fixed: a row added to an `each()` list could land in the wrong place whenever the list wasn't the last thing inside its parent. A list ends at its last row, but kerf was looking for the next _element_ after it and skipping everything else on the way — so static content following the list (a footer row, a totals line, an "add item" control) got jumped, and a new row appeared after it instead of before. The same skip crossed a neighboring list's internal anchor: with two `each()` lists in one parent, rows from the first could be placed inside the second's region, and when both lists started empty their rows came out **in the wrong order** — the second list's rows rendered first. Both were correct on the initial paint and only went wrong on a later update, which made them read as intermittent. Lists now anchor on the next node of any kind, so a list's rows always stay within its own region.
327
3259
 
328
3260
  - Fixed: an `each()` list inside an `<svg>` whose row markup contained an apostrophe (or anything else the serializer writes back differently) failed to mount at all, with a self-contradictory error. Also fixed: `each({ key })` now validates the key, so a key containing an HTML comment terminator can no longer break out of the list's internal marker and put markup in the page.
329
3261
 
@@ -335,7 +3267,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
335
3267
 
336
3268
  - Fixed: a controlled `checked` / `value` on an `each()` row's own top-level element could stay visibly stale after the user had interacted with it — the row reconciler's attribute-only fast path wrote the attribute without syncing the live property, so whether the control obeyed your data depended on which internal route the update happened to take.
337
3269
 
338
- - Fixed: when a conditionally-rendered `each()` list is added or removed, a sibling list could render the *other* list's rows — a batched "hide one list and push to another" applied the queued update to the wrong list's DOM. Lists now verify which data a pending update belongs to before applying it, and rebuild from their own items when it doesn't match.
3270
+ - Fixed: when a conditionally-rendered `each()` list is added or removed, a sibling list could render the _other_ list's rows — a batched "hide one list and push to another" applied the queued update to the wrong list's DOM. Lists now verify which data a pending update belongs to before applying it, and rebuild from their own items when it doesn't match.
339
3271
 
340
3272
  - Fixed: `each()` rows inside an `<svg>` root were re-parsed in the HTML namespace on every update, so rows added or structurally changed after the first render were invisible in the browser — the initial picture looked right, which made it read as a rendering flake. Row parsing now follows the list parent's namespace (rows under `<foreignObject>` correctly stay HTML).
341
3273
 
@@ -343,92 +3275,72 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
343
3275
 
344
3276
  - Fixed: anything sitting between a keyed `each()` list's anchor and its rows — a node injected imperatively into the list region — could make a conditional sibling's removal reorder the list, landing a trailing sibling ahead of the rows. A list's row region (anchor through last row) is now treated as one unit by the diff: it moves whole, the diff's cursor steps over it whole, and injected nodes inside it travel along keeping their position relative to the rows.
345
3277
 
346
- - A conditional sibling *inside* a keyed `each()` list's parent — a header row that comes and goes above the list — no longer costs the list's rows their DOM identity. The morph now recognizes the list's marker when a sibling shifts it, moving the marker and its rows up as a single unit instead of rebuilding the list, so row nodes, focus, and the caret survive the toggle. (An ancestor tag change, or a same-tag sibling that positionally takes the container's place, still rebuilds the list — give the list's own container a stable `id`/`data-key` if its rows need to survive that.)
3278
+ - A conditional sibling _inside_ a keyed `each()` list's parent — a header row that comes and goes above the list — no longer costs the list's rows their DOM identity. The morph now recognizes the list's marker when a sibling shifts it, moving the marker and its rows up as a single unit instead of rebuilding the list, so row nodes, focus, and the caret survive the toggle. (An ancestor tag change, or a same-tag sibling that positionally takes the container's place, still rebuilds the list — give the list's own container a stable `id`/`data-key` if its rows need to survive that.)
347
3279
 
348
3280
  - Fixed: a conditional sibling that shared or positionally shadowed a keyed `each()` list's container could strand the list's rows and then render a duplicate copy of them (e.g. a header `<li>` toggled inside the list's `<ul>`, or a same-tag banner `<ul>` before the list container). The morph can separate the list's marker comment from its still-attached rows; the self-heal now removes any such still-live stranded rows before repopulating, so recovery replaces the rows rather than duplicating them.
349
3281
 
350
3282
  ## [2.0.1] - 2026-07-23
351
3283
 
352
-
353
-
354
3284
  - Fixed a `morph()` bug where static text siblings of a fine-grained bound text hole were dropped after a structural re-render (e.g. `<div>{label} / static</div>` collapsing to just the label).
355
3285
 
356
-
357
3286
  - New animated coding-session demo on the getting-started page: watch the canonical counter get typed out, served, clicked in a browser, and live-edited into a todo list.
358
3287
  - Added an animated architecture diagram and a link to the docs site from the README.
359
3288
 
360
3289
  ## [2.0.0] - 2026-07-23
361
3290
 
362
-
363
-
364
3291
  - `delegateCapture()` now uses `closest()`-style walk-up matching like `delegate()`, passing the matched ancestor to the handler; pass `{ match: 'direct' }` (new `DelegateOptions`) to restore exact-element matching.
365
3292
  - The dangerous-URL screen (`javascript:`, `vbscript:`, script-executing `data:` URLs) now throws an error in development instead of only warning. Production behavior is unchanged: warn and drop the attribute.
366
3293
 
367
-
368
3294
  - New `kerfjs/html` tagged template: author kerf UIs with no build step (CDN / importmap, no JSX transform) with runtime semantics identical to JSX — signal holes become fine-grained bindings, attributes and text are escaped and URL-screened the same way.
369
3295
  - New no-build example app, **live-poll**, served exactly as authored — an importmap plus one `html`-templated module, with view-source showing the app.
370
3296
  - Added `<filter>` to the typed JSX intrinsic elements, so SVG filters compile in JSX-authored code.
371
3297
  - Fully-bound mounts are now a documented, test-pinned guarantee: a render that reads no signal `.value` runs exactly once, forever — every update is a direct per-node write.
372
3298
 
373
-
374
3299
  - Controlled form state now survives user interaction: `checked`, `value`, and `selected` DOM properties are synced when the reconciler mutates those attributes, so a clicked checkbox or typed-into input no longer ignores later updates.
375
3300
  - Fixed stale fine-grained bindings after `arraySignal.update()`: in-place row updates now re-wire bindings whose signal instance changed, instead of leaving effects reading the old row object forever.
376
3301
 
377
-
378
3302
  - New runtime dev-mode override: set `globalThis.KERF_DEV = false` (or `true`) to control dev mode without a bundler — CDN/importmap apps are no longer stuck in dev mode in production.
379
3303
  - Two new opt-in dev warnings: `KERF_DEV_WARN_STALE_BINDING` flags bindings that silently go stale on the byte-equal fast path, and `KERF_DEV_WARN_VALUE_ONLY_RERENDER` flags re-renders whose only changes could have been fine-grained bindings.
380
3304
  - `defineStore`'s dev-mode `get()` snapshot now returns a deep read-only proxy instead of freezing the live state: nested mutations like `get().nested.x = 1` are caught too, and they throw a descriptive `TypeError` rather than failing silently.
381
3305
 
382
-
383
3306
  - Docs repositioned around the "values bind, structure re-renders" idiom as the primary way to render dynamic values, across the overview, reactivity guide, and AI assistant configs.
384
3307
  - New guide covering the no-build authoring path and example app, plus a documentation-wide accuracy pass (delegate capture semantics, `effect()` cleanup returns, URL-screen behavior, and more).
385
3308
 
386
3309
  ## [1.0.2] - 2026-07-22
387
3310
 
388
-
389
-
390
3311
  - Fixed the row-selector demo animation 404ing on the published site — the missing SVG capture is now generated and committed.
391
3312
 
392
3313
  ## [1.0.1] - 2026-07-22
393
3314
 
394
-
395
-
396
3315
  - KF-329: pin release-workflow npm upgrade to npm@11 — npm@12 needs Node ≥ 22.22.2, above the 22.21.0 pin (`c54559f`)
397
3316
 
398
3317
  ## [1.0.0] - 2026-07-22
399
3318
 
400
-
401
-
402
3319
  - **Fine-grained signal bindings** — pass a signal or `computed` directly into a JSX attribute or text hole (e.g. `class={computed(...)}` or `{sig}`) inside `mount()`, and that one node updates on signal change without re-running `render()` or walking the list reconciler. Opt-in per hole and non-breaking; works in static content and inside `each()` rows on both the snapshot and `arraySignal` reconcile paths, with binding effects correctly wired, carried, and disposed across row insert/update/remove/move.
403
3320
  - Bound values get the same safety treatment as static ones: URL screening and `SafeHtml`/`raw()` unwrapping now apply to fine-grained bound attributes.
404
3321
  - New interactive benchmark playground (`npm run bench:serve`) to explore kerf by hand in the standard 1k-rows benchmark app.
405
3322
  - New **row-selector** example app and a "Fine-grained bindings" section in the reactivity demo, both showing select-row updates with zero render re-runs and zero list reconciles.
406
3323
 
407
-
408
3324
  - Hardened the dangerous-URL screen: scheme detection now normalizes away C0 control characters, DEL, and leading whitespace, so obfuscations like `java script:` or a NUL before the colon can no longer slip `javascript:`/`vbscript:` URLs past the check.
409
3325
  - Attribute names are now validated — malformed names (e.g. from spreading attacker-controlled keys into JSX) throw instead of breaking out of the open tag, and inline `on*` event handlers are rejected on both the static and signal-bound attribute paths, closing an XSS vector where a bound `onclick` would have installed a live handler.
410
3326
  - Documented kerf's reserved marker namespace (`data-kfb`, `data-kfbrow`, `kfb:`/`kfbr:`/`kf-list:` comments) — consumer content using these can collide with binding wiring, so they're now explicitly reserved.
411
3327
  - Documented the trusted-input bridges (`toElement()`, `morph()` with string/Element templates, `<iframe srcdoc>`) that bypass escaping by design, and the `raw()`/`SafeHtml` trust boundary.
412
3328
  - Hardened the release pipeline: least-privilege OIDC scoping per job, SHA-pinned GitHub Actions with automated Dependabot bumps, and a token-holding publish job that runs with `--ignore-scripts` and no build tools.
413
3329
 
414
-
415
3330
  - Reduced the per-row create cost of fine-grained row bindings from ~1.65× to ~1.15× via lazy row wiring — the common single-root-binding case now needs no subtree walk or extra allocations.
416
3331
  - Published cross-framework benchmark numbers now come from the official upstream krausest js-framework-benchmark run (kerf is a merged upstream entry), replacing stale local-machine measurements.
417
3332
 
418
-
419
3333
  - README refreshed for the 1.0 release: fine-grained updates and safe-by-default escaping promoted to headline features, and the status line flipped from "Pre-1.0 — API may evolve" to stable 1.0.
420
3334
  - Fine-grained bindings documented across all consumer and AI-assistant surfaces (reactivity docs, API reference, usage guide, Cursor rules, Claude skill).
421
3335
 
422
- - **Signposted the raw HTML/SVG → DOM bridges as trusted-input only.** `toElement()`, `morph()` (with a string/Element template), and the `<iframe srcdoc>` attribute bypass kerf's escaping/URL-screening by design — they're the same trust model as `innerHTML` / `raw()`. The docs now call this out loudly, including that the SVG path is *more* dangerous than the HTML path (a top-level `<svg><script>`, SVG event attributes, and `xlink:href="javascript:"` execute once inserted, whereas an HTML-string `<script>` is inert), and that `srcdoc` is HTML a browser re-parses as a document (so `srcdoc={userString}` executes even though the value is escaped as an attribute). No behavior change — these are documentation + regression tests: a real-browser spec (`tests/browser/trusted-html-bridges.spec.ts`) pins the execution boundary across Chromium/Firefox/WebKit, a unit test pins that the granular list fast path keeps the URL screen's guarantee end-to-end, and another pins that SVG input isn't sanitized. See [`docs/7-svg.md`](docs/7-svg.md) § Security, [`docs/8-api-reference.md`](docs/8-api-reference.md), and [`docs/6-jsx-runtime.md`](docs/6-jsx-runtime.md) §6.4.3.
423
- - **Documented kerf's reserved marker namespace.** Fine-grained bindings and `each()` lists coordinate through in-band markers that the wiring pass finds by scanning the mounted subtree and matching by id. A consumer element that carries one of those names can collide with a real binding's id and silently steal its update, so the names are now documented as reserved: the `data-kfb` / `data-kfbrow` attributes and HTML comments beginning `kfb:` / `kfbr:` / `kf-list:`. Don't emit them from your own markup or via `raw()`. (kerf's escaping already prevents a plain text/attribute *value* from forging one — the only ways in are hand-written markup or `raw()`.) See [`docs/2-reactivity.md`](docs/2-reactivity.md) § "Reserved marker names".
424
- - **Attribute names are now validated, and inline event handlers are rejected outright.** The JSX runtime already escaped attribute *values*; it now also validates each attribute *name* against a safe shape (a letter/underscore/colon followed by letters, digits, or `_ . : -`) and **throws** on anything else. This closes a markup-injection vector when an object with attacker-controlled keys is spread into JSX (`<div {...untrustedObj}>`) — previously a key like `'x><img onerror=…>'` broke out of the open tag even though the value was escaped. Separately, any `on*` attribute (a function *or* a string value, in any case — e.g. `onClick={fn}` or `onclick="…"`) now throws and points at `delegate()`; previously only function-valued keys matching `/^on[A-Z]/` were caught, so a string `onclick="alert(1)"` slipped through and became a live inline handler when parsed. Both checks now cover the **fine-grained bound path** too: a signal bound straight into an attribute (`onclick={signal}`) is written with `setAttribute`, and `setAttribute('onclick', …)` installs a live inline handler just as a parsed string would — so an `on*` (or malformed) name bound as a signal is rejected at binding time, closing the same vector on the signal path. See [`docs/6-jsx-runtime.md`](docs/6-jsx-runtime.md) §6.4.2.
3336
+ - **Signposted the raw HTML/SVG → DOM bridges as trusted-input only.** `toElement()`, `morph()` (with a string/Element template), and the `<iframe srcdoc>` attribute bypass kerf's escaping/URL-screening by design — they're the same trust model as `innerHTML` / `raw()`. The docs now call this out loudly, including that the SVG path is _more_ dangerous than the HTML path (a top-level `<svg><script>`, SVG event attributes, and `xlink:href="javascript:"` execute once inserted, whereas an HTML-string `<script>` is inert), and that `srcdoc` is HTML a browser re-parses as a document (so `srcdoc={userString}` executes even though the value is escaped as an attribute). No behavior change — these are documentation + regression tests: a real-browser spec (`tests/browser/trusted-html-bridges.spec.ts`) pins the execution boundary across Chromium/Firefox/WebKit, a unit test pins that the granular list fast path keeps the URL screen's guarantee end-to-end, and another pins that SVG input isn't sanitized. See [`docs/7-svg.md`](docs/7-svg.md) § Security, [`docs/8-api-reference.md`](docs/8-api-reference.md), and [`docs/6-jsx-runtime.md`](docs/6-jsx-runtime.md) §6.4.3.
3337
+ - **Documented kerf's reserved marker namespace.** Fine-grained bindings and `each()` lists coordinate through in-band markers that the wiring pass finds by scanning the mounted subtree and matching by id. A consumer element that carries one of those names can collide with a real binding's id and silently steal its update, so the names are now documented as reserved: the `data-kfb` / `data-kfbrow` attributes and HTML comments beginning `kfb:` / `kfbr:` / `kf-list:`. Don't emit them from your own markup or via `raw()`. (kerf's escaping already prevents a plain text/attribute _value_ from forging one — the only ways in are hand-written markup or `raw()`.) See [`docs/2-reactivity.md`](docs/2-reactivity.md) § "Reserved marker names".
3338
+ - **Attribute names are now validated, and inline event handlers are rejected outright.** The JSX runtime already escaped attribute _values_; it now also validates each attribute _name_ against a safe shape (a letter/underscore/colon followed by letters, digits, or `_ . : -`) and **throws** on anything else. This closes a markup-injection vector when an object with attacker-controlled keys is spread into JSX (`<div {...untrustedObj}>`) — previously a key like `'x><img onerror=…>'` broke out of the open tag even though the value was escaped. Separately, any `on*` attribute (a function _or_ a string value, in any case — e.g. `onClick={fn}` or `onclick="…"`) now throws and points at `delegate()`; previously only function-valued keys matching `/^on[A-Z]/` were caught, so a string `onclick="alert(1)"` slipped through and became a live inline handler when parsed. Both checks now cover the **fine-grained bound path** too: a signal bound straight into an attribute (`onclick={signal}`) is written with `setAttribute`, and `setAttribute('onclick', …)` installs a live inline handler just as a parsed string would — so an `on*` (or malformed) name bound as a signal is rejected at binding time, closing the same vector on the signal path. See [`docs/6-jsx-runtime.md`](docs/6-jsx-runtime.md) §6.4.2.
425
3339
  - **Hardened the dangerous-URL screen.** The URL-attribute filter (on `href`/`src`/`xlink:href`/`formaction`/`action`) now: (1) sees through control-character and whitespace obfuscation of the scheme — a leading ``, an in-scheme `TAB`/`LF`/`CR` (`java script:`), or a `NUL` before the colon are all normalized away before the scheme is read, matching how a browser resolves the URL, so they can no longer slip a `javascript:` past the screen; (2) treats `data:` by subtype instead of only blocking `data:text/html` — script-executing document types (`data:text/html`, `data:image/svg+xml`, XHTML/XML) are dropped while inert media (raster images, fonts, audio, video, plain text/CSS) still pass, and any unknown subtype fails closed; and (3) also screens the `data` attribute on `<object>` (which loads its target as a document). `raw()` remains the opt-out. Both the static serializer and the fine-grained bound-attribute writer share the screen, so both paths are covered.
426
- - **Fine-grained signal bindings.** Hand a `Signal`/`computed` *itself* (not its `.value`) into a JSX attribute (`class={someSignal}`) or a text hole (`{someSignal}`) inside a `mount()`, and kerf binds that hole directly to the signal: when the signal changes, only that attribute/text node updates — the render function does **not** re-run and the list reconciler does **not** walk. This is kerf's fine-grained update tier, sitting below the coarse `mount()` effect, for the "external state drives one spot" pattern (a `selectedId` flipping a row's class, a live status attribute, etc.). Works in static content and inside `each()` rows on both the snapshot and `arraySignal` (granular) paths, and row bindings' lifetimes track their row node (a row reorder is free; a removed row's binding is torn down). Opt-in and non-breaking: passing a raw signal into JSX previously threw, so existing apps are unchanged, and any hole that isn't a signal stringifies exactly as before. Bound URL attributes (`href`/`src`/`formaction`/`action`/`xlink:href`) get the same `javascript:`/`vbscript:`/`data:text/html` screening as static attributes (`raw()` opts out). Outside a `mount()` (SSR / `SafeHtml.toString()`) a bound signal snapshots its current value and emits no markers. See [`docs/2-reactivity.md`](docs/2-reactivity.md) §2.9.
3340
+ - **Fine-grained signal bindings.** Hand a `Signal`/`computed` _itself_ (not its `.value`) into a JSX attribute (`class={someSignal}`) or a text hole (`{someSignal}`) inside a `mount()`, and kerf binds that hole directly to the signal: when the signal changes, only that attribute/text node updates — the render function does **not** re-run and the list reconciler does **not** walk. This is kerf's fine-grained update tier, sitting below the coarse `mount()` effect, for the "external state drives one spot" pattern (a `selectedId` flipping a row's class, a live status attribute, etc.). Works in static content and inside `each()` rows on both the snapshot and `arraySignal` (granular) paths, and row bindings' lifetimes track their row node (a row reorder is free; a removed row's binding is torn down). Opt-in and non-breaking: passing a raw signal into JSX previously threw, so existing apps are unchanged, and any hole that isn't a signal stringifies exactly as before. Bound URL attributes (`href`/`src`/`formaction`/`action`/`xlink:href`) get the same `javascript:`/`vbscript:`/`data:text/html` screening as static attributes (`raw()` opts out). Outside a `mount()` (SSR / `SafeHtml.toString()`) a bound signal snapshots its current value and emits no markers. See [`docs/2-reactivity.md`](docs/2-reactivity.md) §2.9.
427
3341
 
428
3342
  ## [0.16.0] - 2026-07-01
429
3343
 
430
-
431
-
432
3344
  - Fixed keyed-list selection breaking after a row was removed: a signal read only inside `each()`'s `cacheKey` (such as a `selectedId` toggling a row's class) no longer drops out of the reactive dependency set, so later changes re-render correctly.
433
3345
  - Fixed appending items to a list after clearing it rendering nothing.
434
3346
 
@@ -437,115 +3349,90 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
437
3349
 
438
3350
  ## [0.15.5] - 2026-06-30
439
3351
 
440
-
441
-
442
3352
  - Corrected the advertised bundle size in `llms.txt` to ~11 KB minified + gzipped (including the `@preact/signals-core` runtime dependency; ~12 KB with `arraySignal`), matching the README.
443
3353
 
444
3354
  ## [0.15.4] - 2026-06-30
445
3355
 
446
-
447
-
448
3356
  - `llms.txt` is now published at a public docs-site URL and bundled in the npm package, making kerf's AI-assistant documentation index discoverable to llms.txt directories and tooling.
449
3357
 
450
3358
  - The `kerfjs` package now bundles `llms.txt` (the AI-discovery index) at the package root, and the docs site serves it at `https://brianwestphal.github.io/kerf/llms.txt`. Its links are now absolute GitHub URLs so the file is portable across GitHub, the site, and the installed package.
451
3359
 
452
3360
  ## [0.15.3] - 2026-06-30
453
3361
 
454
-
455
-
456
3362
  - `npm create kerf-component` with no directory argument now prompts for the target directory (defaulting to `my-kerf-component`, with a `.` hint for the current directory) instead of printing usage text and exiting with an error.
457
3363
 
458
3364
  ## [0.15.2] - 2026-06-30
459
3365
 
460
-
461
-
462
3366
  - Added the `create-kerf-component` initializer — scaffold a ready-to-publish kerf component package with `npm create kerf-component@latest <dir>`, no need to reverse-engineer the packaging rules.
463
3367
 
464
3368
  ## [0.15.1] - 2026-06-30
465
3369
 
466
-
467
-
468
3370
  - README refresh + eslint rule-count fixes + CHANGELOG hygiene (`cfbaef3`)
469
3371
 
470
3372
  ## [0.15.0] - 2026-06-30
471
3373
 
472
-
473
-
474
3374
  - List updates now morph same-identity rows in place instead of recreating their DOM nodes, avoiding full-table relayout on large lists and preserving DOM identity, focus, and IME composition across re-renders.
475
3375
 
476
-
477
3376
  - New guide on incremental migration: kerf can own a single DOM subtree and coexist with React (or any framework), letting you migrate one island at a time.
478
3377
  - New guide on building and publishing reusable kerf components as npm packages.
479
3378
  - Example app documentation pages now open with an animated SVG preview of the real app in action, plus a gallery on the complete-examples index.
480
3379
 
481
3380
  ## [0.14.0] - 2026-05-27
482
3381
 
483
-
484
3382
  - Fix `toElement()` first-paint divergence in WebKit by adopting its result into the live document
485
3383
  - Fix `mount()` first render in WebKit by adopting an inert `rootEl` into the live document
486
3384
 
487
3385
  ## [0.13.0] - 2026-05-23
488
3386
 
489
-
490
3387
  - Add `KERF_DEV_WARN_DELEGATE_IN_EFFECT` dev warning to catch `delegate()` calls inside reactive effects
491
3388
  - New `require-delegate-disposer` ESLint rule flags `delegate()` calls whose disposer is discarded
492
3389
  - Document `delegate()` disposer gotchas and canonical cleanup patterns
493
3390
 
494
3391
  ## [0.12.1] - 2026-05-22
495
3392
 
496
-
497
3393
  - Add GitHub Sponsors link to README, homepage, and npm `funding` field
498
3394
 
499
3395
  ## [0.12.0] - 2026-05-22
500
3396
 
501
-
502
3397
  - `toElement` now returns `Element | DocumentFragment` to support multi-root inputs
503
3398
 
504
3399
  ## [0.11.1] - 2026-05-21
505
3400
 
506
-
507
3401
  - `attr()` redesign: typed `AttrSpec<N, V>` exposes `.attrs` with dual overloads for cleaner attribute handling
508
3402
 
509
3403
  ## [0.11.0] - 2026-05-21
510
3404
 
511
-
512
3405
  - `attr()` redesigned with `AttrSpec<N,V>` shape, `.attrs` accessor, and dual overloads
513
3406
  - Hardened defensive programming across the runtime for safer edge-case handling
514
3407
  - Refreshed published performance numbers from a fresh cross-framework benchmark run
515
3408
 
516
3409
  ## [0.10.0] - 2026-05-20
517
3410
 
518
-
519
3411
  - Expose `kerfjs/ai/*` subpaths via package `exports` so the bundled skill/cursorrules files are resolvable
520
3412
  - Add a defensive fallback in `kerfjs/ai-assistant-configs` ESLint rule so it fires against installed kerfjs versions whose `exports` block subpath resolution
521
3413
 
522
3414
  ## [0.9.1] - 2026-05-20
523
3415
 
524
-
525
3416
  - Bundle the kerf-app Claude Code skill and Cursor rules inside the npm package at `ai/skill.md`, `ai/cursorrules`, and `ai/manifest.json`
526
3417
  - Add `kerfjs/ai-assistant-configs` rule to `eslint-plugin-kerfjs` (warn in recommended) to flag drift in installed AI assistant configs
527
3418
  - `eslint --fix` now replaces only the canonical section above the `KERF-APP-CANONICAL-END` marker, preserving consumer customizations below it
528
3419
 
529
3420
  ## [0.9.0] - 2026-05-20
530
3421
 
531
-
532
3422
  - Bundle the kerf-app Claude Code skill and Cursor rules inside the npm package at `ai/skill.md`, `ai/cursorrules`, and `ai/manifest.json`
533
3423
  - Add `kerfjs/ai-assistant-configs` rule (warn in recommended) to `eslint-plugin-kerfjs` v0.9.0 to surface AI-config drift on every lint pass
534
3424
  - Canonical-file contract (`kerf-skill-version` + `KERF-APP-CANONICAL-END` marker) lets `eslint --fix` refresh the canonical section while preserving consumer customizations below the marker
535
3425
 
536
3426
  ## [0.8.2] - 2026-05-19
537
3427
 
538
-
539
3428
  - Package `homepage` fields now point to the published docs site, with prominent links in both READMEs
540
3429
 
541
3430
  ## [0.8.1] - 2026-05-19
542
3431
 
543
-
544
3432
  - New `eslint-plugin-kerfjs` with four AST rules enforcing kerf Hard Rules
545
3433
 
546
3434
  ## [0.8.0] - 2026-05-18
547
3435
 
548
-
549
3436
  - Add opt-in dev warning `KERF_DEV_WARN_NARROW_SET=1` that fires when `set()` is called with a partial-state object (replace semantics would silently drop missing keys); names the missing keys and points at the `set({ ...get(), ...next })` merge fix
550
3437
  - Widen `KerfBaseAttrs.contentEditable` to accept `'plaintext-only'` and add the lowercase `contenteditable` alias
551
3438
  - Expand the `/kerf/migrating/` hub to 13 frameworks — adds Vue 3, Svelte 5, Solid, Preact, htmx, Angular, jQuery, Redux, and Astro pages alongside a refreshed 8-framework comparison matrix
@@ -556,7 +3443,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
556
3443
 
557
3444
  ## [0.7.0] - 2026-05-18
558
3445
 
559
-
560
3446
  - Granular list updates now preserve DOM identity, focus, scroll, IME state, `<details open>`/`<dialog open>`, and `data-morph-skip` subtrees across in-place row updates
561
3447
  - Two new fast paths in the granular reconciler cut krausest select-row by 71% (27.8 → 8.2 ms) and partial-update by 28% (46.8 → 33.8 ms)
562
3448
  - `each()`'s third parameter renamed from `key` to `cacheKey` to clarify it's a passive cache-invalidation comparator, not a React-style reconciliation identity; positional callers unaffected
@@ -572,7 +3458,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
572
3458
 
573
3459
  ## [0.6.0] - 2026-05-11
574
3460
 
575
-
576
3461
  - Public `morph(liveRoot, template)` export for standalone DOM reconciliation
577
3462
  - New `data-morph-preserve` attribute to opt elements out of morphing
578
3463
  - New `data-morph-skip-children` attribute — morph host attrs but leave subtree intact
@@ -581,12 +3466,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
581
3466
 
582
3467
  ## [0.5.1] - 2026-05-11
583
3468
 
584
-
585
3469
  - Fix `dist/jsx-runtime.d.ts` IntrinsicElements self-shadow that broke JSX typing in consumer apps
586
3470
 
587
3471
  ## [0.5.0] - 2026-05-10
588
3472
 
589
-
590
3473
  - Add `arraySignal` (`kerfjs/array-signal` subpath) — granular collection signal that drives O(patches) DOM updates for keyed lists
591
3474
  - Faster keyed-list updates: bulk-parse contiguous insert runs and consecutive update patches in the granular reconcile path
592
3475
  - Perf optimizations on the `each()` / `mount()` update path; benchmarks now competitive with Solid/Vue on swap/remove/clear
@@ -600,17 +3483,14 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
600
3483
 
601
3484
  ## [0.4.2] - 2026-05-09
602
3485
 
603
-
604
3486
  - No user-facing changes in this release.
605
3487
 
606
3488
  ## [0.4.1] - 2026-05-09
607
3489
 
608
-
609
3490
  - Just fixing the build
610
3491
 
611
3492
  ## [0.4.0] - 2026-05-09
612
3493
 
613
-
614
3494
  - `delegate()` now auto-promotes the seven well-known non-bubbling events (`focus`, `blur`, `scroll`, `load`, `error`, `mouseenter`, `mouseleave`) to capture phase, with `closest()`-style selector matching preserved
615
3495
  - Fixed focus and caret position loss when reordering keyed `each()` rows on engines that drop focus on `insertBefore` (older Safari, happy-dom)
616
3496
  - `mount()` now throws a descriptive error when the root element is null/undefined instead of a generic "Cannot set properties of null"
@@ -621,12 +3501,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
621
3501
 
622
3502
  ## [0.3.1] - 2026-05-08
623
3503
 
624
-
625
3504
  - Removed stale `morphdom` references; the bundled native diff is now the only reconciler
626
3505
 
627
3506
  ## [0.3.0] - 2026-05-08
628
3507
 
629
-
630
3508
  - Rebuilt render pipeline with structured segments and a native keyed-list diff, replacing the morphdom dependency
631
3509
  - Added `each()` for keyed list iteration with per-item HTML memoization by object identity
632
3510
  - Renamed the npm package from `kerf` to `kerfjs` (the `kerf` name tripped npm's typo-squatting heuristic); the brand, GitHub repo, and Pages URL are unchanged
@@ -637,24 +3515,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
637
3515
 
638
3516
  ## [0.2.1] - 2026-05-07
639
3517
 
640
-
641
3518
  - Add `Fragment` export to the `kerfjs` barrel for explicit JSX fragment usage
642
3519
 
643
3520
  ## [0.2.0] - 2026-05-07
644
3521
 
645
-
646
3522
  - Fix focused contenteditable losing focus/caret during morph
647
3523
  - Fix `SafeHtml` identity mismatch across entry points caused by dist bundling
648
3524
  - Fix `clearStoreRegistry` no-op in built output, restoring test isolation
649
3525
 
650
3526
  ## [0.1.2] - 2026-05-07
651
3527
 
652
-
653
3528
  - No user-facing changes; release tooling fixes only.
654
3529
 
655
3530
  ## [0.1.1] - 2026-05-07
656
3531
 
657
-
658
3532
  - This is just a publication script test
659
3533
 
660
3534
  ## [0.1.0] - 2026-05-07