@kerfjs/ui 5.0.0-beta.55 → 5.0.0-beta.57

package/docs/workbench.md

@@ -9,9 +9,15 @@ desktop-class devices.
 
 ```ts
 import { Workbench } from "@kerfjs/ui/workbench";
-import "@kerfjs/ui/workbench.css";
 ```
 
+In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
+webpack do by default), the import above also
+loads Workbench's stylesheet and those of the components it renders internally
+(`Pane`, `Toolbar`, `ToolbarControlGroup`, `FloatingToolbar`, `ResizableRegion`,
+`List`, `LucideIcon`). Without that condition, import the manual stylesheets instead:
+`@kerfjs/ui/workbench.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
+
 A top-level `Workbench` needs a definite containing height. Import the opt-in
 `@kerfjs/ui/document.css` baseline and add `.kui-app-root` to the direct mount
 container, or provide an equivalent definite height in application-owned
@@ -107,7 +113,13 @@ an optional `label`. Common shell behavior is configured rather than restyled:
   defaults to two less than the overlay z-index (39), so they sit beneath
   every overlay: an open overlay covers another panel's restore control as
   it covers the rest of the work area, and a collapsed overlay, which drops
-  its pointer events, leaves the control beneath it usable;
+  its pointer events, leaves the control beneath it usable. While a rail
+  overlay is open (static, or a responsive one whose breakpoint applies), the
+  work area's floating controls — restore corners and any `FloatingToolbar`
+  in `main` — are also hidden outright (out of the tab order and the
+  accessibility tree), so they can never paint over the rail whatever
+  stacking context the app gives the work area; they return as it closes.
+  The rail's own floating controls stay, and a drawer overlay hides nothing;
 - `restoreControl` places an application-owned restore affordance in a
   corner of the Workbench itself while the panel is collapsed. Prefer a
   `toolbar.toggle`, which the Workbench relocates for you; keep
@@ -130,8 +142,8 @@ an optional `label`. Common shell behavior is configured rather than restyled:
   carrying `collapsiblePanelToggleIcon(side, true)` — rather than a bare
   button. To give it `FloatingToolbar`'s toolbar role and floating look, wrap
   that group in a `FloatingToolbar` whose `position` matches the corner: the
-  corner owns the inset (it sets `--kui-floating-toolbar-inset` to 0), so the
-  toolbar floats from the corner instead of doubling it.
+  corner owns the inset (it zeroes the toolbar's default inset), so omit
+  `inset` there and the toolbar floats from the corner instead of doubling it.
 
 - `resizable: true | { min, max }` opts the panel in to drag and keyboard
   resizing, driven by `wireWorkbench` (off by default).
@@ -154,10 +166,12 @@ and close. A panel's `toolbar` has four parts:
 - `constant` — groups that stay available either way. They trail the panel's
   toolbar while it is open and move to the work area's toolbar while it is
   closed.
-- `toggle: { action, name }` — the standard collapse toggle, which the
-  Workbench renders: the per-side panel glyph, `aria-controls` naming the
-  panel, `aria-expanded`, a "Show …"/"Hide …" label, and the `data-action`
+- `toggle: { action, name, showLabel?, hideLabel? }` — the standard collapse
+  toggle, which the Workbench renders: the per-side panel glyph,
+  `aria-controls` naming the panel, `aria-expanded`, a "Show …"/"Hide …"
+  label (or your localized `showLabel` / `hideLabel`), and the `data-action`
   the app handles. It is always the last group.
+- `center` — optional panel-only center content.
 
 While a panel is closed, its `constant` groups and then its toggle go to:
 
@@ -198,9 +212,40 @@ The work area's `Pane` can carry more fixed chrome: `mainHeader` renders under
 line or a resource toolbar), each divided from the scrolling `main`.
 `mainHeaderPlacement` and `mainFooterPlacement` (`"fixed"` by default, or
 `"scroll"`) let that header or footer chrome scroll away with `main` instead —
-useful where large text would leave pinned chrome little room. `mainToolbar` also
-takes the `Toolbar`'s `responsive` / `responsiveAt` policy; `responsive: "wrap"`
-keeps a long title whole and wraps its actions below it.
+useful where large text would leave pinned chrome little room. `"auto"` keeps
+it pinned while the work area is tall enough and lets it scroll with `main`
+when the work area is short (the Pane's `chromePlacement="auto"`; it applies to
+the pinned header and footer together).
+
+Every toolbar the Workbench composes — `mainToolbar`, `mainBottomToolbar`, and
+each panel's `toolbar` — takes the `Toolbar`'s configuration (`ToolbarConfig`):
+`dividerSides`, `centerAlign`, `responsive`, `responsiveAt`, and
+`safeAreaEdges`. Configure the toolbar through these props rather than styling
+it. No toolbar draws a divider by default: each `Pane` draws one line under
+its header chrome and one over its footer chrome, wherever that chrome ends,
+only while its content is scrolled beneath it (see
+[Scroll dividers](./layout.md#scroll-dividers) — call `wireScrollDividers`
+once at the app root). Set `dividerSides` only for a permanent separator edge,
+or `chromeDividers: "always"` on the pane for a line that never hides.
+`responsive: "wrap"` keeps a long title whole and wraps its actions
+below it. `mainBottomToolbar` also takes a `center`. A panel's
+`restorePosition` also places its floating restore controls.
+
+The `Pane`s and `List`s the Workbench composes around your content are
+configurable the same way:
+
+- `mainPane` (`PaneConfig`: `contentElement`, `contentLabel`, `separators`,
+  `safeAreaEdges`, `chromeDividers`) configures the work area's `Pane`, which exists whenever the
+  work area has a toolbar, `mainHeader`, or `mainFooter`;
+- a panel's `pane` configures the `Pane` a `toolbar` panel's `content` renders
+  in — for example `{ contentElement: "nav", contentLabel: "Files" }` for a
+  navigator rail;
+- `mainHeaderList` / `mainFooterList` (`ListConfig`: `gap`, `hAlign`,
+  `vAlign`, `dividerSides`, `textInsets`, `controlInsets`) configure the
+  `List`s holding `mainHeader` / `mainFooter`.
+
+An omitted or `undefined` field keeps the default, including the scroll
+dividers described above.
 
 Size a rail so its title and groups fit at its narrowest (a resizable rail's
 `min`); a toolbar that cannot hold them drops the title rather than
@@ -487,7 +532,8 @@ when each policy applies.
 
 ## Public styling boundary
 
-Import `@kerfjs/ui/workbench.css` after the component subpath. Applications may
+The component subpath's browser build loads `workbench.css`; import
+`@kerfjs/ui/workbench.css` manually only without the `browser` condition. Applications may
 set `--kui-workbench-rail-width` and `--kui-workbench-drawer-height` on a
 Workbench instance. The supported composition classes are `.kui-workbench`,
 `.kui-workbench__rail`, `.kui-workbench__rail--left`,

package/doctor/index.mjs

@@ -21,7 +21,11 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { createRequire } from 'node:module';
 
 import { loadApplicationUiProfile } from '../ai/application-ui-profile.mjs';
-import { analyzeUiProject, UI_ANALYSIS_RULES } from '../analyzer/index.mjs';
+import {
+  analyzeUiProject,
+  UI_ANALYSIS_ACTIONS,
+  UI_ANALYSIS_RULES,
+} from '../analyzer/index.mjs';
 import { evaluateUi, UI_EVALUATION_RULES } from '../evaluator/index.mjs';
 import {
   isForeignRuleDefinitionDiagnostic,
@@ -547,6 +551,7 @@ function normalizeAnalyzer(report) {
         evidence: item.evidence,
         catalogFacts: item.chain,
         action:
+          UI_ANALYSIS_ACTIONS[item.ruleId] ??
           'Apply the catalog-declared composition or geometry boundary at this source location.',
         meaning: UI_ANALYSIS_RULES[item.ruleId]?.title ?? item.ruleId,
       }),

package/llms.txt

@@ -17,6 +17,17 @@ component per source file and one owned stylesheet per visual component. Keep it
 compatibility entrypoints implementation-free: JavaScript/TypeScript only re-exports
 the folder modules, and CSS only imports their owner stylesheets.
 
+## The rule: components own their styles
+
+Configure components through their typed props (size, density, inset,
+presentation, `ToolbarConfig`, `PaneConfig`, …); never restyle one from outside.
+No application or parent CSS may select a `.kui-*` class, a `[data-component]`
+root, a `wa-*` element a Kerf component renders, or its `::part()`s, and no
+writing another component's `--_kui-*` / `--kui-*` variables where a prop
+exists. When a component adapts inside another, it styles itself in that
+context in its own stylesheet. A missing prop is a component gap to report,
+not a reason to override — and your own components follow the same rule.
+
 ## How to build a screen (retrieval order)
 
 1. **Pick the component from the interface need**, not by appearance — read
@@ -25,20 +36,32 @@ the folder modules, and CSS only imports their owner stylesheets.
 2. **Get exact signatures before emitting code** — read
    [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) (real prop names,
    callback shapes, disposer return types).
-3. **For exhaustive, structured facts** (ids, exports, variants, `publicClasses`,
-   relationships, side effects, and geometry ownership) load the
-   [Machine-readable component catalog](./ai/component-catalog.json) — the
-   canonical checked-in source; its schema is alongside it. Also load the
+3. **Look up each component you use** in the
+   [component reference index](./ai/components/README.md) — one line per
+   entry — then read only those `ai/components/<id>.md` pages (1–7 KB each):
+   use/avoid, imports and side effects, a link to exact props, legal parents,
+   zones with their JSX prop and child count, app- and wiring-owned state,
+   geometry, accessibility, the styling boundary (configure through props;
+   never override internals), and `KUI-C###` diagnostics. Do not load the
+   large JSON catalogs just to choose or compose components; the pages are
+   generated from them.
+   **Tools and mechanical checks** use the JSON sources instead: the
+   [Machine-readable component catalog](./ai/component-catalog.json) (ids,
+   exports, variants, `publicClasses`, relationships, side effects, and
+   geometry ownership) — the canonical checked-in source; its schema is
+   alongside it. Also load the
    consuming application's catalog extension when present; generate one from the
    [Consumer catalog extension schema](./ai/component-catalog-extension.schema.json)
    when app-owned components must participate in selection or alignment.
