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

package/ai/skill.md

@@ -59,6 +59,48 @@ twice through a wrapper, a second background, or an unnecessary override.
 Check the resulting contrast in both color schemes, especially over a custom
 backdrop. See `../docs/webawesome-theme.md#contextual-transparency`.
 
+### Clear chrome over imagery
+
+For a header or bar laid over imagery (an Apple-Music-style detail page), use
+the `clear` presentation (`Pane headerPresentation`, `NavStack
+chromePresentation` / `bottomToolbarPresentation`, `TabNavigator
+barPresentation`) instead of making `overlay` chrome transparent with CSS.
+Put its controls in `ToolbarControlGroup material="glass"` groups, and add
+`scrollEdge="material"` (or `"surface"`, with `scrollEdgeDistance`, default
+60px) to fade a backing in gradually as content scrolls beneath the bar (it
+stays clear otherwise); give the opening `BackdropImage` `underChrome` so its artwork runs beneath the clear header. A clear bar draws no divider and turns opaque under reduced
+transparency, increased contrast, and forced colors on its own.
+
+### Core dialogs as bottom sheets
+
+For a `kerfjs/overlay` `confirm` / `prompt` / `form` / `choice` (or `overlay()`)
+with `presentation: 'bottom-sheet'`, import `@kerfjs/ui/overlay-sheet.css` once
+instead of writing sheet CSS, pass `exitClass: 'kui-overlay-sheet-exit'` with an
+`exitDuration` for the slide out, and compose the content through the dialog's
+`render` slot (on kerfjs 4.x, with native buttons for the wired controls). For a sheet the person
+can resize, add the `kui-overlay-sheet-resizable` class
+(`className: 'kerf-overlay kui-overlay-sheet-resizable'`) and call
+`wireOverlaySheets()` from `@kerfjs/ui/wire-overlay-sheets` once per container,
+instead of building a grabber.
+
+### App-chosen surface colors
+
+For a surface in its own color (a media page in its artwork's color), set the
+typed `background` prop instead of CSS: `Pane` (also `PaneConfig`, so Workbench
+panels, CollapsiblePanel, and NavStack view panes forward it), `NavStack`,
+`TabNavigator`, and each `TabNavigatorTab`. Pass a `@kerfjs/ui/css-values`
+color (`uiColor(...)`, `fillColor(...)`, `colorVar(...)`); it replaces the
+default or sunken fill, overlay chrome keeps its material, and forced colors
+paint `Canvas`. Never select `.kui-pane` or a layout class to recolor it. You
+own the contrast of the content over the color.
+
+For a region that takes on a color, such as a media page in its artwork's
+color, set `tint={{ color, scheme }}` on the same components (and
+`TabNavigatorTab`, `PaneConfig`) instead: you declare whether the color is a
+`'light'` or `'dark'` surface, and the scope re-derives surface, text, quiet
+text, link, fills, and chrome material from it with lightness clamped to keep
+text at WCAG AA. Add `accent` to re-derive the brand ramp (loud fills, links, focus ring) from the artwork's vivid color with the same AA clamps. Never restyle tokens by hand inside a tinted region.
+
 ## Components own their styles; configure, never override
 
 This is the rule every Kerf UI surface follows, and applications and
@@ -260,6 +302,7 @@ Quick routing:
 | Exclusive choice                      | `TabBar`, `SegmentedControl`, or `Select`                  | Tabs switch tabpanels; segments expose a few choices; `ChoiceChips` keeps a larger visible set as wrapping pills (`multiple` for any number); Select handles a longer value list.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | Status or absent content              | `StateBanner` or `EmptyState`                              | `StateBanner` accepts an optional terse, tone-tinted `badge` beside its title for a count or compact status; do not rely on color alone. Web Awesome callouts suit ecosystem content; toasts are transient and never the only record of important state.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | Compact metadata                      | `Badge`                                                    | Configure status, count, category, or metadata presentation with tone, appearance, shape, and size props. For new content without a count use `size="dot"` (no children) with a `label` or `ariaHidden`. Cap long app-supplied text with `maxWidth` (a `CssLength`); it truncates with an ellipsis and the full string becomes the `title`. Do not build badges with application CSS or use them as interactive controls.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Hero image atop a scrolling view      | `BackdropImage`                                            | Lags the scroll (`parallax`), blurs progressively (`blur`, an opacity cross-fade to a once-blurred copy), dissolves into a typed `fadeTo` color that also paints the content below, and carries `overlay` content; Kerf owns the compositor-only scroll timeline and the reduced-motion, static-effects, and reduced-transparency fallbacks. Never hand-roll scroll listeners, `background-attachment: fixed`, or mask gradients.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | Loading placeholder                   | a component's `placeholder` prop, or `Skeleton`            | Set `placeholder` on a value-bearing component (`Select`, `ListHeader`, `ListItem`, `ValueTableRow`, `SegmentedControl`, `StateBanner`, `AppTab`, `ToolbarText`, `ListActionRow`) to render its real chrome with value slots as subtle **unanimated** skeletons and interactivity disabled; only unknown values change, so a placeholder is never dimmed or styled as disabled (a control whose own `disabled` / `trailingActionDisabled` / choice `disabled` / `actionDisabled` prop is set keeps its live disabled tone via the reserved `data-kui-disabled` marker) — do not hand-rebuild an empty state. Component-drawn chrome stays live too: a `ListItem` or `ListActionRow` placeholder keeps its `busy` spinner while its `status` text (and a `ListItem`'s `trailing` content, always a value) becomes a skeleton. `Skeleton` is the standalone block for a custom slot. A known `AppTab` that is still opening takes `pending` instead: it keeps its name (quiet, and as its accessible name) and the same geometry, shows your `trailing` spinner, and stays selectable (close and drag disabled) so your panel can show placeholders until it loads. Use `LoadingSpinner` for known busy activity, not a skeleton; never animate a skeleton; prefer it over `wa-skeleton`. |
 | Adjustable or asymmetric columns      | `ResizableRegion` or CSS grid                              | Use `ResizableRegion` only for a user-operable controlled separator, CSS grid for asymmetric/intrinsic tracks, and `Grid` for static equal-width tracks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | Structured or ordinary search         | `TokenSearchField` or an input                             | Use token search only when text and ordered filter chips form one editor.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
