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

package/ai/{component-catalog-v2.schema.json → component-composition.schema.json}

@@ -1,18 +1,25 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-catalog-v2.schema.json",
-  "title": "Kerf UI composition catalog v2",
+  "$id": "https://raw.githubusercontent.com/brianwestphal/kerf/main/ui/ai/component-composition.schema.json",
+  "title": "Kerf UI composition catalog",
   "type": "object",
   "required": ["schemaVersion", "package", "compatibility", "entries"],
   "properties": {
     "$schema": { "type": "string" },
-    "schemaVersion": { "const": 2 },
+    "schemaVersion": {
+      "const": 1,
+      "description": "Version of the composition catalog format itself, independent of component-catalog.json's own schemaVersion."
+    },
     "package": { "type": "string", "minLength": 1 },
     "compatibility": {
       "type": "object",
-      "required": ["v1Catalog", "identity"],
+      "required": ["componentCatalog", "identity"],
       "properties": {
-        "v1Catalog": { "type": "string", "minLength": 1 },
+        "componentCatalog": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Relative path to the component (selection) catalog this composition layer describes, or \"not-applicable\" when the package publishes none."
+        },
         "identity": { "const": "package:id" }
       },
       "additionalProperties": false
@@ -274,6 +281,15 @@
               ]
             },
             "publicClasses": { "$ref": "#/$defs/stringList" },
+            "placeableClasses": {
+              "$ref": "#/$defs/stringList",
+              "description": "The subset of publicClasses an application may place on its own elements. Absent means none: every public class is the component's rendered anatomy, reached by rendering the component."
+            },
+            "rootElement": {
+              "type": "string",
+              "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$",
+              "description": "The intrinsic element the component renders at its root. A placeableClasses class on a plain element of this tag recreates the component; the class stays placeable on any other carrier element."
+            },
             "publicTokens": { "$ref": "#/$defs/stringList" },
             "publicParts": { "$ref": "#/$defs/stringList" }
           },

package/ai/components/README.md

