kerfjs 5.0.0-beta.122 → 5.0.0-beta.124

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 (54) hide show
  1. package/CHANGELOG.md +235 -0
  2. package/ai/cursorrules +17 -7
  3. package/ai/manifest.json +13 -7
  4. package/ai/skill.md +18 -9
  5. package/dist/actions.js +1 -1
  6. package/dist/array-signal.js +1 -1
  7. package/dist/async.d.ts +7 -3
  8. package/dist/async.js +16 -2
  9. package/dist/async.js.map +1 -1
  10. package/dist/chunk-KOEGJCIS.js +65 -0
  11. package/dist/chunk-KOEGJCIS.js.map +1 -0
  12. package/dist/{chunk-3C6F6NM4.js → chunk-KUHXPPJ4.js} +1 -1
  13. package/dist/{chunk-3C6F6NM4.js.map → chunk-KUHXPPJ4.js.map} +1 -1
  14. package/dist/{chunk-YVBK73GU.js → chunk-MFRXN2G4.js} +16 -12
  15. package/dist/chunk-MFRXN2G4.js.map +1 -0
  16. package/dist/chunk-N4VHHOCM.js +27 -0
  17. package/dist/chunk-N4VHHOCM.js.map +1 -0
  18. package/dist/{chunk-BI4HGICV.js → chunk-OWNZCCJX.js} +3 -3
  19. package/dist/{chunk-BI4HGICV.js.map → chunk-OWNZCCJX.js.map} +1 -1
  20. package/dist/{chunk-H7WTRM6F.js → chunk-QOAB2ESQ.js} +2 -2
  21. package/dist/{chunk-H7WTRM6F.js.map → chunk-QOAB2ESQ.js.map} +1 -1
  22. package/dist/{chunk-VX3RCRGG.js → chunk-XL35DIZ2.js} +7 -7
  23. package/dist/chunk-XL35DIZ2.js.map +1 -0
  24. package/dist/{chunk-JN7EJM3B.js → chunk-ZZI5NJIV.js} +2 -2
  25. package/dist/{chunk-JN7EJM3B.js.map → chunk-ZZI5NJIV.js.map} +1 -1
  26. package/dist/dev.d.ts +18 -5
  27. package/dist/dev.js +84 -5
  28. package/dist/dev.js.map +1 -1
  29. package/dist/html.js +2 -2
  30. package/dist/index.d.ts +90 -10
  31. package/dist/index.js +25 -6
  32. package/dist/index.js.map +1 -1
  33. package/dist/jsx-runtime.js +1 -1
  34. package/dist/list.js +3 -3
  35. package/dist/overlay.d.ts +9 -9
  36. package/dist/overlay.js +4 -4
  37. package/dist/overlay.js.map +1 -1
  38. package/dist/remount.js +2 -2
  39. package/dist/router.d.ts +3 -1
  40. package/dist/router.js +18 -9
  41. package/dist/router.js.map +1 -1
  42. package/dist/scope.js +3 -3
  43. package/dist/testing.js +1 -1
  44. package/dist/timing.js +1 -1
  45. package/llms.txt +3 -1
  46. package/package.json +2 -2
  47. package/setup/cli.mjs +3 -2
  48. package/setup/index.d.mts +2 -1
  49. package/setup/index.mjs +112 -75
  50. package/setup/state.schema.json +1 -1
  51. package/dist/chunk-IHMDBBUJ.js +0 -20
  52. package/dist/chunk-IHMDBBUJ.js.map +0 -1
  53. package/dist/chunk-VX3RCRGG.js.map +0 -1
  54. package/dist/chunk-YVBK73GU.js.map +0 -1
package/CHANGELOG.md CHANGED
@@ -6,8 +6,154 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ### Removed
10
+
11
+ - **Pinned TabBarItem support.** Removed `pinned` and its sticky/backdrop tokens and RTL compensation. Put fixed controls in TabBar's existing `leading`, `trailing`, or `end` zones outside the scrolling tablist. Ordinary tabs retain keyboard navigation, selection reveal, reordering, scroll dividers, and optional whole-tab snapping (`KF-K6GKN3`).
12
+
9
13
  ### Added
10
14
 
