@kerfjs/ui 5.0.0-beta.17 → 5.0.0-beta.18

package/ai/component-catalog.schema.json

@@ -40,11 +40,26 @@
         "accessibility": { "type": "array", "items": { "type": "string" } },
         "publicClasses": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
         "publicTokens": { "type": "array", "items": { "type": "string" }, "uniqueItems": true },
+        "geometry": { "$ref": "#/$defs/geometry" },
         "delivery": { "$ref": "#/$defs/delivery" },
         "links": { "$ref": "#/$defs/links" }
       },
       "additionalProperties": false
     },
+    "geometry": {
+      "type": "object",
+      "required": ["margin", "border", "padding"],
+      "properties": {
+        "margin": { "$ref": "#/$defs/geometryOwner" },
+        "border": { "$ref": "#/$defs/geometryOwner" },
+        "padding": { "$ref": "#/$defs/geometryOwner" },
+        "notes": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }
+      },
+      "additionalProperties": false
+    },
+    "geometryOwner": {
+      "enum": ["self", "parent", "child", "none", "conditional"]
+    },
     "alternative": {
       "type": "object",
       "required": ["id", "relationship"],

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.17` and `kerfjs@5.0.0-beta.17`. 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.18` and `kerfjs@5.0.0-beta.18`. This bounded reference covers only APIs used by the seven-task corpus. It is interface evidence, not an implementation or runtime guarantee.
 
 ## `@kerfjs/ui/disclosure-arrow`
 
@@ -34,7 +34,7 @@ interface ToolbarProps {
     divider?: boolean;
     className?: string;
 }
-declare function Toolbar({ leading, center, trailing, label, divider, className }: ToolbarProps): SafeHtml;
+declare function Toolbar({ leading, center, trailing, label, divider, className, }: ToolbarProps): SafeHtml;
 
 export { Toolbar, type ToolbarProps };
 ```
@@ -100,7 +100,7 @@ interface ToolbarControlGroupProps {
     /** Corner shape: fully round `pill` (default) or a softer `rounded` rectangle. */
     shape?: 'pill' | 'rounded';
 }
-declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape }: ToolbarControlGroupProps): SafeHtml;
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, }: ToolbarControlGroupProps): SafeHtml;
 
 export { ToolbarControlGroup, type ToolbarControlGroupProps };
 ```
@@ -133,7 +133,7 @@ interface FloatingToolbarProps {
  * top toolbar's own inset); override that token to move it. The app owns the
  * controls and their behavior — wire them with `delegate()` as usual.
  */
-declare function FloatingToolbar({ children, label, position, className }: FloatingToolbarProps): SafeHtml;
+declare function FloatingToolbar({ children, label, position, className, }: FloatingToolbarProps): SafeHtml;
 
 export { FloatingToolbar, type FloatingToolbarPosition, type FloatingToolbarProps };
 ```
@@ -181,7 +181,7 @@ type ListHeaderIndicatorProps = {
     badge?: SafeHtml;
 };
 type ListHeaderProps = ListHeaderBaseProps & ListHeaderIndicatorProps;
-declare function ListHeader({ label, count, countLabel, badge, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes }: ListHeaderProps): SafeHtml;
+declare function ListHeader({ label, count, countLabel, badge, action, actionLabel, actionIcon, actionDisabled, disabledReason, expanded, toggle, placeholder, rootAttributes, triggerAttributes, }: ListHeaderProps): SafeHtml;
 
 export { ListHeader, type ListHeaderProps };
 ```
@@ -238,7 +238,7 @@ interface ListActionRowProps {
     rootAttributes?: ListActionRowRootAttributes;
     trailingActionAttributes?: ListActionRowTrailingAttributes;
 }
-declare function ListActionRow({ label, icon, action, itemId, selected, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, trailingAction, trailingActionLabel, trailingActionIcon, trailingActionDisabled, trailingActionTitle, className, style, rootAttributes, trailingActionAttributes }: ListActionRowProps): SafeHtml;
+declare function ListActionRow({ label, icon, action, itemId, selected, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, trailingAction, trailingActionLabel, trailingActionIcon, trailingActionDisabled, trailingActionTitle, className, style, rootAttributes, trailingActionAttributes, }: ListActionRowProps): SafeHtml;
 
 export { ListActionRow, type ListActionRowProps };
 ```
@@ -276,7 +276,7 @@ interface ListItemProps {
     placeholder?: boolean;
     rootAttributes?: ListItemRootAttributes;
 }
-declare function ListItem({ label, icon, trailing, selected, action, itemId, className, style, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, rootAttributes }: ListItemProps): SafeHtml;
+declare function ListItem({ label, icon, trailing, selected, action, itemId, className, style, pressed, accessibleLabel, title, multiline, state, disabled, tabIndex, placeholder, rootAttributes, }: ListItemProps): SafeHtml;
 
 export { ListItem, type ListItemProps };
 ```
@@ -297,7 +297,7 @@ interface ListInsetControlProps {
  * Use it for controls that carry their own border and padding but no outer margin
  * — the wrapper adds only the alignment margin and layout, not a second inset.
  */
-declare function ListInsetControl({ children, className }: ListInsetControlProps): SafeHtml;
+declare function ListInsetControl({ children, className, }: ListInsetControlProps): SafeHtml;
 
 export { ListInsetControl, type ListInsetControlProps };
 ```
@@ -327,7 +327,7 @@ interface ListInsetTextProps {
  * Pass `horizontalOnly` to keep the horizontal inset but drop the vertical box
  * space for tight text layout.
  */
-declare function ListInsetText({ children, horizontalOnly, className }: ListInsetTextProps): SafeHtml;
+declare function ListInsetText({ children, horizontalOnly, className, }: ListInsetTextProps): SafeHtml;
 
 export { ListInsetText, type ListInsetTextProps };
 ```
@@ -368,7 +368,7 @@ interface PanelHeaderProps {
  * is passed straight into the toolbar's trailing zone; the app supplies whatever
  * trailing controls it needs (typically a `ToolbarControlGroup`).
  */
-declare function PanelHeader({ title, titleId, summary, summaryId, icon, iconClassName, actions, headingLevel, placeholder }: PanelHeaderProps): SafeHtml;
+declare function PanelHeader({ title, titleId, summary, summaryId, icon, iconClassName, actions, headingLevel, placeholder, }: PanelHeaderProps): SafeHtml;
 
 export { PanelHeader, type PanelHeaderProps };
 ```
@@ -386,14 +386,14 @@ interface ValueTableRowProps {
     /** Render the value as an unanimated loading skeleton, keeping the field label. */
     placeholder?: boolean;
 }
-declare function ValueTableRow({ label, value, icon, className, placeholder }: ValueTableRowProps): SafeHtml;
+declare function ValueTableRow({ label, value, icon, className, placeholder, }: ValueTableRowProps): SafeHtml;
 
 interface ValueTableProps {
     label: string;
     className?: string;
     children: SafeHtml | readonly SafeHtml[];
 }
-declare function ValueTable({ label, className, children }: ValueTableProps): SafeHtml;
+declare function ValueTable({ label, className, children, }: ValueTableProps): SafeHtml;
 
 export { ValueTable, type ValueTableProps, ValueTableRow, type ValueTableRowProps };
 ```
@@ -428,7 +428,7 @@ interface AppTabProps {
     placeholder?: boolean;
     rootAttributes?: AppTabRootAttributes;
 }
-declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, closeIcon, selectAction, closeAction, className, placeholder, rootAttributes }: AppTabProps): SafeHtml;
+declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, closeIcon, selectAction, closeAction, className, placeholder, rootAttributes, }: AppTabProps): SafeHtml;
 
 export { AppTab, type AppTabProps };
 ```
@@ -454,7 +454,7 @@ interface TabBarProps {
     activation?: 'automatic' | 'manual';
 }
 /** Render a controlled tab strip. The application owns selection, order, and persistence. */
-declare function TabBar({ id, label, children, leading, trailing, className, activation }: TabBarProps): SafeHtml;
+declare function TabBar({ id, label, children, leading, trailing, className, activation, }: TabBarProps): SafeHtml;
 
 export { TabBar, type TabBarProps };
 ```