@@ -0,0 +1,170 @@
+# @kerfjs/ui component reference
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+One short page per catalog entry. Pick a component by the interface need from the one-line purposes below, then open only the pages you use. Each page lists when to use and avoid it, imports and CSS/registration side effects, where its exact props live, legal parents, zones with their JSX props and child counts, which state the app owns and which a wiring helper owns, geometry ownership, accessibility obligations, the styling boundary (configure through props; never override internals), and its `KUI-C` diagnostics.
+
+Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-api-signatures-v1.md) (Web Awesome JSX in [`webawesome-jsx-signatures-v1.md`](../webawesome-jsx-signatures-v1.md)). Tools and linters read the canonical machine sources instead: [`component-catalog.json`](../component-catalog.json) (selection and delivery) and [`component-composition.json`](../component-composition.json) (composition), joined by `package:id`. Prefer a Kerf UI component over a Web Awesome element whenever both fit.
+
+## Kerf UI — Foundation
+
+- [Badge](./badge.md) — Present compact metadata without application-authored badge CSS or consumer styling of component internals.
+- [LucideIcon](./lucide-icon.md) — Decorative and meaningfully labeled Lucide-compatible icons.
+- [DisclosureArrow](./disclosure-arrow.md) — Indicate whether a disclosure control is open with an overridable 18px root-scaled visual and shortest-path rotation behavior.
+- [Foundation tokens](./foundation.md) — Provide the shared semantic token foundation for application themes and every styled Kerf UI component.
+- [Document baseline](./document-baseline.md) — Let an application opt into Kerf UI-owned document defaults and a definite full-height chain for a percentage-height application shell.
+- [Application layout](./layout.md) — Provide one reusable pane, toolbar, content stack, and content-item geometry across sidebars, main areas, and dialogs.
+
+## Kerf UI — Structure
+
+- [Pane](./pane.md) — Organize a sidebar, main area, inspector, or dialog column into fixed vertical header/footer chrome around one scrolling content owner.
+- [NavStack](./nav-stack.md) — Present a single linear or drill-down flow while preserving each prior view's state, scroll position, and place in the stack.
+- [SplitView](./split-view.md) — Present a selectable list and its detail together when space permits, with a one-pane drill-down replacement on compact devices.
+- [TabScaffold](./tab-scaffold.md) — Switch among two to five co-equal top-level destinations on compact devices while preserving each destination's independent content state.
+- [Workbench](./workbench.md) — Arrange a complex tool or editor as a stable central work area with optional peripheral rails and a bottom drawer.
+- [CollapsiblePanel](./collapsible-panel.md) — Add one independently collapsible peripheral panel without adopting the complete multi-panel Workbench shell.
+- [SunkenPanel](./sunken-panel.md) — Group a vertical list of application content on a visually lowered surface with one owned 8px inset and an explicit rounded or square-corner shape.
+- [Toolbar](./toolbar.md) — Leading, centered, and trailing toolbar composition.
+- [ToolbarControlGroup](./toolbar-control-group.md) — Provide complete toolbar action geometry through configuration, including semantic anchors, overflow containment, and dropdown menu insets without application CSS.
+- [Surface scaffolds](./surface-scaffold.md) — Configure recurring dialog and popup geometry without consumer ::part() overrides.
+- [FloatingToolbar](./floating-toolbar.md) — A transparent, forced-dark toolbar that floats over its container's content.
+- [ToolbarText](./toolbar-text.md) — Large, default, and compact toolbar identity text.
+- [Text](./text.md) — Render paragraph semantics by default, h1 through h6 when selected, or geometry-free inline secondary text as a span while independently configuring quiet or danger tone, compact size, or monospace font.
+- [Headers](./headers.md) — Page, dialog, and definition-list hierarchy.
+- [ValueTable](./value-table.md) — Key/value rows with optional icons and aligned separators.
+- [Row](./row.md) — Arrange related content horizontally with consistent spacing, optional physical-side text/control insets, and explicit left/center/right/full plus top/middle/bottom/full/baseline alignment instead of application-owned flex wrappers.
+- [Grid](./grid.md) — Arrange related siblings in equal-width columns without repeating application-owned grid-template-columns CSS.
+- [Spacer](./spacer.md) — Express an intentional empty dimension or consume remaining flex space without application-owned spacer markup or raw CSS lengths.
+- [ListInsetControl](./list-inset-control.md) — Apply the standard 8px outer margin to all physical sides of a self-bordered control by default, or only the sides selected with the canonical Sides contract.
+- [ListInsetText](./list-inset-text.md) — Apply the full 8px margin + 1px transparent border + 8px padding to all physical sides of bare text by default, or only the sides selected with the canonical Sides contract.
+- [ContentItem](./content-item.md) — Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, and radius, with framing and shape chosen by typed props instead of hand-written modifier classes.
+
+## Kerf UI — Navigation
+
+- [List](./list.md) — Standardize vertical component layout, optional physical-side text/control insets, and scroll/divider ownership instead of repeating ad-hoc flex-column wrappers.
+- [ListHeader](./list-header.md) — Fill the available section width by default, or shrink-wrap without outer geometry when inline, while splitting a dormant title and mutually exclusive semantic count or badge from an optional logical-end action with an 18px visual; disclosure mode renders the title cluster as a button with a default production DisclosureArrow.
+- [ListActionRow](./list-action-row.md) — Keep a selectable primary row action and an independently named trailing action as sibling native controls inside one noninteractive visual row.
+- [ListItem](./list-item.md) — Selectable, disabled, trailing, and multiline navigation rows.
+- [Application tabs](./application-tabs.md) — Show AppTab and TabBar in a complete controlled composition.
+- [AppTab](./tabs.md) — Roving-tabindex-ready tabs with typed compact, segmented, icon-only, and truncating-label presentations.
+- [TabBar](./tab-bar.md) — Controlled tab strips whose tabs shrink and scroll while fixed leading, trailing, and far-edge end actions remain visible.
+
+## Kerf UI — Controls
+
+- [SegmentedControl](./segmented-control.md) — Controlled exclusive choices in toolbar, rounded-rectangle, and pill presentations.
+- [TokenSearchField](./token-search-field.md) — Token-controlled, optionally collapsible search editor with ordered, editable, removable filter chips.
+- [ResizableRegion](./resize.md) — Pointer and keyboard-operable split region with a customizable handle icon.
+- [Select](./select.md) — Controlled Web Awesome select with typed form, toolbar, navigation, compact, icon-only, truncating, hint, and grouped-choice presentations.
+- [PopupMenu](./popup-menu.md) — A trigger button that opens a typed list of commands, built on the Web Awesome dropdown.
+
+## Kerf UI — Feedback
+
+- [Feedback](./feedback.md) — Banners, empty states, and labeled progress.
+- [StateBanner](./state-banner.md) — Present persistent inline feedback or attractive non-status emphasis with a named semantic tone.
+- [EmptyState](./empty-state.md) — Actionable empty and busy content states.
+- [LoadingSpinner](./loading-spinner.md) — Meaningfully labeled or decorative progress.
+- [Skeleton](./skeleton.md) — A subtle, unanimated loading placeholder block for a not-yet-known value slot.
+
+## Web Awesome — Actions
+
+- [Button](./wa-button.md) — Action control with semantic variants, appearances, loading, and icon support.
+- [Button Group](./wa-button-group.md) (conditional) — Exceptional grouped actions; prefer Kerf SegmentedControl for exclusive choices.
+- [Copy Button](./wa-copy-button.md) — Copies a supplied value and announces success or failure.
+- [Dropdown](./wa-dropdown.md) (conditional) — Action-menu primitive; prefer Kerf Select when choosing a value.
+- [Dropdown Item](./wa-dropdown-item.md) (conditional) — Action-menu row; prefer Kerf Select options for value selection.
+
+## Web Awesome — Forms
+
+- [Checkbox](./wa-checkbox.md) — Binary form control with checked, indeterminate, and disabled states.
+- [Checkbox Group](./wa-checkbox-group.md) — Labels and validates a related set of checkboxes.
+- [Color Picker](./wa-color-picker.md) — Color input with swatches, formats, opacity, and eyedropper support.
+- [Input](./wa-input.md) — Text input with labels, hints, clear controls, and semantic appearances.
+- [Known Date](./wa-known-date.md) — Experimental segmented field for partially or fully known dates.
+- [Number Input](./wa-number-input.md) — Numeric input with keyboard and stepper controls.
+- [Option](./wa-option.md) (underlying) — Underlying ecosystem option; prefer choices passed to Kerf Select.
+- [OTP Input](./wa-otp-input.md) — Experimental segmented one-time-password input.
+- [Radio](./wa-radio.md) — Single-choice control used inside a radio group.
+- [Radio Group](./wa-radio-group.md) — Labels and manages a mutually exclusive set of radios.
+- [Rating](./wa-rating.md) — Interactive rating control with accessible labeling.
+- [Select](./wa-select.md) (underlying) — Underlying ecosystem field; prefer Kerf Select for app UI.
+- [Slider](./wa-slider.md) — Range input with markers and value tooltip support.
+- [Switch](./wa-switch.md) — Immediate on/off setting control.
+- [Textarea](./wa-textarea.md) — Multiline text field with labels, hints, and resize behavior.
+- [Time Input](./wa-time-input.md) — Experimental segmented time field with an optional picker.
+
+## Web Awesome — Layout
+
+- [Accordion](./wa-accordion.md) — Coordinates one or more collapsible content sections.
+- [Accordion Item](./wa-accordion-item.md) — Experimental labeled disclosure section used by an accordion.
+- [Card](./wa-card.md) — Groups related content and optional header, media, and footer slots.
+- [Details](./wa-details.md) — Single disclosure panel for secondary information.
+- [Dialog](./wa-dialog.md) — Modal surface for focused tasks and confirmations.
+- [Divider](./wa-divider.md) — Visual separator for related groups of content.
+- [Drawer](./wa-drawer.md) — Edge-anchored modal surface for navigation or secondary tasks.
+- [Page](./wa-page.md) — Responsive application shell with navigation, banner, and main slots.
+- [Scroller](./wa-scroller.md) — Overflow container with accessible scrolling affordances.
+- [Split Panel](./wa-split-panel.md) (conditional) — Alternative split API; prefer Kerf ResizableRegion for application panes.
+
+## Web Awesome — Navigation
+
+- [Breadcrumb](./wa-breadcrumb.md) — Ordered navigation trail for the current location.
+- [Breadcrumb Item](./wa-breadcrumb-item.md) — One link or current-location item in a breadcrumb.
+- [Pagination](./wa-pagination.md) — Experimental page navigation for a bounded result set.
+- [Tab](./wa-tab.md) (conditional) — Ecosystem tab label; prefer Kerf TabBar or SegmentedControl.
+- [Tab Group](./wa-tab-group.md) (conditional) — Ecosystem tabs; prefer Kerf TabBar or SegmentedControl.
+- [Tab Panel](./wa-tab-panel.md) (conditional) — Ecosystem tab panel; prefer app-owned panels with Kerf navigation.
+- [Tree](./wa-tree.md) (exceptional) — Specialized hierarchy; use only when the product requires tree behavior.
+- [Tree Item](./wa-tree-item.md) (exceptional) — Specialized tree row; use only as part of a required tree.
+
+## Web Awesome — Feedback
+
+- [Badge](./wa-badge.md) — Compact status or count label with semantic variants.
+- [Callout](./wa-callout.md) — Prominent contextual message with semantic variants.
+- [Progress Bar](./wa-progress-bar.md) — Linear indicator for determinate or indeterminate progress.
+- [Progress Ring](./wa-progress-ring.md) — Circular indicator for determinate or indeterminate progress.
+- [Skeleton](./wa-skeleton.md) — Placeholder shape for content that is still loading.
+- [Spinner](./wa-spinner.md) — Compact indeterminate activity indicator.
+- [Tag](./wa-tag.md) — Compact categorization label with optional removal action.
+- [Toast](./wa-toast.md) — Placement-aware stack of transient notifications.
+- [Toast Item](./wa-toast-item.md) — One dismissible notification inside a toast stack.
+- [Tooltip](./wa-tooltip.md) — Brief contextual label anchored to a control.
+
+## Web Awesome — Media
+
+- [Animated Image](./wa-animated-image.md) (exceptional) — Specialized animated media; use only for a concrete product requirement.
+- [Avatar](./wa-avatar.md) — Person or entity image with initials fallback.
+- [Carousel](./wa-carousel.md) — Navigable horizontal or vertical collection of slides.
+- [Carousel Item](./wa-carousel-item.md) — One content slide inside a carousel.
+- [Comparison](./wa-comparison.md) (exceptional) — Specialized before-and-after media; use only when specifically required.
+- [Icon](./wa-icon.md) (avoid) — Ecosystem icon renderer; use Kerf LucideIcon in application UI.
+- [Markdown](./wa-markdown.md) — Experimental renderer for trusted Markdown content.
+- [QR Code](./wa-qr-code.md) — Scannable QR representation of a supplied value.
+- [Zoomable Frame](./wa-zoomable-frame.md) (avoid) — Avoid for application UI; keep embedded-media behavior application-owned.
+
+## Web Awesome — Helpers
+
+- [Animation](./wa-animation.md) — Declarative Web Animations API wrapper with preset effects.
+- [Format Bytes](./wa-format-bytes.md) — Locale-aware byte and bit value formatter.
+- [Format Date](./wa-format-date.md) — Locale-aware date and time formatter.
+- [Format Number](./wa-format-number.md) — Locale-aware number, currency, unit, and percentage formatter.
+- [Include](./wa-include.md) — Loads and injects an external HTML fragment.
+- [Intersection Observer](./wa-intersection-observer.md) — Declaratively emits visibility changes for slotted content.
+- [Mutation Observer](./wa-mutation-observer.md) — Declaratively emits DOM mutation records for slotted content.
+- [Popover](./wa-popover.md) — Anchored non-modal surface built on popup positioning.
+- [Popup](./wa-popup.md) (conditional) — Preferred low-level anchored positioning when Tooltip or Popover do not fit.
+- [Random Content](./wa-random-content.md) — Experimental helper that selects one slotted item at random.
+- [Relative Time](./wa-relative-time.md) — Locale-aware human description of a date relative to now.
+- [Resize Observer](./wa-resize-observer.md) — Declaratively emits size changes for slotted content.
+
+## Kerf UI — Recipes
+
+- [Desktop application shell](./recipe-app-shell.md) — App bar above a Workbench with resizable navigation and inspector rails, relocated rail toggles, narrow-container overlays, and explicit pane scroll owners.
+- [Navigation sidebar](./recipe-navigation-sidebar.md) — Navigation sections with icon and iconless rows, a content-item surface, disclosure, and pane footer actions.
+- [Workspace header](./recipe-workspace-header.md) — Page identity with primary, secondary, and overflow actions that relocate at narrow widths.
+- [List-detail dialog](./recipe-list-detail-dialog.md) — Production modal laid out as a workbench: a full-height SplitView list sidebar with its own toolbar beside a full-height detail column that carries the primary title, close control, and record actions; a full-screen drill-down on compact devices.
+- [Composer form](./recipe-composer-form.md) — One visible publishing-form surface with Toolbar heading hierarchy, fields and actions on the shared 8px control gutter, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface.
+- [List workspace states](./recipe-list-workspace-states.md) — Deterministic loading, empty, populated, stale refresh, and error states around one stable list workspace.
+- [Compact toolbar choices and actions](./recipe-compact-toolbar.md) — A compact toolbar that distinguishes grouped commands, a visible exclusive choice, a longer Select, and one ordinary action.
+- [Navigation stack](./recipe-navigation-stack.md) — A push/pop navigation stack drill-down with animated slides and a live device class.
+- [Loading inspector](./recipe-loading-inspector.md) — A record inspector whose per-record values load asynchronously — every value-bearing component takes a shared placeholder flag, so the same chrome renders a faithful loading state and then the populated record.
+- [Collapsible sidebar](./recipe-collapsible-sidebar.md) — A mini app frame whose left navigation rail and bottom activity drawer are standalone CollapsiblePanels driven by wireSidebar: per-side collapse/expand toggles, focus move-in and restore, a dismissable compact overlay, and per-panel persistence.