-   Load the [Composition catalog v2](./ai/component-catalog-v2.json) to
-   mechanically evaluate parents, contexts, zones/cardinality, children, state,
-   wiring (including the wiring-owned `stateAttributes` an app must never
-   render or remove), responsive/layout/accessibility rules, and public
-   boundaries. V1
-   remains compatible; v2 joins catalogs by `package:id`. Consumer v2 catalogs
-   use [the v2 extension schema](./ai/component-catalog-extension-v2.schema.json).
+   A tool loads the [Composition catalog](./ai/component-composition.json) — a
+   generated composition layer beside the component catalog, not a replacement
+   for it — to mechanically evaluate parents, contexts, zones/cardinality,
+   children, state, wiring (including the wiring-owned `stateAttributes` an app
+   must never render or remove), responsive/layout/accessibility rules, and
+   public boundaries. The component catalog stays the selection and delivery
+   surface; the composition layer joins catalogs by `package:id`. Consumer
+   composition catalogs use
+   [the composition extension schema](./ai/component-composition-extension.schema.json).
    Load [compile-time contracts](./ai/compile-time-contracts-v1.json) for stable
    `KUI-T###` ids, exact declaration symbols, and the boundary between rejected
    source states and relationships that still require runtime/catalog checks.
@@ -83,7 +106,10 @@ the folder modules, and CSS only imports their owner stylesheets.
    prefer its canonical shorthand or typed helper over raw CSS strings; a
    `--wa-color-{tone}-fill-loud` override without a governing `on-loud` (same
    or ancestor scope, possibly in a co-loaded stylesheet), or whose literal