@@ -279,7 +322,8 @@ selection set and each tile's nested controls.
 adds 8px. Text insets win on any overlapping side, matching Row and List.
 
 For a complete shell, sidebar, workspace header, list-detail dialog, composer
-form, list-state lifecycle, or mixed-control toolbar, start from the runnable
+form, list-state lifecycle, mixed-control toolbar, or a media detail page
+(clear chrome, tint, and artwork), start from the runnable
 reference in [`docs/recipes.md`](../docs/recipes.md). Preserve its production
 primitives and semantic ownership; replace application state, policy, and copy.
 
@@ -320,7 +364,7 @@ Hard rules:
 4. Wire `data-action` hooks from one stable root with `delegate()` or `delegateActions()` and retain disposers.
 5. Configure components through their typed props; components own their own styles (see "Components own their styles; configure, never override" above). Use the opinionated `--kui-color-*` semantic ramps for theming, not to reshape a component. Use `pop` only for attractive non-status emphasis such as featured, novel, or celebratory content; never substitute it for info, success, warning, or danger. Set a theme token only at the narrowest useful scope, and never where an equivalent prop exists. `publicClasses` exist for diagnostics, tooling, tests, and package-owned composition, not application styling. Never target a Kerf or Web Awesome component from application CSS; add missing configuration to the owner.
 6. `Select` is pure until the app explicitly imports `@kerfjs/ui/select/register`; once registered, an icon-only `Select` (and, via `@kerfjs/ui/popup-menu/register`, an icon-only `PopupMenu`) shows an `aria-hidden` help tag repeating its accessible name (and a Select's current choice) on hover and keyboard focus, hidden while its popup is open — never add a `title` or your own tooltip to these triggers. The same installer tags an icon-only `<button>` or link in a `ToolbarControlGroup` named by `aria-label` (no visible text, no `title`); a toolbar with such buttons but no registered Select or PopupMenu imports `@kerfjs/ui/help-tags/register` once. Name those buttons with `aria-label`, not `title`: a `title` keeps the browser tooltip and skips the tag. Do not import Web Awesome's full registration bundle. When an app writes direct `wa-*` JSX, add `import type {} from '@kerfjs/ui/webawesome'` for the catalog-supported intrinsic-element declarations, import the CSS-only `@kerfjs/ui/webawesome.css` theme once, and keep importing individual Web Awesome component modules so their JavaScript remains tree-shakeable. The type boundary emits no code and registers nothing. Pass icon-bearing `choices` and `renderSelected` content normally: `Select` preserves its slotted option icons across Kerf rerenders and keys selected content by the controlled value, so app wrappers must not add competing morph-control attributes. Give it a visible `label` or an `ariaLabel` for a visually hidden name; the nonempty visible label takes precedence and the package names the actual shadow combobox, including `renderSelected`, without adding label geometry. Use `hint` for persistent supporting text below the control and `placeholderText` only for the empty value inside the closed control; loading placeholders retain the hint. For any number of choices set `multiple` with an array `value`: the popup stays open while choices toggle and closes on an outside press or Escape, the closed control summarizes the chosen labels, and `change` reports the value array; do not add app code to keep it open or to render tags. For a toolbar filter menu, add `selectedPresentation="icon-only"` plus a fixed `triggerIcon` (such as a funnel `LucideIcon`): the trigger shows that icon, a count badge while any choice is chosen, and ends its accessible name with the chosen labels ("Filter by label: Bug, Docs"); do not render your own count badge or rewrite the name. When testing name or description, target the element with the `combobox` role rather than the `wa-select` wrapper. Web Awesome's hint attribute and explicit hint slot both describe that shadow combobox across supported engines; do not add an `aria-description` mirror or application shadow-DOM patch.
-7. Decorative icons are hidden; controls are named; focus is visible; state never relies on color alone; reduced motion and increased contrast remain usable. `DisclosureArrow` defaults to an 18px root-scaled visual; size it with its typed `size` prop (`size={remify(24)}`); it never becomes the interaction or accessible-name owner. Put it in an owning native control with a stable accessible name and controlled `aria-expanded`. `ListHeader` toggle mode supplies it when `actionIcon` is omitted, but the app must reveal matching content; a custom icon replaces it. Author replacement icon content facing right before its configured direction transform is applied. Direction changes take the shortest rotation path, with counterclockwise chosen for a 180-degree closed-to-open tie. Kerf `Select` separately keeps its intrinsic Web Awesome expand glyph at `--kui-disclosure-icon-scale: .5`; an icon-only toolbar Select may set `caret={false}` for a round trigger while preserving its help tag and keyboard listbox, and a custom `renderSelected` icon stays centered.
+7. Decorative icons are hidden; controls are named; focus is visible; state never relies on color alone; reduced motion and increased contrast remain usable. When the app detects a low-power device, it sets `data-kui-effects="static"` on the root element to turn backdrop materials opaque and stop scroll-driven animations; `@media (update: slow)` does the same automatically. `DisclosureArrow` defaults to an 18px root-scaled visual; size it with its typed `size` prop (`size={remify(24)}`); it never becomes the interaction or accessible-name owner. Put it in an owning native control with a stable accessible name and controlled `aria-expanded`. `ListHeader` toggle mode supplies it when `actionIcon` is omitted, but the app must reveal matching content; a custom icon replaces it. Author replacement icon content facing right before its configured direction transform is applied. Direction changes take the shortest rotation path, with counterclockwise chosen for a 180-degree closed-to-open tie. Kerf `Select` separately keeps its intrinsic Web Awesome expand glyph at `--kui-disclosure-icon-scale: .5`; an icon-only toolbar Select may set `caret={false}` for a round trigger while preserving its help tag and keyboard listbox, and a custom `renderSelected` icon stays centered.
 8. `ResizableRegion` uses `wireResizableRegions()` for Arrow, Shift+Arrow, Home/End, and pointer behavior. The app owns size persistence. `handleIcon` replaces decorative dormant glyph content only. Set `responsiveFillAt="narrow"` or `"compact"` when a responsive composition exposes the pane as its only inline track; the component fills that track and hides its dormant separator. For compact overlays, set `presentation="overlay"` and the overlay maximum variables. A lone child (normally a `Pane`) fills the region and owns scrolling; several children stack at natural height. Do not add descendant width/height overrides.
 9. Use controlled `SegmentedControl` for a small exclusive choice set. Select `appearance="toolbar"` when nesting it inside `ToolbarControlGroup`; use rounded or pill shapes for standalone contexts. The package derives inset hover/selection radii from the owning outer shape through `--kui-layout-highlight-inset`; do not restyle an inner highlight to an independent radius. Handle its action, update `value`, keep meaningful choice labels, and preserve every enabled native button in sequential Tab order.
 10. Compose `AppTab` inside controlled `TabBar`; call `wireTabBars()` once and retain its disposer. It owns same-bar drag mechanics, including proximity-based horizontal edge autoscroll, while the app applies `onReorder` and owns order, selection, panels, close policy, routing, and persistence. For a tab-local action followed by a separately pinned workspace action, set `trailingPlacement="adjacent"`, put the local action in `trailing`, and the workspace action in `end`; each action zone accepts one `ToolbarControlGroup` or a standalone `wa-button` when the action needs its own Web Awesome chrome. TabBar owns the shrinking/scrolling tabs and fixed action geometry, so do not add descendant flex overrides. Arrow/Home/End select on move by default and restore focus by bar/tab identity when controlled activation replaces the strip; pass `activation: 'manual'` (or `TabBar activation="manual"` per strip) so arrow keys move focus only and the user selects with Enter/Space/click — use it when selecting a tab is a heavy action. Use runtime-filtered `rootAttributes` for domain metadata and keep an optional `closeIcon` decorative and noninteractive.
@@ -378,6 +422,8 @@ For a read-only field preview that replaces a Web Awesome input, use `FieldLabel
 
 `ToolbarControlGroup.tileTone` selects `neutral`, `brand`, `success`, `warning`, or `danger` quiet fill, matching quiet border, and on-quiet foreground for a non-interactive icon tile. Compose a contained `single` group whose only child is a direct decorative LucideIcon (`aria-hidden="true"`). Omission preserves the normal group palette. The prop does not recolor interactive, mixed, multi-control, or borderless groups; keep real actions in controls with their existing focus/hover/pressed treatments.
 
+`ToolbarControlGroup` `material="glass"` paints a group that floats over imagery or a clear (transparent) toolbar on the translucent chrome material (`--kui-chrome-material` with the blur/saturate `--kui-chrome-material-filter`), with a specular edge in place of the gray border and a soft shadow. Its controls take `--kui-color-text`, so they stay at AA over any content; a raised or outline selection paints an opaque surface pill. The fill turns opaque under reduced transparency, increased contrast, static effects (`update: slow` or `:root[data-kui-effects="static"]`), or without backdrop-filter support, and paints Canvas/CanvasText in forced colors. A `tone="dark"` glass group keeps its loud fill and gains the blur and edge; a borderless group has no surface and ignores the material. Keep the solid default on an opaque toolbar, and never add your own `backdrop-filter` or translucent background to a group.
+
 `ListItem`, `ListItemLink`, and `ListActionRow` take `iconTile` to present their leading `icon` in a filled 32px rounded tile holding an 18px glyph, for settings or command rows that identify each entry by color. Pass a tone (`neutral`, `brand`, `success`, `warning`, or `danger`) for the same quiet fill, matching quiet border, and on-quiet foreground as `ToolbarControlGroup.tileTone`, or `{ color, foreground? }` for an application color: `color` is a `CssColor` (`uiColor()`, `colorVar()`, or `fillColor('#e5484d')`) and `foreground` a `CssForegroundColor`; without one, the glyph is black or white, whichever contrasts with the fill. The tile sits 6px clear of a standard 44px row (a compact row is at least 42px tall), moves the label to the tile's edge, and keeps its colors when the row is hovered or selected. Never wrap the icon in your own tile or resize the row's icon slot.
 
 Common mistakes:
@@ -445,8 +491,10 @@ completion handlers in consumers. Raw `wa-select` elements remain native.
 
 Neutral lowered surfaces and decorative neutral fills/borders are translucent theme colors; compose nested public components directly. Default/raised canvases, foregrounds, focus indicators, and loud contrast-bearing fills remain opaque. Do not assign depth-specific component tokens in demo wrappers.
 
-Use `ToolbarText tone="dark"` on a loud or photo-backed toolbar surface to
-match dark control groups. It applies to read-only headings and actionable
+Use `ToolbarText tone="dark"` on a loud-filled toolbar surface (the inverse
+`--kui-color-neutral-fill-loud`) to match dark control groups; 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`. It applies to read-only headings and actionable
 titles at every size; default tone retains existing identity and heading colors.
 
 Navigation transition continuity: `wireNavStack` slides the incoming view over the preserved previous view on push and the outgoing view off on pop, cross-fades both live chrome surfaces with inert snapshots, and settles/cancels an interrupted transition before starting the next. Reduced motion and duration zero settle immediately.
@@ -471,7 +519,7 @@ details.
 
 Select menus use native viewport shifting with 10px gutters: default menus grow to content (up to 20rem), while `fitMenu` matches trigger width and long labels wrap. Keep popup sizing and position repairs out of consumer CSS.
 
-Give sibling `DialogSurface`s that render conditionally a stable `rootAttributes={{ "data-key": "…" }}` so a re-render morphs each dialog into itself (structurally identical roots otherwise match by position and swap names and open state); never wrap one in a keyed app `div`. Modal `DialogSurface` accepts a typed `preferredWidth` (`CssLength`) that overrides `size` while retaining the viewport width cap. Typed `viewportGutter` and `maxHeight` (`CssLength` or `"viewport"`) bound the modal; explicit height caps stay within the dynamic viewport minus both gutters. Omitted props preserve Web Awesome defaults. Side-sheet/fullscreen geometry, application responsive choices, and preview layout remain separately owned. `height` (`CssLength` or `"viewport"`) gives the modal a definite bounded size, and `bodyLayout="fill"` hands the whole body to one child (a `SplitView` or `Pane`) that owns its scrolling. For a chat-style dialog, `bodyLayout="fill-last"` keeps leading rows (a notice) at their height and gives the last child (a `scrollable` `List` transcript) the rest, and `footerPresentation="floating"` lays the composer footer over the body, a typed `footerOffset` (default 16px) from the panel edges on a transparent background; the body reserves the measured footer height, so never add `::part(footer)` or `::part(body)` rules for it. To let the transcript scroll visibly beneath the floating composer, give the transcript `scrollClearance="block-end"` (on a `scrollable` `List` or a `Pane`): the body then publishes the footer's clearance as the inherited `--kui-scroll-clearance-block-end`, and the transcript adds it inside its own scroll area, so its last message still rests above the composer. Chrome that overlays a region's edge publishes `--kui-scroll-clearance-block-start` / `-end` the same way, and only the one scroller reaching that edge opts in (a composed Pane opts in through `PaneConfig.scrollClearance`: a Workbench `mainPane` or panel `pane`, a `CollapsiblePanel` `pane`, or a `NavStack` view's `pane`); never pad a transcript yourself to clear a footer. `headerPresentation="floating"` lays the dialog's title bar over the body's block start on the translucent `--kui-chrome-material-raised` (opaque under reduced transparency, increased contrast, forced colors, or without `backdrop-filter`); the register measures it and the body reserves it. To let a transcript scroll beneath both the title bar and a floating composer, make it the body's only child (`bodyLayout="fill"`) with `scrollClearance="both"`: the body publishes the header's height as `--kui-scroll-clearance-block-start`. A `ToolbarText` slotted as the label keeps AA on the title bar by itself (normal-color title, lifted description); keep other quiet copy in the body. For a non-modal, light-dismiss dialog use `PopoverDialogSurface` from the same subpath (native `popover="auto"`, `role="dialog"`, Kerf chrome, the same size/gutter/height/fill props, and `presentation="embedded"` for an in-flow catalog or inline preview) instead of a hand-built popover with app CSS. Name it with `label` or `labelledBy`, and describe it with `describedBy` (its `aria-describedby`), usually a title `ToolbarText`'s `descriptionId`.
+Give sibling `DialogSurface`s that render conditionally a stable `rootAttributes={{ "data-key": "…" }}` so a re-render morphs each dialog into itself (structurally identical roots otherwise match by position and swap names and open state); never wrap one in a keyed app `div`. Modal `DialogSurface` accepts a typed `preferredWidth` (`CssLength`) that overrides `size` while retaining the viewport width cap. Typed `viewportGutter` and `maxHeight` (`CssLength` or `"viewport"`) bound the modal; explicit height caps stay within the dynamic viewport minus both gutters. Omitted props preserve Web Awesome defaults. Side-sheet/fullscreen geometry, application responsive choices, and preview layout remain separately owned. `height` (`CssLength` or `"viewport"`) gives the modal a definite bounded size, and `bodyLayout="fill"` hands the whole body to one child (a `SplitView` or `Pane`) that owns its scrolling. For a chat-style dialog, `bodyLayout="fill-last"` keeps leading rows (a notice) at their height and gives the last child (a `scrollable` `List` transcript) the rest, and `footerPresentation="floating"` lays the composer footer over the body, a typed `footerOffset` (default 16px) from the panel edges on a transparent background; the body reserves the measured footer height, so never add `::part(footer)` or `::part(body)` rules for it. To let the transcript scroll visibly beneath the floating composer, give the transcript `scrollClearance="block-end"` (on a `scrollable` `List` or a `Pane`): the body then publishes the footer's clearance as the inherited `--kui-scroll-clearance-block-end`, and the transcript adds it inside its own scroll area, so its last message still rests above the composer. Chrome that overlays a region's edge publishes `--kui-scroll-clearance-block-start` / `-end` the same way, and only the one scroller reaching that edge opts in (a composed Pane opts in through `PaneConfig.scrollClearance`: a Workbench `mainPane` or panel `pane`, a `CollapsiblePanel` `pane`, or a `NavStack` view's `pane`); never pad a transcript yourself to clear a footer. `headerPresentation="floating"` lays the dialog's title bar over the body's block start on the translucent `--kui-chrome-material-raised` (opaque under reduced transparency, increased contrast, forced colors, or without `backdrop-filter`); the register measures it and the body reserves it. To let a transcript scroll beneath both the title bar and a floating composer, make it the body's only child (`bodyLayout="fill"`) with `scrollClearance="both"`: the body publishes the header's height as `--kui-scroll-clearance-block-start`. A `ToolbarText` slotted as the label keeps AA on the title bar by itself (normal-color title, lifted description); keep other quiet copy in the body. `presentation="bottom-sheet"` attaches the dialog to the bottom edge (iOS-style sheet): the top corners keep the dialog radius, the bottom corners are square, and the panel runs behind the home indicator and virtual keyboard while a block-end padding (the larger of `--kui-safe-area-block-end`, the `visualViewport` keyboard overlap the register measures, and `env(keyboard-inset-height)`) keeps content above them; `height` is its opening visible height and `maxHeight` its cap (the dynamic viewport minus the top safe area and one gutter). `resizable` adds a top grabber (a focusable "Resize sheet" separator; drag, arrows, Page Up/Down, Home/End) bounded by `minHeight` (default 160px) and the cap, restarting at `height` on each opening. It slides up on open and down on dismiss by default (`enterMotion` / `exitMotion` = `"standard"` keeps the Web Awesome scale-and-fade), and falls back to Web Awesome motion under reduced motion. Never position a `wa-dialog` at the bottom with `::part(dialog)` rules or add your own keyboard padding. For a non-modal, light-dismiss dialog use `PopoverDialogSurface` from the same subpath (native `popover="auto"`, `role="dialog"`, Kerf chrome, the same size/gutter/height/fill props, and `presentation="embedded"` for an in-flow catalog or inline preview) instead of a hand-built popover with app CSS. Name it with `label` or `labelledBy`, and describe it with `describedBy` (its `aria-describedby`), usually a title `ToolbarText`'s `descriptionId`.
 
 Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog` and repairs Web Awesome 3.12 native dialog names before the first modal opening. Headed dialogs reference the rendered title, including live slotted labels; headerless dialogs use the public `label`. Explicit host `aria-label` and pre-existing native names are preserved. A host that is itself an explicit dialog (`role="dialog"` or `"alertdialog"` with its own name) keeps that name alone: the native panel is left unnamed, so one dialog carries the name. Geometry-only markup stays CSS-free and does not register Web Awesome implicitly.
 

package/ai/webawesome-jsx-signatures-v1.md

@@ -1,6 +1,6 @@
 # Web Awesome JSX signatures for the UI authoring corpus
 
-Generated from the emitted `@kerfjs/ui@5.0.0-beta.100` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
+Generated from the emitted `@kerfjs/ui@5.0.0-beta.101` declaration boundary. Import `@kerfjs/ui/webawesome` for type effects when authoring direct `wa-*` JSX. The module emits no runtime behavior and does not register custom elements.
 
 ```ts
 import { KerfCustomElement } from 'kerfjs/jsx-runtime';

package/dist/backdrop-image.d.ts

@@ -0,0 +1,132 @@
+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 };

package/dist/backdrop-image.js

@@ -0,0 +1,5 @@
+export { BackdropImage } from './chunk-SCDWURBO.js';
+
+
+
+//# sourceMappingURL=backdrop-image.js.map

package/dist/backdrop-image.js.map

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

package/dist/browser/backdrop-image.js

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

package/dist/catalog-resources.d.ts

@@ -5,12 +5,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';

package/dist/catalog.d.ts

@@ -7,12 +7,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';

package/dist/catalog.js

@@ -1,34 +1,35 @@
-import { Workbench } from './chunk-PYBBYSZ3.js';
+import { Workbench } from './chunk-YBWQR2OK.js';
 import { uxReviewCaptureUrl } from './chunk-6C6DLP3W.js';
 export { UX_REVIEW_PROJECT_PATH, loadUxReviewProject, uxReviewCaptureUrl } from './chunk-6C6DLP3W.js';
 
 
 import { TokenSearchField } from './chunk-MF6ZUUJZ.js';
+
 import { Row } from './chunk-YQ2AC4E2.js';
-import { ToolbarText } from './chunk-HGV7J4T6.js';
+import { ListItem } from './chunk-ZYU5WRC3.js';
+import { ToolbarText } from './chunk-EKHDLBRP.js';
 
 import { PopupMenu } from './chunk-HQZYKJ56.js';
-import { ListHeader } from './chunk-T4WJ5VGP.js';
+import { ListHeader } from './chunk-3SKAEPPZ.js';
 import { ListInsetControl } from './chunk-AN5IWMTM.js';
 import { ListInsetText } from './chunk-S4Y3YTAI.js';
-import { ListItem } from './chunk-3GLYIIFR.js';
-
-
-
-import { Text } from './chunk-LL45C7BB.js';
 
 
 
 
-import { ToolbarControlGroup, ToolbarActionLink } from './chunk-QIG4IGUP.js';
+import { ToolbarControlGroup, ToolbarActionLink } from './chunk-2PXZBFEC.js';
 import { Toolbar } from './chunk-CMLPFIC5.js';
 import { List } from './chunk-HZPHCSCS.js';
 
 
+
 import { ensureSunkenTexture } from './chunk-IKS72C6P.js';
 import { LucideIcon } from './chunk-LOSRXZAH.js';
 
 
+import { Text } from './chunk-LL45C7BB.js';
+
+
 
 import { filterDataAttributes } from './chunk-KH4KEMSP.js';
 import { Contrast, ZapOff, Moon, Sun, X, Waypoints, ExternalLink, Scan } from 'lucide';