package/ai/components/application-tabs.md

@@ -0,0 +1,65 @@
+# Application tabs
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:application-tabs` · Kerf UI · CSS composition · Navigation
+
+Controlled document tabs with application-owned state and panels.
+
+## When to use
+
+Show AppTab and TabBar in a complete controlled composition.
+
+- Compose application state, panels, actions, overflow, and reordering around TabBar and AppTab.
+
+**Not when:**
+
+- Use SegmentedControl instead for a compact local choice.
+
+## Imports
+
+- Nothing to import: this is a reference composition.
+- Declared side effects: css.
+
+## Props
+
+No props: this entry has no JavaScript API.
+
+**Variants (configure, do not restyle):**
+
+- overflow
+- keyboard and pointer reordering
+- adding and closing documents
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [AppTab](./tabs.md), [TabBar](./tab-bar.md), [ToolbarControlGroup](./toolbar-control-group.md), [Text](./text.md), [Card](./wa-card.md).
+
+## State and wiring
+
+**The app owns:** ordered tabs; selected tab; tabpanels; add and close policy; routing and persistence.
+
+No wiring helper.
+
+## Geometry
+
+Margin: child · border: child · padding: child (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Keep one selected tab synchronized with one named tabpanel and retain the wireTabBars disposer.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [AppTab](./tabs.md), [TabBar](./tab-bar.md), [ToolbarControlGroup](./toolbar-control-group.md), [Text](./text.md), [Card](./wa-card.md).
+- Docs: [`docs/accessibility.md`](../../docs/accessibility.md), [`docs/accessibility.md#tabs`](../../docs/accessibility.md#tabs).
+- UX catalog route: `?component=application-tabs`.

