@kerfjs/ui 5.0.0-beta.76 → 5.0.0-beta.78

package/ai/components/toolbar.md

@@ -9,6 +9,7 @@
 Leading, centered, and trailing toolbar composition.
 
 - Compose application chrome or a page, panel, or dialog heading with leading, center, and trailing regions.
+- Use typed hideBelow/showBelow lengths with wireToolbarVisibility(root) for per-item toolbar priority; keep primary actions available and provide a showBelow overflow alternative.
 
 **Not when:**
 
@@ -17,13 +18,15 @@ Leading, centered, and trailing toolbar composition.
 ## Imports
 
 - JavaScript: `@kerfjs/ui/toolbar` — exports `Toolbar`.
+- JavaScript: `@kerfjs/ui/wire-toolbar-visibility` — exports `wireToolbarVisibility`.
 - CSS: the browser build of `@kerfjs/ui/toolbar` pulls its CSS automatically; import `@kerfjs/ui/toolbar.css` manually only without the `browser` export condition.
 - Wiring: `wireScrollDividers` from `@kerfjs/ui/wire-scroll-dividers` (optional).
+- Wiring: `wireToolbarVisibility` from `@kerfjs/ui/wire-toolbar-visibility` (optional).
 - Declared side effects: browser-condition-css.
 
 ## Props
 
