@happyvertical/smrt-ui 0.51.39 → 0.53.0

package/AGENTS.md

@@ -46,13 +46,14 @@ components are exempt — they *are* the primitives.
 | `.` | barrel re-exporting the primitives, registry, and theme system |
 | `./playground` | shared-host previews for the complete foundation catalog; rendered inside the active preset and color scheme |
 | `./ui` | `Button`, `Card`, `Badge`, `Avatar`, `Chip`, `Skeleton`, `Tooltip`, `Dropdown`/`Menu`, `Popover`, `Disclosure`, `Accordion`, `Tree`, `Pagination`, … |
-| `./feedback` | `Alert`, `ToastViewport`, `Modal`, `Drawer`/`Sheet`, `ConfirmDialog`, `LoadingOverlay`, `Progress`, `Meter`, `Spinner` |
+| `./feedback` | `Alert`, `ToastViewport`, `Modal`, `Drawer`/`Sheet`, `ConfirmDialog`, `LoadingOverlay`, `Progress`, `Meter`, `Spinner`, phone surfaces `PhoneSheet` / `WorkingStrip` and the `swipeDismiss` action |
 | `./data` | `CollectionToolbar`, `CollectionList`/`ContentList`, `DataTable` and their types — a **component barrel**: it re-exports `.svelte` files, so a plain Node `import()` of it throws `ERR_UNKNOWN_FILE_EXTENSION` |
 | `./data-surface` | **Svelte-free**: registry contracts and shared protocol limits (`DATA_SURFACE_MAX_REQUEST_BYTES`, `DATA_SURFACE_IDENTIFIER_MAX_LENGTH`, …). Server adapters must import these from here, not from `./data` — a server entry that reaches the barrel breaks the `smrt` CLI's plain-Node `.smrt/register.js` load (issue #2924) |
 | `./layout` | `Container`, `Grid`, `Header`, `Footer`, `PageHeader`, `EmptyState`, … |
-| `./calendar` | `Calendar`, `DayView` |
+| `./calendar` | `CalendarView` (time-zone-aware month grid + phone agenda) and its Svelte-free date model (`toEntries`, `layoutMonth`, `dateKeyInZone`, …); deprecated `Calendar`, `DayView` |
 | `./chat` | `MessageBubble`, `ReactionPicker`, `TypingIndicator` |
-| `./forms` | Provider-free fields, choice controls, sliders/ranges, combobox/listbox/multiselect/tags, date/time/file controls, plus the transport-neutral control interaction registry |
+| `./forms` | Provider-free fields, choice controls, sliders/ranges, combobox/listbox/multiselect/tags, date/time/file controls, `CameraCapture`/`SignaturePad` capture, plus the transport-neutral control interaction registry |
+| `./form-retry` | **Svelte-free** form retry (#3291): submission key, in-flight refusal, conditional reset, opt-in restore-after-reload, browser `runOnce()` digest. Also re-exported from `./forms`. Framework-free TS typed structurally against SvelteKit's `SubmitFunction` — never import `@sveltejs/kit` here. Guide: `docs/content/form-retry.md` |
 | `./i18n` | i18n **client**: `useI18n`, `<Trans>`, `defineMessages`, `renderTemplate` (no `smrt-languages` import — the server resolver stays in `smrt-svelte/i18n/server`) |
 | `./registry` | `ModuleUIRegistry` for cross-package component discovery |
 | `./theme` | deprecated compatibility path forwarding to the canonical theme system |
@@ -149,7 +150,28 @@ other text pairing clears WCAG AA in both schemes.
 
 ## Gotchas
 
+- **Calendar dates are `YYYY-MM-DD` keys in the view's `timeZone`.** Project
+  instants into the zone once (`dateKeyInZone`) and do all grid/span math on
+  keys; never `new Date(y, m, d)` / `getDay()` in the browser zone. Months are
+  1-12 in the public API (`CalendarMonth`), unlike `Date#getMonth`.
+- **Capture controls post natively.** `CameraCapture` and `SignaturePad` fill
+  a hidden named file input via `DataTransfer`, falling back to a `formdata`
+  listener (`native-file-field.ts`). Keep camera lifecycle in the
+  framework-free `camera-capture-session.ts` and the pointer gate in
+  `signature-pad-logic.ts`; their effects must not read rendered state. The
+  `<input capture>` path stays opt-in (`fileInputFallback`), off by default.
+  A form `reset` empties a native file input, so both clear their capture on
+  their form's reset (`attachFormResetListener`), even while `disabled`;
+  otherwise the UI shows a file the next submit no longer posts.
+
 - **i18n split**: the client (here) is dependency-free; the Node-only server
   resolver (`buildI18nSnapshot`, → `@happyvertical/smrt-languages`) stays in
   `@happyvertical/smrt-svelte/i18n/server`. Package string catalogs register via
   `defineMessages` imported from `@happyvertical/smrt-ui/i18n`.
+
+- **Consumers type-checking a local checkout** hit "two different types with
+  this name" on `Snippet` when two Svelte copies meet (svelte2tsx's
+  `/// <reference types="svelte" />` in compiled sources ignores `paths`). Keep
+  every Svelte export's `types` condition first and pointing at built
+  `*.svelte.d.ts`; the consumer recipe is
+  [docs/development/svelte-consumer-linking.md](../../docs/development/svelte-consumer-linking.md).

