@kerfjs/ui 5.0.0-beta.110 → 5.0.0-beta.112

package/ai/components/surface-scaffold.md

@@ -13,6 +13,7 @@ Configure recurring dialog and popup geometry without consumer ::part() override
 - A modal task needs a dialog: render a DialogSurface with a label (or labelledBy plus a heading), its body as children, and its buttons as footer, then open it with openDialog() and close it with closeDialog(), the close button, or any element with data-dialog-close. A raw Web Awesome dropdown that needs a list-compatible menu inset uses PopupSurface.
 - A dialog body should compose rows, sections, or aligned bare prose through List and ListInsetText.
 - A modal needs a typed preferred width, viewport gutter, or dynamic viewport-bounded height cap while retaining native body scrolling and footer actions.
+- A dialog needs a less prominent built-in close control: closeEmphasis="quiet" softens the glyph while keeping the native button target and close behavior.
 - A dialog that must leave the page interactive and close on Escape or an outside press uses PopoverDialogSurface; one that fills its body with a SplitView or Pane uses height and bodyLayout="fill".
 - A chat-style dialog floats its composer over the transcript with footerPresentation="floating" and keeps a heading or notice above one scrolling transcript with bodyLayout="fill-last".
 - A phone-first task (compose, quick edit, a picker) should rise from the bottom edge as a sheet the person can resize: presentation="bottom-sheet" with height, and resizable with minHeight / maxHeight bounds.