-   pair measures below 4.5:1, is review finding `KUI-L018` (set both); repair source-located errors until exit 0. Use full mode for release gates;
+   pair measures below 4.5:1, is review finding `KUI-L018` (set both); CSS that restyles a component
+   (`KUI-L019`), touches its private `--_*` variables (`KUI-L020`), overrides a token a typed prop sets
+   (`KUI-L021`), or styles it through a hook class on its root (`KUI-L022`) is an error: configure the
+   component instead, and report a component gap when no prop exists; repair source-located errors until exit 0. Use full mode for release gates;
    generated `dist`/`coverage`, dependency, cache, evidence, and nested-worktree
    directories are excluded consistently from every static stage.
    [`kerf-ui-analyze`](./docs/ui-analyzer.md) remains available when only static
@@ -98,15 +124,26 @@ the folder modules, and CSS only imports their owner stylesheets.
 
 ## Core rules (do the right thing)
 
+- **Prefer a Kerf UI component over a Web Awesome component over a raw HTML
+  tag**, using each for what it is good at. Never render a `Discouraged` Web
+  Awesome element (`wa-dropdown`, `wa-button-group`, `wa-select`, `wa-tab-group`,
+  `wa-icon`, …) directly; reach it only through the Kerf component that wraps or
+  replaces it (`PopupMenu`, `SegmentedControl`, `Select`, `TabBar`,
+  `LucideIcon`), and file a component gap rather than dropping to the raw tag.
 - **Reach for the primitive, not for CSS.** The package is built to look right
   without an application customization layer. Before adding `padding`, `margin`,
   `width`, `height`, `border`, `background`, a wrapper card, or a decoration,
   check whether the component, pane, or content-item already owns it. Prefer a
-  component prop or documented `--kui-*` token. CSS for genuinely new structure
+  component prop — `FloatingToolbar inset`, `DisclosureArrow size`, `ListHeader
+headingLevel`, `TokenSearchField clearIcon`, `ContentItem frame="framed"` for a
+  visibly bounded content item — over overriding its `--kui-*` token. CSS for genuinely new structure
   belongs to the application-owned component that renders it and must not select
   nested Kerf or Web Awesome components.
 - **Never double-inset.** A `.kui-pane` has no padding; its `.kui-content` children