package/README.md

@@ -29,22 +29,214 @@ pnpm add @happyvertical/smrt-ui
 
 | Area | Components |
 | --- | --- |
-| Fields | `Form`, `Field`/`FormGroup`, `Fieldset`, `InputGroup`, `ErrorSummary` |
-| Text and structured input | `Input`, `Textarea`, `Select`, `Combobox`, `Listbox`, `MultiSelect`, `TagsInput` |
+| Fields | `Form`, `Field`/`FormGroup`, `Fieldset`, `InputGroup`, `ErrorSummary`, `FormActionBar` |
+| Text and structured input | `Input`, `Textarea`, `Select`, `Combobox`, `Listbox`, `MultiSelect`, `TagsInput`, `SearchInput` |
 | Choices | `Checkbox`, `RadioGroup`/`Radio`, `Switch`, `Toggle`, `ToggleButton`, `SegmentedControl` |
 | Values and files | `Slider`, `RangeSlider`, `DatePicker`, `TimePicker`, `FilePicker` |
+| Capture | `CameraCapture`, `SignaturePad` |
 | Actions and display | `Button`, `Dropdown`/`Menu`, `Badge`, `Chip`, `Avatar`, `Card`, `Skeleton`, `Tooltip`, `Tree` |
-| Disclosure and overlays | `Popover`, `Disclosure`, `Accordion`/`AccordionItem`, `Modal`, `Drawer`/`Sheet`, `ConfirmDialog` |
-| Feedback | `Alert`, `ToastViewport`, `Progress`, `Meter`, `Spinner`, `LoadingOverlay` |
+| Disclosure and overlays | `Popover`, `Disclosure`, `Accordion`/`AccordionItem`, `Modal`, `Drawer`/`Sheet`, `PhoneSheet`, `ConfirmDialog` |
+| Feedback | `Alert`, `ToastViewport`, `Progress`, `Meter`, `Spinner`, `LoadingOverlay`, `WorkingStrip` |
 | Collections | `CollectionToolbar`, `CollectionList`/`ContentList`, `DataTable`, `Pagination` |
 | Layout and navigation | `Container`, `Grid`, `Header`, `Footer`, `PageHeader`, `EmptyState`, `Tabs`, `FilterChips` |