-Exact prop names and types: [`@kerfjs/ui/toolbar`](../public-api-signatures-v1.md#kerfjsuitoolbar), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
+Exact prop names and types: [`@kerfjs/ui/toolbar`](../public-api-signatures-v1.md#kerfjsuitoolbar), [`@kerfjs/ui/wire-toolbar-visibility`](../public-api-signatures-v1.md#kerfjsuiwire-toolbar-visibility), [`@kerfjs/ui/wire-scroll-dividers`](../public-api-signatures-v1.md#kerfjsuiwire-scroll-dividers) in `public-api-signatures-v1.md`. Do not infer props from examples.
 
 **Variants (configure, do not restyle):**
 
@@ -38,13 +41,14 @@ Exact prop names and types: [`@kerfjs/ui/toolbar`](../public-api-signatures-v1.m
 - trailing groups and a standalone primary wa-button wrap instead of clipping
 - outer inset independently configurable from zone gap
 - app bar or bottom bar claiming its screen edges (safeAreaEdges)
+- typed hideBelow/showBelow thresholds at the nearest Toolbar content width
 
 ## Composition
 
 - Parents: any.
 - Contexts: `application-chrome`, `page-header`, `panel-header`, `dialog-header`.
 - Children: only [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md).
-- Built from: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md).
+- Built from: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md), [PopupMenu](./popup-menu.md).
 
 Zones (a zone is bound to JSX only through its listed prop; never assume the zone id is a prop):
 
@@ -56,12 +60,16 @@ Zones (a zone is bound to JSX only through its listed prop; never assume the zon
 
 **The app owns:** actions; command availability; responsive relocation; which screen edges an app bar or bottom bar outside a Pane header or footer claims for device safe areas (safeAreaEdges).
 
-**Wiring:** `wireScrollDividers` is optional.
+**Wiring:** `wireScrollDividers`, `wireToolbarVisibility` is optional.
 
 **Wiring-owned state attributes** — never render, remove, or branch on these as app state:
 
 - `data-scroll-overflow` on `the targets scroller` (`wireScrollDividers`): The physical edges, in canonical t/r/b/l order, beyond which content is scrolled out of view; absent when nothing is hidden (content that fits never reports its far edges). Re-applied if a re-render drops it.
 - `data-scroll-divider` on `a Toolbar named as targets chrome` (`wireScrollDividers`): The sides, in t/r/b/l order, on which this chrome currently draws its scroll divider: the side facing the scroller while content is hidden beyond it. Re-applied if a re-render drops it.
+- `data-toolbar-width-hidden` on `ToolbarText, ToolbarControlGroup and its paired busy status` (`wireToolbarVisibility`): True when typed hideBelow/showBelow thresholds hide this item at the nearest Toolbar content width. Re-applied after rendering; disposal restores prior markers.
+- `data-toolbar-visibility-probe` on `private aria-hidden measurement boxes under Toolbar` (`wireToolbarVisibility`): Internal out-of-flow CSS length resolver; created and removed by wireToolbarVisibility.
+- `data-morph-preserve` on `private aria-hidden measurement boxes and visibility state children` (`wireToolbarVisibility`): Keeps helper-owned geometry and state across Kerf renders; replacement and explicit removal are repaired, and disposal removes them.
+- `data-toolbar-visibility-state` on `private hidden children of width-managed items and paired busy statuses` (`wireToolbarVisibility`): Preserves actual CSS visibility while rendering removes a transient parent marker, preventing geometry-driven render feedback.
 
 ## Geometry
 
@@ -92,6 +100,6 @@ Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-
 
 ## Related
 
-- Components: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md).
+- Components: [ToolbarText](./toolbar-text.md), [ToolbarControlGroup](./toolbar-control-group.md), [Button](./wa-button.md), [PopupMenu](./popup-menu.md).
 - Docs: [`docs/component-selection.md`](../../docs/component-selection.md), [`docs/component-selection.md#ambiguous-choices`](../../docs/component-selection.md#ambiguous-choices).
 - UX catalog route: `?component=toolbar`.

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.76` and `kerfjs@5.0.0-beta.76`. 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.78` and `kerfjs@5.0.0-beta.78`. 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`
 
@@ -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,9 +374,9 @@ 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`
@@ -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;
@@ -1264,100 +1285,19 @@ export { type ScrollDividerTarget, type WireScrollDividersOptions, wireScrollDiv
 ## `@kerfjs/ui/nav-stack`
 
 ```ts
-import * as kerfjs from 'kerfjs';
-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';
+export { c as NavStack, N as NavStackProps, d as NavStackToolbarConfig, a as NavStackView, e as NavStackViewBottomToolbar, f as NavStackViewToolbar } from './nav-stack-B1Qc2e5q.js';
+import 'kerfjs';
+import './semantic-content-BbzjvSu9.js';
+import './list.js';
+import './flex-alignment-4ms8ZbV8.js';
 import './sides-BPSWde0A.js';
-
-/**
- * One entry in a {@link NavStack}. The app owns the stack as an array (usually a
- * signal); `NavStack` renders it and `wireNavStack` animates the transitions.
- */
-interface NavStackView {
-    /** Stable identity for keyed reconcile and transition direction. */
-    key: string;
-    content: KerfUiContent;
-    /** Background of this view's scrolling work surface. */
-    appearance?: PaneAppearance;
-    /** Title shown in the top toolbar for this view. */
-    title?: string;
-    /** Leading groups for this view's top toolbar, after the back control and before the title. */
-    leading?: KerfUiContent;
-    /** Center content for this view's top toolbar (placed per `toolbarConfig.centerAlign`). */
-    center?: KerfUiContent;
-    /** Trailing actions for this view's top toolbar. */
-    toolbar?: KerfUiContent;
-    /** Fixed chrome below this view's toolbar, above its scrolling content. */
-    header?: KerfUiContent;
-    /** Bottom toolbar for this view. Cross-fades with the top chrome on navigation. */
-    bottomToolbar?: KerfUiContent;
-}
-/**
- * The top toolbar's configuration. Its `ToolbarConfig` forwards to the real
- * `Toolbar` the stack renders; by default that toolbar draws no divider and
- * claims the top and side safe-area edges the stack still touches.
- */
-interface NavStackToolbarConfig extends ToolbarConfig {
-    /** Accessible name of the top toolbar (default: none). */
-    label?: string;
-    /** Size of the view title's `ToolbarText` (default `large`). */
-    titleSize?: ToolbarTextSize;
-    /** Expose the view title as a heading at this level (default: a plain span). */
-    headingLevel?: HeadingLevel;
-}
-interface NavStackProps {
-    id: string;
-    /** Accessible name for the stack region. */
-    label: string;
-    /** The stack, root first; the last entry is the active top view. */
-    views: NavStackView[];
-    /** Accessible label for the icon-only back control (default "Back"). */
-    backLabel?: string;
-    /** The back control's icon (default a chevron-left `LucideIcon`). */
-    backIcon?: KerfUiContent;
-    /**
-     * Visible text beside the back icon, such as the previous view's title
-     * (default: icon only). When set, the text names the control and
-     * `backLabel` is not used.
-     */
-    backText?: string;
-    /** The top toolbar's configuration, forwarded to its `Toolbar`. */
-    toolbarConfig?: NavStackToolbarConfig;
-    /** Persistent last group in every view's top toolbar, supplied by a hosting panel. */
-    panelToggle?: KerfUiContent;
-    /** Hide the top toolbar entirely (rare — a fully custom-chrome view). */
-    hideToolbar?: boolean;
-    /** Optional persistent bottom toolbar used when the active view does not provide one. */
-    bottomToolbar?: KerfUiContent;
-    /**
-     * The line under the top chrome and over the bottom toolbar, where they
-     * meet the active view. `scroll` (default) shows the chrome's line only
-     * while the view's content is scrolled beneath it, and the bottom
-     * toolbar's only while more content lies below — never when the content
-     * fits — once `wireScrollDividers` (`@kerfjs/ui/wire-scroll-dividers`) is
-     * wired above the stack; unwired, neither shows. `always` shows both
-     * without the wiring; `none` neither, even when wired. The line is drawn
-     * inside the chrome, so no state moves the chrome or the content. A
-     * `toolbarConfig.dividerSides` edge is the Toolbar's own and is unaffected.
-     */
-    chromeDividers?: 'scroll' | 'always' | 'none';
-    className?: string;
-    /** Native named-slot assignment when composed inside a web component. */
-    slot?: string;
-}
-/**
- * A navigation stack (iOS-style push/pop). Renders every entry stacked, the last
- * one active; `@kerfjs/ui/wire-nav-stack`'s `wireNavStack` slides the content and
- * cross-fades the chrome across a change. Its top chrome is a real `Toolbar`: the
- * back control and title lead, the active view's `leading` / `center` / `toolbar`
- * content fills the zones, and `toolbarConfig` configures it. 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, backIcon, backText, toolbarConfig, panelToggle, hideToolbar, bottomToolbar, chromeDividers, className, slot, }: NavStackProps): kerfjs.SafeHtml;
-
-export { NavStack, type NavStackProps, type NavStackToolbarConfig, type NavStackView };
+import './css-values.js';
+import './pane.js';
+import './panel-toolbar-CL9tYOkh.js';
+import './toolbar.js';
+import './lucide-icon.js';
+import 'lucide';
+import './toolbar-text.js';
 ```
 
 ## `@kerfjs/ui/wire-nav-stack`
@@ -1388,13 +1328,18 @@ 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 { N as NavStackProps, a as NavStackView } from './nav-stack-B1Qc2e5q.js';
 import { ResizableRegionProps } from './resizable-region.js';
-import './toolbar.js';
+import './list.js';
+import './flex-alignment-4ms8ZbV8.js';
 import './sides-BPSWde0A.js';
+import './css-values.js';
 import './pane.js';
+import './panel-toolbar-CL9tYOkh.js';
+import './toolbar.js';
+import './lucide-icon.js';
+import 'lucide';
 import './toolbar-text.js';
-import './css-values.js';
 
 /**
  * The roomy list pane's `ResizableRegion`: its committed `size` and `min` /
@@ -1409,7 +1354,7 @@ interface SplitViewResizable extends Pick<ResizableRegionProps, 'separator' | 'h
     max: number;
 }
 /** One compact view's top- and bottom-toolbar content (see `NavStackView`). */
-type SplitViewCompactViewToolbars = Pick<NavStackView, 'leading' | 'center' | 'toolbar' | 'bottomToolbar'>;
+type SplitViewCompactViewToolbars = Pick<NavStackView, 'toolbar' | 'bottomToolbar'>;
 /**
  * The compact `NavStack`'s configuration: its toolbar configuration, back
  * control, persistent bottom toolbar, and chrome dividers forward to the
@@ -1490,6 +1435,7 @@ type PaneRootAttributes = Readonly<Record<`data-${string}`, string | undefined>
     'data-chrome-placement'?: never;
     'data-chrome-dividers'?: never;
     'data-appearance'?: never;
+    'data-deep-inset'?: never;
 }>;
 /** How a Pane's header and footer relate to its scrolling content. */
 type PaneChromePlacement = 'fixed' | 'auto';
@@ -1529,6 +1475,8 @@ interface PaneProps {
     chromeDividers?: PaneChromeDividers;
     /** Paint the scrolling work surface with the shared lowered-surface color. */
     appearance?: PaneAppearance;
+    /** Add an extra 8px inline gutter to scrolling content (default: false). */
+    deepInset?: boolean;
     /** Root semantics. Defaults to `div`. */
     element?: PaneElement;
     /** Scrolling content semantics. Defaults to `div`. */
@@ -1563,14 +1511,14 @@ interface PaneProps {
  * or a CollapsiblePanel) forwards, so the app configures that pane instead of
  * styling it. An omitted or `undefined` field keeps the composite's default.
  */
-type PaneConfig = Pick<PaneProps, 'contentElement' | 'contentLabel' | 'separators' | 'safeAreaEdges' | 'chromeDividers' | 'appearance'>;
+type PaneConfig = Pick<PaneProps, 'contentElement' | 'contentLabel' | 'separators' | 'safeAreaEdges' | 'chromeDividers' | 'appearance' | 'deepInset'>;
 /**
  * An unpadded application column with optional fixed header/footer slots and one
  * scrolling vertical content owner. Separator lines are independently opt-in on
  * each logical edge, so the same component works as a sidebar, main area,
  * inspector, or dialog column.
  */
-declare function Pane({ header, children, footer, chromePlacement, chromeDividers, appearance, element, contentElement, separators, safeAreaEdges, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
+declare function Pane({ header, children, footer, chromePlacement, chromeDividers, appearance, deepInset, element, contentElement, separators, safeAreaEdges, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
 
 export { Pane, type PaneAppearance, type PaneChromeDividers, type PaneChromePlacement, type PaneConfig, type PaneContentElement, type PaneElement, type PaneProps, type PaneSeparatorSide };
 ```
@@ -1580,16 +1528,16 @@ 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 { 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 { a as PanelToolbar, b as PanelChromePlacement, c as PanelBottomToolbar, d as PanelToggle } from './panel-toolbar-CL9tYOkh.js';
+import { a as PanelToolbar, c as PanelBottomToolbar, b as PanelChromePlacement, d as PanelToggle } from './panel-toolbar-CL9tYOkh.js';
 import { ToolbarConfig } from './toolbar.js';
+import './toolbar-text.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';
 
@@ -1711,19 +1659,11 @@ interface WorkbenchPanelBase {
     restorePosition?: ResizableRegionRestorePosition;
 }
 /** The original static panel body: one toolbar, optional fixed chrome, and one Pane. */
-interface WorkbenchStaticPanel extends WorkbenchPanelBase {
-    content: KerfUiContent;
+interface WorkbenchStaticPanel extends WorkbenchPanelBase, NavPane<WorkbenchPanelToolbar, WorkbenchPanelBottomToolbar> {
     /** The composed toolbar; marked groups and its toggle relocate on collapse. */
     toolbar?: WorkbenchPanelToolbar;
-    header?: KerfUiContent;
-    headerList?: ListConfig;
     headerPlacement?: WorkbenchChromePlacement;
-    footer?: KerfUiContent;
-    footerList?: ListConfig;
-    bottomToolbar?: WorkbenchPanelBottomToolbar;
     footerPlacement?: WorkbenchChromePlacement;
-    /** Configuration for the static toolbar panel's Pane. */
-    pane?: PaneConfig;
     navStack?: never;
 }
 /** A panel whose active NavStack view supplies the toolbar, fixed header, and scroll body. */
@@ -2191,6 +2131,8 @@ interface TabScaffoldTabBase<Id extends string> {
     content: KerfUiContent;
     /** Background of this scene's scrolling work surface. */
     appearance?: PaneAppearance;
+    /** Add an extra 8px inline gutter to a plain scene's scrolling content. */
+    deepInset?: boolean;
 }
 /** A tab with an optional count or short-status badge. */
 interface TabScaffoldTabCountBadge {
@@ -2433,15 +2375,15 @@ import './toolbar.js';
 import './sides-BPSWde0A.js';
 import './pane.js';
 import './workbench.js';
+import './nav-stack-B1Qc2e5q.js';
 import './list.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-CL9tYOkh.js';
 import './lucide-icon.js';
 import 'lucide';
+import './toolbar-text.js';
+import './resizable-region.js';
 
 /**
  * Controlled, stateless component-catalog shell: a `Workbench` whose left rail
@@ -2528,15 +2470,15 @@ import './semantic-content-BbzjvSu9.js';
 import './sides-BPSWde0A.js';
 import './pane.js';
 import './workbench.js';
+import './nav-stack-B1Qc2e5q.js';
 import './list.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-CL9tYOkh.js';
 import './lucide-icon.js';
 import 'lucide';
+import './toolbar-text.js';
+import './resizable-region.js';
 
 /**
  * Standard resource labels for a Kerf catalog detail footer. Keep these labels
@@ -2751,6 +2693,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;
@@ -3312,27 +3255,53 @@ declare function LucideIcon({ icon, name, appearance, className, color, inline,
 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
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssLength } from './css-values.js';
 
 type DialogSurfaceSize = 'small' | 'medium' | 'large';
 type DialogSurfacePresentation = 'modal' | 'side-sheet' | 'fullscreen';
 type SurfaceInset = 'none' | 'compact' | 'comfortable';
+type DialogSurfaceMaxHeight = CssLength | 'viewport';
 interface DialogSurfaceProps {
     children: KerfUiContent;
     size?: DialogSurfaceSize;
     presentation?: DialogSurfacePresentation;
+    /** Modal preferred width. Takes precedence over size, within the viewport cap. */
+    preferredWidth?: CssLength;
     bodyInset?: SurfaceInset;
     footerInset?: SurfaceInset;
+    /** Modal edge clearance. Omit to retain Web Awesome's default viewport cap. */
+    viewportGutter?: CssLength;
+    /** Modal height cap, bounded by the dynamic viewport minus both gutters. */
+    maxHeight?: DialogSurfaceMaxHeight;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
 }
 /** Configure recurring Web Awesome dialog geometry without consumer ::part() CSS. */
-declare function DialogSurface({ children, size, presentation, bodyInset, footerInset, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
+declare function DialogSurface({ children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
 type PopupSurfaceInset = 'standard' | 'compact' | 'list-zero';
 interface PopupSurfaceProps {
     children: KerfUiContent;
@@ -3344,7 +3313,7 @@ interface PopupSurfaceProps {
 /** Configure recurring Web Awesome dropdown-menu geometry without consumer ::part() CSS. */
 declare function PopupSurface({ children, inset, className, slot, }: PopupSurfaceProps): kerfjs.SafeHtml;
 
-export { DialogSurface, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceSize, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset };
+export { DialogSurface, type DialogSurfaceMaxHeight, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceSize, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset };
 ```
 
 ## `@kerfjs/ui/text`
@@ -3353,6 +3322,7 @@ 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'> & {
@@ -3384,6 +3354,8 @@ type TextCommonProps = Omit<KerfBaseAttrs, 'children' | 'class' | 'className'> &
     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. */
@@ -3407,9 +3379,9 @@ 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, color, size, font, border, flush, lineHeight, wrap, maxLines, children, class: classValue, className, style, ...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`