-  own the geometry (8px inline margin + 1px border + 8px padding). Do not add a
+  own the geometry (8px inline margin + 1px border + 8px padding). Render an
+  ordinary surface-like child as `ContentItem` (`@kerfjs/ui/content-item`) with
+  typed `frame` (`none`/`framed`) and `shape` (`rounded`/`pill`) props instead
+  of hand-writing `<div class="kui-content-item">`. Do not add a
   container padding on top of a content-item's own margin — pick one owner. Use
   `.kui-content` for 24px major vertical rhythm.
 - **Opt into document globals explicitly.** Import `@kerfjs/ui/document.css`
@@ -129,7 +166,7 @@ the folder modules, and CSS only imports their owner stylesheets.
   `@kerfjs/ui/css-values` builders; raw CSS strings are rejected. Use `flex()`
   for List flex, typed lengths for Skeleton geometry, and
   foreground colors for choice icons: `uiColor()` with an `*-on-*`/text token
-  or `foregroundColorVar()`; fill aliases such as `uiColor('success')` do not
+  or `foregroundColorVar()`; fill tokens such as `uiColor('success-fill-quiet')` do not
   type-check. These brands are intentionally
   not interchangeable; rows use classes/tokens/props rather than raw `style`.
 - **Use `Grid` for a fixed positive count of equal-width columns.** It uses
@@ -170,7 +207,21 @@ the folder modules, and CSS only imports their owner stylesheets.
   label uses the same uppercase xs/650 treatment and its label and hint share
   that 9px alignment.
 - `Select` requires a visible `label` or an `ariaLabel` for a visually hidden
-  accessible name. The package names the internal combobox, including custom
+  accessible name. Set `multiple` with an array `value` for any number of
+  choices: the popup stays open while choices toggle and closes on an outside
+  press or Escape, and the closed control summarizes the chosen labels. A
+  toolbar filter menu adds `selectedPresentation="icon-only"` and a fixed
+  `triggerIcon`: the trigger shows that icon plus a count badge while any
+  choice is chosen, and its accessible name ends with the chosen labels.
+  Icon-only Selects (single or multiple) and icon-only `PopupMenu`s show an
+  `aria-hidden` Web Awesome help tag repeating that name (and a Select's
+  choice) on hover and keyboard focus, hidden while the popup is open; the
+  register import installs it, so do not add a `title` or tooltip of your own.
+  The same installer tags an icon-only `<button>` or link inside a
+  `ToolbarControlGroup` named by `aria-label` (no visible text or `title`);
+  import `@kerfjs/ui/help-tags/register` once when a toolbar has such buttons
+  but no registered Select or PopupMenu.
+  The package names the internal combobox, including custom
   selected content; consumers do not need shadow-DOM naming workarounds.
   Import `select/register` once for the canonical animation lifecycle: stale
   close/show completions cannot override a later request. Consumers must not
@@ -191,12 +242,19 @@ the folder modules, and CSS only imports their owner stylesheets.
   (`@kerfjs/ui/popup-menu`, registered once via `@kerfjs/ui/popup-menu/register`)
   in a `single` `ToolbarControlGroup` with `nestedDropdown`; never hand-write
   `wa-dropdown` markup for a menu. Let the group size the trigger from its icon,
-  localized text, and caret; do not force a dropdown or button width. Compact
+  localized text, and caret; do not force a dropdown or button width. Nothing
+  wraps inside a group: an icon sits beside its label on one row, and a
+  `ToolbarText` is one ellipsized line unless you opt into `wrap`/`maxLines`. 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. Compact
   mixed groups keep standard item padding and raised selected chrome without an
   internal separator; the selected item paints over the outer border. For an
   avatar control, set `content="avatar"` and `avatarImage` on the group instead of
   inserting an `img`; a lone control paints the group and a multi-button group
-  paints only its pressed highlight.
+  paints only its pressed highlight. Dividers earn their place: a `Toolbar`
+  draws none by default and pinned chrome gets its line from scroll state (see
+  the scroll-divider rule below); never fake one with a border or pad below a
+  divider to make it look right.
 - **Use one direct toolbar composition for panel/dialog/page headings.** Put an
   optional icon in a `ToolbarControlGroup`, an extra-large `ToolbarText` directly
   in the leading zone, and actions in a trailing group. Supporting copy is
@@ -223,10 +281,34 @@ the folder modules, and CSS only imports their owner stylesheets.
   radius minus `--kui-layout-highlight-inset`. Do not give an inner highlight an
   unrelated radius.
 - **Panes share one child-owned geometry.** Sidebars, main areas, inspectors, and
