@synopackageland/ui 0.23.9 → 0.25.1

package/docs/callout.md

@@ -103,9 +103,9 @@ halfway across. A Callout drops it: it stays on the page, where DSM draws its
 notes with no decoration.
 
 The title reads in the text colour at 600, and the message under it in the
-secondary text colour. Corners are 12px (`--ui-callout-radius`), rounder than
-a card on purpose: a Callout floats above the settings rather than being one
-of them. Buttons in `#actions` and a toast's action are capsules. A Callout
+secondary text colour. Corners follow `--ui-radius-callout` (10px in a DSM window, 12px on a full
+page and mobile; `--ui-callout-radius` overrides it), rounder than a card on
+purpose: a Callout floats above the settings rather than being one of them. Buttons in `#actions` and a toast's action are capsules. A Callout
 fades in and rises 6px when it appears, and a toast slides in; with reduced
 motion both appear at once.
 

package/docs/layout-rules.md

@@ -30,7 +30,7 @@ These rules keep pages built from `@synopackageland/ui` consistent. The componen
 - In a dialog or a side `Sheet`, keep the default `direction="auto"`: as in DSM, the labels sit in a left column whenever the form is at least 400px wide (a 420–480px sheet) and stack above their controls only below that (a phone). Size the column with `Form label-width` (about 120px for short labels); a long label wraps inside it and stays level with its control's first line, whether that is a field, a select, a switch, a toggle group or a segment control.
 - Size a field by its content: number fields are 128px; text fields use `fieldWidth`; in a narrow row that stacks its label (a phone), `md` and `lg` fill the column. Put two short fields side by side rather than stretching one across the page.
 - A checkbox's text sits on the same line as its box. Do not apply `display: grid` to `label` in App CSS; `Checkbox` renders its own label.
