@kerfjs/ui 5.0.0-beta.102 → 5.0.0-beta.104

package/README.md

@@ -311,6 +311,9 @@ when it adds useful context. Set `responsive="wrap"` on a heading whose title
 must stay whole: it keeps one row while everything fits and otherwise moves the
 trailing actions below the title instead of truncating it.
 
+A toolbar with a single zone gives it the whole content box, so content set to
+fill the row reaches both insets; an absent zone leaves no empty track or gap.
+
 A toolbar never clips an action. Its trailing zone wraps whole control groups
 onto another trailing-aligned row under every `responsive` policy, and a
 `responsive="stack"` toolbar wraps its stacked center and trailing groups the
@@ -778,7 +781,12 @@ pass it as the field's `model`, and register it under the field id in
 their optional `suggest` function supplies selectable completions. The model
 commits valid expressions on whitespace or Enter, owns chips and clear/edit/
 remove actions, and exposes `state`, `suggestions`, and the latest `result` as
-signals. Omit the model to retain full manual control. Use `readTokenSearchField()`
+signals. The field subscribes only to `model.structure`, which changes when a
+token is committed or removed, the text becomes empty or non-empty, or the
+editor revision changes, so typing plain text never re-runs the host render.
+Keep it that way in the host: read `model.state.peek()` in render, and bind
+`model.result` (or a `computed`) as a fine-grained signal hole rather than
+reading `model.state.value`. Omit the model to retain full manual control. Use `readTokenSearchField()`
 after browser input to recover text plus token offsets, and
 `placeTokenSearchCaret()` when restoring focus after a controlled update.
 Call `wireTokenSearchFields()` once at a stable root to make Enter submit through

package/ai/component-catalog.json

@@ -84,26 +84,29 @@
       "category": "Foundation",
       "kind": "component",
       "source": "kerf",
-      "description": "A short tag with semantic or inherited tone, an optional accessible remove button, or a native link and download form, including compact and disabled variants.",
+      "description": "A short tag with semantic or inherited tone, an optional accessible remove button, a native link and download form, or a native action button, including compact and disabled variants.",
       "uses": [],
-      "purpose": "Render removable tags and file or link chips without application rules on Web Awesome internals or anchor chrome.",
+      "purpose": "Render removable tags, file or link chips, and activatable action chips without application rules on Web Awesome internals or anchor and button chrome.",
       "publicExports": [
         "Chip"
       ],
       "useWhen": [
         "Show a short tag that the application can remove through a delegated action, including a compact or disabled tag.",
-        "Show a downloadable file or a short link with chip geometry, such as the referenced files of a chat message; set tone inherit inside a brand-loud or neutral ContentItem bubble."
+        "Show a downloadable file or a short link with chip geometry, such as the referenced files of a chat message; set tone inherit inside a brand-loud or neutral ContentItem bubble.",
+        "Offer a short value the user can activate to apply it, such as a filter token in a search syntax help popover that inserts itself into the query: set action (and itemId) so the whole chip is a native button."
       ],
       "avoidWhen": [
         "Use Badge for non-interactive status and count metadata.",
         "Do not use the remove button without a specific accessible name.",
-        "Use ListItemLink for a navigation row and ToolbarActionLink for a toolbar link."
+        "Use ListItemLink for a navigation row and ToolbarActionLink for a toolbar link.",
+        "Use ChoiceChips when the chips choose a persistent value with radio or checkbox state; an action chip fires a one-shot command."
       ],
       "alternatives": [],
       "appOwns": [
         "tag text and identity",
         "remove action and list update",
         "link destination and download file name",
+        "action handler and its effect",
         "disabled policy"
       ],
       "variants": [
@@ -111,12 +114,13 @@
         "quiet, solid, or outline appearance",
         "pill or rounded shape",
         "compact or default size",
-        "removable, link, or plain, enabled or disabled"
+        "removable, link, action, or plain, enabled or disabled"
       ],
       "accessibility": [
         "The remove control is a native button and requires an action and a specific removeLabel. A disabled chip disables that button and removes it from keyboard interaction.",
         "A link chip is a native anchor named by its visible label; external adds a safe rel, a new tab, and an \"(opens in new tab)\" name suffix, and a disabled link chip drops its destination and leaves the tab order.",
         "The inherit tone paints no fill, so its label keeps the surrounding text contrast, and its focus ring follows the surrounding foreground.",
+        "An action chip is one native button (type button) named by its visible label or by actionLabel, which should include that label; Enter and Space activate it, it shows the focus ring on keyboard focus, and a disabled action chip is a disabled button that leaves the tab order. It cannot also be a link or carry a remove button.",
         "Keep meaningful tag text visible because tone is supplementary."
       ],
       "geometry": {
@@ -5363,6 +5367,7 @@
       ],
       "appOwns": [
         "the grammar and evaluation callback when using the optional managed model, or parsing, suggestions, tokens, and query execution in manual mode",
+        "reading the managed model without subscribing per keystroke: TokenSearchField subscribes only to model.structure (committed tokens, empty or non-empty text, editor revision) and model.suggestions, so plain typing never re-runs the host render; in the host's own render, read model.state.peek() or bind model.result (or a computed) as a fine-grained signal hole instead of reading model.state.value",
         "results",
         "the revision that rebuilds the DOM-owned editor for a programmatic text replacement",
         "optional override of the collapsible expand/collapse/focus, which wireTokenSearchFields manages by default (adopt an app expanded signal, opt out per behavior, or drive it via the returned handle)",

package/ai/component-composition-rules.json

@@ -307,7 +307,8 @@
       "helpers": ["wireTokenSearchFields"],
       "obligations": [
         "Retain and invoke the disposer.",
-        "Use readTokenSearchField for DOM-owned text."
+        "Use readTokenSearchField for DOM-owned text.",
+        "With a managed model, read model.state.peek() (never model.state.value) in the host render and bind model.result as a signal hole; the field itself re-renders only when model.structure changes, not per keystroke."
       ]
     },
     "diagnostics": [

package/ai/component-composition.json

@@ -88,6 +88,11 @@
           "owner": "application",
           "required": false
         },
