kerfjs 5.0.0-beta.55 → 5.0.0-beta.57

package/CHANGELOG.md

@@ -6,6 +6,665 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 ## [Unreleased]
 
+- **`ui-public-boundaries` inspects `kerfjs/html` tagged templates.** The
+  no-build `html` template writes the same markup as JSX, so its static
+  `class` attributes now carry `KUI-L101` (private `kui-*` anatomy) and
+  `KUI-L103` (a component's anatomy on your own element):
+  ``html`<aside class="kui-pane">` `` is reported with `Pane` to render, and a
+  plain ``html`<div class="kui-content-item">` `` with `ContentItem`, while a
+  `<ul>` carrier keeps the placeable class. The template's static parts are
+  read by the runtime's own rules; a class a hole supplies (`class=${cls}`)
+  is unknown and skipped.
+
+- **`KUI-L103`'s "render X instead" answer has one implementation.**
+  `@kerfjs/ui` ships `ai/component-class-owners.cjs`, the rule that decides
+  which cataloged classes are a component's anatomy and which export renders
+  each. `eslint-plugin-kerfjs`'s `ui-public-boundaries` loads it beside
+  `application-ui-profile-sync.cjs`, and the generated `ai/components/*.md`
+  pages use it too, so the lint message and the component reference can no
+  longer name different components (a test pins their agreement over the whole
+  shipped catalog). A vendored `profileContractPath` directory must now also
+  hold `component-class-owners.cjs`; an `@kerfjs/ui` without it reports
+  `KUI-L090`.
+
+- **A delegated click no longer re-fires on a target the re-render recycled.**
+  A delegated handler that writes a signal makes `mount()` re-render
+  synchronously, inside the same event dispatch; when the morph recycled the
+  clicked element in place into a control with a different `data-action`,
+  delegates registered later for the same event matched the recycled element
+  and fired too (a `request` click immediately ran `cancel` and undid itself).
+  `delegate()`, `delegateCapture()`, and `kerfjs/actions`' `delegateActions()`
+  now resolve every delegate's match against the DOM as it stood when the
+  event reached the first kerf delegate listener, like per-element listeners:
+  a delegate that matched at dispatch start still fires (unless an earlier
+  handler removed its element), one that matches only after a re-render does
+  not, and `delegateActions()` dispatches by the action value the element
+  carried at dispatch start. `mount()` stays synchronous. The
+  wrap-it-in-a-distinct-element workaround is no longer needed. Cost: about
+  0.11 KB min+gzip, which moves the advertised core size from ~12 KB to
+  ~13 KB.
+
+- **Component packages declare `placeableClasses`, and `KUI-L103` covers
+  their anatomy classes.** `create-kerf-component`'s `kerf.components.json`
+  accepts optional `boundaries.placeableClasses` (a subset of
+  `publicClasses`) and `boundaries.rootElement`, validates them, and copies
+  them into the generated `component-composition.json`.
+  `eslint-plugin-kerfjs`'s `ui-public-boundaries` now checks every class the
+  application or third-party catalogs in `.kerf-ui-profile.json` declare, not
+  only `kui-*` names: `<div class="acme-meter">` is reported with the
+  package's component to render (`Meter`), while its placeable classes stay
+  allowed. The scaffold template's README explains the field, and
+  `@kerfjs/ui/ai/skill.md` (1.50.0) applies the rule to package entries.
+
+- **`eslint-plugin-kerfjs` `ui-public-boundaries` reports a plain
+  `<div class="kui-content-item">` as `ContentItem` recreated (`KUI-L103`).**
+  The `kui-content-item` classes stay placeable on another carrier (a `<ul>`, a
+  `Text`, a control-cluster `<footer>`), but a plain `<div>` carrying them is
+  exactly what `ContentItem` renders; the diagnostic now says to render
+  `ContentItem`. The `@kerfjs/ui` catalogs gain an additive `rootElement`
+  field (selection entry and composition `boundaries.rootElement`) naming the
+  element a component renders around its own placeable classes, and
+  `check:guidance` derives its repository check from the same fields, so the
+  package check and the downstream diagnostic cannot drift. The rule also
+  inspects the static class names of a template-literal `class` /
+  `className` value.
+
+- **`eslint-plugin-kerfjs` `ui-public-boundaries` reports a component's
+  anatomy class written onto an application-owned element (`KUI-L103`).**
+  `<div class="kui-toolbar">`, `<aside class="kui-pane">`, or
+  `<wa-dropdown class="kui-popup-menu">` recreates a component by class and
+  inherits (and invites restyling of) its CSS; the diagnostic names the
+  component to render instead (`Toolbar`, `Pane`, `PopupMenu`). The
+  `@kerfjs/ui` catalogs gain `placeableClasses` (selection entry field and
+  composition `boundaries.placeableClasses`) naming the public classes an
+  application may place itself — the layout utilities, `kui-app-root`, the
+  `kui-content-item` geometry on a non-div carrier, and Web Awesome
+  `hide-actions` — and `check:catalog` requires every class-only entry to list
+  its classes there. A component's own element (`<Toolbar className="kui-toolbar">`)
+  is not reported. The README pane example and `@kerfjs/ui/ai/skill.md`
+  (1.47.0) now render `Pane` instead of writing its classes, and each generated
+  `ai/components/*.md` page states which classes are placeable and which
+  component renders the rest.
+
+- **`kerf-ui-analyze` retires `KUI-L005` ("forced component dimension").**
+  `KUI-L019` already reports any application rule whose subject is a cataloged
+  component, dimensions included, so `.kui-pane { width: 300px }` was reported
+  twice (an error and a review finding). L005's only other shape, a public
+  class as an ancestor (`.kui-pane .app-sidebar { width: 240px }`), sizes the
+  application's own element and is allowed. The analyzer no longer emits it;
+  the id stays in the diagnostic registry (now listing it under `retired`) so
+  existing profile exceptions that name it still load.
+
+- **`KUI-L301` now reports every `Discouraged` Web Awesome element rendered
+  directly.** The `@kerfjs/ui` package-default application profile avoids all
+  fifteen Discouraged entries (Dropdown/Dropdown Item → `PopupMenu`,
+  Select/Option → `Select`, Tab Group/Tab/Tab Panel → `TabBar`, Icon →
+  `LucideIcon`, Split Panel → `ResizableRegion`, Button Group →
+  `SegmentedControl`, Tree/Tree Item → `List`, and Animated Image, Comparison,
+  and Zoomable Frame → `ContentItem`), each with a rationale, and
+  `eslint-plugin-kerfjs` `ui-preferences` (and `kerf-ui-doctor`, which runs it)
+  now resolves a custom-element JSX tag such as `<wa-dropdown>` to its catalog
+  entry, not only an imported component. A declared component's own source
+  stays exempt because it is the wrapper that owns the element. A test keeps
+  the profile's avoid set equal to the catalog's Discouraged set in both
+  directions and lints the UX demo, recipes, and catalog shell clean;
+  `@kerfjs/ui/ai/skill.md` (1.46.0) names the diagnostic.
+
+- **New (`@kerfjs/ui`): `NavStack` and `TabScaffold` take `chromeDividers`
+  (`'scroll' | 'always' | 'none'`), like `Pane`.** `scroll` (the default) keeps
+  today's behavior: the stack's top-chrome and bottom-toolbar lines and the
+  scaffold's bar line follow the scroll once `wireScrollDividers` is installed.
+  `always` draws them permanently without the wiring; `none` never draws them,
+  even when wired. The top `Toolbar`'s own `toolbarConfig.dividerSides` is
+  unaffected. `SplitView` forwards it to its compact stack through
+  `compactStack.chromeDividers`.
+
+- **Fix (`@kerfjs/ui`): a `Pane` that is the only content of a `NavStack` view
+  or a `TabScaffold` scene fills it.** It used to size to its content, so the
+  view scrolled the whole Pane and its header scrolled away. Now the Pane's own
+  content scrolls under its pinned header and footer, the Pane's slots take the
+  safe-area edges the view or scene still reaches, and scroll dividers key on
+  the Pane's content. The rule lives in `pane.css`, as the Workbench-region fill
+  does.
+
+- **The `@kerfjs/ui` suite-v3 AI-regression protocol test runs in every gate
+  again.** `ui/tests/integration/ai-regressions-v3.test.ts` was selected by no
+  package script, so neither `npm --prefix ui run check` nor CI executed it. It
+  now runs as `test:ai-regressions` inside the package's `npm test`, and a new
+  unit guard fails when any file under `ui/tests` is selected by no script
+  reachable from `check` or `test:e2e`.
+
+- **Importing `@kerfjs/ui/catalog` or `@kerfjs/ui/workbench` now ships every
+  stylesheet those composites render.** `catalog`, `workbench`, `nav-stack`,
+  `split-view`, `tab-scaffold`, and `collapsible-panel` gain a CSS-aware
+  `browser` export condition whose generated wrapper imports the foundation, the
+  CSS of each internally rendered component (Pane, Toolbar, ToolbarText, List,
+  ListItem, ListInsetText, Row, PopupMenu, …) in dependency order, and the
+  composite's own CSS. Apps no longer hand-import `pane.css`, and a Catalog
+  sidebar's styling no longer depends on whether the app happens to import
+  `ListInsetText` elsewhere. The list is derived from the source import graph
+  (now following parent-relative imports), the `import` condition stays
+  CSS-free, and the companion `.css` subpaths remain for pipelines without the
+  `browser` condition. `@kerfjs/ui/ai/skill.md` is 1.46.0.
+
+- **The `@kerfjs/ui` AI guidance now states every maintainer design rule
+  explicitly.** An audit of the package's tickets folded the missing rules into
+  `@kerfjs/ui/ai/skill.md` (1.45.0), `llms.txt`, and the design docs: prefer a
+  Kerf UI component over a Web Awesome component over a raw tag and never render
+  a `Discouraged` Web Awesome element directly (only through the Kerf component
+  that wraps it); nothing wraps inside a `ToolbarControlGroup` and a
+  `ToolbarText` is one ellipsized line unless `wrap`/`maxLines` is set; a
+  `Select` or `PopupMenu` trigger drops its focus ring while its popup is open
+  and the ring follows the control's shape (never add ring CSS); dividers earn
+  their place (`dividerSides=""` over self-spacing content or between a pane's
+  header and its list, never padded around); a control sits near where its
+  effect appears; and text aligns to text and icons to icons — a border is
+  never the alignment anchor. The ToolbarControlGroup catalog entry no longer
+  points at a hand-written `wa-dropdown` trigger, and the bundled kerf app
+  configs (`ai/skill.md` 1.25.0, `ai/cursorrules` 1.23.0) name the List family
+  and carry the "components own their styles; configure, never override" rule.
+
+- **Applications and component packages are held to the component-ownership
+  rules `@kerfjs/ui` enforces internally: components own their styles and are
+  configured, never overridden.** `kerf-ui-analyze` and `kerf-ui-doctor` add
+  four error diagnostics (review findings under `--adoption`):
+  - `KUI-L019` — a CSS rule whose subject is another package's cataloged
+    component: a public class (`.kui-toolbar`, `.acme-meter`), its
+    `[data-component]` root, or a Web Awesome tag the package themes
+    (`wa-button`). Your own element in a component's context
+    (`.kui-toolbar > .my-widget`), keying on its state inside `:has()`, and
+    setting its public tokens stay allowed.
+  - `KUI-L020` — reading or writing another component's private `--_*`
+    variable (`--_kui-list-gap`).
+  - `KUI-L021` — overriding a token a typed prop sets (`--kui-list-gap` is
+    `<List gap>`); the message quotes the prop's example.
+  - `KUI-L022` — a class placed on a component's root (`<Toolbar
+className="header" />`) that the application then styles.
+
+  Each message names the component's configuration (typed props, public
+  tokens, variants) and ends by routing a need with no prop to a component-gap
+  report instead of an override. Ownership is per package, from the nearest
+  `package.json`, so a component package styling its own components — including
+  in a Kerf UI parent's context — passes, and third-party catalogs declared in
+  `.kerf-ui-profile.json` get the same protection. `eslint-plugin-kerfjs` adds
+  `ui-component-ownership` (in `recommended-ui` and `strict-ui`, `error`),
+  reporting `KUI-L020` / `KUI-L021` in style strings, style objects, and
+  `style.setProperty()`. The `create-kerf-component` scaffold now ships a
+  `counter.css` that styles only Counter (configured by a typed `size` prop and
+  a `--kerf-counter-gap` token, with context named after Counter and a
+  Toolbar-context rule in its own stylesheet), plus `npm run check:styles`
+  (`kerf-ui-analyze`, from a new `@kerfjs/ui` dev dependency) in
+  `prepublishOnly`.
+
+- **Behavior change (`@kerfjs/ui`): `NavStack` and `TabScaffold` chrome
+  dividers follow the scroll.** The `NavStack` bottom toolbar's and the
+  `TabScaffold` bar's top borders are no longer permanent. With `wireScrollDividers`
+  installed, a `NavStack`'s top chrome draws a line along its bottom edge only
+  while the active view's content is scrolled beneath it, its bottom toolbar a
+  line along its top edge only while more content lies below, and a
+  `TabScaffold` bar a line along its top edge only while the active scene's
+  content continues below it — none when the content fits. The line follows
+  the active view across a push or pop and the active scene across a tab
+  switch, and keys on whichever element actually scrolls: the view or scene
+  itself, or, through a sole child with no chrome of its own on that edge, a
+  `Pane`'s content or a nested `NavStack`'s active view (a sole `Pane`'s own
+  header or footer draws that boundary instead). Each layout draws the line
+  from its own stylesheet (an overlaid pseudo-element on the stack's chrome; the
+  bottom toolbar and bar keep their 1px top border, transparent until shown),
+  so nothing moves; the wiring
+  writes only its `data-scroll-overflow` / `data-scroll-divider` state. Without
+  the wiring those edges draw no line.
+
+- **Behavior change (`@kerfjs/ui`): toolbars no longer draw a divider by
+  default; dividers between pinned chrome and scrolling content follow the
+  scroll.** `Toolbar`'s `dividerSides` now defaults to `''` (was `'b'`), and
+  the `Workbench` (`mainToolbar`, `mainBottomToolbar`, panel toolbars, and the
+  `mainHeader` / `mainFooter` lists), `CollapsiblePanel`, and `Catalog`
+  toolbars no longer place dividers of their own. Instead a `Pane` draws one
+  line under its header and one over its footer, wherever that chrome ends:
+  the header's only while content is scrolled beneath it, the footer's only
+  while more content lies below, and neither when the content fits. The new
+  `@kerfjs/ui/wire-scroll-dividers` subpath's `wireScrollDividers(root, {
+targets? })` reports that state — call it once at the app root and keep its
+  disposer (`wireCatalog` installs it for its own root). It also marks each
+  side of a `TabBar` strip with tabs scrolled out of view, and lets a
+  `Toolbar` or `List` named as chrome in `targets` draw the divider facing an
+  app-owned scroller. The wiring only writes the `data-scroll-overflow` /
+  `data-scroll-divider` state attributes; each component draws its own line,
+  and no state moves the chrome, the content, or a tab. `Pane` gains
+  `chromeDividers` (`scroll` default, `always`, `none`; also in `PaneConfig`,
+  so `mainPane` and a panel's `pane` forward it) and TabBar the
+  `--kui-tab-bar-divider-color` token. To keep a permanent line, set
+  `chromeDividers: "always"` on the pane or an explicit `dividerSides`.
+
+- **`@kerfjs/ui`: `Pane`, `NavStack`, `SplitView`, and `TabScaffold` fill a
+  Workbench region from their own stylesheets.** As a Workbench main area's
+  or panel's only child, each sets its own `height: 100%` in that context,
+  which the Workbench marks on its regions (`data-workbench-main`, and the new
+  `data-workbench-panel-content` on each panel's content); `workbench.css` no
+  longer sizes another component's root (it still fills a nested Workbench).
+  Rendering is unchanged.
+
+- **`@kerfjs/ui`: layouts name the covered-floating-controls context after
+  themselves, and no longer write `FloatingToolbar`'s inset token.** Workbench,
+  CollapsiblePanel, and ResizableRegion each provide their own private
+  `--_kui-<layout>-covered` context in place of the shared
+  `--_kui-floating-covered` flag; `FloatingToolbar` and every restore corner
+  read all three. A restore corner no longer sets
+  `--kui-floating-toolbar-inset: 0px`; `FloatingToolbar` zeroes its own inset
+  inside a restore corner (a toolbar's own `inset` still wins). Rendering is
+  unchanged. One edge case changes: a floating control inside an open overlay
+  of one layout type that is itself covered by another layout type's open
+  overlay (for example, a ResizableRegion overlay in a Workbench work area
+  under an open rail overlay) now stays hidden.
+
+- **`@kerfjs/ui`: `ListHeader`, `NavStack`, `Select`, and `StateBanner` no
+  longer restyle a composed child through a class on its root.** Each child
+  now styles itself: `Text` sets a `ListHeader` label from `text.css`, `Badge`
+  spaces a `Select` count and a `StateBanner` badge from `badge.css`, and a
+  `NavStack` title uses `ToolbarText`'s new `fill` option. Rendering is
+  unchanged. `ToolbarText` gains `fill` (grow into the free space of its
+  toolbar zone and truncate there). The `kui-list-header__label`,
+  `kui-nav-stack__title`, `kui-select__count`, and `kui-state-banner__badge`
+  classes are removed; select a ListHeader label with
+  `.kui-list-header__title > .kui-text` and a NavStack title with
+  `.kui-toolbar-text[data-fill="true"]` if a test needs to find them.
+
+- **`@kerfjs/ui` ships a markdown component reference for AI assistants.**
+  `@kerfjs/ui/ai/components/README.md` indexes every catalog entry in one line,
+  and `@kerfjs/ui/ai/components/<id>.md` gives each entry a short page: when to
+  use and avoid it, imports and CSS/registration side effects, a link to its
+  exact props, legal parents and zones (JSX prop and child count), app- and
+  wiring-owned state, geometry, accessibility obligations, its styling boundary
+  (configure through props; do not override internals), and its diagnostics.
+  `llms.txt` and the shipped skill now send assistants there instead of to the
+  263 KB `component-catalog.json` and 221 KB `component-composition.json`,
+  which remain the canonical sources for tools. The pages are generated from
+  those two files and a package check fails when they drift.
+
+- **Breaking (`@kerfjs/ui` and `create-kerf-component`): the composition
+  catalog files are renamed so they no longer read as a "v2" of the component
+  catalog.** The composition catalog is a generated composition layer beside
+  `component-catalog.json`, not a newer version of it. Update any import,
+  `$schema`, `$ref`, or `.kerf-ui-profile.json` catalog location that names an
+  old path:
+
+  | Old path                                                       | New path                                                        |
+  | -------------------------------------------------------------- | --------------------------------------------------------------- |
+  | `@kerfjs/ui/ai/component-catalog-v2.json`                      | `@kerfjs/ui/ai/component-composition.json`                      |
+  | `@kerfjs/ui/ai/component-catalog-v2.schema.json`               | `@kerfjs/ui/ai/component-composition.schema.json`               |
+  | `@kerfjs/ui/ai/component-catalog-v2.d.ts`                      | `@kerfjs/ui/ai/component-composition.d.ts`                      |
+  | `@kerfjs/ui/ai/component-catalog-v2-overrides.json`            | `@kerfjs/ui/ai/component-composition-rules.json`                |
+  | `@kerfjs/ui/ai/component-catalog-extension-v2.schema.json`     | `@kerfjs/ui/ai/component-composition-extension.schema.json`     |
+  | `@kerfjs/ui/ai/component-catalog-extension-v2.d.ts`            | `@kerfjs/ui/ai/component-composition-extension.d.ts`            |
+  | `@kerfjs/ui/docs/examples/component-catalog-extension-v2.json` | `@kerfjs/ui/docs/examples/component-composition-extension.json` |
+  | scaffolded package `component-catalog-v2.json`                 | scaffolded package `component-composition.json`                 |
+
+  The exported types follow: `ComponentCatalogV2` → `ComponentComposition`,
+  `CatalogCompositionEntryV2` → `CatalogCompositionEntry`,
+  `ConsumerComponentCatalogV2` → `ConsumerComponentComposition`, and
+  `ConsumerCatalogEntryV2` → `ConsumerCompositionEntry`. In the repository,
+  `npm run catalog:v2:sync` is now `npm run composition:sync`
+  (`catalog:sync` still runs both generators). The file contents and their
+  `schemaVersion` are unchanged.
+
+- **Breaking (`@kerfjs/ui`, `create-kerf-component`, and `kerfjs setup`): the
+  composition catalog's own fields no longer read as a "v2" of the component
+  catalog.** In `component-composition.json` (and any consumer composition
+  catalog), `"schemaVersion": 2` is now `"schemaVersion": 1` — the composition
+  format's own first version, independent of `component-catalog.json`'s — and
+  `compatibility.v1Catalog` is now `compatibility.componentCatalog`. A
+  scaffolded package's `kerf.components.json` renames its `v1Catalog` field to
+  `componentCatalog` the same way. Regenerate scaffolded catalogs
+  (`npm run catalog:generate`), and change any `.kerf-ui-profile.json` `composition`
+  location from `"schemaVersion": 2` to `"schemaVersion": 1`; a catalog still
+  carrying the old fields fails validation with a message naming the rename.
+  The `ComponentComposition` type follows (`schemaVersion: 1`,
+  `compatibility.componentCatalog`).
+
+- **`@kerfjs/ui` `NavStack` bars use the standard `Toolbar` padding.** The
+  navigation bar dropped its toolbar's block padding to stay 44px tall, so its
+  title and controls touched the bar's edges. It now keeps the 8px above and
+  below that every other toolbar has (60px plus any top safe-area inset).
+
+- **`@kerfjs/ui` multiline list rows break long camelCase names at word
+  boundaries.** A string label in a `multiline` `ListItem` or `ListActionRow`
+  (such as a Catalog sidebar entry) gets `<wbr>` break opportunities at its
+  camelCase and acronym boundaries, so `QuickTicketComposer` wraps as
+  `QuickTicket` / `Composer` instead of `QuickTicketComp` / `oser`. Breaking
+  mid-word remains the fallback for a single word that is still too wide.
+- **`wbr` is a typed JSX intrinsic element.** The runtime already rendered it
+  as a void element; `JSX.IntrinsicElements` now declares it.
+
+- **`@kerfjs/ui` `Badge` has a text-free dot, and `TabScaffold` tabs can show
+  it.** `Badge` takes `size="dot"`: an 8px solid circle in the badge's tone,
+  with no children, appearance, or shape. Because a dot has no text, its props
+  require either a `label` (announced as an image, for example
+  `label="New activity"`) or `ariaHidden` when the owning component already
+  announces it. `TabScaffoldTab` accepts `badge: true` for the iOS tab-bar dot
+  (new content without a count), centered on the icon's top-trailing corner;
+  its `badgeLabel` is required and joins the tab's accessible name
+  ("Settings, Update available"). `BadgeTextProps` and `BadgeDotProps` are
+  exported from the root barrel.
+
+- **`@kerfjs/ui` `Toolbar` truncates the leading title instead of letting the
+  center zone cover it.** When a leading identity, a `center` group, and
+  trailing actions no longer fit one row, the center zone keeps its whole
+  content width and the leading title ends in an ellipsis. Previously the
+  center track could shrink below its group, which then painted over the
+  title — a pushed `NavStack` view with a center group did this at 390px. The
+  fix holds under every `responsive` policy and both `centerAlign` values, and
+  a toolbar that fits lays out exactly as before.
+
+- **`@kerfjs/ui` `ValueTableRow` keeps its value readable beside a long
+  label.** A long single-word label (such as `ConnectionStateBanner` in a
+  390px-wide table) no longer squeezes the value to 0px wide, where it wrapped
+  one character per line while the label ran underneath it. The label and value
+  now share the row as two content-sized columns: a short value stays whole on
+  one line, the label wraps at its spaces and ends an over-long word in an
+  ellipsis before the value, and when both are long they split the row.
+
+- **`@kerfjs/ui` pinned chrome can give way in a short pane.** `Pane` takes
+  `chromePlacement="auto"`: its header and footer stay pinned while the pane is
+  at least 480px (30rem) tall, and below that the whole pane scrolls as one
+  column so tall chrome never squeezes the content to nothing.
+  `WorkbenchChromePlacement` gains `"auto"` for `mainHeaderPlacement` /
+  `mainFooterPlacement`, and `Catalog` now defaults `headerPlacement` /
+  `footerPlacement` to `"auto"`. Its entry description is pinned under the
+  toolbar, which at 200% text size on a short window had left the preview 0px
+  tall.
+
+- **`@kerfjs/ui` `TabScaffold` tabs can show a badge.** Give a
+  `TabScaffoldTab` a `badge` (a count or short string) to show the iOS tab-bar
+  badge — a compact, solid danger `Badge` at the top-trailing corner of the
+  tab's icon. The badge is hidden from assistive technology; the tab's
+  accessible name becomes `"<label>, <badgeLabel>"` (for example
+  "Inbox, 3 unread"), with `badgeLabel` defaulting to the badge text. Tabs
+  without a badge are unchanged.
+
+- **`@kerfjs/ui` `ListItem` and `ListActionRow` labels stay out of the
+  trailing slot.** A long single-word primary label (such as a Catalog sidebar
+  entry named `ConnectionStateBanner` in a narrow rail) no longer runs
+  underneath trailing status text. Single-line rows now end the primary label
+  and description with a real ellipsis (previously the text was cut mid-glyph
+  with no "…"), and `multiline` rows break a word wider than the label column
+  onto the next line.
+
+- **Custom elements keep the `role` and `aria-*` they set on themselves across
+  re-renders.** Web components conventionally own their host's ARIA (Web
+  Awesome's `wa-option` sets `role="option"` / `aria-selected`, `wa-divider`
+  sets `role="separator"`; Shoelace and FAST do the same), but a template never
+  mentions them, so the morph and the keyed-list attribute fast path stripped
+  them on the next re-render. On any custom element (hyphenated tag), `role`
+  and `aria-*` are now element-owned like `open`: never removed just because
+  the template omits them. The template can still set or change them, a signal
+  binding set to `null` / `false` still removes them, and plain elements are
+  unchanged. Trade-off: omitting one from a static template no longer removes
+  it from a custom element — render an explicit value (`aria-pressed="false"`)
+  instead.
+
+- **`@kerfjs/ui` layout regions no longer slow edits to long lists inside
+  them.** The rule that clears the safe-area context for the children of a
+  Workbench main area or panel, SplitView list or detail, NavStack view,
+  TabScaffold scene, or CollapsiblePanel content made each child re-check the
+  region in Chromium on every DOM change. A 1000-row list placed directly in
+  one of these regions took about 46ms per style recalculation (2ms with the
+  list one level down), and now takes about 0.2ms. Layout and insets are
+  unchanged.
+
+- **`@kerfjs/ui` `CollapsiblePanel` no longer slows insertions into long
+  lists.** An expanded inline panel clears its screen edge for its siblings;
+  the rules that did so selected the siblings themselves
+  (`:has(~ panel)` and `panel ~ *`), which in Chromium made each row inserted
+  into or removed from a long list restyle the list's other rows — about
+  14.6ms instead of 0.2ms per insertion beside a 1000-row list. The panel's
+  container now carries a flag that a CSS style query reads, so a list pays
+  nothing. The edge still clears for the panel's siblings and returns when it
+  collapses; the one difference is that a sibling placed before a left panel
+  or after a right or bottom panel now loses the edge too.
+
+- **`@kerfjs/ui` restore corners and covered floating controls no longer slow
+  every style recalculation.** The `CollapsiblePanel` / `ResizableRegion`
+  restore-corner anchor scope (`:has(> restore) > * > * > *`) and the static
+  side-overlay covered flag (`:has(> open overlay) > :not(overlay)`) put a
+  universal selector after a `:has()` container, which in Chromium restyled
+  the children of every ancestor of each DOM change — about 85ms instead of
+  1ms per edit beside a 1000-row list. The drawer now publishes its anchor
+  only beside a restore control's container (or its work-area column), and
+  the covered flag is set on the overlay's container and cleared on its
+  overlay children. Restore-corner placement and covered-control hiding are
+  unchanged; a new CSS unit test rejects the costly `:has()` shapes.
+
+- **`@kerfjs/ui` adds `ContentItem`.** Import it from
+  `@kerfjs/ui/content-item` to render one self-contained pane child with the
+  shared 8px margin, 1px border, and 8px padding. Framing and shape are typed
+  props instead of hand-written modifier classes:
+  - `frame="framed"` paints the neutral border in the 1px the item always
+    reserves, so its geometry does not change (replacing
+    `class="kui-content-item kui-content-item--framed"`);
+  - `shape="pill"` selects the 22px radius.
+  - `ariaLabel` names a distinct region, and `focusTarget` makes the item a
+    programmatic focus target (`tabindex="-1"`), such as a NavStack view's
+    `data-nav-focus` target.
+
+  The `.kui-content-item` classes stay public for elements that must carry the
+  geometry themselves; their CSS now lives in `content-item.css`, which
+  `layout.css` still imports. There is no filled variant — use `SunkenPanel`
+  for a lowered surface. The catalog, demos, and recipes use the component.
+
+- **`@kerfjs/ui` icon-only toolbar buttons show the same help tag.** An
+  icon-only `<button>` or link inside a `ToolbarControlGroup`, named by
+  `aria-label` with no visible text, now shows the help tag icon-only Selects
+  and PopupMenus show, with the same 500ms hover delay, keyboard-focus-only
+  display, press/Escape dismissal, and quick scanning along a toolbar. The tag
+  is `aria-hidden` and never renames the button. A button with a native
+  `title`, or with its own Web Awesome tooltip, keeps that and gets no second
+  tag. The `select/register` and `popup-menu/register` imports install it; a
+  toolbar with icon-only buttons but neither control imports the new
+  `@kerfjs/ui/help-tags/register` subpath, which registers only the tooltip.
+
+- **`@kerfjs/ui` icon-only Select and PopupMenu triggers show a help tag.**
+  An icon-only `Select` (single or `multiple` with `triggerIcon`) and an
+  icon-only `PopupMenu` now show a Web Awesome tooltip naming the control on
+  hover (after 500ms) and on keyboard focus: a filter reads "Filter by label:
+  Bug, Docs", a single Select its name and current choice, a menu its `label`.
+  It hides while the popup is open, on a press, and on Escape. The tag repeats
+  the accessible name, so it is `aria-hidden` and never joins
+  `aria-labelledby`; screen readers still hear the name once. It is installed
+  by the existing `select/register` and `popup-menu/register` imports, needs no
+  props, and never appears for labeled Selects or text menu triggers.
+
+- **`@kerfjs/ui` toolbar groups drop their focus ring while a popup is open.**
+  A `ToolbarControlGroup` that owns the ring (`focusRing="outline"` or
+  `"halo"`) no longer paints it while a Select listbox or `PopupMenu` inside it
+  is open; the open popup shows focus, and the ring returns when the popup
+  closes with focus still in the group. This matches the per-control Select
+  and PopupMenu triggers.
+
+- **`@kerfjs/ui` multiple `Select` can be an icon-only toolbar filter menu.**
+  Set `selectedPresentation: 'icon-only'` on a `multiple` Select together with
+  a fixed `triggerIcon` (for example a funnel `LucideIcon`); the types require
+  `triggerIcon` there and reject it everywhere else. The trigger keeps the
+  icon-only caret pill used in a `ToolbarControlGroup`, and:
+  - shows the fixed icon whatever is chosen;
+  - adds a compact count `Badge` while any choice is chosen;
+  - ends the combobox's accessible name with the chosen labels in choice order
+    ("Filter by label: Bug, Docs"), leaving the hidden value text empty so the
+    list is not announced twice.
+
+  The popup still stays open while choices toggle.
+
+- **`@kerfjs/ui` `Select` options keep their accessibility semantics across
+  re-renders.** Re-rendering a Select (for example after its `change` handler
+  updates the controlling signal) removed the `role="option"` and
+  `aria-selected` Web Awesome sets on each option, so screen readers lost every
+  option's role and selected state. They now survive in single and `multiple`
+  Selects through the core rule below (custom elements own their `role` /
+  `aria-*`), with no Select-specific restore.
+
+- **`@kerfjs/ui` `Select` dividers keep their separator role across
+  re-renders.** The `wa-divider` a `separatorBefore` choice adds lost the
+  `role="separator"` and `aria-orientation` Web Awesome sets on it the first
+  time the enclosing mount re-rendered, and never got them back, so assistive
+  technology stopped announcing the break between option runs. The Select now
+  renders both attributes itself.
+
+- **`@kerfjs/ui` `Select` and `PopupMenu` re-renders no longer force Web
+  Awesome updates.** Web Awesome reflects its default `size`, `appearance`,
+  `placement`, and `orientation` onto `wa-select`, `wa-dropdown`, and
+  `wa-divider`; the templates omitted them, so every re-render of the enclosing
+  mount stripped them and each host ran a full Lit update to put them back. The
+  templates now render those defaults (`wa-select size="m"
+appearance="outlined" placement="bottom"`, `wa-dropdown size="m"`, divider
+  `orientation="horizontal"`), so an unchanged re-render leaves the hosts
+  alone. No visual change. The `@kerfjs/ui/webawesome` JSX declarations type
+  these attributes.
+
+- **`@kerfjs/ui` Workbench and CollapsiblePanel panes and chrome lists are
+  configurable.** The `Pane`s these layouts compose around app content now
+  take the new `PaneConfig` type (`contentElement`, `contentLabel`,
+  `separators`, `safeAreaEdges`): a Workbench panel's or `CollapsiblePanel`'s
+  `pane`, and the Workbench's `mainPane`. The `List`s holding `mainHeader` /
+  `mainFooter` take the new `ListConfig` type (`gap`, `hAlign`, `vAlign`,
+  `dividerSides`, `textInsets`, `controlInsets`) through `mainHeaderList` /
+  `mainFooterList`. Previously this configuration was hard-coded, so, for
+  example, a navigator rail could not render its content as a `nav` landmark
+  without restyling. Omitted or `undefined` fields keep today's defaults, and
+  the default markup is unchanged.
+
+- **`@kerfjs/ui` `SplitView` forwards its `ResizableRegion` and compact
+  `NavStack` configuration.** `resizable` now also takes the list region's
+  `separator`, `handleIcon`, `contentOverflow`, and collapse options
+  (`collapsed`, `transitioning`, `collapseMotion`, `restoreControl`,
+  `restorePosition`), so an app can hide the list and float a restore control
+  without leaving `SplitView`. The new `compactStack` prop forwards the compact
+  stack's `toolbarConfig`, `backIcon`, `backText`, `hideToolbar`, and
+  persistent `bottomToolbar`, and gives the list and detail views their own
+  toolbar groups (`list` / `detail`: `leading`, `center`, `toolbar`,
+  `bottomToolbar`). Omitted options keep today's defaults.
+
+- **`@kerfjs/ui` `NavStack` renders its top chrome as a real `Toolbar`.** The
+  back control is a borderless `ToolbarControlGroup` and the title a
+  `ToolbarText` in the leading zone, and the stack now forwards:
+  - `toolbarConfig` — the `Toolbar` configuration (`dividerSides`,
+    `centerAlign`, `responsive`, `responsiveAt`, `safeAreaEdges`) plus `label`,
+    `titleSize` (default `large`), and `headingLevel`;
+  - per-view `leading` and `center` groups beside the existing trailing
+    `toolbar`;
+  - `backIcon` and visible `backText` for the back control.
+
+  The defaults keep today's bar: no divider, one 44px band, and the top and
+  side safe-area edges claimed. The hand-rolled `kui-nav-stack__lead` and
+  `kui-nav-stack__actions` wrappers are gone (their content now sits in the
+  toolbar's zones), and `kui-nav-stack__back` / `kui-nav-stack__back-icon`
+  are no longer styled by the stack.
+
+- **`@kerfjs/ui` configures with props instead of token overrides.** Five
+  settings apps previously reached through raw `--kui-*` overrides now have a
+  typed prop or modifier; each defaults to today's rendering, and the
+  underlying tokens keep working:
+  - `FloatingToolbar` `inset` (a `CssLength`, default `--kui-space-m`) moves
+    it from the container edges. Omit it inside a restore corner, which owns
+    the inset.
+  - `DisclosureArrow` `size` (a `CssLength`, default 18px root-scaled).
+  - `ListHeader` `headingLevel` (1–6, default 2) sets the label's native
+    heading element for passive and trailing-action headers; a toggle header
+    has no heading and rejects it at compile time.
+  - `TokenSearchField` `clearIcon` replaces the clear action's glyph.
+  - `.kui-content-item--framed` paints the standard neutral border on a
+    content item that marks a real distinction, with no geometry change.
+
+  The docs and AI guidance also stop recommending `--kui-edge-inset-*`
+  overrides: an app-owned arrangement passes `safeAreaEdges` to its panes and
+  edge-claiming toolbars (including the layout toolbar configurations, which
+  forward it).
+
+- **`@kerfjs/ui` hides a work area's floating controls under an open side
+  overlay.** While a side overlay is open — a Workbench rail (static
+  `presentation: "overlay"`, or a responsive overlay whose breakpoint applies),
+  a `wireSidebar` compact overlay or `presentation="overlay"`
+  `CollapsiblePanel`, or a horizontal `presentation="overlay"`
+  `ResizableRegion` — the covered work area's `FloatingToolbar`s and the
+  layouts' restore corners are now hidden (`visibility: hidden`, so they also
+  leave the tab order and the accessibility tree) instead of relying on
+  stacking order alone. A phone-width app could otherwise paint the main
+  column's floating drawer toggle over its open inspector. They come back as
+  the overlay closes; the overlay's own floating controls and a bottom
+  drawer's overlay are unaffected.
+
+- **`@kerfjs/ui` `Select` supports multiple selection.** Set `multiple: true`
+  and pass the chosen values as an array `value`; the props are typed so an
+  array value requires `multiple`. Behavior:
+  - The popup stays open while the person toggles choices with the pointer,
+    Enter, or Space, and closes only on an outside press, Escape, or focus
+    leaving.
+  - Each chosen option shows a check.
+  - The closed control summarizes the chosen labels in choice order as a short
+    localized list, or shows `placeholderText` when none are chosen.
+  - `change` / `input` report the value array, and a form submits every chosen
+    value under `name`.
+  - Re-rendering with a different `value` updates the selection even after the
+    person has interacted.
+
+  `renderSelected` and `selectedPresentation="icon-only"` stay single-value
+  only.
+
+- **`@kerfjs/ui` `PopupMenu` now looks exactly like `Select`.** Both read one
+  shared popup contract, so a command menu beside a value list in a toolbar
+  draws the same popup. `PopupMenu` changes:
+  - its caret turns to face the open menu;
+  - its menu fades in without scaling;
+  - it takes the Select listbox's 4px inset (also under the default
+    `menuInset="standard"`);
+  - its rows use the Select option's height, padding, and reserved check
+    column, and its icons use the same 16px size and 8px gap;
+  - a keyboard-focused item takes the Select's current-option fill instead of
+    a focus ring;
+  - headings render as the Select's uppercase group titles rather than slotted
+    `h3` elements.
+
+  An open `Select` also no longer paints its trigger focus ring. The open
+  listbox shows focus, and the ring returns when it closes.
+
+- **`@kerfjs/ui` `Catalog` exposes its sidebar and toolbar configuration.** New
+  `sidebar` prop (size, `resizable`, `separator`, `collapseMotion`,
+  `presentation`, `responsiveOverlayAt`, `compactOverlay`, and the header
+  `toolbar`'s `ToolbarConfig`) forwarded to its Workbench rail, plus
+  `mainToolbar` / `footerToolbar` `ToolbarConfig` props. `wireCatalog` takes
+  `sidebarSize` / `sidebarStorageKey` to wire a resizable sidebar. Today's
+  288px fixed sidebar and toolbar policies remain the defaults.
+
+- **`@kerfjs/ui` composed toolbars are configurable.** `WorkbenchMainToolbar`,
+  `WorkbenchMainBottomToolbar`, and the panel `toolbar` of a Workbench panel or
+  `CollapsiblePanel` now take the `Toolbar`'s configuration: the new
+  `ToolbarConfig` type, covering `dividerSides`, `centerAlign`, `responsive`,
+  `responsiveAt`, and `safeAreaEdges`. Previously their dividers were
+  hard-coded, so for example dropping the line between a toolbar and its
+  content took CSS. Today's dividers remain the defaults. Also:
+  - `mainBottomToolbar` and panel toolbars take a `center`;
+  - panel toggles take localized `showLabel` / `hideLabel`;
+  - a Workbench panel's floating restore controls follow its
+    `restorePosition`.
+
+- **Breaking (`@kerfjs/ui`): removed the pre-release compatibility surface.**
+  - The `DividerSides` type is gone; use `Sides`, from the renamed `sides`
+    module.
+  - `ListInsetText.horizontalOnly` and its `kui-list-inset-text--horizontal`
+    class are gone; pass `sides="rl"` instead.
+  - The legacy color tokens are gone, both as `--kui-color-*` properties and
+    as `uiColor()` names. Replace them with their canonical tokens:
+
+    | Removed                                       | Use instead             |
+    | --------------------------------------------- | ----------------------- |
+    | `border`                                      | `neutral-border-normal` |
+    | `border-quiet`                                | `neutral-border-quiet`  |
+    | `accent`                                      | `brand-fill-normal`     |
+    | `accent-text`                                 | `brand-on-quiet`        |
+    | `pop`                                         | `pop-fill-quiet`        |
+    | `pop-text`                                    | `pop-on-fill`           |
+    | `success`, `warning`, `danger`                | `*-fill-quiet`          |
+    | `success-text`, `warning-text`, `danger-text` | `*-on-quiet`            |
+
 - **New `@kerfjs/ui` `PopupMenu` (`@kerfjs/ui/popup-menu`).** It renders a
   trigger and typed commands, headings, and dividers over the Web Awesome
   dropdown. Put it in a `single` `ToolbarControlGroup` with `nestedDropdown`, or