-
-Use the focused subpaths (`/forms`, `/ui`, `/feedback`, `/data`,
+| Calendar | `CalendarView` (deprecated: `Calendar`, `DayView`) |
+
+### Phone surfaces
+
+- `PhoneSheet` (`/feedback`) is the phone replacement for drawers and centered
+  modals: `variant="page"` covers the area, `variant="sheet"` rises from the
+  bottom and closes on a swipe down its header. It is non-modal, closes on its
+  button and Escape, returns focus to the opener, and can stay mounted while
+  closed (hidden and inert) so its content keeps state. It is
+  `position: absolute; inset: 0` — render it in AdminShell's `overlays`.
+- `WorkingStrip` (`/feedback`) shows a transport-neutral `WorkingStatus`
+  (`idle` · `working` · `paused` · `waiting` · `done` · `failed` ·
+  `cancelled`, a `label` for the current step and an optional `goal`) as a
+  strip above a phone bottom bar, a floating pill (`variant="floating"`, the
+  host positions it), or a line at the top of a pane. Optional controls:
+  reopen (`onopen`), Pause/Continue (`onpause`/`onresume`; Escape pauses),
+  Review while waiting (`onreview`), Stop, and Close once finished
+  (`ondismiss`); all 44px. Done uses the success colors, failed the error
+  colors, always with an icon and text. Step changes are announced politely
+  (throttled by `announceIntervalMs`), `waiting` and `failed` assertively; it
+  never takes focus.
+- `FormActionBar` (`/forms`) groups a form's actions (primary last). On phones
+  it is fixed to the bottom, carries `data-form-action-bar` so AdminShell hides
+  its phone bottom bar, and hides while `:root[data-keyboard-open]`.
+- `swipeDismiss` / `swipeDismisses` (`/feedback`) are the touch action and pure
+  decision behind swipe-to-close.
+- `Dictation` / `DictationButton` / `DictationStatus` (`/forms`) let people
+  speak into a text field (tap the microphone, or press and hold the field
+  with `longPress`). The speech `source` is normally smrt-svelte's
+  `createSttDictationSource()` (the browser's own speech recognition). Give
+  it a `transcribe` function too (`createHttpTranscriber('/your/route')`)
+  and, where the browser has no speech recognition (Firefox) or no speech
+  service behind it (Brave: `network` / `service-not-allowed`), it records
+  the message with `MediaRecorder` instead (WebM/Opus, MP4 on Safari; at most
+  `maxDurationMs` 2 minutes and `maxBytes` 10 MB), shows "Writing it down…"
+  while the route turns it into text, and puts the text at the cursor.
+  Keep the speech service's key on the server: the route takes the raw audio
+  body (`Content-Type` is the recording's type, `?language=&durationMs=`)
+  and answers `{ text }`; 413, 503 and 401/403 become "too long", "not set
+  up" and "not allowed" messages.
+
+### Link tabs
+
+`Tabs` with an `href` on every tab renders a page's sections as navigation —
+a `<nav>` of links, `aria-current="page"` on the active one, each tab its own
+URL — instead of an ARIA tablist. `maxVisible` moves extra tabs into a "More"
+menu while the active tab always stays in the row (`splitTabs` is the pure
+rule), `badge` marks a tab needing attention (and dots "More" when a hidden
+tab has one), and the row scrolls sideways on phones with the active tab
+kept in view. It carries `data-shell-tabs`, so AdminShell keeps it sticky
+under the phone top bar. Pair it with `useLinkSurface` (smrt-svelte) so
+agents can switch tabs too.
+
+Use the focused subpaths (`/forms`, `/form-retry`, `/ui`, `/feedback`, `/data`,
 `/data-surface`, `/layout`, `/themes`) to keep imports explicit. The
 Svelte-free `/data-surface` entry exposes the registry contracts and shared
-protocol limits for server adapters. The package root remains a compatibility
+protocol limits for server adapters; the Svelte-free `/form-retry` entry
+exposes the form-retry helper. The package root remains a compatibility
 barrel.
 
+### Calendar dates and shop time
+
+`DateDisplay` accepts `timeZone` (an IANA id such as `America/Edmonton`) for
+instant inputs (`Date`, numeric timestamps, and timestamp strings). Omit it to
+keep browser-local absolute formatting and the existing duration-based relative
+format. With an explicit zone, relative today/yesterday/tomorrow boundaries use
+calendar days in that zone, including daylight saving transitions.
+
+A bare `YYYY-MM-DD` string always denotes that calendar date, independent of the
+viewer or shop zone. It formats in UTC, retains a date-only `datetime` attribute,
+and ignores `showTime` because it contains no time. Relative calendar-date
+labels compare it with today's date in the supplied zone (or the browser zone).
+Impossible calendar dates render `fallback`. Invalid explicit zones used for
+instant or relative formatting also render `fallback` rather than throwing.
+
+### Combobox form submission
+
+A named `Combobox` submits its selected option value through a hidden native
+input. Its visible search text and option label are display-only. With
+`allowCustom`, typed text becomes the submitted value; otherwise searching keeps
+the last committed selection. A named empty selection submits an empty string;
+controls with no name or an empty name are omitted. Disabled controls, including
+those inside disabled fieldsets, are omitted by native `FormData`. Native form
+reset restores the initial selection and its label, unless reset is canceled.
+
+### MultiSelect form submission
+
+A named `MultiSelect` submits one hidden native input per selected option value,
+using repeated field names in selection order. Read them with `FormData.getAll`.
+Option labels are display-only, and numeric option values submit as strings.
+Empty selections, missing or empty names, and disabled controls (including
+ancestor fieldsets) contribute no entries. Native reset restores the initial
+selection unless reset is canceled.
+
+### Listbox form submission
+
+A named `Listbox` submits one hidden native input containing its selected option
+value, with numeric values encoded as strings. A named listbox without a
+selection submits an empty string. Missing or empty names and disabled controls
+(including ancestor fieldsets) are omitted. Native reset restores the initial
+selection unless reset is canceled.
+
+### Status badge tones
+
+`StatusBadge` accepts `tone="success"`, `"warning"`, `"danger"`, `"info"`, or
+`"neutral"` for custom status vocabulary such as `awaiting_cert`. An explicit
+tone overrides the built-in domain scheme while label, size, and outline variant
+continue to work independently. Tones use the active theme's paired container
+and text tokens. Without a tone, known domain statuses retain their existing
+colors and unknown statuses retain the neutral fallback. `StatusTone` is exported
+as a TypeScript type from the package root.
+
+### Touch targets for Checkbox, Radio and Switch
+
+`Checkbox`, `Radio` and `Switch` have an invisible 44x44px hit area around the
+visible control (about 18px for a box or mark, the 2.75rem track for a switch).
+A transparent `::before` on the wrapping `<label>` makes it, so a click anywhere
+in the area toggles the input, no layout shifts, and the focus ring stays on the
+visible box. The box and the label text sit above every hit area, so adjacent
+controls never steal each other's clicks.
+
+The hit area paints above plain (unpositioned) content around it, so it is
+constrained to where that cannot cost a neighbour a click:
+
+- **Beside other content.** A `Checkbox` or `Radio` that is not the only element
+  in its parent (a row title or link next to it, a group's other options) keeps
+  its hit area in the box's own column: it grows vertically only, never over the
+  text or link beside it. Only a control standing alone gets the full 44x44.
+- **Table cells.** Inside a `td`/`th` the area never leaves the cell. A
+  `Checkbox` that is the cell's only content uses the whole cell (clipped to its
+  edges). The cell gets `position: relative` at zero specificity (`:where()`), so
+  a sticky header or a pinned column keeps its own positioning.
+- **Stacked controls.** Hit areas of tightly stacked controls overlap in the
+  gaps; the later control wins a gap, never a neighbour's box or text. Content
+  directly above or below a box, closer than 13px, is covered by its hit area:
+  give it room, or shrink the area with `--smrt-control-hit-size`.
+- **Resize or turn off.** `--smrt-control-hit-size` (default `2.75rem`); `0px`
+  gives only the visible control. Pages never add their own padding hacks.
+- `DataTable`'s built-in selection checkboxes and `CollectionList`'s select box
+  are still native inputs and do not use this yet.
+
+## Calendar
+
+`CalendarView` (`@happyvertical/smrt-ui/calendar`) is a generic month grid
+with a phone agenda:
+
+```svelte
+<script lang="ts">
+  import { CalendarView } from '@happyvertical/smrt-ui/calendar';
+  import { goto } from '$app/navigation';
+  let { data } = $props(); // { year, month, items }
+</script>
+
+<CalendarView
+  items={data.items}
+  year={data.year}
+  month={data.month}
+  timeZone="America/Edmonton"
+  onNavigate={({ year, month }) => goto(`?y=${year}&m=${month}`, { keepFocus: true })}
+/>
+```
+
+- **Items** are generic `CalendarItem`s: `{ id, title, start, end?, allDay?,
+  tone?, color?, label?, group?, href? }`. `start`/`end` take a `Date`, an ISO
+  date-time, or a `YYYY-MM-DD` date (all-day). Timed `end` is exclusive; an
+  all-day `YYYY-MM-DD` end is the inclusive last day, and an all-day end
+  instant at local midnight is exclusive. `tone` maps to the theme's color
+  roles; without it, `group` picks a stable tone. Items with `href` render as
+  links, others as buttons; both call `onItemSelect`.
+- **Time zone and locale**: every day is computed in `timeZone` (IANA;
+  defaults to the browser's — pass it explicitly so server and client
+  agree). Month, weekday, date, and time text come from `Intl` in `locale`
+  (defaults to the i18n locale); `weekStartsOn` defaults to the locale's.
+- **Modes**: `month` is a `role="grid"` month with roving focus (arrows,
+  Home/End, PageUp/PageDown cross months). All-day and multi-day items are
+  bands across the days they cover; a day with more than `maxPerDay` rows
+  shows "+N more", which opens the day in a panel under the grid, or follows
+  `dayHref` when given. `agenda` is a horizontally scrolling strip of the
+  month's days (44px targets, arrow keys) above a day-by-day list. `auto`
+  (default) uses the agenda below 48rem, matching AdminShell's phone
+  breakpoint. No modals.
+- **URL state**: `year` + `month` (1-12) and `selectedDate` (`YYYY-MM-DD`) are
+  controlled when passed; changes are reported via `onNavigate` and
+  `onSelectDate`, so a page can keep them in its URL.
+- The Svelte-free date model (`toEntries`, `layoutMonth`, `dateKeyInZone`,
+  `monthWeeks`, `shiftMonth`, …) is exported from the same subpath for
+  server-side range queries and tests.
+
+**Migrating from `Calendar` / `DayView` (deprecated).** They compute days in
+the browser zone, print English-only names, and hard-code game/meeting/event
+emoji and routes. Map each `DayEventDetail` to a `CalendarItem` (`name` →
+`title`, `type` → `group`/`label`, your own route → `href`), replace
+`Calendar`'s `year`/`month` (0-indexed) with `CalendarView`'s `year`/`month`
+(1-12) and `onMonthNavigate` with `onNavigate`, `baseUrl` with a `dayHref`
+function that builds your day route from the `YYYY-MM-DD` key, and a `DayView`
+page with `CalendarView` in agenda mode (`selectedDate` set to the day) or the
+month grid's day panel. They will be removed in a future minor release.
+
 ### Currency display
 
 `CurrencyDisplay` accepts ISO 4217 codes as a public `string` prop so persisted
@@ -91,6 +283,34 @@ Application-specific editors, maps, charts, media workbenches, and domain
 records remain composites built from this foundation rather than generic base
 components.
 
+## Native and enhanced forms
+
+`Form` forwards native form attributes and Svelte attachments through its rest
+props to the underlying `<form>`. For a SvelteKit action, adapt `enhance` with
+`fromAction` and set `preventDefault={false}` so the enhancement handles submission:
+
+```svelte
+<script lang="ts">
+  import { enhance } from '$app/forms';
+  import { fromAction } from 'svelte/attachments';
+  import { Form, Input } from '@happyvertical/smrt-ui/forms';
+</script>
+
+<Form method="POST" action="?/save" preventDefault={false} {@attach fromAction(enhance)}>
+  <Input name="displayName" />
+  <button type="submit">Save</button>
+</Form>
+```
+
+For a customized enhancement, pass its callback as a getter:
+`{@attach fromAction(enhance, () => submitFunction)}`. The attachment runs on the
+native element and cleans up when it unmounts; the interaction registry and
+staged-review surface remain available. A component reference obtained with
+`bind:this` exposes `getFormElement(): HTMLFormElement | null`, which returns
+`null` before mount and after unmount. For ordinary browser GET/POST forms, use
+`preventDefault={false}` without an attachment. The default remains `true` for
+existing handler-driven forms.
+
 ## Agent-addressable forms
 
 `Form` can expose its controls to a chat, voice, tutorial, or test adapter
@@ -128,7 +348,8 @@ without coupling controls to a transport:
 
 Controls publish serializable metadata, constraints, options, sensitivity, and
 capabilities. Adapters can focus, reveal, highlight, explain, validate, and
-stage reviewable proposals. Agents cannot apply, discard, clear, or undo;
+stage reviewable proposals. An agent never moves keyboard focus: its `focus`
+reveals and highlights the control instead. Agents cannot apply, discard, clear, or undo;
 those value-changing actions require a trusted local gesture handled by the
 framework review surface. Secret/read-only controls reject agent mutations.
 Staging remains separate so proposals never change user state before review.
@@ -178,6 +399,175 @@ not await a same-control mutation through a captured registry reference: that
 call is indistinguishable from an independent caller in browser runtimes and,
 like any hook that never settles, can hold the ordered queue indefinitely.
 
+### Composite controls and form proposals
+
+A composite field — a place picker, a slug field with its own preview, a
+record picker — registers as ONE control with `useControlRegistration` (call
+it during component init inside any `Form`, rich `Form`, or `FormScope`). Give
+it a stable `controlId`, a plain `label`, and, when its value is not a plain
+string/number/boolean, a `valueSchema` so adapters can describe it:
+
+```svelte
+<script lang="ts">
+  import { useControlRegistration } from '@happyvertical/smrt-ui/forms';
+
+  let { value = $bindable(null) } = $props();
+
+  useControlRegistration(() => ({
+    controlId: 'place',
+    metadata: {
+      kind: 'custom',
+      label: 'Town location',
+      valueSchema: {
+        type: 'object',
+        properties: { name: { type: 'string' }, latitude: { type: 'number' }, longitude: { type: 'number' } },
+      },
+    },
+    getValue: () => value,
+    setValue: (next) => { value = next; },
+  }));
+</script>
+```
+
+Call `recordControlUserEdit(context, controlId, subject)` from the
+composite's own user-event handlers so a staged proposal goes stale when the
+person edits over it (native inputs bubble their events to the Form instead).
+`focusControl`, `revealControl`, `highlightControl`, and `emitControlChange`
+are the same DOM helpers the built-in primitives use for their `focus`,
+`reveal`, and `highlight` handles.
+
+`controlProposalInputSchema(registry, formId)` and
+`stageControlProposals(registry, formId, values)` are the transport-neutral
+halves of a "propose values for this form" tool: the schema has one optional
+property per proposable control (never secret/sensitive, unwritable,
+disabled, read-only, file, or password controls), and staging only ever
+creates reviewable proposals. smrt-svelte's `<Form webmcp>` and `FormScope`
+build their `*_stage_changes` tool from these.
+
+## Form retry
+
+`createFormRetry()` is the browser half of `runOnce()` (`@happyvertical/smrt-core`)
+for a SvelteKit enhanced form: a per-tab, per-form submission key, a refused
+second submit while one is in flight, typed values kept across a validation or
+transport failure, a reset after success only when the fields are unchanged
+since submit, and opt-in restore after a reload (a file that cannot be restored
+is reported, never silently dropped). It is framework-free and imports neither
+Svelte nor SvelteKit; the submit function is typed against SvelteKit's
+`SubmitFunction` shape structurally.
+
+```svelte
+<script lang="ts">
+  import { enhance } from '$app/forms';
+  import { createFormRetry } from '@happyvertical/smrt-ui/form-retry';
+
+  const retry = createFormRetry({ form: 'report' });
+</script>
+
+<form method="POST" use:enhance={retry.enhance()} {@attach retry.attach}>
+  <input name="title" />
+  <button type="submit">Send</button>
+  {#if $retry.status === 'transport-error'}<p role="alert">Send it again unchanged.</p>{/if}
+</form>
+```
+
+With smrt-ui's own `Form`, attach the same two pieces to it (see
+[Native and enhanced forms](#native-and-enhanced-forms)):
+`<Form method="POST" preventDefault={false} {@attach fromAction(enhance, () => retry.enhance())} {@attach retry.attach}>`.
+
+`/forms` re-exports the same API as the Svelte-free `/form-retry` entry. See the
+[form retry guide](../../docs/content/form-retry.md) for the server half, the
+per-result table, storage and private-window behaviour, and restore.
+
+## Camera and signature capture
+
+`CameraCapture` takes a photo from the device camera and `SignaturePad` takes a
+signature, each inside an ordinary form. Both live in `/forms`, need only
+browser APIs, and post their file through a plain multipart form when given a
+`name`; the page wires no hidden input and no submit handler.
+
+```svelte
+<script lang="ts">
+  import { CameraCapture, SignaturePad } from '@happyvertical/smrt-ui/forms';
+</script>
+
+<form method="POST" enctype="multipart/form-data">
+  <CameraCapture name="photo" facingMode="environment" />
+  <SignaturePad name="signature" stylusOnly={settings.signatureStylusOnly} />
+  <button type="submit">Send</button>
+</form>
+```
+
+**CameraCapture** uses `getUserMedia` with a live preview. The user takes a
+photo, reviews it, and can retake it before "Use photo" commits it. Committing
+calls `onCapture({ blob, dataUrl })` and fills the named field (`photo.jpg` by
+default; set `fileName`, `imageType`, and `quality` to change it). "Retake"
+after a commit empties the field and calls `onClear`. The root's `data-state`
+is one of `starting`, `streaming`, `reviewing`, `committed`, `off` (disabled),
+`permission-denied`, `no-camera`, `unsupported`, `error`, or `fallback`. Each
+problem state has its own copy and, where it can help, a "Try again" action.
+`getUserMedia` exists only in a secure context, so a page served over plain
+HTTP renders `unsupported`.
+
+The stream's tracks are stopped on unmount, when `disabled` turns on, when
+`facingMode` changes (the camera is then requested again), and as soon as a
+frame is captured. A permission prompt answered after unmount or disable is
+discarded and its stream released. The lifecycle lives in the framework-free
+`createCameraSession()` (exported with `classifyGetUserMediaError()` and
+`isCameraApiSupported()`), so it can be tested against a fake `MediaDevices`.
+
+`fileInputFallback` is opt-in and off by default. With it on, browsers without
+`getUserMedia` render an `<input type="file" accept="image/*" capture>` that
+carries `name` itself (`disabled` blocks it with `aria-disabled` rather than
+the native attribute, so a committed photo keeps posting). It opens the
+operating system's picker, which has no
+live preview and can offer the gallery, so it is not a substitute for the
+camera flow. With it off, those browsers render the `unsupported` state.
+
+**SignaturePad** draws on its own canvas. "Use signature" stays disabled until
+an accepted stroke exists, then returns a PNG through `onCapture({ blob,
+dataUrl })` and fills the named field (`signature.png` by default). A committed
+pad is locked until "Clear", which empties the field and calls `onClear`.
+`stylusOnly` is a prop the caller resolves; with it on, only `pointerType ===
+'pen'` draws. `isAcceptedPointerType()` and `mapPointerToCanvasPoint()` are
+exported as pure functions. The pad is dark ink on white paper in every theme
+and colour scheme, and the exported PNG is opaque white, so it reads the same
+wherever it is shown.
+
+**Native form posting.** The named field is a hidden `<input type="file">`
+filled through `DataTransfer` (Chrome 60+, Firefox 62+, Safari 14.1+). Where
+`DataTransfer` cannot be constructed or assigned, the field drops its `name`
+and a capture-phase `formdata` listener appends the file while the browser
+builds the request, which covers native navigation submits as well as
+`new FormData(form)`. Where neither API exists, nothing is posted and
+`onCapture` is the only channel. The root's `data-smrt-file-field` attribute
+reports `data-transfer`, `formdata-event`, `file-input`, or `none`. Before a
+commit the field posts what an empty native file input posts. `disabled`
+freezes the controls but keeps a committed file in the submission; unmount the
+component to drop it, or put it in a disabled `<fieldset>`, which leaves the
+field out of the submission (committed or empty) in every posting strategy.
+
+A reset of the owning form (`form.reset()`, a reset button, or SvelteKit
+`enhance`'s `update()` after a success, including `createFormRetry()`'s
+conditional reset) empties the field as it empties a native file input, in
+every posting strategy. A committed photo or signature is discarded as
+"Retake" or "Clear" would and `onClear` is called. A photo under review or
+ink not yet committed is discarded too, without `onClear`, so the next entry
+cannot attach the previous one's capture. `CameraCapture` returns to the live
+camera (`off` while `disabled`, the emptied picker with `fileInputFallback`)
+and supersedes a frame still encoding; with nothing held, a reset changes
+nothing and never re-prompts for the camera. `SignaturePad` returns to blank,
+unlocked paper. A reset clears both even while `disabled`, as it clears a
+disabled native input, and a reset a later listener cancels still leaves the
+component and the posted field both empty.
+
+Text comes from the `ui.camera_capture.*` and `ui.signature_pad.*` i18n keys
+and can be overridden per instance with `labels`. Capture is a touch flow, so
+its actions (and the fallback picker) are touch targets at every density: at
+least `--smrt-touch-target-min` (48px by default; see
+[Touch density](#touch-density)), which ThemeProvider `overrides` can raise.
+Both register with an enclosing `Form`'s interaction registry as non-readable,
+non-writable `file` controls.
+
 ## DataTable controller
 
 `DataTable` can share one headless `DataTableController` between rendered
@@ -437,6 +827,34 @@ registry.register({
 });
 ```
 
+### Navigation and step surfaces
+
+Two ready-made surfaces cover interactions a view intent cannot reach on its
+own (an intent only dispatches a registry command):
+
+- `registerLinkSurface({ registry, surfaceId, label, description, links,
+  navigate })` mounts a menu, tab row, or section list. `state.links`
+  publishes each link's id, label, description, and group — never its href —
+  and the default `open` control resolves `{ target }` (an id, a label, or a
+  unique label prefix) to one of those links and calls `navigate(href)`.
+  Nothing an agent sends can become a URL.
+  Return the navigation's promise from `navigate`: the command answers at
+  once, and `whenSurfaceNavigationSettled(registry)` resolves once it
+  finished and the new page's surfaces registered (a bespoke surface that
+  navigates calls `trackSurfaceNavigation(registry, promise)`).
+- `registerStepSurface({ registry, surfaceId, label, description, steps,
+  current, next, back, goTo, nextWrites, showNext })` mounts a wizard.
+  `state` carries the steps with their status, the current step, and
+  `nextWrites`. `next`/`back`/`go-to` run the page's own handlers (return
+  `false` to refuse, e.g. when validation fails). When the current step's
+  forward button saves or creates something (`nextWrites`), `next` never
+  presses it: it calls `showNext` to reveal and highlight the button and
+  publishes `awaitingPerson: true` until the flow moves on.
+
+smrt-svelte's `useLinkSurface` / `useStepSurface` / `useListSurface`
+(`@happyvertical/smrt-svelte/web`) bind these to a component's lifetime on
+the Provider's registry.
+
 `inspect()` and command results are deterministic `{ version, descriptor,
 revision, state, selection }` envelopes; neither includes a timestamp, rows,
 functions, authority fields, tenant/principal data, SQL, or a transport handle.
@@ -529,6 +947,46 @@ hand-authored, and every text pairing clears WCAG AA.
 Run the shared playground to inspect the full catalog under every preset and
 light/dark scheme.
 
+### Card look tokens
+
+`Card` and `CollectionList` rows read these custom properties, so an app can
+change the card look once in its own theme layer instead of per page. Unset,
+they keep the stock look.
+
+| Property | Default | Used for |
+| --- | --- | --- |
+| `--smrt-card-border` | `1px solid var(--smrt-color-outline-variant)` | edge of `default` and `elevated` cards, CollectionList rows |
+| `--smrt-card-background` | `var(--smrt-color-surface)` | card and row fill |
+| `--smrt-card-shadow` | `none` | shadow of `default` cards (`elevated` keeps its elevation) |
+| `--smrt-card-divider` | `1px solid var(--smrt-color-outline-variant)` | rule under a card header / above its footer |
+
+The `outlined` variant always draws its outline. For borderless cards on a
+`surface` page, pair `--smrt-card-border: none` with a tinted background such
+as `var(--smrt-color-surface-variant)` so cards stay distinct in both schemes:
+
+```css
+:root {
+  --smrt-card-border: none;
+  --smrt-card-background: var(--smrt-color-surface-variant);
+}
+```
+
+### Component override hooks
+
+Hooks an app sets once in its own theme layer instead of restyling a component's
+classes. Unset, each keeps its stock look.
+
+| Property | Component | Used for |
+| --- | --- | --- |
+| `--smrt-popover-panel-width` | `Popover` | the panel's width (never wider than the viewport minus 2rem) |
+| `--smrt-popover-panel-padding` | `Popover` | the panel's padding |
+| `--smrt-admin-shell-background` | `AdminShell` (smrt-svelte) | the page background behind the cards |
+| `--smrt-admin-shell-scrollbar-track` / `-thumb` / `-thumb-hover` | `AdminShell` (smrt-svelte) | the themed thin scrollbars inside the shell |
+| `--smrt-shell-title-font-family` | `ShellTitle` (smrt-svelte) | the workspace name's font family |
+
+`IconToggle` takes a `tone` prop (a CSS colour such as `var(--status-draft)`) for
+a toggle that is neutral until pressed and then wears its colour.
+
 ## Development
 
 ```bash
@@ -537,3 +995,95 @@ pnpm test
 pnpm build
 pnpm verify:pack
 ```
+
+### Touch density
+
+Set `<ThemeProvider density="touch">` for floor tablets and phones, or set
+`density="touch"` on Input, Select, Textarea, Checkbox, Switch, RadioGroup,
+Button (including links), FilterChips, SegmentedControl, or DataTable. DataTable
+applies density to its sort buttons. Density is independent of existing `size`
+props, including native Input/Select sizes. Omitted density inherits; explicitly
+setting `density="comfortable"` opts that control out and keeps its usual size.
+RadioGroup expands each option's clickable label, and Checkbox/Switch expand
+the label hit area while preserving the visual mark.
+
+`--smrt-touch-target-min` defaults to `48px` across all presets and works without
+a provider. Customize it globally with ThemeProvider's `overrides`, for example
+`overrides={{ '--smrt-touch-target-min': '56px' }}`. Touch targets grow with larger
+content; normal density keeps existing component sizing. `CameraCapture` and
+`SignaturePad` actions use `--smrt-touch-target-min` at every density, since
+capture is a touch flow. TenantNav sizing is
+tracked separately in [#3246](https://github.com/happyvertical/smrt/issues/3246).
+
+### Narrow DataTable
+
+Set `responsiveMode="hide-columns"` to adapt to the table's container width.
+The default `responsiveBreakpoint={800}` includes both 768px tablets and 390px
+phones. Narrow mode budgets one column per `responsiveColumnMinWidth={160}`
+pixels, after reserving space for selection and expansion controls. Higher
+`column.responsive.priority` values survive first (missing/nonfinite values are
+zero); ties preserve declared display order. `responsive.keepVisible` columns
+always survive responsive collapse, while explicitly hidden columns stay hidden.
+
+Retained cells wrap, and their desktop width and pinning settings resume when
+the container widens. Responsive presentation never changes controller state,
+sorting, selection, or persisted column visibility. Header groups and structural
+row colspans follow the retained columns. If keepVisible columns exceed the
+budget, all remain visible and share the available width. Custom cell/header
+snippets should fit their cells. Default `responsiveMode="scroll"` preserves
+existing horizontal scrolling.
+
+ConfirmDialog opens a native modal dialog above existing Modal and Drawer surfaces.
+Its `message` accepts plain text or a Svelte snippet (including lists and emphasis);
+each instance owns its accessible title and description ids. Escape and backdrop
+clicks request `oncancel`; the parent controls `open`. The opener regains focus
+on close. Buttons remain disabled while `loading`, and Escape stays available.
+The native top layer replaces the previous fixed div; confirmation now stacks
+above an already open modal and makes its background inert. Escape is scoped to
+the active dialog rather than handled globally. Existing `open`, `loading` and
+action callbacks retain their controlled-state contracts.
+
+Browser feedback contracts run with `pnpm --filter @happyvertical/smrt-ui test:e2e`
+(after installing Playwright Chromium, or setting
+`PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH` to a local Chromium executable).
+
+ToastViewport follows the topmost native modal dialog and restores its original
+host when all modals close. Its live region, dismiss buttons and actions stay
+interactive inside Modal, Drawer and ConfirmDialog. Hover and focus independently
+pause auto-dismiss, then resume the remaining duration. Configure
+`createToaster({ successDuration: 0 })` to keep success records until dismissal;
+per-toast `duration: 0` remains supported. `inset` accepts a CSS length, `anchor`
+accepts a content-region element, and `top-center`/`bottom-center` positions center
+the viewport within that region (or the window). Anchor geometry follows resize
+and scroll. Custom injected Toaster implementations may optionally implement
+`pause(id, reason)` and `resume(id, reason)` to support interaction pausing.
+
+### SegmentedControl forms
+
+SegmentedControl renders native radio inputs. Set `name` to post the selected
+option value with ordinary form submission or FormData; numeric values post as
+strings while bound values retain their declared type. Unselected, unknown,
+disabled-option, disabled-control and disabled-fieldset values are omitted.
+`required` uses native form validation and accepts numeric zero. Nameless controls
+validate without posting a generated field. Arrow keys cycle enabled options;
+Home/End select the first/last enabled option. Touch density applies to the full
+clickable segment.
+
+Native form reset restores the initial bound value if that option is still
+available and enabled; otherwise it clears the selection. Canceling the reset
+event preserves the current selection. Reset does not fire `onvaluechange`,
+matching native controls; bind:value reflects it.
+
+### Application icons
+
+Icon includes the original menu/search/chevron/action glyphs plus `alert`,
+`warning`, `info`, `home`, `user`, `settings`, `trash`, `edit`, `calendar`,
+`clock`, `camera`, `upload`, and `download`. Import `registerIcons` from
+`@happyvertical/smrt-ui` to install an application SVG path map at startup.
+Registrations update mounted icons; the returned cleanup function removes that
+registration and restores the previous active set. Last active registration wins,
+and an explicit Icon `path` prop wins over every named set. Unknown names retain
+their empty shape. Names and paths must be nonempty strings; invalid mixed sets
+are rejected atomically. Sets are snapshotted, so later caller mutations do not
+change glyphs. Register static application assets, never request or identity data,
+and install the same application set for SSR and client hydration.