@@ -532,7 +532,7 @@ interface NavStackProps {
  * cross-fades the chrome across a change. A single-pane layout is a `NavStack`
  * with one entry. See `docs/23-app-layouts.md` §3.1.
  */
-declare function NavStack({ id, label, views, backLabel, hideToolbar, bottomToolbar, className }: NavStackProps): SafeHtml;
+declare function NavStack({ id, label, views, backLabel, hideToolbar, bottomToolbar, className, }: NavStackProps): SafeHtml;
 
 export { NavStack, type NavStackProps, type NavStackView };
 ```
@@ -599,7 +599,7 @@ interface SplitViewProps {
  * resizable wiring with `wireResizableRegions` and the compact back with
  * `wireNavStack`.
  */
-declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, resizable, className }: SplitViewProps): SafeHtml;
+declare function SplitView({ id, label, list, detail, compact, detailActive, listTitle, detailTitle, backLabel, resizable, className, }: SplitViewProps): SafeHtml;
 
 export { SplitView, type SplitViewProps, type SplitViewResizable };
 ```
@@ -637,7 +637,7 @@ interface WorkbenchProps {
  * work area relayouts once, not per frame. The app owns each `collapsed` flag;
  * the collapse is pure CSS (no wire). See `docs/23-app-layouts.md` §3.3.
  */
-declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className }: WorkbenchProps): SafeHtml;
+declare function Workbench({ id, label, main, leftRail, rightRail, bottomDrawer, className, }: WorkbenchProps): SafeHtml;
 
 export { Workbench, type WorkbenchPanel, type WorkbenchProps };
 ```
@@ -682,7 +682,7 @@ interface CollapsiblePanelToggleProps {
  * put it in the panel's own header (to collapse) and somewhere always-visible
  * (to expand while collapsed).
  */
-declare function CollapsiblePanelToggle({ side, collapsed, action, panelId, label, className }: CollapsiblePanelToggleProps): SafeHtml;
+declare function CollapsiblePanelToggle({ side, collapsed, action, panelId, label, className, }: CollapsiblePanelToggleProps): SafeHtml;
 interface CollapsiblePanelProps {
     /** A stable id for the panel — `wireSidebar` targets it and toggles reference it. */
     id: string;
@@ -708,7 +708,7 @@ interface CollapsiblePanelProps {
  * and persistence semantics, and with `CollapsiblePanelToggle` for the standard
  * affordance. See `docs/24-collapsible-panel.md`.
  */
-declare function CollapsiblePanel({ id, side, collapsed, size, label, children, className }: CollapsiblePanelProps): SafeHtml;
+declare function CollapsiblePanel({ id, side, collapsed, size, label, children, className, }: CollapsiblePanelProps): SafeHtml;
 
 export { CollapsiblePanel, type CollapsiblePanelProps, type CollapsiblePanelSide, CollapsiblePanelToggle, type CollapsiblePanelToggleProps, collapsiblePanelToggleIcon };
 ```
