@kerfjs/ui 5.0.0-beta.75 → 5.0.0-beta.77

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.75` and `kerfjs@5.0.0-beta.75`. 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.77` and `kerfjs@5.0.0-beta.77`. 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`
 
@@ -147,9 +147,9 @@ export { DisclosureArrow, type DisclosureArrowProps, type DisclosureDirection };
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { PaneSeparatorSide } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as Sides } from './sides-BPSWde0A.js';
+import { PaneSeparatorSide } from './pane.js';
 
 type ToolbarPosition = 'header' | 'footer';
 interface ToolbarProps {
@@ -217,13 +217,21 @@ export { Sides, Toolbar, type ToolbarConfig, type ToolbarPosition, type ToolbarP
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { CssLength } from './css-values.js';
 
 type ToolbarTextSize = 'xlarge' | 'xlarge-fixed' | 'large' | 'default' | 'small' | 'xsmall';
+type ToolbarTextTone = 'default' | 'dark';
 /** ARIA heading level for a title exposed as a heading landmark. */
 type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 interface ToolbarTextBaseProps {
     text: string;
     size?: ToolbarTextSize;
+    /** Use dark-toolbar foregrounds on a dark or photo-backed toolbar. */
+    tone?: ToolbarTextTone;
+    /** Hide below this Toolbar content width; requires wireToolbarVisibility. */
+    hideBelow?: CssLength;
+    /** Show only below this Toolbar content width; requires wireToolbarVisibility. */
+    showBelow?: CssLength;
     className?: string;
     /** Optional id, e.g. so a dialog can reference the title via aria-labelledby. */
     id?: string;
@@ -264,9 +272,9 @@ type ToolbarTextProps = ToolbarTextBaseProps & (({
     wrap?: never;
     maxLines?: never;
 });
-declare function ToolbarText({ text, size, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, fill, slot, action, }: ToolbarTextProps): kerfjs.SafeHtml;
+declare function ToolbarText({ text, size, tone, hideBelow, showBelow, className, id, headingLevel, placeholder, wrap, ellipsis, maxLines, fill, slot, action, }: ToolbarTextProps): kerfjs.SafeHtml;
 
-export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize };
+export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarTextSize, type ToolbarTextTone };
 ```
 
 ## `@kerfjs/ui/toolbar-control-group`
