@kerfjs/ui 5.0.0-beta.95 → 5.0.0-beta.96

package/ai/component-composition.schema.json

@@ -239,6 +239,10 @@
                 "additionalProperties": false
               }
             },
+            "actions": {
+              "description": "data-action values the application must handle with a root-delegated listener (delegate or delegateActions) instead of a named helper. Required wiring names at least one helper or action.",
+              "$ref": "#/$defs/stringList"
+            },
             "obligations": { "$ref": "#/$defs/stringList" },
             "stateAttributes": {
               "description": "Wiring-owned state attributes: data-* attributes a wiring helper writes at runtime, which the application must not render, remove, or treat as its own state. Optional for extension catalogs; first-party entries always list it, empty when their helpers write none.",

package/ai/components/README.md

@@ -33,8 +33,12 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 - [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 through extra-large 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.
+- [FramedList](./framed-list.md) — Group settings-style rows of arbitrary content (copy, keycaps, controls) in one framed surface with between-row dividers and an optional highlighted row, without app list CSS.
+- [SummaryRow](./summary-row.md) — Present dense item summaries (tickets, tasks, messages) as selectable list rows or board cards with Kerf-owned selection, hover, focus, rail, clamping, list-edge rounding, and narrow compaction, without app row CSS.
 - [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 with either a fixed count or automatic container-width collapse.
+- [ColumnTrack](./column-track.md) — Lay out a board of columns (kanban) as one horizontal scroll owner: equal columns that never shrink below a minimum, or a paged phone layout with a peeking next column and start snapping, without app track CSS.
+- [ContentSwap](./content-swap.md) — Swap arbitrary content in place (a dialog body that steps to a second page, a label or footer whose actions change) with Kerf-owned push or crossfade motion, reduced-motion handling, and an inert, hidden inactive side.
 - [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.
@@ -53,16 +57,24 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 ## Kerf UI — Controls
 
 - [SegmentedControl](./segmented-control.md) — Controlled exclusive choices in toolbar, rounded-rectangle, and pill presentations.
+- [ChoiceChips](./choice-chips.md) — Choose one value from a visible set too large for a segmented track, such as a color palette with labeled swatches.
 - [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) — Choose one or more controlled values, keep unavailable choices visible, and optionally select all enabled choices or clear a multiple selection.
+- [Combobox](./combobox.md) — Let people pick an existing value or create a new one by typing (tags, labels, recipients), with the themed field chrome, the ARIA combobox pattern, and a touch-safe font size, without a native datalist or app CSS.
 - [PopupMenu](./popup-menu.md) — A typed action menu with nested choices, selected state, and optional pointer-anchored context opening, built on the Web Awesome dropdown.
+- [IconButton](./icon-button.md) — Render an icon-only action as a square one form-control height on each side, so it matches an adjacent wa-input or Select, without ::part overrides.
+- [IconToggleButton](./icon-toggle-button.md) — Render an icon-only aria-pressed toggle in content or a pane footer, where a Toolbar does not belong, with the 44px contained geometry and raised pressed face of a single ToolbarControlGroup.
+- [SplitButton](./split-button.md) — Render a prominent primary action plus an options trigger (provider, model, target) as one control with a semantic tone, full-width sizing, a busy presentation, and native aria-expanded on the trigger, outside any Toolbar.
+- [FilePicker](./file-picker.md) — Let people choose or drop files (attachments, evidence, imports) without app CSS: a link-toned browse trigger and a dashed drop target that highlights while dragging, both around visually hidden native file inputs.
 
 ## Kerf UI — Feedback
 
 - [AnchoredSurface](./anchored-surface.md) — Present arbitrary app-owned content next to an element or pointer with Kerf UI surface styling and kerfjs/overlay lifecycle.
 - [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.
+- [CornerStatus](./corner-status.md) — Show ongoing app-level progress such as "Loading…" or "Updating tickets… 3 of 12" in a viewport corner above page chrome and any dialog opened before it, without a close button, light dismiss, Escape, or focus change.
+- [EdgeActivityIndicator](./edge-activity-indicator.md) — Signal ambient background activity (server work, sync) along the top edge of the viewport without allocating layout or taking the pointer, with Kerf-owned motion and reduced-motion handling.
 - [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.

package/ai/components/badge.md

@@ -34,6 +34,9 @@ Exact prop names and types: [`@kerfjs/ui/badge`](../public-api-signatures-v1.md#
 - pill or rounded shape
 - compact or default size, or a text-free dot (size: 'dot')
 - labeled or decorative duplicate
+- leading icon
+- title tooltip and data-\* rootAttributes
+- maxWidth caps the badge and truncates long text with an ellipsis, defaulting the title to string or number content
 
 ## Composition
 
@@ -55,14 +58,15 @@ Margin: none · border: self · padding: self (layout role: foundation). `self`
 
 - 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.
+- A label replaces abbreviated or symbolic visible text; the badge is then a labeled image (role img).
 
 ## 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`.
+Public class hooks (select for layout placement only, never to change the component's look): `kui-badge`, `kui-badge__icon`, `kui-badge__label`.
 
-Never put `kui-badge` on an element you write; render `Badge` instead (`KUI-L103`).
+Never put `kui-badge`, `kui-badge__icon`, `kui-badge__label` 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`).
 

package/ai/components/choice-chips.md

@@ -0,0 +1,80 @@
+# ChoiceChips
+
+<!-- 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:choice-chips` · Kerf UI · component · Controls
+
+An exclusive, wrapping set of separated pill chips backed by native radios, with optional leading color swatches or icons.
+
+## When to use
+
+Choose one value from a visible set too large for a segmented track, such as a color palette with labeled swatches.
+
+- Expose one exclusive choice among several visible options that must wrap onto more rows, such as a labeled color palette with swatches.
+
+**Not when:**
+
+- Use SegmentedControl for a few compact choices on one track.
+- Use Select when the choice list is long or space is tight.
+- Do not use it for removable tags (Chip) or for multiple selection.
+
+**Alternatives:**
+
+- [SegmentedControl](./segmented-control.md) (nearest)
+- [Select](./select.md) (nearest)
+- [Radio Group](./wa-radio-group.md) (prefer-over) — Use ChoiceChips instead of button-appearance radios that must wrap; a joined button group wraps into ragged rows with shared borders.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/choice-chips` — exports `ChoiceChips`.
+- CSS: the browser build of `@kerfjs/ui/choice-chips` pulls its CSS automatically; import `@kerfjs/ui/choice-chips.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/choice-chips`](../public-api-signatures-v1.md#kerfjsuichoice-chips) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- color swatch, transparent (struck-through) swatch, icon, or text-only choices
+- default or compact size
+- disabled group or disabled choices
+- required
+
+## Composition
+
+- Parents: any.
+- Contexts: `wrapping-exclusive-choice`.
+- Children: unrestricted.
+- Built from: [LucideIcon](./lucide-icon.md).
+
+## State and wiring
+
+- value — controlled
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Name the radio group with label or with labelledBy pointing at a visible heading.
+- Every choice keeps a visible text label; a swatch or icon is decorative.
+
+## 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-choice-chips`.
+
+Never put `kui-choice-chips` on an element you write; render `ChoiceChips` 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: [LucideIcon](./lucide-icon.md), [SegmentedControl](./segmented-control.md), [Select](./select.md), [Radio Group](./wa-radio-group.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/accessibility.md#choicechips`](../../docs/accessibility.md#choicechips).
+- UX catalog route: `?component=choice-chips`.

package/ai/components/column-track.md

@@ -0,0 +1,78 @@
+# ColumnTrack
+
+<!-- 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:column-track` · Kerf UI · component · Structure
+
+A horizontal track of equal, min-width columns that scrolls sideways, or pages one column at a time with peek and snapping.
+
+## When to use
+
+Lay out a board of columns (kanban) as one horizontal scroll owner: equal columns that never shrink below a minimum, or a paged phone layout with a peeking next column and start snapping, without app track CSS.
+
+- A board shows several parallel columns (kanban lanes) that must keep a readable width and scroll sideways, or page one at a time on a phone.
+
+**Not when:**
+
+- Do not use for a responsive grid that wraps; use Grid.
+- Do not use for two resizable panes; use SplitView or ResizableRegion.
+- Do not re-track a Grid from application CSS to get overflowing columns.
+
+**Alternatives:**
+
+- [Grid](./grid.md) (nearest) — Use Grid when columns should wrap or collapse instead of scrolling.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/column-track` — exports `ColumnTrack`.
+- CSS: the browser build of `@kerfjs/ui/column-track` pulls its CSS automatically; import `@kerfjs/ui/column-track.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/column-track`](../public-api-signatures-v1.md#kerfjsuicolumn-track) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- scroll with a minimum column width
+- paged with peek and mandatory snapping
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the columns and their content; choosing scroll or paged layout (for example by device class); drag and drop between columns.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: self (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- The track pads 8px inline and fills its parent's height; columns sit flush and own their insets and vertical scrolling.
+
+## Accessibility
+
+- Name the track with aria-label through rootAttributes when it is a landmark-like region; give each column a region name. Paged scrolling is smooth unless reduced motion is preferred.
+
+## 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-column-track`, `kui-column-track__columns`.
+
+Never put `kui-column-track`, `kui-column-track__columns` on an element you write; render `ColumnTrack` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-layout-inline-margin`. 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: [Grid](./grid.md).
+- Docs: [`docs/layout.md`](../../docs/layout.md), [`docs/component-selection.md#problem-to-component-matrix`](../../docs/component-selection.md#problem-to-component-matrix).
+- UX catalog route: `?component=column-track`.

package/ai/components/combobox.md

@@ -0,0 +1,88 @@
+# Combobox
+
+<!-- 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:combobox` · Kerf UI · component · Controls
+
+A free-text field with a filtered suggestion list that can also create a new value.
+
+## When to use
+
+Let people pick an existing value or create a new one by typing (tags, labels, recipients), with the themed field chrome, the ARIA combobox pattern, and a touch-safe font size, without a native datalist or app CSS.
+
+- People type to find an existing value among many, or create a new one (tags, labels, recipients).
+
+**Not when:**
+
+- Do not use when only existing values are allowed and nothing needs typing; use Select.
+- Do not use for free text plus removable filter tokens in one editor; use TokenSearchField.
+- Do not style a native input with a datalist from app CSS.
+
+**Alternatives:**
+
+- [Select](./select.md) (nearest) — Use Select when only existing values are allowed.
+- [TokenSearchField](./token-search-field.md) (nearest) — Use TokenSearchField for search text with removable filter tokens.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/combobox` — exports `Combobox`, `wireComboboxes`.
+- CSS: the browser build of `@kerfjs/ui/combobox` pulls its CSS automatically; import `@kerfjs/ui/combobox.css` manually only without the `browser` export condition.
+- Wiring: `wireComboboxes` from `@kerfjs/ui/wire-comboboxes` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/combobox`](../public-api-signatures-v1.md#kerfjsuicombobox) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- with create
+- suggestions only (createLabel={false})
+- hint
+- disabled
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the suggestions and the committed values; normalizing and validating created values; clearing the field after a commit.
+
+**Wiring:** `wireComboboxes` is required.
+
+- Filters suggestions, moves the active option, and reports commits; without it the list never opens.
+
+**Wiring-owned state attributes** — never render, remove, or branch on these as app state:
+
+- `data-value` on `the create option (kui-combobox__option[data-create])` (`wireComboboxes`): The typed text the create option would commit; rewritten as the person types.
+
+## Geometry
+
+Margin: none · border: self · padding: self (layout role: controls). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Label and hint sit on the value's text column (1px border + 8px padding); the 44px field matches a themed wa-input.
+
+## Accessibility
+
+- Native input with role=combobox, aria-autocomplete=list, aria-expanded, aria-controls, and aria-activedescendant; options are role=option in a listbox. The visible label is a real label; the hint is aria-describedby.
+
+## 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-combobox`, `kui-combobox__label`, `kui-combobox__hint`, `kui-combobox__control`, `kui-combobox__input`, `kui-combobox__listbox`, `kui-combobox__option`.
+
+Never put `kui-combobox`, `kui-combobox__label`, `kui-combobox__hint`, `kui-combobox__control`, `kui-combobox__input`, `kui-combobox__listbox`, `kui-combobox__option` on an element you write; render `Combobox` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-combobox-z-index`, `--kui-color-neutral-on-quiet`, `--kui-color-text-quiet`, `--kui-color-neutral-border-normal`, `--kui-color-text`, `--kui-color-surface`, `--kui-color-surface-raised`, `--kui-color-text-link`, `--kui-color-brand-fill-quiet`, `--kui-font-xs`, `--kui-font-s`, `--kui-layout-item-padding`, `--kui-layout-rounded-radius`, `--kui-shadow-l`, `--kui-space-2xs`, `--kui-space-xs`. 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: [Select](./select.md), [TokenSearchField](./token-search-field.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=combobox`.

package/ai/components/content-item.md

@@ -47,6 +47,8 @@ Exact prop names and types: [`@kerfjs/ui/content-item`](../public-api-signatures
 - framed pill item
 - base surface item
 - neutral, info, pop, success, warning, or danger semantic item
+- brand-loud item (solid brand fill, on-loud foreground)
+- chat bubble at the start or end of the row (bubble), fit to its content up to 80%
 - named focus-target region
 - multi-select rich grid row
 

package/ai/components/content-swap.md

@@ -0,0 +1,78 @@
+# ContentSwap
+
+<!-- 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-swap` · Kerf UI · component · Structure
+
+Two content sides sharing one cell, swapped in place with a push, a crossfade, or no motion.
+
+## When to use
+
+Swap arbitrary content in place (a dialog body that steps to a second page, a label or footer whose actions change) with Kerf-owned push or crossfade motion, reduced-motion handling, and an inert, hidden inactive side.
+
+- A region swaps between two contents in place, such as a dialog's two steps or a footer's action sets, and the change should read as motion.
+
+**Not when:**
+
+- Do not use for full navigation views with their own toolbars; use NavStack.
+- Do not use to swap more than two states at once; render the current pair.
+- Do not hand-roll stacked cells, inert handling, or push keyframes in app CSS.
+
+**Alternatives:**
+
+- [NavStack](./nav-stack.md) (nearest) — Use NavStack for full views with toolbars and back navigation.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/content-swap` — exports `ContentSwap`.
+- CSS: the browser build of `@kerfjs/ui/content-swap` pulls its CSS automatically; import `@kerfjs/ui/content-swap.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/content-swap`](../public-api-signatures-v1.md#kerfjsuicontent-swap) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- push forward or backward
+- crossfade
+- none
+- full-width slot region
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** which side is active and the push direction; both sides' content; the region's name.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Both sides share one grid cell; the region keeps the active side's height and clips the motion.
+
+## Accessibility
+
+- The inactive side is inert and aria-hidden; label makes the swap a named region. Push mirrors in right-to-left documents. Reduced motion replaces the slide with a short fade.
+
+## 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-swap`, `kui-content-swap__side`.
+
+Never put `kui-content-swap`, `kui-content-swap__side` on an element you write; render `ContentSwap` 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: [NavStack](./nav-stack.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=content-swap`.

package/ai/components/corner-status.md

@@ -0,0 +1,88 @@
+# CornerStatus
+
+<!-- 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:corner-status` · Kerf UI · component · Feedback
+
+Non-dismissible app-level status pinned to a viewport corner in the top layer, hosting StateBanner.
+
+## When to use
+
+Show ongoing app-level progress such as "Loading…" or "Updating tickets… 3 of 12" in a viewport corner above page chrome and any dialog opened before it, without a close button, light dismiss, Escape, or focus change.
+
+- Show ongoing app-level progress or status that has no better home beside the affected work and must stay visible until the work ends.
+
+**Not when:**
+
+- Do not use for transient, dismissible confirmation; use a toast.
+- Do not use for status that belongs beside the affected work; place a StateBanner there.
+- Do not position a StateBanner with fixed-position application CSS; use CornerStatus.
+
+**Alternatives:**
+
+- [StateBanner](./state-banner.md) (composes-with) — Compose one or more StateBanners (urgency="status") inside it; they stack.
+- [Toast](./wa-toast.md) (prefer-over) — A toast item is transient and always dismissible; CornerStatus stays until the application removes it.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/corner-status` — exports `CornerStatus`, `wireCornerStatus`.
+- CSS: the browser build of `@kerfjs/ui/corner-status` pulls its CSS automatically; import `@kerfjs/ui/corner-status.css` manually only without the `browser` export condition.
+- Wiring: `wireCornerStatus` from `@kerfjs/ui/wire-corner-status` (required).
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/corner-status`](../public-api-signatures-v1.md#kerfjsuicorner-status) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- bottom-end
+- bottom-start
+- top-end
+- top-start
+- embedded (in flow)
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [StateBanner](./state-banner.md).
+
+## State and wiring
+
+**The app owns:** status lifetime (render while the work runs, remove when it ends); the composed StateBanner copy and progress; corner placement.
+
+**Wiring:** `wireCornerStatus` is required.
+
+- Opens each overlay host in the top layer as renders insert it; without it the Popover API keeps the host hidden.
+
+## Geometry
+
+Margin: none · border: child · padding: child (layout role: feedback). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+- Placement owns the 16px viewport gutter plus device safe-area insets; a StateBanner inside drops its inline margin and gains elevation.
+
+## Accessibility
+
+- The host adds no role; the composed StateBanner with urgency="status" is the polite live region.
+- Opening never moves focus, and there is no close button, light dismiss, or Escape handling to compete with dialogs.
+- A modal dialog opened while it shows stacks above it and makes it inert (unannounced); show progress the dialog's task depends on inside the dialog.
+
+## 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-corner-status`.
+
+Never put `kui-corner-status` on an element you write; render `CornerStatus` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-corner-status-gutter`, `--kui-corner-status-z-index`, `--kui-safe-area-block-end`, `--kui-safe-area-block-start`, `--kui-safe-area-inline-end`, `--kui-safe-area-inline-start`, `--kui-space-m`, `--kui-space-xs`. 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: [StateBanner](./state-banner.md), [Toast](./wa-toast.md).
+- Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#ambiguous-choices`](../../docs/component-selection.md#ambiguous-choices).
+- UX catalog route: `?component=corner-status`.

package/ai/components/document-baseline.md

@@ -4,7 +4,7 @@
 
 `@kerfjs/ui:document-baseline` · Kerf UI · CSS composition · Foundation
 
-Opt-in document-level defaults: border-box sizing, body margin/font/surface, native table-cell and form-control font metrics, link color, and the html → body → .kui-app-root full-height chain.
+Opt-in document-level defaults: border-box sizing, body margin/font/surface, native table-cell and form-control font metrics, semantic control cursors, link color, and the html → body → .kui-app-root full-height chain.
 
 ## When to use
 
@@ -35,6 +35,7 @@ No props: this entry has no JavaScript API.
 
 - document-flow page (no .kui-app-root)
 - full-height application root
+- viewport-locked application root (data-viewport="locked" on a body-child .kui-app-root: 100dvh and overflow clip on html, body, and the root)
 
 ## Composition
 
@@ -57,6 +58,7 @@ Margin: none · border: none · padding: none (layout role: foundation). `self`
 ## Accessibility
 
 - Links keep the semantic link color at zero specificity so application focus and link styles still apply.
+- Native controls get semantic cursors at zero specificity: pointer on enabled buttons, links, role=button, checkbox/radio/button-type inputs, selects, and checkbox/radio labels; not-allowed on disabled controls, aria-disabled role=button, and a disabled wa-button's base part; text on text-like inputs and textareas.
 
 ## Styling boundary
 

package/ai/components/edge-activity-indicator.md

@@ -0,0 +1,81 @@
+# EdgeActivityIndicator
+
+<!-- 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:edge-activity-indicator` · Kerf UI · component · Feedback
+
+A layout-free top-edge activity strip with a traveling wave and an optional hanging status pill.
+
+## When to use
+
+Signal ambient background activity (server work, sync) along the top edge of the viewport without allocating layout or taking the pointer, with Kerf-owned motion and reduced-motion handling.
+
+- Ambient, app-wide background activity (server work, sync) should be visible without a modal, a banner, or any layout shift.
+
+**Not when:**
+
+- Do not use for progress the user waits on or must read; use CornerStatus or a StateBanner.
+- Do not use for known progress; use a progress bar.
+- Do not use it as the only record of important state; the bars are hidden from assistive technology.
+
+**Alternatives:**
+
+- [CornerStatus](./corner-status.md) (nearest) — Use CornerStatus for readable, non-dismissible app-level progress.
+- [LoadingSpinner](./loading-spinner.md) (nearest) — Use LoadingSpinner for local activity beside the affected control.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/edge-activity-indicator` — exports `EdgeActivityIndicator`.
+- CSS: the browser build of `@kerfjs/ui/edge-activity-indicator` pulls its CSS automatically; import `@kerfjs/ui/edge-activity-indicator.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/edge-activity-indicator`](../public-api-signatures-v1.md#kerfjsuiedge-activity-indicator) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- busy or idle
+- with or without a status pill
+- semantic tone
+- safe-area inset or flush
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+
+## State and wiring
+
+**The app owns:** the busy state; the optional status message; the tone.
+
+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.
+
+- Fixed to the top edge below the device safe area; it allocates no layout.
+
+## Accessibility
+
+- The strip is aria-hidden and pointer-inert; the optional pill is a polite live region that holds text only while it shows. Under reduced motion the wave and scale stop and the strip and pill only fade.
+
+## 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-edge-activity-indicator`, `kui-edge-activity-indicator__strip`, `kui-edge-activity-indicator__message`.
+
+Never put `kui-edge-activity-indicator`, `kui-edge-activity-indicator__strip`, `kui-edge-activity-indicator__message` on an element you write; render `EdgeActivityIndicator` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-edge-activity-indicator-z-index`, `--kui-safe-area-block-start`, `--kui-color-brand-fill-loud`, `--kui-color-brand-on-loud`, `--kui-color-neutral-fill-loud`, `--kui-color-neutral-on-loud`, `--kui-color-pop-fill-loud`, `--kui-color-pop-on-loud`, `--kui-color-success-fill-loud`, `--kui-color-success-on-loud`, `--kui-color-warning-fill-loud`, `--kui-color-warning-on-loud`, `--kui-color-danger-fill-loud`, `--kui-color-danger-on-loud`, `--kui-font-2xs`, `--kui-space-m`, `--kui-space-s`. 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: [CornerStatus](./corner-status.md), [LoadingSpinner](./loading-spinner.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=edge-activity-indicator`.