@@ -791,7 +791,7 @@ interface TabScaffoldProps {
  * On larger classes, promote the tabs to a `Workbench` rail or sidebar instead of
  * a bottom bar. See `docs/23-app-layouts.md` §3.4.
  */
-declare function TabScaffold({ id, label, tabs, active, className }: TabScaffoldProps): SafeHtml;
+declare function TabScaffold({ id, label, tabs, active, className, }: TabScaffoldProps): SafeHtml;
 
 export { TabScaffold, type TabScaffoldProps, type TabScaffoldTab };
 ```
@@ -835,7 +835,7 @@ interface ResizableRegionProps {
 }
 declare const clampRegionSize: (size: number, min: number, max: number) => number;
 declare const resizeRegionFromPointer: (startSize: number, delta: number, edge: ResizableRegionEdge) => number;
-declare function ResizableRegion({ id, label, size, min, max, axis, edge, collapsed, transitioning, handleIcon, children }: ResizableRegionProps): SafeHtml;
+declare function ResizableRegion({ id, label, size, min, max, axis, edge, collapsed, transitioning, handleIcon, children, }: ResizableRegionProps): SafeHtml;
 
 export { ResizableRegion, type ResizableRegionAxis, type ResizableRegionEdge, type ResizableRegionProps, clampRegionSize, resizeRegionFromPointer };
 ```
@@ -855,7 +855,7 @@ interface WireResizableRegionsOptions {
     onCommit: (change: ResizeCommit) => void;
 }
 /** Wire pointer and separator-keyboard behavior for every ResizableRegion below root. */
-declare function wireResizableRegions(root: HTMLElement, { step, largeStep, onPreview, onCommit }: WireResizableRegionsOptions): () => void;
+declare function wireResizableRegions(root: HTMLElement, { step, largeStep, onPreview, onCommit, }: WireResizableRegionsOptions): () => void;
 
 export { type ResizeCommit, type WireResizableRegionsOptions, wireResizableRegions };
 ```
@@ -998,6 +998,13 @@ interface CatalogProps {
     sidebarFooter?: SafeHtml;
     /** Status line content shown at the start of the detail footer. */
     status?: SafeHtml;
+    /**
+     * Whether to highlight transparent specimens' outer bounds and non-zero
+     * margins. Pass a boolean (rather than omitting the prop) when the active
+     * entry can switch between component and composition previews;
+     * `wireCatalogGeometryOverlay` keeps the overlay synchronized.
+     */
+    geometryOverlay?: boolean;
     selectAction?: string;
     toggleSidebarAction?: string;
     toggleThemeAction?: string;
@@ -1013,7 +1020,7 @@ interface CatalogProps {
  * `collapsed`, and `theme` signals and computes `content` from `active` in its own
  * render; wire the sidebar/collapse/theme actions with `wireCatalog`.
  */
-declare function Catalog({ brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, className, }: CatalogProps): SafeHtml;
+declare function Catalog({ brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, className, }: CatalogProps): SafeHtml;
 /**
  * How a {@link CatalogExample}'s content aligns its visible left edge with the
  * example's `ListHeader` label (which sits 16px in — 8px title + 8px label):
@@ -1040,7 +1047,7 @@ interface CatalogExampleProps {
  * `--kui-catalog-example-align` custom property so a debug overlay can exclude it
  * from a specimen's measured margin.
  */
-declare function CatalogExample({ label, note, align, className, children }: CatalogExampleProps): SafeHtml;
+declare function CatalogExample({ label, note, align, className, children, }: CatalogExampleProps): SafeHtml;
 interface CatalogExampleStackProps {
     /** Accessible label for the stack region. */
     label?: string;
@@ -1048,7 +1055,7 @@ interface CatalogExampleStackProps {
     children?: SafeHtml | readonly SafeHtml[];
 }
 /** A vertically-stacked group of {@link CatalogExample}s with the catalog's example rhythm. */
-declare function CatalogExampleStack({ label, className, children }: CatalogExampleStackProps): SafeHtml;
+declare function CatalogExampleStack({ label, className, children, }: CatalogExampleStackProps): SafeHtml;
 
 export { Catalog, type CatalogBrand, type CatalogEntry, CatalogExample, type CatalogExampleAlign, type CatalogExampleProps, CatalogExampleStack, type CatalogExampleStackProps, type CatalogProps, type CatalogRelated, type CatalogResource, type CatalogSecondaryGroup, type CatalogSection };
 ```
@@ -1067,11 +1074,40 @@ interface WireCatalogOptions {
     onToggleSecondary?: () => void;
     /** When set, `?<urlParam>=<id>` is written on select via `history.replaceState`. */
     urlParam?: string;
+    /**
+     * Reveal the chosen sidebar row after selection. `true` uses desktop-safe
+     * defaults; pass options to customize scroll alignment or the media guard.
+     */
+    revealSelection?: boolean | CatalogRevealOptions;
     selectAction?: string;
     toggleSidebarAction?: string;
     toggleThemeAction?: string;
     toggleSecondaryAction?: string;
 }
+interface CatalogRevealOptions {
+    /** Scroll alignment within the sidebar. Default `'nearest'`. */
+    block?: ScrollLogicalPosition;
+    /** Cross-axis alignment. Default `'nearest'`. */
+    inline?: ScrollLogicalPosition;
+    /** Scroll behavior. Default `'auto'`. */
+    behavior?: ScrollBehavior;
+    /**
+     * Only reveal when this media query matches. Defaults to the Catalog's
+     * desktop layout; pass `false` to reveal at every viewport size.
+     */
+    media?: string | false;
+}
+/**
+ * Reveal one Catalog sidebar entry after the controlled render settles without
+ * moving focus. Returns a cancellation function for rapid selection changes.
+ */
+declare function revealCatalogEntry(root: HTMLElement, id: string, { block, inline, behavior, media, }?: CatalogRevealOptions): () => void;
+/**
+ * Keep a Catalog's opt-in geometry overlay synchronized with its preview.
+ * Transparent specimens receive a dashed outer bound and positive margins use
+ * devtools-style orange bands. Returns a disposer.
+ */
+declare function wireCatalogGeometryOverlay(root: HTMLElement): () => void;
 /**
  * Wire a {@link Catalog}'s interactions with one delegated listener set: sidebar
  * item selection (and the related-entry popup menu), the sidebar collapse toggle, and
@@ -1079,9 +1115,9 @@ interface WireCatalogOptions {
  * them in the callbacks; optionally mirror the active id into the URL via `urlParam`.
  * Returns a disposer.
  */
-declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, }: WireCatalogOptions): () => void;
+declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, }: WireCatalogOptions): () => void;
 
-export { type WireCatalogOptions, wireCatalog };
+export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry, wireCatalog, wireCatalogGeometryOverlay };
 ```
 
 ## `@kerfjs/ui/segmented-control`
@@ -1136,7 +1172,7 @@ interface StateBannerProps {
     /** Render the title and detail as unanimated loading skeletons, keeping the icon and tone. */
     placeholder?: boolean;
 }
-declare function StateBanner({ title, detail, icon, action, tone, urgency, className, placeholder }: StateBannerProps): SafeHtml;
+declare function StateBanner({ title, detail, icon, action, tone, urgency, className, placeholder, }: StateBannerProps): SafeHtml;
 
 export { StateBanner, type StateBannerProps, type StateBannerTone };
 ```
@@ -1154,7 +1190,7 @@ interface EmptyStateProps {
     busy?: boolean;
     className?: string;
 }
-declare function EmptyState({ title, detail, icon, action, busy, className }: EmptyStateProps): SafeHtml;
+declare function EmptyState({ title, detail, icon, action, busy, className, }: EmptyStateProps): SafeHtml;
 
 export { EmptyState, type EmptyStateProps };
 ```
@@ -1198,7 +1234,7 @@ interface SkeletonProps {
  * `placeholder` prop. Decorative by default (`aria-hidden`); pass `label` to
  * announce it. Sizes to its slot unless `width`/`height` are given.
  */
-declare function Skeleton({ width, height, radius, lines, label, className }: SkeletonProps): kerfjs.SafeHtml;
+declare function Skeleton({ width, height, radius, lines, label, className, }: SkeletonProps): kerfjs.SafeHtml;
 
 export { Skeleton, type SkeletonProps };
 ```