15
+ - **Kerf UI `ToolbarButton` count badges (KF-HDQTVV).** A ToolbarControlGroup button takes `badge` (a count, short text, or `true` for a dot), `badgeTone` (default `danger`), and `badgeMax` (default 99, so 128 shows "99+"). A count of 0 or empty text shows no badge. Kerf owns the pill's placement just over the icon's top-trailing corner, a 2px ring against the group's surface (the page surface for a borderless group), and 16px sizing at both group sizes, so apps no longer position a `Badge` with their own CSS. A Toolbar zone holding one stops clipping it, because WebKit cut its top off flat. The badge is `aria-hidden`, so the caller names the count in `ariaLabel` and `title` ("Workers, 2 live"). It is plain data, so the Kerf UI editor can author it. The ToolbarControlGroup demo's Corner Count example shows 0, 2, 99+, and a dot at default and compact sizes.
16
+ - **Kerf UI `SummaryRow` `action` (KF-YT6A0N).** A SummaryRow option takes an `action` prop, rendered as `data-action`, as ContentItem and ListItem do. A view document can now name the action a row fires, so the editor's play mode logs it (and hands it to the app's play handler) when the row is clicked or chosen with Enter or Space. A `data-action` in `rootAttributes` still works; `action` wins when both are set. Group rows (`semanticRole="group"`) take no `action`.
17
+ - **The Kerf UI editor's New starts with no root; the root can be deleted (KF-PK3GVY).** New, and the editor's first draft when the host passes no document, no longer seed a Pane. The canvas shows "Start with a component" with a component picker (Pane first) and Add, and the Outline says "No components yet". The chosen component becomes the root, seeded as Replace the root seeds it (a Pane starts with `fill`), and a component dragged from Components onto the empty canvas, or a pasted copy, becomes the root the same way. The root can now be deleted from the Inspector, the context menu, or the Delete key: the document goes back to having no root, keeps its params, slots, and name, and one Undo restores the tree. Replace the root stays as a shortcut. **File format:** `root` is now optional in `kerf-ui-document/v1` (`ui/ai/view-document.schema.json`, `ViewDocument.root?`), so an empty draft autosaves and saves as a document with no `root` field. `validateView` reports it as the new `KUI-V017` ("the document has no root"), so `generateView`, `interpretView`, and `kerf-ui-view` refuse it with that diagnostic, and `previewView` renders nothing.
18
+ - **Kerf UI `PagedView` `pageLabel` localizes the page dots (KF-QSWJGQ).** Each dot's accessible name was fixed English ("Page 2 of 3: <label>"). `pageLabel` is a template string that fills `{index}` (1-based), `{count}`, and `{label}`, such as `pageLabel="Seite {index} von {count}: {label}"`; the default `Page {index} of {count}: {label}` is unchanged. It is a plain string, so the Kerf UI editor can author it. A placeholder inside a page label is spoken as written.
19
+ - **A Kerf UI `PagedView` (KF-0QJ2K3).** `PagedView` (`@kerfjs/ui/paged-view`) pages a sidebar or panel region horizontally between full-size panes, with compact page dots floating in a chrome-material pill at the bottom; page content scrolls beneath the dots and ends clear of them. Touch swipes and trackpad scrolls snap to a page, and the dots work by click and by Left, Right, Home, and End. `wirePagedViews(root, { onPageChange })` (`@kerfjs/ui/wire-paged-views`) reports the chosen page id so the app can own and persist `page`, and scrolls to whatever page a render shows, smoothly unless reduced motion is preferred. The dots are a tablist named "Page 2 of 3: <label>", and off-screen pages are inert.
20
+ - **Kerf UI single-select listboxes get the listbox keyboard (KF-3WS7RR).** A `List selectionMode="single"` listbox is now one Tab stop with Kerf-owned movement, matching the multi-select grid. The new `wireSummaryRows(root)` (`@kerfjs/ui/wire-summary-rows`) handles `SummaryRow` options and `wireContentItems` handles `ContentItem selectionMode="single"` options. The roving `tabindex` sits on the last focused option, else the selected one, else the first, and survives re-renders. Up/Down/Home/End move focus without selecting. Enter or Space selects the focused option by dispatching its click (Space on release, carrying the key's Shift, Ctrl, and Cmd state), so the app's delegated `data-action` handler still owns the selection. Apps can always override a key, in listboxes and grids alike: Kerf skips a key event that is already `defaultPrevented`, so handling the key first (on the option, in the capture phase, or from a listener added to the root before wiring) and calling `preventDefault()` replaces Kerf's movement or activation. The UX catalog wires `wireSummaryRows`. Its SummaryRow and ContentItem listboxes are now one Tab stop each.
21
+ - **A node context menu in the Kerf UI editor (KF-JV7XW1).** Right-click an Outline row or an element on the edit canvas, or press Shift+F10 or the ContextMenu key on a focused row, to select that node and open a menu at the pointer (below the row when opened from the keyboard). The menu offers **Embed in ›**, with the same entries and legality as the Flow area plus Other…, then Move up, Move down, Duplicate, and Delete. Commands that cannot act on the node are disabled. The menu is Kerf UI's own context `PopupMenu`. It does not open in play mode, it leaves click-to-select and drag alone, and focus returns to the row it opened from.
22
+ - **Kerf UI: `List landmark="group"` and `labelledBy` (KF-P9NV94).** A List can now be a named `role="group"` as well as a `region`, and a landmark List can take its name from a visible label with `labelledBy` (its id, rendered as `aria-labelledby`) instead of `ariaLabel`, never both. A read-only field preview grouped under its `FieldLabel` no longer needs a raw `<div role="group" aria-labelledby>`, so the editor can build it; the Text › Read-Only Field Preview demo uses it and has an editor build.
23
+ - **Embed in a NavStack, TabNavigator, or SplitView in the Kerf UI editor (KF-N7K17T).** These layouts have no main zone, so Embed in never offered them. A NavStack or TabNavigator now holds the embedded node in its first view's or tab's content, in place of that view's seeded slot, and a SplitView holds it in its detail pane beside its seeded list. Turning a Pane root into a NavStack no longer means Replace the root and losing the tree.
24
+ - **Embed in for the root in the Kerf UI editor (KF-84CCD1).** The root node's Flow area now has Embed in. The chosen container becomes the new root and holds the whole old tree in its main zone, under the same rule as any other node: it is offered only when the result adds no validation problem. A Pane that becomes the root starts with `fill`, as New's root does. The step is one undo. A node that is a `$each` template or an `$if` branch also embeds in place now.
25
+ - **Kerf UI view documents: `$param` / `$bind` inside list and object values (KF-3QEZFB).** A field inside a prop value, such as a ContentItem's `media.src`, can hold a document param or an `$each` item field, checked against that field's type, so app data sits beside fields the document builds (`media.overlay`). `interpretView` and generated code read it in place. The editor's object form gains **Bind a field**, which binds one scalar field or promotes its literal to a param with that literal as the default.
26
+ - **Kerf UI `List` `landmark="region"` and `ColumnTrack` `ariaLabel` (KF-CW7Z38).** `List landmark="region" ariaLabel="…"` renders a named `role="region"` (a reader, a result picker, a board column) and owns its `role` and `aria-label` over `rootAttributes`; TypeScript requires the name and rejects combining `landmark` with `selectionMode`, and the props catalog records both, so a view document with an unnamed landmark fails validation (`KUI-V004`). `ColumnTrack ariaLabel` names the board's scroller as a `role="region"`, as `SunkenPanel` does; a bare `aria-label` in its `rootAttributes` named a role-less `div` and was not exposed. `ListLandmark` is exported. The List › Document Inset, Result Picker, and List View Transitions demos and both ColumnTrack boards use the props instead of a `role` in `rootAttributes`, and the editor builds Document Inset, Result Picker, and both boards. Text › Read-Only Field Preview (a group named by its label's id) stays unbuilt pending KF-P9NV94.
27
+ - **Kerf UI `List` `selectionMode="single"`: a labeled listbox (KF-MN7QK5).** `List selectionMode="single" ariaLabel="…"` renders `role="listbox"` with that name, for `SummaryRow` options and `ContentItem selectionMode="single"` options, the way `selectionMode="multiple"` renders a multi-select grid; the app no longer wraps rows in its own `<div role="listbox">`. The options keep their Tab stop, `aria-selected`, and Enter/Space activation; the app still owns the selection and any arrow-key movement. TypeScript now requires `ariaLabel` whenever `selectionMode` is set (`ListSelectionMode` is exported), and the props catalog records it, so a view document with a selectable List and no name fails validation (`KUI-V004`). The SummaryRow, Grid › Selectable Document Tiles, and Text › Presentation Roles demos compose `Text variant="span" weight="strong"` instead of raw `<strong>`, and the editor builds all five examples.
28
+ - **Kerf UI `Pane` `scrollAnchoring`; the editor Inspector no longer jumps in Safari (KF-NV427Y).** `scrollAnchoring="none"` opts a Pane's scrolling content out of the browser's scroll anchoring (`overflow-anchor: none`); the default `auto` keeps it. `PaneConfig` forwards it through Workbench panes, CollapsiblePanel, and NavStack views. The editor's Inspector views opt out, because Safari applied a stale anchoring jump to the Inspector about 300ms after an edit inserted a row, when the autosave status reflowed another pane.
29
+ - **Docs: the Worker recipe cancels, disposes, and pools (KF-E6ER9X).** The `kerfjs/async` "heavy app compute in a Worker" recipe is now a `createCompute(spawn, init)` client: a `resource()` run's `AbortSignal` terminates a running job's worker, and the next call starts a fresh one and reloads its resident data through `init`; `dispose()` terminates and rejects pending and later calls, registered on a `kerfjs/scope`; and a short pool snippet sends each call to the least busy worker. No `kerfjs/worker` subpath ships (`docs/27-worker.md`).
30
+ - **Docs: the Worker recipe's `call()` no longer hangs on a failed worker (KF-CP3SZV).** The `kerfjs/async` "heavy app compute in a Worker" recipe now handles the worker's `error` and `messageerror` events: a worker that fails to load or crashes rejects every pending call, and later calls reject at once instead of waiting forever.
31
+ - **Kerf UI embedded popups sit in flow outside a Toolbar (KF-A1Y7SY).** An `embedded` PopupMenu or Select placed directly in a Pane (or any scrolling container) had its preview menu clipped, because an overlay cannot escape a scroller. Outside a Toolbar the embedded popup now sits in flow below its trigger (a Select's listbox before its hint); inside a Toolbar it still overlays so the control band keeps its height.
32
+ - **Editor: the Inspector hides preview-only popup props (KF-TGGSHZ).** PopupMenu `embedded` / `embeddedSubmenu` and Select `embedded` exist for the canvas preview, which sets them itself; authored in a view they would make the app's popup inert, so the props catalog marks them `hidden`. A dialog's `embedded` presentation stays authorable.
33
+ - **Kerf UI `FieldLabel` declares `id` (KF-Q70Q9Y).** `id` was only a pass-through native attribute, so the editor could not author the id a group's `labelledBy` names. It is now a declared prop in the props catalog.
34
+ - **Editor: an object's required switches write `false` (KF-VQTDYG).** Filling in an object prop in the Inspector (a DialogSurface `stack`) now writes `false` for each required boolean whose switch shows off, so the document is valid without turning each switch on and off.
35
+ - **View validation places a ListDetailDialog's toolbar controls in their Toolbar (KF-WBH5P2).** A composition entry's `configTypes` can name one field of a config type (`ListDetailDialogList.toolbar`, `ListDetailDialogDetail.actions`), so a ToolbarControlGroup in a ListDetailDialog's list toolbar or detail actions no longer fails `KUI-L201`, while the column's `content` and `footer` keep their own placement rules.
36
+ - **Kerf UI `PopupMenu` `embeddedSubmenu`; the editor canvas shows the submenu being edited (KF-M2FGPQ).** With `embedded`, `embeddedSubmenu` (a path of `items` indices, one per level) also shows that submenu open, in the document and inert. It sits beside its item with its first row level with the item, as the register places a real one, on the start side for an end-aligned menu, and below its parent menu at phone widths. The item takes its open-submenu fill. While the Inspector edits a place inside a PopupMenu item's `submenu` (`items.2.submenu…`), the edit canvas shows that submenu open. The document, the Inspector, and the export are unchanged. The UX catalog's Embedded Preview menu shows a Group By submenu.
37
+ - **An embedded Kerf UI `PopupMenu` or `Select` keeps no focus fill, and a Select's listbox sits on its control (KF-HVJDWF).** An embedded popup's rows take no focus: a menu's items render as static rows instead of buttons, and a Select's choices and listbox drop their `tabindex`. A click on a row no longer leaves the current-row fill, which looked like a stuck hover or a choice, and on the editor canvas the click still selects the PopupMenu or Select. An embedded Select's listbox now hangs right below the control, over its `hint`, as the real listbox does. The UX catalog's Embedded Preview Select shows a hint.
38
+ - **Kerf UI `PopupMenu` and `Select` `embedded`; the editor canvas shows a selected one open (KF-KN9CPE).** `embedded` renders the popup open at its trigger, in the document instead of the top layer, as a static preview: a PopupMenu's menu at its `placement` (its submenus stay closed), a Select's listbox below the control. It overlays what lies below rather than pushing it aside, so a trigger in a toolbar group keeps its place, and a toolbar's leading zone stops clipping while it holds one. An embedded popup is inert: the registers leave it alone, so its trigger opens nothing and its rows choose nothing, and a menu's items render without their `data-action`. The editor's edit canvas shows the selected PopupMenu or Select embedded, so the `items` or `choices` edited in the Inspector are visible; the document, the Inspector, and the export keep the authored props, and play mode opens the real popup. The UX catalog shows each as an Embedded Preview example.
39
+ - **Kerf UI `Pane` `anchorName` (KF-TBCXTR).** A Pane names its root as a CSS anchor (`anchor-name`) from a dashed ident, so an app names its main column for an anchored `PopoverDialogSurface` without CSS. `PaneConfig` forwards it through Workbench panes, panel panes, CollapsiblePanel, and NavStack views. A value that is not a dashed ident throws.
40
+ - **Kerf UI `PopoverDialogSurface` manual dismiss and anchored docking; transient surfaces on the editor canvas (KF-T1V86Q).** `dismiss="manual"` renders `popover="manual"`, so Escape and a press outside leave a request open until its own controls close it. `anchorName` (a CSS dashed ident) docks the open overlay centered on the bottom edge of the element the application names with that `anchor-name`, inset by `viewportGutter`; engines without CSS anchor positioning keep the centered placement. The editor's edit canvas now shows every PopoverDialogSurface embedded, and play mode names its view root with each `anchorName` the played view references, a placeholder anchor standing in for the application's region. The UX catalog's anchored request popup is now a PopoverDialogSurface instead of an app-owned element with its own CSS.
41
+ - **`eslint-plugin-kerfjs` flags a raw `<form>` (KF-JPE38T).** `ui-preferences` reports a native `<form>` as `KUI-L303` and points at Kerf UI's `Form` with `wireForms`, which keeps a submission from navigating the page. A `Form` rendered without `wireForms` reachable was already reported by `ui-wiring` (`KUI-L401`); that case is now pinned by a test. Kerf UI `Form` gains `labelledBy`, `ariaLabel`, and `describedBy` for a named `form` landmark, and the composer-form recipe renders a `Form` instead of a raw `<form>`.
42
+ - **Kerf UI Button new-tab links get `rel="noopener noreferrer"` (KF-6GBJBP).** An enabled link `Button` whose target is `_blank` (through `link` or `href` + `target`) now renders `rel="noopener noreferrer"`, matching a link `Chip`'s `external`.
43
+ - **Kerf UI Button link emphasis and a `link` prop (KF-RESJ2S).** `emphasis="link"` draws any `Button`, a `<button>` with an `action` or a link, as an inline text link: underlined text in its tone's link color (neutral takes `--kui-color-text-link`) at the surrounding text size, with no fill, border, padding, or control height, keeping its native role and focus ring. It cannot take `pressed`. `link` takes a URL string, a `URL`, or `{ href, target }` and renders an `<a>` that keeps the Button's emphasis; it is the preferred form of `href` + `target`, which keep working, and giving both throws. The Inspector edits `link` as text or as a destination with a target. The ContentItem feed-card demo's raw "Source" anchor is now a link-emphasis Button.
44
+ - **Router `match()` / `activeClass()` notify only the links that change (KF-5P2QAP).** A navigation used to re-evaluate every link's active check; links now share one `setSelector()` over the current path's segment prefixes, so a navigation updates the links that turned on or off and nothing else, however long the nav. Results are unchanged, including `match('/')` staying exact. The router subpath grows by 0.30 KB min+gzip.
45
+ - **`selector()` / `setSelector()` key signals stay current while held (KF-4TXB21).** A key signal read outside any subscriber, such as one a click handler keeps, now returns the current comparison. Before, it kept the answer it had when handed out until something subscribed. Subscribed keys still update at O(1) per change.
46
+ - **Opt-in selector fan-out dev warning (KF-AJ4KG6).** `enableWarnings({ selectorFanout: true })` from `kerfjs/dev` (or `KERF_DEV_WARN_SELECTOR_FANOUT=1` under Node) warns once per signal when three writes in a row each re-evaluate at least 200 `computed()`s and almost none of them (at most 2, or 2%) produce a different value — the per-row `computed(() => row.id === selected.value ? 'danger' : '')` shape that `selector()` and `setSelector()` make O(1). The message prints the write's stack. A broad update whose computeds all change stays silent, and a tick that writes two tracked signals is not attributed. Like `untrackedSignals`, it only covers signals and computeds created after the switch is on. `computed()` is now a thin kerf wrapper over signals-core's (same signature, `watched` / `unwatched` options forwarded).
47
+ - **A Kerf UI `TabPanel` (KF-RE1EBK).** `TabPanel` (`@kerfjs/ui/tab-panel`) renders the application-owned panel a `TabBarItem` controls: `role="tabpanel"` with `id`, `aria-labelledby` from `tabId`, `hidden`, and `busy` (`aria-busy`), plus content `children`, `className`, `slot`, and `data-*` `rootAttributes`. Pair its `id` with the tab's `panelId` and its `tabId` with the tab's `tabId`; selection stays application state, so hide every panel but the selected tab's. It adds no inset, chrome, or layout. The ApplicationTabs catalog demos now use TabPanel and nested `Text` nodes instead of raw `<section role="tabpanel">` and `<strong>` markup, and the Kerf UI editor builds both of them.
48
+ - **A Kerf UI `Form` (KF-XX4Y95).** `Form` (`@kerfjs/ui/form`) renders a layout-neutral native form (`display: contents`, no inset or chrome) with `id`, `name`, `action`, `noValidate`, `children`, and `rootAttributes`. Its `action` is a delegated `data-action` handled on `submit` with `delegateActions(root, 'submit', table)`, not a URL; call `wireForms(root)` (`@kerfjs/ui/wire-forms`) once so a submit Button or Enter in a field never navigates the page. The Kerf UI editor places it from the palette like any container and never navigates on a canvas or play-mode submission, and the ChoiceChips dialog demo uses it instead of a raw form.
49
+ - **`setSelector()` for set membership (KF-1TFHMP).** `setSelector(checked)` over a `signal<ReadonlySet<K>>` returns `(key) => ReadonlySignal<boolean>`; a write diffs the previous set against the next and notifies only the keys that were added or removed, so multi-select, expanded tree rows, or error fields stop re-evaluating every row. A new Set with the same members notifies nothing. Exported from `kerfjs`; it tree-shakes away when unused.
50
+ - **WorkbenchDialog and ListDetailDialog `embedded` (KF-RWJ9KD).** Both render in flow and always shown, keeping their `height`, through DialogSurface's embedded presentation, and the Kerf UI editor's edit canvas shows them that way so their content can be seen and selected. An embedded DialogSurface now also keeps a `height` / `maxHeight` and clips a filling body to its rounded corners as a modal does. It draws a 1px border instead of the drop shadow, which a scrolling pane clipped at its edge (KF-4RSG7D).
51
+ - **DialogSurface `presentation="embedded"`, and dialogs in the Kerf UI editor (KF-SYGSD0).** An embedded DialogSurface is the same panel in flow and always open, without the top layer or a backdrop; `openDialog` / `closeDialog` leave it alone and its close controls do not hide it. The editor's edit canvas shows every DialogSurface embedded, so a closed modal's content can be seen and selected while the document keeps its authored presentation. In play mode a `show-dialog` trigger with `data-dialog-id` opens its dialog modally, with `data-dialog-close`, Escape and the backdrop wired as in an app, and the action is logged.
52
+ - **`selector()` for O(1) row selection (KF-769EW2).** `selector(selectedId)` returns `(key) => ReadonlySignal<boolean>`. Bind `computed(() => isSelected(row.id).value ? 'danger' : '')` in each row: the selector subscribes to `selectedId` once and a change writes only the previous and next keys' signals, where the plain `row.id === selectedId.value` computed re-evaluated every row. Entries are released with the rows that watch them. Exported from `kerfjs`; it tree-shakes away when unused.
53
+ - **`resource()` fetchers can cancel superseded runs (KF-DSXXTD).** A fetcher now receives an `AbortSignal` as its second argument. It aborts when a newer `run()` supersedes the run or `reset()` is called, and never after the run has settled. Pass it to `fetch()` to close a superseded request, or terminate a Worker job; the abort rejection is dropped by the stale guard, so it never surfaces as `failed`. Existing `() => …` and `(report) => …` fetchers are unchanged.
54
+ - **`KUI-L024` / `KUI-L025` analyzer findings.** `kerf-ui-analyze` and `kerf-ui-doctor` report a stylesheet selector naming `.wa-light` / `.wa-dark` / `.wa-invert` / `.wa-theme-default` (use the `scheme` prop or the `.kui-*` scopes), and a `--wa-*` write that nothing reads in a package without `@awesome.me/webawesome`. Writes to the `--wa-*` values Kerf's foundation reads stay legitimate theming. `KUI-L023` also joins the diagnostic ID registry, so profile exceptions for it load (`KF-J0MCPN`).
55
+ - **`KUI-L302` lint finding for Web Awesome scope classes.** `eslint-plugin-kerfjs`'s `ui-preferences` rule reports `wa-light`, `wa-dark`, `wa-invert`, and `wa-theme-default` in a JSX `class` / `className` and points at the `scheme` prop or the `.kui-*` scope classes, since the Web Awesome classes do nothing without its theme. Like `KUI-L301`, it honors profile exceptions (`KF-M2F5K4`).
56
+ - **Kerf-owned appearance scopes.** `.kui-light`, `.kui-dark`, `.kui-invert` and `[data-kui-scheme]` set a subtree's scheme from `foundation.css`, so they work without Web Awesome. `Pane`, `ContentItem`, `NavStack`, `TabNavigator` and its tabs take a `scheme` prop for the plain palette in a fixed scheme; a `tint` implies its scheme, and a disagreeing pair throws. Tinted surfaces now render `data-kui-scheme` and `kui-<scheme>` in place of the Web Awesome `wa-<scheme>` class, which only worked when the Web Awesome bridge was loaded. The bridge re-derives Web Awesome elements inside the Kerf scopes and still honors `.wa-*` (`KF-E44H0A`).
57
+ - **`ListHeader controls` and `List hidden`.** A toggle header names the region it shows or hides with `controls` (reported as `aria-controls` on its trigger), and a List collapses with `hidden`, so a disclosed group is a List instead of a raw `div` and the Kerf UI editor can build the List "Scrollable Application List" demo (`KF-9JACQY`).
58
+ - **Edit and add text runs in the Kerf UI editor (KF-YBMVVM).** A zone that mixes text and nodes holds `#text` runs, but a run's text could not be edited and the only way to make one was **Use as nodes**, so text could not follow a node in a sentence. A selected run's Inspector now edits its text, and a text-accepting zone offers **Text run** in Add a child.
59
+ - **Text `lang` and `ariaLabel` are declared props (KF-AC7AFR).** Text took them only as inherited native attributes, which the Kerf UI editor does not edit, so the Semantic Variants demo's labelled paragraph could not be built. They render the same `lang` and `aria-label` attributes as before.
60
+ - **Button `expanded` (KF-DE348P).** A Button can be a disclosure control: `expanded` renders `aria-expanded`, the application flips it in its `action` handler, and a `DisclosureArrow` makes a natural `icon`. A link Button refuses it, as it refuses `pressed`. The DisclosureArrow demos now use it in place of raw `<button aria-expanded>` elements, so the Kerf UI editor can rebuild them; the editor offers it as a Not set / On / Off Select beside `pressed`.
61
+ - **Pick a ColorSwatches value by swatch in the Kerf UI editor (KF-H1X3S7).** The Inspector's value picker read only a node's `choices`, so a ColorSwatches `value` was a free text field where an author typed `#0a84ff`. `component-props.json` props can now name the sibling list a value picks from (`choicesFrom`, set in the props overlay); ColorSwatches' `value` takes its `swatches`, so it is a Select of swatch labels, and renaming a swatch's value keeps it selected. `check:props` rejects a `choicesFrom` that names no sibling prop.
62
+ - **Rename a param in the Kerf UI editor (KF-1HEZZZ).** Promote to a param names the new param `<ref name><Prop>`, or `node<Prop>` for a node without a ref name, and nothing could change it. A prop bound to a param now shows a **<Prop> param** field: a new name renames the param, keeps its place in `params`, and updates every `$param` reference (bindings, `$each` sources, `$if` conditions, composed inputs). A taken or non-camelCase name is refused in the field.
63
+ - **Set a component's classes in the Kerf UI editor (KF-X8X8VX).** `className` was hidden in the Inspector, so a view could not carry a class such as an appearance scope. It is now a **Classes** field in a trailing **Advanced** section; `component-props.json` marks it `control: "classes"` (also allowed in the props overlay schema). Inner hooks such as `headerClassName` stay hidden.
64
+ - **Text `id` is a declared prop.** Text took `id` only as an inherited native attribute, which the Kerf UI editor does not edit, so a Text could not be built as a link's destination (the ListItem › Native Navigation Link demo's `#list-item-link-target`). It renders the same `id` attribute as before (`KF-86PM4R`).
65
+ - **Text `live` and `rootAttributes`, and Row `ariaLabel`.** A Text readout can be an `aria-live` region and carry `data-*` hooks, and a Row of related controls can name itself as a group. The SearchField demos now use these in place of raw attributes, a raw `<span>` and a raw `<div role="group">`, so the Kerf UI editor can rebuild them (`KF-7V2VGS`).
66
+ - **A TextField end toggle, and Not set in the Kerf UI editor.** `TextField` takes `toggle: { label, icon, pressed, action }`, an icon toggle button inside the end of a single-line field that reports `aria-pressed` and runs its delegated `action` (a password's Show, for example). The editor's Inspector uses it for every optional text prop: the toggle, pressed while the prop is unset, unsets it, and an emptied field now holds the empty string instead of unsetting. A required text prop can be `""`, so ValueTableRow placeholder rows (`value=""`) are buildable (`KF-3Y2GS2`).
67
+ - **An empty zone in a Kerf UI view document is an explicit `null` (KF-YCM09F).** `validateView` accepts an empty zone list for a required prop that takes `null`, and `interpretView` and generated modules pass `null` for any empty zone. SplitView's `detail` composition minimum is now 0, so the editor can build a SplitView with nothing selected by removing the detail's last child. The SplitView demo passes `null` instead of an empty `<div />`.
68
+ - **Switch a list item's kind in the Kerf UI editor (KF-BGKYYH).** An item of a discriminated union list, such as a `ScrollEffect` effect or a `PopupMenu` entry, has a Kind Select in its form: switching a reveal to a scale keeps its `range`, `rangeStart`, and `rangeEnd` and shows the scale's `from` and `to`. So reveal on entry plus fade on exit builds in the effects list editor without JSON. Switching a member no longer carries over the old member's literal discriminant.
69
+ - **Data attributes in the Kerf UI editor, and `KUI-V015` (KF-65FTKX).** The Inspector's Data attributes section edits a component's `rootAttributes` as Name and Value fields with Add and Remove, so a view document can carry app identity such as `data-band`. View documents carry lowercase `data-*` attributes only: `validateView` reports `KUI-V015` for any other key, and for the reserved `data-kerf-*` (the node marker), `data-key` (the row key), and `data-editor-*` names. `dataAttributeProblem(key)` in `@kerfjs/ui/view` names the problem with one key. A document that set a List's `role` or another non-`data-*` key through `rootAttributes` is now invalid.
70
+ - **A new ScrollEffect starts with one effect in the Kerf UI editor (KF-T3PYVC).** A required list whose placeholder items would all be identical, such as a ScrollEffect's `effects` (three stacked `parallax` layers before), now seeds one item. Lists whose items differ keep three numbered placeholders, so a Select's choices and a PopupMenu's items are unchanged.
71
+ - **A new Kerf UI editor document fills the screen (KF-Z70DBC).** New's root Pane, and a Pane chosen in Replace the root, starts with `fill` on, so a new view fills an app's `.kui-app-root` and play mode instead of ending after its content. Turn `fill` off in Properties for a Pane that should take its content's height.
72
+ - **`Pane` `fill`.** `<Pane fill>` takes the full height of a parent with a definite height (an app's `.kui-app-root`, a `SizedRegion`, a grid cell) or the rest of a flex column, so a one-screen app's root Pane reaches the bottom of the screen with its header and footer pinned and its content scrolling between them, the same way a NavStack view or Workbench region fills its Pane. The default is unchanged: a Pane takes its content's height. `docs/app-layouts.md` now says when to use a filled Pane (one screen that never navigates) and when a one-entry `NavStack` (a screen that pushes views or needs the stack's chrome) (`KF-RMEME0`).
73
+ - **Play mode in the Kerf UI editor.** **Play** in the Canvas toolbar runs the document in a stage that hosts a device-sized frame, scaled down to fit the stage (never up) while its viewport inside stays the device's. The view runs with its real wiring: tabs switch, a NavStack's back pops, and Workbench rails and sidebars collapse, all on a play-time copy. **Done** (or Escape while focus is outside the frame) returns to the editor as it was, and the document never changes. The frame loads the host's own editor page with `?kerf-ui-play`, where `createEditor` returns the player, so hosts need no change (`KF-60BEEJ`).
74
+ - **Play mode devices (KF-R7KXSN).** The play bar picks the device the view runs on: an iPhone SE, iPhone 17, iPhone 17 Pro Max, Android (Pixel 8), three iPads, two MacBooks, a 1080p desktop, or Flexible, with each preset's size and safe areas cited to a published source. Phones and tablets rotate and have an **Installed app** toggle: off, the view runs as a browser tab inside the device's safe areas; on, it fills the device and gets the safe areas through `--kui-safe-area-*` on the play page's `:root`. **Scale** is Fit or a fixed 50–150%, which may overflow and scroll the stage. Flexible takes a typed or dragged width and height. Changing devices resizes the running view without reloading it, and the choice is remembered per browser. Hosts add devices through `createEditor({ devicePresets })` or the Vite plugin's `devicePresets` module.
75
+ - **Play mode subtracts the mobile browsers' toolbars (KF-FNQFPJ).** With Installed app off, each shipped phone and tablet now takes its browser's toolbars from the viewport as well as its safe areas: Safari's bottom address bar and toolbar on iPhone (the default iPhone 17 tab is 402×678, was 402×778), Safari's tab and address bar on iPad, and Chrome's toolbar and gesture bar on Android. The heights are estimates of the toolbars fully expanded. The drawn address bar is now a pill at most 40px tall.
76
+ - **Play mode draws a top browser toolbar (KF-YC59PH).** In a browser tab, iPad Safari, Chrome for Android, and the iPhones in landscape now show the status bar at the device's own safe-area height with an address bar below it, instead of a status bar stretched over the whole top band. iPhone portrait, whose toolbar is at the bottom, is unchanged.
77
+ - **Play mode device frames (KF-E8T0AY).** The played view sits in a generic, unbranded mock device: a phone body with a pill cutout, a punch-hole, or a Home button; a tablet; a laptop with a window title bar; or a monitor on a stand. Phones and tablets get a status bar and a home indicator, and a browser tab gets its address bar where there's room. The play bar's Device frame toggle hides the frame without moving or resizing the view.
78
+ - **Play mode actions and the action log (KF-RF6RCS).** A played view's `$action`s call the host's mock handlers. Register them with `createEditor({ playHandlers })` or the `@kerfjs/ui/vite-editor` plugin's `playHandlers` module. A handler receives `{ action, nodeId, event, params, view }` and can set params (re-rendering the view), push or pop a NavStack through `view.navStack(name)`, or open an overlay. A handler that throws is logged, and the view keeps running. The play bar's Action log button shows a count of unseen actions and opens a list, newest first: each action, its node, the event, and whether a handler ran, was missing, or threw. The log keeps 200 entries and clears each time play mode starts.
79
+ - **Play mode starts each NavStack at its root view (KF-BFE3EC).** A played view opens the way an app launches: every NavStack shows its first view, and a mock handler pushes the rest with `view.navStack(name).push(key)`. A "row opens its detail" flow no longer needs a Back first. The editing canvas still shows the view you're editing.
80
+ - **More components respond in play mode (KF-XV732Q).** Workbench panels and ResizableRegions resize, a SplitView collapses on a compact device and pushes its detail from a list row, and value controls (Switch, Checkbox, RadioGroup, Slider, Select, SegmentedControl, ChoiceChips, Combobox, ColorField, ColorPicker, TagField, Disclosure, and a toggle ListItem) keep the person's change across re-renders: in the play copy, in the `$param` the prop reads, or for one `$each` row. A TabBarItem repeated by `$each` selects for its own row, a tab's close removes it, and a sidebar toggled by several actions responds to each.
81
+ - **Play mode keeps nested controls per row (KF-7XQAFR).** A value control inside an `$each` row, not only the row's own root (a Switch in a repeated Row, for instance), keeps the person's change for its row across re-renders. A repeated tab also closes when its `$each` reads a `$bind` (a param object's array, or an outer row's array) instead of a `$param`: the item leaves the param it comes from.
82
+ - **Play mode keeps a repeat-inside-a-repeat's rows apart (KF-ZMBST3).** An inner `$each` row's play-time state is keyed by its row path (the outer rows' keys, then its own), so two inner rows sharing a key under different outer rows no longer share it. Toggling a Switch on tab `a` in group 2 leaves tab `a` in group 1 alone. A TabBar repeated per group selects within its own group, and a closed selected tab hands its selection to a neighbor in the same group. A keyed ref on an inner template still returns the first row with that key.
83
+ - **Play mode selects and closes a placed tab in its own row's bar (KF-36QBFM).** A tab placed directly in a TabBar that repeats per row (not repeated by the bar's own `$each`) was one node shared by every row's bar: clicking it selected it in every bar and cleared the repeated tabs' selection everywhere, and its close did nothing. It now selects for its own row's bar only, and its close hides it there, handing a selection to the row's next open placed tab.
84
+ - **`Select` and `PopupMenu` take a `popupNote` (KF-59BF6C).** Quiet text at the bottom of the open popup, below the choices, announced as the listbox's or menu's description and never an option or item. It wraps to the choices' width and is drawn from the shared popup contract, so both look the same. A toolbar Select, which has no room for a `hint` below its trigger, can now say what its choices leave out: the editor's play bar uses it for the Device menu's "Touch, pixel density, and the on-screen keyboard aren't emulated."
85
+ - **`ScrollEffect` and the shared scroll-effect layer (KF-YCX1XH).** `@kerfjs/ui/scroll-effect` ties compositor-only effects on any content to its own scroll position, with no scroll listener: `effects` takes `parallax` (`lag`), `reveal`, `fade`, `scale` (`from`/`to`), and `dim` (`to`) presets, each over an `entry`, `exit`, `cover`, or `contain` view-timeline range with optional `rangeStart`/`rangeEnd` percentages, nested in array order so transforms stack and opacities multiply. Out-of-range numbers throw a `RangeError`. Only `transform` and `opacity` animate. The named view timeline, the keyframes, and the static fallbacks (no scroll-driven animation support, reduced motion, `data-kui-effects="static"`, `update: slow`, reduced transparency, increased contrast, forced colors) now live once in `@kerfjs/ui/scroll-effect.css`, and `BackdropImage` runs its parallax, progressive blur, and dim on the same layer with unchanged output; `@kerfjs/ui/backdrop-image.css` imports it. There is no blur preset for arbitrary content (a compositor-only blur needs a second copy of the content) and no IntersectionObserver gating.
86
+ - **Show a NavStack's lower view in the Kerf UI editor.** A NavStack's Flow area lists its views under Shown on the canvas; choosing one previews the stack cut back to it, so that view's nodes can be seen, ringed, and dropped into. The document keeps every view (`KF-RMZ2NP`).
87
+ - **Embed in, in the Kerf UI editor.** The selected node's Embed in menu puts it inside a new container in its place: SizedRegion, ListInsetControl, or ListInsetText where each can hold it, or any container from the Other… dialog. A nested whole-screen layout's hint row offers Embed in SizedRegion, and the canvas no longer draws its own frame around such a layout, so it shows the collapse an app would until it is embedded (`KF-6MGYSG`).
88
+ - **View hints.** `validateView` now returns `hints`, non-blocking advice that never makes a document invalid. The first, `KUI-H001`, flags a `NavStack`, `SplitView`, `TabNavigator`, or `Workbench` below the root with nothing giving it a height and suggests a `SizedRegion`. `kerf-ui-view` prints hints without failing, and the Kerf UI editor lists them under Problems (`KF-KQ72TW`).
89
+ - **`SizedRegion` gives a nested whole-screen layout a height.** `NavStack`, `SplitView`, `TabNavigator`, and `Workbench` have no height of their own and collapsed to their bar below an app's root. Wrap one in `SizedRegion` (`@kerfjs/ui/sized-region`): `height="fill"` (the default) takes the rest of a Pane's content, and `minHeight` alone gives a usable height even in content that sizes to itself. (`KF-63XR5K`).
90
+ - **The Kerf UI editor's canvas shows the tab you are editing.** Selecting a node inside a TabNavigator tab's content previews that tab, so its content, selection ring, and drop targets are visible; the document keeps the tab it opens on (`KF-YZPBFH`).
91
+ - **`Button` and `ToolbarButton` open native popovers.** `popoverTarget` and `popoverTargetAction` (`toggle`, `show`, `hide`) make either one the Popover API's invoker, and `ariaHasPopup` reports the popup it opens; a link `Button` refuses `popoverTarget`. The catalog's popover triggers and the anchored request popup's actions now use them (`KF-PAMQNM`).
92
+
93
+ - **`Text` takes `weight="strong"`.** A title or key phrase that matters more than its neighbors renders inside a `<strong>` element (through every wrap, truncation, and line-cap mode), so view documents and the Kerf UI editor can express it instead of raw `<strong>` markup; the demos and recipes use it (`KF-6A9GJ2`).
94
+ - **`ToolbarButton` in `@kerfjs/ui/toolbar-control-group`.** A ToolbarControlGroup's native `<button type="button">` as a component: icon-only with `ariaLabel`, or labeled, with `action`, `pressed`, `disabled`, `title`, and `selectedChrome="none"`. It renders exactly the button the group already styles, so view documents, the Kerf UI editor, and generated code can place toolbar actions (`KF-5ZEYKP`).
95
+ - **A node's problems in its Inspector in the Kerf UI editor.** The selected node's problems lead its Properties, and a field a problem is about, or that a variant hint names, shows it as its error ("To fix: set "label" or "ariaLabel""). The document is validated once per edit for the canvas, the Problems list, and the Inspector (`KF-H782W9`).
96
+ - **Duplicate, copy, and paste in the Kerf UI editor.** The selected node's heading carries a Duplicate action (or press ⌘D / Ctrl+D) that copies it right after itself; ⌘C and ⌘V (Ctrl+C / Ctrl+V) copy a node and paste it after the selection, or at the end of the selected root's main zone. Copies get fresh ids and numbered names (`folderList2`), each is one undo step, and a paste the document cannot take changes nothing and says why (`KF-QAVK73`).
97
+ - **Promote list and object props to params in the Kerf UI editor.** Promoting a list, object, or record prop (a Select's `choices`) makes a param typed exactly as that prop that keeps its current value as the default, so the application can supply the data (`KF-V9V2B6`).
98
+ - **App-supplied functions and models in view documents.** A param typed `{ "kind": "prop", "component": …, "prop": … }` carries a value a document cannot spell (a Select's `renderSelected`, a SearchField's `model`): the generated module types it from the component (`Parameters<typeof Select>[0]["renderSelected"]`), it is optional exactly when the prop is, and it binds only to that prop. The Kerf UI editor promotes such props to these params and previews them with placeholders; `createEditorCatalog({ placeholders })` adds a host's own (`KF-H3CB2P`).
99
+ - **More props edit in the Kerf UI editor.** A Chip's `children` and a ListHeader's `actionIcon` take text or components, an inline object deep in a config (a pane's `compactChromeOpen`) edits as a form, and a nested `data-*` attribute map edits as JSON. The props catalog now records a text-and-markup union as content and keeps inline object fields five levels deep (`KF-24G2KV`).
100
+ - **Field zones: nodes inside prop values.** A view document's zone key can name a content field inside a prop value (`leftRail.content`, `mainToolbar.title`, `views.0.content`); `validateView`, `interpretView`, and generated modules put its nodes in that field, and `fieldZoneOf` resolves such a key. In the Kerf UI editor a Workbench's rails and drawer, a toolbar's title and slots, and each NavStack view's content now take components from Add a child, the outline, and drag and drop (`KF-PD6QC5`).
101
+ - **Workbench rails and drawers in the Kerf UI editor.** A Workbench's (or WorkbenchDialog's) `leftRail`, `rightRail`, and `bottomDrawer` pick Static panel or Navigation panel, then edit that panel's form; switching keeps the label and size (`KF-907BXY`).
102
+ - **Typed choices in the Kerf UI editor.** Props that take one of several kinds of value (a LucideIcon's `size` as a keyword or a number, a Button's `badge`, a Select's `value`), number or boolean enums (`headingLevel`, `tabIndex`), and optional literals (`selectionMode`) now edit in a Select that keeps the value's type, with a text, number, list, or form control for an open member, instead of a read-only row (`KF-3CKTKN`).
103
+ - **Rounded segmented tab strips.** `TabBar` takes `shape="rounded"` with `presentation="segmented"` to draw the strip at the shared control radius, with every tab concentric inside it, instead of a pill track. The Kerf UI editor's Document and Inspector rail strips use it, as the UX review asked. Segmented strips stay pills by default, and the earlier change that drew every segmented tab as a pill is reverted (`KF-YBD6XJ`).
104
+ - **An outlined, compact PopupMenu trigger.** `PopupMenu` takes `emphasis="secondary"` to outline its button trigger like a secondary `Button`, and `size="compact"` for a compact Button's height, so a menu outside a toolbar (an Add menu in a row of actions) matches the buttons beside it. The Kerf UI editor's list editor uses both for its **Add ▾** menu (`KF-MGKDJC`).
105
+ - **Color fields suggest colors in the Kerf UI editor.** A color prop such as a Pane's `background` or a LucideIcon's `color` now shows a color builder placeholder (`uiColor("surface-raised")`) and hint instead of `px(8)` (`KF-PE0PTT`).
106
+ - **Field editors for your own types in the Kerf UI editor.** `createEditor({ fieldEditors })`, or a `src/kerf-ui-field-editors.ts` module beside `@kerfjs/ui/vite-editor`, registers an editor for a named type (`'ShippingWindow'`, `'ListConfig'`) that replaces the type-driven form wherever a prop or field has that type. Its `render(context)` gets the value, its type, `commit`, preset-button and control attributes, and the type-driven `form()` to compose (`KF-EXA2WH`).
107
+ - **A list editor in the Kerf UI editor.** A list of objects or union items (a Select's `choices`, a PopupMenu's `items`, a NavStack's `views`) now opens as one row per item: choose a row to edit that item's form, remove it, drag or Alt+Shift+Arrow to reorder, and **Add** a new item (or pick the kind from **Add ▾** for a PopupMenu's items, headings, and dividers) (`KF-CY1D5W`).
108
+ - **An icon picker in the Kerf UI editor.** A LucideIcon's `icon` (and any icon-data prop or field) now opens a dialog that searches the Lucide icons and shows them; choosing one sets it, and the canvas updates (`KF-VYRDDQ`).
109
+ - **Inline tag and checkbox editors in the Kerf UI editor.** A list of strings (a TagField's `tags`, a ColumnExplorer's `path`) now edits in a TagField and a set of sides (a Pane's `separators` or `safeAreaEdges`) in a CheckboxGroup, instead of JSON (`KF-A9ZHGW`).
110
+ - **Object forms in the Kerf UI editor.** An object prop (a Workbench's `mainFooterList`, a Pane's `tint`) now opens a form built from its type's fields instead of a JSON textarea. A form of at most 10 fields slides into the Inspector, Back returns, and the canvas updates as you edit; a larger one, such as a Workbench's `mainPane`, opens in a dialog. Nested objects open the same way. **Edit as JSON**, **Reset**, and **Fill with example** remain on every form (`KF-Z9S029`).
111
+ - **The Kerf UI editor's component filter stays put.** The Filter Components field now sits in the Document rail's pinned header, under the tab strip, so it stays in view while the Components list scrolls (`KF-PR8MA6`).
112
+ - **Clearer component groups in the Kerf UI editor.** The Components list titles each category with a default `ListHeader` and spaces the categories apart, as the catalog's sidebar does (`KF-K2VP9A`, `KF-YR81M0`).
113
+ - **Every component renders as added in the Kerf UI editor.** A Workbench, SplitView, TabBar, ToolbarControlGroup, FloatingToolbar, and 18 other components showed "cannot render" when added, because their required zones and content started empty. A new node now gets placeholders for them: the zone's own component where the catalog names one (a TabBar gets a TabBarItem), otherwise a `Text` naming the zone ("Main"). Seeded numbers start at their default or 1 (a Grid's `columns`), icon data names a Lucide icon, and list-or-set unions seed a list. Every placeholder can be changed or removed like any other node (`KF-FGD8B3`).
114
+ - **Filter the Kerf UI editor's components.** The Components area opens with a Filter Components field that narrows the palette to components whose name or category holds the text, with an empty state when nothing matches and a clear button (`KF-Y26SKM`).
115
+ - **Edit sizes in the Kerf UI editor.** A List, Row, or Grid `gap`, a layout `flex`, a Spacer or Skeleton `width`/`height`, and a dialog `height` were read-only in the Inspector because they take either a keyword or a css-values builder. They now get a Select of their keywords (spacing tokens in scale order) plus **Custom…**, which opens a field for a builder call such as `px(12)` (`KF-Q5AXNP`).
116
+ - **Replace the root in the Kerf UI editor.** Selecting a document's root offers Replace the root under Children: pick any component (such as a NavStack or TabNavigator, which fill the view only as the root) to start the document from it. Params, slots, and the name stay, and Undo restores the previous tree (`KF-KWQVDJ`).
117
+ - **Item slots in Kerf UI view documents.** `{ "$slot": "name" }` is now valid at a content field inside a prop value, such as a NavStack view's `content`, a TabNavigator tab's `content`, or a row menu's `icon`. The application fills it like a zone's `$slot`: `validateView` checks it, the contract and generated `<Name>Slots` include it, and generated code and `interpretView` render `slots.name()` in place. The editor seeds one for each such required field of a new node, so NavStack, TabNavigator, ListDetailDialog, and ListActionRow render as soon as they are added, and lists them in the outline under their node (`KF-SXDM56`).
118
+ - **Placeholder lists in the Kerf UI editor.** A Combobox, Select, PopupMenu, or any other component added with a required list or object prop now starts with numbered placeholders ("Suggestion 1", "Choice 1", "Item 1") built from the props catalog, so it renders right away instead of reporting `requires "suggestions"`. The Inspector edits those props as JSON checked against their type, and **Fill with example** restores the placeholder for an unset one (`KF-HNNWN9`).
119
+ - **Tabbed rails in the Kerf UI editor.** The Document rail switches between Outline, Components, and Problems (with a count badge), and the Inspector between a node's Properties, Flow (Show, Otherwise, Repeat, Move to), and Children (Add a child, slots), with segmented tab strips instead of one long list. A newly added node opens on its Properties (`KF-MHY1GB`).
120
+ - **Drag components from the Kerf UI editor's palette.** A Components row drags onto the canvas and drops before, after, or inside a node wherever the validator allows, or into the root when dropped on blank canvas (so an empty document takes its first node); the new node has its required props filled and is selected. A click still shows the component's documentation (`KF-78MHM8`).
121
+ - **`ChoiceChips` `overflow="scroll"` for one-row strips.** A section or filter strip can stay on one row that scrolls sideways inside the group, with no scrollbar, so it never wraps the content below it down. `wireChoiceChips` keeps the checked chip in view (scrolling only the group), `wireScrollDividers` fades each edge with chips past it, and the focus ring is never clipped. It cannot be combined with `maxHeight` (`KF-0Q7Q3D`).
122
+ - **The Kerf UI editor's Inspector keeps its tabs in reach.** A selected node's title and its Properties, Flow, and Children tab strip stay pinned under the Inspector's toolbar while a long form scrolls, with a scroll divider (`KF-5QXNWS`).
123
+ - **Drop palette components on the Kerf UI editor's outline.** A drag rests on the Outline tab to open it, then lands before, after, or inside an outline row with TreeList's own indicator. The Document rail's tab strip is now pinned under its toolbar, with a scroll divider. `@kerfjs/ui/wire-tree-list` adds `treeListExternalDrop(root, { canDrop })` so an application's own pointer drag from outside a TreeList can target its rows (`KF-67K2VP`).
124
+ - **Clearer drag feedback in the Kerf UI editor.** A chip naming the dragged component or node follows the pointer, the drop line or ring carries a caption such as "After folderList" or "Inside Pane › content", and a node moved on the canvas dims in place. A line before the first node no longer disappears on the canvas's clipped top edge (`KF-Y4GHQV`).
125
+ - **Every palette component drags in the Kerf UI editor.** Components with required props the editor cannot fill in yet (Select, PopupMenu, Combobox, CornerStatus, ResizableRegion, ListInsetControl, ChoiceChips, and about 40 others) could not be dropped anywhere, because those unfilled props counted as problems the drop would add. A drop now accepts the new node's own unfilled props, unmatched variants, and empty required zones, as Add a child does, and Problems then asks for them; where the node may go still decides (`KF-DC23E9`).
126
+ - **New in the Kerf UI editor.** The toolbar's New starts an empty document (an empty Pane) with no undo history. With autosave it is a new draft, saved at once, and the previous document stays in its own file (`KF-QSSTMX`).
127
+ - **The Kerf UI editor saves every change.** With `createEditor({ storage })` (both editor hosts pass `devServerStorage()`), each change saves through the dev server about 400 ms after it: to an autosaved draft in the project's self-ignoring `.kerf-ui-editor/drafts/` folder until **Save As…** names a `.kui.json` path inside the project, then to that file. The Preview header shows the file and whether it is saved, saving, or not saved (with the reason), and the editor reopens the last file on the next visit. `@kerfjs/ui/vite-editor` serves the file endpoint (`editorFileMiddleware`), which reads and writes only project `.kui.json` files and refuses writes from other sites. With storage, downloading a copy moves to Export's Document (.kui.json) (`KF-0SY9M6`).
128
+ - **`KUI-V014`: controls inside controls.** `validateView` now reports a control, link, or component that renders one placed at any depth in the zones of a component whose root is a control or link, such as a Button in an actionable ListItem's `trailing`. The browser splits that markup, which used to break the row at render time. A composed `#view` document is checked with the enclosing control in force (`KF-71ATXP`). `eslint-plugin-kerfjs`'s `ui-composition` rule, and so `kerf-ui-doctor`, reports the same placement in JSX as `KUI-L205` (`KF-VTFKX8`). The Kerf UI editor's drops and Move to stop offering those places. Selection catalog entries declare the rules as `content.interactive` (`root` or `contains`, optionally only `whenProps` are set, with per-export `content.exports`), projected into `component-composition.json`; every Kerf UI component that renders a native control, link, or label is classified, plus the interactive Web Awesome elements. Component packages declare the same rules under `composition.content` in `kerf.components.json`, which `create-kerf-component` validates and copies; components without them stay unchecked (`KF-0P9WWB`).
129
+ - **A preview that fails to mount no longer breaks the Kerf UI editor.** The canvas preview is rendered and test-mounted outside the editor's render, so a document whose markup the browser splits (a Button nested in a repeated ListItem's description) shows why it cannot be previewed while the rest of the editor keeps responding (`KF-P6FPG2`).
130
+ - **Drag nodes on the Kerf UI editor's canvas.** Pressing a node or slot placeholder and dragging past a few pixels moves it before, after, or inside the node under the pointer (read along a row's flow when its parent lays out left to right), with a line or ring over the canvas for legal drops only; Escape cancels and the ending click does not reselect (`KF-CWDE93`).
131
+ - **Slots select and move like nodes in the Kerf UI editor.** Clicking a slot's canvas placeholder selects it and rings it, and a selected slot moves with the Inspector toolbar's Move up, Move down, and Delete, or by dragging its outline row; the separate Delete slot button is gone (`KF-5RKX3W`).
132
+ - **Drag-and-drop in `TreeList` and the Kerf UI editor's outline.** TreeList nodes take `draggable`, and `wireTreeList(root, { canDrop, onMove })` lets a row be dragged before, after, or inside another row of its tree, painting a line or ring only for drops `canDrop` accepts. `moveTreeListNode(nodes, move)` applies a move to a plain node tree. The editor's outline drags nodes to legal places (beside a node, slot, repeat, or condition, or into a node's first zone that takes it), and the Inspector's Move to picker moves the selected node to the end of any zone it fits, as the keyboard alternative (`KF-WXP6AB`).
133
+ - **Otherwise branches in the Kerf UI editor.** A conditional node's Otherwise show select puts a component in the `$if`'s `else` branch (or removes it), nodes in either branch edit the shared condition and their own repeat, and removing a two-branch condition keeps both nodes. Nodes under a condition that also repeats are now found for prop edits and bindings (`KF-5S56VQ`).
134
+ - **Richer value editing in the Kerf UI editor.** A css-value prop's field lists the builders the prop accepts and how to compose them (`calc(plus(px(8), space("m")))`), and refuses an outer builder the prop does not take. A text-accepting content prop such as a Button's label switches between text and nodes: Use as nodes moves the text into a text node so components can sit beside it, adding a child does the same first, and Use as text moves a lone text run back (`KF-YR91FA`).
135
+ - **Control flow in the Kerf UI editor.** The Inspector's Control flow section shows a node only while a true/false param or item field holds (`$if`) and repeats it for each item of a list (`$each`, with a suggested item name and row key; renaming the item updates the row's bindings). Add a child also adds a `$slot`, declared when new and, inside a row, given the row item as input; a selected slot binds its inputs and can be deleted. Choices are the sources the validator accepts, the outline shows conditions, repeats, and slots, and every change is undoable (`KF-90GTJN`).
136
+ - **Bind props in the Kerf UI editor.** The editor's Inspector binds a prop to a document param or a field of an enclosing `$each` item, offering only the sources the validator accepts for that prop; Not bound clears a binding, and every change is undoable (`KF-K5TKCV`).
137
+ - **`ColumnExplorer` in `@kerfjs/ui`.** `@kerfjs/ui/column-explorer` browses a hierarchy the macOS column-view way: one column of ListItem rows per level in a ColumnTrack, where choosing a row with children opens the next column, and an optional `preview` column shows a chosen leaf. It reads TreeList's nodes, and the app owns the chosen `path` (`treeListPath(nodes, id)`). `layout="paged"` shows one column per page on a phone. `wireColumnExplorer` (`@kerfjs/ui/wire-column-explorer`) adds per-column keyboard navigation (Up, Down, Home, End, Right to open and enter, Left to return, type-ahead) and brings a newly opened column into view (`KF-JY68DQ`).
138
+ - **Run the Kerf UI editor in your app with `@kerfjs/ui/vite-editor`.** `kerfUiEditor()` serves the editor at `/__kerf-ui-editor/` on your Vite dev server only. It previews Kerf UI's components and those your `.kerf-ui-profile.json` catalogs declare, each through the function its catalog names (app-source components too), with your CSS and aliases. Options: `route`, and `registry` (default `src/kerf-ui-registry.ts`) to add or replace component functions. Adding an app component lists its package in the document's `catalogs` (`KF-6GT5QY`).
139
+ - **`@kerfjs/ui/editor`: the Kerf UI editor as a module.** `createEditor({ catalog, document?, save? })` mounts the editor shell (document rail, preview canvas, editing inspector, undo and redo, open, save, export, and compare). `createEditorCatalog({ props, composition, selection?, components })` combines Kerf UI's catalogs with an application package's, and `componentMap(props, modules)` maps each catalog key to its component function from the modules its `import` fields name. Application components appear under Application in the palette, can be added to legal zones, and a component with no registered function previews as a labeled placeholder. The host loads the global stylesheets plus `@kerfjs/ui/editor.css` and registers `@kerfjs/ui/popup-menu/register` and `@kerfjs/ui/select/register` (`KF-6GT5QY`).
140
+ - **`TreeList` in `@kerfjs/ui`.** `@kerfjs/ui/tree-list` shows a hierarchy as ListItem rows indented by depth, with a disclosure arrow on each row that has children: an ARIA tree whose nodes, expansion, and selection the app owns (`action` chooses, `toggleAction` opens or closes). Nodes take icons, descriptions, trailing content, `disabled`, and `hasChildren` for children loaded on demand. `wireTreeList` (`@kerfjs/ui/wire-tree-list`) adds tree keyboard navigation: arrows, Home and End, Right and Left to open, enter, close, and return to the parent, Enter and Space to choose, and type-ahead. `treeListRows` and `treeListPath` expose the model. The Kerf UI editor's outline is now a TreeList (`KF-ECR4XG`).
141
+ - **`FilePickerTrigger` can look like a Button.** Give it `tone`, `emphasis`, or `size` (the same values as `Button`, with the same defaults) and it draws as a Button of those settings instead of the compact link-toned trigger, so an Open picker matches a Save button beside it. It stays a native file label around the hidden input, and keyboard focus on that input shows the Button's focus ring (`KF-W99E6W`).
142
+ - **App-source components in Kerf UI view tools.** `kerf-ui-props` builds a prop catalog for components that live in an application's source (no package export) from their composition entry's `source` file and the app's `tsconfig.json`, recording root-relative imports. `kerf-ui-view` rewrites those imports relative to each document, so a generated view imports `../src/order-card.js` and compiles against the app's own code (`KF-7JP509`).
143
+ - **`rootAttributes` on 36 more components.** Every Kerf UI component with a single root now takes a `rootAttributes` prop for application `data-*` metadata (a row key, a test hook, the editor's node marker), filtered against the component's own protected markers. Affected components: ChoiceChips, CollapsiblePanel, CollapsiblePanelToggle, Combobox, ContentSwap, CornerStatus, DisclosureArrow, EdgeActivityIndicator, EmptyState, FilePickerTrigger, FileDropZone, FloatingToolbar, ListInsetControl, LoadingSpinner, LucideIcon, NavStack, ResizableRegion, SearchField, SegmentedControl, Select, Skeleton, Spacer, SplitView, SunkenPanel, PopupSurface, TabBar, TabNavigator, TagField, Toolbar, ToolbarControlGroup, ToolbarActionLink, ToolbarText, ValuePreview, ValueTable, ValueTableRow, and Workbench. `component-props.json` records each component's `dataChannel`, and the Kerf UI editor can now name and select nodes of all of them (`KF-PYR8XZ`).
144
+ - **Compare with an existing view module.** The Kerf UI editor's Compare picker reads a `.view.ts` your app already imports and lists the contract changes regenerating would make before you export. `readViewHeader` and `kerfjs/no-generated-view-edits` now also detect an edited `kui-contract` header line, not only an edited body (`KF-9J810J`).
145
+ - **Profiles locate prop catalogs.** A `.kerf-ui-profile.json` catalog entry may declare `props`: the package's `component-props.json` (`schemaVersion` matches `kerf-ui-component-props/v<n>`). The `@kerfjs/ui` defaults declare their own. `kerf-ui-view` now discovers the composition and prop catalogs that the profiles above a document declare, so documents can use a component package's components without `--props` / `--composition` flags; `--no-profile` opts out (`KF-S61KAT`).
146
+ - **`previewView` for editor previews.** `@kerfjs/ui/view` adds a lenient renderer for editors. It skips validation and the contract check, and it renders a caller-supplied placeholder for nodes the caller flags as broken or whose rendering throws, so one bad node never blanks the preview. Applications keep using the strict `interpretView`. The Kerf UI editor now previews documents with problems this way (`KF-F355BF`).
147
+ - **Component packages ship `component-props.json`.** `@kerfjs/ui` adds a `kerf-ui-props --write | --check` bin. It generates a component package's structured prop schema, the same format as Kerf UI's own, from the package's composition catalog and built declarations, plus optional inspector hints. Packages scaffolded by `create-kerf-component` get `props:generate` and `props:check` scripts, with `prepublishOnly` regenerating the file, so Kerf UI view tools can validate, inspect, and generate documents that use their components (`KF-B8TGP4`).
148
+ - **Icons in Kerf UI view documents.** A document places a Lucide icon by name with `{ "$icon": "inbox" }` on `LucideIcon`'s `icon` prop, which `component-props.json` now marks with `iconSource: "lucide"`. `validateView` reports misuse or, given a name list, unknown icons as `KUI-V013`. Generated modules import the icon from `lucide` under a collision-free alias, and `interpretView` resolves it from an `icons` map (`KF-91KCPK`).
149
+ - **`kerfjs/no-generated-view-edits` lint rule.** `eslint-plugin-kerfjs` reports a generated Kerf UI view module (`*.view.ts` / `.view.js` / `.view.d.ts`) whose body no longer matches the digest in its `kerf-ui-view` header, a damaged header, or a hand-written module sitting beside a `.kui.json` document. Regenerate instead of editing; behavior and overrides belong in your own files. It is in `recommended` at `error` and ignores CRLF conversion (`KF-BD3ZHQ`).
150
+ - **`interpretView` for server-driven Kerf UI views.** `@kerfjs/ui/view` renders a `*.kui.json` view document at runtime, with the same output as its generated module, given an explicit component map. It first checks the document's contract digest against the `<name>Contract` your app compiled (from a `--declarations-only` module). A served document that changed inputs, actions, slots, or refs throws `KuiContractMismatch`, or renders your `onMismatch` fallback, instead of silently breaking the client (`KF-5G4CNW`).
151
+ - **`kerf-ui-view` generator for Kerf UI view documents.** `@kerfjs/ui` ships `generateView` and a `kerf-ui-view generate | check | diff` bin. They turn a `*.kui.json` view document into a read-only, deterministic `*.view.ts` module that calls component functions directly (no JSX, no build step). The module exports typed inputs, an exhaustive action-handler interface (row actions get the row key), `SafeHtml` slots, refs resolved through a `data-kerf-node` marker, and a contract digest. `check` fails on stale or hand-edited modules, and `diff` lists breaking and compatible contract changes before you regenerate. `--target js` emits `.view.js` plus `.view.d.ts` for no-build apps (`KF-WWJGSN`).
152
+ - **`@kerfjs/ui/view` document validator.** `validateView` checks a Kerf UI view document (`kerf-ui-document/v1`, the editor's JSON source of truth) against the component-props and composition catalogs. It reports `KUI-V001`–`V012` (shape, unknown components and props, values that don't fit their types or variants, missing required props, ids and names, `$param`/`$bind` scope, keyed `$each`, action scope, strictly parsed `$css` builder calls, node-marker channels, composed views) plus the `KUI-L201`–`L204` composition checks the ESLint rule runs on JSX. `ai/view-document.schema.json` ships for editors, and `component-props.json` now marks text-accepting content (`acceptsText`) and `data-*` index signatures (`index`) (`KF-FB9340`).
153
+ - **Structured component prop schema.** `@kerfjs/ui` ships `ai/component-props.json` (plus its schema), generated from the published declarations and Web Awesome's manifest. It lists every component's props in a small type grammar, with required, documented defaults, enum values in source order, zones and content slots, css-value grammars, and the discriminated variants of union props such as Button's icon-only form and ListHeader's toggle mode. Editors, validators, and code generators can read prop shapes without parsing TypeScript. `npm run props:sync` regenerates it, and the package check fails on drift (`KF-8PXPKW`).
154
+ - **One Kerf UI Sketch Library.** `@kerfjs/ui` ships `docs/design/sketch/Kerf-UI.sketch`, with 308 editable light/dark Symbols covering all 110 design-template variants on one page per family. It includes 141 `Kerf/<Theme>/<Role>` Color Variables and Button's shared styles. Its document, Symbol, Text, and Color Variable IDs stay stable across releases, so linked instances sync while keeping overrides. The six family `.sketch` files become build inputs; install `Kerf-UI.sketch` instead (`KF-WW7BNZ`).
155
+ - **Kerf UI Sketch text names SF Pro.** `Kerf-UI.sketch` used Sketch's nameless system font, which Sketch's Embed Fonts settings reported as three Invalid Font entries. It now names SF Pro's Regular, Medium, and Semibold faces, the font production's `system-ui` uses on macOS, so install Apple's SF Pro fonts before adding the Library (`KF-KFV416`).
156
+ - **Decline setup value proposals.** `kerfjs setup --resolve <id>=skip` remembers an unused dependency, script, compiler option, or catalog/profile value per package. Dry runs expose proposal ids, `=kerf` adopts a declined value later, and new authored conflicts still require an explicit conflict resolution (`KF-0TTETG`).
11
157
  - **Stable `StateBanner` root identity.** `rootAttributes` accepts a safe `data-key` so a conditional status banner can disappear before a sibling without replacing the sibling's focused action (`KF-KDF5YG`).
12
158
  - **Native drag on `SummaryRow` options.** `draggable` writes the native attribute on the selectable row or board card root, preserving its option semantics and delegated identity across rerenders (`KF-NHPCWZ`).
13
159
  - **Static diagnostic `SummaryRow`.** `semanticRole="group"` renders a labeled, non-option list row or board card that retains rail and selected visuals while a nested native recovery action owns focus and activation (`KF-H32FQY`).
@@ -111,6 +257,26 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
111
257
 
112
258
  ### Changed
113
259
 
260
+ - **Kerf UI `TabNavigator` tab badges hide a zero count and cap at `badgeMax` (KF-0V773N).** A tab `badge` of 0 or less now renders no badge (and adds nothing to the tab's name), and a count past the new per-tab `badgeMax` (default 99) shows `99+`, using the same helper as `Button` and `ToolbarButton`. Text is still trimmed and shown as written, and non-finite numbers still render nothing. **Behavior change:** a tab that passed `badge: 0` to show a "0" now shows no badge; pass the text `"0"` to keep it.
261
+ - **Kerf UI `Button` badges hide a zero count and cap at `badgeMax` (KF-78EZ8Q).** A `Button` `badge` of 0 or less, or empty text, now renders no badge, and a count past the new `badgeMax` (default 99) shows `99+`, the same rules as `ToolbarButton` (one shared helper, so they cannot drift). `badgeLabel` joins the button's accessible name only while the badge shows. **Behavior change:** a caller that passes `badge={0}` on purpose to show a "0" now gets no badge; pass the text `"0"` to keep it.
262
+ - **AI guidance stops steering toward Web Awesome.** The Kerf skill and Cursor rules (`kerf-skill-version` 1.29.0 / 1.25.0) name the `scheme` prop and `.kui-*` scopes, scope the `webawesome.css` paragraph to the optional integration, and no longer describe `Select` as Web Awesome markup. The `@kerfjs/ui` catalog guidance sends a plain action to `Button` and an ordinary form field to a multiline `TextField` instead of `wa-button` / `wa-textarea`, and the UI skill (1.71.0) labels its `--wa-*` tips as integration-only (`KF-XNKQPX`).
263
+ - **Kerf stylesheets read only `--kui-*` tokens.** Seven Web Awesome theme values Kerf used directly now have foundation tokens that follow them with the same fallbacks: `--kui-font-3xl`, `--kui-font-weight-bold`, `--kui-font-family-heading`, `--kui-font-weight-heading`, `--kui-line-height-condensed`, `--kui-color-overlay-modal` and `--kui-transition-slow`. Dialog, popup and sheet insets read the new `--kui-surface-inset` (8px) and `--kui-container-inset` (16px) instead of the bridge's `--kui-wa-surface-inset` / `--kui-wa-container-inset`, which now alias them for Web Awesome elements only. Override the `--kui-*` tiers to change Kerf surfaces (`KF-0DZ2V9`).
264
+ - **Raw Web Awesome children in Kerf containers are styled by the optional bridge.** No Kerf component renders a Web Awesome element, so the rules for a raw `wa-button` or `wa-dropdown` inside a ToolbarControlGroup, a Toolbar's trailing zone, a popup surface, a Workbench panel, or a ResizableRegion moved from those components' stylesheets into `@kerfjs/ui/webawesome.css`. A Kerf-only bundle sheds about 1.6 KB gzip of selectors that matched nothing, and the catalog no longer loads Web Awesome for Toolbar, TabBar, SurfaceScaffold, PopupMenu, or the composer-form recipe. An app that places raw Web Awesome elements in those containers imports the bridge, as Web Awesome use already requires (`KF-Z2K3RR`).
265
+ - **`KUI-H001` stays quiet in a filled Pane (KF-AMEZB3).** A `NavStack`, `SplitView`, `TabNavigator`, or `Workbench` in the content of a `Pane` with `fill: true` that itself has a height (the root, or inside a `SizedRegion` or layout) no longer gets the "collapses to its bar" hint, since the filled Pane gives it a height. New's root Pane starts filled, so a layout dropped into a new document is no longer flagged.
266
+ - **A StateBanner's action takes Kerf UI Buttons, laid out as a horizontal list.** Put compact pill `Button`s (`size="compact" shape="pill"`) in `action`. A neutral Button takes the banner's tone: a primary one is the translucent tone pill, a secondary one a tone outline, a plain one tone text. Brand, success, and danger Buttons keep their own tone. The action lays out its controls (several Buttons, a `LoadingSpinner` beside one) as a wrapping, end-aligned row, so no `Row` wrapper is needed. Plain `<button>`s still get the pill. The demos, recipes, and guidance use Buttons, and the editor can build a banner action again (`KF-Q87Q17`, replacing `KF-5TGWQG`'s plain-button contract).
267
+ - **`ToolbarButton` can be an avatar button.** In a `ToolbarControlGroup` with `content="avatar"`, a `ToolbarButton` takes `ariaLabel` alone and shows the group's `avatarImage`; its `icon` is optional for that form (`KF-CFWFAE`).
268
+
269
+ - **Overlay render slots for buttons and errors are typed as `data-*` attributes.** `ConfirmRenderSlots`, `PromptRenderSlots`, `FormRenderSlots` / `FormRenderField`, and `ChoiceRenderSlots` type their `ok`, `cancel`, `error`, and `actions` slots as ``Record<`data-${string}`, string>`` (what they always held), so a component that accepts only data attributes, such as a Kerf UI `Button` or `ToolbarButton` via `rootAttributes`, can carry them. Input slots stay `Record<string, string>`; spreading any slot works as before (`KF-YRC20J`).
270
+
271
+ - **`ListHeader` `badge` and `status` take plain text.** Both accept `string | SafeHtml`; ListHeader still wraps each in its own compact Badge, so `badge="New"` replaces `badge={<span>New</span>}` and the Kerf UI editor edits them as text fields instead of suggesting a Badge inside the Badge (`KF-ZYQVHD`).
272
+ - **Promote an app-supplied prop from its own row in the Kerf UI editor.** A function or model prop such as a Select's `renderSelected` showed as a read-only "—"; its row now says the app supplies it and promotes it to a param when chosen. The Promote and Bind lists name props in words (`KF-D85GY0`).
273
+ - **Item forms keep field order in the Kerf UI editor.** In a form for a list item or object (a Select choice), the Icon row and Configure rows now sit where their fields are instead of after every text field, and picking a choice's icon fills its `iconName` with the icon's name until you give it one of your own (`KF-3J47BY`).
274
+ - **Add a child suggests what a zone holds in the Kerf UI editor.** The Component choice lists the components a zone is named for first, under Suggested (a Button's `icon` offers LucideIcon, a `badge` zone Badge), and starts on that suggestion; the rest follow grouped by the palette's categories instead of one alphabetical list of every component. Changing the zone starts its component choice over (`KF-N8TW04`).
275
+ - **A clearer LucideIcon Inspector in the Kerf UI editor.** A LucideIcon's icon comes first, under Icon with its `name`, then Appearance and Accessibility; Inspector rows keep their prop order instead of listing every icon or Configure row after the text fields. A new LucideIcon's `name` matches its icon, and choosing another icon renames it until you give it a name of your own (one undo restores both). The node's own name field is now "Ref name", so it no longer reads like the `name` prop (`KF-DQFXWG`).
276
+ - **Readable field labels in the Kerf UI editor.** The Inspector labels each prop and form field in sentence case (`controlInsets` reads "Control insets", `hAlign` "Horizontal align", `ariaLabel` "ARIA label") instead of its run-together camelCase name, and Configure and Choose rows name their field the same way (`KF-7M4XQR`).
277
+ - **`wa-tree` and `wa-tree-item` are Discouraged.** They now point at `TreeList` (`@kerfjs/ui/tree-list`), and the default application UI profile's `hierarchy-navigation` preference prefers TreeList, so `KUI-L301` steers a hierarchy to it rather than to an exception for Web Awesome Tree (`KF-QMH4F5`).
278
+ - **Compact toolbar groups use compact text.** A `ToolbarControlGroup` with `size="compact"` now sets the 14px text of a compact `Button` (`--kui-font-s`), so its plain buttons, action links, and PopupMenu triggers match a compact Button beside them; before, they kept the default 16px text at the 32px height (`KF-Z8EYHT`).
279
+ - **`ListHeader` action ends on the list's bordered edge.** A full-width header's fitted trailing action no longer sits 4px inside its header to center its glyph on a Pane toolbar slot; its border box now ends flush at the 8px inline margin, on the same edge as a selected or hovered `ListItem` and a Pane header's trailing `ToolbarControlGroup`. Bordered elements in one column align outer edges; borderless nested glyphs align with nested content (`KF-78N7HE`).
114
280
  - **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`).
115
281
  - **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`).
116
282
  - **`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`).
@@ -157,6 +323,75 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
157
323
 
158
324
  ### Fixed
159
325
 
326
+ - **Kerf UI `TabBar`: intrinsic tabs shrink with an ellipsized name before the strip scrolls (KF-VQ1Z8H).** Each `TabBarItem` in an intrinsic strip used to stay at its full width (`min-width: max-content`), so a narrowing bar only narrowed the tab scroller and cut a tab off mid-word at its edge, with no ellipsis. A tab now gives up width by ellipsizing its name down to a minimum of its chrome plus a few characters, and the strip scrolls only once every tab is at that minimum. Leading, trailing, and end zones still never shrink, and a wide bar where everything fits lays out exactly as before: a name shorter than the minimum never widens. The name now sits in a new `kui-tab-bar-item__label`, which sizes it from a hidden generated copy, so the visible name is still the only accessible name. `wireTabBars` gives a truncated tab its full name as a `title` on hover. `nameOverflow="visible"`, placeholder, icon-only, and fill-allocation tabs keep their previous geometry.
327
+ - **Kerf UI `PagedView` keeps its page when its region resizes (KF-W093WV).** `wirePagedViews` now realigns each viewport to its rendered page whenever the viewport resizes, instead of relying on the browser to re-snap. Before, Firefox could be left between pages after a resizable sidebar widened again, and the offset a resize left could be reported to `onPageChange` as if the person had chosen another page.
328
+ - **Kerf UI editor play mode runs the ContentItem and SummaryRow keyboard (KF-963DMT).** Play now installs `wireContentItems` and `wireSummaryRows`, so a played `List selectionMode` listbox or grid is one Tab stop, the arrows and Home/End move focus, and Enter/Space activate the focused option, sending a ContentItem's `action` to the action log as a shipped app does. Media cards also get their load and tint state. `wireContentItems` is now in the component catalog as optional ContentItem wiring, so catalog tooling knows about it.
329
+ - **Kerf UI `SummaryRow`: the keyboard focus ring is drawn inside the row (KF-Q1F3FH).** A focused row drew an outside 24%-alpha shadow ring, so in a list section its neighbors painted over the top and bottom and the section's rounded clip cut the sides, leaving a faint hairline that hid which row had focus once the arrow keys moved it. Row and card options now draw the standard `--kui-focus-ring` inside their own box (a negative-offset outline on an overlay above the leading rail), so nothing around the row covers it, and the selected fill and border still read apart from focus.
330
+ - **Kerf UI `SummaryRow`: a nested action in the title shows its whole focus ring (KF-ETTYMK).** The title's line clamp clips its overflow at the text, so a focused Button inside `title` (a static `semanticRole="group"` row's recovery action) lost the top and bottom of its ring. The clamp box now carries a focus ring's reach as padding offset by an equal negative margin, so the ring fits inside the clip in every engine while the title's layout, line count, and ellipsis are unchanged.
331
+ - **Kerf UI `Select`: an open listbox keeps keyboard focus through a re-render (KF-VJW4XW).** An application re-render that landed while a Select opened could leave focus on the trigger, where Home, End and the arrows are ignored. Focus that falls back to the trigger or the page now returns to the chosen option; focus moved elsewhere stays where it is.
332
+ - **Kerf UI `SummaryRow` ends a clamped title with an ellipsis (KF-KZNNT2).** A title longer than `titleLines` used to stop at its last visible line with no overflow indicator, so a cut at a word boundary read as a complete title. Row and card titles now clamp with `-webkit-line-clamp` and end the last visible line with an ellipsis, while the floated `trailingMeta` still wraps the first line and inline title content still clamps as one paragraph. The title holds its content in one new `kui-summary-row__title-text` block, because WebKit lifts a float out of a line-clamp box. Do not add a clamp or `text-overflow` in app CSS.
333
+ - **Kerf UI view validator: a prop-typed param outside a node's props no longer names an unrelated component (KF-3624D4).** A `$param` / `$bind` typed as a component prop, used in a `$if` condition, a `#text` value, a `#view` prop, or a `$slot` input, was checked against whichever component the validator had visited last, so its `KUI-V004` named an unrelated component and could change when an unrelated node moved. It now reports `a ‹component› "‹prop›" value fits only that prop, not "‹field›"`, whatever comes before it.
334
+ - **Kerf UI view validator: a mismatch message names field zones instead of quoting their nodes (KF-20GMVX).** A `KUI-V004` for an invalid prop value whose field zones hold nodes (a CollapsiblePanel `toolbar`) now writes each zone as `<zone toolbar.leading>` instead of serializing every node inside it. The message stays readable in the Problems rail and the CLI, and editing inside the zone no longer changes it, so the editor's Move to, drops, and Embed in no longer mistake that edit for a new problem.
335
+ - **Editor: selecting a node in a large document is fast again (KF-SFAA5R).** The Inspector's Move to list validated the whole document once per zone on every selection, so a click cost 617 ms at 300 nodes and 7.1 s at 1000. `moveDestinations` now asks the new scoped move check, `createMoveCheck` from `@kerfjs/ui/view`, which re-checks only the source parent, the target parent, and the moved subtree, and falls back to a full validation where only that can tell. Building the list for a node in a flat 1000-node Pane drops from about 9.5 s to 24 ms in Node; the list itself is unchanged.
336
+ - **Editor: a field-level param can be renamed (KF-5ZMAEM).** A field promoted to a param from an object form's Bind a field (a ContentItem's `media.src`) kept its generated name (`nodeMediaSrc`); the form now shows a **Src param** name field while the field is bound to a param, and renaming it updates the param and every prop and field that uses it, as a bound prop's row already did. The Image-Tinted Feed Cards build names its artwork params `skylineUrl` and `skylineBlurredUrl`.
337
+ - **Editor: Bind a field offers params for the first field of an unset object (KF-PTMNSZ).** Binding a ContentItem's `media.src` while `media` was unset listed no source at all, because the result was still missing the required `alt` and that problem rejected every candidate. Source now judges each candidate with the object's other required fields standing in, so the string params that fit `src` are offered and the ones that do not fit stay out.
338
+ - **Editor: a saved document's bytes no longer depend on edit order (KF-YJFMZY).** Save, autosave, and Export's Document (.kui.json) now write each node's props, and every object inside them, in the component's declared prop order. Before, a field landed where it was first written, so a TextField toggle saved `pressed` before or after `action` depending on which was edited first, and an editor build sample re-saved with a different key order. The committed editor build samples are normalized to that order.
339
+ - **Editor: a selection no longer costs the square of the document (KF-ZW633Z).** The outline asked whether each row could be dragged by cloning the whole document for that row, so one click made one full clone per node (611 clones at 600 nodes). Where every node sits is now read from one walk per document version, and the Embed in options validate the unchanged document once instead of once per container. A selection now makes the same three clones at any size, and its remaining work grows linearly with the document: a click in a flat Pane drops from 100 ms to 34 ms at 300 nodes and from 700 ms to 83 ms at 1000 (Chromium, production build).
340
+ - **`each()`'s duplicate-reference error points at the real cause for an `arraySignal` (KF-7HMTZQ).** An `arraySignal` `push()`, `insert()` or `update()` renders through the granular path, which skips the O(N) duplicate check, so the error fired on a later, unrelated render and seemed to blame it. The message now names both indices (`first at index 0, again at index 1`) and, for an `arraySignal`, says the duplicate was most likely added by an earlier mutation. Detection itself is unchanged: an early check would cost O(N) per insert.
341
+ - **A click during a NavStack pop reaches the revealed view (KF-SBP2MV).** While a popped view slid out, it sat over the revealed view and took the pointer, so a click on the revealed view in that moment hit the outgoing copy and did nothing (the Kerf UI editor's Inspector dropped a Configure click right after Back). The exiting view is now `inert` and ignores pointer events for the duration of the slide.
342
+ - **A re-pointed input's `change` fires in WebKit (KF-FMGEJ6).** When a re-render changed a text input's `value` attribute, WebKit kept the value the input was created with as its `change` baseline, so typing that earlier value back fired no `change` (the Kerf UI editor's Inspector lost such commits in Safari). The morph, fine-grained bindings, and the keyed-list attribute fast path now write the live property before the attribute. The end state is unchanged in every engine.
343
+ - **Per-axis gaps in the Kerf UI editor (KF-VA14AP).** A List, Row, or Grid `gap` could hold `{ column, row }` only as JSON after it already held one, so per-axis gaps could not be started. Its size Select now offers **Columns and rows…**, which edits each axis in its own size Select (keywords or Custom…). `validateView` also rejected a token on an axis (`{ column: 'none', row: 'm' }`, `KUI-V004`), because `component-props.json` recorded each axis as a builder-only css-value. A css-values alias that also takes token names now keeps them as literals.
344
+ - **The Kerf UI editor names unnamed object members by what sets them apart (KF-BT1YG0).** A union of object shapes with no type name or literal tag, such as SearchField's `trailingAction` (a disclosure with `expanded`, or a toggle with `pressed`), read "Custom 1…" and "Custom 2…" in the Inspector's type Select. Each member is now named after the fields only it allows: "With expanded…" and "With pressed…".
345
+ - **Badge `ariaHidden` is a switch in the Kerf UI editor (KF-AYX1G2).** `component-props.json` recorded the prop as a `boolean | false | true` union because Badge's labeled and hidden variants narrow it to `false` and `true`, so the Inspector offered a two-item Select. A prop whose variant types are `boolean` and boolean literals now merges into one `boolean`.
346
+ - **The Kerf UI editor names components as authors write them.** The palette, Add a child list, outline and Inspector named an entry's primary component after its catalog title, so `DialogSurface` read "Surface Scaffolds" and `FilePickerTrigger` read "FilePicker". Every component now shows its export name (`KF-9DA687`).
347
+ - **A TabBarItem can be made non-closable in the Kerf UI editor.** `closable` defaults to `true` but did not say so, so `component-props.json` recorded no default and the editor's switch could not write `false`. Its JSDoc now states the default (`KF-X2E1B1`).
348
+ - **Multi-line text props hold line breaks in the Kerf UI editor.** The props overlay's `textarea` control (EmptyState and StateBanner `detail`, Text `children`) was ignored, so every string prop was a single-line field that Enter committed. Those props now edit in a multi-line field that commits on change, and ValuePreview `value` is one of them. TextField's end `toggle` now also works on a multi-line field, pinned to its top end, so an optional multi-line prop keeps its Not set toggle (`KF-8FCJ02`).
349
+ - **A ListActionRow can be an unpressed toggle in the Kerf UI editor.** Its `pressed` edited as a switch, which clears the prop when off, so the editor could not write `pressed: false` (`aria-pressed="false"`). It now has the same Not set / Off / On Select as `Button`, `ListItem`, and `ToolbarButton` (`KF-3T47XJ`).
350
+ - **A ToolbarControlGroup in a MessageComposer's leading zone validates.** MessageComposer draws its controls in a compact Toolbar, and its docs place leading controls in a `ToolbarControlGroup`, but the composition rules allowed a group only in Toolbar, FloatingToolbar or TabBar. So `validateView` reported `KUI-L201` for that documented composition. MessageComposer is now a listed parent (`KF-K1HFS2`).
351
+ - **Default-on boolean props can be turned off in the Kerf UI editor.** `component-props.json` read a default only from a backticked phrasing, so props documented as "(default true)" or "Defaults to true." (Select and PopupMenu `caret`, ColorField and ColorPicker `alpha`, ColorPicker `eyedropper`, BackdropImage `bleedInline`, ToolbarText `ellipsis`) had no default. The editor showed their switch off and could not write `false`. Unquoted `true`/`false` defaults are now read, and Select's `caret` doc states its default (`KF-YNEMFD`).
352
+ - **Turning `multiple` on or off reshapes a Select or ChoiceChips value in the Kerf UI editor.** A picked value became the wrong shape when `multiple` changed. Now one value becomes a one-entry list and a list keeps its first entry, in the same undo step. Renaming a choice's value also renames it inside a list value (`KF-E3MN4B`).
353
+ - **A prop typed with a lone `true` or `false` no longer offers the other boolean.** `component-props.json` folded any boolean literal in a union into `boolean`, so the Kerf UI editor offered `false` for Button's `badge` (`string | number | true`) and `true` for Combobox's `createLabel` (`string | false`). A lone literal now stays a `literal` member (`KF-FY62FK`).
354
+ - **The Kerf UI editor picks several values for an array `value`.** A CheckboxGroup's value, and a ChoiceChips value once `multiple` is on, now get a checkbox per choice instead of a single-choice Select that wrote one string of the wrong type; none checked is `[]`. A required string value (SegmentedControl) can also be set to `Empty ("")` for its no-selection state (`KF-8MEWP2`).
355
+ - **A TextField's spell checking can be turned off in the Kerf UI editor.** Browsers check spelling when `spellcheck` is unset, and the Inspector's switch cleared the prop when turned off, so `spellcheck: false` couldn't be written. It now edits as a Not set / Off / On select, as a toggle's `pressed` does (`KF-38KD5N`).
356
+ - **"Add to …" in a nested form adds to that field in the Kerf UI editor.** A content field inside an object prop that was not yet set, such as a SplitView's Compact stack › List › Toolbar › Trailing, wasn't treated as a zone of the node. So **Add to trailing** said "Every zone of this component is full" or put the child in another zone (`compactStack.backIcon`), which left the document invalid. The field's form now adds to the field itself (`KF-KAVBDD`).
357
+ - **An empty Toolbar's zones stay apart on the Kerf UI editor canvas.** In a narrow column, such as a SplitView's list, the Leading, Center, and Trailing placeholders each kept a 160px minimum and drew over one another, so a drop aimed at Leading landed in Center. A placeholder now never grows past its zone, so each zone is its own drop target (`KF-K3EKKF`).
358
+ - **Embed in no longer writes an empty `props` object in the Kerf UI editor.** A container with no props of its own, embedded through Flow › Embed in (a List or a ContentItem from Other…), exported as `"props": {}`; it now has no `props` key, as when it is dropped from the palette (`KF-QX497W`).
359
+ - **A Workbench panel's nested forms open in the Kerf UI editor.** In a static or navigation panel's form (a rail or the bottom drawer), Configure toolbar, Configure pane, and the other nested object rows did nothing; the type at a path inside a union-typed prop now follows the member the value holds, so those forms open and their fields write inside the panel (`KF-EZN7H2`).
360
+ - **A `$bind` into a param with a default uses the default (KF-8P3H7F).** `{ "$bind": "data.tabs" }` over a `data` param with a default read the raw input, so an app that omitted the optional `data` (and the editor canvas, which samples only params without a default) threw "Cannot read properties of undefined" in `interpretView`, `previewView`, and the generated view module. A `$bind` path now starts from the param read the way `$param` reads it, `(inputs.data ?? <default>)`, in the interpreter and the generator alike; `null` takes the default too.
361
+ - **A repeat inside a repeat's row renders (KF-CFA1S1).** An `$each` inside another `$each`'s template, such as a TabBar per group repeating `group.tabs`, threw in `interpretView`, `previewView`, and the generated view module, because kerf refuses a keyed `each()` inside a row render; the editor canvas showed "This document cannot be previewed". The inner repeat now renders as a plain `.map()` that re-renders with its row, in the interpreter and the generator alike, and its rows still carry `data-key`. A `#view` in an `$each` row whose document has its own top-level `$each` cannot work that way (its module can't know it is in a row), so `validateView` reports it as the new `KUI-V016`.
362
+ - **Icon-only buttons look complete on the Kerf UI editor canvas.** A Button or ToolbarButton with an icon and no text showed a full "is empty — drag a component here" stand-in that swamped its toolbar; a node holding something in another zone now shows its main-zone stand-in only while it is selected (`KF-6EV4Q5`).
363
+ - **Toolbar controls in a view's toolbar validate.** A `ToolbarControlGroup` in a NavStack view's (or a Pane's or Workbench's) toolbar config renders inside that Toolbar, but `validateView` reported `KUI-L201` for it and the editor showed the layout as unable to render. Composition entries can now name the config types they render (`configTypes`), and a content field inside one is placed in that component (`KF-THTR71`).
364
+ - **The Kerf UI editor's selection ring no longer marks the wrong content.** Selecting a node in an inactive tab drew the ring over the active tab's content at the same place; the ring now hides while the selected node can't be seen (`KF-ZC9EXM`).
365
+ - **The Kerf UI editor recognizes a dot-badge tab.** A TabNavigator tab with `badge: true` was listed as a count-badge tab and edited with the count form; a union member whose literal the value carries now wins over an earlier member that only tolerates it (`KF-2XH5XS`).
366
+ - **A list item's typed choice takes an open value in the Kerf UI editor.** Picking Number… or Text… for a field such as a tab's badge in a Configure dialog used to change nothing; it now sets the value and shows its control, as a typed choice in the Inspector does (`KF-ZAQQFK`).
367
+ - **Drop into a tab's content on the Kerf UI editor canvas.** A selected node's seeded item slots (a TabNavigator tab's or NavStack view's content) show as drop stand-ins named after the slot, and a drop there fills the content. Before, the canvas showed only the slot's name, and a drop into its field zone was refused (`KF-HGG7MJ`).
368
+
369
+ - **The Kerf UI editor's outline keeps a node's item content in item order.** A filled field zone (tab 1's content) is listed among the remaining item slots in tab order, rather than after them (`KF-KA5B40`).
370
+
371
+ - **The Kerf UI editor can make an unpressed toggle.** `pressed` on `Button`, `ListItem`, and `ToolbarButton` edits with a Not set / Off / On Select instead of a switch, because unset means a plain action and `false` means a toggle that is off (`aria-pressed="false"`). Off now writes `pressed: false` (`KF-K9VBB4`).
372
+ - **Turning a switch off in the Kerf UI editor clears its prop.** An optional boolean switched back to its default (`showValue` off) no longer leaves `showValue: false` in the document; a prop that defaults on still records `false` (`KF-K03GBN`).
373
+
374
+ - **The UI evaluator names a failed screenshot capture.** When a full-page capture fails after a context's checks ran, `KUI-B001` now says the screenshot could not be captured and suggests a longer timeout, instead of telling you to check that the app is running (`KF-G8KKNY`).
375
+
376
+ - **Kerf UI editor zone labels count items from 1.** A field zone read `views › 0 › content` while the item slot it replaces, and the `View 1` row that edits it, counted from 1; zone labels now read `views › 1 › content` too (the document keeps its 0-based `views.0.content` key) (`KF-3N67HR`).
377
+ - **The Kerf UI editor icon picker shows each Lucide icon once, by its own name.** Lucide exports 255 aliases (`ArrowDownAz` for `ArrowDownAZ`, `Filter` for `Funnel`), which showed as duplicate tiles, and `ArrowDownAZ` was named `arrowDownAZ`; the picker now offers one tile per icon under Lucide's canonical name (`arrow-down-a-z`, `funnel`) while an alias still finds it in a search (`KF-NTK7YW`).
378
+ - **Clearing a Kerf UI editor field commits in Safari.** When a node's problems appeared above its Inspector controls, the re-render turned one prop's input into another's; WebKit then fired no `change` for the next clear, so a cleared `label` stayed set. Each control is now keyed by its prop or field (`KF-QCBJ4F`).
379
+ - **A content field in a Kerf UI editor item form leads to its field zone.** In a SegmentedControl choice’s form, `Content` read “KerfUiContent” and did nothing; it now adds to that choice’s field zone (opening Children with the zone chosen when nothing is suggested), or names and selects the nodes there, like a top-level content row. A field seeded with an item slot (a NavStack view's `content`) names the slot instead of showing its JSON, and nodes added from the row take the slot's place (`KF-VSWT2Q`, `KF-1ZSW5J`).
380
+ - **New nodes in the Kerf UI editor no longer write a `false` variant discriminant.** Dropping a ListHeader exported `toggle: false` and a Select `multiple: false`, restating defaults the validator already assumes when a prop is absent; seeding now leaves them unset (`KF-RRVYCG`).
381
+ - **The Kerf UI editor says why a drop is not allowed.** Dragging a component or node where it cannot go drew nothing and dropped nothing; the drag caption now names the reason in words while the pointer rests there ("ToolbarControlGroup goes in Toolbar or FloatingToolbar or TabBar", or "cannot go here") (`KF-6RYJ64`).
382
+ - **Toolbars and toolbar groups in the Kerf UI editor.** A new ToolbarControlGroup starts with a ToolbarButton instead of a stray Text, and Add a child in a group suggests ToolbarButton then ToolbarActionLink. A container with no main zone (a Toolbar) shows a placeholder for each empty zone ("Leading — drop here", "Center", "Trailing") while it is empty or selected, and a drop on one lands in that zone (`KF-7BB55F`).
383
+ - **A Select's value picks from its choices in the Kerf UI editor.** The `value` of a component with literal `choices` (Select, SegmentedControl, RadioGroup, …) is now a Select of those choices instead of a free text field labeled "Value value"; renaming the selected choice's value carries the value along in the same undo step, and a value that names no choice is shown as such with a hint. Props that take several kinds of value label the kind "<Prop> type" and the value "<Prop>" (`KF-9AWGPS`).
384
+ - **`validateView` accepts `$icon` and `$css` inside list and object values.** A Select choice's `icon` or `color` set in the Kerf UI editor was rejected with a type mismatch that dumped the whole `choices` value, although `interpretView` and the generated module already handled them (`KF-3J9GJV`).
385
+ - **Variant problems say how to fix them in the Kerf UI editor.** A node whose props fit none of its component's variants listed only "props match none of its variants"; the Problems list and banner now add what would fix it, such as `set "label" or "ariaLabel"`, `remove "ariaLabel" or "label"`, or `set "toggle" to false` (`KF-TVZ06Y`).
386
+ - **A gutter around the Kerf UI editor's canvas.** The preview sat flush against the canvas edges, so the selection ring of a node at the edge was drawn over its content; the canvas now leaves a small gutter so the ring and drop lines show whole (`KF-C4EW1V`).
387
+ - **Node-only content props are editable from Properties in the Kerf UI editor.** A prop that takes only components, such as a Button's or ListItem's `icon` or a ListItem's `trailing`, showed as a read-only "—". Its row now adds the component the zone calls for (a LucideIcon for an icon) and selects it, or opens Children on that zone when there is no single choice; once filled, the row names what fills it ("LucideIcon · plus") and selects it (`KF-5T3TE4`).
388
+ - **The Kerf UI editor's icon picker focuses its search.** Opening Choose icon puts focus in the search field, so typing a name filters the icons at once (`KF-GQHRC0`).
389
+ - **Empty containers show on the Kerf UI editor canvas.** A container whose main zone holds nothing (a new document's Pane, a Row just dropped in) previewed with no size, so it could not be seen, clicked, or dropped into. It now shows a placeholder ("Row is empty — drag a component here") that selects the node and takes a drop; the document is unchanged (`KF-ZWJHJR`).
390
+ - **Drops land in a node's main zone in the Kerf UI editor.** Dropping a component on blank canvas, or inside a node, now fills the zone its `children` render into (a Pane's content) before any other, and Add a child starts on that zone, instead of the first zone listed (a Pane's header) (`KF-W10DXQ`).
391
+ - **`@kerfjs/ui/styles.css` now holds the whole root-barrel layer.** It left out the stylesheets of `ListInsetControl`, `ListInsetText`, `SunkenPanel`, and `FloatingToolbar`. A root-barrel import paired with `styles.css`, as the Kerf UI editor's canvas does, therefore rendered those components unstyled: a `ListInsetControl` had no inset. The component-integrations check now fails when a root-barrel component's stylesheet does not reach `styles.css` (`KF-H29W31`).
392
+ - **Singular counts in the Kerf UI editor's preview header.** A document with one node or one problem now reads "1 node" and "1 problem" instead of "1 nodes" and "1 problems" (`KF-X2YQZE`).
393
+ - **A toggle `ListHeader`'s disclosure arrow lines up with its rows' trailing icons.** The arrow was centered in a 24px layer, 3px inside the trailing content edge of the `ListItem` rows below it. The layer now hugs the 18px arrow, so it ends on the toggle's 1px border + 8px padding, the same inset as a row's trailing icon, at standard and compact density (`KF-HZKKK9`).
394
+ - **UI doctor KUI-L401 honors view-scoped exceptions from app entries.** A declared application entry keeps each component use's source file when checking missing wiring, so a narrow exception on one view does not move to the entry or suppress another view's warning (`KF-5X91JH`).
160
395
  - **Live Markdown editor at phone width.** The editor and preview stack into full-width, independently scrolling panes on narrow screens; tablet and desktop keep the side-by-side layout (`KF-HR730P`).
161
396
  - **UI doctor KUI-L401 respects `ChoiceChips` modes.** Radio and toggle modes no longer require `wireChoiceChips`; listbox and dynamic modes still do. Entry-point wiring remains recognized when bundle entries are declared in `.kerf-ui-profile.json` (`KF-KCM28K`, `KF-CYYR43`).
162
397
  - **Site audit accepts the patched DOMPurify release.** The documentation site's direct dependency and lockfile now use DOMPurify 3.4.17, resolving the reported sanitizer advisories while keeping the audit policy and Markdown editor behavior intact (`KF-VB4EXK`).
package/ai/cursorrules CHANGED
@@ -1,4 +1,4 @@
1
- <!-- kerf-skill-version: 1.24.0 -->
1
+ <!-- kerf-skill-version: 1.27.0 -->
2
2
 
3
3
  # kerf.cursorrules — rules for building apps with kerf
4
4
 
@@ -65,15 +65,18 @@ match Hot Sheet 2 and Web Awesome: override `--kui-color-*` globally or
65
65
  component properties such as `--kui-state-banner-background` at a tone or
66
66
  instance boundary, for theming only.
67
67
 
68
- For Web Awesome's broader free component set, import the CSS-only
69
- `@kerfjs/ui/webawesome.css` theme once, then import only each Web Awesome
70
- component module the app renders. The theme registers no component JavaScript
71
- and remains overridable through later or scoped `--wa-*` values.
68
+ Scope a subtree to the light or dark palette with a component's
69
+ `scheme="light" | "dark"` prop or Kerf's `.kui-light` / `.kui-dark` /
70
+ `.kui-invert` classes; they need no Web Awesome CSS. Only with the optional
71
+ Web Awesome integration: import the CSS-only `@kerfjs/ui/webawesome.css` theme
72
+ once, then only each Web Awesome component module the app renders. The theme
73
+ registers no component JavaScript and remains overridable through later or
74
+ scoped `--wa-*` values.
72
75
 
73
76
  `Select` is pure markup until the app explicitly imports
74
77
  `@kerfjs/ui/select/register`. Do that once in the application entry that uses
75
78
  Select; never hide registration inside a component. Web Awesome is an optional
76
- peer and stays out of bundles that use neither Select nor the Web Awesome theme. More detail ships at
79
+ peer that only the `@kerfjs/ui/webawesome.css` theme touches. More detail ships at
77
80
  `node_modules/@kerfjs/ui/ai/skill.md`.
78
81
 
79
82
  ## Public API — one import path
@@ -83,7 +86,9 @@ import {
83
86
  signal,
84
87
  computed,
85
88
  effect,
86
- batch, // reactivity
89
+ batch,
90
+ selector,
91
+ setSelector, // reactivity
87
92
  defineStore,
88
93
  resetAllStores, // stores
89
94
  mount,
@@ -112,6 +117,8 @@ if (import.meta.env.DEV) await import("kerfjs/dev");
112
117
  | `computed(fn)` | derived value (read-only) |
113
118
  | `effect(fn)` | side effect that re-runs on signal change |
114
119
  | `batch(fn)` | coalesce multiple writes into one re-run |
120
+ | `selector(source)` | keyed equality at O(1) per change: `selector(selectedId)(row.id).value` is true for the selected row; one subscription instead of one per row |
121
+ | `setSelector(source)` | membership in a `ReadonlySet` signal; a write notifies only the added/removed members (multi-select, expanded rows) |
115
122
  | `defineStore({initial, actions})` | named multi-consumer state |
116
123
  | `resetAllStores()` | reset every store (test teardown) |
117
124
  | `mount(el, render)` | bind reactive render to a DOM element; returns a disposer |
@@ -251,6 +258,9 @@ mount(listEl, () => (
251
258
  )}
252
259
  </ul>
253
260
  ));
261
+ // Large list: `const isSelected = selector(selectedId)` (from "kerfjs") and
262
+ // `computed(() => (isSelected(row.id).value ? "sel" : ""))` — one subscription
263
+ // to selectedId instead of one per row, so a selection flip is O(1).
254
264
  ```
255
265
 
256
266
  ## Common errors → fixes
package/ai/manifest.json CHANGED
@@ -1,13 +1,13 @@
1
1
  {
2
- "kerfjsVersion": "5.0.0-beta.122",
2
+ "kerfjsVersion": "5.0.0-beta.124",
3
3
  "files": [
4
4
  {
5
5
  "name": "skill",
6
6
  "source": "kerf.claude-skill.md",
7
7
  "bundle": "ai/skill.md",
8
8
  "dest": ".claude/skills/kerf-app/SKILL.md",
9
- "version": "1.28.0",
10
- "sha256": "95a803e82a234dda363f468511bf64247c89798c1af8a1c62d082b40627f41aa",
9
+ "version": "1.31.0",
10
+ "sha256": "9880f36aa1994da1b02c35fed72079d2484c0f384f68e22ae47d0634b233a1cb",
11
11
  "history": {
12
12
  "1.0.0": "bef982cb743fd4c73e666ee5cf774112e57c93ebb13b24bbacbf08577db0930a",
13
13
  "1.1.0": "f2aadb21e33dd389028951ae1ecbd9f8ba68648b3c5beba43fb4dfa2ab29f195",
@@ -43,7 +43,10 @@
43
43
  "1.25.0": "bc2622cb12b382118e44aa50d1afb058252e0caf85b7c0ced4433bc0ca76f7c1",
44
44
  "1.26.0": "64a86a36399d12e5803a050c116d32d8762608d91ec9222670592ff471bc64b8",
45
45
  "1.27.0": "7cc6a566cbe08023079731b98166e3c5e49160a8844358f928acf3ee0654092c",
46
- "1.28.0": "95a803e82a234dda363f468511bf64247c89798c1af8a1c62d082b40627f41aa"
46
+ "1.28.0": "95a803e82a234dda363f468511bf64247c89798c1af8a1c62d082b40627f41aa",
47
+ "1.29.0": "1816494efdc7e3b15d9c5213988477f68f82c5c2a2e4a685956500845ae5cc90",
48
+ "1.30.0": "2e78139920bbb6e6fd1e396cd6ed3edf772cfdbd2f0eb84d0c3077f9cd2035c6",
49
+ "1.31.0": "9880f36aa1994da1b02c35fed72079d2484c0f384f68e22ae47d0634b233a1cb"
47
50
  }
48
51
  },
49
52
  {
@@ -62,8 +65,8 @@
62
65
  "source": "kerf.cursorrules",
63
66
  "bundle": "ai/cursorrules",
64
67
  "dest": ".cursorrules",
65
- "version": "1.24.0",
66
- "sha256": "9578b5141b417b10560a426086c0f8dad3bd6a302f2856bea4808be7d02ef0d3",
68
+ "version": "1.27.0",
69
+ "sha256": "e8d8a56ed88ee427c2edc9ddfb4358780e19ea70c0feeae4e052d8b7c4520aae",
67
70
  "history": {
68
71
  "1.0.0": "98f7faff2b7585ef9cc511add42ea5d9bf0cbae8307b066af090e9281136d2ab",
69
72
  "1.1.0": "a2ec8c221dc694c98b81009cd2d99f9159a45fda94585de2f54471b227099eda",
@@ -95,7 +98,10 @@
95
98
  "1.21.1": "9b3eb825a7bec05bb6f0138f77b45fadf896b83020178c34c5a2f531c38f4dee",
96
99
  "1.22.0": "3515c663e908b2d6dc9a2a9cf42f2a5bf9a5b3a10c79d43e30cc8427e2ce209d",
97
100
  "1.23.0": "dad6f677c85bf01760da6694afb7ead1439f0e1f0298ba8dac65de44ba031848",
98
- "1.24.0": "9578b5141b417b10560a426086c0f8dad3bd6a302f2856bea4808be7d02ef0d3"
101
+ "1.24.0": "9578b5141b417b10560a426086c0f8dad3bd6a302f2856bea4808be7d02ef0d3",
102
+ "1.25.0": "c52120502cc76fa5c6588a551b1d7f8097e2f6cd8a496d30a8bad0e103ea37db",
103
+ "1.26.0": "a583bad7217181229f7bc7047a472f87867738d9514f926dc9805b7e2443d8c2",
104
+ "1.27.0": "e8d8a56ed88ee427c2edc9ddfb4358780e19ea70c0feeae4e052d8b7c4520aae"
99
105
  }
100
106
  }
101
107
  ]