@@ -274,9 +282,12 @@ export { type HeadingLevel, ToolbarText, type ToolbarTextProps, type ToolbarText
 ```ts
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssLength } from './css-values.js';
 
 type ToolbarControlGroupAppearance = 'contained' | 'borderless';
 type ToolbarControlGroupTone = 'default' | 'dark';
+/** Quiet palette for a contained, single decorative icon tile. */
+type ToolbarControlGroupTileTone = 'neutral' | 'brand' | 'success' | 'warning' | 'danger';
 type ToolbarControlGroupButtonAppearance = 'plain' | 'push';
 type ToolbarControlGroupShape = 'pill' | 'rounded';
 type ToolbarControlGroupSize = 'default' | 'compact';
@@ -286,6 +297,7 @@ type ToolbarControlGroupFocusRing = 'control' | 'outline' | 'halo';
 type ToolbarControlGroupSelectedChrome = 'raised' | 'filled' | 'outline';
 type ToolbarControlGroupSelectedTone = 'brand' | 'neutral' | 'pop';
 type ToolbarControlGroupOverflow = 'visible' | 'scroll' | 'wrap';
+type ToolbarControlGroupExpandedOverflow = 'clip' | 'visible';
 type ToolbarControlGroupMenuInset = 'standard' | 'compact' | 'list-zero';
 type ToolbarControlGroupVisibility = 'always' | 'compact-only' | 'hide-collapsed-tiny' | 'yield-to-expanded-sibling';
 type ToolbarControlGroupSizing = 'content' | 'grow' | 'fill';
@@ -314,6 +326,8 @@ interface ToolbarControlGroupProps {
     single?: boolean;
     appearance?: ToolbarControlGroupAppearance;
     tone?: ToolbarControlGroupTone;
+    /** Quiet fill, matching border and foreground for a contained single group whose only child is a decorative SVG. Ignored for interactive or mixed content. */
+    tileTone?: ToolbarControlGroupTileTone;
     buttonAppearance?: ToolbarControlGroupButtonAppearance;
     /** Corner shape: fully round `pill` (default) or a softer `rounded` rectangle. */
     shape?: ToolbarControlGroupShape;
@@ -330,8 +344,14 @@ interface ToolbarControlGroupProps {
     menuInset?: ToolbarControlGroupMenuInset;
     /** Keep an overlong row inside the available width by scrolling or wrapping. */
     overflow?: ToolbarControlGroupOverflow;
+    /** Let app-owned anchored surfaces extend outside an expanded search group. Collapsed searches retain their clipping. */
+    expandedOverflow?: ToolbarControlGroupExpandedOverflow;
     /** Responsive visibility owned by the enclosing Toolbar container. */
     visibility?: ToolbarControlGroupVisibility;
+    /** Hide below this Toolbar content width; requires wireToolbarVisibility. */
+    hideBelow?: CssLength;
+    /** Show only below this Toolbar content width; requires wireToolbarVisibility. */
+    showBelow?: CssLength;
     /** Intrinsic (default), grow from a basis, or occupy a full wrapping row. */
     sizing?: ToolbarControlGroupSizing;
     /** Place this group at the end of its flex row in a wrapping Toolbar zone. */
@@ -354,17 +374,17 @@ interface ToolbarControlGroupProps {
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
-declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, visibility, sizing, placement, growBasis, relocateOnCollapse, scrim, busy, busyLabel, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, tileTone, buttonAppearance, shape, size, density, content, focusRing, selectedChrome, selectedTone, nestedDropdown, menuInset, overflow, expandedOverflow, visibility, hideBelow, showBelow, sizing, placement, growBasis, relocateOnCollapse, scrim, busy, busyLabel, avatarImage, slot, }: ToolbarControlGroupProps): kerfjs.SafeHtml;
 
-export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupFocusRing, type ToolbarControlGroupMenuInset, type ToolbarControlGroupOverflow, type ToolbarControlGroupPlacement, type ToolbarControlGroupProps, type ToolbarControlGroupSelectedChrome, type ToolbarControlGroupSelectedTone, type ToolbarControlGroupShape, type ToolbarControlGroupSize, type ToolbarControlGroupSizing, type ToolbarControlGroupTone, type ToolbarControlGroupVisibility };
+export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupExpandedOverflow, type ToolbarControlGroupFocusRing, type ToolbarControlGroupMenuInset, type ToolbarControlGroupOverflow, type ToolbarControlGroupPlacement, type ToolbarControlGroupProps, type ToolbarControlGroupSelectedChrome, type ToolbarControlGroupSelectedTone, type ToolbarControlGroupShape, type ToolbarControlGroupSize, type ToolbarControlGroupSizing, type ToolbarControlGroupTileTone, type ToolbarControlGroupTone, type ToolbarControlGroupVisibility };
 ```
 
 ## `@kerfjs/ui/floating-toolbar`
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { CssLength } from './css-values.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssLength } from './css-values.js';
 
 /** Where a {@link FloatingToolbar} floats within its positioned container. */
 type FloatingToolbarPosition = 'bottom' | 'bottom-start' | 'bottom-end' | 'top' | 'top-start' | 'top-end';
@@ -525,6 +545,7 @@ export { PopupMenu, type PopupMenuDivider, type PopupMenuElement, type PopupMenu
 ```ts
 import { SafeHtml } from 'kerfjs';
 import { HeadingLevel } from './toolbar-text.js';
+import './css-values.js';
 
 type ListHeaderRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -631,11 +652,11 @@ export { ListHeader, type ListHeaderProps };
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
+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 { 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';
 
 type ListRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -898,7 +919,10 @@ export { ListInsetText, type ListInsetTextProps, Sides };
 ```ts
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
 
+/** Base surface treatment or semantic status colors. */
+type ContentItemAppearance = 'transparent' | 'surface' | SemanticTone;
 /** Whether the item's always-reserved 1px border is transparent or visible. */
 type ContentItemFrame = 'none' | 'framed';
 /** Corner shape: the 12px rounded rectangle or the 22px pill. */
@@ -907,9 +931,11 @@ type ContentItemShape = 'rounded' | 'pill';
 type ContentItemSelectionMode = 'none' | 'single' | 'multiple' | 'toggle';
 type ContentItemRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
+    'data-appearance'?: never;
 }>;
 type ContentItemInteractiveRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
+    'data-appearance'?: never;
     'data-action'?: never;
     'data-item-id'?: never;
     'data-interactive'?: never;
@@ -919,6 +945,12 @@ type ContentItemInteractiveRootAttributes = Readonly<Record<`data-${string}`, st
     'data-kui-pressed'?: never;
 }>;
 interface ContentItemBaseProps {
+    /**
+     * Coordinated background, border, and foreground colors. `transparent`
+     * preserves the surrounding surface; `surface` paints the base surface;
+     * semantic values match StateBanner. Defaults to `transparent`.
+     */
+    appearance?: ContentItemAppearance;
     /** Item content; a plain string is allowed for bare copy. */
     children?: KerfUiContent | string;
     /**
@@ -974,9 +1006,9 @@ type ContentItemProps = ContentItemBaseProps & ({
  * border (transparent unless `framed`), 8px padding, and a rounded or pill
  * radius. It owns that whole geometry, so wrappers must not add more.
  */
-declare function ContentItem({ children, frame, flush, shape, title, ariaLabel, focusTarget, interactive, action, itemId, selectionMode, selected, disabled, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
+declare function ContentItem({ appearance, children, frame, flush, shape, title, ariaLabel, focusTarget, interactive, action, itemId, selectionMode, selected, disabled, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
 
-export { ContentItem, type ContentItemFrame, type ContentItemProps, type ContentItemSelectionMode, type ContentItemShape };
+export { ContentItem, type ContentItemAppearance, type ContentItemFrame, type ContentItemProps, type ContentItemSelectionMode, type ContentItemShape, SemanticTone };
 ```
 
 ## `@kerfjs/ui/value-table`
@@ -1254,11 +1286,12 @@ export { type ScrollDividerTarget, type WireScrollDividersOptions, wireScrollDiv
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { PaneAppearance } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { ToolbarConfig } from './toolbar.js';
 import { ToolbarTextSize, HeadingLevel } from './toolbar-text.js';
+import { PaneAppearance } from './pane.js';
 import './sides-BPSWde0A.js';
+import './css-values.js';
 
 /**
  * One entry in a {@link NavStack}. The app owns the stack as an array (usually a
@@ -1376,12 +1409,12 @@ export { type WireNavStackOptions, wireNavStack };
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { NavStackProps, NavStackView } from './nav-stack.js';
 import { ResizableRegionProps } from './resizable-region.js';
-import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import './pane.js';
 import './toolbar.js';
 import './sides-BPSWde0A.js';
+import './pane.js';
 import './toolbar-text.js';
 import './css-values.js';
 
@@ -1568,16 +1601,16 @@ export { Pane, type PaneAppearance, type PaneChromeDividers, type PaneChromePlac
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { ListConfig } from './list.js';
 import { NavStackProps } from './nav-stack.js';
 import { PaneConfig } from './pane.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
-import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-CL9tYOkh.js';
 import { ToolbarConfig } from './toolbar.js';
-import { a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-DDKh4uKd.js';
-import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './sides-BPSWde0A.js';
+import './css-values.js';
 import './toolbar-text.js';
 import './lucide-icon.js';
 import 'lucide';
@@ -1962,18 +1995,18 @@ export { type WireWorkbenchOptions, type WireWorkbenchPanel, type WorkbenchPanel
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { P as PanelSide, a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-CL9tYOkh.js';
+export { e as collapsiblePanelToggleIcon } from './panel-toolbar-CL9tYOkh.js';
 import { ListConfig } from './list.js';
 import { PaneConfig } from './pane.js';
-import { P as PanelSide, a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-DDKh4uKd.js';
-export { e as collapsiblePanelToggleIcon } from './panel-toolbar-DDKh4uKd.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
-import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import './css-values.js';
-import './flex-alignment-4ms8ZbV8.js';
+import './toolbar.js';
 import './sides-BPSWde0A.js';
 import './lucide-icon.js';
 import 'lucide';
-import './toolbar.js';
+import './css-values.js';
+import './flex-alignment-4ms8ZbV8.js';
 
 /** Which edge a {@link CollapsiblePanel} docks to. */
 type CollapsiblePanelSide = PanelSide;
@@ -2168,8 +2201,8 @@ export { type SidebarStorage, type WireSidebarOptions, type WireSidebarPanel, wi
 
 ```ts
 import { SafeHtml } from 'kerfjs';
-import { PaneAppearance } from './pane.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { PaneAppearance } from './pane.js';
 
 interface TabScaffoldTabBase<Id extends string> {
     id: Id;
@@ -2269,8 +2302,8 @@ export { type WireTabScaffoldOptions, wireTabScaffold };
 
 ```ts
 import { SafeHtml } from 'kerfjs';
-import { CssLength } from './css-values.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssLength } from './css-values.js';
 
 type ResizableRegionAxis = 'horizontal' | 'vertical';
 type ResizableRegionEdge = 'start' | 'end';
@@ -2415,20 +2448,20 @@ 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-BuHELdXR.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-BuHELdXR.js';
+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 { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import './toolbar.js';
-import './pane.js';
 import './sides-BPSWde0A.js';
+import './pane.js';
 import './workbench.js';
 import './list.js';
-import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
+import './css-values.js';
 import './nav-stack.js';
 import './toolbar-text.js';
 import './resizable-region.js';
-import './panel-toolbar-DDKh4uKd.js';
+import './panel-toolbar-CL9tYOkh.js';
 import './lucide-icon.js';
 import 'lucide';
 
@@ -2510,20 +2543,20 @@ export { Catalog, CatalogExample, type CatalogExampleAlign, type CatalogExampleP
 ## `@kerfjs/ui/catalog-resources`
 
 ```ts
-import { C as CatalogResource } from './types-BuHELdXR.js';
-import './semantic-content-BbzjvSu9.js';
-import 'kerfjs';
+import { C as CatalogResource } from './types-C9BubXfz.js';
 import './toolbar.js';
-import './pane.js';
+import 'kerfjs';
+import './semantic-content-BbzjvSu9.js';
 import './sides-BPSWde0A.js';
+import './pane.js';
 import './workbench.js';
 import './list.js';
-import './css-values.js';
 import './flex-alignment-4ms8ZbV8.js';
+import './css-values.js';
 import './nav-stack.js';
 import './toolbar-text.js';
 import './resizable-region.js';
-import './panel-toolbar-DDKh4uKd.js';
+import './panel-toolbar-CL9tYOkh.js';
 import './lucide-icon.js';
 import 'lucide';
 
@@ -2689,9 +2722,9 @@ export { SegmentedControl, type SegmentedControlAppearance, type SegmentedContro
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { CssForegroundColor } from './css-values.js';
 import { LucideNode } from './lucide-icon.js';
-import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import 'lucide';
 
 interface SelectChoice<Value extends string = string> {
@@ -2740,6 +2773,7 @@ interface SelectBaseProps<Value extends string = string> {
     /** Supporting text shown below the control and associated with its combobox. */
     hint?: string;
     disabled?: boolean;
+    /** Match menu width to the trigger; default menus grow to content within viewport gutters. */
     fitMenu?: boolean;
     /** Render as an unanimated loading skeleton: the label above a static, empty control box. */
     placeholder?: boolean;
@@ -2820,8 +2854,10 @@ export { Select, type SelectChoice, type SelectFocusRingOwner, type SelectMultip
 ```ts
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
 
-type StateBannerTone = 'neutral' | 'info' | 'pop' | 'success' | 'warning' | 'danger';
+/** @deprecated Use SemanticTone. */
+type StateBannerTone = SemanticTone;
 type StateBannerUrgency = 'status' | 'alert';
 type StateBannerCopyLayout = 'inline' | 'stacked';
 type StateBannerActionPlacement = 'trailing' | 'below';
@@ -2832,7 +2868,7 @@ interface StateBannerProps {
     badge?: string;
     icon?: SafeHtml;
     action?: KerfUiContent;
-    tone?: StateBannerTone;
+    tone?: SemanticTone;
     urgency?: StateBannerUrgency;
     /** Keep the detail beside the title, or give it its own line. */
     copyLayout?: StateBannerCopyLayout;
@@ -2846,7 +2882,7 @@ interface StateBannerProps {
 }
 declare function StateBanner({ title, detail, badge, icon, action, tone, urgency, copyLayout, actionPlacement, className, placeholder, slot, }: StateBannerProps): SafeHtml;
 
-export { StateBanner, type StateBannerActionPlacement, type StateBannerCopyLayout, type StateBannerProps, type StateBannerTone, type StateBannerUrgency };
+export { SemanticTone, StateBanner, type StateBannerActionPlacement, type StateBannerCopyLayout, type StateBannerProps, type StateBannerTone, type StateBannerUrgency };
 ```
 
 ## `@kerfjs/ui/empty-state`
@@ -2874,13 +2910,15 @@ export { EmptyState, type EmptyStateProps };
 
 ```ts
 import * as kerfjs from 'kerfjs';
+import { CssForegroundColor } from './css-values.js';
 import { LucideIconSize } from './lucide-icon.js';
 import 'lucide';
-import './css-values.js';
 
 type LoadingSpinnerSize = LucideIconSize;
 interface LoadingSpinnerProps {
     className?: string;
+    /** Foreground color; omit to inherit the surrounding text color. */
+    color?: CssForegroundColor;
     label?: string;
     /** Named icon scale or positive pixel size, converted to rem. Omit for 1em. */
     size?: LoadingSpinnerSize;
@@ -2888,7 +2926,7 @@ interface LoadingSpinnerProps {
     slot?: string;
 }
 /** Stable viewBox-centered progress ring based on svg-spinners' MIT-licensed 180-ring. */
-declare function LoadingSpinner({ className, label, size, slot, }: LoadingSpinnerProps): kerfjs.SafeHtml;
+declare function LoadingSpinner({ className, color, label, size, slot, }: LoadingSpinnerProps): kerfjs.SafeHtml;
 
 export { LoadingSpinner, type LoadingSpinnerProps, type LoadingSpinnerSize };
 ```
@@ -2933,8 +2971,8 @@ export { Skeleton, type SkeletonProps };
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { CssFlexKeyword, CssFlex } from './css-values.js';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssFlexKeyword, CssFlex } from './css-values.js';
 
 type SunkenPanelShape = 'rounded' | 'square';
 interface SunkenPanelProps {
@@ -2964,16 +3002,16 @@ export { SunkenPanel, type SunkenPanelProps, type SunkenPanelShape };
 ## `@kerfjs/ui/token-search-field`
 
 ```ts
+export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, k as TokenSearchTrailingAction, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-model-DTcTXWMS.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
-export { T as TokenSearchEditorAttributes, a as TokenSearchField, b as TokenSearchFieldProps, c as TokenSearchFieldValue, j as TokenSearchToken, k as TokenSearchTrailingAction, p as placeTokenSearchCaret, r as readTokenSearchField } from './token-search-field-CVGwDn2y.js';
 ```
 
 ## `@kerfjs/ui/wire-token-search-fields`
 
 ```ts
 import { Signal } from 'kerfjs';
-import { d as TokenSearchModel } from './token-search-field-CVGwDn2y.js';
+import { d as TokenSearchModel } from './token-search-model-DTcTXWMS.js';
 import './semantic-content-BbzjvSu9.js';
 
 interface TokenSearchSubmit {
@@ -3170,14 +3208,16 @@ export { type ActionHandler, type DelegateActionsOptions, action, delegateAction
 
 ```ts
 import { SafeHtml } from 'kerfjs';
+import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
 
-type BadgeTone = 'neutral' | 'brand' | 'pop' | 'success' | 'warning' | 'danger';
+/** @deprecated Use SemanticTone. */
+type BadgeTone = SemanticTone;
 type BadgeAppearance = 'quiet' | 'solid' | 'outline';
 type BadgeShape = 'pill' | 'rounded';
 /** Size of a text badge. A text-free dot is the separate `size: 'dot'` form. */
 type BadgeSize = 'compact' | 'default';
 interface BadgeCommonProps {
-    tone?: BadgeTone;
+    tone?: SemanticTone;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -3220,19 +3260,20 @@ type BadgeProps = BadgeTextProps | BadgeDotProps;
 /** Compact, non-interactive metadata whose tone, emphasis, and shape are configured by props. */
 declare function Badge(props: BadgeProps): SafeHtml;
 
-export { Badge, type BadgeAppearance, type BadgeDotProps, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeTextProps, type BadgeTone };
+export { Badge, type BadgeAppearance, type BadgeDotProps, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeTextProps, type BadgeTone, SemanticTone };
 ```
 
 ## `@kerfjs/ui/chip`
 
 ```ts
 import { SafeHtml } from 'kerfjs';
-import { BadgeTone, BadgeAppearance, BadgeShape, BadgeSize } from './badge.js';
+import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
+import { BadgeAppearance, BadgeShape, BadgeSize } from './badge.js';
 
 interface ChipCommonProps {
     /** Decorative leading icon, normally an unsized LucideIcon. */
     icon?: SafeHtml;
-    tone?: BadgeTone;
+    tone?: SemanticTone;
     appearance?: BadgeAppearance;
     shape?: BadgeShape;
     size?: BadgeSize;
@@ -3280,6 +3321,8 @@ interface LucideIconProps {
     className?: string;
     /** Foreground color; omit to inherit the surrounding text color. */
     color?: CssForegroundColor;
+    /** Flow with surrounding text instead of occupying a block. */
+    inline?: boolean;
     label?: string;
     /** Named icon scale or positive pixel size, converted to rem. Omit for 1em. */
     size?: LucideIconSize;
@@ -3287,11 +3330,29 @@ interface LucideIconProps {
     slot?: string;
 }
 /** Render a Lucide-compatible icon node without copying icon SVG strings. */
-declare function LucideIcon({ icon, name, appearance, className, color, label, size, slot, }: LucideIconProps): kerfjs.SafeHtml;
+declare function LucideIcon({ icon, name, appearance, className, color, inline, label, size, slot, }: LucideIconProps): kerfjs.SafeHtml;
 
 export { LucideIcon, type LucideIconProps, type LucideIconSize, type LucideNode };
 ```
 
+## `@kerfjs/ui/wire-toolbar-visibility`
+
+```ts
+type Root = HTMLElement | Document;
+/**
+ * Wire ToolbarText and ToolbarControlGroup width thresholds below root.
+ * Below is strict: hideBelow hides at width < threshold; showBelow hides at
+ * width >= threshold. Percentages use the closest Toolbar's content box;
+ * em and custom properties use the item's own inherited context. Invalid,
+ * negative, unresolved, or contradictory thresholds leave the item visible.
+ * This helper changes only a component-owned visibility marker. Existing
+ * CSS visibility policies still apply. Dispose with the owning application.
+ */
+declare function wireToolbarVisibility(root: Root): () => void;
+
+export { wireToolbarVisibility };
+```
+
 ## `@kerfjs/ui/surface-scaffold`
 
 ```ts
@@ -3333,6 +3394,16 @@ export { DialogSurface, type DialogSurfacePresentation, type DialogSurfaceProps,
 import * as kerfjs from 'kerfjs';
 import { KerfBaseAttrs } from 'kerfjs/jsx-runtime';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as Sides } from './sides-BPSWde0A.js';
+import { CssForegroundColor } from './css-values.js';
+
+type FieldLabelProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
+    children: string;
+    class?: string;
+    className?: string;
+};
+/** Visible field heading for a read-only preview; use its id with aria-labelledby on the preview group. */
+declare function FieldLabel({ children, class: classValue, className, ...attributes }: FieldLabelProps): kerfjs.SafeHtml;
 
 type TextVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span';
 type TextTone = 'default' | 'quiet' | 'danger';
@@ -3342,24 +3413,21 @@ type TextBorder = 'transparent' | 'none';
 type TextLineHeight = 'default' | 'tight';
 type TextWrap = 'normal' | 'anywhere' | 'nowrap' | 'truncate';
 type TextContent = KerfUiContent | string | number | readonly TextContent[];
-type FieldLabelProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
-    children: string;
-    class?: string;
-    className?: string;
-};
-/** Visible field heading for a read-only preview; use its id with aria-labelledby on the preview group. */
-declare function FieldLabel({ children, class: classValue, className, ...attributes }: FieldLabelProps): kerfjs.SafeHtml;
 type TextCommonProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> & {
     /** Native heading, paragraph, or inline span element to render. Defaults to `p`. */
     variant?: TextVariant;
     /** Semantic foreground treatment. Defaults to the inherited foreground. */
     tone?: TextTone;
+    /** Foreground color; overrides tone when supplied, or inherits when omitted. */
+    color?: CssForegroundColor;
     /** Text sizing independent of the native semantic element. */
     size?: TextSize;
     /** Font family independent of the native semantic element. */
     font?: TextFont;
     /** Transparent alignment border or no border when embedded in owner chrome. */
     border?: TextBorder;
+    /** Add the shared control gutter outside selected physical edges. */
+    controlMargins?: Sides;
     /** Remove the block variant's item padding and border in compact content. */
     flush?: boolean;
     /** Use compact leading for short dialog or metadata copy. */
@@ -3383,19 +3451,19 @@ type TextProps = TextCommonProps & ({
  * content-item padding; `span` adds no box geometry.
  * All ordinary native heading/paragraph attributes pass through to the element.
  */
-declare function Text({ variant: Variant, tone, size, font, border, flush, lineHeight, wrap, maxLines, children, class: classValue, className, ...attributes }: TextProps): kerfjs.SafeHtml;
+declare function Text({ variant: Variant, tone, color, size, font, border, flush, controlMargins, lineHeight, wrap, maxLines, children, class: classValue, className, style, ...attributes }: TextProps): kerfjs.SafeHtml;
 
-export { FieldLabel, type FieldLabelProps, Text, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextVariant, type TextWrap };
+export { FieldLabel, type FieldLabelProps, Sides, Text, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextVariant, type TextWrap };
 ```
 
 ## `@kerfjs/ui/row`
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
-import { H as HorizontalAlignment, V as VerticalAlignment } from './flex-alignment-4ms8ZbV8.js';
 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';
 
 type RowRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -3445,8 +3513,9 @@ export { CssFlex, CssFlexKeyword, CssLength, HorizontalAlignment, Row, type RowP
 
 ```ts
 import * as kerfjs from 'kerfjs';
-import { UiSpaceName, CssLength, CssFlexKeyword, CssFlex } from './css-values.js';
 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';
 
 type GridRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -3455,6 +3524,8 @@ type GridRootAttributes = Readonly<Record<`data-${string}`, string | undefined>
     'data-auto-fill'?: never;
     'data-flex'?: never;
     'data-fill'?: never;
+    'data-text-insets'?: never;
+    'data-control-insets'?: never;
 }>;
 interface GridCommonProps {
     children?: KerfUiContent;
@@ -3472,6 +3543,10 @@ interface GridCommonProps {
      * flex layout use `flex` instead. Defaults to false.
      */
     fill?: boolean;
+    /** Physical sides that receive the standard 17px text inset. */
+    textInsets?: Sides;
+    /** Physical sides that receive the standard 8px control inset. Text insets win on overlap. */
+    controlInsets?: Sides;
     className?: string;
     /** Safe `data-*` metadata; Grid-owned structural attributes remain protected. */
     rootAttributes?: GridRootAttributes;
@@ -3491,9 +3566,9 @@ type GridProps = GridCommonProps & ({
     autoFill?: boolean;
 });
 /** Render equal tracks with a fixed count or a responsive minimum width. */
-declare function Grid({ children, selectionMode, ariaLabel, columns, minColumnWidth, autoFill, gap, flex, fill, className, rootAttributes, slot, }: GridProps): kerfjs.SafeHtml;
+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, UiSpaceName };
+export { CssFlex, CssFlexKeyword, CssLength, Grid, type GridProps, Sides, UiSpaceName };
 ```
 
 ## `@kerfjs/ui/spacer`
@@ -3522,7 +3597,7 @@ export { CssLength, Spacer, type SpacerProps, UiSpaceName };
 ## `@kerfjs/ui/token-search-model`
 
 ```ts
+export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, l as createTokenSearchModel } from './token-search-model-DTcTXWMS.js';
 import 'kerfjs';
-export { d as TokenSearchModel, e as TokenSearchModelOptions, f as TokenSearchResolvedToken, g as TokenSearchRule, h as TokenSearchState, i as TokenSearchSuggestion, l as createTokenSearchModel } from './token-search-field-CVGwDn2y.js';
 import './semantic-content-BbzjvSu9.js';
 ```