@kerfjs/ui 5.0.0-beta.82 → 5.0.0-beta.84

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.82` and `kerfjs@5.0.0-beta.82`. 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.84` and `kerfjs@5.0.0-beta.84`. 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`
 
@@ -66,6 +66,13 @@ type UiColorName = (typeof uiColorNames)[number];
 type UiForegroundColorName = Extract<UiColorName, `${string}-on-${string}` | 'text' | 'text-quiet' | 'text-link'>;
 /** Kerf UI's complete spacing-token vocabulary. `s` and `xl` are exceptions. */
 type UiSpaceName = 'none' | '2xs' | 'xs' | 's' | 'm' | 'l' | 'xl';
+/** A token or complete typed length for one gap axis. */
+type UiGapValue = UiSpaceName | CssLength;
+/** A shared gap or independent column and row gaps. */
+type UiGap = UiGapValue | Readonly<{
+    column: UiGapValue;
+    row: UiGapValue;
+}>;
 /** Create a complete pixel length. */
 declare function px(value: number): CssLength;
 /** Create a complete root-font-relative length. */
@@ -116,7 +123,7 @@ declare function foregroundColorVar(name: `--${string}`, fallback?: CssForegroun
  */
 declare function foregroundColor(value: string): CssForegroundColor;
 
-export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, type CssForegroundColor, type CssLength, type CssLengthExpression, type CssSize, type CssSizeKeyword, type CssValue, type UiColor, type UiColorName, type UiForegroundColorName, type UiSpaceName, calc, colorVar, em, flex, foregroundColor, foregroundColorVar, lengthVar, pct, plus, px, rem, remify, space, uiColor };
+export { type CssColor, type CssFlex, type CssFlexBasis, type CssFlexKeyword, type CssForegroundColor, type CssLength, type CssLengthExpression, type CssSize, type CssSizeKeyword, type CssValue, type UiColor, type UiColorName, type UiForegroundColorName, type UiGap, type UiGapValue, type UiSpaceName, calc, colorVar, em, flex, foregroundColor, foregroundColorVar, lengthVar, pct, plus, px, rem, remify, space, uiColor };
 ```
 
 ## `@kerfjs/ui/disclosure-arrow`