-  dialogs all use an unpadded `.kui-pane` (optional `.kui-pane__toolbar`, one
-  scrolling `.kui-pane__content`, optional `.kui-pane__footer`). A visible pane owns
-  its collapse control; a hidden pane's restore moves to the adjacent main
-  toolbar's matching edge — no icon-only rail. Keep one scroll owner per region.
+  dialogs all render `Pane`: an unpadded `.kui-pane` (optional header, one
+  scrolling `.kui-pane__content`, optional footer). Never write a component's
+  anatomy classes onto your own element to recreate it (`KUI-L103`); only
+  the catalog's `placeableClasses` (layout utilities, `.kui-app-root`,
+  `.kui-content-item` on a non-div carrier) belong there. A visible pane owns
+  its collapse control (the last control of its last group); a hidden pane's
+  restore moves to the adjacent main toolbar's matching edge — no icon-only
+  rail — and a collapsed drawer's restore sits in the bottom toolbar or a
+  `FloatingToolbar` beside the drawer, near where its effect appears. Align
+  text to text and icons to icons across a pane; a border is decoration, never
+  the alignment anchor. Keep one scroll owner per region.
+- **Dividers between pinned chrome and scrolling content are scroll state.**
+  Toolbars draw no divider by default. Call `wireScrollDividers(appRoot)`
+  (`@kerfjs/ui/wire-scroll-dividers`) once and keep its disposer: every `Pane`
+  then draws the line under its header only while content is scrolled beneath
+  it and the line over its footer only while more content lies below (never
+  when the content fits), every `NavStack`'s top chrome and bottom toolbar and
+  every `TabScaffold` bar do the same around the active view or scene, and
+  every `TabBar` marks each side of its strip with tabs scrolled out of view. Configure a pane with `chromeDividers`
+  (`scroll` default, `always`, `none`), and a `NavStack` or `TabScaffold`
+  with its own `chromeDividers` (same values; a `SplitView` forwards it through
+  `compactStack`); name app-owned chrome in `targets`.
+  Never add a border, or a permanent `dividerSides`, to fake one.
+  While a side overlay is open (a Workbench rail overlay, a `wireSidebar` compact
+  overlay, an overlay `CollapsiblePanel` or horizontal `ResizableRegion`), the
+  layout hides the covered work area's `FloatingToolbar`s and restore corners
+  itself (unfocusable, out of the accessibility tree) until it closes — do not
+  hide them from overlay state yourself.
 - **State and behavior live in the app.** Components take semantic `data-action`
   strings and controlled values; wire them once with `delegate()`/`delegateActions()`
   or the disposer-returning `wire…` helpers, and own domain copy, transport, and
@@ -240,7 +322,9 @@ the folder modules, and CSS only imports their owner stylesheets.
   (mark a preferred new-view target with `data-nav-focus`), `wireTabBars` the
   overflow autoscroll, drag preview, and
   replacement focus after controlled automatic tab activation,
-  `wireResizableRegions` the live drag preview; they report committed changes via
+  `wireResizableRegions` the live drag preview, `wireScrollDividers` the
+  scroll-state attributes from which a `Pane` draws its chrome dividers and a
+  `TabBar` its overflow dividers; they report committed changes via
   callbacks. For a tab-local action plus a separate far-edge action, set
   `TabBar trailingPlacement="adjacent"`, put the local action in `trailing`, and
   the workspace action in `end`; the component keeps both visible while its tab
@@ -290,6 +374,10 @@ the folder modules, and CSS only imports their owner stylesheets.
 - **Use `Badge` for compact non-interactive metadata.** Configure its semantic
   tone, appearance, shape, and size instead of creating badge CSS in an app or
   consuming component. Use a real button or link for interactive content.
+  For new content without a count, use the text-free `size="dot"` form: it
+  takes no children, and needs a `label` (announced as an image) or
+  `ariaHidden` when its owner announces it. A `TabScaffold` tab shows the dot
+  with `badge: true` plus its required `badgeLabel`.
 
 ## Public exports
 
@@ -298,9 +386,13 @@ the folder modules, and CSS only imports their owner stylesheets.
 `ListInsetText`, `SegmentedControl`,
 `Select`, `TokenSearchField` (+ `readTokenSearchField`, `placeTokenSearchCaret`,
 `wireTokenSearchFields`), `AppTab`, `TabBar` (+ `wireTabBars`, `reorderTabs`),
