@kerfjs/ui 5.0.0-beta.6 → 5.0.0-beta.61

package/ai/components/list-inset-text.md

@@ -0,0 +1,72 @@
+# ListInsetText
+
+<!-- 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:list-inset-text` · Kerf UI · component · Structure
+
+Gives selected physical sides of bare text the content-item geometry so it lines up with bordered items.
+
+## When to use
+
+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.
+
+- Line a plain text element up with bordered .kui-content items — it adds the 8px margin, 1px transparent border, and 8px padding the text lacks.
+
+**Not when:**
+
+- Do not use it to wrap an interactive control (use ListInsetControl), or a component that already owns its content-item geometry.
+
+**Alternatives:**
+
+- [ListInsetControl](./list-inset-control.md) (nearest)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/list-inset-text` — exports `ListInsetText`.
+- CSS: the browser build of `@kerfjs/ui/list-inset-text` pulls its CSS automatically; import `@kerfjs/ui/list-inset-text.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/list-inset-text`](../public-api-signatures-v1.md#kerfjsuilist-inset-text) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- all-side inset by default
+- top/right/bottom/left inset combinations
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the text content.
+
+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.
+
+## Accessibility
+
+- A layout wrapper only; it adds no role or name.
+
+## 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-list-inset-text`.
+
+Never put `kui-list-inset-text` on an element you write; render `ListInsetText` 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
+
+- Components: [ListInsetControl](./list-inset-control.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=list-inset-text`.

package/ai/components/list-item.md

@@ -0,0 +1,94 @@
+# ListItem
+
+<!-- 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:list-item` · Kerf UI · component · Navigation
+
+Configurable native-button action rows and native-anchor navigation rows with structured labels, status/busy metadata, density, group dividers, protected domain metadata hooks, and rounded-boundary overflow clipping.
+
+## When to use
+
+Selectable, disabled, trailing, and multiline action or link rows.
+
+- Render a selectable, disabled, trailing, or multiline sidebar action row whose descendants must remain clipped to the rounded row boundary; use ListItemLink when the destination has an href and needs native link activation.
+
+**Not when:**
+
+- Do not use for an ordinary inline link, form button, isolated ARIA menuitem, or an interactive trailing action; use ListActionRow for sibling row actions.
+- Do not inject declaration strings; use className, public tokens, and cataloged component props for application styling.
+
+**Alternatives:**
+
+- [ListActionRow](./list-action-row.md) (nearest) — The trailing region must be independently interactive.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/list-item` — exports `ListItem`, `ListItemLink`.
+- CSS: the browser build of `@kerfjs/ui/list-item` pulls its CSS automatically; import `@kerfjs/ui/list-item.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/list-item`](../public-api-signatures-v1.md#kerfjsuilist-item) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- native link and external link
+- selected
+- pressed
+- disabled
+- trailing
+- multiline
+- placeholder (loading)
+- compact density
+- spacious density
+- centered icon beside a multiline label
+- drag-target state
+- description and status
+- busy while retaining content
+- before, after, or paired group divider
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `style`: declarations grammar; raw values: forbid — e.g. `className="app-row"`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md), [LoadingSpinner](./loading-spinner.md).
+
+## State and wiring
+
+**The app owns:** routing; link destinations; selection; permissions; action handling; domain data attributes.
+
+No wiring helper.
+
+## Geometry
+
+Margin: self · border: self · padding: self (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Public resting background and border, hover border, and selected border tokens can be scoped to a row or its containing list without changing the default tones.
+
+## Accessibility
+
+- ListItem uses native button activation and pressed maps to aria-pressed; ListItemLink uses native anchor activation and external opens a new tab with safe rel and an announced default label. Both map selected to aria-current; disabled or loading links omit href and leave the tab order. rootAttributes cannot add role=menuitem or replace owned ARIA; trailing is dormant content and must not contain controls.
+
+## 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-list-item`, `kui-list-item__icon`, `kui-list-item__label`, `kui-list-item__primary-label`, `kui-list-item__description`, `kui-list-item__status`, `kui-list-item__trailing`.
+
+Never put `kui-list-item`, `kui-list-item__icon`, `kui-list-item__label`, `kui-list-item__primary-label`, `kui-list-item__description`, `kui-list-item__status`, `kui-list-item__trailing` on an element you write; render `ListItem` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-brand-border-normal`, `--kui-color-brand-border-quiet`, `--kui-color-brand-fill-quiet`, `--kui-color-brand-fill-normal`, `--kui-color-neutral-fill-quiet`, `--kui-color-neutral-on-normal`, `--kui-color-neutral-on-quiet`, `--kui-color-neutral-border-quiet`, `--kui-color-neutral-border-normal`, `--kui-focus-ring`, `--kui-list-item-color`, `--kui-list-item-background`, `--kui-list-item-align-items`, `--kui-list-item-border-width`, `--kui-list-item-border`, `--kui-list-item-columns`, `--kui-list-item-drag-target-background`, `--kui-list-item-drag-target-outline`, `--kui-list-item-drag-target-outline-offset`, `--kui-list-item-gap`, `--kui-list-item-hover-background`, `--kui-list-item-hover-border`, `--kui-list-item-icon-color`, `--kui-list-item-icon-size`, `--kui-list-item-label-max-width`, `--kui-list-item-label-weight`, `--kui-list-item-min-height`, `--kui-list-item-padding-block`, `--kui-list-item-padding-inline`, `--kui-list-item-radius`, `--kui-list-item-selected-background`, `--kui-list-item-selected-border`, `--kui-list-item-selected-color`, `--kui-list-item-trailing-color`, `--kui-list-group-divider-color`, `--kui-font-xs`, `--kui-layout-inline-margin`, `--kui-layout-item-gap`, `--kui-layout-item-padding`, `--kui-layout-rounded-radius`. 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), [LoadingSpinner](./loading-spinner.md), [ListActionRow](./list-action-row.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=list-item`.

package/ai/components/list.md

@@ -0,0 +1,103 @@
+# List
+
+<!-- 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:list` · Kerf UI · component · Navigation
+
+A vertical stack with physical-axis alignment, side-selectable text/control insets, optional typed token/length gap, flex growth, vertical scrolling, and independently selectable divider edges.
+
+## When to use
+
+Standardize vertical component layout, optional physical-side text/control insets, and scroll/divider ownership instead of repeating ad-hoc flex-column wrappers.
+
+- Arrange component rows or sections in a vertical stretch-aligned stack.
+- Let one bounded list own vertical scrolling, flex growth, or one or more physical-edge dividers.
+- Choose a finite gap shorthand such as xs or m, or compose a typed length with @kerfjs/ui/css-values when the spacing scale is insufficient.
+- Use a finite flex keyword or the flex() builder when List participates in flexible layout.
+- Apply the standard text or control inset to selected physical sides without an application wrapper.
+- Align children horizontally or distribute them vertically with the same physical alignment vocabulary as Row.
+
+**Not when:**
+
+- Do not use List as semantic list markup; use ul/ol when list semantics are required and apply layout deliberately.
+- Do not create nested scroll owners or use divider sides as a substitute for meaningful grouping.
+- Do not pass raw CSS strings to gap or flex, mix their distinct grammars, or use the off-rhythm s/xl spacing steps without a deliberate exception.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/list` — exports `List`, `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `plus`, `calc`, `flex`.
+- CSS: the browser build of `@kerfjs/ui/list` pulls its CSS automatically; import `@kerfjs/ui/list.css` manually only without the `browser` export condition.
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/list`](../public-api-signatures-v1.md#kerfjsuilist), [`@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):**
+
+- no gap
+- standard boolean gap
+- named none/2xs/xs/s/m/l/xl token gap
+- typed CssLength gap
+- boolean, finite-keyword, or typed CssFlex flex
+- scrollable
+- left/center/right/full horizontal alignment
+- top/middle/bottom/full vertical alignment
+- top/right/bottom/left divider combinations
+- top/right/bottom/left text and control inset combinations
+- fill: the layout root fills a definite-height parent
+- rootAttributes: safe data-\* metadata on the root
+- scroll dividers when named as wireScrollDividers targets chrome
+
+**CSS-value props** (typed builders from `@kerfjs/ui/css-values`; raw CSS strings are rejected):
+
+- `gap`: length grammar; raw values: forbid; shorthands `none`, `2xs`, `xs`, `m`, `l`; exceptional (justify) `s`, `xl`; helpers `px`, `rem`, `em`, `pct`, `space`, `lengthVar`, `calc` — e.g. `gap="xs"`
+- `flex`: flex grammar; raw values: forbid; shorthands `none`, `auto`, `initial`; helpers `flex` — e.g. `flex="none"`
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`, `navigation-list`, `vertical-layout`.
+- Children: unrestricted.
+- Built from: [ListHeader](./list-header.md), [ListActionRow](./list-action-row.md), [ListItem](./list-item.md).
+
+## State and wiring
+
+**The app owns:** child semantics and content; the bounded height needed for scrolling; typed gap, flex, alignment, and divider choices.
+
+**Wiring:** `wireScrollDividers` is optional.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-scroll-overflow` on `the targets scroller` (`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 `a List named as targets chrome` (`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: conditional · padding: conditional (layout role: navigation). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- List adds no margin. dividerSides draws selected physical edges without changing geometry; textInsets adds the full 17px content inset and controlInsets adds 8px on selected sides, with text winning on overlap.
+
+## Accessibility
+
+- List adds layout only and no list role; children retain responsibility for their native or ARIA semantics.
+- Give a scrollable List a bounded block size and keep keyboard focus visible as its contents scroll.
+
+## 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-list`.
+
+Never put `kui-list` on an element you write; render `List` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-neutral-border-normal`, `--kui-layout-item-gap`, `--kui-list-divider-color`, `--kui-list-gap`. 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: [ListHeader](./list-header.md), [ListActionRow](./list-action-row.md), [ListItem](./list-item.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#correct-composition-and-duplicated-markup-trap`](../../docs/component-selection.md#correct-composition-and-duplicated-markup-trap).
+- UX catalog route: `?component=list`.

package/ai/components/loading-spinner.md

@@ -0,0 +1,72 @@
+# LoadingSpinner
+
+<!-- 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:loading-spinner` · Kerf UI · component · Feedback
+
+## When to use
+
+Meaningfully labeled or decorative progress.
+
+- Show compact labeled or decorative indeterminate activity in Kerf UI.
+
+**Not when:**
+
+- Do not use for known progress.
+
+**Alternatives:**
+
+- [Spinner](./wa-spinner.md) (prefer-over)
+- [Progress Bar](./wa-progress-bar.md) (prefer-over)
+- [Progress Ring](./wa-progress-ring.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/loading-spinner` — exports `LoadingSpinner`.
+- CSS: the browser build of `@kerfjs/ui/loading-spinner` pulls its CSS automatically; import `@kerfjs/ui/loading-spinner.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/loading-spinner`](../public-api-signatures-v1.md#kerfjsuiloading-spinner) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- labeled
+- decorative
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** loading lifecycle; adjacent status copy.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Labeled spinners use role img; decorative spinners are hidden and stop for reduced motion.
+
+## 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-loading-spinner`.
+
+Never put `kui-loading-spinner` on an element you write; render `LoadingSpinner` 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
+
+- Components: [Spinner](./wa-spinner.md), [Progress Bar](./wa-progress-bar.md), [Progress Ring](./wa-progress-ring.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=loading-spinner`.

package/ai/components/lucide-icon.md

@@ -0,0 +1,66 @@
+# LucideIcon
+
+<!-- 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:lucide-icon` · Kerf UI · component · Foundation
+
+## When to use
+
+Decorative and meaningfully labeled Lucide-compatible icons.
+
+- Render a decorative or explicitly labeled Lucide-compatible icon in Kerf application UI.
+
+**Not when:**
+
+- Do not use an icon as the only name of an unfamiliar action.
+
+**Alternatives:**
+
+- [Icon](./wa-icon.md) (prefer-over)
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/lucide-icon` — exports `LucideIcon`.
+- CSS: the browser build of `@kerfjs/ui/lucide-icon` pulls its CSS automatically; import `@kerfjs/ui/lucide-icon.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/lucide-icon`](../public-api-signatures-v1.md#kerfjsuilucide-icon) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- decorative
+- labeled
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** icon choice; meaningful 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
+
+- Decorative icons are aria-hidden; meaningful icons require a label.
+
+## 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: [Icon](./wa-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=lucide-icon`.

package/ai/components/nav-stack.md

@@ -0,0 +1,103 @@
+# NavStack
+
+<!-- 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:nav-stack` · Kerf UI · component · Structure
+
+A controlled one-pane navigation stack that keeps prior views mounted, slides content on push and pop, cross-fades per-view chrome, and moves/restores focus.
+
+## When to use
+
+Present a single linear or drill-down flow while preserving each prior view's state, scroll position, and place in the stack.
+
+- A compact surface shows one view at a time and navigation pushes into details or pops back.
+- A simple single-pane screen needs the same stable app-layout contract without any nested navigation.
+
+**Not when:**
+
+- Do not use NavStack when a list and detail should remain visible together; use SplitView.
+- Do not use it for co-equal top-level destinations on compact devices; wrap one stack per destination in TabScaffold.
+
+**Alternatives:**
+
+- [SplitView](./split-view.md) (roomy-alternative) — Promote a list-to-detail stack to SplitView once both regions fit together.
+- [TabScaffold](./tab-scaffold.md) (composes-with) — Use one NavStack as each TabScaffold tab's persistent content.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/nav-stack` — exports `NavStackView`, `NavStackToolbarConfig`, `NavStackProps`, `NavStack`.
+- CSS: the browser build of `@kerfjs/ui/nav-stack` pulls its CSS automatically; import `@kerfjs/ui/nav-stack.css` manually only without the `browser` export condition.
+- Wiring: `wireNavStack` from `@kerfjs/ui/wire-nav-stack` (required).
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/nav-stack`](../public-api-signatures-v1.md#kerfjsuinav-stack), [`@kerfjs/ui/wire-nav-stack`](../public-api-signatures-v1.md#kerfjsuiwire-nav-stack), [`@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):**
+
+- single root view
+- pushed detail view
+- toolbar hidden
+- configured top toolbar
+- custom back icon or visible back text
+- per-view bottom toolbar
+- persistent bottom-toolbar fallback
+- chrome and bottom-toolbar dividers only while the active view scrolls beneath them (wired by wireScrollDividers)
+- permanent or no chrome dividers (chromeDividers always or none)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md).
+
+## State and wiring
+
+**The app owns:** ordered view stack and stable keys; view content and titles; push and pop actions; preferred initial focus targets when DOM order is insufficient; per-view bottom toolbar content or a persistent fallback; per-view leading, center, and trailing top-toolbar groups; top-toolbar configuration, title size, and heading level; whether the chrome and bottom-toolbar dividers follow the scroll, always show, or never show (chromeDividers).
+
+**Wiring:** `wireNavStack`, `wireScrollDividers` is required.
+
+- Use wireNavStack as documented.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-nav-chrome-transition` on `kui-nav-stack` (`wireNavStack`): "true" while the chrome cross-fades between the outgoing and incoming view.
+- `data-nav-chrome-copy` on `kui-nav-stack__chrome-copy` (`wireNavStack`): Marks the inert, aria-hidden snapshot of the outgoing chrome shown during the cross-fade.
+- `data-nav-exiting` on `kui-nav-stack__view` (`wireNavStack`): "true" on a popped view the helper briefly re-inserts to slide it out.
+- `data-scroll-overflow` on `the active kui-nav-stack__view, or the kui-pane__content of a sole Pane in it` (`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-nav-stack__chrome and kui-nav-stack__bottom` (`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: conditional · padding: child (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The stack owns its full-height chrome and viewport; each view owns its internal content padding and scrollable content.
+- The top chrome's bottom line and the bottom toolbar's top line are scroll state (wireScrollDividers), drawn as an overlaid 1px pseudo-element on the chrome and the bottom toolbar's always-present 1px top border, so neither moves the chrome or the content.
+
+## Accessibility
+
+- Give the stack region an accessible label and every back control a stable action label; visible backText names the control itself.
+- Set toolbarConfig.headingLevel when the view title is the page's or section's heading landmark.
+- Use wireNavStack so each controlled push moves focus into the new top view and each pop restores the revealed view's remembered descendant.
+- Mark a preferred initial heading or control with data-nav-focus when the first enabled focusable descendant is not the right target.
+
+## 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-nav-stack`, `kui-nav-stack__chrome`, `kui-nav-stack__bottom`, `kui-nav-stack__chrome--entering`, `kui-nav-stack__chrome-copy`, `kui-nav-stack__chrome-copy--bottom`, `kui-nav-stack__chrome-copy--exiting`, `kui-nav-stack__viewport`, `kui-nav-stack__view`, `kui-nav-stack__view--entering`, `kui-nav-stack__view--exiting`.
+
+Never put `kui-nav-stack`, `kui-nav-stack__chrome`, `kui-nav-stack__bottom`, `kui-nav-stack__chrome--entering`, `kui-nav-stack__chrome-copy`, `kui-nav-stack__chrome-copy--bottom`, `kui-nav-stack__chrome-copy--exiting`, `kui-nav-stack__viewport`, `kui-nav-stack__view`, `kui-nav-stack__view--entering`, `kui-nav-stack__view--exiting` on an element you write; render `NavStack` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-nav-stack-transition-duration`. 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: [Toolbar](./toolbar.md), [ToolbarControlGroup](./toolbar-control-group.md), [ToolbarText](./toolbar-text.md), [SplitView](./split-view.md), [TabScaffold](./tab-scaffold.md).
+- Docs: [`docs/nav-stack.md`](../../docs/nav-stack.md), [`docs/app-layouts.md#decision-matrix`](../../docs/app-layouts.md#decision-matrix).
+- UX catalog route: `?component=nav-stack`.

package/ai/components/pane.md

@@ -0,0 +1,100 @@
+# Pane
+
+<!-- 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:pane` · Kerf UI · component · Structure
+
+An unpadded application column with optional vertical header/footer slots, one scrolling vertical content stack, and independent logical-edge separators.
+
+## When to use
+
+Organize a sidebar, main area, inspector, or dialog column into fixed vertical header/footer chrome around one scrolling content owner.
+
+- An application column needs shared header, content, and optional footer organization with exactly one scrolling content owner.
+- A pane boundary needs an opt-in separator on any combination of logical sides.
+- Pinned chrome needs a divider from the scrolling content only while content is scrolled beneath it (wireScrollDividers).
+
+**Not when:**
+
+- Do not use Pane as a padded card or add a competing scroll owner around its content slot.
+- Do not enable separators merely as decoration; use them only where the pane owns a real boundary.
+
+**Alternatives:**
+
+- [Application layout](./layout.md) (composes-with) — Use the layout content-item and control classes inside Pane when children need shared geometry.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/pane` — exports `Pane`, `wireScrollDividers`.
+- CSS: the browser build of `@kerfjs/ui/pane` pulls its CSS automatically; import `@kerfjs/ui/pane.css` manually only without the `browser` export condition.
+- Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/pane`](../public-api-signatures-v1.md#kerfjsuipane), [`@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):**
+
+- content only
+- header + content
+- header + content + footer
+- block-start separator
+- block-end separator
+- inline-start separator
+- inline-end separator
+- chrome dividers only while scrolled (default, wired by wireScrollDividers)
+- always or no chrome dividers
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-column`, `sidebar`, `main-content`, `inspector`, `dialog-column`.
+- Children: unrestricted.
+
+Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
+
+- `header` — JSX prop `header`; accepts `fixed-chrome`; any number.
+- `content` — JSX prop `children`; accepts `pane-content`; any number.
+- `footer` — JSX prop `footer`; accepts `fixed-chrome`; any number.
+
+## State and wiring
+
+**The app owns:** root and content semantics; accessible labels; header, content, and footer children; which logical boundaries show separators; which sides may compensate for device safe areas in an app-owned arrangement (safeAreaEdges); responsive placement and visibility; whether the chrome dividers follow the scroll, always show, or never show (chromeDividers).
+
+**Wiring:** `wireScrollDividers` is optional.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-scroll-overflow` on `kui-pane__content` (`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` (`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: child · border: conditional · padding: child (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The pane is unpadded; separators are independently opt-in on logical edges and default off.
+- Safe areas: the root and separators paint through unsafe areas while header, content, and footer pad the sides the pane still reaches (routed by --kui-edge-inset-\*); content block insets are scroll padding.
+
+## Accessibility
+
+- Choose semantic root and content elements that match the region and provide labels for landmark elements.
+- Keep fixed header/footer chrome outside the single scrolling content slot so reading and focus order remain coherent.
+
+## 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-pane`, `kui-pane__content`, `kui-pane__footer`, `kui-pane__header`, `kui-pane__toolbar`.
+
+Never put `kui-pane`, `kui-pane__content`, `kui-pane__footer`, `kui-pane__header`, `kui-pane__toolbar` on an element you write; render `Pane` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-edge-inset-block-end`, `--kui-edge-inset-block-start`, `--kui-edge-inset-inline-end`, `--kui-edge-inset-inline-start`, `--kui-pane-separator-color`, `--kui-pane-separator-width`. 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: [Application layout](./layout.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/layout.md#anatomy`](../../docs/layout.md#anatomy).
+- UX catalog route: `?component=pane`.