@@ -1357,7 +1393,7 @@ interface TokenSearchFieldsHandle {
  * expand/collapse/focus. Returns a {@link TokenSearchFieldsHandle} — a disposer that also
  * exposes the managed `expanded` state per field id.
  */
-declare function wireTokenSearchFields(root: HTMLElement, { onSubmit, onEdit, collapsible, keyboard }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
+declare function wireTokenSearchFields(root: HTMLElement, { onSubmit, onEdit, collapsible, keyboard, }?: WireTokenSearchFieldsOptions): TokenSearchFieldsHandle;
 
 export { type TokenSearchCollapsibleOptions, type TokenSearchEdit, type TokenSearchFieldsHandle, type TokenSearchKeyboardOptions, type TokenSearchSubmit, type TokenSearchTokenRemoval, type WireTokenSearchFieldsOptions, wireTokenSearchFields };
 ```

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.34.0
+kerf-ui-skill-version: 1.36.0
 ---
 
 # Building with @kerfjs/ui
@@ -15,9 +15,18 @@ return values, and supported import paths; do not infer them from examples.
 Read `../docs/webawesome-theme.md` when using Web Awesome components or changing
 shared theme tokens.
 
+Before choosing or aligning components, look for a consumer-owned catalog that
+conforms to `./component-catalog-extension.schema.json`. Treat its entries as a
+second, package-qualified input beside `./component-catalog.json`: search both,
+preserve their source identity, and use the shared `geometry` vocabulary across
+their composition boundary. When a consuming project has reusable visual
+components but no extension, generate and maintain one from
+`../docs/examples/component-catalog-extension.json`; do not infer their geometry
+from rendered appearance alone.
+
 Choose from the need, not from visual resemblance:
 
-1. Search the Kerf catalog and preferred Web Awesome subset.
+1. Search the consumer extension first, then the Kerf catalog and preferred Web Awesome subset.
 2. Reuse a primitive when purpose, anatomy, state, and interaction match.
 3. Compose primitives for recurring layout. Prefer public props and tokens; use only cataloged `publicClasses` when composition-specific CSS needs a selector.
 4. Add a thin application adapter for copy, domain mapping, actions, routing, persistence, permissions, and transport.
@@ -25,25 +34,25 @@ Choose from the need, not from visual resemblance:
 
 Quick routing:
 
-| Need | Choose | Nearest alternatives / boundary |
-| --- | --- | --- |
-| Navigation row | `ListItem` | Use an ordinary link or button when sidebar/menu anatomy and state do not apply. Multiline leading icons stay aligned with the first text line. |
-| Navigation row with a trailing action | `ListActionRow` | Use `ListItem` when the trailing region is dormant; never put controls inside either component's SafeHtml slots. Multiline leading icons stay aligned with the first text line. |
-| Page, panel, or dialog heading | `Toolbar` or `PanelHeader` | Toolbar is persistent chrome; `PanelHeader` heads a panel, dialog, or page. |
-| Exclusive choice | `TabBar`, `SegmentedControl`, or `Select` | Tabs switch tabpanels; segments expose a few choices; Select handles a longer value list. |
-| Status or absent content | `StateBanner` or `EmptyState` | Web Awesome callouts suit ecosystem content; toasts are transient and never the only record of important state. |
-| Loading placeholder | a component's `placeholder` prop, or `Skeleton` | Set `placeholder` on a value-bearing component (`Select`, `ListHeader`, `ListItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `ListActionRow`) to render its real chrome with value slots as subtle **unanimated** skeletons and interactivity disabled — do not hand-rebuild an empty state. `Skeleton` is the standalone block for a custom slot. Use `LoadingSpinner` for known busy activity, not a skeleton; never animate a skeleton; prefer it over `wa-skeleton`. |
-| Adjustable or static columns | `ResizableRegion` or CSS grid | Use the component only for a user-operable controlled separator. |
-| Structured or ordinary search | `TokenSearchField` or an input | Use token search only when text and ordered filter chips form one editor. |
-| Key/value facts | `ValueTable` with `ValueTableRow` | Use rows with `icon` only when the optional 24px leading visual adds context. |
-| Command search | Application-local semantics using shared layout vocabulary | No runtime component or production recipe is exported; the app owns behavior, policy, and copy. |
+| Need                                  | Choose                                                     | Nearest alternatives / boundary                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Navigation row                        | `ListItem`                                                 | Use an ordinary link or button when sidebar/menu anatomy and state do not apply. Multiline leading icons stay aligned with the first text line.                                                                                                                                                                                                                                                                                                                                                                             |
+| Navigation row with a trailing action | `ListActionRow`                                            | Use `ListItem` when the trailing region is dormant; never put controls inside either component's SafeHtml slots. Multiline leading icons stay aligned with the first text line.                                                                                                                                                                                                                                                                                                                                             |
+| Page, panel, or dialog heading        | `Toolbar` or `PanelHeader`                                 | Toolbar is persistent chrome; `PanelHeader` heads a panel, dialog, or page.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Exclusive choice                      | `TabBar`, `SegmentedControl`, or `Select`                  | Tabs switch tabpanels; segments expose a few choices; Select handles a longer value list.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Status or absent content              | `StateBanner` or `EmptyState`                              | Web Awesome callouts suit ecosystem content; toasts are transient and never the only record of important state.                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Loading placeholder                   | a component's `placeholder` prop, or `Skeleton`            | Set `placeholder` on a value-bearing component (`Select`, `ListHeader`, `ListItem`, `ValueTableRow`, `PanelHeader`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `ListActionRow`) to render its real chrome with value slots as subtle **unanimated** skeletons and interactivity disabled — do not hand-rebuild an empty state. `Skeleton` is the standalone block for a custom slot. Use `LoadingSpinner` for known busy activity, not a skeleton; never animate a skeleton; prefer it over `wa-skeleton`. |
+| Adjustable or static columns          | `ResizableRegion` or CSS grid                              | Use the component only for a user-operable controlled separator.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Structured or ordinary search         | `TokenSearchField` or an input                             | Use token search only when text and ordered filter chips form one editor.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| Key/value facts                       | `ValueTable` with `ValueTableRow`                          | Use rows with `icon` only when the optional 24px leading visual adds context.                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Command search                        | Application-local semantics using shared layout vocabulary | No runtime component or production recipe is exported; the app owns behavior, policy, and copy.                                                                                                                                                                                                                                                                                                                                                                                                                             |
 
 For a complete shell, sidebar, workspace header, list-detail dialog, composer
 form, list-state lifecycle, or mixed-control toolbar, start from the runnable
 reference in [`docs/recipes.md`](../docs/recipes.md). Preserve its production
 primitives and semantic ownership; replace application state, policy, and copy.
 
-The concise human decision matrix is in [`component-selection.md`](../docs/component-selection.md). For exhaustive tool retrieval, load [`component-catalog.json`](./component-catalog.json), the canonical metadata for every public component/helper, composition, and supported Web Awesome entry. Use its linked current recipes instead of inferring behavior from CSS.
+The concise human decision matrix is in [`component-selection.md`](../docs/component-selection.md). For exhaustive tool retrieval, load [`component-catalog.json`](./component-catalog.json), the canonical metadata for every public component/helper, composition, and supported Web Awesome entry. Its `geometry` object identifies who owns margin, border, and padding; use that contract to avoid double-insetting or wrapping an already complete surface. Use its linked current recipes instead of inferring behavior from CSS.
 
 Hard rules:
 
@@ -58,44 +67,44 @@ Hard rules:
 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. 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. Arrow/Home/End select on move by default; 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. The leading icon, first text line, clear action, and trailing slot share one fixed row when content wraps. 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. 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, or a clear-button mousedown guard — the helper owns them. 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.
-12. Demo work uses public production component subpaths and their browser-selected CSS. 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. Project its 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.
+12. Demo work uses public production component subpaths and their browser-selected CSS. 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. Project its 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. For focused component previews, pass `geometryOverlay={true}` to `Catalog` so transparent bounds and positive margins remain inspectable; disable it for compositions, and use the catalog's machine-readable `geometry` ownership to interpret the result instead of treating every visible inset as component-owned. 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); override those tiers instead of restyling individual 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.
 14. Treat the complete Web Awesome catalog as support coverage, not a recommendation list. Its UX sidebar marks superseded and exceptional entries `Discouraged`. Consider Popup when it replaces custom anchored positioning. Prefer Kerf `Select` over direct Dropdown/Dropdown Item/Select/Option composition, `SegmentedControl` over Button Group, `TabBar` or `SegmentedControl` over Web Awesome Tabs, `LucideIcon` over Web Awesome Icon, and `ResizableRegion` over Split Panel. Use Tree/Tree Item, Animated Image, and Comparison only for a specific required behavior; avoid Zoomable Frame.
 15. Build sidebars, main areas, inspectors, and dialogs from `@kerfjs/ui/layout.css`: an unpadded `.kui-pane`, optional `.kui-pane__toolbar`, one scrolling `.kui-pane__content`, and optional `.kui-pane__footer`. Add `.kui-content` for 24px major vertical separation and `.kui-content-item` for a child-owned 8px inline margin, 1px transparent-or-visible border, 8px padding, and 12px radius. Use the pill modifier for 22px. Do not pad pane shells or duplicate item geometry in wrappers.
 16. Keep a visible collapsible pane's collapse control in its own toolbar. When hidden, move its restore control into the adjacent main toolbar on the corresponding logical edge: leading for an inline-start sidebar and trailing for an inline-end inspector. Collapse the pane completely; do not preserve an empty icon-only rail.
-16. The only direct children of a `Toolbar` zone (`leading`/`center`/`trailing`) are `ToolbarText` (identity/title text) and `ToolbarControlGroup`; never drop bare buttons, inputs, links, or arbitrary markup straight into a zone. `SegmentedControl`, `Select`, a collapsible `TokenSearchField`, and Web Awesome controls all live inside a `ToolbarControlGroup`. For an ordinary icon/action control inside a group, use a plain `<button>` (the group styles `> button` fully) — that is the default; reach for `wa-button` only when you need a Web Awesome feature, chiefly a `wa-dropdown` popup trigger. A popup menu in a toolbar is a `single` `ToolbarControlGroup` wrapping a `wa-dropdown` whose `slot="trigger"` `wa-button` is the toolbar button and whose `wa-dropdown-item`s are the menu, with the dropdown kept under `data-morph-skip-children`. `PanelHeader` composes these for you as a panel/dialog/page heading. Wrap every toolbar item, including dormant text, in `ToolbarControlGroup`. A group remains 44px outside (`calc(2px + remify(42px))`) when its border/background are transparent; use 8px between groups and inside items. Split dormant and interactive regions: `ListHeader` fills the available inline width and keeps its label and mutually exclusive semantic count or non-count `badge` together, with an independent logical-end 44px action unless disclosure mode makes the title cluster the button. Its action visual defaults to 18px through `--kui-list-header-action-icon-size`; never shrink the target to match it. Pass every non-negative safe-integer section quantity through `count` with a localized full spoken `countLabel`; never concatenate it into `label` or put a number in `badge`. `ListItem.trailing` is dormant; use `ListActionRow` when primary and trailing actions need sibling 44px native buttons. Its `label`, `icon`, and `trailingActionIcon` slots are also dormant and cannot contain controls. Let panes relocate at narrow widths instead of shrinking targets.
-17. When a recurring concept has no matching export or production recipe, keep its semantics in a thin application adapter while reusing the public layout vocabulary. The composer recipe uses one visible form surface, `PanelHeader` title/summary ids, shared 8px field/action gutters, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface; do not turn every section into a card or double-inset intrinsically bordered controls. The application-local `../docs/examples/command-palette-adapter.tsx` is reference source for one such missing concept, not an `@kerfjs/ui` runtime export or catalog recipe. The application owns its registration, ranking, history, permissions, availability, shortcut policy, focus policy, dispatch, and copy. If a missing concept recurs across products, open an upstream component or recipe request.
-18. Compose `ValueTable` from typed `ValueTableRow` entries instead of handwritten `dt`/`dd` wrappers. Pass `icon` for the optional 24px leading visual; the row owns 8px of root-scaled top and bottom padding, the 8px iconless or 40px icon-bearing separator start, and the common 8px right inset.
-19. Use `PanelHeader` for a panel, dialog, or page heading, not a custom heading row. It is a plain top `Toolbar` (overriding no Toolbar styles): the leading zone holds an optional icon (a normal bordered `ToolbarControlGroup` given a brand fill with a matching border) and the title as extra-large `ToolbarText`; the app's trailing controls (typically a `ToolbarControlGroup`) go straight in the trailing zone, and the icon group is omitted when no icon is passed. Its optional `summary`/`summaryId` row stays below the title. The app owns modal behavior, focus, dismissal, command policy, and action handling.
-20. Space with the official five-step scale, picked by how connected two elements are — not by eye. `0` `--kui-space-none` = no separation (one unit); `4px` `--kui-space-2xs` = very minor air on a connected cluster; `8px` `--kui-space-xs` = standard, between elements within a group; `16px` `--kui-space-m` = minor, between homogeneous groups; `24px` `--kui-space-l` = major, between heterogeneous groups (the `.kui-content` rhythm). The 8px-vs-24px distinction is inside-a-group vs between-major-differing-regions. `--kui-space-s` (12px) and `--kui-space-xl` (32px) are off-scale exceptions; prefer the five canonical remify-authored tokens. See `docs/layout.md` "Spacing scale".
-21. Pick a whole-screen layout from the opt-in, tree-shakeable subpaths by data + interaction + device, and derive responsiveness from `@kerfjs/ui/device-class`'s `deviceClass()` (`compact` = handset or portrait tablet = one pane at a time). Simple/flat → `NavStack` with one entry (single pane), plus `TabScaffold` (`@kerfjs/ui/tab-scaffold`, iOS bottom tabs, each tab its own `NavStack`) for 2–5 co-equal sections on `compact`. Drill-down → `NavStack` (`@kerfjs/ui/nav-stack`), upgrading to `SplitView` (`@kerfjs/ui/split-view`, list-detail) once both panes fit (`atLeast('tablet')` landscape); `SplitView` collapses to a `NavStack` on `compact`. Complex tool with peripheral panels → `Workbench` (`@kerfjs/ui/workbench`, collapsible rails + drawer) `atLeast('desktop')`, degrading to `NavStack`/overlays below. These are declarative (the app owns the stack/selection/collapsed/active state as signals) with disposer-returning `wire…` helpers; each ships a companion CSS import and stays out of the barrel. For a standalone collapsible rail or bottom drawer outside a full shell, use `CollapsiblePanel` + `CollapsiblePanelToggle` (`@kerfjs/ui/collapsible-panel`) with `wireSidebar` (`@kerfjs/ui/wire-sidebar`): the standard collapse animation and per-side icon convention (`PanelLeft*`/`PanelRight*`/`PanelBottom*`) plus toggle, focus, compact overlay, and persistence semantics. Dialogs pick the same inner layout, then present per device class (full-screen modal on `compact`, inline on desktop). See `docs/app-layouts.md` and `docs/collapsible-panel.md`.
+17. The only direct children of a `Toolbar` zone (`leading`/`center`/`trailing`) are `ToolbarText` (identity/title text) and `ToolbarControlGroup`; never drop bare buttons, inputs, links, or arbitrary markup straight into a zone. `SegmentedControl`, `Select`, a collapsible `TokenSearchField`, and Web Awesome controls all live inside a `ToolbarControlGroup`. For an ordinary icon/action control inside a group, use a plain `<button>` (the group styles `> button` fully) — that is the default; reach for `wa-button` only when you need a Web Awesome feature, chiefly a `wa-dropdown` popup trigger. A popup menu in a toolbar is a `single` `ToolbarControlGroup` wrapping a `wa-dropdown` whose `slot="trigger"` `wa-button` is the toolbar button and whose `wa-dropdown-item`s are the menu, with the dropdown kept under `data-morph-skip-children`. `PanelHeader` composes these for you as a panel/dialog/page heading. Wrap every toolbar item, including dormant text, in `ToolbarControlGroup`. A group remains 44px outside (`calc(2px + remify(42px))`) when its border/background are transparent; use 8px between groups and inside items. Split dormant and interactive regions: `ListHeader` fills the available inline width and keeps its label and mutually exclusive semantic count or non-count `badge` together, with an independent logical-end 44px action unless disclosure mode makes the title cluster the button. Its action visual defaults to 18px through `--kui-list-header-action-icon-size`; never shrink the target to match it. Pass every non-negative safe-integer section quantity through `count` with a localized full spoken `countLabel`; never concatenate it into `label` or put a number in `badge`. `ListItem.trailing` is dormant; use `ListActionRow` when primary and trailing actions need sibling 44px native buttons. Its `label`, `icon`, and `trailingActionIcon` slots are also dormant and cannot contain controls. Let panes relocate at narrow widths instead of shrinking targets.
+18. When a recurring concept has no matching export or production recipe, keep its semantics in a thin application adapter while reusing the public layout vocabulary. The composer recipe uses one visible form surface, `PanelHeader` title/summary ids, shared 8px field/action gutters, 24px major rhythm, and a conditional StateBanner as its only nested semantic surface; do not turn every section into a card or double-inset intrinsically bordered controls. The application-local `../docs/examples/command-palette-adapter.tsx` is reference source for one such missing concept, not an `@kerfjs/ui` runtime export or catalog recipe. The application owns its registration, ranking, history, permissions, availability, shortcut policy, focus policy, dispatch, and copy. If a missing concept recurs across products, open an upstream component or recipe request.
+19. Compose `ValueTable` from typed `ValueTableRow` entries instead of handwritten `dt`/`dd` wrappers. Pass `icon` for the optional 24px leading visual; the row owns 8px of root-scaled top and bottom padding, the 8px iconless or 40px icon-bearing separator start, and the common 8px right inset.
+20. Use `PanelHeader` for a panel, dialog, or page heading, not a custom heading row. It is a plain top `Toolbar` (overriding no Toolbar styles): the leading zone holds an optional icon (a normal bordered `ToolbarControlGroup` given a brand fill with a matching border) and the title as extra-large `ToolbarText`; the app's trailing controls (typically a `ToolbarControlGroup`) go straight in the trailing zone, and the icon group is omitted when no icon is passed. Its optional `summary`/`summaryId` row stays below the title. The app owns modal behavior, focus, dismissal, command policy, and action handling.
+21. Space with the official five-step scale, picked by how connected two elements are — not by eye. `0` `--kui-space-none` = no separation (one unit); `4px` `--kui-space-2xs` = very minor air on a connected cluster; `8px` `--kui-space-xs` = standard, between elements within a group; `16px` `--kui-space-m` = minor, between homogeneous groups; `24px` `--kui-space-l` = major, between heterogeneous groups (the `.kui-content` rhythm). The 8px-vs-24px distinction is inside-a-group vs between-major-differing-regions. `--kui-space-s` (12px) and `--kui-space-xl` (32px) are off-scale exceptions; prefer the five canonical remify-authored tokens. See `docs/layout.md` "Spacing scale".
+22. Pick a whole-screen layout from the opt-in, tree-shakeable subpaths by data + interaction + device, and derive responsiveness from `@kerfjs/ui/device-class`'s `deviceClass()` (`compact` = handset or portrait tablet = one pane at a time). Simple/flat → `NavStack` with one entry (single pane), plus `TabScaffold` (`@kerfjs/ui/tab-scaffold`, iOS bottom tabs, each tab its own `NavStack`) for 2–5 co-equal sections on `compact`. Drill-down → `NavStack` (`@kerfjs/ui/nav-stack`), upgrading to `SplitView` (`@kerfjs/ui/split-view`, list-detail) once both panes fit (`atLeast('tablet')` landscape); `SplitView` collapses to a `NavStack` on `compact`. Complex tool with peripheral panels → `Workbench` (`@kerfjs/ui/workbench`, collapsible rails + drawer) `atLeast('desktop')`, degrading to `NavStack`/overlays below. These are declarative (the app owns the stack/selection/collapsed/active state as signals) with disposer-returning `wire…` helpers; each ships a companion CSS import and stays out of the barrel. For a standalone collapsible rail or bottom drawer outside a full shell, use `CollapsiblePanel` + `CollapsiblePanelToggle` (`@kerfjs/ui/collapsible-panel`) with `wireSidebar` (`@kerfjs/ui/wire-sidebar`): the standard collapse animation and per-side icon convention (`PanelLeft*`/`PanelRight*`/`PanelBottom*`) plus toggle, focus, compact overlay, and persistence semantics. Dialogs pick the same inner layout, then present per device class (full-screen modal on `compact`, inline on desktop). See `docs/app-layouts.md` and `docs/collapsible-panel.md`.
 
 Common mistakes:
 
-| Mistake | Fix |
-| --- | --- |
-| Hard-coded project/transport action in a component | Pass a semantic `data-action` string from an application adapter |
-| Per-instance signal at module scope | Create state in the application or a factory and pass it in |
-| `role="menuitem"` on one button | Use the native button, or implement the complete ARIA menu widget |
-| Put a button/link/interactive role in `ListItem.trailing` or a `ListActionRow` SafeHtml slot | Use `ListActionRow` for the sibling controls and keep its label/icon slots dormant |
-| Copy ListItem/ListHeader markup to add product data or a popover target | Use the typed `rootAttributes`/`triggerAttributes` slots and retain the component's protected semantics |
-| Concatenate a section count into a ListHeader label or numeric badge | Pass `count={value}` and a localized full phrase such as `countLabel="3 notes"`; reserve `badge` for non-count SafeHtml |
-| Put a chevron on navigation that reveals nothing | Remove it, or model a real controlled `ListHeader` disclosure; omit `actionIcon` to use the production `DisclosureArrow` |
-| Test only a custom-element attribute | Assert live property, emitted event, focus, and rendered output |
-| Import all Web Awesome components | Import only `@kerfjs/ui/select/register` for `Select`, or individual Web Awesome modules for other controls; `webawesome.css` registers no JavaScript |
-| Write `wa-*` JSX without activating its types | Add `import type {} from '@kerfjs/ui/webawesome'`; registration and theme imports remain separate |
-| Maintain a root list of component styles | Import each visual component from its JS subpath; its reachable CSS follows automatically |
-| Add demo-only markup for a production state | Add the state to the production component, then render that export in the catalog |
-| Choose a listed ecosystem component by default | Apply the component-selection guidance above; catalog coverage means supported and themed, not preferred |
-| Add sidebar-specific wrapper padding | Use the unpadded `.kui-pane`; let `ListHeader`, `ListItem`, and `.kui-content-item` own their 8/1/8 geometry |
-| Put bare text or controls directly in a toolbar slot | Wrap every item in `ToolbarControlGroup`, using `appearance="borderless"` for transparent chrome |
-| Reach for `wa-button` for a plain control inside a `ToolbarControlGroup` | Use a plain `<button>` (the group styles it fully); `wa-button` is only for Web Awesome features like a `wa-dropdown` popup trigger |
-| Let the document, pane, and list all scroll | Keep fixed chrome outside one `.kui-pane__content` scroll owner per pane |
-| Invent an `@kerfjs/ui` command-palette export | Keep the semantics application-local, reuse public layout vocabulary, and propose recurring behavior upstream |
-| Handwrite `ValueTable` row wrappers or compensate their padding or separators | Compose `ValueTableRow`; its root-scaled block padding, optional icon hook, and separator geometry are public contract |
-| Rebuild a panel/dialog heading row by hand | Use `PanelHeader`: a plain toolbar with an optional bordered icon group, an xl title, trailing controls you pass, and the optional subtitle below |
-| Force a `width`/`height`/`padding` on a component to size or space it | Let it size to its content and tokens; a forced box leaves a halo or a stretched oval — adjust an icon-size or spacing token, not the box |
-| Wrap a component or region in a card, border, backdrop, or outline to "contain" it | Let it sit on the surface; add a `.kui-content-item` only for a real distinction — hierarchy comes from alignment, spacing, and type first |
-| Add another container's padding on top of a content-item's own margin | Pick one owner of the inset; a pane has no padding and its `.kui-content` children own the 8/1/8 geometry — stacking them double-insets |
-| Keep chrome, a label, or a readout that aids no decision | Delete it; every element must help a person decide or act |
-| Override a component's default size or color because it "looks off" | Trust the default (a LucideIcon is 24px) and fix the surrounding layout instead |
+| Mistake                                                                                      | Fix                                                                                                                                                   |
+| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Hard-coded project/transport action in a component                                           | Pass a semantic `data-action` string from an application adapter                                                                                      |
+| Per-instance signal at module scope                                                          | Create state in the application or a factory and pass it in                                                                                           |
+| `role="menuitem"` on one button                                                              | Use the native button, or implement the complete ARIA menu widget                                                                                     |
+| Put a button/link/interactive role in `ListItem.trailing` or a `ListActionRow` SafeHtml slot | Use `ListActionRow` for the sibling controls and keep its label/icon slots dormant                                                                    |
+| Copy ListItem/ListHeader markup to add product data or a popover target                      | Use the typed `rootAttributes`/`triggerAttributes` slots and retain the component's protected semantics                                               |
+| Concatenate a section count into a ListHeader label or numeric badge                         | Pass `count={value}` and a localized full phrase such as `countLabel="3 notes"`; reserve `badge` for non-count SafeHtml                               |
+| Put a chevron on navigation that reveals nothing                                             | Remove it, or model a real controlled `ListHeader` disclosure; omit `actionIcon` to use the production `DisclosureArrow`                              |
+| Test only a custom-element attribute                                                         | Assert live property, emitted event, focus, and rendered output                                                                                       |
+| Import all Web Awesome components                                                            | Import only `@kerfjs/ui/select/register` for `Select`, or individual Web Awesome modules for other controls; `webawesome.css` registers no JavaScript |
+| Write `wa-*` JSX without activating its types                                                | Add `import type {} from '@kerfjs/ui/webawesome'`; registration and theme imports remain separate                                                     |
+| Maintain a root list of component styles                                                     | Import each visual component from its JS subpath; its reachable CSS follows automatically                                                             |
+| Add demo-only markup for a production state                                                  | Add the state to the production component, then render that export in the catalog                                                                     |
+| Choose a listed ecosystem component by default                                               | Apply the component-selection guidance above; catalog coverage means supported and themed, not preferred                                              |
+| Add sidebar-specific wrapper padding                                                         | Use the unpadded `.kui-pane`; let `ListHeader`, `ListItem`, and `.kui-content-item` own their 8/1/8 geometry                                          |
+| Put bare text or controls directly in a toolbar slot                                         | Wrap every item in `ToolbarControlGroup`, using `appearance="borderless"` for transparent chrome                                                      |
+| Reach for `wa-button` for a plain control inside a `ToolbarControlGroup`                     | Use a plain `<button>` (the group styles it fully); `wa-button` is only for Web Awesome features like a `wa-dropdown` popup trigger                   |
+| Let the document, pane, and list all scroll                                                  | Keep fixed chrome outside one `.kui-pane__content` scroll owner per pane                                                                              |
+| Invent an `@kerfjs/ui` command-palette export                                                | Keep the semantics application-local, reuse public layout vocabulary, and propose recurring behavior upstream                                         |
+| Handwrite `ValueTable` row wrappers or compensate their padding or separators                | Compose `ValueTableRow`; its root-scaled block padding, optional icon hook, and separator geometry are public contract                                |
+| Rebuild a panel/dialog heading row by hand                                                   | Use `PanelHeader`: a plain toolbar with an optional bordered icon group, an xl title, trailing controls you pass, and the optional subtitle below     |
+| Force a `width`/`height`/`padding` on a component to size or space it                        | Let it size to its content and tokens; a forced box leaves a halo or a stretched oval — adjust an icon-size or spacing token, not the box             |
+| Wrap a component or region in a card, border, backdrop, or outline to "contain" it           | Let it sit on the surface; add a `.kui-content-item` only for a real distinction — hierarchy comes from alignment, spacing, and type first            |
+| Add another container's padding on top of a content-item's own margin                        | Pick one owner of the inset; a pane has no padding and its `.kui-content` children own the 8/1/8 geometry — stacking them double-insets               |
+| Keep chrome, a label, or a readout that aids no decision                                     | Delete it; every element must help a person decide or act                                                                                             |
+| Override a component's default size or color because it "looks off"                          | Trust the default (a LucideIcon is 24px) and fix the surrounding layout instead                                                                       |

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.17` 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.18` 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/app-tab.d.ts

@@ -25,6 +25,6 @@ interface AppTabProps {
     placeholder?: boolean;
     rootAttributes?: AppTabRootAttributes;
 }
-declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, closeIcon, selectAction, closeAction, className, placeholder, rootAttributes }: AppTabProps): SafeHtml;
+declare function AppTab({ id, name, selected, closable, draggable, leading, trailing, closeIcon, selectAction, closeAction, className, placeholder, rootAttributes, }: AppTabProps): SafeHtml;
 
 export { AppTab, type AppTabProps };