+`wireScrollDividers` (scroll-state dividers for every `Pane`, `NavStack`,
+`TabScaffold`, and `TabBar`),
 `ResizableRegion` (+ `wireResizableRegions`), `StateBanner`, `EmptyState`,
 `LoadingSpinner`, `Skeleton`, `ValueTable`, `ValueTableRow`. Whole-screen layouts (opt-in,
-tree-shakeable, declarative with `wire…` helpers, each with a companion CSS import):
+tree-shakeable, declarative with `wire…` helpers; the browser build of each layout
+subpath loads its CSS and that of the components it renders, and a companion
+CSS subpath remains for pipelines without the `browser` condition):
 `NavStack`, `SplitView`, `Workbench`, `TabScaffold`, driven by `deviceClass()` from
 `@kerfjs/ui/device-class`. For a standalone collapsible rail/drawer outside a full
 shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelToggle`)
@@ -329,6 +421,7 @@ shell, `@kerfjs/ui/collapsible-panel` (`CollapsiblePanel`, `CollapsiblePanelTogg
 - [workbench.md](./docs/workbench.md): the `Workbench` multi-panel shell, its collapse policies, and opt-in `resizable` panels driven by `wireWorkbench` (`@kerfjs/ui/wire-workbench`: drag, keyboard, min/max, persistence, compact suspension), the `mainMinSize` / `mainMinHeight` work-area minimums (default 320px wide beside any inline rail, 120px tall above the drawer) that resizable panels stop at and inline panels shrink around, and a panel's `responsiveOverlayAt` (`narrow` / `compact`, rails and the bottom drawer) that presents it as an overlay below a Workbench container breakpoint without a device-class check; a panel given its `collapsed` signal is a transient overlay (collapsed on entering the breakpoint, takes focus and keeps Tab inside while open, closed by Escape or an outside press, focus returned; `dismissOverlays`), and overlays are exclusive by default (opening one closes the others; `exclusiveOverlays: false` opts out).
 - [app-layouts.md](./docs/app-layouts.md): choosing `NavStack`/`SplitView`/`Workbench`/`TabScaffold` by data + interaction + device, and dialog presentation, plus the safe-area model (surfaces paint through unsafe areas; content pads only the edges it reaches; `Pane.safeAreaEdges` for app-owned arrangements, `Toolbar.safeAreaEdges` for an app bar or bottom bar at a screen edge).
 - [webawesome-theme.md](./docs/webawesome-theme.md): the optional Web Awesome theme; catalog coverage means themed-and-supported, not preferred (prefer the Kerf primitive when one exists). The UX sidebar visibly tags superseded and exceptional Web Awesome choices as `Discouraged`; Popup remains an available conditional positioning primitive.
+- [ai/components/README.md](./ai/components/README.md): the generated per-component markdown reference — the assistant entry point over both JSON catalogs.
 - [component-catalog.json](./ai/component-catalog.json) + [component-catalog-extension.schema.json](./ai/component-catalog-extension.schema.json) + [catalog-authoring.json](./ai/catalog-authoring.json) + [public-api-signatures-v1.md](./ai/public-api-signatures-v1.md) + [webawesome-jsx-signatures-v1.md](./ai/webawesome-jsx-signatures-v1.md): machine-readable selection facts, a reusable app-component extension contract, Catalog authoring discovery, and exact signatures.
 - [compile-time-contracts-v1.json](./ai/compile-time-contracts-v1.json) + [type-contracts.md](./docs/type-contracts.md): stable compile diagnostics, packed-declaration proof, migrations, and explicit non-goals.
 - [README.md](./README.md): package overview and the component subpath table.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kerfjs/ui",
-  "version": "5.0.0-beta.55",
+  "version": "5.0.0-beta.57",
   "description": "Accessible, composable UI primitives for kerf applications.",
   "type": "module",
   "license": "MIT",
@@ -38,7 +38,8 @@
     "**/*.css",
     "./dist/browser/*.js",
     "./dist/select-register.js",
