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

package/docs/anchored-surface.md

@@ -0,0 +1,107 @@
+# AnchoredSurface
+
+Use `openAnchoredSurface` from `@kerfjs/ui/anchored-surface` for interactive help
+or other arbitrary content beside a control. Use `openAnchoredSurfaceAt` for a
+pointer location. Import `@kerfjs/ui/styles.css` or the individual
+`@kerfjs/ui/anchored-surface.css` stylesheet. The surface draws its own raised
+background, border, inset, radius, shadow, and viewport size limit; the app
+supplies the content and decides when to open or close it.
+
+```tsx
+import { openAnchoredSurface } from '@kerfjs/ui/anchored-surface';
+
+const help = openAnchoredSurface(button, () => <HelpContent />, {
+  label: 'Pricing help',
+});
+// Close after an app action: help.close();
+```
+
+The returned `OverlayHandle` has `el`, idempotent `close()`, and `result`.
+The surface is a non-modal `role="dialog"` named by the required nonempty `label`.
+Focus moves to its first focusable descendant by default and returns to the
+focusable anchor on close (or the previously focused element for a nonfocusable
+anchor). Pass `initialFocus: false` for read-only
+help that leaves focus on its trigger. Escape and an outside press dismiss it;
+`dismiss`, `onDismiss`, and `outsideIgnore` can customize that behavior.
+`placement` (`bottom` or `top`), `align` (`start` or `end`), `gap`, and
+`viewportMargin` feed the shared `kerfjs/overlay` positioning core: it flips
+vertically when the other side fits, keeps the surface `viewportMargin` (default
+8px) inside the viewport edges, and follows scroll, resize, and changes to the
+anchor's own size. Anchor help for a field to the whole field rather than to a
+button inside it: the surface then clears every line of a field that wraps, and
+moves as the field grows (a SearchField's trailing help action opens beside
+`[data-component="search-field"]`, which also keeps typing in the field from
+dismissing it). The surface fits
+its height to the room beside the anchor: when neither side holds it, it opens
+on the roomier side, caps its height to that room, and scrolls its content.
+The room is exposed to the content as `--kui-anchored-surface-available-height`
+and refreshed on every reposition, so a tall help surface fits beside a field on
+a phone without application media queries or `max-height` overrides.
+
+```tsx
+openAnchoredSurfaceAt(
+  { x: event.clientX, y: event.clientY, context: event.target as Element },
+  () => <ContextHelp />,
+  { label: 'Context help' },
+);
+```
+
+Pass `context` for a pointer opened inside a modal dialog. Inside a
+`DialogSurface`, the surface stays interactive with no extra markup: the
+dialog renders the host `kerfjs/overlay` uses. Inside a Web Awesome
+`wa-dialog` or `wa-drawer`, `kerfjs/overlay` finds the modal `<dialog>` in the
+element's shadow root and hosts the surface in the element's light DOM,
+slotted inside the dialog. Dialogs opened by `kerfjs/overlay` get a host
+automatically too. For another app-owned native `<dialog>`, include
+`<div data-kerf-overlay-host data-morph-skip></div>` in the dialog markup so
+controls in the anchored surface stay interactive. For any other modal context,
+pass `container`: an element inside the open modal, where the surface is
+appended instead. The helper uses the browser top layer where available, and
+the shared overlay fallback elsewhere.
+
+Closing the anchor's modal dialog also closes the surface. Escape closes only
+the surface; the dialog beneath stays open. The temporary pointer anchor is
+removed when the surface closes.
+
+## Dark tone for media chrome
+
+A popup anchored to dark media chrome (a volume control in a
+`ToolbarControlGroup tone="dark"` over a video or image preview) passes
+`tone: 'dark'`:
+
+```tsx
+openAnchoredSurface(volumeButton, () => <VolumeControls />, {
+  label: 'Volume',
+  tone: 'dark',
+  placement: 'top',
+});
+```
+
+The tone is the same loud, inverse tone as a dark `ToolbarControlGroup` or
+`ToolbarText`: dark beside a light page and light beside a dark one, so the
+popup matches the group that opened it. When the surface opens it takes the
+opposite of the anchor's color scheme (an explicit `color-scheme` on the anchor
+or an ancestor wins; `light dark` follows the user's preference), and the
+surface is marked `data-tone="dark"`. Nothing else changes. Every semantic
+color token is a `light-dark()` pair, so the surface fill, border, and shadow,
+and the text, borders, and focus rings of the Kerf UI and Web Awesome
+components inside it (a `ListItem` mute row, a `Slider`), resolve to the
+other side by inheritance. The content needs no tone props and no overrides.
+Text and focus rings keep WCAG AA in both page schemes. A theme that replaces a
+semantic token with a single color instead of a `light-dark()` pair opts that
+token out of the flip. While the surface is open it follows a live switch: an
+OS preference change, or a theme class, attribute, or inline `color-scheme`
+changed on the anchor or one of its ancestors, flips it to the new opposite
+(the content's own color transitions run, as the page's do). A scheme changed
+only by swapping a stylesheet is not observed. `openAnchoredSurfaceAt` reads the
+scheme from its `context` (the element under the pointer), so a region with its
+own `color-scheme` is honored; without a connected `context` it reads the modal
+scope's (or the page's).
+
+## Theming
+
+Override `--kui-anchored-surface-inset` and
+`--kui-anchored-surface-radius` for a theme; content can compose any Kerf UI
+components without the surface applying action policy. Prefer `PopupMenu` for
+a typed command list and `Select` for choosing a persistent value. See
+[component selection](component-selection.md).