package/dist/app-tab.js

@@ -1,4 +1,4 @@
-export { AppTab } from './chunk-2Z5TWHKQ.js';
+export { AppTab } from './chunk-PIDTEQ3U.js';
 
 
 

package/dist/catalog.d.ts

@@ -66,6 +66,13 @@ interface CatalogProps {
     sidebarFooter?: SafeHtml;
     /** Status line content shown at the start of the detail footer. */
     status?: SafeHtml;
+    /**
+     * Whether to highlight transparent specimens' outer bounds and non-zero
+     * margins. Pass a boolean (rather than omitting the prop) when the active
+     * entry can switch between component and composition previews;
+     * `wireCatalogGeometryOverlay` keeps the overlay synchronized.
+     */
+    geometryOverlay?: boolean;
     selectAction?: string;
     toggleSidebarAction?: string;
     toggleThemeAction?: string;
@@ -81,7 +88,7 @@ interface CatalogProps {
  * `collapsed`, and `theme` signals and computes `content` from `active` in its own
  * render; wire the sidebar/collapse/theme actions with `wireCatalog`.
  */
-declare function Catalog({ brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, className, }: CatalogProps): SafeHtml;
+declare function Catalog({ brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, className, }: CatalogProps): SafeHtml;
 /**
  * How a {@link CatalogExample}'s content aligns its visible left edge with the
  * example's `ListHeader` label (which sits 16px in — 8px title + 8px label):
@@ -108,7 +115,7 @@ interface CatalogExampleProps {
  * `--kui-catalog-example-align` custom property so a debug overlay can exclude it
  * from a specimen's measured margin.
  */
-declare function CatalogExample({ label, note, align, className, children }: CatalogExampleProps): SafeHtml;
+declare function CatalogExample({ label, note, align, className, children, }: CatalogExampleProps): SafeHtml;
 interface CatalogExampleStackProps {
     /** Accessible label for the stack region. */
     label?: string;
@@ -116,6 +123,6 @@ interface CatalogExampleStackProps {
     children?: SafeHtml | readonly SafeHtml[];
 }
 /** A vertically-stacked group of {@link CatalogExample}s with the catalog's example rhythm. */
-declare function CatalogExampleStack({ label, className, children }: CatalogExampleStackProps): SafeHtml;
+declare function CatalogExampleStack({ label, className, children, }: CatalogExampleStackProps): SafeHtml;
 
 export { Catalog, type CatalogBrand, type CatalogEntry, CatalogExample, type CatalogExampleAlign, type CatalogExampleProps, CatalogExampleStack, type CatalogExampleStackProps, type CatalogProps, type CatalogRelated, type CatalogResource, type CatalogSecondaryGroup, type CatalogSection };