@@ -57,6 +58,7 @@ Exact prop names and types: [`@kerfjs/ui/surface-scaffold`](../public-api-signat
 - core kerfjs/overlay confirm/prompt/form/choice as a bottom sheet styled by @kerfjs/ui/overlay-sheet.css
 - resizable core kerfjs/overlay bottom sheet: the kui-overlay-sheet-resizable class plus wireOverlaySheets adds the resizable DialogSurface sheet grabber
 - header with label text or heading content, headerActions, a close button, and an optional footer; withoutHeader for content that owns its heading and close control
+- normal (default) or quiet closeEmphasis on the built-in close button
 - accessible description by describedBy: the heading ToolbarText descriptionId or app-owned body summary copy
 - light dismiss (a backdrop press closes; otherwise the panel pulses)
 
@@ -89,6 +91,7 @@ Margin: parent · border: child · padding: self (layout role: structure). `self
 
 - DialogSurface is a native \<dialog> opened modally (showModal): it is in the top layer, the rest of the page is inert, focus stays inside, and it returns to the opener on close. Focus starts on an autofocus element, otherwise on the panel.
 - Name it with label (also its title text) or labelledBy (the id of a heading, such as a ToolbarText). The close button is named Close (closeLabel) and Escape asks to close; the cancelable kui-request-close event reports source close-button, escape, or backdrop.
+- closeEmphasis="quiet" uses a smaller, quiet-colored close glyph inside the same 40px target; hover, focus ring, forced colors, accessible naming, and close requests remain available.
 - Name a PopoverDialogSurface with label or labelledBy. Describe either surface with describedBy (rendered as aria-describedby on the dialog root), usually the heading ToolbarText descriptionId or app-owned summary copy in the body; rootAttributes accepts only data-\* attributes, so it never sets aria-describedby.
 - A floating header's title uses the normal text color, which keeps WCAG AA over the 80% raised chrome material on any content; the material turns opaque under prefers-reduced-transparency, prefers-contrast: more, forced colors, or without backdrop-filter.
 - A resizable bottom sheet's grabber is a focusable horizontal separator ("Resize sheet") with aria-valuemin, aria-valuenow, and aria-valuemax in visible px; the arrow keys, Page Up/Down, Home, and End resize it, and its slide motion is skipped under prefers-reduced-motion.

package/ai/components/value-preview.md

@@ -0,0 +1,75 @@
+# ValuePreview
+
+<!-- Generated by scripts/sync-component-docs.mjs from ai/component-catalog.json and ai/component-composition.json. Do not edit; run `npm run catalog:sync`. -->
+
+`@kerfjs/ui:value-preview` · Kerf UI · component · Structure
+
+A bounded, read-only multiline text value with keyboard scrolling.
+
+## When to use
+
+Display a literal long value with line breaks and long tokens inside a bounded scroll region.
+
+- A read-only value may have multiple lines or long unbroken text and needs bounded scrolling, such as a conflict version.
+
+**Not when:**
+
+- Do not use for editing; use a multiline TextField.
+- Do not use for short label/value facts; use ValueTable.
+
+**Alternatives:**
+
+- [ValueTable](./value-table.md) (nearest) — Use ValueTable for rows of short labelled facts.
+
+## Imports
+
+- JavaScript: `@kerfjs/ui/value-preview` — exports `ValuePreview`.
+- CSS: the browser build of `@kerfjs/ui/value-preview` pulls its CSS automatically; import `@kerfjs/ui/value-preview.css` manually only without the `browser` export condition.
+- Declared side effects: browser-condition-css.
+
+## Props
+
+Exact prop names and types: [`@kerfjs/ui/value-preview`](../public-api-signatures-v1.md#kerfjsuivalue-preview) in `public-api-signatures-v1.md`. Do not infer props from examples.
+
+**Variants (configure, do not restyle):**
+
+- typed minimum and maximum height
+
+## Composition
+
+- Parents: any.
+- Contexts: `application-ui`.
+- Children: unrestricted.
+- Built from: [SunkenPanel](./sunken-panel.md).
+
+## State and wiring
+
+**The app owns:** value; empty wording.
+
+No wiring helper.
+
+## Geometry
+
+Margin: none · border: none · padding: none (layout role: structure). `self` means the component already owns it — do not add wrapper padding, margin, or borders around it.
+
+## Accessibility
+
+- Give the focusable output a label so keyboard and screen-reader users can identify and scroll it.
+
+## Styling boundary
+
+The component owns its own styles. Configure it through its props and variants; do not override its internals.
+
+Public class hooks (select for layout placement only, never to change the component's look): `kui-value-preview`.
+
+Never put `kui-value-preview` on an element you write; render `ValuePreview` instead (`KUI-L103`).
+
+Public tokens it reads: `--kui-color-text`, `--kui-font-xs`, `--kui-focus-ring`. Set a token only where its public contract allows; prefer a prop.
+
+Everything else is internal: `kerf-ui-analyze` reports private or unknown `.kui-*` selectors (`KUI-L001`, `KUI-L010`), unknown or private tokens (`KUI-L002`, `KUI-L012`), and any application rule that restyles the component, forced dimensions included (`KUI-L019`).
+
+## Related
+
+- Components: [SunkenPanel](./sunken-panel.md), [ValueTable](./value-table.md).
+- Docs: [`docs/value-preview.md`](../../docs/value-preview.md).
+- UX catalog route: `?component=value-preview`.

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.110` and `kerfjs@5.0.0-beta.110`. 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.112` and `kerfjs@5.0.0-beta.112`. 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`
 
@@ -167,6 +167,7 @@ import { S as Sides } from './sides-BPSWde0A.js';
 import { PaneSeparatorSide } from './pane.js';
 import './scroll-clearance-BikHljTc.js';
 import './css-values.js';
+import './surface-tint-DQgYCaP9.js';
 
 type ToolbarPosition = 'header' | 'footer';
 /** Control-band density: `default` (60px with 44px groups) or `compact`. */
@@ -1195,7 +1196,11 @@ export { ListInsetText, type ListInsetTextProps, Sides };
 ```ts
 import * as kerfjs from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssColor } from './css-values.js';
 import { S as SemanticTone } from './semantic-tone-CdW013KF.js';
+import { S as SurfaceTint } from './surface-tint-DQgYCaP9.js';
+import { BackdropImagePosition, BackdropImageParallax, BackdropImageBlur, BackdropImageScrim } from './backdrop-image.js';
+import './extension-attributes-mu8MFUl0.js';
 
 /**
  * Base surface treatment, semantic status colors, or `brand-loud`: the solid
@@ -1214,12 +1219,43 @@ type ContentItemFrame = 'none' | 'framed';
 type ContentItemShape = 'rounded' | 'pill';
 /** `single` uses an option; `multiple` uses a grid row; `toggle` uses a pressed button. */
 type ContentItemSelectionMode = 'none' | 'single' | 'multiple' | 'toggle';
+/** One card-owned lead image in the containing feed's shared scrollport. */
+interface ContentItemMedia {
+    src: string;
+    alt: string;
+    srcset?: string;
+    sizes?: string;
+    /** Width divided by height; reserves the image block before it loads. Default 16/9. */
+    aspectRatio?: number;
+    position?: BackdropImagePosition;
+    /** Default subtle (35% lag); set none for a static lead image. */
+    parallax?: BackdropImageParallax;
+    /** App-supplied soft copy; its opacity changes, never its blur filter. */
+    blurredSrc?: string;
+    /** Shared BackdropImage blur behavior; use instead of `blurredSrc`. */
+    blur?: BackdropImageBlur;
+    /** Skip offscreen media painting in long feeds while retaining card geometry. */
+    deferOffscreen?: boolean;
+    /** Color the image dissolves into and the card body continues on. */
+    fadeTo?: CssColor;
+    /** Content layered over the image, including native controls. */
+    overlay?: KerfUiContent;
+    /** Dim the image behind overlay content. */
+    scrim?: BackdropImageScrim;
+    /** Extend the image to the card's top, left, and right inner edges. */
+    edgeToEdge?: boolean;
+}
 type ContentItemRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
     'data-appearance'?: never;
     'data-outlined'?: never;
     'data-bubble'?: never;
     'data-grid-row'?: never;
+    'data-media-state'?: never;
+    'data-media-edge'?: never;
+    'data-media-fade'?: never;
+    'data-kui-tint'?: never;
+    'data-kui-tint-accent'?: never;
 }>;
 type ContentItemInteractiveRootAttributes = Readonly<Record<`data-${string}`, string | undefined> & {
     'data-component'?: never;
@@ -1227,6 +1263,11 @@ type ContentItemInteractiveRootAttributes = Readonly<Record<`data-${string}`, st
     'data-outlined'?: never;
     'data-bubble'?: never;
     'data-grid-row'?: never;
+    'data-media-state'?: never;
+    'data-media-edge'?: never;
+    'data-media-fade'?: never;
+    'data-kui-tint'?: never;
+    'data-kui-tint-accent'?: never;
     'data-action'?: never;
     'data-item-id'?: never;
     'data-interactive'?: never;
@@ -1242,6 +1283,10 @@ interface ContentItemBaseProps {
      * semantic values match StateBanner. Defaults to `transparent`.
      */
     appearance?: ContentItemAppearance;
+    /** Reserved lead image with a per-image scroll timeline. Wire the containing root with `wireContentItems`. */
+    media?: ContentItemMedia;
+    /** App-sampled image color, scoped to this card once its image loads. */
+    tint?: SurfaceTint;
     /** Item content; a plain string is allowed for bare copy. */
     children?: KerfUiContent | string;
     /**
@@ -1318,9 +1363,9 @@ type ContentItemProps = ContentItemBaseProps & ({
  * border (transparent unless `framed`), 8px padding, and a rounded or pill
  * radius. It owns that whole geometry, so wrappers must not add more.
  */
-declare function ContentItem({ appearance, children, frame, flush, shape, bubble, title, ariaLabel, focusTarget, outlined, tabIndex, gridRow, interactive, action, itemId, selectionMode, selected, disabled, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
+declare function ContentItem({ appearance, media, tint, children, frame, flush, shape, bubble, title, ariaLabel, focusTarget, outlined, tabIndex, gridRow, interactive, action, itemId, selectionMode, selected, disabled, className, rootAttributes, slot, }: ContentItemProps): kerfjs.SafeHtml;
 
-export { ContentItem, type ContentItemAppearance, type ContentItemBubble, type ContentItemFrame, type ContentItemProps, type ContentItemSelectionMode, type ContentItemShape, SemanticTone };
+export { ContentItem, type ContentItemAppearance, type ContentItemBubble, type ContentItemFrame, type ContentItemMedia, type ContentItemProps, type ContentItemSelectionMode, type ContentItemShape, SemanticTone };
 ```
 
 ## `@kerfjs/ui/value-table`
@@ -1722,12 +1767,13 @@ 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-CU_0dKtI.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-CrZF95VO.js';
 import 'kerfjs';
 import './semantic-content-BbzjvSu9.js';
 import './pane.js';
 import './scroll-clearance-BikHljTc.js';
 import './css-values.js';
+import './surface-tint-DQgYCaP9.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
@@ -1767,11 +1813,12 @@ 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-CU_0dKtI.js';
+import { N as NavStackProps, a as NavStackView } from './nav-stack-CrZF95VO.js';
 import { ResizableRegionProps } from './resizable-region.js';
 import './pane.js';
 import './scroll-clearance-BikHljTc.js';
 import './css-values.js';
+import './surface-tint-DQgYCaP9.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
@@ -1876,6 +1923,8 @@ 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';
+import { S as SurfaceTint } from './surface-tint-DQgYCaP9.js';
+export { a as SurfaceTintScheme } from './surface-tint-DQgYCaP9.js';
 
 /**
  * What clear (fully transparent) chrome fades in as content scrolls beneath
@@ -1886,28 +1935,6 @@ import { CssColor } from './css-values.js';
  */
 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
  * compensate for a device safe-area inset.
@@ -2129,7 +2156,7 @@ type PaneConfig = Pick<PaneProps, 'contentElement' | 'contentLabel' | 'separator
  */
 declare function Pane({ header, children, footer, chromePlacement, chromeDividers, compactChrome, compactChromeOpen, 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 PaneCompactChrome, type PaneCompactChromePolicy, type PaneConfig, type PaneContentElement, type PaneElement, type PaneHeaderPresentation, type PaneProps, type PaneSeparatorSide, ScrollClearance, type ScrollEdge, type SurfaceTint, type SurfaceTintScheme };
+export { Pane, type PaneAppearance, type PaneChromeDividers, type PaneChromePlacement, type PaneCompactChrome, type PaneCompactChromePolicy, type PaneConfig, type PaneContentElement, type PaneElement, type PaneHeaderPresentation, type PaneProps, type PaneSeparatorSide, ScrollClearance, type ScrollEdge, SurfaceTint };
 ```
 
 ## `@kerfjs/ui/workbench`
@@ -2137,13 +2164,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-CU_0dKtI.js';
+import { b as NavPane, N as NavStackProps } from './nav-stack-CrZF95VO.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 './css-values.js';
+import './surface-tint-DQgYCaP9.js';
 import './toolbar-text.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
@@ -2557,6 +2585,7 @@ import './sides-BPSWde0A.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
 import './scroll-clearance-BikHljTc.js';
+import './surface-tint-DQgYCaP9.js';
 
 /** Which edge a {@link CollapsiblePanel} docks to. */
 type CollapsiblePanelSide = PanelSide;
@@ -2762,8 +2791,9 @@ export { type SidebarStorage, type WireSidebarOptions, type WireSidebarPanel, wi
 ```ts
 import { SafeHtml } from 'kerfjs';
 import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
-import { PaneAppearance, SurfaceTint, ScrollEdge } from './pane.js';
+import { PaneAppearance, ScrollEdge } from './pane.js';
 import { CssColor } from './css-values.js';
+import { S as SurfaceTint } from './surface-tint-DQgYCaP9.js';
 import './scroll-clearance-BikHljTc.js';
 
 interface TabNavigatorTabBase<Id extends string> {
@@ -3092,8 +3122,9 @@ import './sides-BPSWde0A.js';
 import './pane.js';
 import './scroll-clearance-BikHljTc.js';
 import './css-values.js';
+import './surface-tint-DQgYCaP9.js';
 import './workbench.js';
-import './nav-stack-CU_0dKtI.js';
+import './nav-stack-CrZF95VO.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
@@ -3247,8 +3278,9 @@ import './sides-BPSWde0A.js';
 import './pane.js';
 import './scroll-clearance-BikHljTc.js';
 import './css-values.js';
+import './surface-tint-DQgYCaP9.js';
 import './workbench.js';
-import './nav-stack-CU_0dKtI.js';
+import './nav-stack-CrZF95VO.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
@@ -3302,8 +3334,9 @@ import './sides-BPSWde0A.js';
 import './pane.js';
 import './scroll-clearance-BikHljTc.js';
 import './css-values.js';
+import './surface-tint-DQgYCaP9.js';
 import './workbench.js';
-import './nav-stack-CU_0dKtI.js';
+import './nav-stack-CrZF95VO.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
@@ -4545,6 +4578,9 @@ type BackdropImageRootAttributes = StructuralRootAttributes & Readonly<{
     'data-fade'?: never;
     'data-repeat'?: never;
     'data-under-chrome'?: never;
+    'data-aspect-ratio'?: never;
+    'data-inline-bleed'?: never;
+    'data-defer-offscreen'?: never;
 }>;
 interface BackdropImageCommonProps {
     /** Image URL. */
@@ -4558,6 +4594,12 @@ interface BackdropImageCommonProps {
     position?: BackdropImagePosition;
     /** Height of the image block. Default 320px (`remify(320)`). */
     height?: CssLength;
+    /** Reserve image height from its width, useful for an inline card. Cannot be combined with `height`. */
+    aspectRatio?: number;
+    /** Native image loading behavior. Omit for the browser default. */
+    loading?: 'eager' | 'lazy';
+    /** Bleed to a Pane's inline content edges. Set false when embedded in a card. Defaults to true. */
+    bleedInline?: boolean;
     /** How far the image lags the scroll. Default `none`. */
     parallax?: BackdropImageParallax;
     /**
@@ -4571,6 +4613,8 @@ interface BackdropImageCommonProps {
      * statically blurred copy. Static (unblurred) wherever parallax is.
      */
     blur?: BackdropImageBlur;
+    /** Skip painting the image hero while it is off screen in a long feed. */
+    deferOffscreen?: boolean;
     /**
      * 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
@@ -4672,6 +4716,15 @@ declare function openDialog(dialog: HTMLDialogElement): void;
  * `close` event fires once it has closed.
  */
 declare function closeDialog(dialog: HTMLDialogElement): void;
+/**
+ * Reconcile one controlled stack after rendering its DialogSurface layers.
+ * Opening back-to-front establishes native top-layer order; unchanged layers
+ * keep their DOM nodes and focus. The application owns `stack.open` and handles
+ * `kui-request-close` to update that state before calling this again.
+ */
+declare function syncDialogStack(root: ParentNode): void;
+/** Follow a controlled stack's render updates until the returned stop runs. */
+declare function wireDialogStack(root: ParentNode): () => void;
 
 type DialogSurfaceSize = 'small' | 'medium' | 'large';
 /**
@@ -4712,6 +4765,8 @@ type DialogSurfaceFooterPresentation = 'docked' | 'floating';
  * material, so content scrolls visibly beneath the title bar.
  */
 type DialogSurfaceHeaderPresentation = 'docked' | 'floating';
+/** The built-in close control's visual weight; `normal` keeps the default. */
+type DialogSurfaceCloseEmphasis = 'normal' | 'quiet';
 /**
  * Application `data-*` identity on the DialogSurface root, such as
  * `data-key`; the surface's own configuration attributes stay protected.
@@ -4729,6 +4784,19 @@ type DialogSurfaceName = {
     labelledBy: string;
 };
 type DialogSurfaceProps = DialogSurfaceName & DialogSurfaceOptions;
+/** Controlled state of one native modal layer inside a `wireDialogStack` root. */
+interface DialogSurfaceStack {
+    /** Whether this layer belongs in the native top layer. */
+    open: boolean;
+    /** The one frontmost open layer; it owns modal focus and accessibility. */
+    active: boolean;
+    /** One-based order from the back to the front. */
+    position: number;
+    /** Number of layers in the stack, including closed layers still rendered. */
+    count: number;
+    /** Optional vertical offset for an inactive layer; omitted on phones. */
+    offset?: CssLength;
+}
 interface DialogSurfaceOptions {
     /** The dialog's id, for `openDialog(document.getElementById(id))`. */
     id?: string;
@@ -4748,6 +4816,8 @@ interface DialogSurfaceOptions {
     alert?: boolean;
     /** The body content. */
     children: KerfUiContent;
+    /** Controlled modal stack state; call `wireDialogStack` on the containing root. */
+    stack?: DialogSurfaceStack;
     /**
      * Header title content in place of the `label` text, such as an xl
      * `ToolbarText` with a description. The dialog keeps its `label` (or
@@ -4767,6 +4837,8 @@ interface DialogSurfaceOptions {
     lightDismiss?: boolean;
     /** The close button's accessible name (default `Close`). */
     closeLabel?: string;
+    /** Soften the built-in close control without changing its 40px target. */
+    closeEmphasis?: DialogSurfaceCloseEmphasis;
     size?: DialogSurfaceSize;
     presentation?: DialogSurfacePresentation;
     /** Modal preferred width. Takes precedence over size, within the viewport cap. */
@@ -4860,7 +4932,7 @@ interface DialogSurfaceOptions {
  * floating header and footer measurement, the bottom sheet's keyboard
  * clearance and grabber, and re-render resilience while open.
  */
-declare function DialogSurface({ id, label, labelledBy, describedBy, alert, heading, headerActions, footer, withoutHeader, lightDismiss, closeLabel, children, size, presentation, preferredWidth, bodyInset, footerInset, viewportGutter, maxHeight, height, minHeight, resizable, enterMotion, exitMotion, bodyLayout, headerPresentation, footerPresentation, footerOffset, rootAttributes, className, slot, }: DialogSurfaceProps): kerfjs.SafeHtml;
+declare function DialogSurface({ id, label, labelledBy, describedBy, alert, heading, headerActions, footer, withoutHeader, lightDismiss, closeLabel, closeEmphasis, children, stack, 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. */
@@ -4927,7 +4999,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 { type DialogCloseSource, type DialogRequestCloseDetail, DialogSurface, type DialogSurfaceBodyLayout, type DialogSurfaceFooterPresentation, type DialogSurfaceHeaderPresentation, type DialogSurfaceHeight, type DialogSurfaceMaxHeight, type DialogSurfaceName, type DialogSurfaceOptions, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceRootAttributes, type DialogSurfaceSheetMotion, type DialogSurfaceSize, PopoverDialogSurface, type PopoverDialogSurfaceDataAttributes, type PopoverDialogSurfacePresentation, type PopoverDialogSurfaceProps, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset, closeDialog, openDialog };
+export { type DialogCloseSource, type DialogRequestCloseDetail, DialogSurface, type DialogSurfaceBodyLayout, type DialogSurfaceCloseEmphasis, type DialogSurfaceFooterPresentation, type DialogSurfaceHeaderPresentation, type DialogSurfaceHeight, type DialogSurfaceMaxHeight, type DialogSurfaceName, type DialogSurfaceOptions, type DialogSurfacePresentation, type DialogSurfaceProps, type DialogSurfaceRootAttributes, type DialogSurfaceSheetMotion, type DialogSurfaceSize, type DialogSurfaceStack, PopoverDialogSurface, type PopoverDialogSurfaceDataAttributes, type PopoverDialogSurfacePresentation, type PopoverDialogSurfaceProps, PopupSurface, type PopupSurfaceInset, type PopupSurfaceProps, type SurfaceInset, closeDialog, openDialog, syncDialogStack, wireDialogStack };
 ```
 
 ## `@kerfjs/ui/list-detail-dialog`
@@ -4939,9 +5011,10 @@ import { CssLength } from './css-values.js';
 import { SplitViewListWidth } from './split-view.js';
 import { DialogSurfaceSize, DialogSurfaceHeight, DialogSurfaceMaxHeight, DialogSurfaceRootAttributes } from './surface-scaffold.js';
 export { DialogCloseSource, DialogRequestCloseDetail, closeDialog, openDialog } from './surface-scaffold.js';
-import './nav-stack-CU_0dKtI.js';
+import './nav-stack-CrZF95VO.js';
 import './pane.js';
 import './scroll-clearance-BikHljTc.js';
+import './surface-tint-DQgYCaP9.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
@@ -5067,9 +5140,10 @@ import { CssLength } from './css-values.js';
 import { WorkbenchMainBottomToolbar, WorkbenchPanel } from './workbench.js';
 import { DialogSurfaceSize, DialogSurfaceHeight, DialogSurfaceMaxHeight, DialogSurfaceRootAttributes } from './surface-scaffold.js';
 export { DialogCloseSource, DialogRequestCloseDetail, closeDialog, openDialog } from './surface-scaffold.js';
-import './nav-stack-CU_0dKtI.js';
+import './nav-stack-CrZF95VO.js';
 import './pane.js';
 import './scroll-clearance-BikHljTc.js';
+import './surface-tint-DQgYCaP9.js';
 import './list.js';
 import './extension-attributes-mu8MFUl0.js';
 import './flex-alignment-4ms8ZbV8.js';
@@ -5277,6 +5351,78 @@ declare function Text({ variant: Variant, tone, color, size, font, border, flush
 export { FieldLabel, type FieldLabelProps, Sides, Text, type TextAlign, type TextBorder, type TextContent, type TextFont, type TextLineHeight, type TextProps, type TextSize, type TextTone, type TextTruncate, type TextTruncateKeep, type TextVariant, type TextWrap };
 ```
 
+## `@kerfjs/ui/editor-frame`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { K as KerfUiContent } from './semantic-content-BbzjvSu9.js';
+import { CssLength } from './css-values.js';
+
+type EditorFrameMode = 'source' | 'preview';
+type EditorFrameAppearance = 'framed' | 'embedded';
+type EditorFrameInset = 'padded' | 'flush';
+interface EditorFrameProps {
+    /** A Toolbar or other fixed controls above the writing surface. */
+    toolbar?: KerfUiContent;
+    /** A native textarea in source mode, or rendered content in preview mode. */
+    children: KerfUiContent;
+    mode: EditorFrameMode;
+    /** Framed fixed-height card (default) or unframed content within a host. */
+    appearance?: EditorFrameAppearance;
+    /** Remove the writing surface inset when the host owns the text column. */
+    inset?: EditorFrameInset;
+    /** Fill the viewport inset as a raised editor overlay. */
+    expanded?: boolean;
+    /** Framed block size; defaults to 320px. Ignored while expanded or embedded. */
+    height?: CssLength;
+    /** Maximum framed inline size; defaults to 672px. */
+    maxWidth?: CssLength;
+    /** Embedded source height restored by the app. */
+    sourceHeight?: CssLength;
+    /** Let an embedded native textarea grow with its content. */
+    sourceAutosize?: boolean;
+    /** Name a distinct editor region for assistive technology. */
+    label?: string;
+    /** App-owned root identity for delegation or a stable morph key. */
+    rootAttributes?: Readonly<Record<`data-${string}`, string | undefined>>;
+    slot?: string;
+}
+/**
+ * A fixed toolbar over one writing surface. Source mode gives a native
+ * textarea the scrollport; preview mode scrolls the surface around rendered
+ * content. The app owns editing, draft restoration, and preview actions.
+ */
+declare function EditorFrame({ toolbar, children, mode, appearance, inset, expanded, height, maxWidth, sourceHeight, sourceAutosize, label, rootAttributes, slot, }: EditorFrameProps): kerfjs.SafeHtml;
+
+export { EditorFrame, type EditorFrameAppearance, type EditorFrameInset, type EditorFrameMode, type EditorFrameProps };
+```
+
+## `@kerfjs/ui/value-preview`
+
+```ts
+import * as kerfjs from 'kerfjs';
+import { CssLength } from './css-values.js';
+
+interface ValuePreviewProps {
+    /** Accessible name for the keyboard-scrollable value. */
+    label: string;
+    /** Literal plain-text value, including newlines and long unbroken text. */
+    value: string;
+    /** Minimum height; defaults to 48px. */
+    minHeight?: CssLength;
+    /** Maximum height before the value scrolls; defaults to 96px. */
+    maxHeight?: CssLength;
+    id?: string;
+    className?: string;
+    /** Native named-slot assignment when composed inside a web component. */
+    slot?: string;
+}
+/** Read-only, bounded multiline text for a containing surface such as SunkenPanel. */
+declare function ValuePreview({ label, value, minHeight, maxHeight, id, className, slot, }: ValuePreviewProps): kerfjs.SafeHtml;
+
+export { ValuePreview, type ValuePreviewProps };
+```
+
 ## `@kerfjs/ui/framed-list`
 
 ```ts
@@ -5348,7 +5494,7 @@ type SummaryRowRootAttributes = Readonly<Record<`data-${string}`, string | undef
     'data-selected'?: never;
     'data-dimmed'?: never;
 }>;
-interface SummaryRowProps {
+interface SummaryRowBaseProps {
     /** The identity line: an identifier, inline status glyphs, and the title. */
     title: KerfUiContent;
     /** Optional leading glyph, such as a category icon. */
@@ -5363,7 +5509,7 @@ interface SummaryRowProps {
     titleLines?: number;
     /** A leading state rail in a semantic tone (Up Next, blocked, …). */
     rail?: SemanticTone;
-    /** Selected state, exposed as `aria-selected`. */
+    /** Selected visual state; also exposed as `aria-selected` for an option. */
     selected?: boolean;
     /** Dim a finished or cut item; hover and selection restore it. */
     dimmed?: boolean;
@@ -5371,21 +5517,30 @@ interface SummaryRowProps {
     listEdge?: SummaryRowListEdge;
     /** Skip rendering while off screen in long lists (`content-visibility`). */
     deferRendering?: boolean;
-    /** Accessible name when the visible content is not a good one. */
-    ariaLabel?: string;
     id?: string;
     className?: string;
-    /** Safe `data-*` identity (an item id or delegated action) on the option. */
+    /** Safe `data-*` identity (an item id or delegated action) on the root. */
     rootAttributes?: SummaryRowRootAttributes;
 }
+type SummaryRowProps = SummaryRowBaseProps & ({
+    /** Selectable option, the default; place it in a labeled listbox. */
+    semanticRole?: 'option';
+    /** Native HTML drag source on this option root, in row or card form. */
+    draggable?: boolean;
+    /** Accessible name when the visible content is not a good one. */
+    ariaLabel?: string;
+} | {
+    /** Static labeled group; nested actions own focus and activation. */
+    semanticRole: 'group';
+    draggable?: never;
+    ariaLabel: string;
+});
 /**
- * A selectable, keyboard-focusable summary of one item, as a list row or a
- * board card: an optional leading glyph and state rail, a clamped identity line
- * with trailing quiet metadata, and a wrapping metadata line. It is a
- * `role="option"`; place rows in a labeled `role="listbox"` and own selection
- * and keyboard movement in the application.
+ * A list row or board card with a clamped identity line, metadata, and state
+ * rail. The default is a focusable `role="option"` for a labeled listbox;
+ * `semanticRole="group"` gives a static labeled row for nested actions.
  */
-declare function SummaryRow({ title, leading, trailingMeta, metadata, presentation, titleLines, rail, selected, dimmed, listEdge, deferRendering, ariaLabel, id, className, rootAttributes, }: SummaryRowProps): SafeHtml;
+declare function SummaryRow({ title, leading, trailingMeta, metadata, presentation, titleLines, rail, selected, dimmed, listEdge, deferRendering, semanticRole, draggable, ariaLabel, id, className, rootAttributes, }: SummaryRowProps): SafeHtml;
 
 export { SummaryRow, type SummaryRowListEdge, type SummaryRowPresentation, type SummaryRowProps };
 ```
@@ -6662,6 +6817,8 @@ interface ButtonOptions {
      * flips it in its `action` handler. A link (`href`) cannot be a toggle.
      */
     pressed?: boolean;
+    /** Mark the current step in a sequence with `aria-current="step"`. */
+    currentStep?: boolean;
     /**
      * Busy: a spinner replaces the label (which still names it) and the button
      * reports `aria-busy`. Presses still reach it; the application decides
@@ -6716,12 +6873,12 @@ interface ButtonOptions {
  * in one of four tones and three emphases, at the 44px control height or
  * compact, with a label or as an icon-only square, rounded or pill-shaped,
  * sized to its label or filling its parent's width, and optionally a
- * `pressed` toggle. Inside a
+ * `pressed` toggle or `currentStep` marker. Inside a
  * `ToolbarControlGroup`, use a plain `<button>`, which the group styles; use
  * Button for a dialog footer, a form, or a standalone action beside other
  * content.
  */
-declare function Button({ children, tone, emphasis, size, shape, fill, pressed, icon, loading, disabled, type, name, value, form, href, target, action, focusRingInset, badge, badgeLabel, badgeTone, ariaLabel, title, id, className, rootAttributes, slot, }: ButtonProps): kerfjs.SafeHtml;
+declare function Button({ children, tone, emphasis, size, shape, fill, pressed, currentStep, icon, loading, disabled, type, name, value, form, href, target, action, focusRingInset, badge, badgeLabel, badgeTone, ariaLabel, title, id, className, rootAttributes, slot, }: ButtonProps): kerfjs.SafeHtml;
 
 export { Button, type ButtonContent, type ButtonEmphasis, type ButtonLabel, type ButtonOptions, type ButtonProps, type ButtonRootAttributes, type ButtonShape, type ButtonSize, type ButtonTone, type ButtonType };
 ```