-- For 2–4 mutually exclusive settings, use `RadioGroup` (vertical by default, `orientation="horizontal"` when labels fit). In a wizard step, `variant="card"` draws the options as choice cards with an optional `icon` each. A checkbox enables an independent option; a switch turns a feature on or off immediately. Keep the circular radio with a dot, square checkbox with a tick, and pill switch with a moving thumb.
+- For 2–4 mutually exclusive settings, use `RadioGroup` (vertical by default, `orientation="horizontal"` when labels fit). In a wizard step, `variant="card"` draws the options as choice cards with an optional `icon` each. The 2–4 count is a guide, not a limit: the cards wrap, but five or more short options (or longer ones, even three) read better as a vertical radio list. A checkbox enables an independent option; a switch turns a feature on or off immediately. Keep the circular radio with a dot, square checkbox with a tick, and pill switch with a moving thumb.
 - Reserve `SegmentControl` for toolbar view switching: its selected item is a primary-filled capsule. `variant="sheet"` and `SectionTabs` are navigation tabs. Do not use either as a form value selector.
 - Choices side by side are 34px apart (`--ui-choice-inline-gap`, DSM's Task Scheduler) and share one top whether checked or not. For a set of checkboxes use `CheckboxGroup` (`orientation="horizontal"` for a row, `v-model` an array of values), as `RadioGroup` for one choice; Checkboxes written one after another get the same gap. Do not add margins between them.
 - A password field has a show/hide toggle; `Input type="password"` adds it.

package/docs/mobile-native.md

@@ -22,6 +22,37 @@ App. Each line links to its details below.
 | No end space under docked bars | The room under the last row is constant (`--ui-page-end-space`, plus `--ui-bars-room` under docked bars); a fill page's list runs under the FAB and bars to the screen's bottom with no blank band, also when that list is an App's own element nested in the page. |
 | Gesture velocity | One estimator and one set of thresholds for every gesture decision the UI makes. See [Gesture velocity](#gesture-velocity). |
 
+## Phone look
+
+Since 0.25 a touch phone (narrow and a coarse pointer, the phone tokens'
+gate) draws softer than a DSM window: a pale page with white cards on it and
+no frames, round corners, more air and bigger text. It is all in
+`src/theme/phone.css`, inside `@media (pointer: coarse)` and scoped to the
+phone presentation; a desktop, a DSM window (also one narrowed with a mouse)
+and a touch tablet are unchanged. Tap boxes, bar heights, hide on scroll and
+the commit footer behave as before.
+
+| Token or part | Before (phone) | Phone look |
+| --- | --- | --- |
+| Page under cards (`--ui-page-canvas`) | `#fafbf9` | `#f1f3f0` (dark: the dark page, `#121513`) |
+| Card | white, 1px frame, card shadow, 6px corner | white, no frame, 1px soft shadow (none in dark), `--ui-radius-card` 20px |
+| Section list (SectionTabs' phone list) | framed group, 6px corner, 44px rows, full-width rules | inset grouped list: white group, 20px corner, 52px rows, hairlines inset 16px, on the mist |
+| A list of ListItems on the page (`role="list"`, `ul`, `ol`, outside a card, sheet or dialog) | full-bleed rows, full-width rules | the same inset grouped list: one white group per list, rows inset 16px, hairlines from the text's edge, the heading just above it inset to the text |
+| Page background | the mist only on a page of cards | the mist on every page (not a data-grid page or `surface="none"`); a sticky row and `--ui-app-web-surface` follow it |
+| `--ui-radius-md` / `-lg` (and the 0.23.9 roles on them) | 4 / 6 | 12 / 14: md rounds the control, container and popover roles (fields, tool buttons, inset blocks, menus), lg the panel and nav roles |
+| `--ui-radius-dialog` / `-window` / `-sheet` | 8 / 8 / 12 | 24 |
+| Primary, danger and secondary buttons | capsule (action) or 4px (tool) | capsule; a primary's fill is accent step 10 (`#0075db`, 4.6:1 with white) |
+| Segmented control | accent pill on a framed track, equal columns | ink pill (`--ui-phone-ink`, `#1f2421`; dark `#e3e8e4`) on a frameless mist track; 6px sides; up to three segments stay equal columns but one whose label is wider than its share grows to it, so a label is not cut (four ellipsize as before) (`check:phone-layout` checks it) |
+| Phone bar | white with a hairline | the page's colour, no hairline, 17px bold title, round pressed tint |
+| Tab bar | full-width white row with a top rule | a floating white pill inset 16px, 8px above the bottom (`--ui-tab-bar-float`); the current tab is ink on a round pad |
+| `--ui-text-muted` | 40% grey (2:1) | 80% (4.8:1 on the mist; dark 62%) |
+| Separators | `--ui-border-subtle` | `--ui-phone-separator` |
+
+An App that sets `--ui-mobile-bar-bg`, `--ui-mobile-bar-border` or
+`--ui-tab-bar-bg` keeps its colour. The tab bar's box keeps the full width and
+adds the float gap below the pill, so the room AppLayout measures for the
+bottom bars, the FAB's offset and the end space follow it.
+
 ## Width containment and the release gate
 
 Typography tables scroll horizontally within their parent, including a flex
@@ -75,12 +106,12 @@ control and grid sizes; it does not change the 16px field rule.
 
 | Token | Desktop | Touch tablet | Phone | Used for |
 |---|---|---|---|---|
-| `--ui-font-size` | 13 | 13 | **14** | primary text: list and record titles, field values, body copy, menu items |
-| `--ui-font-size-sm` | 12 | 12 | **12** | secondary text: labels, meta, captions, helper text, badges |
+| `--ui-font-size` | 13 | 13 | **15** | primary text: list and record titles, field values, body copy, menu items |
+| `--ui-font-size-sm` | 12 | 12 | **13** | secondary text: labels, meta, captions, helper text, badges |
 | `--ui-font-size-xs` (new) | 12 | 12 | 12 | the smallest text anywhere |
-| `--ui-line-height` | 20 | 20 | **20** | body line |
-| `--ui-font-size-lg` | 14 | 14 | **15** | card and section titles |
-| `--ui-font-size-title` | 16 | 16 | **16** | header and dialog titles |
+| `--ui-line-height` | 20 | 20 | **22** | body line |
+| `--ui-font-size-lg` | 14 | 14 | **17** | card and section titles |
+| `--ui-font-size-title` | 16 | 16 | **17** | header and dialog titles |
 | `--ui-grid-font-size` (new) | 13 | 13 | **14** | grid cell text (not yet read by the canvas grid; see below) |
 | `--ui-font-size-field` (new) | 16 | 16 | 16 | every field on a coarse pointer, to stop iOS focus zoom |
 | `--ui-control-md` | 28 | **44** | **44** | fields, selects, form and sheet buttons |
@@ -91,15 +122,15 @@ control and grid sizes; it does not change the 16px field rule.
 | `--ui-grid-row-height` / `-header-height` | 28 | **36** | **32** | canvas grid rows (docs/ux-grid.md) |
 | `--ui-list-row-height` | 32 | **44** | **44** | list rows, a DisclosureRow |
 | `--ui-menu-row-height` | 32 | **44** | **44** | menu, select and sheet list rows |
-| `--ui-page-padding-x` / `-y` | 16 (narrow layout 12) | 16 | **12** | page gutter |
-| `--ui-section-gap` | 12 | 12 | **12** | space between sections |
-| `--ui-card-padding` | 20 (Card default) | 20 | **12** | card inset |
+| `--ui-page-padding-x` / `-y` | 16 (narrow layout 12) | 16 | **16 / 12** | page gutter |
+| `--ui-section-gap` | 12 | 12 | **16** | space between sections |
+| `--ui-card-padding` | 20 (Card default) | 20 | **16** | card inset |
 | `--ui-chrome-height` | 44 (web 48, narrow layout 44) | – | **44** | the phone bar (plus its 1px rule) |
 | `--ui-tab-bar-height` | – | – | **48** | the tab bar's row, above `--ui-safe-bottom` |
 | `--ui-section-tab-height` | 44 | 44 | **40** | the drawn height of a phone's tabs strip (its tap box stays 44) |
 | `--ui-sticky-top-offset` | 0 | 0 | measured | what sticks at the top of a PageContent (see below) |
 | `--ui-page-end-space` | 24 | 24 | 24 (constant: hiding the bars never changes it) | room after a page's last row |
-| `--ui-radius-sheet` (new) | 12 | 12 | 12 | top corners of a bottom sheet |
+| `--ui-radius-sheet` (new) | 12 | 12 | **24** | top corners of a bottom sheet |
 | `--ui-safe-top/right/bottom/left` (new) | `env(safe-area-inset-*, 0px)` | same | same | notch and home indicator; non-zero only once the viewport meta has `viewport-fit=cover` |
 | `--ui-pressed` (new) | 8% of the text colour | same | same | the pressed tint |
 
@@ -159,6 +190,17 @@ component rule overrides them.
   IconButton draw their own pressed state (`data-variant`), so they're
   skipped. A component that sets its own shadow or `active:` style also keeps
   its own.
+- Press feedback on a phone (`phone.css`, a coarse pointer in the mobile
+  presentation): a Button or an IconButton takes the `--ui-state-pressed`
+  layer over its own active colour and settles to `scale(0.98)` in 100ms
+  (`cubic-bezier(0.24, 1, 0.4, 1)`), springing back on release. The scale is
+  a transform, so nothing around the control moves. A ghost Button or
+  IconButton already fills with the layer and a link button fades, so neither
+  takes a second layer. A list row, a tab and a menu item keep the layer
+  alone: a row that shrank would pull away from its hairlines. A disabled
+  control takes nothing. Reduced motion and `data-ui-motion="off"` keep the
+  layer and drop the scale. A DSM window, a desktop page and a touch tablet
+  are unchanged.
 - Hover: every hand-written `:hover` rule in the theme sits inside
   `@media (hover: hover)`, so a tap leaves no stuck hover look. Tailwind's
   `hover:` utilities already do this.
@@ -437,7 +479,11 @@ contain`, a pinned footer and safe-area padding. The top corners use
   overrides that.
 
 `Dialog` on a phone (an app 640px or narrower) renders as a `BottomSheet`:
-`auto`, or `full` for `fullscreen` and for a form with more than 3 fields. The
+`auto`, or `full` for `fullscreen` and for a form with more than 3 fields.
+`presentation="modal"` keeps a centred window instead, with the phone's
+dialog corner and dim scrim, as tall as its content up to its `height` inside
+the safe area (only a longer body scrolls); `WizardDialog` uses it by default, as a DSM
+wizard opens, and `presentation="adaptive"` gives it the bottom sheet. The
 CSS-only dialog-as-sheet in `adaptive.css` is gone. `Sheet side="bottom"` is
 a `BottomSheet` everywhere; without `size` it fits its content. Left and right
 sheets are unchanged, and their footer keeps clear of the home indicator.

package/docs/release-checks.md

@@ -8,7 +8,7 @@ checks through the optional build-isolation wrapper.
 
 | Entry point | Default | Explicit full |
 | --- | --- | --- |
-| `npm run gates`, `scripts/gates.mjs` | Internal-content checks, build, lint, typecheck, unit tests, notices, isolated pack and tarball content audit | Adds Chromium and WebKit installation, responsive/adaptive/date-picker/JSON/host/switch/layout/InfoTip/motion/short-viewport/phone-layout/phone-bars (Chromium and WebKit)/focus-restore browser checks, Histoire build, exact-tarball registry consumer smoke |
+| `npm run gates`, `scripts/gates.mjs` | Internal-content checks, build, lint, typecheck, unit tests, notices, isolated pack and tarball content audit | Adds Chromium and WebKit installation, responsive/adaptive/date-picker/JSON/host/switch/layout/InfoTip/motion/short-viewport/phone-layout/phone-bars (Chromium and WebKit)/press/focus-restore browser checks, Histoire build, exact-tarball registry consumer smoke |
 | `pnpm check`, `check:fast` | Basic, with optional Docker host build isolation | `SPL_FULL_GATE=1` selects the same full plan |
 | `fast-ci.yml`, composite verify action | Basic | No automatic extended checks |
 | Disabled CI/release workflow templates | Basic, version/tag/ancestry checks, stage, pack and actual archive audit | No implicit browser or registry consumer smoke |

package/docs/theme-hooks.md

@@ -182,7 +182,7 @@ before the token existed. Set them on the app root or any ancestor.
 | `--ui-mobile-bar-fg` | the phone bar's text, menu button and brand | `var(--ui-text-secondary)` (text), `var(--ui-text)` (button, brand) |
 | `--ui-mobile-bar-border` | the phone bar's bottom rule | `var(--ui-border-subtle)` |
 | `--ui-callout-max-width` | caps how wide a `Callout` grows; it spans its container by default | none |
-| `--ui-callout-radius` | a `Callout`'s and a `Toast`'s corners | 12px |
+| `--ui-callout-radius` | a `Callout`'s and a `Toast`'s corners | `--ui-radius-callout` (window 10px, web and mobile 12px) |
 | `--ui-callout-glow` | how strong the tone's glow is behind a `Callout`'s or `Toast`'s icon; a dark theme raises it (workbench: 14%) | 9% |
 | `--ui-callout-shadow` | the shadow under a `Callout` and a `Toast` (workbench dark: `0 10px 28px -12px rgba(0, 0, 0, 0.6)`) | `0 8px 24px -12px rgba(15, 23, 42, 0.18)` |
 
@@ -193,24 +193,34 @@ The colour, radius, spacing and web tokens are listed in the
 ## Corner radius
 
 Components round their corners with a role, not a step, so a theme can round
-one kind of surface without the others:
-
-| Token | Rounds | Window | Web and phone |
-| --- | --- | --- | --- |
-| `--ui-radius-inner` | a part inside a control or a popover: a menu row, a tag, a tooltip, a checkbox box, a small hit area | 3px | 3px |
-| `--ui-radius-control` | a button, a field, a select, a segment | 4px | 4px |
-| `--ui-radius-container` | a flat block: a card's surface, an inset area, a thumbnail frame | 4px | 4px |
-| `--ui-radius-popover` | a menu, a select or combobox list, a popover, a picker | 4px | 4px |
-| `--ui-radius-panel` | a raised block: a choice card, a framed region, a drop zone, a side drawer, a grid card | 5px | 6px |
-| `--ui-radius-nav` | a navigation row in the sidebar or the top bar | 5px | 6px |
-
-Each role defaults to a step of the scale (`--ui-radius-sm`, `-md`, `-lg`),
-and the steps stay public. Override a role to change only that kind of
-surface; override a step on `:root` to move every role on it. The roles are
-declared on `:root` and again on the web and phone presentation roots
-(`adaptive.css`), so a step overridden there still moves them. A step
-overridden on any other element does not reach the roles below it: override
-the role on that element instead.
+one kind of surface without the others. Since 0.25 a DSM window rounds a step
+softer than DSM's own 3-5px and a full page softer still; the mobile
+presentation keeps the steps (a phone rounds them itself, `phone.css`):
+
+| Token | Rounds | Window | Web | Mobile | Touch phone |
+| --- | --- | --- | --- | --- | --- |
+| `--ui-radius-inner` | a part inside a control or a popover: a menu row, a tag, a tooltip, a checkbox box, a small hit area | 4px | 6px | `sm` (3px) | 3px |
+| `--ui-radius-control` | a button, a field, a select, a segment | 6px | 8px | `md` (4px) | 12px |
+| `--ui-radius-container` | a flat block: a card's surface, an inset area, a thumbnail frame | 8px | 10px | `md` (4px) | 12px |
+| `--ui-radius-popover` | a menu, a select or combobox list, a popover, a picker | 8px | 10px | `md` (4px) | 12px |
+| `--ui-radius-panel` | a raised block: a choice card, a framed region, a drop zone, a side drawer, a grid card | 8px | 12px | `lg` (6px) | 14px |
+| `--ui-radius-nav` | a navigation row in the sidebar or the top bar | 6px | 8px | `lg` (6px) | 14px |
+| `--ui-radius-window` | a dialog with a title bar | 10px | 14px | 8px | 24px |
+| `--ui-radius-dialog` | a message box | 10px | 14px | 8px | 24px |
+| `--ui-radius-callout` | a `Callout` and a `Toast` (`--ui-callout-radius` still wins) | 10px | 12px | 12px | 12px |
+
+A part inside a popover stays concentric with it: a menu row (`inner`, 4px) sits
+4px inside its menu (`popover`, 8px). What floats highest rounds most.
+
+The steps `--ui-radius-sm`, `-md` and `-lg` stay public at DSM's 3, 4 and 5px
+for an App's own parts. On the mobile presentation the roles follow the steps
+(declared again on its root in `adaptive.css`), so a step overridden there
+moves them. On a touch phone (docs/mobile-native.md, "Phone look") the phone
+scope sets the steps `--ui-radius-md` to 12px and `-lg` to 14px, so the roles
+follow them there; a card on a page of cards and a grouped list take
+`--ui-radius-card` (20px), and a sheet `--ui-radius-sheet` (24px).
+
+Override a role to change only that kind of surface:
 
 ```css
 :root {
@@ -219,10 +229,31 @@ the role on that element instead.
 }
 ```
 
+To keep the pre-0.25 corners in a DSM window, set the roles back to the steps:
+`inner` 3px, `control`, `container` and `popover` 4px, `panel` and `nav` 5px,
+`window` 3px, `dialog` 6px, `callout` 12px.
+
+## Focus, hover and the scrim
+
+| Token | What | Value |
+| --- | --- | --- |
+| `--ui-focus-ring` | the keyboard focus colour | the accent (`--ui-accent-9`), solid |
+| `--ui-shadow-focus` | keyboard focus on a control: a 2px gap in the surface colour, then a 2px ring | `0 0 0 2px surface, 0 0 0 4px ring` |
+| `--ui-shadow-focus-inset` | keyboard focus inside a row, a cell or a tab strip | `inset 0 0 0 2px ring` |
+| `--ui-shadow-focus-field` | a focused field, whose own border turns primary: a soft halo | `0 0 0 3px` `--ui-focus-halo` (`--ui-accent-a4`) |
+| `--ui-state-hover` | the pointer on a ghost button or a menu row | 6% of the text colour |
+| `--ui-state-pressed` | pressed (a ghost button, a touch control while the finger is down) | 8% of the text colour; `--ui-pressed` is a deprecated alias |
+| `--ui-surface-hover` | the pointer on a list or table row (DSM's pale blue) | `--ui-accent-a2` |
+| `--ui-overlay` | the scrim behind a modal | window: white 55%; web: `--ui-overlay-page`; mobile: `--ui-overlay-dim` (black 40%, as before) |
+| `--ui-overlay-page` | the scrim on a full page | `rgba(15, 23, 32, 0.32)`; dark `rgba(0, 0, 0, 0.5)` |
+
+A component never writes a ring out (`shadow-[0_0_0_3px_…]`); it uses one of
+the focus tokens (`tests/css/focus-ring.test.ts`).
+
 ## Motion
 
 The components move a little by default: dialogs and their masks fade in and
-settle from 97 %, menus, popovers and select lists drop 4px from their trigger,
+settle from 97 %, menus, popovers and select lists drop 6px from their trigger (settling from 96 %),
 a notification slides 8px in, expandable bodies (`Card`, `SettingsSection`,
 `ExpandableItem`, `Callout` details, `TimelineRow`, `FacetPanel`, `Accordion`,
 `Fieldset`) open their height, a row the user just added fades in, and a tab

package/docs/wizard.md

@@ -57,15 +57,20 @@ const open = ref(false)
   does not stack its children with a gap. Several blocks go in one `Form`
   (fields one field gap apart) or a `<Space direction="column">`; a lone
   Callout, paragraph or card grid needs no wrapper.
-- **Choices.** A step's 2–4 options are choice cards:
+- **Choices.** Options that each need an icon and a line are choice cards:
   `<RadioGroup variant="card" orientation="horizontal" :options>`. Each card
   shows the option's `icon` in a tile, its label and one line, and keeps the
   radio dot; the whole card picks it and the chosen card takes the primary
   border and a soft fill. The cards share the row (180px at least) and wrap
-  in a narrow window.
+  in a narrow window. Cards usually suit 2–4 options; that is a guide, not a
+  limit, and nothing cuts a fifth. Five short options (symptoms, say) read
+  better as a vertical `RadioGroup` list, and long options do too even when
+  there are three. Pick by how the options read, not by their count.
 - **Types.** `welcome` offers only Start; `done` drops Back and Cancel, fills
-  the progress and turns the main action into Finish. The last step without
-  `next-step-key` turns it into Apply.
+  the progress and turns the main action into Finish; `result` ends the flow
+  with an outcome the app sets ([Result](#result)); `progress` shows work the
+  app runs ([Progress](#progress)). The last step without `next-step-key`
+  turns the main action into Apply.
 - **Main action.** `next-label`, `next-disabled` and `:show-next="false"` (a step
   that moves on by itself or through its own choices, such as a row of cards)
   change it for one step. `:show-back="false"` hides Back.
@@ -98,9 +103,12 @@ const open = ref(false)
 The `#footer` slot replaces the footer's buttons and receives `nextStep`,
 `previousStep`, `finish`, `cancel`, `canGoPrevious`, `isLastStep`, `busy` and
 `stepKey`. Events: `next-step`, `previous-step` (`{ from, to }`), `finished`,
-`cancel`. A step guard (`pre-enter-next-step`, `pre-enter-previous-step`)
-returning `false` keeps the step; the main action shows a spinner while it
-runs. The step list does not navigate, so a guard cannot be skipped.
+`cancel` and `navigation-error` ([Guards](#guards)). The step list does not
+navigate, so a guard cannot be skipped.
+
+`finished` means the user took Finish (or Apply); it does not mean the work
+succeeded. Read the outcome from your own state, and do not run the work again
+in a `finished` callback.
 
 A wizard fills the height its container gives it (`WizardDialog` and
 `<Dialog flush height="…">` give it one); on a page, set a height on its
@@ -117,6 +125,220 @@ there is no Back and nothing shifts. A welcome step offers Start alone; a done
 step offers Finish (and its own `#actions`). There is no Close in the footer:
 a `WizardDialog` closes from its header.
 
+## Result
+
+A `type="result"` step ends the flow with an outcome: `result-tone` is
+`success`, `warning`, `danger` or `neutral` (the default, which claims neither
+success nor failure). A partial import, a failed connection test or a scan
+that finished with warnings is a result, never a `done` step: `done` always
+shows the success mark and its burst.
+
+```vue
+<WizardStep
+  step-key="result"
+  type="result"
+  :result-tone="tone"
+  headline="Some items were not imported"
+  description="The imported items are kept; check why the others failed and try again"
+>
+  <FindingList :items="findings" />
+  <template #actions>
+    <Button variant="ghost" kind="tool" @click="startAgain">Check again</Button>
+  </template>
+</WizardStep>
+```
+
+- The step shows its tone's mark (a tick, a warning sign, a cross or an info
+  mark) on its colour, read as "Succeeded", "Warning", "Failed" or "Done". It
+  pops in once, with no ring and no burst for any tone.
+- Finish is the one main action, blue for every tone: a red mark does not
+  make the button red. Back and Cancel are gone; the header's close button and
+  the step's `#actions` stay. `next-label` renames Finish.
+- The guide marks the step with the outcome: a warning or a failure is not
+  drawn or read as completed. The steps before it read as completed: that says
+  the user passed them, not that the backend did each part.
+- A result step never moves on: `next-step-key` is ignored (with a warning
+  in development).
+- Map the outcome in the app: a rollback that worked can be `neutral`, a
+  partial or unknown rollback `warning`, a failed one `danger`.
+
+## Progress
+
+A `type="progress"` step shows work the app runs: a progress bar and a status
+line. The wizard only draws them; the app starts, watches and ends the work,
+and moves the wizard on (`v-model:active-step-key`) when the backend says the
+work ended.
+
+```vue
+<WizardStep
+  step-key="scanning"
+  type="progress"
+  headline="Checking"
+  :progress="total > 0
+    ? { mode: 'determinate', label: 'Items checked', value: checked, max: total, status: statusText }
+    : { mode: 'indeterminate', label: 'Getting status', status: statusText }"
+  stop-label="Stop watching"
+  @stop="stopWatching"
+/>
+```
+
+- `progress` is `{ mode: 'indeterminate', label, status? }` while the total is
+  unknown, or `{ mode: 'determinate', label, value, max, valueLabel?, status? }`.
+  Without it the bar is indeterminate and named by the headline. `status` is
+  read politely when it changes.
+- The bar is on its own tinted track (never grey) and has no stripes or
+  pattern; reduced motion stills it.
+- Next and Back are hidden unless the step sets `:show-next="true"` or
+  `:show-back="true"` (for work that only reads). Back never undoes work that
+  changed data.
+- `stop-label` adds a secondary button that emits `stop`; `stop-disabled`
+  disables it while the app waits for the backend. "Stop watching" only stops
+  the app looking; "Cancel task" is for a backend that can cancel, and the app
+  shows a cancelled result only once the backend confirms it.
+- There is no timeout, retry count or auto-advance: time passing is not a
+  failure. `lazy` only mounts the step's content; it starts and stops nothing.
+
+## Guards
+
+`pre-enter-next-step` and `pre-enter-previous-step` run before a move. A guard
+gets `{ from, direction, signal }` and returns:
+
+| Return | Effect |
+| --- | --- |
+| nothing | the move goes on as the step says |
+| `false` | the step stays |
+| `{ goTo: 'key' }` | the move goes to that step instead, this time only |
+
+```ts
+async function checkAgain({ signal }: WizardGuardContext): Promise<WizardGuardResult> {
+  const status = await api.status({ signal })
+  if (status.needsAccess) return { goTo: 'access' }
+  return status.ready ? undefined : false
+}
+```
+
+- The main action shows a spinner while a guard runs; presses meanwhile are
+  ignored, so the guard runs once.
+- A `goTo` is checked once the app's update has rendered, so a step the
+  guard mounts with `v-if` can be its target. It moves through the usual
+  `next-step` or `previous-step` event, `update:active-step-key` and focus.
+  The target's own guard does not run.
+- A `goTo` that names no registered step (`unknown-step`) or the step itself
+  (`same-step`) keeps the step and emits `navigation-error`. A guard that
+  throws or rejects keeps the step and emits `navigation-error` with
+  `guard-rejected`, without the error's text: show your own message.
+- `signal` aborts when the move no longer matters: the wizard left the step,
+  the app reset `active-step-key`, the `WizardDialog` closed (not while "Keep
+  editing" is asked) or the wizard unmounted. The spinner stops at once, and
+  a reply that comes later moves nothing and emits nothing. Pass `signal` to
+  your requests so they stop too.
+- A step key is not a permission. The target step and the backend still check
+  what the user may do.
+
+A guard written as `() => false | void` still works as before.
+
+## Recipes
+
+These use the API above; none needs anything new.
+
+### Branches the backend decides
+
+Steps need not all be known up front. A guard loads the branch, and a
+`next-step-key` function reads it; the wizard reads `next-step-key` after the
+guard. A step only some branches need can be mounted with `v-if`; it takes its
+place in document order.
+
+```vue
+<WizardStep step-key="inspect" headline="Check the target"
+  :pre-enter-next-step="loadBranch"
+  :next-step-key="() => branch.needsAccess ? 'access' : 'preview'" />
+<WizardStep v-if="branch.needsAccess" step-key="access" headline="Allow access" next-step-key="preview" />
+<WizardStep step-key="preview" headline="Confirm" />
+```
+
+Map each backend kind to a step key in the app, and treat an unknown kind as
+"cannot continue": never use a backend string as a key. The progress counts
+the mounted steps, so mount the path the user takes, not every branch; when
+the total is unknown, `progress-text` can say so.
+
+### Two equal ways on
+
+Keep or roll back, replace or keep: put the choices in one `RadioGroup` (cards
+when they need an icon and a line) and let one main action confirm the chosen
+one. Its `next-label` follows the choice; a choice never acts by itself, so
+moving through the options with the arrow keys does nothing else. The footer
+keeps one blue button. A choice that destroys data asks in a confirmation
+dialog first, whose confirm button is the only red one.
+
+```vue
+<WizardStep step-key="decision" headline="Choose what to do"
+  :show-back="false" :next-disabled="!decision"
+  :next-label="decision === 'rollback' ? 'Roll back' : 'Keep changes'"
+  :next-step-key="() => decision === 'rollback' ? 'working' : 'result'"
+  :pre-enter-next-step="confirmDecision">
+  <RadioGroup v-model="decision" variant="card" orientation="horizontal" :options="allowedDecisions" />
+</WizardStep>
+```
+
+Offer only the choices the backend allows: an interrupted run has no "keep".
+
+### Handing over to another wizard
+
+The parent opens one wizard at a time. To hand over (a diagnosis opening a
+fix): check what the source passes, stop the source's pending work, close the
+source, then set the target's props and open it. Do not rely on two
+`v-model:open` flips in one tick; mount the two exclusively (`v-if` on one
+state) so only one dialog holds the focus. A handover is not the source's
+Finish and not a rollback, and secrets do not travel in its props.
+
+```ts
+type WizardRequest = { kind: 'diagnose' } | { kind: 'setup'; intent: 'send' | 'receive' } | undefined
+```
+
+### Watching work
+
+For a [progress](#progress) step the app watches the backend:
+
+1. Watch only while the wizard is open on that step. Leaving, closing,
+   unmounting or reopening ends the round: clear its timer and abort its
+   request.
+2. One request at a time: schedule the next when the last ends, not with
+   `setInterval`. Follow the backend's retry-after; on errors back off slowly
+   (from about a second to 15 or 30 seconds). These are a schedule, not a
+   deadline.
+3. After every `await`, check that the round, the open state and the step are
+   still the same before writing anything.
+4. A network error shows "Status not up to date" with a way to check again and
+   keeps the last progress. Only the backend's own failed or interrupted state
+   leads to a failure result.
+5. Reopening reads the run from the backend and resumes; it does not apply
+   again.
+
+### Opening another DSM app
+
+When a step needs the user to finish something in another app, open it with
+the platform SDK's app launcher (it knows the app's verified ID; a package
+name is not an app ID), and always show the path in words as well, for a host
+that cannot open it. A secondary button opens it; the step's main action is
+"Check again", whose guard reads the state again. Coming back to the wizard
+only triggers a check: it is never a success by itself.
+
+```vue
+<WizardStep step-key="external" headline="Finish in the other app"
+  next-label="Check again" :pre-enter-next-step="checkAgain">
+  <p>When you are done there, come back and check again</p>
+  <Button variant="secondary" kind="tool" @click="openApp">Open the app</Button>
+  <p v-if="launchUnavailable">Open it from the DSM main menu</p>
+</WizardStep>
+```
+
+### Not provided
+
+The wizard has no backend step schema or runner, no timeout or retry settings
+for work, no two-primary footer, no card count option, no cross-wizard
+navigation and no launcher of its own. These stay with the app (or the
+platform SDK) on purpose.
+
 ## Modal
 
 `WizardDialog` opens like a DSM modal window, in the app (app-local, see
@@ -131,8 +353,16 @@ a `WizardDialog` closes from its header.
   step title) shows a ring only after a key, never after a click.
 
 These are `Dialog` props (`scrim="light"`, `:close-on-outside="false"`,
-`:header-divider="false"`), so a dialog of your own around a `Wizard` can
-open the same way.
+`:header-divider="false"`, `presentation="modal"`), so a dialog of your own
+around a `Wizard` can open the same way.
+
+On a phone `WizardDialog` stays a centred window, as a DSM wizard does: the
+phone's dialog corner, the phone's dim scrim, the same fixed header and
+footer. It is as tall as its step, up to the wizard's height inside the
+phone's safe area; only a longer step scrolls, between the header and the
+footer. `presentation="adaptive"` keeps the bottom sheet instead, for an app
+that wants its earlier phone look; other dialogs are bottom sheets on a phone
+as before. The "Discard changes?" question is always a centred window.
 
 ## Leaving with input
 
@@ -164,6 +394,7 @@ in every built-in locale.
 - **Motion.** A step fades in from 10px on the side it comes from and its
   title fades in; the progress segments ease to their new state; the done mark
   pops with a ring and a short burst. Reduced motion turns all of it off.
-- **Size.** In a phone-width window the dialog is a bottom sheet.
+- **Size.** In a phone-width window the dialog stays a centred window with a
+  margin around it; `presentation="adaptive"` makes it a bottom sheet.
 - **Theme.** Colours are the theme's roles, so the wizard follows the accent
   and the dark theme.