@@ -651,7 +658,8 @@ import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { H as HorizontalAlignment, L as ListVerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 export { V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { S as Sides } from './sides-BPSWde0A.js';
-import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
+import { UiGap, CssFlexKeyword, CssFlex } from './css-values.js';
+export { CssLength, UiGapValue, UiSpaceName } from './css-values.js';
 
 type ListRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -670,8 +678,8 @@ interface ListProps {
     selectionMode?: 'multiple';
     /** Accessible name for the multi-select grid. */
     ariaLabel?: string;
-    /** Use the standard item gap, a named UI spacing token, or a typed CSS length. Defaults to no gap. */
-    gap?: boolean | UiSpaceName | CssLength;
+    /** Standard gap (`true`), one spacing value, or separate column and row values. Defaults to no gap. */
+    gap?: boolean | UiGap;
     /** Allow this list to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
     flex?: boolean | CssFlexKeyword | CssFlex;
     /**
@@ -708,7 +716,7 @@ type ListConfig = Pick<ListProps, 'gap' | 'hAlign' | 'vAlign' | 'dividerSides' |
 /** A stretch-aligned vertical stack with optional gap, flex, fill, scroll, and dividers. */
 declare function List({ children, selectionMode, ariaLabel, gap, flex, fill, hAlign, vAlign, scrollable, dividerSides, textInsets, controlInsets, className, rootAttributes, slot, }: ListProps): kerfjs.SafeHtml;
 
-export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, List, type ListConfig, type ListProps, ListVerticalAlignment, Sides, UiSpaceName };
+export { CssFlex, CssFlexKeyword, HorizontalAlignment, List, type ListConfig, type ListProps, ListVerticalAlignment, Sides, UiGap };
 ```
 
 ## `@kerfjs/ui/list-action-row`
@@ -1287,7 +1295,7 @@ export { type ScrollDividerTarget, type WireScrollDividersOptions, wireScrollDiv
 ## `@kerfjs/ui/nav-stack`
 
 ```ts
-export { c as NavStack, N as NavStackProps, d as NavStackToolbarConfig, a as NavStackView, e as NavStackViewBottomToolbar, f as NavStackViewToolbar } from './nav-stack-B1Qc2e5q.js';
+export { c as NavStack, N as NavStackProps, d as NavStackToolbarConfig, a as NavStackView, e as NavStackViewBottomToolbar, f as NavStackViewToolbar } from './nav-stack-BvSKY448.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
 import './list.js';
@@ -1330,7 +1338,7 @@ export { type WireNavStackOptions, wireNavStack };
 ```ts
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import { N as NavStackProps, a as NavStackView } from './nav-stack-B1Qc2e5q.js';
+import { N as NavStackProps, a as NavStackView } from './nav-stack-BvSKY448.js';
 import { ResizableRegionProps } from './resizable-region.js';
 import './list.js';
 import './flex-alignment-4ms8ZbV8.js';
@@ -1535,7 +1543,7 @@ export { Pane, type PaneAppearance, type PaneChromeDividers, type PaneChromePlac
 ```ts
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import { b as NavPane, N as NavStackProps } from './nav-stack-B1Qc2e5q.js';
+import { b as NavPane, N as NavStackProps } from './nav-stack-BvSKY448.js';
 import { ListConfig } from './list.js';
 import { PaneConfig } from './pane.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
@@ -2200,14 +2208,21 @@ interface TabNavigatorProps<Id extends string = string> {
     tabs: readonly TabNavigatorTab<Id>[];
     /** The controlled active tab id (the app owns selection). */
     active: NoInfer<Id>;
+    /**
+     * The bar's top separator. `auto` (default) draws it against a sunken active
+     * work surface and otherwise follows `chromeDividers`; `hidden` suppresses
+     * the line, including a scroll divider.
+     */
+    separator?: 'auto' | 'hidden';
     /**
      * The line over the tab bar, where it meets the active scene. `scroll`
      * (default) shows it only while more of the scene's content lies below —
      * never at the scroll end or when the content fits — once
      * `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is wired above
      * the scaffold; unwired, it does not show. `always` shows it without the
-     * wiring; `none` never, even when wired. The line is the bar's own 1px top
-     * border, so no state moves the bar or a tab.
+     * wiring; `none` suppresses that scroll divider. A sunken active work
+     * surface still draws the separator unless `separator="hidden"`. The line
+     * is the bar's own 1px top border, so no state moves the bar or a tab.
      */
     chromeDividers?: 'scroll' | 'always' | 'none';
     className?: string;
@@ -2222,7 +2237,7 @@ interface TabNavigatorProps<Id extends string = string> {
  * 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 TabNavigator<Id extends string>({ id, label, tabs, active, chromeDividers, className, slot, }: TabNavigatorProps<Id>): SafeHtml;
+declare function TabNavigator<Id extends string>({ id, label, tabs, active, separator, chromeDividers, className, slot, }: TabNavigatorProps<Id>): SafeHtml;
 
 export { TabNavigator, type TabNavigatorProps, type TabNavigatorTab };
 ```
@@ -2393,14 +2408,14 @@ export { DEFAULT_BREAKPOINTS, type DeviceBreakpoints, type DeviceClass, type Dev
 ```ts
 import * as kerfjs from 'kerfjs';
 import { SafeHtml } from 'kerfjs';
-import { a as CatalogProps } from './types-C9BubXfz.js';
-export { b as CatalogBrand, c as CatalogEntry, d as CatalogRelated, C as CatalogResource, e as CatalogSecondaryGroup, f as CatalogSection, g as CatalogStageRootAttributes } from './types-C9BubXfz.js';
+import { a as CatalogProps } from './types-Bn-dXLcs.js';
+export { b as CatalogBackgroundStyle, c as CatalogBrand, d as CatalogEntry, e as CatalogRelated, C as CatalogResource, f as CatalogSecondaryGroup, g as CatalogSection, h as CatalogStageRootAttributes } from './types-Bn-dXLcs.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import './toolbar.js';
 import './sides-BPSWde0A.js';
 import './pane.js';
 import './workbench.js';
-import './nav-stack-B1Qc2e5q.js';
+import './nav-stack-BvSKY448.js';
 import './list.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './css-values.js';
@@ -2417,7 +2432,7 @@ import './resizable-region.js';
  * standard toggle moves into the entry toolbar while it is collapsed, and on
  * a small screen the sidebar overlays the stage like any Workbench rail.
  */
-declare function Catalog({ id, brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, stageRootAttributes, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, headerPlacement, footerPlacement, sidebar, mainToolbar, footerToolbar, className, slot, }: CatalogProps): kerfjs.SafeHtml;
+declare function Catalog({ id, brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, backgroundStyle, stageRootAttributes, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, headerPlacement, footerPlacement, sidebar, mainToolbar, footerToolbar, className, slot, }: CatalogProps): kerfjs.SafeHtml;
 
 /** How a specimen aligns its visible edge with its `ListHeader` label. */
 type CatalogExampleAlign = 'glyph' | 'inline-control' | 'text-trigger' | 'none';
@@ -2488,14 +2503,14 @@ export { Catalog, CatalogExample, type CatalogExampleAlign, type CatalogExampleP
 ## `@kerfjs/ui/catalog-resources`
 
 ```ts
-import { C as CatalogResource } from './types-C9BubXfz.js';
+import { C as CatalogResource } from './types-Bn-dXLcs.js';
 import './toolbar.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
 import './sides-BPSWde0A.js';
 import './pane.js';
 import './workbench.js';
-import './nav-stack-B1Qc2e5q.js';
+import './nav-stack-BvSKY448.js';
 import './list.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './css-values.js';
@@ -2603,14 +2618,6 @@ interface CatalogRevealOptions {
  * 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.
- * Specimens receive computed border highlights (or a dashed bound when they
- * have no border and are transparent), while positive computed margins use
- * devtools-style orange bands. CSS/stylesheet-only changes are observed too.
- * 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
@@ -2622,7 +2629,7 @@ declare function wireCatalogGeometryOverlay(root: HTMLElement): () => void;
  */
 declare function wireCatalog(root: HTMLElement, { onSelect, onToggleSidebar, onToggleTheme, onToggleSecondary, urlParam, revealSelection, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, collapsed, sidebarSize, sidebarStorageKey, id: catalogId, }: WireCatalogOptions): () => void;
 
-export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry, wireCatalog, wireCatalogGeometryOverlay };
+export { type CatalogRevealOptions, type WireCatalogOptions, revealCatalogEntry, wireCatalog };
 ```
 
 ## `@kerfjs/ui/segmented-control`
@@ -3420,7 +3427,8 @@ import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { H as HorizontalAlignment, V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 import { S as Sides } from './sides-BPSWde0A.js';
-import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
+import { UiGap, CssFlexKeyword, CssFlex } from './css-values.js';
+export { CssLength, UiGapValue, UiSpaceName } from './css-values.js';
 
 type RowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -3438,8 +3446,8 @@ interface RowProps {
     hAlign?: HorizontalAlignment;
     /** Vertical alignment and wrapped-line distribution. Defaults to full. */
     vAlign?: VerticalAlignment;
-    /** A named UI spacing token or typed CSS length. Defaults to xs. */
-    gap?: UiSpaceName | CssLength;
+    /** One spacing value or separate column and row values. Defaults to xs. */
+    gap?: UiGap;
     /** Allow this row to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
     flex?: boolean | CssFlexKeyword | CssFlex;
     /**
@@ -3463,7 +3471,7 @@ interface RowProps {
 /** A horizontal flex row with explicit physical-axis alignment and spacing. */
 declare function Row({ children, hAlign, vAlign, gap, flex, fill, wrap, textInsets, controlInsets, className, rootAttributes, slot, }: RowProps): kerfjs.SafeHtml;
 
-export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, Row, type RowProps, Sides, UiSpaceName, VerticalAlignment };
+export { CssFlex, CssFlexKeyword, HorizontalAlignment, Row, type RowProps, Sides, UiGap, VerticalAlignment };
 ```
 
 ## `@kerfjs/ui/grid`
@@ -3472,7 +3480,8 @@ export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, Row, type RowP
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as Sides } from './sides-BPSWde0A.js';
-import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
+import { UiGap, CssFlexKeyword, CssFlex, CssLength } from './css-values.js';
+export { UiGapValue, UiSpaceName } from './css-values.js';
 
 type GridRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -3490,8 +3499,8 @@ interface GridCommonProps {
     selectionMode?: 'multiple';
     /** Accessible name for the multi-select grid. */
     ariaLabel?: string;
-    /** A named UI spacing token or typed CSS length. Defaults to xs. */
-    gap?: UiSpaceName | CssLength;
+    /** One spacing value or separate column and row values. Defaults to xs. */
+    gap?: UiGap;
     /** Allow this grid to grow/shrink, use a keyword, or supply a typed CSS flex shorthand. */
     flex?: boolean | CssFlexKeyword | CssFlex;
     /**
@@ -3525,7 +3534,7 @@ type GridProps = GridCommonProps & ({
 /** Render equal tracks with a fixed count or a responsive minimum width. */
 declare function Grid({ children, selectionMode, ariaLabel, columns, minColumnWidth, autoFill, gap, flex, fill, textInsets, controlInsets, className, rootAttributes, slot, }: GridProps): kerfjs.SafeHtml;
 
-export { CssFlex, CssFlexKeyword, CssLength, Grid, type GridProps, Sides, UiSpaceName };
+export { CssFlex, CssFlexKeyword, CssLength, Grid, type GridProps, Sides, UiGap };
 ```
 
 ## `@kerfjs/ui/spacer`
@@ -3558,3 +3567,38 @@ export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchRe
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
 ```
+
+## `@kerfjs/ui/anchored-surface`
+
+```ts
+import { PopoverOptions, OverlayContent, OverlayHandle } from 'kerfjs/overlay';
+
+/** App-facing options for a non-modal, arbitrary-content help surface. */
+interface AnchoredSurfaceOptions extends Pick<PopoverOptions, 'placement' | 'align' | 'gap' | 'dismiss' | 'initialFocus' | 'onDismiss' | 'outsideIgnore'> {
+    /** Accessible name for the non-modal dialog. */
+    label: string;
+}
+/** A viewport pointer location; `context` is the element under the pointer. */
+interface AnchoredSurfacePoint {
+    x: number;
+    y: number;
+    /** Pass the event target when opening from inside a modal dialog. */
+    context?: Element;
+}
+/**
+ * Open app-owned content beside an element. The surface owns its Kerf UI chrome;
+ * kerfjs/overlay owns positioning, top-layer/modal hosting, focus, and dismissal.
+ * The caller owns content, action policy, and calling `close()` when an action
+ * completes. `initialFocus` defaults to the first focusable descendant; set it
+ * to `false` for read-only help that should leave focus on its trigger.
+ */
+declare function openAnchoredSurface(anchor: Element, content: OverlayContent, options: AnchoredSurfaceOptions): OverlayHandle;
+/**
+ * Open the same surface at pointer coordinates. The temporary anchor has no
+ * layout or hit target. `context` keeps a surface opened inside a modal dialog
+ * in that dialog's interactive host slot; it is removed on close or failure.
+ */
+declare function openAnchoredSurfaceAt(point: AnchoredSurfacePoint, content: OverlayContent, options: AnchoredSurfaceOptions): OverlayHandle;
+
+export { type AnchoredSurfaceOptions, type AnchoredSurfacePoint, openAnchoredSurface, openAnchoredSurfaceAt };
+```

package/ai/skill.md

@@ -246,9 +246,9 @@ Hard rules:
 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). 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`). 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, exact specimen selection, geometry-overlay legend and exclusions, skip-marker behavior, 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.
+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`). 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. 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.
-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. Never render a `Discouraged` element directly in application, demo, or recipe markup; reach it only through the Kerf component that wraps it (`PopupMenu` renders `wa-dropdown`, `Select` renders `wa-select` / `wa-option`), and treat a Kerf component gap as a request to file, not a reason to drop to the raw element.
+14. Treat the complete Web Awesome catalog as support coverage, not a recommendation list. Its UX sidebar marks superseded and exceptional entries `Discouraged`. Use `openAnchoredSurface` from `@kerfjs/ui/anchored-surface` for arbitrary interactive help or popup content beside a control, or `openAnchoredSurfaceAt` at pointer coordinates; pass an accessible label and let the app own content/actions. Consider Popup only when its lower-level behavior is specifically needed. 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. Never render a `Discouraged` element directly in application, demo, or recipe markup; reach it only through the Kerf component that wraps it (`PopupMenu` renders `wa-dropdown`, `Select` renders `wa-select` / `wa-option`), and treat a Kerf component gap as a request to file, not a reason to drop to the raw element.
 15. Build sidebars, main areas, inspectors, and dialogs by rendering `Pane` (`@kerfjs/ui/pane`): an unpadded `.kui-pane` root, an optional `header`, one scrolling `.kui-pane__content`, and an optional `footer`; pick landmarks with `element` / `contentElement`. Never write a component's anatomy classes (`kui-pane`, `kui-toolbar`, `kui-list-item`, …) onto your own element to recreate it — render the component (`KUI-L103`). Only the catalog's `placeableClasses` (the `.kui-content` / `.kui-scroll-owner` / `.kui-control-cluster` / `.kui-inline-metadata` layout utilities, `.kui-app-root`, and `.kui-content-item` geometry on a non-div carrier) belong on elements you write. Use `Row` instead of a hand-written flex-row wrapper, `List` instead of a hand-written flex-column wrapper, and `Grid` instead of repeated equal-track CSS when children need a fixed positive count of evenly distributed columns. `Row` defaults to left/full with an `xs` gap and no wrapping; Grid defaults to an `xs` gap and keeps each track at `minmax(0, 1fr)`; List retains full/top and zero-gap defaults. The app owns Grid's responsive column-count changes. When a Row, List, or Grid is the layout root of a definite-height parent (an app root or a fixed-height frame), pass `fill` so it takes that full height, and put route/test/recipe `data-*` markers in its `rootAttributes`; never wrap a layout in a frame `Pane` just for height or a root attribute, because its content slot becomes a scroll owner that never scrolls. Inside a flex layout use `flex`, not `fill`. Use `List` when rows or sections also need flex growth, one vertical scroll owner, or physical-edge dividers. `dividerSides`, `textInsets`, and `controlInsets` use canonical physical `t`/`r`/`b`/`l` order; text geometry wins where text and control selections overlap. `ListInsetText` and `ListInsetControl` inset all four sides by default and accept the same `sides` grammar for selective edges. A dialog body is generally a `List`: set `DialogSurface bodyInset="none"` when its list children own geometry, and wrap bare dialog prose in `ListInsetText` so it aligns with bordered siblings without a second inset. Add `.kui-content` for 24px major vertical separation and render each ordinary surface-like child as `ContentItem` (`@kerfjs/ui/content-item`) for a child-owned 8px inline margin, 1px border, 8px padding, and 12px radius. Choose `frame="framed"` (neutral border in the always-reserved 1px, same geometry) only for a real distinction and `shape="pill"` for 22px; do not hand-write `<div class="kui-content-item">` or its modifier classes. There is no filled variant: a lowered filled surface is `SunkenPanel`. Do not pad pane shells, duplicate item geometry in wrappers, or create nested scroll owners. Align text to text and icons to icons across a pane — a title, a row label, and bare prose share the same text column (`ListInsetText` puts bare text on it); a border is decoration and never the alignment anchor, so a bordered surface extends to the pane gutter instead of being indented to line its border up with a heading's text.
     15a. Use `Text` from `@kerfjs/ui/text` for ordinary headings, paragraphs, and inline secondary text outside toolbar title zones. Omit `variant` for the default `p`, pass `h1`–`h6` according to the document outline, or use `variant="span"` inside a row, label, or table cell; ordinary native attributes pass through. Express supporting, error, compact, or code text with the independent finite `tone="quiet|danger"`, `size="compact"`, and `font="monospace"` props instead of global utility classes or appearance-only heading choices. Block Text variants own a transparent 1px border and the standard item padding; `span` owns no box geometry. Keep toolbar identity/title content on `ToolbarText` and list-aligned bare prose on `ListInsetText`. `ToolbarText` below `xlarge` is intentionally quiet identity text in default tone; a normal-color subsection title is `Text` with an `h2`–`h6` variant (or `ListHeader` for a list or menu section), never a recolored `ToolbarText`. Use `controlMargins` with canonical physical Sides for an exterior 8px control gutter without a Row wrapper; avoid stacking parent insets, and remember spans retain native inline margin behavior.
 

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.82` 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.84` 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/anchored-surface.d.ts

@@ -0,0 +1,30 @@
+import { PopoverOptions, OverlayContent, OverlayHandle } from 'kerfjs/overlay';
+
+/** App-facing options for a non-modal, arbitrary-content help surface. */
+interface AnchoredSurfaceOptions extends Pick<PopoverOptions, 'placement' | 'align' | 'gap' | 'dismiss' | 'initialFocus' | 'onDismiss' | 'outsideIgnore'> {
+    /** Accessible name for the non-modal dialog. */
+    label: string;
+}
+/** A viewport pointer location; `context` is the element under the pointer. */
+interface AnchoredSurfacePoint {
+    x: number;
+    y: number;
+    /** Pass the event target when opening from inside a modal dialog. */
+    context?: Element;
+}
+/**
+ * Open app-owned content beside an element. The surface owns its Kerf UI chrome;
+ * kerfjs/overlay owns positioning, top-layer/modal hosting, focus, and dismissal.
+ * The caller owns content, action policy, and calling `close()` when an action
+ * completes. `initialFocus` defaults to the first focusable descendant; set it
+ * to `false` for read-only help that should leave focus on its trigger.
+ */
+declare function openAnchoredSurface(anchor: Element, content: OverlayContent, options: AnchoredSurfaceOptions): OverlayHandle;
+/**
+ * Open the same surface at pointer coordinates. The temporary anchor has no
+ * layout or hit target. `context` keeps a surface opened inside a modal dialog
+ * in that dialog's interactive host slot; it is removed on close or failure.
+ */
+declare function openAnchoredSurfaceAt(point: AnchoredSurfacePoint, content: OverlayContent, options: AnchoredSurfaceOptions): OverlayHandle;
+
+export { type AnchoredSurfaceOptions, type AnchoredSurfacePoint, openAnchoredSurface, openAnchoredSurfaceAt };

package/dist/anchored-surface.js

@@ -0,0 +1,3 @@
+export { openAnchoredSurface, openAnchoredSurfaceAt } from './chunk-IOS2NXW7.js';
+
+//# sourceMappingURL=anchored-surface.js.map

package/dist/anchored-surface.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"anchored-surface.js"}

package/dist/app-tab.js

@@ -1,4 +1,4 @@
-export { AppTab } from './chunk-HFLGWMG3.js';
+export { AppTab } from './chunk-KAJVVN7Q.js';
 
 
 

package/dist/browser/anchored-surface.js

@@ -0,0 +1,3 @@
+import '../styles/foundation.css';
+import '../styles/anchored-surface.css';
+export * from '../anchored-surface.js';

package/dist/browser/catalog.js

@@ -3,13 +3,13 @@ import '../styles/loading-spinner.css';
 import '../styles/toolbar-control-group.css';
 import '../styles/skeleton.css';
 import '../styles/toolbar-text.css';
-import '../styles/list.css';
 import '../styles/list-inset-control.css';
 import '../styles/list-inset-text.css';
 import '../styles/lucide-icon.css';
 import '../styles/token-search-field.css';
 import '../styles/resizable-region.css';
 import '../styles/toolbar.css';
+import '../styles/list.css';
 import '../styles/pane.css';
 import '../styles/floating-toolbar.css';
 import '../styles/nav-stack.css';

package/dist/catalog-resources.d.ts

@@ -1,11 +1,11 @@
-import { C as CatalogResource } from './types-C9BubXfz.js';
+import { C as CatalogResource } from './types-Bn-dXLcs.js';
 import './toolbar.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
 import './sides-BPSWde0A.js';
 import './pane.js';
 import './workbench.js';
-import './nav-stack-B1Qc2e5q.js';
+import './nav-stack-BvSKY448.js';
 import './list.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './css-values.js';

package/dist/catalog.d.ts

@@ -1,13 +1,13 @@
 import * as kerfjs from 'kerfjs';
 import { SafeHtml } from 'kerfjs';
-import { a as CatalogProps } from './types-C9BubXfz.js';
-export { b as CatalogBrand, c as CatalogEntry, d as CatalogRelated, C as CatalogResource, e as CatalogSecondaryGroup, f as CatalogSection, g as CatalogStageRootAttributes } from './types-C9BubXfz.js';
+import { a as CatalogProps } from './types-Bn-dXLcs.js';
+export { b as CatalogBackgroundStyle, c as CatalogBrand, d as CatalogEntry, e as CatalogRelated, C as CatalogResource, f as CatalogSecondaryGroup, g as CatalogSection, h as CatalogStageRootAttributes } from './types-Bn-dXLcs.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import './toolbar.js';
 import './sides-BPSWde0A.js';
 import './pane.js';
 import './workbench.js';
-import './nav-stack-B1Qc2e5q.js';
+import './nav-stack-BvSKY448.js';
 import './list.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './css-values.js';
@@ -24,7 +24,7 @@ import './resizable-region.js';
  * standard toggle moves into the entry toolbar while it is collapsed, and on
  * a small screen the sidebar overlays the stage like any Workbench rail.
  */
-declare function Catalog({ id, brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, geometryOverlay, stageRootAttributes, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, headerPlacement, footerPlacement, sidebar, mainToolbar, footerToolbar, className, slot, }: CatalogProps): kerfjs.SafeHtml;
+declare function Catalog({ id, brand, sections, active, content, collapsed, theme, headerActions, secondarySections, sidebarFooter, status, backgroundStyle, stageRootAttributes, selectAction, toggleSidebarAction, toggleThemeAction, toggleSecondaryAction, headerPlacement, footerPlacement, sidebar, mainToolbar, footerToolbar, className, slot, }: CatalogProps): kerfjs.SafeHtml;
 
 /** How a specimen aligns its visible edge with its `ListHeader` label. */
 type CatalogExampleAlign = 'glyph' | 'inline-control' | 'text-trigger' | 'none';

package/dist/catalog.js

@@ -1,31 +1,32 @@
-import { Workbench } from './chunk-LQKY5S4F.js';
+import { Workbench } from './chunk-KL3W6FUN.js';
 
 
-import { TokenSearchField } from './chunk-3SXWV2IR.js';
+import { TokenSearchField } from './chunk-VLGQIYZ5.js';
+import { ToolbarText } from './chunk-3DXHNLME.js';
 import { PopupMenu } from './chunk-NJZMR7HM.js';
 
-import { Row } from './chunk-5D3WDMIK.js';
-import { ListHeader } from './chunk-VIGVNDXZ.js';
+import { Row } from './chunk-MORVLMDG.js';
+import { ListHeader } from './chunk-GPCAXYMT.js';
 import { Text } from './chunk-4Y4L5YEI.js';
 import { ListInsetControl } from './chunk-AN5IWMTM.js';
 import { ListInsetText } from './chunk-NMWDHZVM.js';
-import { ListItem } from './chunk-HFQDSSED.js';
-import { ToolbarText } from './chunk-VHXHLZ6R.js';
+import { ListItem } from './chunk-3PO7JEK7.js';
 
 
 
 
 
 
-import { ToolbarControlGroup, ToolbarActionLink } from './chunk-RRCD3A6G.js';
+import { ToolbarControlGroup, ToolbarActionLink } from './chunk-MTCTX25G.js';
 import { Toolbar } from './chunk-BYHGRKC3.js';
 
-import { List } from './chunk-NVRJ7C3W.js';
+import { List } from './chunk-QQICWWNX.js';
+
+import { LucideIcon } from './chunk-NP3FSLNX.js';
 
-import { LucideIcon } from './chunk-PQQQXJGV.js';
 
-import { filterDataAttributes } from './chunk-LAZLBC2Q.js';
 
+import { filterDataAttributes } from './chunk-LAZLBC2Q.js';
 import { Moon, Sun, X, Waypoints, ExternalLink } from 'lucide';
 import { jsx, jsxs, Fragment } from 'kerfjs/jsx-runtime';
 
@@ -242,11 +243,14 @@ function CatalogSidebar({
     footer
   ] }) });
 }
-var protectedAttributes = /* @__PURE__ */ new Set(["data-catalog-stage"]);
+var protectedAttributes = /* @__PURE__ */ new Set([
+  "data-catalog-stage",
+  "data-background-style"
+]);
 function CatalogStage({
   name,
   content,
-  geometryOverlay,
+  backgroundStyle = "checkerboard",
   rootAttributes = {}
 }) {
   const safeRootAttributes = filterDataAttributes(
@@ -259,19 +263,9 @@ function CatalogStage({
       ...safeRootAttributes,
       class: "kui-catalog__stage",
       "data-catalog-stage": true,
+      "data-background-style": backgroundStyle,
       "aria-label": `${name} preview`,
-      children: /* @__PURE__ */ jsxs("div", { class: "kui-catalog__canvas", children: [
-        content,
-        geometryOverlay !== void 0 ? /* @__PURE__ */ jsx(
-          "div",
-          {
-            class: "kui-catalog__geometry-overlay",
-            "data-catalog-geometry-overlay": true,
-            "data-morph-skip-children": true,
-            "aria-hidden": "true"
-          }
-        ) : null
-      ] })
+      children: /* @__PURE__ */ jsx("div", { class: "kui-catalog__canvas", children: content })
     }
   );
 }
@@ -293,7 +287,7 @@ function Catalog({
   secondarySections,
   sidebarFooter,
   status,
-  geometryOverlay,
+  backgroundStyle,
   stageRootAttributes,
   selectAction = "catalog-select",
   toggleSidebarAction = "catalog-toggle-sidebar",
@@ -317,7 +311,6 @@ function Catalog({
       class: `kui-catalog ${className}`.trim(),
       "data-component": "catalog",
       "data-sidebar-collapsed": String(collapsed),
-      "data-geometry-overlay": geometryOverlay === void 0 ? void 0 : String(geometryOverlay),
       slot,
       children: /* @__PURE__ */ jsx(
         Workbench,
@@ -338,7 +331,17 @@ function Catalog({
               ...sidebar.toolbar,
               label: `${catalogName} header`,
               title: /* @__PURE__ */ jsxs(Fragment, { children: [
-                brand.logoUrl ? /* @__PURE__ */ jsx(ToolbarControlGroup, { appearance: "borderless", single: true, children: /* @__PURE__ */ jsx("img", { class: "kui-catalog__mark", src: brand.logoUrl, alt: "" }) }) : null,
+                brand.logoUrl ? /* @__PURE__ */ jsx(
+                  ToolbarControlGroup,
+                  {
+                    appearance: "borderless",
+                    content: "avatar",
+                    shape: "rounded",
+                    single: true,
+                    avatarImage: brand.logoUrl,
+                    children: null
+                  }
+                ) : null,
                 /* @__PURE__ */ jsx(ToolbarText, { text: brand.title, size: "large", headingLevel: 1 })
               ] }),
               toggle: { action: toggleSidebarAction, name: catalogName }
@@ -349,7 +352,6 @@ function Catalog({
                 id: `${id}-filter`,
                 label: "Filter catalog",
                 placeholder: "Filter items or headings",
-                className: "kui-catalog__filter",
                 editorAttributes: { "data-catalog-filter": "" },
                 trailingAction: {
                   icon: /* @__PURE__ */ jsx(LucideIcon, { icon: X, name: "x" }),
@@ -403,6 +405,7 @@ function Catalog({
               ) : null
             ] })
           },
+          mainPane: { appearance: "sunken" },
           mainFooter: /* @__PURE__ */ jsx(
             CatalogResourceFooter,
             {
@@ -424,15 +427,15 @@ function Catalog({
           ) : null,
           mainHeaderPlacement: headerPlacement,
           mainFooterPlacement: footerPlacement,
-          main: /* @__PURE__ */ jsx(List, { flex: true, children: /* @__PURE__ */ jsx(
+          main: /* @__PURE__ */ jsx(
             CatalogStage,
             {
               name,
               content,
-              geometryOverlay,
+              backgroundStyle,
               rootAttributes: stageRootAttributes
             }
-          ) })
+          )
         }
       )
     }