package/docs/app-layouts.md

@@ -9,7 +9,7 @@ changes. The layouts:
 - [`NavStack`](nav-stack.md) — push/pop navigation (a single pane is a one-entry stack).
 - [`SplitView`](split-view.md) — list-detail (two panes, collapsing to a stack).
 - [`Workbench`](workbench.md) — the Xcode-like collapsible rails + drawer.
-- [`TabScaffold`](tab-scaffold.md) — the iOS bottom tab bar (each tab a stack).
+- [`TabNavigator`](tab-navigator.md) — the iOS bottom tab bar (each tab a stack).
 - [`CollapsiblePanel` + `wireSidebar`](collapsible-panel.md) — a standalone
   collapsible rail or bottom drawer (with `CollapsiblePanelToggle`), outside a full
   shell: the standard collapse animation, icon convention, and `wireSidebar`
@@ -19,15 +19,182 @@ Derive responsiveness from `deviceClass()`: `compact` (a handset or portrait
 tablet) means "one pane at a time"; `atLeast('tablet')` / `atLeast('desktop')`
 gate the roomier presentations.
 
+Full-height shells retain `height: 100%` so they remain embeddable. Give a
+top-level shell a definite height chain by importing `@kerfjs/ui/document.css`
+and applying `.kui-app-root` to the direct mount container; see the
+[document baseline](document-baseline.md). Do not replace an embeddable shell's
+height with `100dvh`; a full-viewport app instead adds `data-viewport="locked"`
+to its `.kui-app-root`, which locks the document (not the shell) to `100dvh`.
+
+## Safe areas
+
+On a device with unsafe areas (a notch, rounded corners, a home indicator) and a
+page that opts into them with `<meta name="viewport" content="…, viewport-fit=cover">`,
+the layouts handle the insets for you. There is nothing to configure:
+
+- **Surfaces paint edge to edge.** Pane and panel backgrounds, separators, and
+  dividers run through the unsafe area. A collapsible rail or drawer grows by
+  the inset it reaches, so its content keeps its configured width or height.
+- **Content is padded on the sides it touches.** Inline insets pad the sides a
+  region actually reaches. Block insets become padding _inside_ the scroll
+  container (with matching `scroll-padding`), so content scrolls under the
+  status bar or home indicator but its first and last items can always be
+  scrolled clear.
+- **Interior edges get nothing.** A `Workbench` center next to an expanded rail,
+  a `SplitView` detail beside its list, or a `NavStack` view under its docked
+  chrome is not inset on that edge. Collapse the rail and the center picks up
+  the edge. A `NavStack` with `chromePresentation="overlay"` is the exception
+  by design: its views reach under the translucent chrome, and the measured
+  chrome height (top safe area included) becomes their block-start inset, so
+  content scrolls beneath the bar yet rests clear of it (see
+  [Navigation stack › Overlay chrome](nav-stack.md#overlay-chrome)). Its
+  `bottomToolbarPresentation="overlay"` does the same at the bottom: the
+  measured toolbar height (bottom safe area included) becomes the views'
+  block-end inset, so the last item rests just above the toolbar. A
+  `TabNavigator` with `barPresentation="overlay"` does the same for its tab
+  bar: the measured bar height (bottom safe area included) becomes the
+  scenes' block-end inset.
+- **No double inset.** Whichever region applies an inset clears it for its
+  descendants. A layout region whose only child is a `Pane` or another layout
+  lets that child own the insets. That child fills the region — a `Workbench`
+  area or panel, a `NavStack` view, a `TabNavigator` scene — so a sole `Pane`'s
+  header stays pinned while its own content scrolls. A `Pane` header or footer whose only child is
+  a `Toolbar` hands the inline insets to the toolbar, so the toolbar's dividers
+  still reach the edge.
+
+A plain `Pane` follows the same rules. It assumes it may touch every screen edge
+unless its layout says otherwise. When your own markup puts panes side by side,
+say which sides each pane reaches with `safeAreaEdges`:
+
+```tsx
+<div class="app-columns">
+  <Pane label="Library" safeAreaEdges={['block-start', 'block-end', 'inline-start']}>…</Pane>
+  <Pane label="Reader" safeAreaEdges={['block-start', 'block-end', 'inline-end']}>…</Pane>
+</div>
+```
+
+An app bar or bottom bar that sits directly at a screen edge, outside any
+`Pane` header or footer, claims its edges the same way. A `Toolbar` only pads
+the inline edges an owner hands it until you list the sides it reaches:
+
+```tsx
+<List fill>
+  <Toolbar
+    label="App bar"
+    safeAreaEdges={['block-start', 'inline-start', 'inline-end']}
+    leading={<ToolbarText text="Atlas" />}
+  />
+  <Row gap="none" flex>…panes that list block-end and their outer side…</Row>
+</List>
+```
+
+Each claimed side pads by the edge context, or the full device inset when
+nothing routes that edge, while the bar's surface and divider still reach the
+screen edge. A claimed toolbar inside a `Pane` header or footer adds nothing
+extra, because the pane already owns those edges.
+
+Pass `safeAreaEdges={[]}` for a pane that never sits at a screen edge. In an
+arrangement you own, give each `Pane` (and each edge-claiming `Toolbar`)
+`safeAreaEdges` listing only the sides its region reaches. The toolbar
+configurations layouts accept (a Workbench `mainToolbar` / `mainBottomToolbar`,
+and a Workbench panel's or `CollapsiblePanel`'s `toolbar`) forward
+`safeAreaEdges` to their `Toolbar` the same way.
+A `CollapsiblePanel` clears the edge it covers for its direct flex siblings
+automatically; a panel wrapped in your own grid cell cannot see its siblings,
+so pass the neighboring panes' `safeAreaEdges` yourself.
+
+The device insets come from `--kui-safe-area-block-start`, `-block-end`,
+`-inline-start`, and `-inline-end`, which default to `env(safe-area-inset-*)`.
+Override them on `:root` to reserve room for app-owned chrome or to simulate a
+device in tests.
+
+### Edge-to-edge content inside a Pane
+
+The Pane's scrolling slot publishes its resolved horizontal padding as
+`--kui-pane-content-inset-inline-start` and
+`--kui-pane-content-inset-inline-end`. Both inherited values include the safe
+area on the corresponding side, plus the extra 8px when `deepInset` is true.
+An app component can use them to let a row background or divider reach the
+Pane edge while its text stays on the ordinary content axis:
+
+It also publishes its resolved block-start padding as
+`--kui-pane-content-inset-block-start`: the top safe area, `deepInset`, and
+the clearance of an overlay or clear header (or of NavStack chrome handed to
+a view's Pane). A first child can run up beneath that inset with a matching
+negative margin; `BackdropImage`'s `underChrome` does this for artwork behind
+clear chrome.
+
+```css
+.orders-table {
+  margin-inline-start: calc(-1 * var(--kui-pane-content-inset-inline-start));
+  margin-inline-end: calc(-1 * var(--kui-pane-content-inset-inline-end));
+}
+
+.orders-table th:first-child,
+.orders-table td:first-child {
+  padding-inline-start: calc(var(--kui-pane-content-inset-inline-start) + 17px);
+}
+
+.orders-table th:last-child,
+.orders-table td:last-child {
+  padding-inline-end: calc(var(--kui-pane-content-inset-inline-end) + 17px);
+}
+```
+
+Here 17px is the app's chosen text offset from the content slot: a default
+`ContentItem` uses 8px outer margin, 1px border, and 8px inner padding. Adjust
+that offset to match the neighboring content. Keep the table inside the Pane's
+single scrolling slot; the negative margins change only its inline reach. The
+[`Pane` UX catalog example](../ux-demo/demos/pane.tsx) shows both `deepInset`
+states with the same table component.
+
+### Scrolling beneath overlaying chrome
+
+`Pane.scrollClearance` (`"block-start"`, `"block-end"`, or `"both"`) lets the
+scrolling slot pass beneath chrome laid over the pane's edge, such as a
+`DialogSurface` floating footer over a filling Pane. The slot adds the
+inherited `--kui-scroll-clearance-block-*` context that the chrome publishes to
+its block padding and `scroll-padding`, alongside the safe-area and
+`deepInset` insets, so its first and last items still rest clear of the
+chrome. See `docs/layout.md` "Scroll clearance".
+
+### Compact chrome
+
+A `Pane` declares what its header and footer do when its container presents
+compactly, with `compactChrome: { header?, footer? }`:
+
+- `fixed` (default) keeps the chrome docked; it shrinks the content area.
+- `scroll` puts the chrome inline with the content: the pane scrolls as one
+  column, and a footer settles at the bottom of short content and scrolls
+  past long content. Chrome left `fixed` stays stuck to its edge.
+- `overlay` lays the chrome over the content's edge on the chrome material,
+  hidden until the app opens it with `compactChromeOpen` from a control the
+  person can reach (a toolbar button in the view).
+
+The Pane only declares the policy. Its container applies it in its compact
+presentation — a `NavStack` view (so a compact `SplitView` and
+`ListDetailDialog` too), a `TabNavigator` scene, a full-screen
+`DialogSurface` (so a compact `WorkbenchDialog`), or a `Workbench` at its
+compact width (448px or less) — and ignores it when roomy. Pass it through a
+view's or panel's `pane` configuration (`pane: { compactChrome: { footer:
+'scroll' } }`).
+
+Make open `overlay` chrome transient with `wirePaneChrome(root, { header,
+footer })` from `@kerfjs/ui/wire-pane-chrome`, passing the signals the Pane
+renders as `compactChromeOpen`: Escape, or a press that starts and ends outside
+the open chrome, sets its signal to false, and focus left inside the chrome
+returns to the control that opened it. The app's own toggle keeps working,
+because the dismissal is decided at the click.
+
 ## Decision matrix
 
-| Situation | Layout | Device threshold |
-| --- | --- | --- |
-| Simple app, a few flat sections | `NavStack` with one entry (single pane); add `TabScaffold` for 2–5 co-equal sections on handset | `TabScaffold` on `compact`; promote its tabs to a `Workbench` rail / sidebar `atLeast('desktop')` |
-| Drill-down browsing (list → item → sub-item) | `NavStack`; upgrade to `SplitView` once list + detail fit together | `SplitView` two-pane `atLeast('tablet')` landscape / non-`compact`; `NavStack` form on `compact` |
-| Two related panes, selecting on the left updates the right | `SplitView` | two panes when not `compact`; collapses to `NavStack` (list → detail) on `compact` |
-| Complex tool / editor with peripheral panels (navigator, inspector, console) | `Workbench` | full three-panel `atLeast('desktop')`; on smaller classes present the rails via `NavStack` / overlay drawers, not a shrunken shell |
-| Mobile app with 2–5 top-level destinations, each its own drill-down | `TabScaffold`, each tab a `NavStack` | bottom bar on `compact`; promote to a rail / sidebar `atLeast('desktop')` |
+| Situation                                                                    | Layout                                                                                           | Device threshold                                                                                                                   |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Simple app, a few flat sections                                              | `NavStack` with one entry (single pane); add `TabNavigator` for 2–5 co-equal sections on handset | `TabNavigator` on `compact`; promote its tabs to a `Workbench` rail / sidebar `atLeast('desktop')`                                 |
+| Drill-down browsing (list → item → sub-item)                                 | `NavStack`; upgrade to `SplitView` once list + detail fit together                               | `SplitView` two-pane `atLeast('tablet')` landscape / non-`compact`; `NavStack` form on `compact`                                   |
+| Two related panes, selecting on the left updates the right                   | `SplitView`                                                                                      | two panes when not `compact`; collapses to `NavStack` (list → detail) on `compact`                                                 |
+| Complex tool / editor with peripheral panels (navigator, inspector, console) | `Workbench`                                                                                      | full three-panel `atLeast('desktop')`; on smaller classes present the rails via `NavStack` / overlay drawers, not a shrunken shell |
+| Mobile app with 2–5 top-level destinations, each its own drill-down          | `TabNavigator`, each tab a `NavStack`                                                            | bottom bar on `compact`; promote to a rail / sidebar `atLeast('desktop')`                                                          |
 
 ### Worked examples
 
@@ -40,10 +207,33 @@ gate the roomier presentations.
   selection).
 - **IDE (complex tool):** `Workbench` with a left navigator rail, a right
   inspector rail, and a bottom console drawer, each `collapsed` bound to a
-  signal. Only offer this `atLeast('desktop')`.
-- **Social app (tabbed):** `TabScaffold` with Home / Search / Profile tabs, each
+  signal. Only offer this `atLeast('desktop')`. To let people size the
+  navigator or console, opt those panels in with `resizable` and call
+  `wireWorkbench` with their size signals and `deviceClass`; resizing is
+  suspended on `compact`, where the rails become overlay drawers — or give each
+  rail `responsiveOverlayAt: "narrow"` and let the Workbench's own width decide
+  when it overlays, with no device check; pass each rail's `collapsed` signal
+  to `wireWorkbench` so the overlay starts collapsed, takes focus and keeps Tab
+  inside it while open, and closes on Escape or an outside press. Inline
+  rails, fixed or resizable, leave the editor its `mainMinSize` (320px by
+  default) and shrink in proportion when the window narrows; the bottom drawer
+  leaves it `mainMinHeight` (120px by default) and shrinks when the window gets
+  shorter.
+- **Social app (tabbed):** `TabNavigator` with Home / Search / Profile tabs, each
   `content` a `NavStack`. On a tablet/desktop, render the same sections as a
   `Workbench` left rail instead of a bottom bar.
+- **Media detail page (album, artist, film):** a `NavStack` with
+  `chromePresentation="clear"` and `scrollEdge="material"`, a scoped `tint`
+  from the artwork's bottom color, and a view Pane that opens with an
+  `underChrome` `BackdropImage` (parallax, progressive blur, `fadeTo` the
+  tinted surface). Keep chrome controls in glass control groups. The
+  [Media Detail recipe](recipes.md#media-detail) composes all of it.
+
+Whatever the layout, call `wireScrollDividers(appRoot)` from
+`@kerfjs/ui/wire-scroll-dividers` once: every `Pane` a layout renders, every
+`NavStack`'s top chrome and bottom toolbar, and every `TabNavigator` bar then
+draw the line between the pinned chrome and the scrolling content only while
+content is scrolled beneath them, and toolbars need no divider of their own. See [Scroll dividers](layout.md#scroll-dividers).
 
 ## Dialogs
 

package/docs/apple-hig.md

@@ -7,10 +7,12 @@ Native Apple applications should use native platform controls and follow the Hum
 - Accessibility is behavior: every workflow is keyboard-operable; focus is visible; DOM and reading order agree; controls have accessible names; decorative icons are hidden.
 - Use adaptive semantic colors. Every custom role needs usable light, dark, and increased-contrast behavior. Never rely on color alone.
 - Use the system UI font stack and allow browser zoom through 200%. Avoid thin weights and hard minimums that clip enlarged text.
+- On iOS, prevent unwanted focus magnification by keeping editable text legible at touch widths. Do not force the page scale back on blur: that would also undo a person's deliberate pinch zoom.
 - Group with space and alignment before adding borders. Keep essential content in the leading reading path and secondary detail in progressive disclosure.
 - Use one icon family and one metaphor per action. Directional icons may mirror in RTL; checkmarks, logos, and real-world objects do not.
 - Motion is brief, causal, and optional. Honor reduced-motion and reduced-transparency preferences; repeating indicators stop moving under reduced motion.
 - Writing is concise, specific, and action-led. Labels describe the result, not implementation details.
+- Capitalize by element type, consistently: names of commands, controls, views, and fields use title style; descriptions, messages, tooltips, and option text use sentence style. See [Writing interface copy](./writing.md#capitalization).
 
 ## Interaction
 

package/docs/backdrop-image.md

@@ -0,0 +1,128 @@
+# BackdropImage
+
+`BackdropImage` opens a scrolling `Pane` or `NavStack` view with a large image,
+such as an artist, album, or place page. The image can lag the scroll
+(parallax), dissolve through a mask into an app-chosen color, and that color
+keeps painting under the content below, so the page reads as one surface.
+
+```tsx
+import { BackdropImage } from '@kerfjs/ui/backdrop-image';
+import { remify, uiColor } from '@kerfjs/ui/css-values';
+
+<Pane label="Artist">
+  <BackdropImage
+    src="/art/hero.jpg"
+    srcset="/art/hero-800.jpg 800w, /art/hero-1600.jpg 1600w"
+    sizes="100vw"
+    alt=""
+    height={remify(360)}
+    parallax="subtle"
+    fadeTo={uiColor('surface')}
+    scrim="bottom"
+    overlay={
+      <Toolbar
+        label="Artist"
+        leading={<ToolbarText text="Night Harbor" size="xl" headingLevel={1} />}
+      />
+    }
+  >
+    <ContentItem>Top songs</ContentItem>
+  </BackdropImage>
+</Pane>;
+```
+
+## Props
+
+- `src`, `alt` (required). Pass `alt=""` for a decorative image that only sets a
+  mood. `srcset` and `sizes` add responsive candidates to the fitted form.
+- `fit` (`cover` by default, `contain`, `fill`) and `position` (`center` by
+  default, or `top`, `bottom`, `left`, `right`, and the four corners) choose how
+  one image fills the block and which part stays in view.
+- `repeat` (`repeat`, `repeat-x`, `repeat-y`) tiles the image as a background at
+  its natural size instead. A tiled image with alt text is exposed as
+  `role="img"`; `srcset`, `sizes`, and `fit` do not apply.
+- `height` is a typed `CssLength` (default 320px). The block grows when the
+  overlay content is taller.
+- `parallax`: `none` (default) scrolls the image with the content, `subtle`
+  lags by 35%, and a number from 0 to 1 is the lag factor.
+- `fadeTo` is a typed `CssColor` (`uiColor()`, `colorVar()`, `fillColor()`).
+  The image's lower half dissolves into it, and the whole surface, including
+  `children` below the image, paints it. Omit it for a hard edge and no
+  surface color.
+- `blur` (`{ radius?, blurredSrc?, dim? }`) blurs the image progressively as it
+  scrolls away (see [Progressive blur](#progressive-blur)).
+- `scrim`: `bottom` darkens toward the block end where an overlay title sits,
+  `full` dims the image evenly. A scrim is dark in both color schemes, so the
+  overlay takes the dark scheme over it: default-tone titles and controls read
+  light in both schemes (do not use `ToolbarText tone="dark"` there; that tone
+  inverts with the scheme). Under reduced transparency or increased contrast,
+  where the overlay sits on a solid `fadeTo` band, it keeps the page's scheme.
+  The app keeps overlay text at AA with the image, scrim, and fade it chooses.
+- `overlay` is laid over the image's block end; `children` continue below it.
+- `underChrome` runs the image up beneath the Pane's block-start inset (an
+  overlay or clear header's clearance, NavStack chrome handed to a view's
+  Pane, and the top safe area), so artwork fills the screen behind clear
+  chrome. The visible image keeps `height` below the chrome, and `overlay`
+  content stays clear of it. It reads the Pane's
+  `--kui-pane-content-inset-block-start`, so the image must be the first child
+  of the Pane's content.
+
+## Layout and ownership
+
+Place it first in the scrolling content. The root bleeds to the Pane's resolved
+inline insets (the safe area, `deepInset`) and hands them back to its overlay
+and content, so a `ContentItem` or `Toolbar` inside keeps the ordinary text
+axis. It adds no padding of its own. Configure it through its props; never
+restyle its internals.
+
+## Parallax
+
+The image layer animates only `transform` on a scroll-driven
+`animation-timeline`: the image block is a named `view-timeline`, and the layer
+runs over its `exit-crossing` range, from the block's top meeting the
+scroller's start edge to its bottom passing it. That binds to the nearest
+scroll container, which is the Pane's content scroller (or the Pane root while
+a `chromePlacement="auto"` pane scrolls as one column), and the range is the
+block's own height of scroll wherever it sits. The layer moves by the lag
+factor times that distance, so the image moves slower than the content. There
+is no scroll listener and no `background-attachment: fixed`, and the compositor
+runs the animation.
+
+## Progressive blur
+
+`blur` stacks a blurred copy of the image over the sharp one and fades the
+copy in over the first half of the parallax's scroll range, so the image is
+fully softened while most of it is still in view, the way a media page's
+artwork blurs early in the scroll. The blur itself is set once: either a CSS `filter: blur()` of
+`radius` (default 24px) on a copy of `src`, which overhangs the block by its
+radius so the blur's transparent fringe falls outside the clip, or an
+app-supplied pre-blurred or low-resolution `blurredSrc` (no filter unless
+`radius` is also given). Only the copy's `opacity` animates, plus the optional
+`dim` layer (a black layer whose opacity ramps to `dim`, from 0 to 1), so no
+frame re-rasterizes the image. The copy is decorative (`alt=""`,
+`aria-hidden`).
+
+```tsx
+<BackdropImage
+  src="/art/hero.jpg"
+  alt=""
+  parallax="subtle"
+  blur={{ blurredSrc: '/art/hero-blur-64.jpg', dim: 0.2 }}
+  fadeTo={uiColor('surface')}
+/>
+```
+
+In a Chromium performance trace of 200 scroll frames across the image's exit
+range, the effect produced no `Paint` events and no per-frame raster (a
+control that repainted the root each frame produced 400 `Paint` events), and
+no animation failed to composite.
+
+## Fallbacks
+
+| Condition                                                          | Result                                                                                             |
+| ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| No `animation-timeline` support (Firefox at the time of writing)   | Static, sharp image (no parallax, blur, or dim); the fade and color still apply.                   |
+| `prefers-reduced-motion: reduce`                                   | Static, sharp image.                                                                               |
+| `:root[data-kui-effects="static"]`                                 | Static, sharp image.                                                                               |
+| `@media (update: slow)` (e-ink, print)                             | Static, sharp image.                                                                               |
+| `prefers-reduced-transparency: reduce` or `prefers-contrast: more` | No dissolve: a hard edge onto solid `fadeTo`, and `overlay` content sits on a solid `fadeTo` band. |