-    "./dist/popup-menu-register.js"
+    "./dist/popup-menu-register.js",
+    "./dist/help-tags-register.js"
   ],
   "exports": {
     ".": {
@@ -139,6 +140,11 @@
       "browser": "./dist/browser/list-inset-text.js",
       "import": "./dist/list-inset-text.js"
     },
+    "./content-item": {
+      "types": "./dist/content-item.d.ts",
+      "browser": "./dist/browser/content-item.js",
+      "import": "./dist/content-item.js"
+    },
     "./resizable-region": {
       "types": "./dist/resizable-region.d.ts",
       "browser": "./dist/browser/resizable-region.js",
@@ -159,6 +165,7 @@
     },
     "./catalog": {
       "types": "./dist/catalog.d.ts",
+      "browser": "./dist/browser/catalog.js",
       "import": "./dist/catalog.js"
     },
     "./catalog-resources": {
@@ -194,8 +201,13 @@
       "types": "./dist/wire-tab-bars.d.ts",
       "import": "./dist/wire-tab-bars.js"
     },
+    "./wire-scroll-dividers": {
+      "types": "./dist/wire-scroll-dividers.d.ts",
+      "import": "./dist/wire-scroll-dividers.js"
+    },
     "./nav-stack": {
       "types": "./dist/nav-stack.d.ts",
+      "browser": "./dist/browser/nav-stack.js",
       "import": "./dist/nav-stack.js"
     },
     "./wire-nav-stack": {
@@ -204,6 +216,7 @@
     },
     "./split-view": {
       "types": "./dist/split-view.d.ts",
+      "browser": "./dist/browser/split-view.js",
       "import": "./dist/split-view.js"
     },
     "./pane": {
@@ -213,10 +226,12 @@
     },
     "./workbench": {
       "types": "./dist/workbench.d.ts",
+      "browser": "./dist/browser/workbench.js",
       "import": "./dist/workbench.js"
     },
     "./collapsible-panel": {
       "types": "./dist/collapsible-panel.d.ts",
+      "browser": "./dist/browser/collapsible-panel.js",
       "import": "./dist/collapsible-panel.js"
     },
     "./wire-sidebar": {
@@ -225,6 +240,7 @@
     },
     "./tab-scaffold": {
       "types": "./dist/tab-scaffold.d.ts",
+      "browser": "./dist/browser/tab-scaffold.js",
       "import": "./dist/tab-scaffold.js"
     },
     "./wire-tab-scaffold": {
@@ -282,6 +298,10 @@
       "types": "./dist/select-register.d.ts",
       "import": "./dist/select-register.js"
     },
+    "./help-tags/register": {
+      "types": "./dist/help-tags-register.d.ts",
+      "import": "./dist/help-tags-register.js"
+    },
     "./webawesome": {
       "types": "./dist/webawesome.d.ts",
       "import": "./dist/webawesome.js"
@@ -328,6 +348,7 @@
     "./list-header.css": "./dist/styles/list-header.css",
     "./list-inset-control.css": "./dist/styles/list-inset-control.css",
     "./list-inset-text.css": "./dist/styles/list-inset-text.css",
+    "./content-item.css": "./dist/styles/content-item.css",
     "./resizable-region.css": "./dist/styles/resizable-region.css",
     "./app-tab.css": "./dist/styles/app-tab.css",
     "./catalog.css": "./dist/styles/catalog.css",
@@ -374,12 +395,12 @@
     "format": "prettier --write . --ignore-unknown",
     "format:css": "prettier --write \"src/**/*.css\" \"ux-demo/**/*.css\"",
     "check:format": "prettier --check . --ignore-unknown",
-    "catalog:sync": "node scripts/sync-component-catalog.mjs && node scripts/sync-component-catalog-v2.mjs",
-    "catalog:v2:sync": "node scripts/sync-component-catalog-v2.mjs",
+    "catalog:sync": "node scripts/sync-component-catalog.mjs && node scripts/sync-component-composition.mjs && node scripts/sync-component-docs.mjs",
+    "composition:sync": "node scripts/sync-component-composition.mjs && node scripts/sync-component-docs.mjs",
     "check:component-integrations": "node scripts/check-component-integrations.mjs",
     "component-integrations:dry-run": "node scripts/check-component-integrations.mjs --dry-run",
     "check:change": "node scripts/check-ui-change.mjs",
-    "check:catalog": "node scripts/sync-component-catalog.mjs --check && node scripts/sync-component-catalog-v2.mjs --check && node scripts/check-component-catalog.mjs",
+    "check:catalog": "node scripts/sync-component-catalog.mjs --check && node scripts/sync-component-composition.mjs --check && node scripts/sync-component-docs.mjs --check && node scripts/check-component-catalog.mjs",
     "check:profile": "node scripts/check-application-ui-profile.mjs",
     "check:demo-conformance": "node scripts/check-catalog-demo-conformance.mjs",
     "check:recipes": "node scripts/check-recipes.mjs",
@@ -391,6 +412,7 @@
     "ai:compatibility:sync": "node scripts/sync-ai-compatibility.mjs --write",
     "ai:regressions:compile": "node scripts/compile-ai-regression-response.mjs",
     "ai:regressions:prepare": "node scripts/prepare-ai-regression.mjs",
+    "ai:regressions:measure-context": "node scripts/measure-ai-regression-context.mjs",
     "ai:regressions:record": "node scripts/record-ai-regression-run.mjs",
     "ai:regressions:record-v3": "node scripts/record-ai-regression-run-v3.mjs",
     "ai:regressions:replay-v3": "node scripts/replay-ai-regression-run-v3.mjs",
@@ -399,12 +421,13 @@
     "lint:eslint": "eslint src tests ux-demo docs/examples --max-warnings 0",
     "lint": "npm run lint:eslint && npm run check:format",
     "typecheck": "node node_modules/typescript7/bin/tsc --noEmit",
-    "test": "npm run test:unit && npm run test:bundle && npm run test:analyzer && npm run test:doctor && npm run test:evaluator",
+    "test": "npm run test:unit && npm run test:bundle && npm run test:analyzer && npm run test:doctor && npm run test:evaluator && npm run test:ai-regressions",
     "test:unit": "vitest run tests/unit --coverage",
     "test:bundle": "npm run build && vitest run tests/bundle",
     "test:analyzer": "vitest run tests/integration/ui-analyzer-downstream.test.ts",
     "test:doctor": "vitest run tests/unit/ui-doctor.test.ts tests/integration/ui-doctor-downstream.test.ts",
     "test:evaluator": "vitest run tests/unit/ui-evaluator.test.ts tests/integration/ui-evaluator-downstream.test.ts",
+    "test:ai-regressions": "vitest run tests/integration/ai-regressions-v3.test.ts",
     "test:contract-types:source": "node node_modules/typescript7/bin/tsc -p tests/consumer-types/contracts/tsconfig.source.json",
     "test:contract-types:packed": "node scripts/check-packed-type-contracts.mjs",
     "test:consumer-types": "npm run test:contract-types:source && npm run build && node node_modules/typescript7/bin/tsc -p tests/consumer-types/webawesome/tsconfig.json && npm run test:contract-types:packed",

package/ux-demo/recipes/collapsible-sidebar.tsx

@@ -7,6 +7,7 @@ import {
   CollapsiblePanelRelocated,
   type CollapsiblePanelToolbar,
 } from '@kerfjs/ui/collapsible-panel';
+import { ContentItem } from '@kerfjs/ui/content-item';
 import { deviceClass } from '@kerfjs/ui/device-class';
 import { FloatingToolbar } from '@kerfjs/ui/floating-toolbar';
 import { Grid } from '@kerfjs/ui/grid';
@@ -133,7 +134,6 @@ export const createRecipe: RecipeFactory = (announce) => {
       header={
         <Toolbar
           label="Current navigation view"
-          dividerSides=""
           leading={
             <>
               <CollapsiblePanelRelocated
@@ -152,7 +152,7 @@ export const createRecipe: RecipeFactory = (announce) => {
         />
       }
     >
-      <div class="kui-content-item">
+      <ContentItem>
         <List gap="2xs">
           <Text variant="span">
             <strong>Narrow the window to a compact width</strong>
@@ -162,7 +162,7 @@ export const createRecipe: RecipeFactory = (announce) => {
             a backdrop, Escape, and a trapped Tab ring, all managed by the wire.
           </Text>
         </List>
-      </div>
+      </ContentItem>
     </Pane>
   );
 

package/ux-demo/recipes/composer-form.tsx

@@ -64,7 +64,6 @@ export const createRecipe: RecipeFactory = (announce) => {
         <List>
           <Toolbar
             label="Publish workspace update"
-            dividerSides=""
             leading={
               <ToolbarText
                 text="Publish workspace update"

package/ux-demo/recipes/list-detail-dialog.tsx

@@ -114,7 +114,6 @@ export const createRecipe: RecipeFactory = (announce) => {
       header={
         <Toolbar
           label="Recent projects"
-          dividerSides=""
           leading={<ToolbarText text="Recent projects" />}
         />
       }
@@ -131,7 +130,6 @@ export const createRecipe: RecipeFactory = (announce) => {
         header={
           <Toolbar
             label="Project details"
-            dividerSides=""
             leading={
               <ToolbarText
                 text={record.name}

package/ux-demo/recipes/list-workspace-states.tsx

@@ -135,7 +135,6 @@ export const createRecipe: RecipeFactory = (announce) => {
       header={
         <Toolbar
           label="Release tasks"
-          dividerSides=""
           responsive="stack"
           responsiveAt="compact"
           leading={

package/ux-demo/recipes/loading-inspector.tsx

@@ -59,7 +59,6 @@ export const createRecipe: RecipeFactory = (announce) => {
           <>
             <Toolbar
               label="Ticket inspector"
-              dividerSides=""
               responsive="wrap"
               leading={
                 <>

package/ux-demo/recipes/navigation-sidebar.tsx

@@ -1,5 +1,6 @@
 import '@kerfjs/ui/layout.css';
 
+import { ContentItem } from '@kerfjs/ui/content-item';
 import { List } from '@kerfjs/ui/list';
 import { ListHeader } from '@kerfjs/ui/list-header';
 import { ListItem } from '@kerfjs/ui/list-item';
@@ -120,7 +121,7 @@ export const createRecipe: RecipeFactory = (announce) => {
               disabled
               title="Available to administrators"
             />
-            <div class="kui-content-item">
+            <ContentItem>
               <List gap="2xs">
                 <Text variant="span">
                   <strong>Quarterly goal</strong>
@@ -129,7 +130,7 @@ export const createRecipe: RecipeFactory = (announce) => {
                   Ship accessible navigation patterns to every workspace.
                 </Text>
               </List>
-            </div>
+            </ContentItem>
           </>
         )}
       </section>