+        {
+          "id": "action handler and its effect",
+          "owner": "application",
+          "required": false
+        },
         { "id": "disabled policy", "owner": "application", "required": false }
       ],
       "wiring": {
@@ -106,6 +111,7 @@
           "The remove control is a native button and requires an action and a specific removeLabel. A disabled chip disables that button and removes it from keyboard interaction.",
           "A link chip is a native anchor named by its visible label; external adds a safe rel, a new tab, and an \"(opens in new tab)\" name suffix, and a disabled link chip drops its destination and leaves the tab order.",
           "The inherit tone paints no fill, so its label keeps the surrounding text contrast, and its focus ring follows the surrounding foreground.",
+          "An action chip is one native button (type button) named by its visible label or by actionLabel, which should include that label; Enter and Space activate it, it shows the focus ring on keyboard focus, and a disabled action chip is a disabled button that leaves the tab order. It cannot also be a link or carry a remove button.",
           "Keep meaningful tag text visible because tone is supplementary."
         ]
       },
@@ -4387,7 +4393,8 @@
         "helpers": ["wireTokenSearchFields"],
         "obligations": [
           "Retain and invoke the disposer.",
-          "Use readTokenSearchField for DOM-owned text."
+          "Use readTokenSearchField for DOM-owned text.",
+          "With a managed model, read model.state.peek() (never model.state.value) in the host render and bind model.result as a signal hole; the field itself re-renders only when model.structure changes, not per keystroke."
         ],
         "stateAttributes": [
           {

package/ai/components/README.md

@@ -9,7 +9,7 @@ Exact prop and callback types live in [`public-api-signatures-v1.md`](../public-
 ## Kerf UI — Foundation
 
 - [Badge](./badge.md) — Present compact metadata without application-authored badge CSS or consumer styling of component internals.
-- [Chip](./chip.md) — Render removable tags and file or link chips without application rules on Web Awesome internals or anchor chrome.
+- [Chip](./chip.md) — Render removable tags, file or link chips, and activatable action chips without application rules on Web Awesome internals or anchor and button chrome.
 - [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.

package/ai/components/chip.md

@@ -4,20 +4,22 @@
 
 `@kerfjs/ui:chip` · Kerf UI · component · Foundation
 
-A short tag with semantic or inherited tone, an optional accessible remove button, or a native link and download form, including compact and disabled variants.
+A short tag with semantic or inherited tone, an optional accessible remove button, a native link and download form, or a native action button, including compact and disabled variants.
 
 ## When to use
 
-Render removable tags and file or link chips without application rules on Web Awesome internals or anchor chrome.
+Render removable tags, file or link chips, and activatable action chips without application rules on Web Awesome internals or anchor and button chrome.
 
 - Show a short tag that the application can remove through a delegated action, including a compact or disabled tag.
 - Show a downloadable file or a short link with chip geometry, such as the referenced files of a chat message; set tone inherit inside a brand-loud or neutral ContentItem bubble.
+- Offer a short value the user can activate to apply it, such as a filter token in a search syntax help popover that inserts itself into the query: set action (and itemId) so the whole chip is a native button.
 
 **Not when:**
 
 - Use Badge for non-interactive status and count metadata.
 - Do not use the remove button without a specific accessible name.
 - Use ListItemLink for a navigation row and ToolbarActionLink for a toolbar link.
+- Use ChoiceChips when the chips choose a persistent value with radio or checkbox state; an action chip fires a one-shot command.
 
 ## Imports
 
@@ -35,7 +37,7 @@ Exact prop names and types: [`@kerfjs/ui/chip`](../public-api-signatures-v1.md#k
 - quiet, solid, or outline appearance
 - pill or rounded shape
 - compact or default size
-- removable, link, or plain, enabled or disabled
+- removable, link, action, or plain, enabled or disabled
 
 ## Composition
 
@@ -45,7 +47,7 @@ Exact prop names and types: [`@kerfjs/ui/chip`](../public-api-signatures-v1.md#k
 
 ## State and wiring
 
-**The app owns:** tag text and identity; remove action and list update; link destination and download file name; disabled policy.
+**The app owns:** tag text and identity; remove action and list update; link destination and download file name; action handler and its effect; disabled policy.
 
 No wiring helper.
 
@@ -58,6 +60,7 @@ Margin: none · border: self · padding: self (layout role: foundation). `self`
 - The remove control is a native button and requires an action and a specific removeLabel. A disabled chip disables that button and removes it from keyboard interaction.
 - A link chip is a native anchor named by its visible label; external adds a safe rel, a new tab, and an "(opens in new tab)" name suffix, and a disabled link chip drops its destination and leaves the tab order.
 - The inherit tone paints no fill, so its label keeps the surrounding text contrast, and its focus ring follows the surrounding foreground.
+- An action chip is one native button (type button) named by its visible label or by actionLabel, which should include that label; Enter and Space activate it, it shows the focus ring on keyboard focus, and a disabled action chip is a disabled button that leaves the tab order. It cannot also be a link or carry a remove button.
 - Keep meaningful tag text visible because tone is supplementary.
 
 ## Styling boundary

package/ai/components/token-search-field.md

@@ -65,6 +65,7 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 - Retain and invoke the disposer.
 - Use readTokenSearchField for DOM-owned text.
+- With a managed model, read model.state.peek() (never model.state.value) in the host render and bind model.result as a signal hole; the field itself re-renders only when model.structure changes, not per keystroke.
 
 **Wiring-owned state attributes** — never render, remove, or branch on these as app state:
 

package/ai/public-api-signatures-v1.md

@@ -1,6 +1,6 @@
 # Public API signatures for the UI authoring corpus
 
-Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.102` and `kerfjs@5.0.0-beta.102`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
+Generated from emitted declarations for `@kerfjs/ui@5.0.0-beta.104` and `kerfjs@5.0.0-beta.104`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/css-values`
 
@@ -3836,7 +3836,7 @@ export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape, ensureSunken
 ## `@kerfjs/ui/token-search-field`
 
 ```ts
-export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, k as TokenSearchTrailingAction, l as TokenSearchTrailingActionAttributes, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-model-aYR0YAei.js';
+export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, k as TokenSearchToken, l as TokenSearchTrailingAction, m as TokenSearchTrailingActionAttributes, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-model-JA1i8z4D.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
 ```
@@ -3845,7 +3845,7 @@ import './semantic-content-BbzjvSu9.js';
 
 ```ts
 import { Signal } from 'kerfjs';
-import { d as TokenSearchModel } from './token-search-model-aYR0YAei.js';
+import { d as TokenSearchModel } from './token-search-model-JA1i8z4D.js';
 import './semantic-content-BbzjvSu9.js';
 
 interface TokenSearchSubmit {
@@ -4166,6 +4166,31 @@ interface ChipNoLinkProps {
     download?: never;
     external?: never;
 }
+interface ChipNoActionProps {
+    action?: never;
+    actionLabel?: never;
+}
+/**
+ * An action chip renders its whole root as a native
+ * `<button type="button">` carrying `data-action` (and `data-item-id`) for an
+ * application delegated handler. It cannot also be a link or carry a remove
+ * button, because nested interactive content is invalid.
+ */
+interface ChipActionProps {
+    /** Delegated action name; the chip renders as a native `<button>`. */
+    action: string;
+    /**
+     * Accessible name when the visible label alone is unclear, such as
+     * "Insert filter is:mine". Start it with, or include, the visible label so
+     * speech input still matches.
+     */
+    actionLabel?: string;
+    href?: never;
+    download?: never;
+    external?: never;
+    removeAction?: never;
+    removeLabel?: never;
+}
 /**
  * A link chip renders a native `<a>` with Chip geometry. It cannot also carry
  * a remove button, because a button inside a link is invalid.
@@ -4179,23 +4204,28 @@ interface ChipLinkProps {
     external?: boolean;
     removeAction?: never;
     removeLabel?: never;
+    action?: never;
+    actionLabel?: never;
 }
 /**
  * A plain chip, a removable chip (a delegated action plus a specific
- * accessible name), or a link chip (`href`, optional `download`/`external`).
+ * accessible name), a link chip (`href`, optional `download`/`external`), or
+ * an action chip (`action`, optional `actionLabel`) whose whole body is a
+ * native button.
  */
 type ChipProps = ChipCommonProps & ChipLabelProps & (({
     removeAction: string;
     removeLabel: string;
-} & ChipNoLinkProps) | ({
+} & ChipNoLinkProps & ChipNoActionProps) | ({
     removeAction?: never;
     removeLabel?: never;
-} & ChipNoLinkProps) | ChipLinkProps);
+} & ChipNoLinkProps & ChipNoActionProps) | ChipLinkProps | ChipActionProps);
 /**
- * A short label with an optional native remove button, or a native link when
- * `href` is set. The application owns removal and the link destination.
+ * A short label with an optional native remove button, a native link when
+ * `href` is set, or a native button when `action` is set. The application
+ * owns removal, the link destination, and the action handler.
  */
-declare function Chip({ children, icon, truncate, tone, appearance, shape, size, disabled, itemId, className, slot, href, download, external, removeAction, removeLabel, }: ChipProps): SafeHtml;
+declare function Chip({ children, icon, truncate, tone, appearance, shape, size, disabled, itemId, className, slot, href, download, external, removeAction, removeLabel, action, actionLabel, }: ChipProps): SafeHtml;
 
 export { Chip, type ChipProps, type ChipTone };
 ```
@@ -5042,7 +5072,7 @@ export { CssLength, Spacer, type SpacerProps, UiSpaceName };
 ## `@kerfjs/ui/token-search-model`
 
 ```ts
-export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, m as createTokenSearchModel } from './token-search-model-aYR0YAei.js';
+export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchStructure, j as TokenSearchSuggestion, n as createTokenSearchModel } from './token-search-model-JA1i8z4D.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
 ```

package/ai/skill.md

@@ -1,7 +1,7 @@
 ---
 name: kerf-ui
 description: Build interfaces with kerfjs and the @kerfjs/ui production component package. Use whenever code imports @kerfjs/ui or a task asks for Kerf UI components.
-kerf-ui-skill-version: 1.61.0
+kerf-ui-skill-version: 1.62.0
 ---
 
 # Building with @kerfjs/ui
@@ -368,7 +368,7 @@ Hard rules:
 8. `ResizableRegion` uses `wireResizableRegions()` for Arrow, Shift+Arrow, Home/End, and pointer behavior. The app owns size persistence. `handleIcon` replaces decorative dormant glyph content only. Set `responsiveFillAt="narrow"` or `"compact"` when a responsive composition exposes the pane as its only inline track; the component fills that track and hides its dormant separator. For compact overlays, set `presentation="overlay"` and the overlay maximum variables. A lone child (normally a `Pane`) fills the region and owns scrolling; several children stack at natural height. Do not add descendant width/height overrides.
 9. Use controlled `SegmentedControl` for a small exclusive choice set. Select `appearance="toolbar"` when nesting it inside `ToolbarControlGroup`; use rounded or pill shapes for standalone contexts. The package derives inset hover/selection radii from the owning outer shape through `--kui-layout-highlight-inset`; do not restyle an inner highlight to an independent radius. Handle its action, update `value`, keep meaningful choice labels, and preserve every enabled native button in sequential Tab order.
 10. Compose `AppTab` inside controlled `TabBar`; call `wireTabBars()` once and retain its disposer. It owns same-bar drag mechanics, including proximity-based horizontal edge autoscroll, while the app applies `onReorder` and owns order, selection, panels, close policy, routing, and persistence. For a tab-local action followed by a separately pinned workspace action, set `trailingPlacement="adjacent"`, put the local action in `trailing`, and the workspace action in `end`; each action zone accepts one `ToolbarControlGroup` or a standalone `wa-button` when the action needs its own Web Awesome chrome. TabBar owns the shrinking/scrolling tabs and fixed action geometry, so do not add descendant flex overrides. Arrow/Home/End select on move by default and restore focus by bar/tab identity when controlled activation replaces the strip; pass `activation: 'manual'` (or `TabBar activation="manual"` per strip) so arrow keys move focus only and the user selects with Enter/Space/click — use it when selecting a tab is a heavy action. Use runtime-filtered `rootAttributes` for domain metadata and keep an optional `closeIcon` decorative and noninteractive.
-11. Use token-controlled `TokenSearchField` when free text and removable structured filters share one editor. Editable text stays DOM-owned between token changes; to replace the text programmatically (reseeding a persistent dialog's field on reopen, applying a saved search) change the field's `revision` along with `query` for an unmanaged field, or call `model.replace({ query, tokens })` for a model-managed field; never re-key a wrapper. The leading icon, first text line, clear action, and trailing slot share one fixed row when content wraps. For automatic parsing, chips, suggestions, and evaluation, use createTokenSearchModel with grammar rules, pass it as TokenSearchField.model, and register it in wireTokenSearchFields models; a rule's `suggest(input, state)` receives committed tokens so it can exclude selected values. Otherwise the app owns parsing and suggestions; call `readTokenSearchField()` on input, empty `textContent` on clear, use `placeTokenSearchCaret()` after explicit controlled focus changes, and call `wireTokenSearchFields()` once so Enter submits without inserting a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. `clearIcon` replaces the clear action's glyph (its `clearLabel` still names it). For a compact icon button beside the clear button (a search-syntax help glyph), pass `trailingAction: { icon, label, action, expanded?, pressed?, controls?, haspopup?, attributes? }` — it matches the clear button's size, hover, focus, and cursor in every presentation; set `expanded` for a disclosure or `pressed` for a toggle, never both, and never hand-style a button into `trailing`. Enable `collapsible` for an animated iconic closed state, standalone or inside `ToolbarControlGroup`; the field keeps text or tokens expanded, and `wireTokenSearchFields()` manages the transient expand/collapse/focus by default (activate to reveal + focus, Escape or empty blur to collapse). Bind the field's `expanded` to the returned handle's `expanded(id)` signal or adopt your own via `collapsible.signals`; opt a behavior out only when the app must own it. Do not hand-roll the open handler, the focusout collapse, a clear-button mousedown guard, or reopening after controlled clear or Select All deletion — the helper keeps the replacement editor open and focused. Clear and deletion restoration finish at the replacement mutation checkpoint before the next input task, so shortcut-letter typing cannot escape to the page and delayed animation frames cannot overwrite a later selection. Persist both query and tokens returned by the DOM read. For real-app adoption it also provides a focusout keep-open exception (`data-token-search-keep-open` regions or `collapsible.keepOpenOn(target)`, so a sibling suggestions/date/help surface does not collapse an empty field), opt-in atomic-chip keyboard (`keyboard`: Backspace/Delete remove the adjacent chip via `onRemoveToken`, ArrowRight moves the caret past a trailing chip), and an `onEdit({id, editor, event})` input callback (the `InputEvent` lets you gate on `inputType`/`data`) — reach for these instead of re-adding hand-rolled keydown/input handlers around the field.
+11. Use token-controlled `TokenSearchField` when free text and removable structured filters share one editor. Editable text stays DOM-owned between token changes; to replace the text programmatically (reseeding a persistent dialog's field on reopen, applying a saved search) change the field's `revision` along with `query` for an unmanaged field, or call `model.replace({ query, tokens })` for a model-managed field; never re-key a wrapper. The leading icon, first text line, clear action, and trailing slot share one fixed row when content wraps. For automatic parsing, chips, suggestions, and evaluation, use createTokenSearchModel with grammar rules, pass it as TokenSearchField.model, and register it in wireTokenSearchFields models; a rule's `suggest(input, state)` receives committed tokens so it can exclude selected values. The field subscribes only to `model.structure` (committed tokens, empty or non-empty text, editor revision), so plain typing never re-runs the host render; in the host's own render read `model.state.peek()` and bind `model.result` (or a `computed`) as a signal hole — reading `model.state.value` there re-renders the host on every keystroke. Otherwise the app owns parsing and suggestions; call `readTokenSearchField()` on input, empty `textContent` on clear, use `placeTokenSearchCaret()` after explicit controlled focus changes, and call `wireTokenSearchFields()` once so Enter submits without inserting a line break and keyboard chip deletion restores focus plus the text-relative caret after controlled replacement. `clearIcon` replaces the clear action's glyph (its `clearLabel` still names it). For a compact icon button beside the clear button (a search-syntax help glyph), pass `trailingAction: { icon, label, action, expanded?, pressed?, controls?, haspopup?, attributes? }` — it matches the clear button's size, hover, focus, and cursor in every presentation; set `expanded` for a disclosure or `pressed` for a toggle, never both, and never hand-style a button into `trailing`. Enable `collapsible` for an animated iconic closed state, standalone or inside `ToolbarControlGroup`; the field keeps text or tokens expanded, and `wireTokenSearchFields()` manages the transient expand/collapse/focus by default (activate to reveal + focus, Escape or empty blur to collapse). Bind the field's `expanded` to the returned handle's `expanded(id)` signal or adopt your own via `collapsible.signals`; opt a behavior out only when the app must own it. Do not hand-roll the open handler, the focusout collapse, a clear-button mousedown guard, or reopening after controlled clear or Select All deletion — the helper keeps the replacement editor open and focused. Clear and deletion restoration finish at the replacement mutation checkpoint before the next input task, so shortcut-letter typing cannot escape to the page and delayed animation frames cannot overwrite a later selection. Persist both query and tokens returned by the DOM read. For real-app adoption it also provides a focusout keep-open exception (`data-token-search-keep-open` regions or `collapsible.keepOpenOn(target)`, so a sibling suggestions/date/help surface does not collapse an empty field), opt-in atomic-chip keyboard (`keyboard`: Backspace/Delete remove the adjacent chip via `onRemoveToken`, ArrowRight moves the caret past a trailing chip), and an `onEdit({id, editor, event})` input callback (the `InputEvent` lets you gate on `inputType`/`data`) — reach for these instead of re-adding hand-rolled keydown/input handlers around the field.
     An application helper can call `model.commit(value)` for the active `name:` prefix when it computes a valid value outside suggestions; invalid values and missing prefixes leave the query unchanged.
 12. Demo work uses public production component subpaths and their browser-selected CSS. Focused demos and recipes have no local stylesheet, inline style, or styling-only class; use public components and `CatalogExample.viewport` for unavoidable specimen constraints (a recipe declares its frame through its exported `presentation`). To preview a top-layer specimen that production anchors with CSS anchor positioning, name the frame with `viewport.anchorName` (a dashed-ident such as `"--app-shell-main"`) and center in-flow content with `viewport.contentWidth` + `contentAlign: "center"` instead of wrapping the specimen in a stage element. When a recipe needs a capability no component offers, report the component gap instead of adding CSS. Use exactly three demo kinds: a `component` is one component with variants/states, a `composition` is a focused container of components commonly used together, and a `recipe` is the recommended production approach to a task. Organize catalog routes into product-important functional groups; within each group put all components before compositions, order each kind by importance with display-name alphabetical tie-breaking, and put recipes after every component/composition group. Show `Composition` as an entry tag instead of repeating the word in its name. Give every public visual component its own category-grouped catalog route; list themed third-party components under a clearly labeled collapsible ecosystem section, with a focused route for each. For the complete taxonomy, focused/composition decision, `CatalogExample` / `CatalogExampleStack` row/group nesting, specimen structure and metadata ownership, follow the single [Catalog demo authoring contract](../docs/catalog.md#catalog-demo-authoring-contract), discovered machine-readably through [`catalog-authoring.json`](./catalog-authoring.json). Never infer structure from private `kui-catalog-*` classes. Project each component's deterministic repository-relative demo source and existing documentation path so the detail can expose `View demo source` and `Read guidance` links without a runtime export; also derive first-party component implementation paths from their canonical browser imports, and label Web Awesome documentation as Kerf integration guidance. Declare direct `uses` relationships so `Used by` stays derivable, and theme shell chrome through the same semantic tokens as the stage instead of drawing a substitute. Enable `wireCatalog({ revealSelection: true })` for long desktop sidebars so controlled selections remain visible without moving focus; keep its default compact media guard unless compact scrolling is an explicit product behavior, and use `revealCatalogEntry` for an initial deep link.
 13. The Web Awesome theme makes Tooltip and Popover arrowless by default. Keep that default unless a pointer materially clarifies the anchor; opt back in with `--wa-tooltip-arrow-size`, `--kui-wa-popover-arrow-size`, or a popover's public `--arrow-size`, and use `without-arrow` when local no-arrow intent should survive theme changes. Its non-field chrome uses `--kui-wa-control-inset` (8px controls/items), `--kui-wa-surface-margin` / `--kui-wa-surface-inset` (8px around/inside Accordion, Card, Details, Callout, and Include), and `--kui-wa-container-inset` (16px Tab Panel content and framed disclosure regions). Plain Details use the 8px surface inset on the trigger and keep the body flush; plain Accordion items use it on both trigger and body. Outlined and sunken Details use the 16px container inset on the trigger and 8px on the body; framed Accordion items use 16px on both. Dialog maps its body to the 8px surface tier and its footer to the 16px container tier independently of `--spacing`. Override those tiers instead of restyling individual parts. Filled badges use each variant's quiet fill with normal text so their compact copy stays WCAG-AA readable; override the pair with `--kui-wa-badge-filled-background` / `--kui-wa-badge-filled-foreground`, not host selectors. The theme draws a dialog's or drawer's built-in close control as the same 40px borderless circle a single `ToolbarControlGroup` button uses, so do not restyle it. When a dialog provides another dismissal affordance, put `hide-actions` on the `wa-dialog` host to hide its directly exported `header-actions` part; never chain `::part()` selectors through internal parts. Checkbox and Radio Group option regions, the Color Picker trigger, and Slider's complete interactive region receive the shared 8px logical inline outer inset because those controls have no bordered field shell. Known Date field captions and bordered text-like field hints align with values at the 9px border-plus-padding inset. OTP Input's label uses the same uppercase xs/650 treatment as other field labels, and both its label and hint use that 9px inset.
@@ -470,7 +470,7 @@ For prominent content text, use `Text size="large"`; use `size="xlarge"` for dis
 
 For an exclusive choice among several visible options that must wrap (a labeled color palette), use `ChoiceChips` from `@kerfjs/ui/choice-chips`: separate pills backed by native radios, so the group is one Tab stop, arrow keys select, and the checked radio submits under `name`. Name it with `label` or `labelledBy` (a visible `FieldLabel`), lead choices with `swatch` (a `CssColor` such as `fillColor('#3b82f6')`, or `'transparent'` for the struck-through no-color dot) or `icon`, and handle the delegated `action` on `change`. Never wrap a `SegmentedControl` or button-appearance `wa-radio` set instead. Set `multiple` with a `readonly Value[]` `value` when any number of the options may be on (label filters, annotation intents): the pills become native checkboxes in a `role="group"`, each its own Tab stop that Space toggles, and every checked value submits under `name` (read the checked boxes by name in the change handler). A multiple group takes no `required`. On dark inverse chrome, put the chips in a dark appearance scope (`.wa-dark` or any `color-scheme: dark` ancestor) instead of restyling them.
 
-For removable tags use `Chip`, with `removeAction` for delegated handling and a specific `removeLabel` for the native button. `itemId` identifies the tag; the app owns removal. `size="compact"` and `disabled` replace app styling of raw `wa-tag` internals. Use `Badge` for non-interactive metadata. For a downloadable file or a short link, give `Chip` an `href` (optional `download`, `true` or a file name, and `external`) instead of styling an `<a>`: it renders a native link with chip geometry, icon, truncation, focus ring, and hover feedback, and cannot also carry a remove button. Inside a `brand-loud` or `neutral` ContentItem bubble set `tone="inherit"`, which follows the bubble's foreground with a currentColor border and no fill.
+For removable tags use `Chip`, with `removeAction` for delegated handling and a specific `removeLabel` for the native button. `itemId` identifies the tag; the app owns removal. `size="compact"` and `disabled` replace app styling of raw `wa-tag` internals. Use `Badge` for non-interactive metadata. For a downloadable file or a short link, give `Chip` an `href` (optional `download`, `true` or a file name, and `external`) instead of styling an `<a>`: it renders a native link with chip geometry, icon, truncation, focus ring, and hover feedback, and cannot also carry a remove button. Inside a `brand-loud` or `neutral` ContentItem bubble set `tone="inherit"`, which follows the bubble's foreground with a currentColor border and no fill. For a short value the user activates once (a filter token in a search help popover that inserts itself into the query), give `Chip` an `action` and `itemId`: the whole chip becomes a native `<button type="button" data-action data-item-id>` with hover, press, focus-ring, and disabled states, and an optional `actionLabel` that contains the visible label. It cannot also take `href` or `removeAction`. A compact rounded action chip keeps a compact `Badge`'s height in a compact `ValueTable` cell, so use it there instead of a `Badge` the app makes clickable.
 
 For a chat message or assistant prompt, use `Composer` from `@kerfjs/ui/composer`: a raised frame whose border turns brand while focus is within, a borderless textarea that grows between `minRows` (default 1) and `maxRows` (default 8) lines and then scrolls, and an action row with an optional quiet `hint` and trailing `actions` (a brand Send `wa-button`). Name it with a title-style `label` and give it an `id` so the hint describes the field; the app reads and clears the textarea in its send action. For Enter-to-send, set `submitOnEnter` and call `wireComposers(root)` from `@kerfjs/ui/wire-composers` once; Enter or Cmd/Ctrl+Enter clicks the first trailing action, Shift+Enter inserts a newline, and an IME composition commit or an empty message never sends. Never hand-roll that keydown handler. In a chat dialog, slot it into a `DialogSurface` with `footerPresentation="floating"` and `footerInset="none"`. Never wrap a `wa-textarea` and a button in app-styled composer chrome.
 

package/ai/webawesome-jsx-signatures-v1.md

@@ -1,6 +1,6 @@
 # Web Awesome JSX signatures for the UI authoring corpus
 
-Generated from the emitted `@kerfjs/ui@5.0.0-beta.102` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
+Generated from the emitted `@kerfjs/ui@5.0.0-beta.104` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
 
 ```ts
 import { KerfCustomElement } from 'kerfjs/jsx-runtime';

package/dist/catalog.js

@@ -3,7 +3,7 @@ import { uxReviewCaptureUrl } from './chunk-6C6DLP3W.js';
 export { UX_REVIEW_PROJECT_PATH, loadUxReviewProject, uxReviewCaptureUrl } from './chunk-6C6DLP3W.js';
 
 
-import { TokenSearchField } from './chunk-MF6ZUUJZ.js';
+import { TokenSearchField } from './chunk-ZJC5ND3M.js';
 
 import { Row } from './chunk-YQ2AC4E2.js';
 import { ListItem } from './chunk-ZYU5WRC3.js';

package/dist/chip.d.ts

@@ -35,6 +35,31 @@ interface ChipNoLinkProps {
     download?: never;
     external?: never;
 }
+interface ChipNoActionProps {
+    action?: never;
+    actionLabel?: never;
+}
+/**
+ * An action chip renders its whole root as a native
+ * `<button type="button">` carrying `data-action` (and `data-item-id`) for an
+ * application delegated handler. It cannot also be a link or carry a remove
+ * button, because nested interactive content is invalid.
+ */
+interface ChipActionProps {
+    /** Delegated action name; the chip renders as a native `<button>`. */
+    action: string;
+    /**
+     * Accessible name when the visible label alone is unclear, such as
+     * "Insert filter is:mine". Start it with, or include, the visible label so
+     * speech input still matches.
+     */
+    actionLabel?: string;
+    href?: never;
+    download?: never;
+    external?: never;
+    removeAction?: never;
+    removeLabel?: never;
+}
 /**
  * A link chip renders a native `<a>` with Chip geometry. It cannot also carry
  * a remove button, because a button inside a link is invalid.
@@ -48,22 +73,27 @@ interface ChipLinkProps {
     external?: boolean;
     removeAction?: never;
     removeLabel?: never;
+    action?: never;
+    actionLabel?: never;
 }
 /**
  * A plain chip, a removable chip (a delegated action plus a specific
- * accessible name), or a link chip (`href`, optional `download`/`external`).
+ * accessible name), a link chip (`href`, optional `download`/`external`), or
+ * an action chip (`action`, optional `actionLabel`) whose whole body is a
+ * native button.
  */
 type ChipProps = ChipCommonProps & ChipLabelProps & (({
     removeAction: string;
     removeLabel: string;
-} & ChipNoLinkProps) | ({
+} & ChipNoLinkProps & ChipNoActionProps) | ({
     removeAction?: never;
     removeLabel?: never;
-} & ChipNoLinkProps) | ChipLinkProps);
+} & ChipNoLinkProps & ChipNoActionProps) | ChipLinkProps | ChipActionProps);
 /**
- * A short label with an optional native remove button, or a native link when
- * `href` is set. The application owns removal and the link destination.
+ * A short label with an optional native remove button, a native link when
+ * `href` is set, or a native button when `action` is set. The application
+ * owns removal, the link destination, and the action handler.
  */
-declare function Chip({ children, icon, truncate, tone, appearance, shape, size, disabled, itemId, className, slot, href, download, external, removeAction, removeLabel, }: ChipProps): SafeHtml;
+declare function Chip({ children, icon, truncate, tone, appearance, shape, size, disabled, itemId, className, slot, href, download, external, removeAction, removeLabel, action, actionLabel, }: ChipProps): SafeHtml;
 
 export { Chip, type ChipProps, type ChipTone };

package/dist/chip.js

@@ -1,3 +1,3 @@
-export { Chip } from './chunk-34U4ANDJ.js';
+export { Chip } from './chunk-N7MBGONH.js';
 
 //# sourceMappingURL=chip.js.map

package/dist/{chunk-PKL6QJKK.js → chunk-CR5U5FV6.js}

@@ -1,4 +1,4 @@
-import { readTokenSearchField, placeTokenSearchCaret } from './chunk-MF6ZUUJZ.js';
+import { readTokenSearchField, placeTokenSearchCaret } from './chunk-ZJC5ND3M.js';
 import { autoUpdate, computePosition, offset, flip, shift, size } from '@floating-ui/dom';
 import { delegate, delegateCapture, signal } from 'kerfjs';
 
@@ -832,4 +832,4 @@ function wireTokenSearchFields(root, {
 
 export { wireTokenSearchFields };
 
-//# sourceMappingURL=chunk-PKL6QJKK.js.map
+//# sourceMappingURL=chunk-CR5U5FV6.js.map