@kerfjs/ui 5.0.0-beta.100 → 5.0.0-beta.101

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.100` and `kerfjs@5.0.0-beta.100`. 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.101` and `kerfjs@5.0.0-beta.101`. 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`
 
@@ -166,6 +166,7 @@ import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as Sides } from './sides-BPSWde0A.js';
 import { PaneSeparatorSide } from './pane.js';
 import './scroll-clearance-BikHljTc.js';
+import './css-values.js';
 
 type ToolbarPosition = 'header' | 'footer';
 /** Control-band density: `default` (60px with 44px groups) or `compact`. */
@@ -253,7 +254,12 @@ 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. */
+    /**
+     * Use loud-toolbar foregrounds on a toolbar painted with the inverse loud
+     * fill, matching dark control groups; like them it inverts with the color
+     * scheme. Over a dark photo or scrim keep the default tone inside a
+     * `BackdropImage` overlay, which takes the dark scheme under its scrim.
+     */
     tone?: ToolbarTextTone;
     /** Hide below this Toolbar content width; requires wireToolbarVisibility. */
     hideBelow?: CssLength;
@@ -326,6 +332,8 @@ import { CssLength } from './css-values.js';
 
 type ToolbarControlGroupAppearance = 'contained' | 'borderless';
 type ToolbarControlGroupTone = 'default' | 'dark';
+/** Surface material: the opaque `solid` fill (default) or translucent `glass`. */
+type ToolbarControlGroupMaterial = 'solid' | 'glass';
 /** Quiet palette for a contained, single decorative icon tile. */
 type ToolbarControlGroupTileTone = 'neutral' | 'brand' | 'success' | 'warning' | 'danger';
 type ToolbarControlGroupButtonAppearance = 'plain' | 'push';
@@ -366,6 +374,15 @@ interface ToolbarControlGroupProps {
     single?: boolean;
     appearance?: ToolbarControlGroupAppearance;
     tone?: ToolbarControlGroupTone;
+    /**
+     * `glass` paints the group on the translucent chrome material (backdrop
+     * blur and saturation) with a specular edge and a soft shadow, for a group
+     * floating over imagery or a clear toolbar. Controls take the normal text
+     * color so they keep AA over any content; the fill turns opaque under
+     * reduced transparency, increased contrast, static effects, or without
+     * backdrop-filter support. A borderless group has no surface and ignores it.
+     */
+    material?: ToolbarControlGroupMaterial;
     /** 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;
@@ -421,9 +438,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, 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;
+declare function ToolbarControlGroup({ children, label, className, expanded, single, appearance, tone, material, 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 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 };
+export { ToolbarActionLink, type ToolbarActionLinkProps, ToolbarControlGroup, type ToolbarControlGroupAppearance, type ToolbarControlGroupButtonAppearance, type ToolbarControlGroupContent, type ToolbarControlGroupDensity, type ToolbarControlGroupExpandedOverflow, type ToolbarControlGroupFocusRing, type ToolbarControlGroupMaterial, 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`
@@ -1531,6 +1548,31 @@ declare function wireScrollDividers(root: Root, { targets }?: WireScrollDividers
 export { type ScrollDividerTarget, type WireScrollDividersOptions, wireScrollDividers };
 ```
 
+## `@kerfjs/ui/wire-overlay-sheets`
+
+```ts
+/**
+ * Give every resizable core `kerfjs/overlay` bottom sheet opened in
+ * `container` the resize grabber a `resizable` `DialogSurface` sheet has: a
+ * `role="separator"` at the sheet's top edge that resizes its visible height
+ * by drag or keyboard (arrows, Page Up/Down, Home, End), between
+ * `--kui-overlay-sheet-min-height` (160px) and the sheet's cap below the top
+ * safe area. A sheet opts in with the `kui-overlay-sheet-resizable` class
+ * (`overlay()` and the promise dialogs alike) and opens at its content
+ * height each time.
+ *
+ * kerf appends each overlay to its `container` (`document.body` by
+ * default), so call this once per container you open sheets in. The grabber
+ * is `data-morph-preserve` and returns to the top of the sheet after each
+ * re-render of the overlay's content. Requires
+ * `@kerfjs/ui/overlay-sheet.css`. Returns a disposer that removes every
+ * grabber and stops watching.
+ */
+declare function wireOverlaySheets(container?: ParentNode): () => void;
+
+export { wireOverlaySheets };
+```
+
 ## `@kerfjs/ui/wire-list-reorder`
 
 ```ts
@@ -1601,16 +1643,16 @@ export { wireListFocusScroll };
 ## `@kerfjs/ui/nav-stack`
 
 ```ts
-export { c as NavStack, d as NavStackBottomToolbarPresentation, e as NavStackChromePresentation, N as NavStackProps, f as NavStackToolbarConfig, a as NavStackView, g as NavStackViewBottomToolbar, h as NavStackViewToolbar } from './nav-stack-VXTumzKa.js';
+export { c as NavStack, d as NavStackBottomToolbarPresentation, e as NavStackChromePresentation, N as NavStackProps, f as NavStackToolbarConfig, a as NavStackView, g as NavStackViewBottomToolbar, h as NavStackViewToolbar } from './nav-stack-CU_0dKtI.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
+import './pane.js';
+import './scroll-clearance-BikHljTc.js';
+import './css-values.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
-import './scroll-clearance-BikHljTc.js';
 import './sides-BPSWde0A.js';
-import './css-values.js';
-import './pane.js';
 import './panel-toolbar-vg6Ir5Dy.js';
 import './toolbar.js';
 import './lucide-icon.js';
@@ -1646,15 +1688,15 @@ 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-VXTumzKa.js';
+import { N as NavStackProps, a as NavStackView } from './nav-stack-CU_0dKtI.js';
 import { ResizableRegionProps } from './resizable-region.js';
+import './pane.js';
+import './scroll-clearance-BikHljTc.js';
+import './css-values.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
-import './scroll-clearance-BikHljTc.js';
 import './sides-BPSWde0A.js';
-import './css-values.js';
-import './pane.js';
 import './panel-toolbar-vg6Ir5Dy.js';
 import './toolbar.js';
 import './lucide-icon.js';
@@ -1751,6 +1793,38 @@ export { SplitView, type SplitViewCompactStack, type SplitViewCompactViewToolbar
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
 import { S as ScrollClearance } from './scroll-clearance-BikHljTc.js';
+import { CssColor } from './css-values.js';
+
+/**
+ * What clear (fully transparent) chrome fades in as content scrolls beneath
+ * it: `none` stays clear; `material` fades in the translucent chrome
+ * material; `surface` fades in the opaque surface. The fade tracks the scroll
+ * over `scrollEdgeDistance` (opacity only), from the scroll state
+ * `wireScrollDividers` reports; unwired, the chrome stays clear.
+ */
+type ScrollEdge = 'none' | 'material' | 'surface';
+
+/** The color scheme an app declares for a {@link SurfaceTint}'s color. */
+type SurfaceTintScheme = 'light' | 'dark';
+/**
+ * A scoped tint for a layout surface: the app's color (usually sampled from
+ * artwork it already knows) and the scheme that color belongs to. Kerf does no
+ * color detection; `scheme` says whether the color reads as a light or a dark
+ * surface. Inside the scope the surface, raised surface, text, quiet text, and
+ * everything built on them (quiet fills, separators' backdrop, the chrome
+ * material) re-derive from the color, with lightness clamped so text keeps
+ * WCAG AA over any color.
+ */
+interface SurfaceTint {
+    color: CssColor;
+    scheme: SurfaceTintScheme;
+    /**
+     * An optional accent (usually the artwork's most vivid color). The scope's
+     * brand ramp re-derives from it: loud fills and their text, brand text and
+     * links, text on brand fills, and the focus ring, each clamped to keep AA.
+     */
+    accent?: CssColor;
+}
 
 /**
  * Logical pane sides: where a {@link Pane} can show a separator and where it can
@@ -1774,10 +1848,16 @@ type PaneRootAttributes = Readonly<Record<`data-${string}`, string | undefined>
     'data-chrome-placement'?: never;
     'data-chrome-dividers'?: never;
     'data-appearance'?: never;
+    'data-background'?: never;
+    'data-kui-tint'?: never;
+    'data-kui-tint-accent'?: never;
     'data-deep-inset'?: never;
     'data-outlined'?: never;
     'data-scroll-clearance'?: never;
     'data-header-presentation'?: never;
+    'data-header-material'?: never;
+    'data-scroll-edge'?: never;
+    'data-scroll-edge-distance'?: never;
     'data-header-overlay'?: never;
 }>;
 /** How a Pane's header and footer relate to its scrolling content. */
@@ -1792,8 +1872,12 @@ type PaneChromeDividers = 'scroll' | 'always' | 'none';
  * How a Pane's header relates to its scrolling content: `docked` in its own
  * row above the content, or `overlay` laid over the content's top edge on the
  * translucent chrome material, so content scrolls visibly beneath it.
+ * `clear` lays it over
+ * the same edge fully transparent, for chrome over imagery: legibility comes
+ * from glass control groups or a scrim, and with `scrollEdge="material"` the
+ * chrome material fades in once content scrolls beneath it.
  */
-type PaneHeaderPresentation = 'docked' | 'overlay';
+type PaneHeaderPresentation = 'docked' | 'overlay' | 'clear';
 /** Background treatment of the Pane's scrolling work surface. */
 type PaneAppearance = 'default' | 'sunken';
 interface PaneProps {
@@ -1839,8 +1923,38 @@ interface PaneProps {
      * content passing beneath it.
      */
     headerPresentation?: PaneHeaderPresentation;
+    /**
+     * With `headerPresentation="clear"`, `material` fades the chrome material
+     * in behind the header once content scrolls beneath it (default `none`).
+     */
+    scrollEdge?: ScrollEdge;
+    /**
+     * The scroll distance, in CSS pixels, over which the scroll edge fades in
+     * (default 60).
+     */
+    scrollEdgeDistance?: number;
     /** Paint the scrolling work surface with the shared lowered-surface color. */
     appearance?: PaneAppearance;
+    /**
+     * Paint the whole pane, header and footer included, in an app-chosen color
+     * (`uiColor('surface-raised')`, `fillColor('#1f2a44')`, or `colorVar(…)`
+     * from `@kerfjs/ui/css-values`). It replaces the appearance's fill: a sunken
+     * pane drops its lowered color and grain. Omitted, the pane keeps its
+     * default (transparent, or the sunken surface). Forced colors paint
+     * `Canvas`. Keep text at AA over the color; a dark color needs a matching
+     * tint or dark tones for its content.
+     */
+    background?: CssColor;
+    /**
+     * A scoped tint: `{ color, scheme }`, the app's color and the scheme it
+     * belongs to. The pane paints the tinted surface (unless `background` is
+     * set) and its whole subtree, chrome material and quiet fills included,
+     * re-derives its surface and text tokens from the color with lightness
+     * clamped to keep text at WCAG AA. Without relative color syntax, or under
+     * `prefers-contrast: more`, the scope keeps the plain palette in the
+     * declared scheme.
+     */
+    tint?: SurfaceTint;
     /**
      * Clear chrome that lies over the scrolling content's block-start and/or
      * block-end edge, such as a `DialogSurface` floating footer over a filling
@@ -1891,16 +2005,16 @@ 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' | 'headerPresentation' | 'appearance' | 'deepInset' | 'scrollClearance' | 'tabIndex' | 'outlined'>;
+type PaneConfig = Pick<PaneProps, 'contentElement' | 'contentLabel' | 'separators' | 'safeAreaEdges' | 'chromeDividers' | 'headerPresentation' | 'scrollEdge' | 'scrollEdgeDistance' | 'appearance' | 'background' | 'tint' | 'deepInset' | 'scrollClearance' | 'tabIndex' | 'outlined'>;
 /**
  * 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, headerPresentation, appearance, deepInset, scrollClearance, tabIndex, outlined, element, contentElement, separators, safeAreaEdges, id, label, contentLabel, className, headerClassName, contentClassName, footerClassName, rootAttributes, slot, }: PaneProps): kerfjs.SafeHtml;
+declare function Pane({ header, children, footer, chromePlacement, chromeDividers, headerPresentation, scrollEdge, scrollEdgeDistance, appearance, background, tint, deepInset, scrollClearance, tabIndex, outlined, 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 PaneHeaderPresentation, type PaneProps, type PaneSeparatorSide, ScrollClearance };
+export { Pane, type PaneAppearance, type PaneChromeDividers, type PaneChromePlacement, type PaneConfig, type PaneContentElement, type PaneElement, type PaneHeaderPresentation, type PaneProps, type PaneSeparatorSide, ScrollClearance, type ScrollEdge, type SurfaceTint, type SurfaceTintScheme };
 ```
 
 ## `@kerfjs/ui/workbench`
@@ -1908,14 +2022,14 @@ 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-VXTumzKa.js';
+import { b as NavPane, N as NavStackProps } from './nav-stack-CU_0dKtI.js';
 import { ListConfig } from './list.js';
 import { PaneConfig } from './pane.js';
 import { ResizableRegionSeparator, ResizableRegionCollapseMotion, ResizableRegionContentOverflow, ResizableRegionPresentation, ResizableRegionRestorePosition } from './resizable-region.js';
 import { a as PanelToolbar, c as PanelBottomToolbar, b as PanelChromePlacement, d as PanelToggle } from './panel-toolbar-vg6Ir5Dy.js';
 import { ToolbarConfig } from './toolbar.js';
-import './toolbar-text.js';
 import './css-values.js';
+import './toolbar-text.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './scroll-clearance-BikHljTc.js';
@@ -2528,7 +2642,8 @@ export { type SidebarStorage, type WireSidebarOptions, type WireSidebarPanel, wi
 ```ts
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import { PaneAppearance } from './pane.js';
+import { PaneAppearance, SurfaceTint, ScrollEdge } from './pane.js';
+import { CssColor } from './css-values.js';
 import './scroll-clearance-BikHljTc.js';
 
 interface TabNavigatorTabBase<Id extends string> {
@@ -2540,6 +2655,17 @@ interface TabNavigatorTabBase<Id extends string> {
     content: KerfUiContent;
     /** Background of this scene's scrolling work surface. */
     appearance?: PaneAppearance;
+    /**
+     * Paint this scene in an app-chosen color (a `@kerfjs/ui/css-values` color
+     * builder). It replaces the appearance's fill. Forced colors paint `Canvas`.
+     */
+    background?: CssColor;
+    /**
+     * A scoped tint (`{ color, scheme }`) for this scene: its surfaces and every
+     * descendant re-derive their surface and text tokens from the app's color
+     * in the declared scheme, with lightness clamped to keep text at WCAG AA.
+     */
+    tint?: SurfaceTint;
     /** Add 8px to every side of a plain scene's scrolling content. */
     deepInset?: boolean;
     /** Opt into keyboard (`0`) or programmatic (`-1`) focus on this scene. */
@@ -2585,8 +2711,13 @@ type TabNavigatorTab<Id extends string = string> = TabNavigatorTabBase<Id> & (Ta
  * How a {@link TabNavigator}'s tab bar relates to the active scene: `docked`
  * below it, or `overlay` laid over its bottom edge on the translucent chrome
  * material, so the scene's content scrolls visibly beneath the bar.
+ * `clear` lays it over
+ * the same edge fully transparent, for chrome over imagery: legibility comes
+ * from glass control groups or a scrim, and with `scrollEdge="material"` the
+ * chrome material fades in once content scrolls beneath
+ * it, until the scene scrolls to its end.
  */
-type TabNavigatorBarPresentation = 'docked' | 'overlay';
+type TabNavigatorBarPresentation = 'docked' | 'overlay' | 'clear';
 interface TabNavigatorProps<Id extends string = string> {
     id: string;
     /** Accessible name for the tab bar. */
@@ -2625,6 +2756,29 @@ interface TabNavigatorProps<Id extends string = string> {
      * toward the normal text color to keep AA over the content beneath.
      */
     barPresentation?: TabNavigatorBarPresentation;
+    /**
+     * With `barPresentation="clear"`, `material` fades the chrome material in
+     * behind the bar while the active scene continues beneath it (default
+     * `none`).
+     */
+    scrollEdge?: ScrollEdge;
+    /**
+     * The scroll distance, in CSS pixels, over which the scroll edge fades in
+     * (default 60).
+     */
+    scrollEdgeDistance?: number;
+    /**
+     * Paint the navigator, and its docked tab bar, in an app-chosen color (a
+     * `@kerfjs/ui/css-values` color builder) instead of the surface. A tab's own
+     * `background` paints its scene. Forced colors paint `Canvas`.
+     */
+    background?: CssColor;
+    /**
+     * A scoped tint (`{ color, scheme }`) for the navigator, its bar, and every scene: its surfaces and every
+     * descendant re-derive their surface and text tokens from the app's color
+     * in the declared scheme, with lightness clamped to keep text at WCAG AA.
+     */
+    tint?: SurfaceTint;
     className?: string;
     /** Native named-slot assignment when composed inside a web component. */
     slot?: string;
@@ -2637,7 +2791,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, separator, chromeDividers, barPresentation, className, slot, }: TabNavigatorProps<Id>): SafeHtml;
+declare function TabNavigator<Id extends string>({ id, label, tabs, active, separator, chromeDividers, barPresentation, scrollEdge, scrollEdgeDistance, background, tint, className, slot, }: TabNavigatorProps<Id>): SafeHtml;
 
 export { TabNavigator, type TabNavigatorBarPresentation, type TabNavigatorProps, type TabNavigatorTab };
 ```
@@ -2817,12 +2971,12 @@ import './toolbar.js';
 import './sides-BPSWde0A.js';
 import './pane.js';
 import './scroll-clearance-BikHljTc.js';
+import './css-values.js';
 import './workbench.js';
-import './nav-stack-VXTumzKa.js';
+import './nav-stack-CU_0dKtI.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
-import './css-values.js';
 import './panel-toolbar-vg6Ir5Dy.js';
 import './lucide-icon.js';
 import 'lucide';
@@ -2972,12 +3126,12 @@ import './semantic-content-BbzjvSu9.js';
 import './sides-BPSWde0A.js';
 import './pane.js';
 import './scroll-clearance-BikHljTc.js';
+import './css-values.js';
 import './workbench.js';
-import './nav-stack-VXTumzKa.js';
+import './nav-stack-CU_0dKtI.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
-import './css-values.js';
 import './panel-toolbar-vg6Ir5Dy.js';
 import './lucide-icon.js';
 import 'lucide';
@@ -3027,12 +3181,12 @@ import './semantic-content-BbzjvSu9.js';
 import './sides-BPSWde0A.js';
 import './pane.js';
 import './scroll-clearance-BikHljTc.js';
+import './css-values.js';
 import './workbench.js';
-import './nav-stack-VXTumzKa.js';
+import './nav-stack-CU_0dKtI.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
-import './css-values.js';
 import './panel-toolbar-vg6Ir5Dy.js';
 import './lucide-icon.js';
 import 'lucide';
@@ -4077,6 +4231,143 @@ declare function LucideIcon({ icon, name, appearance, className, color, inline,
 export { LucideIcon, type LucideIconProps, type LucideIconSize, type LucideNode };
 ```
 
+## `@kerfjs/ui/backdrop-image`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { S as StructuralRootAttributes } from './extension-attributes-mu8MFUl0.js';
+import { CssLength, CssColor } from './css-values.js';
+
+/** How a single image fills the backdrop (`object-fit`). */
+type BackdropImageFit = 'cover' | 'contain' | 'fill';
+/** Which part of the image stays in view when it is cropped. */
+type BackdropImagePosition = 'center' | 'top' | 'bottom' | 'left' | 'right' | 'top left' | 'top right' | 'bottom left' | 'bottom right';
+/** Tile the image as a background instead of fitting one copy. */
+type BackdropImageRepeat = 'repeat' | 'repeat-x' | 'repeat-y';
+/**
+ * How far the image lags the scroll: `none` scrolls with the content,
+ * `subtle` lags by 35%, and a number from 0 to 1 is the lag factor (0.5
+ * moves the image at half the scroll speed).
+ */
+type BackdropImageParallax = 'none' | 'subtle' | number;
+/**
+ * A dimming layer under `overlay` content: `bottom` darkens toward the
+ * block end where a title sits, `full` dims the whole image evenly.
+ */
+type BackdropImageScrim = 'none' | 'bottom' | 'full';
+/**
+ * A scroll-linked progressive blur: a statically blurred copy of the image
+ * fades in as the image block scrolls away. Only the copy's opacity (and the
+ * optional dim layer's) animates; the blur itself is set once.
+ */
+interface BackdropImageBlur {
+    /**
+     * CSS blur radius applied once to the copy. Default 24px; with
+     * `blurredSrc` the default is no filter, since that asset is already soft.
+     */
+    radius?: CssLength;
+    /**
+     * An app-supplied pre-blurred or low-resolution copy of the image, used
+     * instead of filtering `src`.
+     */
+    blurredSrc?: string;
+    /**
+     * Peak opacity, from 0 to 1, of a black dim layer that ramps in with the
+     * blur. Default 0 (no dim layer).
+     */
+    dim?: number;
+}
+type BackdropImageRootAttributes = StructuralRootAttributes & Readonly<{
+    'data-component'?: never;
+    'data-blur'?: never;
+    'data-parallax'?: never;
+    'data-scrim'?: never;
+    'data-fade'?: never;
+    'data-repeat'?: never;
+    'data-under-chrome'?: never;
+}>;
+interface BackdropImageCommonProps {
+    /** Image URL. */
+    src: string;
+    /**
+     * Accessible description of the image. Pass `''` for a decorative image
+     * that only sets a mood; assistive technology then skips it.
+     */
+    alt: string;
+    /** Which part of a cropped image stays in view. Default `center`. */
+    position?: BackdropImagePosition;
+    /** Height of the image block. Default 320px (`remify(320)`). */
+    height?: CssLength;
+    /** How far the image lags the scroll. Default `none`. */
+    parallax?: BackdropImageParallax;
+    /**
+     * The color the image fades into at its block end. It also paints the
+     * whole surface, so `children` below the image sit on the same color and
+     * the page reads as one surface. Omit for a hard edge with no surface.
+     */
+    fadeTo?: CssColor;
+    /**
+     * Blur the image progressively as it scrolls away, by cross-fading a
+     * statically blurred copy. Static (unblurred) wherever parallax is.
+     */
+    blur?: BackdropImageBlur;
+    /**
+     * Run the image up beneath the scroller's block-start inset: an overlay or
+     * clear Pane header, NavStack chrome handed to a view's Pane, and the top
+     * safe area, the way a media page's artwork fills the screen behind
+     * transparent chrome. The visible image keeps `height` below that inset,
+     * and `overlay` content stays clear of the chrome. Place the image first in
+     * the Pane's content; it reads the Pane's
+     * `--kui-pane-content-inset-block-start`. Default `false`.
+     */
+    underChrome?: boolean;
+    /** Dim the image under `overlay` content. Default `none`. */
+    scrim?: BackdropImageScrim;
+    /** Content laid over the image's block end, such as a title and actions. */
+    overlay?: KerfUiContent;
+    /** Content that continues below the image on the `fadeTo` surface. */
+    children?: KerfUiContent;
+    id?: string;
+    className?: string;
+    /** Safe `data-*`, `aria-*`, and structural `role` metadata on the root. */
+    rootAttributes?: BackdropImageRootAttributes;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/** One fitted image, with optional responsive candidates. */
+interface BackdropImageSingleProps extends BackdropImageCommonProps {
+    repeat?: undefined;
+    /** Responsive image candidates (`srcset`). */
+    srcset?: string;
+    /** Rendered-size hints for `srcset` (`sizes`). */
+    sizes?: string;
+    /** How the image fills the block. Default `cover`. */
+    fit?: BackdropImageFit;
+}
+/** A tiled background image at its natural size. */
+interface BackdropImageTiledProps extends BackdropImageCommonProps {
+    repeat: BackdropImageRepeat;
+    srcset?: never;
+    sizes?: never;
+    fit?: never;
+}
+type BackdropImageProps = BackdropImageSingleProps | BackdropImageTiledProps;
+/**
+ * An image backdrop at the top of a scrolling Pane or NavStack view: the
+ * image can lag the scroll (parallax on a scroll-driven, compositor-only
+ * transform), fade through a mask into `fadeTo`, and that color keeps
+ * painting under `children` so the page reads as one surface. Kerf owns the
+ * static fallbacks: no parallax without scroll-driven animation support,
+ * under reduced motion, under `data-kui-effects="static"`, or on a
+ * slow-update display, and a hard edge onto solid `fadeTo` under reduced
+ * transparency.
+ */
+declare function BackdropImage(props: BackdropImageProps): kerfjs.SafeHtml;
+
+export { BackdropImage, type BackdropImageBlur, type BackdropImageFit, type BackdropImageParallax, type BackdropImagePosition, type BackdropImageProps, type BackdropImageRepeat, type BackdropImageScrim, type BackdropImageSingleProps, type BackdropImageTiledProps };
+```
+
 ## `@kerfjs/ui/wire-toolbar-visibility`
 
 ```ts
@@ -4103,7 +4394,19 @@ 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';
+/**
+ * How the dialog is presented: `modal` (default) centered on the screen,
+ * `side-sheet` against the inline end, `fullscreen`, or `bottom-sheet`
+ * attached to the bottom edge (square bottom corners, safe-area and
+ * virtual-keyboard clearance, optionally user-resizable).
+ */
+type DialogSurfacePresentation = 'modal' | 'side-sheet' | 'fullscreen' | 'bottom-sheet';
+/**
+ * How a bottom sheet appears or leaves: `slide` (default) moves the panel in
+ * from, or out to, the bottom edge; `standard` keeps Web Awesome's
+ * scale-and-fade. Both honor `prefers-reduced-motion`.
+ */
+type DialogSurfaceSheetMotion = 'slide' | 'standard';
 type SurfaceInset = 'none' | 'compact' | 'comfortable';
 type DialogSurfaceMaxHeight = CssLength | 'viewport';
 /** A definite modal height: a length or the full viewport, minus both gutters. */
@@ -4144,13 +4447,34 @@ interface DialogSurfaceProps {
     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. */
+    /**
+     * Modal height cap, bounded by the dynamic viewport minus both gutters. On a
+     * bottom sheet, the cap (and the resize ceiling), bounded by the dynamic
+     * viewport minus the top safe area and one gutter.
+     */
     maxHeight?: DialogSurfaceMaxHeight;
     /**
      * Modal definite height, bounded the same way, so a filling child has a
-     * height to fill. Takes precedence over `maxHeight`.
+     * height to fill. Takes precedence over `maxHeight`. On a bottom sheet, the
+     * height it opens at (the visible height above the safe area or keyboard).
      */
     height?: DialogSurfaceHeight;
+    /**
+     * A resizable bottom sheet's resize floor (default 160px), the visible
+     * height above the safe area or keyboard.
+     */
+    minHeight?: CssLength;
+    /**
+     * Let the person resize a bottom sheet by its top grabber (drag, or the
+     * arrow, Page Up/Down, Home and End keys) between `minHeight` and the
+     * sheet's cap. Needs the `/register` entry; each opening starts at `height`
+     * (or the content height). Ignored by other presentations.
+     */
+    resizable?: boolean;
+    /** How a bottom sheet appears (default `slide` up from the bottom edge). */
+    enterMotion?: DialogSurfaceSheetMotion;
+    /** How a bottom sheet is dismissed (default `slide` down off the bottom edge). */
+    exitMotion?: DialogSurfaceSheetMotion;
     /**
      * Body layout (default `flow`); `fill` lets one child own the body and
      * `fill-last` stacks fixed rows above one filling last child.
@@ -4200,7 +4524,7 @@ interface DialogSurfaceProps {
     slot?: string;
 }
 /** Configure recurring Web Awesome dialog geometry without consumer ::part() CSS. */
-declare function DialogSurface({ children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, height, bodyLayout, headerPresentation, footerPresentation, footerOffset, rootAttributes, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
+declare function DialogSurface({ children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, height, minHeight, resizable, enterMotion, exitMotion, bodyLayout, headerPresentation, footerPresentation, footerOffset, rootAttributes, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
 /** Where a PopoverDialogSurface appears: the top layer, or in flow. */
 type PopoverDialogSurfacePresentation = 'overlay' | 'embedded';
 /** Application `data-*` metadata on the surface root. */
@@ -4267,7 +4591,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 DialogSurfaceBodyLayout, type DialogSurfaceFooterPresentation, type DialogSurfaceHeaderPresentation, type DialogSurfaceHeight, type DialogSurfaceMaxHeight, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceRootAttributes, type DialogSurfaceSize, PopoverDialogSurface, type PopoverDialogSurfaceDataAttributes, type PopoverDialogSurfacePresentation, type PopoverDialogSurfaceProps, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset };
+export { DialogSurface, type DialogSurfaceBodyLayout, type DialogSurfaceFooterPresentation, type DialogSurfaceHeaderPresentation, type DialogSurfaceHeight, type DialogSurfaceMaxHeight, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceRootAttributes, type DialogSurfaceSheetMotion, type DialogSurfaceSize, PopoverDialogSurface, type PopoverDialogSurfaceDataAttributes, type PopoverDialogSurfacePresentation, type PopoverDialogSurfaceProps, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset };
 ```
 
 ## `@kerfjs/ui/text`