package/ai/components/badge.md

@@ -0,0 +1,72 @@
+# Badge
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:badge` · Kerf UI · component · Foundation
+
+Self-styled, non-interactive status, count, and category metadata configured through semantic tone, appearance, shape, and size props.
+
+## When to use
+
+Present compact metadata without application-authored badge CSS or consumer styling of component internals.
+
+- Show a short status, count, category, or metadata label whose presentation should be configured rather than restyled.
+
+**Not when:**
+
+- Do not use Badge as a button, link, or removable chip; choose an interactive control with the correct native semantics.
+- Do not rely on tone alone to communicate meaning.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/badge` — exports `Badge`.
+- CSS: the browser build of `@kerfjs/ui/badge` pulls its CSS automatically; import `@kerfjs/ui/badge.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/badge`](../public-api-signatures-v1.md#kerfjsuibadge) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- neutral, brand, pop, success, warning, or danger tone
+- quiet, solid, or outline appearance
+- pill or rounded shape
+- compact or default size, or a text-free dot (size: 'dot')
+- labeled or decorative duplicate
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** metadata text; semantic tone mapping; accessible label for abbreviated content.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Badge is non-interactive. Supply label when visible content is abbreviated, and ariaHidden when it repeats an accessible name owned by the surrounding component. A text-free dot must take either label (exposed as an image) or ariaHidden, which the types enforce.
+- Keep meaningful text visible because tone is supplementary.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-badge`.
+
+Never put `kui-badge` on an element you write; render `Badge` instead (`KUI-L103`).
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=badge`.

package/ai/components/collapsible-panel.md

@@ -0,0 +1,102 @@
+# CollapsiblePanel
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:collapsible-panel` · Kerf UI · component · Structure
+
+A standalone controlled left or right rail or bottom drawer with standard collapse icons and optional compact-overlay behavior through wireSidebar.
+
+## When to use
+
+Add one independently collapsible peripheral panel without adopting the complete multi-panel Workbench shell.
+
+- An application needs one collapsible side rail or bottom drawer outside a full Workbench.
+- The panel should become a dismissable, focus-managed overlay on compact devices.
+
+**Not when:**
+
+- Do not use CollapsiblePanel for a complete editor shell with multiple coordinated rails and a drawer; use Workbench.
+- Do not preserve an empty icon-only rail when collapsed; move the restore control into adjacent visible chrome.
+
+**Alternatives:**
+
+- [Workbench](./workbench.md) (larger-composition) — Use Workbench when the central work area coordinates multiple peripheral panels.
+- [Collapsible sidebar](./recipe-collapsible-sidebar.md) (recipe) — Use the production recipe for collapse, restore, compact overlay, focus, and persistence ownership.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/collapsible-panel` — exports `CollapsiblePanelSide`, `collapsiblePanelToggleIcon`, `CollapsiblePanelToolbarToggle`, `CollapsiblePanelToolbar`, `CollapsiblePanelToggleProps`, `CollapsiblePanelToggle`, `CollapsiblePanelProps`, `CollapsiblePanel`, `CollapsiblePanelRelocatedProps`, `CollapsiblePanelRelocated`.
+- CSS: the browser build of `@kerfjs/ui/collapsible-panel` pulls its CSS automatically; import `@kerfjs/ui/collapsible-panel.css` manually only without the `browser` export condition.
+- Wiring: `wireSidebar` from `@kerfjs/ui/wire-sidebar` (required).
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/collapsible-panel`](../public-api-signatures-v1.md#kerfjsuicollapsible-panel), [`@kerfjs/ui/wire-sidebar`](../public-api-signatures-v1.md#kerfjsuiwire-sidebar), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- left rail
+- right rail
+- bottom drawer
+- collapsed
+- compact overlay
+- compact responsive replacement
+- hidden separator
+- slide, fade-slide, or instant content
+- clipped, scrolling, or popup-visible content
+- safe-area restore control
+- chrome dividers only while scrolled (wired by wireScrollDividers)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** controlled collapsed state; panel content and size; toggle placement; persistence policy; compact-device policy.
+
+**Wiring:** `wireSidebar`, `wireScrollDividers` is required.
+
+- Use wireSidebar as documented.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-collapsible-responsive` on `the root passed to wireSidebar` (`wireSidebar`): With a deviceClass: "inline" on a wide device class, otherwise the compact presentation ("overlay" or "hidden"). Re-applied if a re-render drops it.
+- `data-collapsible-overlay` on `the root passed to wireSidebar` (`wireSidebar`): With a deviceClass on a compact device: "true" for the overlay presentation, "false" for hidden. Absent on a wide device class. Re-applied if a re-render drops it.
+- `data-morph-preserve` on `kui-collapsible-panel__backdrop` (`wireSidebar`): Keeps the injected compact-overlay backdrop through the application's re-render; the helper creates and removes the backdrop itself.
+- `data-scroll-overflow` on `kui-pane__content of each panel and work-area Pane` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
+- `data-scroll-divider` on `kui-pane__header and kui-pane__footer of each panel and work-area Pane` (`wireScrollDividers`): The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it.
+
+## Geometry
+
+Margin: none · border: self · padding: child (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The panel owns its dock-edge separator and size track; its child content owns internal padding and scrolling.
+
+## Accessibility
+
+- Give the panel region and every collapse or restore control an accessible label.
+- Keep the restore control outside the disappearing panel and use wireSidebar for focus transfer, Escape, backdrop dismissal, and compact focus trapping.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-collapsible-panel`, `kui-collapsible-panel--left`, `kui-collapsible-panel--right`, `kui-collapsible-panel--bottom`, `kui-collapsible-panel__content`, `kui-collapsible-panel__restore`, `kui-collapsible-panel__backdrop`, `kui-collapsible-panel__toggle`.
+
+Never put `kui-collapsible-panel`, `kui-collapsible-panel--left`, `kui-collapsible-panel--right`, `kui-collapsible-panel--bottom`, `kui-collapsible-panel__content`, `kui-collapsible-panel__restore`, `kui-collapsible-panel__backdrop`, `kui-collapsible-panel__toggle` on an element you write; render `CollapsiblePanel` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-collapsible-panel-width`, `--kui-collapsible-panel-height`, `--kui-collapsible-panel-popup-z`, `--kui-collapsible-panel-overlay-z`, `--kui-collapsible-panel-restore-inset`, `--kui-collapsible-panel-restore-z`, `--kui-collapsible-panel-backdrop-z`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md), [Workbench](./workbench.md), [Collapsible sidebar](./recipe-collapsible-sidebar.md).
+- Docs: [`docs/collapsible-panel.md`](../../docs/collapsible-panel.md), [`docs/collapsible-panel.md#recipe-and-coverage`](../../docs/collapsible-panel.md#recipe-and-coverage).
+- UX catalog route: `?component=collapsible-panel`.

package/ai/components/content-item.md

@@ -0,0 +1,90 @@
+# ContentItem
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:content-item` · Kerf UI · component · Structure
+
+One self-contained content child with the shared 8px margin + 1px border + 8px padding geometry, a typed frame, and a rounded or pill shape.
+
+## When to use
+
+Render one self-contained .kui-content child that owns its 8px inline margin, real 1px border, 8px padding, and radius, with framing and shape chosen by typed props instead of hand-written modifier classes.
+
+- An ordinary surface-like child of a Pane or .kui-content stack needs the shared content-item geometry so its content edge lands at the standard 17px inset.
+- A content item marks a real distinction and must read as visibly bounded: pass frame="framed" (the border is always reserved, so geometry does not change).
+- A content item should follow a pill control's 22px radius: pass shape="pill".
+
+**Not when:**
+
+- Do not wrap a component that already owns content-item geometry (ListItem, ListHeader, StateBanner, Toolbar, ValueTable) or pad around a ContentItem; either double-insets.
+- Do not frame an item only to make it look contained; hierarchy comes from alignment, spacing, and type first.
+- Do not use it as a filled or lowered card; use SunkenPanel for a lowered surface.
+- Do not use it for bare text alone; use ListInsetText, which adds the same inset without claiming a surface.
+
+**Alternatives:**
+
+- [ListInsetText](./list-inset-text.md) (nearest) — Use ListInsetText when bare text only needs to align with neighboring content items.
+- [SunkenPanel](./sunken-panel.md) (nearest) — Use SunkenPanel for a lowered, filled surface around a vertical stack.
+- [Application layout](./layout.md) (composes-with) — Place ContentItem children in a Pane or .kui-content stack, which owns the 24px major rhythm.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/content-item` — exports `ContentItem`.
+- CSS: the browser build of `@kerfjs/ui/content-item` pulls its CSS automatically; import `@kerfjs/ui/content-item.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/content-item`](../public-api-signatures-v1.md#kerfjsuicontent-item) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- unframed rounded item
+- framed rounded item
+- pill item
+- framed pill item
+- named focus-target region
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the item content; whether the item marks a real distinction that warrants a visible frame; corner shape; region semantics and accessible name; whether the item is a programmatic focus target.
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The 1px border is always reserved and transparent unless frame="framed", so framed and unframed items share the same geometry.
+
+## Accessibility
+
+- An ordinary item adds no role or name; pass ariaLabel only when the item is a distinct named region (it then renders role="region").
+- focusTarget makes the item a programmatic focus target (tabindex="-1", never a tab stop), such as a NavStack view's data-nav-focus target.
+- The frame is decorative and never the only signal of state.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-content-item`, `kui-content-item--pill`, `kui-content-item--framed`.
+
+Classes an application may place on its own elements: `kui-content-item`, `kui-content-item--pill`, `kui-content-item--framed`.
+
+A plain `<div>` carrying them is exactly what `ContentItem` renders: render `ContentItem` instead (`KUI-L103`), and place the classes only on another carrier element.
+
+Public tokens it reads: `--kui-content-item-border`, `--kui-content-item-radius`, `--kui-content-item-background`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [ListInsetText](./list-inset-text.md), [SunkenPanel](./sunken-panel.md), [Application layout](./layout.md).
+- Docs: [`docs/layout.md`](../../docs/layout.md), [`docs/layout.md#content-items`](../../docs/layout.md#content-items).
+- UX catalog route: `?component=content-item`.

package/ai/components/disclosure-arrow.md

@@ -0,0 +1,77 @@
+# DisclosureArrow
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:disclosure-arrow` · Kerf UI · component · Foundation
+
+Root-scaled 18px animated open and closed disclosure indicator with configurable directions, shortest-path rotation, and right-oriented replacement icon content.
+
+## When to use
+
+Indicate whether a disclosure control is open with an overridable 18px root-scaled visual and shortest-path rotation behavior.
+
+- Add a shortest-path rotating indicator to a control that owns open and closed state; author replacement icon content facing right before direction transforms are applied.
+
+**Not when:**
+
+- Do not use the arrow as the interactive control or accessible name by itself.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/disclosure-arrow` — exports `DisclosureArrow`.
+- CSS: the browser build of `@kerfjs/ui/disclosure-arrow` pulls its CSS automatically; import `@kerfjs/ui/disclosure-arrow.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/disclosure-arrow`](../public-api-signatures-v1.md#kerfjsuidisclosure-arrow) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- open
+- closed
+- custom directions
+- replacement icon
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `size`: length grammar; raw values: forbid; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `size={remify(24)}`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+**The app owns:** open state; interaction; accessible control label.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: foundation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- The arrow is decorative; expose expanded state through aria-expanded on its owning control and keep that control's accessible name stable.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-disclosure-arrow`.
+
+Never put `kui-disclosure-arrow` on an element you write; render `DisclosureArrow` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-disclosure-arrow-duration`, `--kui-disclosure-arrow-size`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [LucideIcon](./lucide-icon.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=disclosure-arrow`.