@kerfjs/ui 4.5.0-beta.1 → 5.0.0-beta.100

package/docs/split-view.md

@@ -8,11 +8,29 @@ on compact ones. One of the opt-in app layouts (see
 ```ts
 import { SplitView } from "@kerfjs/ui/split-view";
 import { deviceClass } from "@kerfjs/ui/device-class";
-import "@kerfjs/ui/split-view.css";
-// plus nav-stack.css when the compact path is reachable, and
-// wireResizableRegions / wireNavStack for the interactive behavior.
+// plus wireResizableRegions / wireNavStack for the interactive behavior.
 ```
 
+In a browser bundler that honors the `browser` export condition (Vite, esbuild, and
+webpack do by default), the import above also
+loads SplitView's stylesheet and those of the components it renders internally
+(its compact `NavStack`, `ResizableRegion`, and the toolbar
+components). Without that condition, import the manual stylesheets instead:
+`@kerfjs/ui/split-view.css` plus those components' CSS, or `@kerfjs/ui/styles.css`.
+
+## Safe areas
+
+The list pane grows by the inline-start unsafe inset and pads for the edges it
+touches; the detail pads for its own outer edges. Neither is inset on the
+shared interior edge. A pane whose only child is a `Pane` lets that child own
+the insets, and the compact form hands them to its `NavStack`. See
+[Choosing an app layout › Safe areas](app-layouts.md#safe-areas).
+
+For a lowered list or detail background, render a `Pane` in that region with
+`appearance="sunken"`. SplitView arranges regions but does not own their
+vertical scroll; its compact NavStack form can use the view's or nested Pane's
+appearance. See [Lowered work surfaces](layout.md#lowered-work-surfaces).
+
 ## Responsive by device class
 
 `SplitView` is declarative; the app derives `compact` from the device class and
@@ -37,13 +55,84 @@ const selected = signal<string | null>(null);
 
 - **Roomy** (`compact: false`): both panes show. With `resizable`, the list sits
   in a `ResizableRegion` (wire it with `wireResizableRegions`); without it the
-  list takes a fixed `--kui-split-view-list-width` (default 320px) and the detail
-  fills the rest.
+  list takes a fixed width and the detail fills the rest. Set it with
+  `listWidth`: a number of CSS pixels (default 320), or `{ size, maxFraction }`
+  to cap the preferred size at that share of the SplitView's own width, so a
+  narrow container (a dialog, a small window) always leaves the detail in view —
+  `listWidth={{ size: 432, maxFraction: 0.5 }}` is 432px until the split is
+  narrower than 864px, then half of it. `listWidth` is for the fixed split; a
+  resizable list is sized by `resizable` (combining them throws). The
+  `--kui-split-view-list-width` token remains for theme-level defaults; the
+  prop wins over it.
 - **Compact** (`compact: true`): the split collapses to a `NavStack`. The list is
   the root; when `detailActive` is true the detail is pushed over it with an
   automatic back control (wire it with `wireNavStack`, whose `onBack` clears the
   app's selection). This is the portrait-tablet / handset presentation; as a
   dialog the compact form is a full-screen or large partial-cover modal.
 
+## Filling its container
+
+A SplitView fills its container's block size: give the container a definite
+height (a fixed or viewport-bounded `height`, a flex item that grows, a grid
+row) and the split stretches to it, with each `Pane` owning its own scrolling.
+That holds in a block box, a fixed-size native popover or dialog, a flex column
+below a header, and a grid; no app-side `display: grid` /
+`grid-template-rows: minmax(0, 1fr)` wrapper is needed. A container sized only
+by `max-height` has no height to fill, so the split takes its content height;
+give such a container a `height` instead.
+
+## Configuring the list region and the compact stack
+
+`resizable` forwards the list's `ResizableRegion` configuration alongside
+`size`, `min`, and `max`: `separator` (`"hidden"` keeps the resize hit target
+but paints no line), `handleIcon`, `contentOverflow`, and collapse —
+`collapsed`, `transitioning`, `collapseMotion`, `restoreControl`, and
+`restorePosition`. A collapsed list snaps to zero width, renders `inert` and
+`aria-hidden`, and the detail fills the split; the app owns the `collapsed`
+flag and renders the restore control (usually a `FloatingToolbar`). Omitted
+options keep the region's defaults.
+
+```tsx
+resizable={{
+  size: listWidth.value,
+  min: 220,
+  max: 480,
+  collapsed: listCollapsed.value,
+  restoreControl: <ShowThreadsToolbar />,
+}}
+```
+
+`compactStack` configures the compact `NavStack`: `toolbarConfig`, `backIcon`,
+`backText`, `hideToolbar`, the persistent `bottomToolbar`, and `chromeDividers`
+forward to the stack, and `list` / `detail` give each view its own structured
+top `toolbar` (`leading`, `center`, `trailing`) and `bottomToolbar`:
+
+```tsx
+compactStack={{
+  backText: "Threads",
+  toolbarConfig: { headingLevel: 1 },
+  list: { toolbar: { trailing: <ComposeGroup /> } },
+  detail: {
+    toolbar: { trailing: <ReplyGroup /> },
+    bottomToolbar: { label: "Message Actions", leading: <MessageActions /> },
+  },
+}}
+```
+
+The catalog's **Interactive Compact Drill-Down** example exercises this exact
+controlled flow: a list action sets the selected message, `detailActive` pushes
+its detail, and the wired Back action clears the selection to reveal the
+preserved list. It also forwards `compactStack`: a level-2 heading title over
+a bottom divider, a Compose group on the list view, and a Reply group plus a
+bottom toolbar on the detail. Use the same structure in application demos so
+compact examples show the interaction rather than rendering a disconnected
+detail state.
+
+The catalog's **Resizable, Collapsible List** example forwards `resizable`: a
+hidden separator that still resizes the list (its committed width comes back
+through `wireResizableRegions`' `onCommit` into the app's size signal), a Hide
+control in the list's own toolbar, and a `FloatingToolbar` restore control in
+the split's bottom-start corner.
+
 Compose the interactive wiring from the existing helpers — `SplitView` adds no
 wire of its own.

package/docs/sunken-panel.md

@@ -8,7 +8,7 @@ issue tracker or component catalog.
 ```tsx
 import { SunkenPanel } from '@kerfjs/ui/sunken-panel';
 
-<SunkenPanel ariaLabel="Release workspace">
+<SunkenPanel ariaLabel="Release Workspace">
   <ReleaseSummary />
   <ReleaseChecks />
 </SunkenPanel>;
@@ -23,6 +23,28 @@ The default `shape="rounded"` uses the shared rounded-rectangle radius. Choose
 </SunkenPanel>
 ```
 
+## Filling a work area
+
+Set `fill` when the panel is the direct layout root of a parent with a definite
+height. Inside a flex column, use `flex` so it takes the remaining space and
+can shrink with its parent. Like `Grid`, `flex` accepts `true` (equivalent to
+`1 1 auto`), a CSS flex keyword, or a typed `CssFlex` value. The panel keeps
+`min-height: 0`, allowing its parent to own scrolling.
+
+```tsx
+<List fill>
+  <Toolbar label="Work Area" />
+  <SunkenPanel flex>
+    <WorkArea />
+  </SunkenPanel>
+</List>
+```
+
+Inside a `Pane`, the Pane's content remains the scroll owner. Place a
+`SunkenPanel fill` in a definite-height Pane content region when the surface
+itself needs to cover empty space, or use `flex` when a flex parent allocates
+the remaining space. The panel does not add another scroller.
+
 ## Ownership
 
 The root owns its lowered background, 8px padding, and 8px vertical gap.
@@ -34,10 +56,20 @@ Use `ariaLabel` only when the surface is a distinct region people need to find
 by name. With a label, the root receives `role="region"`; without one it remains
 a non-landmark grouping.
 
+Set `tabIndex={0}` to include the whole panel in the Tab order, or
+`tabIndex={-1}` for a programmatic focus target. Keyboard focus draws the
+standard focus ring. `outlined` keeps the same ring visible independently of
+focus, for example while the panel is a drop target. Give a focusable work area
+an `ariaLabel` when it is a distinct named region.
+
 Do not use `SunkenPanel` merely to add padding, as a substitute for pane
 header/content/footer anatomy, or around a child that already owns the same
 outer surface.
 
+For a lowered scrolling work area with Pane chrome, use
+[`Pane appearance="sunken"`](layout.md#lowered-work-surfaces). It paints the
+scroll viewport and empty space without adding a second scroller.
+
 ## Public styling boundary
 
 Override the public properties at the composition boundary:
@@ -48,6 +80,27 @@ Override the public properties at the composition boundary:
 - `--kui-sunken-panel-gap`
 - `--kui-sunken-panel-radius`
 
+The default background uses the shared translucent lowered-surface token.
+Nested panels composite naturally at every depth: darker in light mode and
+lighter in dark mode, without wrappers, depth classes, or per-instance token
+assignments. Pane and Web Awesome sunken surfaces use the same palette.
+See [Contextual transparency](./webawesome-theme.md#contextual-transparency).
+Keep ordinary composition on these defaults; public properties are theming
+escape hatches, not a reason to restyle each demo or nesting level.
+
+Every sunken surface — SunkenPanel, `Pane appearance="sunken"`, sunken
+Workbench regions and TabNavigator scenes, and Web Awesome
+`appearance="sunken"` — paints `--kui-sunken-surface`: a fine, monochrome
+grain (a seeded 100px tile at 4% maximum opacity) over the lowered color. The
+tile is drawn once per page, at runtime, by the first sunken surface that
+renders (nothing ships as an asset; server rendering paints the flat color
+until the browser renders one). Translucent children such as a `ValueTable`
+let the grain show through rather than adding their own. Set
+`--kui-sunken-texture: none` at `:root` for a flat lowered surface, or to
+another image; call `ensureSunkenTexture()` (exported from
+`@kerfjs/ui/sunken-panel`) on a page whose only sunken surfaces are Web Awesome
+elements.
+
 The public root class is `.kui-sunken-panel`. Prefer the properties above over
 styling descendants. The `square` shape deliberately overrides the radius
 property with zero; use `rounded` when customizing the radius token.

package/docs/surface-scaffold.md

@@ -0,0 +1,270 @@
+# Dialog and popup surface scaffolds
+
+`DialogSurface` and `PopupSurface` configure recurring Web Awesome surface
+geometry without application `::part()` overrides. They do not replace Web
+Awesome behavior: the application still owns open state, dismissal policy, ids,
+labels, and content. With `@kerfjs/ui/popup-menu/register` imported, a dropdown
+inside `PopupSurface` also keeps keyboard item navigation made during its show
+animation when Web Awesome completes its initial focus handoff.
+
+Wrap one `wa-dialog` with `DialogSurface`. Choose `size` (`small`, `medium`, or
+`large`), `presentation` (`modal`, `side-sheet`, or `fullscreen`), and independent
+`bodyInset` / `footerInset` (`none`, `compact`, or `comfortable`). The defaults
+match Kerf's medium modal, 8px body, and 16px footer rhythm.
+
+The modal size presets have preferred widths of 400px, 560px, and 800px,
+respectively, before the viewport width cap. Set `preferredWidth` to a branded
+`CssLength` when the desktop shell needs another width. It takes precedence over
+`size`, while the viewport cap still applies. For example, 832px and 480px
+desktop preferences can share the same responsive dialog without changing its
+resource tracks or preview aspect sizing.
+
+### Sibling dialogs keep their identity
+
+Every `DialogSurface` root has the same structure, so two sibling dialogs that
+are rendered conditionally are matched by position when the page re-renders:
+one open dialog's element (with its accessible name and open state) can be
+reused for another, and Web Awesome events such as `wa-after-hide` fire on the
+wrong dialog or not at all. Give each sibling a stable key on its root with
+`rootAttributes`, instead of wrapping it in an app `div`:
+
+```tsx
+<DialogSurface rootAttributes={{ "data-key": "project-setup" }}>
+  <wa-dialog label="Set up project">…</wa-dialog>
+</DialogSurface>
+```
+
+`rootAttributes` takes `data-*` identity only; the surface's own configuration
+attributes (`data-size`, `data-presentation`, …) stay protected.
+
+### Modal viewport bounds
+
+`viewportGutter` accepts a branded `CssLength` from `@kerfjs/ui/css-values`.
+It sets the minimum horizontal clearance; `preferredWidth` overrides the `size`
+preset when supplied. `maxHeight` accepts a branded length or `"viewport"`; explicit caps are
+clamped to the dynamic viewport height minus twice the gutter (16px per edge
+when the gutter is omitted). Negative gutters/caps clamp to zero. Omitting
+both options preserves Web Awesome's existing width and phone height caps.
+These options apply only to `presentation="modal"`; side sheets and fullscreen
+surfaces keep their own geometry.
+
+```tsx
+import '@kerfjs/ui/surface-scaffold/register';
+import { remify } from '@kerfjs/ui/css-values';
+import { DialogSurface } from '@kerfjs/ui/surface-scaffold';
+
+<DialogSurface preferredWidth={remify(832)} viewportGutter={remify(8)} maxHeight="viewport" bodyInset="none">
+  <wa-dialog label="Close Workspace">{/* Application-owned content and footer */}</wa-dialog>
+</DialogSurface>;
+```
+
+This gives a desktop modal an 832px preferred width and a phone modal an 8px edge gutter with a `calc(100dvh - 16px)` height
+cap without application selectors on Kerf roots or Web Awesome parts. A cap
+is not a fixed height: short content stays naturally sized, and taller content
+scrolls in Web Awesome's body while its header/footer remain outside that
+scroll owner. Choosing a larger cap cannot guarantee that arbitrary content
+fits without scrolling; preview tracks, canvas aspect ratios and content sizing
+remain application-owned.
+
+Responsive policy is explicit application state: read `deviceClass()` during
+the render to choose the gutter, cap or presentation. For example use
+`viewportGutter={remify(device.value.handset ? 8 : 16)}` with `maxHeight="viewport"`.
+The scaffold introduces no hidden breakpoint or automatic fullscreen switch.
+An application can configure device-class breakpoints when its phone policy
+differs from the default. Prefer a typed cap such as `maxHeight={remify(640)}`
+when the modal should stop growing before the viewport bound.
+
+### Filling the dialog
+
+`maxHeight` caps a modal that sizes to its content. A layout that fills the
+dialog (a list-detail `SplitView`, a `Pane` with its own chrome and scroller)
+needs a height to fill instead: set `height` to a branded length or
+`"viewport"`. It is bounded exactly like `maxHeight` (the dynamic viewport minus
+both gutters) and takes precedence over it. `bodyLayout="fill"` then gives the
+body's whole height to its one child, which owns its own scrolling; the body
+itself stops scrolling. Combine it with `bodyInset="none"`.
+
+```tsx
+<DialogSurface size="large" height={remify(640)} viewportGutter={remify(8)} bodyInset="none" bodyLayout="fill">
+  <wa-dialog label="Repository Status">
+    <SplitView id="repo-split" label="Changes" listWidth={{ size: 432, maxFraction: 0.5 }} list={list} detail={detail} />
+  </wa-dialog>
+</DialogSurface>;
+```
+
+### Chat dialogs: a floating footer over a filling transcript
+
+A chat-style dialog keeps a heading or notices above one scrolling transcript
+and floats its composer over the body's block end. Two props compose it:
+
+- `bodyLayout="fill-last"` stacks the body's children: the leading children
+  keep their natural height, and the last one takes the remaining height and
+  owns its scrolling (a `scrollable` `List` transcript). The body itself stops
+  scrolling. `PopoverDialogSurface` accepts the same layout.
+- `footerPresentation="floating"` lays the footer over the body's block end,
+  `footerOffset` (a branded `CssLength`, default the 16px container inset)
+  from the panel's inline and block-end edges, on a transparent background.
+  The modal panel is its positioning context. The default `docked` footer
+  sits below the body as before.
+
+The register measures the footer (it follows a composer that grows, wraps, or
+hides) and the body reserves that height plus the offset after its own inset,
+with a matching `scroll-padding`. Flowing body content scrolls beneath the
+floating footer and its end stays reachable above it; with `fill` or
+`fill-last` the filling child's scrollport ends at the footer's top. Content
+is never hidden beneath the footer.
+
+To let a filling transcript scroll visibly beneath the floating footer, opt
+its scroller in with `scrollClearance="block-end"` (a `scrollable` `List`, or a
+`Pane`, as the `fill` or last `fill-last` child). The body then stops
+reserving the footer below that child, so the child reaches the panel's block
+end, and publishes the footer's clearance (measured height plus offset) as the
+inherited `--kui-scroll-clearance-block-end` context. The child adds it to its
+own block-end padding and `scroll-padding`: messages pass beneath the
+transparent footer mid-scroll, the last message rests above the composer at
+the end, and focus or `scrollIntoView` never leaves an item hidden beneath it.
+The context is general: chrome that overlays a region's block-start or
+block-end edge publishes `--kui-scroll-clearance-block-start` / `-end`, and a
+scroll owner opts in per edge (see `docs/layout.md` "Scroll clearance"). A
+dialog body clears any clearance inherited from the page.
+
+Choose the offset like any other responsive value: the scaffold adds no
+breakpoint. An 8px offset lines a composer up with the transcript's
+content-item edges when the body has `bodyInset="none"` and list geometry;
+`viewportGutter` and `footerOffset` can follow `deviceClass()` when a phone
+needs tighter edges. Put a [`Composer`](./composer.md) in the floating footer
+with `footerInset="none"`: its raised frame and shadow lift it over the
+transcript, and its field grows the measured footer. With `submitOnEnter` and
+`wireComposers(root)`, Enter sends through the same action as the Send button.
+
+```tsx
+<DialogSurface height={remify(560)} viewportGutter={remify(8)} bodyInset="none" bodyLayout="fill-last" footerPresentation="floating" footerOffset={remify(8)} footerInset="none">
+  <wa-dialog label="Assistant">
+    <StateBanner title="Answers use the latest nightly build." tone="neutral" />
+    <List gap="xs" controlInsets="tb" scrollable scrollClearance="block-end">
+      {messages.map((message) => (
+        <ContentItem bubble={message.mine ? 'end' : 'start'} appearance={message.mine ? 'brand-loud' : 'neutral'}>
+          <Text variant="span">{message.text}</Text>
+        </ContentItem>
+      ))}
+    </List>
+    <Composer submitOnEnter slot="footer" id="assistant-message" name="message" label="Message" placeholder="Ask about this build" actions={<wa-button variant="brand" data-action="send-message">Send</wa-button>} />
+  </wa-dialog>
+</DialogSurface>;
+```
+
+### A floating title bar
+
+`headerPresentation="floating"` lays the dialog's header (its title and close
+control) over the body's block-start edge on the translucent chrome material,
+`--kui-chrome-material-raised` (the raised panel surface at 80% opacity)
+behind `--kui-chrome-material-filter` (a blur and saturation backdrop filter).
+Content passing beneath the title bar reads as softened color, not as
+competing text. The default `docked` header sits above the body as before.
+
+The register measures the header the same way it measures the footer (it
+follows a title that wraps, text that grows, or a `without-header` toggle).
+The body reserves the measured height before its own inset, with a matching
+`scroll-padding`, so flowing content starts below the title bar and scrolls
+beneath it. A dialog without the register has no measurement, so its header
+stays docked rather than covering content.
+
+To let a filling transcript scroll visibly beneath the title bar, make it the
+body's only child (`bodyLayout="fill"`, or `fill-last` with no leading rows)
+and opt its scroller in with block-start `scrollClearance`. The body then
+stops reserving the header, so the child reaches the panel's block-start
+edge, and publishes the header's height as `--kui-scroll-clearance-block-start`.
+Leading `fill-last` rows (a notice above the transcript) keep the body's
+reservation: they never sit beneath the title bar. Combined with a floating
+composer and `scrollClearance="both"`, the transcript scrolls beneath both:
+
+```tsx
+<DialogSurface height={remify(560)} viewportGutter={remify(8)} bodyInset="none" bodyLayout="fill" headerPresentation="floating" footerPresentation="floating" footerOffset={remify(8)} footerInset="none">
+  <wa-dialog label="Release Thread">
+    <ToolbarText slot="label" text="Release Thread" size="xlarge" description="Engineering · 5.2 candidate" />
+    <List gap="xs" controlInsets="tb" scrollable scrollClearance="both">
+      {bubbles}
+    </List>
+    <Composer submitOnEnter slot="footer" id="thread-message" name="message" label="Message" placeholder="Reply to the thread" actions={<wa-button variant="brand" data-action="send-message">Send</wa-button>} />
+  </wa-dialog>
+</DialogSurface>;
+```
+
+Like a `Pane`'s overlay header, the title bar draws its divider as scroll
+state: a 1px line along its bottom edge only while the body, or a filling
+child that reaches beneath it, is scrolled away from its top, and none at
+rest. The register follows those scrollers (a nested scroller that starts
+below the title bar never counts), and the line is an inset shadow, so it
+never moves the header or the content.
+
+The material turns opaque under `prefers-reduced-transparency: reduce` or
+`prefers-contrast: more`, and where the browser lacks `backdrop-filter`; in
+forced colors the header paints `Canvas` with a `CanvasText` bottom edge.
+
+For a title with a short supporting line, slot a `ToolbarText` as the label
+(`<ToolbarText slot="label" text="Release Thread" size="xlarge" description="Engineering · 5.2 candidate" />`).
+On the floating title bar an untoned `ToolbarText` keeps AA by itself: its
+title takes the normal text color and its description lifts halfway toward
+it. Any other quiet copy you place there can fall below AA over the content
+passing beneath it, so keep it in the body (see
+[Accessibility › Chrome material](accessibility.md#chrome-material)).
+
+Treat a dialog body as a `List` by default. When its rows or sections own their
+standard list geometry, set `bodyInset="none"` so the dialog does not add a
+second inset. Bare prose is still a list child: wrap it in `ListInsetText` so its
+text edge receives the standard 8px margin + 1px transparent border + 8px
+padding and aligns with bordered siblings. Reserve `compact` or `comfortable`
+body insets for exceptional content that does not already have list/content-item
+geometry.
+
+## Non-modal dialogs: `PopoverDialogSurface`
+
+`wa-dialog` is modal: it makes the page inert until it closes. When a dialog
+should leave the page interactive and close on Escape or a press outside (a
+status panel, a quick inspector), render `PopoverDialogSurface` instead of a
+hand-built popover with application chrome CSS. It is a native
+`popover="auto"` section with `role="dialog"` that owns Kerf's dialog chrome
+(raised surface, border, large radius and shadow, and a backdrop) and the
+same geometry props as a modal `DialogSurface`: `size`, `preferredWidth`,
+`viewportGutter` (16px by default), `height` / `maxHeight`, and `bodyLayout`
+(`flow`, `fill`, or `fill-last`).
+Name it with `label` or `labelledBy`. To give it an accessible description,
+pass `describedBy`, the id of the element that holds the summary. It renders as
+`aria-describedby` on the `role="dialog"` root and usually names a title
+`ToolbarText`'s `descriptionId`:
+
+```tsx
+<PopoverDialogSurface id="connection-details" labelledBy="connection-title" describedBy="connection-summary" bodyLayout="fill-last">
+  <Toolbar label="Connection Details Heading" leading={<ToolbarText text="Connection Details" size="xlarge" id="connection-title" description="Connected to the build server." descriptionId="connection-summary" />} />
+  {details}
+</PopoverDialogSurface>;
+```
+
+`DialogSurface` has no `describedBy`. It wraps a `wa-dialog` that the app
+authors, so the app names and describes that dialog on its own markup.
+
+Open it with a control's `popoverTarget` (or `showPopover()`); the browser
+places it centered in the top layer, light-dismisses it, and restores nothing
+else, so move focus into it with `autofocus` on its first control when that
+matters. A closed surface stays hidden; only the open one lays out.
+`presentation="embedded"` renders the same surface in flow, with no top
+layer and never wider than its container, for a catalog specimen or an inline
+preview.
+
+```tsx
+<button type="button" popoverTarget="repository-status">Repository Status</button>
+<PopoverDialogSurface id="repository-status" label="Repository Status" preferredWidth={remify(1024)} height={remify(640)} viewportGutter={remify(8)} bodyLayout="fill">
+  <SplitView id="repo-split" label="Changes" list={list} detail={detail} />
+</PopoverDialogSurface>;
+```
+
+Use `DialogSurface` with `wa-dialog` whenever the task must block the page.
+
+Wrap one `PopupMenu` (or another single `wa-dropdown`) with `PopupSurface`. `inset="list-zero"` removes menu
+padding for a child that already owns row insets, `compact` uses 4px, and
+`standard` uses the shared 8px surface inset. Keep the dropdown trigger named and
+preserve `data-morph-skip-children` when its upgraded light-DOM items must retain
+identity across Kerf rerenders. Import `@kerfjs/ui/popup-menu/register` once for
+the focus handoff fix when wrapping a raw `wa-dropdown`.
+
+Import `@kerfjs/ui/surface-scaffold/register` once when using `DialogSurface`: it registers `wa-dialog`, measures each surface's footer for a floating footer's body clearance, draws a floating header's divider while content is scrolled beneath it, 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.