@bitforgehq/ui 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,3665 @@
+# Changelog
+
+All notable changes to `@bitforgehq/ui`. One `##` section per version; one `###` sub-section per touched component (the agent-docs generator lifts those into each component's page).
+
+The heading for the version being worked on carries `(unreleased)` in place of a date. At release time, that placeholder is replaced with the release date (`## 0.3.1 (unreleased)` becomes `## 0.3.1 (YYYY-MM-DD)`) in the same commit that bumps `projects/ui/package.json`. See "Releasing" in the root `README.md`. 0.3.0 is the first version published to npm; the 0.2.0 and 0.1.0 sections below are the history of versions that were never published.
+
+## 0.3.0 (2026-09-28)
+
+### Migration
+
+Breaking changes from 0.2.x, each with its fix:
+
+1. Fields show default text for errors that carry no `message` (Signal Forms validators without
+   `{ message }`, Reactive `Validators.*`). Before: a touched invalid field turned red with no
+   text unless you passed `errorMessage`. After: it shows its kind's default text ("Fill in this
+   field", "Use at least 5 characters", …). Fix: translate with
+   `provideBfLabels({ validation: {...} })`, or keep passing `errorMessage`.
+2. Text fields default to the compact `md` step. Before: `bf-input`, `bf-select` and `bf-textarea`
+   defaulted to `lg` (48 px, 16 px sides). After: `md` (40 px, 14 px sides, 14 px type; the
+   textarea's padding and type). Fix: Capacitor apps add `provideBfDefaults({ fieldSize: 'lg' })`
+   to their `ApplicationConfig.providers` to keep the 0.2 look, or `provideBfDefaults({ size: 'lg' })`
+   to enlarge every control; a single field takes `size="lg"`.
+3. `bf-segmented` heights follow the shared scale. Before: `md` (default) was a 44 px track (36 px
+   segments), `sm` a 40 px track. After: the track is `sm` 32, `md` 40, `lg` 48 px. Fix:
+   `size="lg"` (48) where the old 44 px control must stay touch-sized, or
+   `provideBfDefaults({ controlSize: 'lg' })` app-wide.
+4. `bf-chip` has a `size`. Before: a fixed 36 px pill. After: `md` 40 px by default (`sm` 32,
+   `lg` 48). Fix: `size="sm"` for a 32 px filter row.
+5. `BfFieldSize`, `BfButtonSize` and `BfSegmentedSize` are deprecated aliases of `BfSize`. Before:
+   separate unions (`BfFieldSize` `'md' | 'lg'`, `BfSegmentedSize` `'sm' | 'md'`). After: all three
+   are `BfSize` (`'sm' | 'md' | 'lg'`). Fix: no action needed unless you switch exhaustively over
+   `BfFieldSize` or `BfSegmentedSize` (add the new step); import `BfSize` from `@bitforgehq/ui`
+   going forward, as the aliases are removed in 1.0.0.
+6. "Nothing selected" is `null`, not `''`, in `bf-select`, `bf-radio-group` and `bf-segmented`.
+   Before: `value` was a `string` defaulting to `''`, and `bf-select` showed its placeholder for any
+   falsy value. After: the controls are generic (`BfSelectComponent<T = string>`, …) with
+   `value: T | null` defaulting to `null`; an option whose value is `''` is now a real, selectable
+   option, and the placeholder shows only while no option matches. `[formField]` and
+   `[(value)]` bindings to a `string` field or signal keep compiling (Angular does not type-check
+   the write-back of a two-way binding); an explicit `(valueChange)="x.set($event)"` into a
+   `string` signal no longer compiles (`string | null` is not assignable to `string`). Fix: type
+   the bound signal or field `T | null` and start it at `null` (a `required()` rule treats `null`
+   as empty), compare against `null` instead of `''`, or listen to `(changed)`, which emits only a
+   chosen, never-null `T`.
+7. Object option values need `compareWith`. Before: options matched by `===` on strings only.
+   After: a value is matched to an option with `Object.is` by default, so an object value that is
+   equal but not the same instance (e.g. reloaded from the server) selects nothing. Fix: pass
+   `[compareWith]="byId"` with `byId = (a: Team, b: Team) => a.id === b.id`.
+8. Numbers bind to `bf-number-input`. Before: a numeric field used `bf-input type="number"` with a
+   `string` model and could not use Signal Forms `min()`/`max()`. After: `bf-number-input` binds
+   `number | null` (empty is `null`), takes `min`/`max`/`step`, and reports unreadable text as a
+   `parse` error. Fix: replace `<bf-input type="number" [(value)]="qty">` and its string model with
+   `<bf-number-input [(value)]="qty">` (import `BfNumberInputComponent` from
+   `@bitforgehq/ui/number-input`) and `qty = signal<number | null>(…)`;
+   `bf-input type="number"` still works and stays string-typed.
+9. Object option values render their index as the native value. Before: every option value was a
+   string, rendered as `<option value="…">` and as the radio's `value`. After: string, number and
+   boolean values still render as themselves (`"42"` for `42`); an object value renders its option
+   index (`"0"`, `"1"`, …) in `bf-select` and `bf-radio-group`. Fix: for object options, pick by
+   label in browser tests (`selectOption({ label })`) and post the model, not native form data.
+10. `bf-segmented`'s public `tabStop` is an index. Before: the value of the segment that owned the
+    tab stop (`''` when none). After: its option index (`-1` when every option is disabled). Fix:
+    read `options()[tabStop()]?.value` where you read `tabStop()`.
+11. Inside `bf-tabs` the tab bar is a `nav` of links, not a `tablist`. Before: `nav` >
+    `role="tablist"` > `button role="tab"` with `aria-selected`, a roving tab stop and arrow-key
+    selection. After: `nav` > plain group > `<a href>` per tab with `aria-current` on the active
+    one (`page` at the tab's root page, `true` on a child page of it); every tab is in the tab order
+    and the arrow keys do nothing (Tab moves between tabs). In Safari and iOS WKWebView (the
+    Capacitor iOS app) Tab reaches links only with "Press Tab to highlight each item" turned on
+    (Option+Tab otherwise), so a hardware-keyboard user who reached the old tab buttons with Tab
+    now needs Option+Tab there; VoiceOver and Full Keyboard Access are unaffected. A standalone
+    `bf-tab-bar`, and one inside a routed page under `bf-tabs`, is unchanged. Fix: in tests and
+    scripts, query `getByRole('link', { name: 'Projects' })` instead of `getByRole('tab', …)` and
+    assert `aria-current` (`page`, or `true` below the tab's root) instead of
+    `aria-selected="true"`; select a tab with a click or Enter, not the arrow keys.
+12. `bf-card [interactive]` and its `clicked` output are deprecated. Before:
+    `<bf-card [interactive]="true" (clicked)="open()">` made the whole card one `<button>`, hiding
+    headings and nesting controls. After: they still work in 0.3 and are removed in 1.0.0. Fix: put
+    a `bfAction` link or button in the card's heading,
+    `<h3><a bfAction routerLink="/projects/atlas">Atlas rebrand</a></h3>` (import
+    `BfActionDirective`), and give other controls in the card `class="relative z-1"`.
+13. Custom themes set `--color-primary-text`. Before: the text button, the focused field label
+    and the iOS back button used `--color-primary` as text, so a light brand primary (yellow, light
+    green) failed 4.5:1. After: they use the new `--color-primary-text` (`#2b26ba` light, `#8c88f5`
+    dark by default), which the library cannot derive from your override. Fix: an app that
+    overrides `--color-primary` adds `--color-primary-text` (a shade of it with ≥ 4.5:1 on `bg` and
+    `surface`) to its `@theme` and `.dark` blocks; regenerate the snippet with the docs site's
+    theme configurator, which also derives a contrast-safe `--color-primary-strong`. Optionally set
+    `--radius-control` (default `9999px`) to move buttons, chips, badges, segmented, the tab bar,
+    the action bar and toggles off the pill.
+14. `BfTabBarHost` and `BfTabLinks` gained required members. Before: `BfTabBarHost` had `active`,
+    `tabStop` and `select`. After: it also requires `linkMode`, `linkHref(id)` and
+    `linkIsRoot(id)`, and the new `BfTabLinks` (`BF_TAB_LINKS`) requires `href(id)` and
+    `isRoot(id)`. Fix: only a class that implements `BfTabBarHost` itself (a custom bar providing
+    `BF_TAB_BAR`) breaks; add `readonly linkMode = false`, `linkHref = () => null` and
+    `linkIsRoot = () => true`.
+15. `bf-alert`'s role follows `urgent`, not `variant`. Before: a `danger` alert was
+    `role="alert"` (assertive), every other variant `role="status"`. After: every alert is
+    `status` unless it has `urgent`, in any variant. Fix: add `urgent` to danger alerts that must
+    interrupt; in tests, query `getByRole('status')` for the others.
+16. `bf-alert`'s dismiss button is named after the title. Before: "Dismiss" (or `dismissLabel`).
+    After: "Dismiss: Sync failed" when the alert has a `title`, the label alone without one. Fix:
+    in tests, query `getByRole('button', { name: 'Dismiss: Sync failed' })`, or match the label as
+    a prefix.
+17. Alert dialogs and action sheets focus the cancel button first. Before: focus landed on the
+    first button (`BfAlertDialogService`) or the first row (`BfActionSheetService`). After: it lands
+    on the `cancel`-role button (an action sheet always has one), else the first button. Fix: in
+    tests, stop assuming the first button is focused; press Tab or click the button you mean.
+18. `BfAlertDialogService.open()` returns `Promise<string | undefined>`. Before: `Promise<string>`;
+    an alert without a cancel button could only be answered by tapping a button. After: a
+    navigation to another URL path closes every alert, resolving the cancel button's answer, or
+    `undefined` when it has no cancel button. Fix: handle `undefined` like cancel (for example
+    `if (answer === 'delete')` already does); where a `string` is required, write
+    `(await alerts.open(…)) ?? 'cancel'`, or pass `closeOnNavigation: false` to keep the alert open
+    until a button is tapped.
+19. Overlays close when the URL path changes. Before: a sheet, modal, action sheet or alert stayed
+    open over the next page after a push, a pop, a tab switch or a deep link. After: they close
+    (`afterClosed` resolves `undefined`, an action sheet `undefined`, an alert its cancel answer);
+    query- and fragment-only changes do not close them, and toasts never close. An overlay opened
+    before the first navigation ends (from the root component, an `APP_INITIALIZER` or a
+    shell-level "What's new" sheet) closes when the start URL redirects (`''` to `'today'`). On
+    the web, browser back closes an open form sheet or modal before a route `canDeactivate` guard
+    runs. Fix: pass `closeOnNavigation: false` to an overlay that must stay open across a
+    navigation; open a start-up overlay after the first `NavigationEnd`; persist a draft that
+    must survive browser back.
+20. `/mobile` overlays outside `provideBfShell()` make the page `inert`. Before: opening a sheet,
+    modal, action sheet or alert without the shell left the rest of the page interactive. After:
+    every direct child of `<body>` becomes `inert` while one is open, except the CDK overlay
+    container, the CDK live announcer and `AriaDescriber` containers,
+    `script`/`style`/`template`/`link`, and body children marked `data-bf-overlay-keep`. Fix: mark
+    an element that must stay usable outside the overlay (a body-level chat widget, your own live
+    region) `data-bf-overlay-keep`.
+21. `/mobile` overlays outside `provideBfShell()` register no hardware back handler. Before: the
+    Android back button closed a sheet, modal, action sheet or alert through
+    `BfBackButtonService` alone. After: overlays reach the back button only through the new
+    optional `BF_OVERLAY_HOST` token, which `provideBfShell()` provides; without it, back falls
+    through to the page. Fix: an app that uses `/mobile` overlays without `provideBfShell()` and
+    relies on Android back closing them provides `BF_OVERLAY_HOST` itself.
+22. `provideBfShell()` provides no service itself. Before: it listed `BfNavController`, the
+    platform services and every overlay service, so a lazy route's `providers: [provideBfShell()]`
+    created its own copies in that route's environment injector. After: all of them are
+    `providedIn: 'root'` and resolve from the root injector even under a lazy
+    `provideBfShell()`; only the config, the route reuse strategy and `BF_OVERLAY_HOST` stay in
+    that injector. Fix: put `provideBfShell()` in the application providers (as the setup guide
+    does); nothing changes there.
+23. Deprecated output names. Before: `bf-chip` `(toggled)`, `bf-tab-bar` `(tabChange)` and
+    `(tabReselect)`, `bf-stack-outlet` `(stackChange)`, `(transitionStart)` and `(transitionEnd)`,
+    `bf-refresher` `(refresh)`. After: one naming convention (outputs are past-tense events; a value
+    control has one `changed`) names them `(changed)`, `(changed)` and `(reselected)`,
+    `(stackChanged)`, `(transitionStarted)` and `(transitionEnded)`, and `(refreshRequested)`; the
+    old names stay as deprecated aliases that emit the same payload at the same moment. Fix: rename
+    the binding (`(toggled)="x()"` → `(changed)="x()"`, a subscription `bar.tabChange` →
+    `bar.changed`); the old names keep emitting until 0.4.0, where they are removed.
+24. `bf-tabs` no longer writes the bar's `active`, so `(activeChange)` and `[(active)]` on a bar
+    inside `bf-tabs` no longer fire. Before: `bf-tabs` set the projected `bf-tab-bar`'s `active`
+    to the current tab (and back after a refused navigation), which emitted `activeChange`, and
+    hid the bar with `setHidden()`. After: the bar derives its selection and hiding from the new
+    `BF_TAB_BAR_CONTROLLER` that `bf-tabs` provides; `active` keeps its initial value and
+    `activeChange` stays silent. Fix: listen to `(changed)` instead of `(activeChange)`, and read
+    the shown tab from the bar's `selected()` or `BfTabsComponent.current()`/`tabKey()` instead of
+    `active()`.
+25. `bf-field` keeps its help text while an error shows. Before: the error paragraph replaced the
+    help paragraph, and `describedBy()` and the controls' `aria-describedby` pointed at one of
+    them. After: the help paragraph stays and the error renders under it; `aria-describedby` lists
+    both (`"<id>-help <id>-error"`), and every control that shows an error sets
+    `aria-errormessage="<id>-error"` while `aria-invalid="true"`. An error that appears while a
+    pointer button is held down shows once the press ends. Fix: shorten help text that repeated the
+    error, and update a test or a custom control that expected `describedBy()` to be the error id
+    alone (read the ids with `split(' ')`).
+26. `bf-spinner` draws a CSS ring instead of an SVG, and does not rotate under reduced motion.
+    Before: an inline `<svg>` (`width`/`height` 16/20/24, a faint `<circle>` track and a `<path>`
+    arc) with `animate-spin`, spinning even under `prefers-reduced-motion`. After: a
+    `<span data-bf-spinner-ring aria-hidden="true">` ring with a `currentColor` border, inset by a
+    1 px margin in the same 16/20/24 px box (`motion-safe:animate-spin`), which pulses its
+    opacity under reduced motion (`motion-reduce:animate-pulse`). The `px` member (the box in px)
+    is deprecated. Fix: move CSS or test selectors from `bf-spinner svg` (`circle`, `path`,
+    `[width]`) to `bf-spinner [data-bf-spinner-ring]`, and read the `size` input instead of
+    `px()`, which keeps returning 16/20/24 until it is removed in 0.4.0; colour the spinner
+    through its parent's text colour as before.
+27. `bf-icon` keeps the fills Lucide sets. Before: the renderer dropped `fill`, so icons with
+    filled details lost them (the dots of `Palette`, the points of `ChartScatter`, the hole of
+    `KeyRound`, 10 distinct icons in all). After: those shapes render as solid `currentColor`. Fix:
+    nothing, unless an app drew the missing dots itself or styled `bf-icon circle { fill }`;
+    drop that.
+28. A dismissible sheet has two controls of its own ahead of its content. Before: the sheet's
+    first focusable element was the content's. After: a visually hidden "Close" button
+    (`[data-bf-sheet-close]`) comes first, then, with two or more snap points, the grabber button
+    (`[data-bf-sheet-grabber-button]`, "Expand"/"Collapse"); initial focus never lands on them:
+    it goes to the panel (the default) or, with `autoFocus: 'first-field'`, to the content's first
+    field (see Migration 33). Fix: tests that count a sheet's buttons or walk its Tab order skip
+    the two (`:not([data-bf-sheet-close]):not([data-bf-sheet-grabber-button])`); keep a visible
+    close or cancel control in the content.
+29. The page-sheet `bf-modal` starts below the status bar. Before: the card sat 12 px from the
+    viewport top (`top-3`) and its `bf-header` padded itself by the top safe area. After: the
+    card's top is the safe-area top plus 10 px, and a `bf-header` (or `fullscreen` `bf-content`)
+    inside it adds no safe-area padding (`BfPageContext.safeAreaTop` false). Fix: drop any
+    padding an app added to make up for either; a fullscreen modal is unchanged. A `bf-page`
+    inside a sheet modal's content is not supported (its fresh context brings the band back); the
+    modal docs say so.
+30. Native system bars follow the in-app theme. Before: the shell left the status-bar and
+    navigation-bar style to the app. After: under `provideBfShell()` on native iOS and Android,
+    `SystemBars.setStyle()` follows `BfPlatformService.dark()` at launch and on every theme
+    change (`Default` on Android WebView < 140). Fix: an app that styles the bars itself passes
+    `provideBfShell({ syncSystemBars: false })`.
+31. `bf-header` collapses its large title over the title's rendered height. Before: the collapse
+    ran over a fixed 56 px of scroll (the iOS large title is about 70 px tall, so it finished
+    early). After: the range is the large title block's measured height, at most 200 px (a taller
+    title collapses its whole height over 200 px, so faster than it scrolls), at least 44 px, and
+    56 px until measured; the snap goes to it; a page whose rest range is shorter keeps the title
+    expanded; `data-bf-scrolled` still switches on at full collapse, now at that height. At compact
+    heights (`(max-height: 500px)`) there is no large title and no collapse. Fix: tests or styles
+    that scroll 56 px to collapse the header scroll by the large title's height (`.bf-large` block
+    `offsetHeight`, capped at 200) instead.
+32. `bf-list-item` titles wrap. Before: the title, the title slot and the subtitle each truncated
+    on one line. After: long ones wrap (`wrap-anywhere`), so no text is lost at large text sizes.
+    Fix: add `truncate` to rows that should keep one line (`<bf-list-item truncate>`).
+33. Sheets focus their panel on open. Before: `BfSheetService.open()` focused the content's first
+    focusable element, so a sheet with a text field raised the Android keyboard at once. After:
+    focus goes to the sheet itself (the named `role="dialog"` pane, `tabindex="-1"`), new option
+    `autoFocus: 'panel' | 'first-field'` (default `'panel'`). Fix: pass `autoFocus: 'first-field'`
+    for a sheet that exists to be typed into; tests that expected the first field focused focus it
+    themselves or pass the option.
+34. Android back at a stack root backgrounds the app. Before: when no overlay and no stack could go
+    back, `BfBackButtonService` called `App.exitApp()`, so the next launch started cold. After: it
+    calls `App.minimizeApp()`, and a relaunch resumes warm on the same tab. Fix: pass
+    `provideBfShell({ backAtRoot: 'exit' })` to keep finishing the activity.
+35. Overlays close on a browser's close request. Before: Android back in Chrome or a PWA (no
+    Capacitor) went back in history under an open overlay. After: where `CloseWatcher` exists,
+    each non-passive overlay creates one, and a close request runs its `Escape` path (the
+    overlay closes, or `onEscape` runs); the URL stays. Fix: nothing; an overlay that must survive
+    Android web back passes `dismissOnEscape: false`.
+36. The shown page's `bf-content` is the `main` landmark. Before: the shell rendered no `main`.
+    After: the scroller of the page a `bf-stack-outlet` shows has `role="main"` (not inside
+    `bf-modal`, and not for a `bf-page` outside an outlet), and while it overflows with nothing
+    focusable inside it is a tab stop (`tabindex="0"`). Fix: remove a `main` element or
+    `role="main"` an app put around the outlet or inside its pages, so there is one `main`; tests
+    that count `main` landmarks or Tab stops expect these.
+37. `bfHorizontalScroll` is deprecated. Before: the docs said a horizontal scroller in a stack page
+    needed it. After: a horizontal scroller pans on its own (`touch-action` is not inherited past
+    a scroll container); the directive still sets `touch-action: pan-x pan-y` until 0.4.0. Fix:
+    remove `bfHorizontalScroll` and its import.
+38. `bf-segmented` keeps its labels whole and scrolls sideways when they cannot fit. Before: a
+    label broke anywhere (`wrap-anywhere`), letter by letter at the largest text sizes ("S y st e
+    m" at iOS AX5), and the side padding was rem (it grew with Dynamic Type). After: the side
+    padding is px (12/14/18, the same at the default size), a segment shrinks only to its longest
+    word (`min-w-min`), labels wrap between words, and when the segments still cannot fit (iOS
+    235 % on a phone) the control scrolls sideways inside a new `[data-bf-segmented-scroller]`
+    wrapper around the track. Fix: nothing; tests that read the track as the host's first child
+    look inside the scroller, and styles that set `px-*` on segments use px values.
+39. The iOS edge swipe-back reacts to touch only. Before: any primary pointer that pressed in the
+    left 50 px edge zone and dragged right armed it, so a mouse drag (a desktop page with the mode
+    forced to `ios`) popped the page. After: it arms only for `pointerType` `touch`; a mouse, a
+    text selection from the edge and a pen never pop. Fix: nothing in an app (a desktop user goes
+    back with the header's back button); a test that simulates swipe-back dispatches its
+    `pointerdown`/`pointermove`/`pointerup` with `pointerType: 'touch'` (as
+    `e2e/navigation.spec.ts` does) instead of a mouse drag.
+
+### config
+
+New app-level configuration in `@bitforgehq/ui` (additive). `BfSize` (`'sm' | 'md' | 'lg'`, 32/40/48
+px) is the one control-height scale. `provideBfDefaults({ size, fieldSize, controlSize })` sets
+the default height step of text fields (`fieldSize`) and of actions and choice controls
+(`controlSize`) through the `BF_DEFAULTS` token (library default `BF_DEFAULT_VALUES`, `md` for
+both); `size` sets both, an explicit `fieldSize`/`controlSize` wins. `provideBfLabels(overrides)`
+replaces the library's built-in English strings (`BfLabels`: `loading`, `dismiss`, `tabBar`,
+`tabBadge(count)`, `back`, `ok`, `cancel`, `actions`, `sheet`, `modal`, `refreshing`, `close`,
+`expand`, `collapse`, `sheetPosition`, `dialog`, `notifications`) and the default error text per validator kind (`validation`, a `BfValidationMessages`) through the
+`BF_LABELS` token (defaults `BF_DEFAULT_LABELS`). Both providers return a plain `Provider` that
+merges over the parent injector's value (labels' `validation` key by key; a key set to
+`undefined` keeps the parent's string), so they work in
+`ApplicationConfig.providers` and in a component's `providers` for a sub-tree. A component-level
+`provideBfLabels()` covers the widgets, form controls, `bf-back-button` and `bf-refresher` inside
+it; the overlay services (`ok`, `cancel`, `actions`, `sheet`, `modal`, `close`, `dialog`,
+`notifications`) are root singletons and use it only when the call passes the feature's `injector` (see those entries).
+`close` ("Close") names the `bf-dialog` close button, `dialog` ("Dialog") a dialog with no
+title, heading or `ariaLabel`, and `notifications` ("Notifications") the desktop toast stack's
+region.
+`bfValidationMessage(error, messages)` returns an error's own `message`, else the default for its
+kind (Signal Forms kinds and the Reactive Forms interop kinds, limits read from the error or its
+`context`), else `validation.fallback`.
+
+JSDoc of `defaults.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@default` on the option properties the code applies; `@param` docs. No behaviour change.
+
+JSDoc of `labels.ts` for the API reference: `@summary`/`@since` on the exported symbols; `@default`
+on the option properties the code applies; `@param` docs. No behaviour change.
+
+JSDoc of `size.ts` for the API reference: `@summary`/`@since` on the exported symbols. No behaviour
+change.
+
+JSDoc of `validation-messages.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@default` on the option properties the code applies; `@param` docs. No behaviour change.
+
+`document-reset.ts` (new, internal, exported as `ɵprovideBfDocumentReset` for the `/testing` and
+`/mobile` test providers only; not public API): the document cleanup of `provideBfTesting()` and
+`provideBfShellTesting()`.
+
+New label keys `expand` ("Expand") and `collapse` ("Collapse"), the names of `bf-sheet`'s grabber
+button below and at the top snap point, and `sheetPosition(position, count)` ("Sheet at 1 of 2"),
+the sheet's position, which completes the grabber's name and is announced when it changes; `close` ("Close") now also names `bf-sheet`'s
+screen-reader Close. Like the other overlay labels they come from the injector the sheet is
+opened with.
+
+### theme
+
+**Breaking for custom themes:** new `--color-primary-text` (primary as text: the text button, the
+focused `bf-field` label, the iOS back button), declared with its own value in `@theme`
+(`#2b26ba`) and `.dark` (`#8c88f5`), ≥ 4.5:1 on `bg` and `surface`. An app that overrides
+`--color-primary` must set it too. See Migration 13.
+
+New `--radius-control: 9999px` (utility `rounded-control`): the shape of buttons, icon buttons,
+chips, badges, segmented, the tab bar and its tabs, the action bar, toggles and the alert's dismiss
+button. The default keeps them pills; avatars, radios, the tab count badge and the spinner stay
+`rounded-full` (a circle carries meaning). Additive.
+
+New pressed tokens, light and dark (F-045), each ≥ 4.5:1 with the text it carries:
+`--color-primary-pressed` (`#1f1b8c` / `#b9b7fb`, primary filled), `--color-primary-soft-pressed`
+(`#cfcdf6` / `#34357a`, tonal fills and outline or text presses), `--color-surface-pressed`
+(`#e4e0d6` / `#2e3139`, neutral rows, segments and unselected chips) and `--color-danger-pressed`
+(`#7f2618` / `#f4a497`, danger filled). `tools/theme-contrast.test.ts` checks every
+text-on-pressed pair. A custom theme that overrides `--color-primary` should set the two primary
+pressed tokens too; the docs theme configurator derives them one step past their hover siblings.
+New `--animate-progress-indeterminate` with its `bf-progress-indeterminate` keyframes (the
+indeterminate `bf-progress` stripe).
+
+**Behaviour:** light `--color-text-muted` is `#5b6555` (was `#616b5b`), so muted text keeps 4.5:1
+on `--color-surface-pressed` (a pressed list row's subtitle and trailing notes: 4.63:1; 6.11:1 on
+`surface`).
+
+New `--spacing-card-lg: 1.5rem` (24 px, utility `p-card-lg`): the `bf-card` `lg` padding, beside
+`--spacing-card` (18 px, `md`). Additive (F-063).
+
+### input
+
+New `changed` output: the new text right after each user edit (not for a programmatic write), so
+every value control has one `changed`. New exported `BfInputInputMode` (`BfInputMode | ''`),
+`BfInputEnterKeyHint` (`BfEnterKeyHint | ''`) and `BfInputAutocapitalize`
+(`BfAutocapitalize | ''`), the types of `inputMode`, `enterKeyHint` and `autocapitalize` (were
+the same unions written inline; `''`, the default, leaves the attribute off). `BfInputMode`,
+`BfEnterKeyHint` and `BfAutocapitalize` keep their 0.2.0 members (their `@since` now says 0.2.0).
+
+**Breaking:** the default `size` is `md` (40 px) instead of `lg` (48 px); `size` is a `BfSize`
+(`sm` 32, `md` 40, `lg` 48 px — `sm` is new) and, unset, follows `provideBfDefaults()`'s
+`fieldSize`. See Migration 2. Icon insets and padding are logical (`start-*`/`end-*`, `ps-*`/`pe-*`),
+so `icon-start` and `icon-end` sit at the inline start and end under `dir="rtl"`.
+
+**Behaviour:** an error without a message shows its kind's default text (was a red border only):
+once touched, the field shows the first error's own `message`, else `provideBfLabels()`'s
+`validation` text for its kind (Signal Forms and Reactive interop kinds), else
+`validation.fallback`. `errorMessage` still wins. See Migration 1.
+
+JSDoc of `input.component.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@slot` docs for `icon-start`, `icon-end`; `@param` docs; template handlers and framework hooks
+marked `@internal`, so the reference leaves them out. No behaviour change.
+
+**Behaviour:** the help text stays while an error shows, with the error under it (F-020):
+`aria-describedby` lists both (`"<id>-help <id>-error"`), and `aria-errormessage` points at the
+error paragraph while `aria-invalid="true"`. See Migration 25.
+
+### textarea
+
+New `changed` output: the new text right after each user edit (not for a programmatic write).
+
+**Breaking:** the default `size` is `md` instead of `lg`; `size` is a `BfSize` (`sm` is new) and,
+unset, follows `provideBfDefaults()`'s `fieldSize`. A step sets padding and type, never a height
+(`rows` and `autoResize` do), and the docs now say so. See Migration 2.
+
+**Behaviour:** an error without a message shows its kind's default text (was a red border only):
+once touched, the field shows the first error's own `message`, else `provideBfLabels()`'s
+`validation` text for its kind (Signal Forms and Reactive interop kinds), else
+`validation.fallback`. `errorMessage` still wins. See Migration 1.
+
+JSDoc of `textarea.component.ts` for the API reference: `@param` docs; template handlers and
+framework hooks marked `@internal`, so the reference leaves them out. No behaviour change.
+
+**Behaviour:** the help text stays while an error shows, with the error under it (F-020):
+`aria-describedby` lists both (`"<id>-help <id>-error"`), and `aria-errormessage` points at the
+error paragraph while `aria-invalid="true"`. See Migration 25.
+
+New `maxRows = input<number | undefined>(undefined)` (F-019). With `autoResize` the box keeps
+`field-sizing: content` and now starts at `rows` lines (a `min-block-size` of `rows` times `1lh`
+plus the size's padding and border), so an empty auto-resizing textarea is as tall as a fixed one with the
+same `rows` (it was one line); with `maxRows` it stops at that many lines (`max-block-size`, the same
+way) and scrolls. **Behaviour:** where the browser has no `field-sizing` (`CSS.supports()` says no, read once;
+also on the server) the box keeps its fixed `rows` and the resize
+handle instead of the one-line box it had.
+
+### select
+
+**Breaking:** typed values. `BfSelectComponent<T = string>` is generic over the option value
+(`BfSelectOption<T = string>`), so numbers, ids and objects bind directly; `value` is `T | null`
+and defaults to `null` (was `''`), which shows the placeholder. New `compareWith`
+(`BfCompareWith<T>`, default `Object.is`) matches `value` to an option, and new `changed` emits the
+chosen value (never `null`) after a user change. A string, number or boolean option value is the
+native `<option value>` (`"42"` for `42`); an object option's is its index; a choice maps back by
+position, so duplicate native values still resolve. An option whose value is `''` is now
+selectable instead of reading as "empty"; an option whose value is `null` is unsupported (it reads
+as nothing selected). See Migration 6, 7 and 9.
+
+**Breaking:** the default `size` is `md` (40 px) instead of `lg` (48 px); `size` is a `BfSize`
+(`sm` 32, `md` 40, `lg` 48 px — `sm` is new) and, unset, follows `provideBfDefaults()`'s
+`fieldSize`. See Migration 2. The chevron and the text padding are logical, so the chevron sits at
+the inline end under `dir="rtl"`.
+
+**Behaviour:** an error without a message shows its kind's default text (was a red border only):
+once touched, the field shows the first error's own `message`, else `provideBfLabels()`'s
+`validation` text for its kind (Signal Forms and Reactive interop kinds), else
+`validation.fallback`. `errorMessage` still wins. See Migration 1.
+
+JSDoc of `select.component.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs; template handlers and framework hooks marked `@internal`, so the reference leaves
+them out. No behaviour change.
+
+**Behaviour:** the help text stays while an error shows, with the error under it (F-020):
+`aria-describedby` lists both (`"<id>-help <id>-error"`), and `aria-errormessage` points at the
+error paragraph while `aria-invalid="true"`. See Migration 25.
+
+### checkbox
+
+New `ariaLabelledby` input: the id(s) of the element(s) that name the box when no visible `label`
+is shown (a table's column header and row title), set as the native checkbox's `aria-labelledby`.
+Additive.
+
+**Behaviour:** new `size` (`BfSize`; unset follows `provideBfDefaults()`'s `controlSize`): rows
+are `sm` 32, `md` 40 (default), `lg` 48 px under a fine pointer, and at least 44 px under a coarse
+pointer (was 44 px everywhere); the box is 18 / 22 / 24 px with a matching check mark, and the error
+text's indent is logical (`ps-*`). The row is at least 24 px wide (`min-w-6`), so a label-less box
+with only `ariaLabel` still meets the 24×24 px target size of WCAG 2.5.8 under a fine pointer.
+
+**Behaviour:** an error without a message shows its kind's default text (was a red border only):
+once touched, the field shows the first error's own `message`, else `provideBfLabels()`'s
+`validation` text for its kind (Signal Forms and Reactive interop kinds), else
+`validation.fallback`. `errorMessage` still wins. See Migration 1.
+
+JSDoc of `checkbox.component.ts` for the API reference: `@slot` docs for `default`; `@param` docs;
+template handlers and framework hooks marked `@internal`, so the reference leaves them out. No
+behaviour change.
+
+**Behaviour:** a pressed state (F-045): the box border turns `text` while the row is held down. None while disabled or read-only; under forced colours the system colours win.
+
+**Behaviour:** sets `aria-errormessage` to its error paragraph (`<id>-error`) while
+`aria-invalid="true"`, and an error that appears while a pointer button is held down (a press
+elsewhere that blurred it) shows once the press ends, so the layout never moves under the pointer
+(F-020).
+
+### toggle
+
+New `ariaLabelledby` input: the id of the element that names the switch when no visible `label`
+is shown, set as the native switch's `aria-labelledby`. Additive.
+
+New exported `BfToggleLabelPosition` (`'end' | 'start'`), the type of `labelPosition` (was an
+inline union with the same values).
+
+**Behaviour:** new `size` (`BfSize`; unset follows `provideBfDefaults()`'s `controlSize`): rows
+are `sm` 32, `md` 40 (default), `lg` 48 px under a fine pointer, and at least 44 px under a coarse
+pointer (was 44 px everywhere); the track is 24×40 / 28×48 / 32×56 px with a matching knob, and the knob
+travels to the inline end (mirrored under `dir="rtl"`).
+
+**Behaviour:** an error without a message shows its kind's default text (was a red border only):
+once touched, the field shows the first error's own `message`, else `provideBfLabels()`'s
+`validation` text for its kind (Signal Forms and Reactive interop kinds), else
+`validation.fallback`. `errorMessage` still wins. See Migration 1.
+
+**Behaviour:** the track and the knob use `rounded-control` (`--radius-control`, `9999px` by
+default, so they render as before).
+
+**Behaviour:** the knob carries the state for any configured primary: `on-primary` on the on track
+(was `surface`), `primary-strong` when read-only and on (was `primary`); off and disabled knobs
+stay `surface`.
+
+JSDoc of `toggle.component.ts` for the API reference: `@slot` docs for `default`; `@param` docs;
+template handlers and framework hooks marked `@internal`, so the reference leaves them out. No
+behaviour change.
+
+**Behaviour:** a pressed state (F-045): the track takes a `text` border while the row is held down. None while disabled or read-only; under forced colours the system colours win.
+
+**Behaviour:** sets `aria-errormessage` to its error paragraph (`<id>-error`) while
+`aria-invalid="true"`, and an error that appears while a pointer button is held down (a press
+elsewhere that blurred it) shows once the press ends, so the layout never moves under the pointer
+(F-020).
+
+**Behaviour:** the label wraps (`min-w-0 wrap-anywhere`) instead of overflowing its row at large
+text sizes (F-051): a `labelPosition="start"` label in a `bf-list-item` spilled past the row's
+start edge at the iOS AX sizes.
+
+### radio-group
+
+New exported `BfRadioGroupOrientation` (`'vertical' | 'horizontal'`), the type of `orientation`
+(was an inline union with the same values).
+
+**Breaking:** typed values. `BfRadioGroupComponent<T = string>` is generic over the option value
+(`BfRadioOption<T = string>`); `value` is `T | null` and defaults to `null` (was `''`), with
+nothing checked; `changed` emits `T` (was `string`). New `compareWith` (default `Object.is`)
+matches `value` to an option. A radio's native `value` is its option value for a string, number
+or boolean and its index for an object. See Migration 6, 7 and 9.
+
+**Behaviour:** new `size` (`BfSize`; unset follows `provideBfDefaults()`'s `controlSize`): rows
+are `sm` 32, `md` 40 (default), `lg` 48 px under a fine pointer, and at least 44 px under a coarse
+pointer (was 44 px everywhere); the ring is 18 / 22 / 24 px with a matching dot.
+
+**Behaviour:** an error without a message shows its kind's default text (was a red border only):
+once touched, the field shows the first error's own `message`, else `provideBfLabels()`'s
+`validation` text for its kind (Signal Forms and Reactive interop kinds), else
+`validation.fallback`. `errorMessage` still wins. See Migration 1.
+
+**Behaviour:** the dot is `primary-strong` (was `primary`), so it reaches 3:1 in its `surface`
+ring for any configured primary.
+
+JSDoc of `radio-group.component.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@param` docs; template handlers and framework hooks marked `@internal`, so the reference
+leaves them out. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): an option's ring border turns `text` while the option is held down. None while disabled or read-only; under forced colours the system colours win.
+
+**Behaviour:** sets `aria-errormessage` to its error paragraph (`<id>-error`) while
+`aria-invalid="true"`, and an error that appears while a pointer button is held down (a press
+elsewhere that blurred it) shows once the press ends, so the layout never moves under the pointer
+(F-020).
+
+### segmented
+
+**Breaking:** typed values. `BfSegmentedComponent<T = string>` is generic over the option value
+(`BfSegmentOption<T = string>`); `value` is `T | null` and defaults to `null` (was `''`), with
+nothing checked and the first enabled segment owning the tab stop; `changed` emits `T` (was
+`string`). New `compareWith` (default `Object.is`) matches `value` to an option. `tabStop` is now
+the index of the segment that owns the tab stop (was its value, `-1` when every option is
+disabled), and `select(value)` matches through `compareWith`. See Migration 6, 7 and 10.
+
+**Breaking:** heights follow the shared `BfSize` scale: the track is `sm` 32, `md` 40 (default,
+was 44), `lg` 48 px (new); unset, `size` follows `provideBfDefaults()`'s `controlSize`. The
+segments' 44 px hit extension applies only under a coarse pointer (`pointer-coarse:`). See
+Migration 3.
+
+**Behaviour:** an error without a message shows its kind's default text (was a red border only):
+once touched, the field shows the first error's own `message`, else `provideBfLabels()`'s
+`validation` text for its kind (Signal Forms and Reactive interop kinds), else
+`validation.fallback`. `errorMessage` still wins. See Migration 1.
+
+**Behaviour:** the selected segment carries a 1.5 px inset `primary-strong` outline (≥ 3:1 on
+`surface` and the track), so the selection no longer rests on a fill 1.18:1 from the track; a
+disabled selected segment is outlined in `text-disabled`. The focus ring sits on a 2 px `surface`
+offset (≥ 3:1) instead of on the track (2.79:1). The track and segments use `rounded-control`
+(`--radius-control`).
+
+**Behaviour:** under forced colours the selected segment's outline, focus ring (on a `Canvas`
+offset) and shadow use system colours only (`CanvasText`; no shadow), since it opts out of the
+adjustment; a disabled selected segment's outline is `GrayText` instead of the authored
+`text-disabled`.
+
+JSDoc of `segmented.component.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@param` docs; template handlers and framework hooks marked `@internal`, so the reference
+leaves them out. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): an editable segment takes `surface-pressed` (an unselected one with `text`, which holds 4.5:1 there) while held down. None while disabled or read-only; under forced colours the system colours win.
+
+**Behaviour:** sets `aria-errormessage` to its error paragraph (`<id>-error`) while
+`aria-invalid="true"`, and an error that appears while a pointer button is held down (a press
+elsewhere that blurred it) shows once the press ends, so the layout never moves under the pointer
+(F-020).
+
+**Behaviour:** labels stay whole at every text size. The segments' side padding is px
+(`px-[12px]`/`px-[14px]`/`px-[18px]`, the rem values at the default size) and so is the track's
+(`px-[4px]`, `gap-[2px]`), so Dynamic Type spends the width on the label; a segment shrinks only to
+its longest word (`min-w-min`, was `min-w-0`) and a label wraps between words (was
+`wrap-anywhere`, which broke "System" letter by letter at iOS AX5). When the segments still cannot
+fit, the track grows past the control and a new `[data-bf-segmented-scroller]` wrapper
+(`overflow-x-auto`, padded so the focus ring is not clipped) scrolls it sideways; the host gains
+`max-w-full`. On the demo's Theme control the three segments fit side by side at iOS 200 %
+(WCAG 1.4.4) on a 393 px phone, and scroll at 235 %. See Migration 38.
+
+### number-input
+
+New `changed` output: the new `number | null` right after a user edit that changes the model
+(unreadable text changes nothing and does not emit). `step` is typed with the new exported
+`BfNumberInputStep` (`number | 'any'`) and `inputMode` with `BfNumberInputMode`
+(`'numeric' | 'decimal' | ''`); `enterKeyHint` takes `BfInputEnterKeyHint` (`BfEnterKeyHint | ''`).
+
+New `bf-number-input`: a native `<input type="number">` with the chrome, sizes (`fieldSize`), slots
+and states of `bf-input` that implements `FormValueControl<number | null>` through Angular's
+`transformedValue()`. An empty field is `null`; text the browser cannot read as a number keeps the
+model and raises a `parse` error ("Enter a valid number", `provideBfLabels()`'s
+`validation.parse`), shown once the field is left, with or without a form. `min`, `max` and
+`step` are native attributes that limit stepping, bound by Signal Forms `min()`/`max()` (whose
+errors and default messages are the only range errors; a step mismatch is not reported). Unset,
+`inputMode` is `numeric` for an integer (or no) step and `decimal` otherwise only when `min >= 0`;
+without such a `min` it stays off, so phone keyboards keep a minus key. A form `reset()` replaces
+unreadable text with the number. Works
+with Reactive Forms `FormControl<number | null>` through the Signal Forms interop. See Migration 8.
+It ships in its own entry point, `import { BfNumberInputComponent } from
+'@bitforgehq/ui/number-input'`, because it parses with Angular's `transformedValue()` and so loads
+Angular Forms (`@angular/forms`, a required peer); a parse error reaches the bound Signal Forms
+field (blocking `submit()`) or Reactive `FormControl` (invalid) with no setup. The widgets entry
+`@bitforgehq/ui` loads no `@angular/forms` code at runtime, so an app without forms ships none of
+it.
+
+JSDoc of `number-input.component.ts` for the API reference: `@slot` docs for `icon-start`,
+`icon-end`; `@param` docs; template handlers and framework hooks marked `@internal`, so the
+reference leaves them out. No behaviour change.
+
+**Behaviour:** the help text stays while an error shows, with the error under it (F-020):
+`aria-describedby` lists both (`"<id>-help <id>-error"`), and `aria-errormessage` points at the
+error paragraph while `aria-invalid="true"`. See Migration 25.
+
+### spinner
+
+**Behaviour:** `label` defaults to `''` and falls back to `provideBfLabels()`'s `loading`
+("Loading"); the rendered English default is unchanged.
+
+JSDoc of `spinner.component.ts` for the API reference: `@summary`/`@since` on the exported symbols.
+No behaviour change.
+
+**Behaviour:** a pure-CSS ring with no inline SVG (F-066): a `rounded-full` ring sized
+`size-3.5`, `size-4.5` or `size-5.5` (14/18/22 px, close to the old SVG's 14/17.5/21 px outer
+edge) and inset by `m-px`, so the box stays 16/20/24 px, with a `border-2`, `border-2` or
+`border-[3px]` border, `border-current/25` for the track and `border-t-current` for the arc; the
+arc ends are square. It rotates with `motion-safe:animate-spin`; under `prefers-reduced-motion` it no longer
+rotates at all but pulses its opacity (`motion-reduce:animate-pulse`, F-064). Under forced colours
+the track is `GrayText` and the arc `CanvasText`. The `decorative`, `label` and status semantics
+are unchanged.
+
+**Deprecated:** `px` (the box in px, 16/20/24): use the `size` input; removed in 0.4.0. See
+Migration 26.
+
+### alert
+
+**Behaviour:** `dismissLabel` defaults to `''` and falls back to `provideBfLabels()`'s `dismiss`
+("Dismiss"); the rendered English default is unchanged.
+
+**Behaviour:** the dismiss button uses `rounded-control` (`--radius-control`).
+
+**Behaviour:** the role no longer follows the variant: the region is `role="status"` (polite)
+unless the new `urgent` input makes it `role="alert"` (assertive), in any variant. Migration: add
+`urgent` to danger alerts that must interrupt (see Migration 15).
+
+New `announce` input: the live region renders empty and fills on the next frame, so an alert
+inserted after an action is announced (APG alert, WCAG 4.1.3); it is read once, at creation.
+
+**Behaviour:** with a `title` the dismiss button is named `<dismissLabel>: <title>` ("Dismiss:
+Sync failed"), so two dismissible alerts have distinct buttons (see Migration 16). The docs show
+moving focus in the `dismissed` handler; the widget never moves it.
+
+JSDoc of `alert.component.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@slot` docs for `icon`, `default`, `actions`. No behaviour change.
+
+### tab-bar
+
+**Deprecated:** `tabChange` → `changed` and `tabReselect` → `reselected`. The new outputs emit the
+tab id at the same moments; the old names still emit the same id right after them until 0.4.0 (see
+Migration 23). `bf-tabs` listens to the new names.
+
+**Breaking:** (ARIA contract) with the new `BF_TAB_LINKS` token provided by a router-aware parent
+(`bf-tabs`) in the same template, the bar renders a `nav` holding a plain group of links instead
+of a `tablist`: no roving tab stop and no arrow-key, Home or End handling. The token is looked up
+with `host: true`, so a bar inside a routed page under `bf-tabs` stays a standalone `tablist`.
+`BfTabBarHost` gains `linkMode`, `linkHref(id)` and `linkIsRoot(id)`. See Migration 11 and 14.
+
+**Behaviour:** `label` defaults to `''` and falls back to `provideBfLabels()`'s `tabBar` ("Main");
+the rendered English default is unchanged.
+
+**Behaviour:** shaped with the new `rounded-control` (`--radius-control`, `9999px` by default, so it renders as before); override the token to move off the pill.
+
+JSDoc of `tab-bar.component.ts` for the API reference: `@slot` docs for `default`; `@param` docs;
+template handlers and framework hooks marked `@internal`, so the reference leaves them out. No
+behaviour change.
+
+JSDoc of `tab-bar.token.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+**Behaviour:** new `BF_TAB_BAR_CONTROLLER` token and `BfTabBarController` interface (additive,
+extends `BfTabLinks`): a parent that projects the bar and drives it provides `current()`,
+`hidden()`, `hideTransition()`, `select(id)` and `reselect(id)`. With a controller (looked up with
+`host: true`, like `BF_TAB_LINKS`) the bar shows `current()` as its selection (`''` while it is
+`null`), hides while `hidden()` is true with the transition `hideTransition()` gives, and hands a
+user selection to `select(id)`/`reselect(id)`, still emitting `changed` or `reselected` (and the
+deprecated `tabChange`/`tabReselect` right after them); it never writes `active` then. New
+`selected` on the bar: the id shown as selected, `active` without a controller; `BfTabBarHost`
+gains it as an optional member (`bf-tab` falls back to `active`), so a custom `BF_TAB_BAR`
+provider keeps working. Inside `bf-tabs` `activeChange` no longer emits. Without a controller
+nothing changes; `setHidden()` stays for other parents. See Migration 24.
+
+**Behaviour:** large text and compact heights (F-051, F-054): the tabs' row has a minimum height
+in px (`min-h-[64px]`, was the rem `h-16`) and grows with a label wrapped to two lines, which
+Android's font scale (a text zoom that does not scale the bar) needs at 2.0. Being px, the bar no
+longer grows with iOS Dynamic Type itself, as UITabBar does not: at AX5 it was 154.7 px (the rem
+`h-16` at a 235 % root) and is now 98 px (a capsule and two capped label lines). At compact
+heights (`(max-height: 500px)`, phone landscape) it is at least 48 px (`min-h-[48px]`). The bottom
+offset stays.
+
+### tab
+
+**Breaking:** (ARIA contract) inside `bf-tabs` a tab is `<a href>` with `aria-current` while
+active: `page` on the tab's root page, `true` on a child page of it (no `role="tab"` or
+`aria-selected`); a disabled one is `<a role="link" aria-disabled="true">` without `href`. A plain
+primary click selects the tab through the bar (default prevented); Ctrl/Cmd, Shift, Alt and middle
+clicks open the link in a new tab or window. The link's underline is removed with an important
+utility (`no-underline!`), so an unlayered global link rule cannot underline it. See Migration 11.
+
+**Behaviour:** a badged tab is named by `aria-label` = label, comma, announcement ("Projects, 3
+new"; was "Projects , 3 new", with a pause, from a visually hidden span that browsers joined with a
+space), in both forms; the `sr-only` announcement span is gone. Without a badge the visible label
+is the name, as before.
+
+**Behaviour:** the badge is placed with a logical inset (`-end-2`), so it sits at the icon's
+inline end under `dir="rtl"`.
+
+**Behaviour:** a numeric `badge` is announced through `provideBfLabels()`'s `tabBadge(count)`
+(`"{n} new"` by default, now translatable); a string badge is announced as given.
+
+**Behaviour:** the active capsule carries a 1.5 px inset `primary-strong` outline (≥ 3:1 on its
+`primary-soft` fill and the bar), so the active tab no longer rests on a fill 1.23:1 from the bar;
+a disabled active capsule is outlined in `text-disabled`. The tab and its capsule use
+`rounded-control` (`--radius-control`); the count badge stays a circle.
+
+**Docs:** `bf-tab` has a page of its own (`tab-bar/tab.docs.md`): its id, its badges (moved from
+the `bf-tab-bar` page) and a disabled tab, with the tab's own theming and accessibility; the
+`bf-tab-bar` page links to it.
+
+JSDoc of `tab.component.ts` for the API reference: `@slot` docs for `default`; template handlers and
+framework hooks marked `@internal`, so the reference leaves them out. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): the capsule of an enabled tab takes `primary-soft-pressed` (an inactive one with the `text` icon) while the tab is held down. None while disabled; under forced colours the system colours win.
+
+**Behaviour:** large text (F-051): the label's size and line height are capped at 200 %
+(`min(var(--text-nano), 22px)`, `min(var(--text-nano--line-height), 28px)`, in px because iOS
+Dynamic Type scales the root); it still wraps to at most two lines and never clips vertically. The
+tab has 4 px of vertical padding, so a grown tab keeps off the bar's edge. The capsule (30 × 52
+px), the badge (18 px, its count capped at 13 px), the padding and the gaps are px, so they keep
+their size at every text size. The label hyphenates a long word where the engine has
+hyphenation for the page's `lang` (`hyphens-auto wrap-break-word`, was `wrap-anywhere`), and
+otherwise still breaks it rather than overflowing (WKWebView on the iOS 18 simulator does not
+hyphenate "Projects", so it still reads "Projec/ts" at AX5). At
+compact heights (`(max-height: 500px)`, F-054) the icon and the label sit side by side
+(`flex-row gap-[6px]`).
+
+### back-button
+
+**Behaviour:** `label` defaults to `''` and falls back to `provideBfLabels()`'s `back` ("Back"),
+both as the iOS text and as the Material button's name.
+
+**Behaviour:** the iOS label and chevron use `primary-text` (was `primary`); hover stays
+`primary-strong`.
+
+JSDoc of `back-button.component.ts` for the API reference: docs for the undocumented members and
+methods. No behaviour change.
+
+JSDoc of `back-button.service.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@param` docs. No behaviour change.
+
+**Behaviour:** large text (F-051): the host (`min-w-0 shrink`) and the iOS button (`shrink`, no
+longer `shrink-0`) may shrink inside the header's `start` slot, down to the 44 px hit area: the
+text truncates and then disappears before the chevron, as UIKit drops the back title when space is
+short. The text stays the button's name. It carries `data-bf-back-text`, the part `bf-header`'s iOS
+start-slot cap lets give way.
+
+### alert-dialog
+
+New exported `BfAlertDialogButtonRole` (`'cancel' | 'destructive'`), the type of
+`BfAlertDialogButton.role` (was an inline union with the same values).
+
+**Type:** `open()` returns `Promise<string | undefined>` (was `Promise<string>`): a navigation to
+another URL path closes the alert and resolves the cancel button's answer, else `undefined`. New
+`closeOnNavigation` option (default true). Migration: handle `undefined` like cancel (see
+Migration 18).
+
+**Behaviour:** the default button (no `buttons`) is labelled with `provideBfLabels()`'s `ok`
+("OK").
+
+New `injector` option: labels resolve from it per call (default the root injector) and it becomes
+the parent of the content's injector, so a feature-level `provideBfLabels()` and the feature's
+other providers reach the dialog.
+
+`BfAlertDialogButton` gains `id?: string`; `open()` resolves the tapped button's `id ?? label`,
+and `Escape` and the hardware back button the cancel button's. Buttons render with
+`track $index`, so two buttons with the same label both render.
+
+**Behaviour:** focus starts on the `cancel`-role button, else the first button (APG alert dialog),
+even when a destructive button comes first (see Migration 17).
+
+JSDoc of `alert-dialog.service.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@default` on the option properties the code applies; `@param` docs. No behaviour change.
+
+The docs say that Android back in a browser with `CloseWatcher` answers with the cancel button,
+and that an alert without one swallows it; see `### overlay core` and Migration 35.
+
+### action-sheet
+
+New exported `BfActionSheetActionRole` (`'destructive' | 'cancel'`), the type of
+`BfActionSheetAction.role` (was an inline union with the same values).
+
+**Behaviour:** a navigation to another URL path closes it, resolving `undefined`; new
+`closeOnNavigation` option (default true). Migration: pass `closeOnNavigation: false` to keep it
+open (see Migration 19).
+
+**Behaviour:** the synthesized cancel button is labelled with `provideBfLabels()`'s `cancel`
+("Cancel"), and a sheet without `title` is named by its `actions` label ("Actions").
+
+New `injector` option: labels resolve from it per call (default the root injector) and it becomes
+the parent of the content's injector, so a feature-level `provideBfLabels()` and the feature's
+other providers reach the action sheet.
+
+`BfActionSheetAction` gains `id?: string`; `open()` resolves the tapped row's `id ?? label` (the
+cancel action still resolves `undefined`). Rows render with `track $index`, so two rows with the
+same label both render.
+
+**Behaviour:** focus starts on the cancel button, not the first row (see Migration 17).
+
+JSDoc of `action-sheet.component.ts` for the API reference: `@summary`/`@since` on the exported
+symbols. No behaviour change.
+
+JSDoc of `action-sheet.service.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@default` on the option properties the code applies; `@param` docs. No behaviour change.
+
+The docs say that Android back in a browser with `CloseWatcher` closes the action sheet, resolving
+`undefined`; see `### overlay core` and Migration 35.
+
+### sheet
+
+**Behaviour:** a navigation to another URL path (a push, a pop, a tab switch) closes it with no
+result, also a `dismissible: false` one; new `closeOnNavigation` option (default true). Migration:
+pass `closeOnNavigation: false` to keep it open (see Migration 19).
+
+**Behaviour:** named by the first heading: without `ariaLabel`, the panel is named by the first
+heading in its content that is not `aria-hidden` (`h1`–`h6` or `role="heading"`, given an id
+`bf-overlay-title-<n>` when it has none) through `aria-labelledby`, once the content has rendered;
+without a heading, by `provideBfLabels()`'s `sheet` ("Sheet"). An explicit `ariaLabel` always wins.
+
+New `injector` option: labels resolve from it per call (default the root injector) and it becomes
+the parent of the content's injector, so a feature-level `provideBfLabels()` and the feature's
+other providers reach the sheet.
+
+A heading that renders after the overlay opened (behind `@if`, a `resource()`) still names it: the
+panel is watched until its first heading appears.
+
+JSDoc of `sheet-ref.ts` for the API reference: `@summary`/`@since` on the exported symbols; `@param`
+docs. No behaviour change.
+
+JSDoc of `sheet.service.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@default` on the option properties the code applies; `@param` docs. No behaviour change.
+
+**Behaviour:** the keyboard lift and cap (`translate`, `padding-bottom`, `max-height`,
+`transition`) are written in the render phase (`afterRenderEffect({ write })`) instead of an
+`effect`; internal timing only, no API change.
+
+With two or more snap points the grabber is a button (`[data-bf-sheet-grabber-button]`), so the
+sheet can be resized without dragging (WCAG 2.5.7): a tap, click, `Enter` or `Space` moves it one
+point up, and from the top point back to the lowest; `ArrowUp`/`ArrowDown` step one point (never
+past the ends, never dismissing), `Home`/`End` jump to the lowest/top point, all through
+`snapTo()` (instant under reduced motion). It is named after the next press and the position
+("Expand, Sheet at 1 of 2": `expand` below the top point, `collapse` at it, then
+`sheetPosition`); focus stays on it, and every settle on another point (button, key, drag or
+`snapTo()`) announces `sheetPosition` politely through CDK `LiveAnnouncer`. A drag that starts on
+it still drags (a pointer click within the 6 px slop is the press; a keyboard or screen-reader
+click, `detail` 0, is never swallowed). Alt, Ctrl and Meta combinations are left alone. It is
+the full-width 24 px handle row, extended downward to 44 px under a coarse pointer, so a tap just
+above the sheet reaches the backdrop. With one snap point the grabber stays decorative
+(`aria-hidden`) and nothing is announced.
+
+**Behaviour:** every dismissible sheet renders a visually hidden "Close" button
+(`provideBfLabels()`'s `close`) as its first element, shown as a pill at the top-end corner when
+focused; activating it closes the sheet. VoiceOver reaches it by swiping, since WKWebView does not
+deliver the two-finger scrub to web content. A `dismissible: false` sheet has none. The Close and
+the grabber button never take the initial focus. Keep a visible close or cancel control in the
+content (Migration 28).
+
+**Behaviour:** a sheet opens with focus on its panel (the `role="dialog"` pane, named and
+`tabindex="-1"`), so a screen reader lands inside it and no soft keyboard comes up on open. New
+option `autoFocus?: BfSheetAutoFocus` (`'panel' | 'first-field'`, default `'panel'`; new exported
+type), mapped to the overlay core's `autoFocus` (`'first-field'` → `'first-tabbable'`, which
+honours `[autofocus]`/`[cdkFocusInitial]` and skips the sheet's Close and grabber). Action sheets
+and modals are unchanged. See Migration 33.
+
+`bf-sheet` provides a fresh `BfPageContext` (`mainLandmark` false) to its content: a `bf-content`
+in a sheet opened with a page's injector no longer resolves the page's context, so it is no second
+`main` and does not replace the page's registered scroller.
+
+Android back in a browser (no Capacitor) closes an open sheet first where `CloseWatcher` exists
+(see `### overlay core`, Migration 35).
+
+### modal
+
+**Behaviour:** a navigation to another URL path closes it with no result, also a
+`dismissible: false` one; new `closeOnNavigation` option (default true). Migration: pass
+`closeOnNavigation: false` to keep it open (see Migration 19).
+
+**Behaviour:** named by the first heading: without `ariaLabel`, the panel is named by the first
+heading in its content that is not `aria-hidden` (such as the `bf-header` title) through
+`aria-labelledby`, once the content has rendered; without a heading, by `provideBfLabels()`'s
+`modal` ("Modal"). An explicit `ariaLabel` always wins.
+
+New `injector` option: labels resolve from it per call (default the root injector) and it becomes
+the parent of the content's injector, so a feature-level `provideBfLabels()` and the feature's
+other providers reach the modal.
+
+A heading that renders after the overlay opened (behind `@if`, a `resource()`) still names it: the
+panel is watched until its first heading appears.
+
+JSDoc of `modal.component.ts` for the API reference: `@summary`/`@since` on the exported symbols. No
+behaviour change.
+
+JSDoc of `modal.service.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@default` on the option properties the code applies; `@param` docs. No behaviour change.
+
+**Behaviour:** the page-sheet card (`presentation: 'sheet'`) starts 10 px below the top safe
+area (`top-[calc(var(--spacing-safe-top)+10px)]`, UIKit's page-sheet inset; was `top-3`), so it
+sits below the status bar and the parent page peeks above it, and it sets its `BfPageContext`'s
+`safeAreaTop` to false, so its content's header adds no second status-bar band (Migration 29). A
+fullscreen modal is unchanged.
+
+**Behaviour:** its content is no `main` landmark: `bf-modal` sets its `BfPageContext.mainLandmark`
+to false (content in a dialog is not the page's main content; the page behind stays `main`, inert
+while the modal is open). Android web back closes it where `CloseWatcher` exists (Migration 35).
+
+### refresher
+
+**Deprecated:** `refresh` → `refreshRequested`, typed with the new exported
+`BfRefresherRefreshEvent` (`{ complete: () => void }`, was an inline object type). Both outputs
+emit the same event object for each completed pull until `refresh` is removed in 0.4.0 (see
+Migration 23).
+
+**Behaviour:** the status region announces `provideBfLabels()`'s `refreshing` ("Refreshing").
+
+### button
+
+**Behaviour:** `size` is a `BfSize` and, unset, follows `provideBfDefaults()`'s `controlSize`
+(`md` by default, as before). The 44 px hit extension of `sm` and `md` applies only under a coarse
+pointer (`pointer-coarse:`), so dense desktop rows do not overlap; the `outline` variant's
+extension adds its 1.5 px border back and reaches 44 px (was 42). See Migration 5 for
+`BfButtonSize`.
+
+New link form: the selector is `bf-button, a[bfButton]`. `<a bfButton routerLink="…">` (or
+`href`) puts the variant, size and full-width classes on your own `<a>` (plus an important
+`no-underline!`, so an unlayered global link rule cannot underline it; no
+inner `<button>`), so a navigation action is a real link that looks like the button: exposed as
+`link`, activated with Enter (not Space), opened in a new tab with Ctrl/Cmd-click, the URL
+visible. `clicked` still emits; `type`, `disabled` and `loading` do not apply (a link is never
+disabled; render a disabled `bf-button` instead). Additive. The host of `bf-button` now binds its
+classes through `[class]`; a consumer's own `class` on the element is kept.
+
+**Behaviour:** the `text` variant is coloured `primary-text` (new token, ≥ 4.5:1 on `bg` and
+`surface`; was `primary`), still `primary-strong` on hover. The `danger` variant's hover label is
+`danger-soft` on `danger` (was `on-primary`, which a custom light primary can turn black, 2.7:1 on
+the default danger).
+
+**Behaviour:** shaped with the new `rounded-control` (`--radius-control`, `9999px` by default, so
+it renders as before); override the token to move off the pill.
+
+JSDoc of `button.component.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@slot` docs for `icon-start`, `default`, `icon-end`; template handlers and framework hooks marked
+`@internal`, so the reference leaves them out. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): `primary` takes `primary-pressed`, `tonal`, `outline` and `text` `primary-soft-pressed` (the `text` label turns `primary-strong`), `danger` `danger-pressed` with `danger-soft` text, while the button is held down (`enabled:active:`, and `active:` on `a[bfButton]`). None while disabled or loading; under forced colours the system colours win.
+
+### icon-button
+
+**Behaviour:** `size` is a `BfSize` and, unset, follows `provideBfDefaults()`'s `controlSize`. The
+44 px hit extension applies only under a coarse pointer, and the `outline` variant's compensates its
+1.5 px border.
+
+**Behaviour:** shaped with the new `rounded-control` (`--radius-control`, `9999px` by default, so it renders as before); override the token to move off the pill.
+
+JSDoc of `icon-button.component.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@slot` docs for `default`; template handlers and framework hooks marked `@internal`, so
+the reference leaves them out. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): `primary` takes `primary-pressed`, `tonal`, `outline` and `text` `primary-soft-pressed` (the `text` icon turns `text`) while the button is held down. None while disabled; under forced colours the system colours win.
+
+### chip-group
+
+New `bf-chip-group` (`BfChipGroupComponent<T>`, `BfChipGroupMode` `'single' | 'multiple'`, root
+entry, F-038): a named row of `bf-chip`s. `single` (default): the host is `role="radiogroup"`
+named by `label` or `ariaLabelledby`, the chips are `role="radio"` with `aria-checked`, one roving
+tab stop (the selected chip, else the first enabled), and the arrow keys (wrapping, skipping
+disabled chips), `Home` and `End` move focus and the selection, as in `bf-segmented`; `Space` and
+`Enter` select, there is no deselect. `[(value)]` holds the selected chip's `value` (`null` for
+none) and `(changed)` emits it after a user change. `multiple`: the host is `role="group"` and the
+chips stay independent `aria-pressed` toggles with their own `[(selected)]`. `disabled` disables
+every chip. It is not a Signal Forms control; for a form field use `bf-segmented` or
+`bf-radio-group`.
+
+A chip without a `value` inside a `single` group never matches the group's value and cannot be
+selected, so chips that all leave it unset never read as selected together; give every chip a
+`value`.
+
+### chip
+
+**Deprecated:** `toggled` → `changed`. The new `changed` output emits the new `selected` state
+after a user toggle; `toggled` still emits the same value right after it until 0.4.0 (see
+Migration 23).
+
+**Breaking:** new `size` (`BfSize`; unset follows `provideBfDefaults()`'s `controlSize`): `sm` 32,
+`md` 40 (default, was a fixed 36), `lg` 48 px. The hit extension applies only under a coarse
+pointer and compensates the chip's 1.5 px border, so it reaches 44 px (was 42). See Migration 4.
+
+**Behaviour:** shaped with the new `rounded-control` (`--radius-control`, `9999px` by default, so it renders as before); override the token to move off the pill.
+
+JSDoc of `chip.component.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@slot` docs for `icon-start`, `default`; template handlers and framework hooks marked `@internal`,
+so the reference leaves them out. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): unselected chips take `surface-pressed`, selected `tonal` ones `primary-soft-pressed`, selected `ink` ones `text-secondary` while held down. None while disabled; under forced colours the system colours win.
+
+New `value = input<unknown>(undefined)`: what the chip stands for inside a `bf-chip-group`
+(compared with `Object.is`); unused outside one. Inside a `single` group the chip renders
+`role="radio"` with `aria-checked` (no `aria-pressed`), takes the group's roving `tabindex`, is
+disabled with the group, and its own `selected` is ignored: the group's `value` decides. A
+single-choice row without a group keeps working, and `deselectable` keeps its behaviour; the docs'
+single-choice section now points to the group. New `focus(options?)` focuses the chip's button.
+
+### list-item
+
+**Behaviour:** logical properties: text aligns to the inline start and the chevron sits at the
+inline end, pointing there (mirrored under `dir="rtl"`).
+
+New navigation rows: a `title` content slot (`bfSlot="title"`), rendered in the title position
+and type, takes an `<a bfAction routerLink="…">` (the new `BfActionDirective`), whose `::after`
+stretches over the row. The row stays a `listitem`, the link's name is the title, and the row
+shows the pointer, the `surface-muted` hover and the focus ring (on keyboard focus) while it holds
+its own `bfAction`; the row box is `relative`. Text under the stretched link is not selectable.
+
+**Behaviour:** the trailing slot is wrapped in a `relative z-1` flex box (`gap-3`, as between the
+row's items, hidden when empty), so a toggle or button there stays clickable above a stretched
+link. `interactive` stays for rows that act on the page.
+
+**Docs:** `bf-list-item` has a page of its own (`list/list-item.docs.md`): the row's slots, the
+navigation rows and the action and settings rows (moved from the `bf-list` page), with the row's own
+theming and accessibility. The `bf-list` page keeps the container: a list of rows and the plain
+list, and links to the row page.
+
+JSDoc of `list-item.component.ts` for the API reference: `@slot` docs for `leading`, `title`,
+`default`, `trailing`. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): an `interactive` row takes `surface-pressed` while held down, and a row holding a `bfAction` while its action is (`has-[[data-bf-action]:active]`). None while disabled; under forced colours the system colours win.
+
+While a row is pressed its chevron turns `text-muted` (`text-subtle` misses 3:1 on
+`surface-pressed`).
+
+**Behaviour:** the title, the title slot and the subtitle wrap by default (`wrap-anywhere`, no
+clamp) instead of truncating, so no text is lost at large text sizes (F-051). New
+`truncate = input(false, { transform: booleanAttribute })` restores one line with an ellipsis for
+each. See Migration 32. The mobile demo's Inbox rows use `truncate` (a mail list); its Today,
+project and Me rows wrap.
+
+### card
+
+**Behaviour:** logical properties: content aligns to the inline start (`text-start`).
+
+**Deprecated:** `interactive` and `clicked` (removed in 1.0.0): a card-sized `<button>` hid the
+heading and could not hold other controls. Use the new stretched-link pattern instead: a
+`bfAction` link or button (`BfActionDirective`, new in `@bitforgehq/ui`) in the card's heading
+stretches its hit area over the card, which is now always `relative` and shows the pointer, the
+`shadow-floating` hover and the focus ring (on keyboard focus) while it holds its own `bfAction`
+(it registers with the nearest card or row, so a card holding navigation rows is not lit by them);
+secondary controls take `class="relative z-1"`. Text under the stretched area is not selectable.
+See Migration 12.
+
+JSDoc of `card.component.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@slot` docs for `header`, `default`, `footer`. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): a card holding a `bfAction` drops from `shadow-floating` back to `shadow-raised` while its action is held down (`has-[[data-bf-action]:active]`), the deprecated `interactive` card while it is. None while disabled; under forced colours the system colours win.
+
+`padding="lg"` is `p-card-lg` (the new `--spacing-card-lg` token, 24 px) instead of `p-6`
+(F-063); the rendered padding is unchanged, and an app can now retune it in its `@theme`.
+
+### action-bar
+
+**Behaviour:** logical properties: the pill's and the label's padding use `ps-*`/`pe-*`, so the
+label leads under `dir="rtl"`.
+
+**Behaviour:** shaped with the new `rounded-control` (`--radius-control`, `9999px` by default, so it renders as before); override the token to move off the pill.
+
+JSDoc of `action-bar.component.ts` for the API reference: `@slot` docs for `default`. No behaviour
+change.
+
+### overlay core
+
+New exported `BfOverlayRole` (`'dialog' | 'alertdialog' | 'status'`) and `BfOverlayAutoFocus`
+(`'first-tabbable' | 'panel'`), the types of `BfOverlayOptions.role` and `autoFocus` (were inline
+unions with the same values).
+
+**Behaviour:** overlays close when the URL path changes. New `closeOnNavigation` option of
+`BfOverlayService.open()` (default true, false for passive overlays) and `onNavigation` (runs
+instead of `close()`, e.g. to answer with a cancel id). The core listens through
+`Location.onUrlChange()` from `@angular/common` (router navigations, `popstate` and `hashchange`),
+so `/overlay` still needs no `@angular/router`; the path is compared without its query and
+fragment, so query- or fragment-only changes never close (a matrix-parameter change is a path
+change and closes; a `history.pushState()` outside Angular's `Location` is not seen). Migration:
+pass `closeOnNavigation: false` to an overlay that must survive a navigation. The internal path
+watcher's unregister function is idempotent.
+
+New `providers` option of `BfOverlayService.open()`: extra providers of the content's injector,
+built with the new overlay's ref (`BfDialogService` provides its typed `BfDialogRef` this way).
+New `autoFocus` option: `'first-tabbable'` (default, as before) or `'panel'`, which focuses the
+pane itself (for long content). Additive.
+
+**Behaviour:** initial focus on an `[autofocus]`/`[cdkFocusInitial]` element: a focusable mark
+(a control, or any element with a `tabindex`, including `tabindex="-1"`, e.g. a region to start
+reading at) takes focus itself, as before; a mark that is not focusable (e.g. a `bf-button` host)
+now forwards focus to the first tabbable element inside it instead of nowhere; a mark whose
+controls are all disabled is skipped for the first tabbable element of the panel, else the panel
+(before: focus stayed behind the overlay). Migration: none.
+
+**Behaviour:** on close, when the element that opened the overlay is gone (a deleted row, content
+re-rendered under a nested overlay), focus moves to the topmost overlay still open instead of
+the page behind it; with none left it stays on the body. Migration: after a destructive action
+that removes the opener, move focus yourself (the next row, the list heading).
+
+**Behaviour:** an `ariaLabelledBy` whose id names no element inside the rendered panel is removed
+when `ariaLabel` is unset, so a panel never points at nothing. Migration: render the heading in
+the overlay content (or pass `ariaLabel`).
+
+**Behaviour:** the animation helpers (`fadeIn`, `fadeOut`, `fadeUp`, `fadeDown`, `scaleIn`,
+`slideUp`, `slideDown`) and the backdrop fade work without the Web Animations API (jsdom in a
+consumer's Vitest or Jest run): they apply the end state (an exit's last frame; an enter leaves
+the element as it is) and return an already finished `Animation`. Migration: consumer tests can
+drop their `Element.prototype.animate` stand-in.
+
+**Behaviour:** `Escape` from inside another CDK overlay pane (a CDK menu, such as `bf-menu`,
+opened from a dialog) no longer closes the overlay underneath: the menu closes and the dialog
+stays open. Migration: none.
+
+**Behaviour:** pressing the backdrop of a modal overlay no longer moves focus to `<body>` (out of
+the dialog, alert or sheet): its `mousedown` is cancelled, so focus stays where it was; a
+dismissing backdrop still closes on its click. Migration: none.
+
+The heading helper that names a `/mobile` sheet or modal by its content's first heading moved into
+the core (internal, `ɵ`-prefixed export; `/mobile` imports it by package name).
+
+New `injector` option of `BfOverlayService.open()`: the parent of the content's injector (default
+the root injector), so overlay content resolves the opener's providers. Additive.
+
+**Behaviour:** outside a shell the page behind a modal overlay is `inert`. When no page root is
+registered (no `bf-stack-outlet`, e.g. a desktop page), `BfOverlayStack` makes every direct child
+of `<body>` `inert` while a non-passive overlay is open, except the CDK overlay container, the CDK
+live announcer and `AriaDescriber` containers, `script`/`style`/`template`/`link` and direct body
+children marked `data-bf-overlay-keep`; an element that was already `inert` keeps it, and
+destroying the app (its injector) with an overlay open removes every `inert` the stack set. Inside
+the shell (registered roots) nothing changes. Migration: mark an element outside the overlay that
+must stay usable (your own live region, a chat widget) `data-bf-overlay-keep`; it works only on a
+direct child of `<body>`, since nothing inside an inert element (such as your app root) can opt
+out. A custom `OverlayContainer` placed inside the app root keeps that body child active, so the
+page is not isolated.
+
+**Behaviour:** the hardware back button reaches overlays through the new optional
+`BF_OVERLAY_HOST` token (`registerBack()`, `documentScrolls`), which `provideBfShell()` provides
+(back handlers on `BfBackButtonService`, no scroll lock). Without `provideBfShell()` overlays
+register no hardware back handler, and the scroll lock follows `documentScrolls` instead of
+`BF_SHELL_CONFIG`. Migration: an app that used `/mobile` overlays without `provideBfShell()` and
+relied on Android back closing them provides `BF_OVERLAY_HOST` itself.
+
+JSDoc of `motion.ts` for the API reference: `@summary`/`@since` on the exported symbols; `@param`
+docs. No behaviour change.
+
+JSDoc of `overlay-animations.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+JSDoc of `overlay-host.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+JSDoc of `overlay-ref.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+JSDoc of `overlay-stack.service.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@default` on the option properties the code applies; `@param` docs. No behaviour change.
+
+JSDoc of `overlay.service.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@default` on the option properties the code applies; `@param` docs. No behaviour change.
+
+`BfOverlayStack` no longer injects the CDK `OverlayContainer`: outside a shell it keeps every body
+child that holds a `.cdk-overlay-container` active, found by that class, so `bf-stack-outlet` and
+`bf-tabs`, which register their hosts as page roots, pin no CDK overlay code. No behaviour change:
+the library's overlays and a consumer's own CDK overlay pushed directly stay usable, and a second
+container (a custom `OverlayContainer` beside the default) stays active too.
+
+Initial focus (`autoFocus: 'first-tabbable'`) skips the library's own container controls
+(`bf-sheet`'s hidden Close and grabber button, marked with the internal `data-bf-overlay-chrome`);
+they stay in the Tab order. Documented on `autoFocus`; the marker is not API.
+
+**Behaviour:** Android web back closes the top overlay. For every non-passive overlay, where the
+window has `CloseWatcher` (Chromium 120+) and the host does not handle the system back itself,
+the core creates a watcher on open and destroys it on close; its close request runs the same path
+as `Escape` (`onEscape`, else close when `dismissOnEscape` is not false). An overlay that stays
+open (not dismissible, or below the top one) creates a new watcher, so it keeps claiming the next
+back press. `Escape` stays a single dismissal: the core cancels the key, so it never reaches a
+watcher as a second close request. See Migration 35. A non-dismissible overlay (`dismissOnEscape: false` without
+`onEscape`) therefore swallows Android web back while it is open, as the `BfOverlayService` JSDoc
+now says.
+
+New `BfOverlayHost.handlesSystemBack?: boolean`: true when the host already routes the system back
+to `registerBack`; the overlays then create no `CloseWatcher`. `provideBfShell()` sets it on
+native Android.
+
+### dialog
+
+New exported `BfConfirmSize` (`'sm' | 'md'`), the type of `BfConfirmOptions.size`,
+`BfDialogRole` (`'dialog' | 'alertdialog'`), the type of `BfDialogConfig.role`, and
+`BfConfirmButtonRole` (`'cancel' | 'destructive'`), the type of `BfConfirmButton.role`;
+`BfDialogConfig` `autoFocus` takes the new `BfOverlayAutoFocus`.
+
+New `bf-dialog` and `BfDialogService` in `@bitforgehq/ui/overlay`: a centred modal dialog for
+desktop and web apps with no Capacitor dependency. `open(component | template, config)` returns
+a typed `BfDialogRef<R, C>` (`afterClosed`, `closed()`, `componentInstance`, `close(result)`);
+the content injects `BfDialogRef` and `BF_DIALOG_DATA`, a template gets `{ $implicit: ref, data }`.
+`BfDialogConfig`: `data`, `size` (`sm` 24, `md` 32 (default), `lg` 48, `xl` 64 rem, capped at the
+viewport minus the gutters, or `fullscreen`), `role` (`dialog`/`alertdialog`), `ariaLabel`,
+`ariaDescribedBy`, `dismissOnBackdrop` (default true for `dialog`, false for `alertdialog`),
+`dismissOnEscape`, `autoFocus`, `restoreFocus`, `panelClass`, `injector`. `bf-dialog` lays out a
+`title` (the `h2` the panel is labelled by), `[bfSlot=header]`, a scrolling body (focusable only
+while it overflows, then a region named by the title when there is one) and an end-aligned
+`[bfSlot=footer]`, with a close button (`closeButton`, `closeLabel`, default the `close` label)
+last in the tab order. `confirm({ title, message?, buttons?, size?, injector? })` opens an alert
+dialog and resolves with the pressed button's `id ?? label` (default buttons Cancel and OK, ids
+`cancel` and `ok`); focus starts on the cancel button, `Escape` answers with it or is ignored
+without one. A navigation to another URL path closes a dialog with no result and a `confirm()`
+with the cancel button's answer (else `undefined`); `closeOnNavigation: false` (on `BfDialogConfig`
+and `confirm()`) keeps it open. Title and message ids come from the library's shared id counter,
+so they never repeat an id of a `bf-dialog` rendered in the page. Focus is trapped and restored,
+the page behind is `inert` and document scroll is locked (APG dialog (modal) and alert dialog
+patterns).
+
+JSDoc of `dialog-ref.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+JSDoc of `dialog.component.ts` for the API reference: `@slot` docs for `header`, `default`,
+`footer`. No behaviour change.
+
+JSDoc of `dialog.service.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@default` on the option properties the code applies; `@param` docs. No behaviour change.
+
+The `bf-dialog` host carries `data-bf-dialog-id` (its title id, also without a rendered title), so
+`BfDialogHarness` finds the overlay panel the card sits in, also under a stacked dialog.
+
+The docs say that Android back in a browser with `CloseWatcher` closes the dialog like `Escape`
+(and that `dismissOnEscape: false` swallows it); see `### overlay core` and Migration 35.
+
+### desktop-toast
+
+The card's action button output is `actionClicked` (an action emits `clicked`, a sub-part's
+action `<part>Clicked`); `BfDesktopToastService` binds it.
+
+New `BfDesktopToastService` and `bf-desktop-toast` in `@bitforgehq/ui/overlay`: toasts for desktop
+and web apps with no Capacitor dependency. `show({ message, action?, duration?, injector? })`
+returns a `BfToastRef` and follows the `/mobile` toast's rules: 3000 ms by default, persistent
+(`duration` 0) with an action, a later `show()` replaces every persistent toast (`'dismiss'`),
+`Escape` inside a toast dismisses it, focus returns only when it was inside the closing toast, one
+polite `LiveAnnouncer` announcement per toast, everything ends with the injector. Up to three
+cards are visible at once in one passive overlay pane, bottom right (bottom left in RTL) 24 px in
+plus the safe area, the newest nearest the edge; later toasts wait. The pointer over the stack or
+focus inside it pauses every visible toast. The stack is a `region` named by the new
+`notifications` label ("Notifications"); no backdrop, no focus move, no scroll lock, nothing
+`inert`. Cards fade in with an 8 px slide (a fade under reduced motion). A navigation never closes
+a toast. `F6` from the page moves focus to the action of the newest toast that has one, and `F6`
+inside the stack moves it back (the key is left to the browser otherwise). In a right-to-left page
+the end inset reads the left safe area (`--spacing-safe-left`).
+`provideBfDesktopToast(config)` sets `position` (`'bottom-end'` (default), `'bottom-center'`,
+`'top-end'` or `'top-center'`), `maxVisible` (default 3) and `ariaLabel` (the region name; empty
+uses the label), over `BF_DESKTOP_TOAST_DEFAULTS`.
+
+JSDoc of `desktop-toast.service.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@default` on the option properties the code applies; `@param` docs. No behaviour change.
+
+### menu
+
+New `changed` output on `bfMenuItemCheckbox`: the new `checked` state right after the user toggles
+the item (after `triggered`, beside the model's `checkedChange`), so it has the one `changed` of
+every value control.
+
+New `bf-menu` and its parts in `@bitforgehq/ui/overlay`, on the Angular CDK menu (APG menu button
+and menu patterns): `bfMenuItem` on a `<button>` or a link (`<a>` with `href` or `routerLink`),
+`bfMenuItemCheckbox` and `bfMenuItemRadio` (`checked`, CSS-drawn check mark and dot),
+`bfMenuGroup` (radio items exclusive), `bfMenuDivider` and `[bfMenuTriggerFor]` (on any element,
+or on an item for a submenu with a CSS chevron, mirrored in RTL). Items take `bfMenuItemDisabled`
+(focusable, `aria-disabled`) and `bfMenuItemTypeahead` and emit `triggered`; the trigger takes
+`bfMenuTriggerData` and `bfMenuPlacement` (`below-start` (default), `below-end`, `above-start`,
+`above-end`, flipping on overflow; submenus open beside their item) and emits `bfMenuOpened` and
+`bfMenuClosed`. `bf-menu` takes `size` (item rows `sm` 32, `md` 36, `lg` 44 px, 44 px under a
+coarse pointer; unset follows `provideBfDefaults()` `controlSize`), `ariaLabel` and
+`ariaLabelledby`; without either it is named by its trigger. Keyboard: `Enter`, `Space`,
+`ArrowDown` open on the first item, `ArrowUp` on the last; arrows wrap, `Home`/`End`, type-ahead,
+`Escape` and `Tab` close with focus back on the trigger, `ArrowRight`/`ArrowLeft` open and close
+submenus (swapped in RTL); `Space` also follows a link item (once, ignoring auto-repeat), and a
+disabled link item never navigates, also with `routerLink`. `bfMenuItemCheckbox` emits
+`checkedChange` with the state it flipped to, so `[(checked)]` binds it two-way. An open submenu
+stays open while the pointer moves diagonally towards it (CDK menu aim). Under forced colours the
+focused item is drawn in `Highlight`, a focused disabled one in `GrayText` on `Canvas` with a
+`Highlight` outline. A navigation to another URL path closes an open menu (query- and
+fragment-only changes do not); the trigger watches the URL only while its menu is open.
+
+JSDoc of `menu-item.directive.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@binding` docs for the host-directive bindings `bfMenuItemDisabled`,
+`bfMenuItemTypeahead`, `triggered`, `checked`. No behaviour change.
+
+JSDoc of `menu-trigger.directive.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@binding` docs for the host-directive bindings `bfMenuTriggerFor`, `bfMenuTriggerData`,
+`bfMenuOpened`, `bfMenuClosed`. No behaviour change.
+
+JSDoc of `menu.component.ts` for the API reference: `@slot` docs for `default`. No behaviour change.
+
+The two effects that write into the CDK host directives (`bfMenuItemCheckbox`'s `checked`,
+`bfMenuTrigger`'s `menuPosition` and `ngOnChanges`) carry an `effect-justified` comment: the CDK
+exposes no input they could derive from. No behaviour change.
+
+### menu-button
+
+New `bf-menu-button` in `@bitforgehq/ui/overlay`: a native `<button>` that opens a `bf-menu`
+(`menu`, a `TemplateRef`) with `aria-haspopup="menu"` and `aria-expanded`, styled like
+`bf-button` (`variant` `outline` (default), `text`, `tonal`; a CSS caret) or, with `iconOnly`,
+like `bf-icon-button`. `size` (unset follows `controlSize`), `placement`, `label` (the
+`aria-label`, required with `iconOnly`), `disabled`, and `opened`/`closed` outputs. Its classes
+come from `bf-button`'s and `bf-icon-button`'s own class maps (internal `ɵ` exports of
+`@bitforgehq/ui`), so the looks never drift.
+
+JSDoc of `menu-button.component.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@slot` docs for `icon-start`, `default`. No behaviour change.
+
+**Behaviour:** a pressed state (F-045): the button and icon-only forms take `bf-button`'s and `bf-icon-button`'s pressed fills from their shared class maps. None while disabled; under forced colours the system colours win.
+
+### toast
+
+The toast engine (timing, hold, replace, focus return, announcements, teardown) moved into
+`@bitforgehq/ui/overlay`, shared with the new desktop toast; `BfToastService` renders one toast at
+a time on it exactly as before. `BfToastRef`, `BfToastDismissReason` and `BfToastAction` are now
+also exported from `@bitforgehq/ui/overlay`; the `/mobile` exports stay (not deprecated) and are
+the same types and class. No behaviour change: a navigation never closes a toast (it opts out of
+the core's new `closeOnNavigation`).
+
+JSDoc of `toast.component.ts` for the API reference: `@summary`/`@since` on the exported symbols. No
+behaviour change.
+
+JSDoc of `toast.service.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@default` on the option properties the code applies; `@param` docs. No behaviour change.
+
+**Behaviour:** `--bf-toast-keyboard` is written in the render phase (`afterRenderEffect`) instead
+of an `effect`; internal timing only, no API change.
+
+### overlay entry
+
+New secondary entry `@bitforgehq/ui/overlay`: the overlay core with no Capacitor and no router
+dependency (peers `@angular/cdk` and `rxjs`). `BfOverlayService`, `BfOverlayRef`,
+`BfComponentOverlayRef`, `BF_OVERLAY_DATA`, `BfOverlayStack`, their option types and the
+animations (`fadeIn`, `fadeOut`, `fadeUp`, `fadeDown`, `scaleIn`, `slideUp`, `slideDown`) moved
+here from `@bitforgehq/ui/mobile`, joined by `BF_OVERLAY_HOST`/`BfOverlayHost`,
+`OVERLAY_REDUCED_DURATION`, `prefersReducedMotion` (still exported from `/mobile` too) and
+`BfOverlayController` (for entries that extend `BfOverlayRef`). `/mobile` builds its sheet, modal,
+toast, action sheet and alert dialog on it.
+
+**Type:** the `/mobile` exports of the moved names are deprecated aliases of the `/overlay` ones
+(the same classes, tokens and functions), removed in 0.4.0. Migration: import them from
+`@bitforgehq/ui/overlay` instead of `@bitforgehq/ui/mobile`.
+
+**Migration — every moved core import:**
+
+| Old (`@bitforgehq/ui/mobile`, deprecated) | New (`@bitforgehq/ui/overlay`) |
+| ----------------------------------------- | ------------------------------ |
+| `BF_OVERLAY_DATA`                         | `BF_OVERLAY_DATA`              |
+| `BfComponentOverlayRef`                   | `BfComponentOverlayRef`        |
+| `BfOverlayOptions`                        | `BfOverlayOptions`             |
+| `BfOverlayPosition`                       | `BfOverlayPosition`            |
+| `BfOverlayRef`                            | `BfOverlayRef`                 |
+| `BfOverlayService`                        | `BfOverlayService`             |
+| `BfOverlayStack`                          | `BfOverlayStack`               |
+| `BfOverlayStackOptions`                   | `BfOverlayStackOptions`        |
+| `BfOverlayTemplateContext`                | `BfOverlayTemplateContext`     |
+| `BfStackedOverlay`                        | `BfStackedOverlay`             |
+| `OVERLAY_DURATION`                        | `OVERLAY_DURATION`             |
+| `OVERLAY_EASING`                          | `OVERLAY_EASING`               |
+| `fadeDown`                                | `fadeDown`                     |
+| `fadeIn`                                  | `fadeIn`                       |
+| `fadeOut`                                 | `fadeOut`                      |
+| `fadeUp`                                  | `fadeUp`                       |
+| `scaleIn`                                 | `scaleIn`                      |
+| `slideDown`                               | `slideDown`                    |
+| `slideUp`                                 | `slideUp`                      |
+
+`/mobile` keeps these as deprecated aliases (same class/token/function identity) until 0.4.0; new
+code imports them from `@bitforgehq/ui/overlay` directly. `prefersReducedMotion` and
+`OVERLAY_REDUCED_DURATION` are new in `/overlay` and stay exported from `/mobile` too (not
+deprecated — no import change needed). `BfToastRef`, `BfToastDismissReason` and `BfToastAction`
+also moved, but `/mobile`'s export of them is the same class/type, not deprecated (see `toast`
+above). An app that adds `@bitforgehq/ui/overlay` installs `@angular/cdk` and `rxjs` (peers of
+`/overlay`); `/mobile` needs those plus `@angular/router` and `@capacitor/core` (unchanged).
+
+**Behaviour changes bundled with the move** (each detailed under its own `###` above; one line
+each here for a single migration pass):
+
+- Outside a shell (no `provideBfShell()`), the page behind an open non-passive overlay is now
+  `inert` (`### overlay core`, Migration 20).
+- The hardware back button now reaches overlays only through the optional `BF_OVERLAY_HOST`
+  token, provided by `provideBfShell()`; without it, no back handler is registered
+  (`### overlay core`, Migration 21).
+- Overlays close by default when the URL path changes (`closeOnNavigation`, default true; toasts
+  never close) (`### overlay core`, Migration 19).
+- `bf-alert`'s role follows the new `urgent` input, not `variant`: add `urgent` to a danger alert
+  that must interrupt (`### alert`, Migration 15).
+- `bf-alert`'s dismiss button is named after the alert's title, not a bare "Dismiss" (`### alert`,
+  Migration 16).
+- Alert dialogs and action sheets focus the `cancel`-role button first, not the first button
+  (`### alert-dialog`, `### action-sheet`, Migration 17).
+- `BfAlertDialogService.open()` returns `Promise<string | undefined>` (was `Promise<string>`): a
+  navigation may resolve `undefined` when there is no cancel button (`### alert-dialog`, Migration
+  18).
+
+### testing entry
+
+New secondary entry `@bitforgehq/ui/testing` (additive), for consumer specs under Vitest (the
+Angular CLI default) or Jest. It imports only `@angular/core`, `@angular/cdk/testing` and
+`@bitforgehq/ui` (never `/overlay`, `/mobile` or Capacitor; lint- and consumer-smoke-checked), so
+it needs `@angular/cdk` as a dev dependency; the CDK stays an optional peer.
+
+- `installBfJsdomShims(options?)` (`jsdom-shims.ts`) installs, only where missing,
+  `Element.prototype.animate` (an `Animation` whose `finished` resolves at once), `PointerEvent`
+  (a `MouseEvent` with `pointerId`, `isPrimary`, `pointerType`, `width`, `height`, `pressure`)
+  and a `matchMedia` stub (every query false; `reducedMotion: true` reports
+  `(prefers-reduced-motion: reduce)` as matching; `matchMedia: false` skips it). It is idempotent
+  and returns a function that removes exactly what it installed (a replaced global is restored
+  from its descriptor, getters included; a global it cannot set is left alone). The shims moved here from the
+  library's own `setup-jest.ts`; the library, docs, web-demo and mobile-demo Jest setups now call
+  it. The shimmed `Animation` is a small class implementing the interface in full (no cast, the
+  same shape as `overlay-animations.ts`'s own `BfFinishedAnimation`); its `finished` resolves to
+  the animation itself, matching the real Web Animations API, not `undefined` as before.
+- `provideBfTesting({ defaults?, labels? })` (`provide-bf-testing.ts`) passes the options to
+  `provideBfDefaults()`/`provideBfLabels()` and, when the test environment is torn down, removes
+  `dark` and `cdk-global-scrollblock` from `<html>`, `inert` from the children of `<body>` and every
+  child of a `.cdk-overlay-container`. The cleanup needs TestBed's default
+  `teardown: { destroyAfterEach: true }`.
+- CDK component harnesses (`harnesses/*.harness.ts`), each with `static with({ label })` (the
+  shared `BfHarnessFilters`, the CDK's `selector`/`ancestor` plus `label`): `BfSelectHarness`
+  (label, value label, option labels, `selectOption(label)`, disabled, read-only, required,
+  error and help text, focus, blur), `BfRadioGroupHarness` and `BfSegmentedHarness` (label, option
+  labels, selected label, `select(label)`, disabled, error text), `BfDialogHarness` (title, text,
+  role, `clickButton(label)`, `close()`, `pressEscape()`; through
+  `TestbedHarnessEnvironment.documentRootLoader()`), `BfMenuButtonHarness` (`open()`, `isOpen()`,
+  `getMenu()`), `BfMenuHarness` (`getItems(filter?)`, `clickItem(label, ...submenuPath)`),
+  `BfMenuItemHarness` (text, disabled, checked, submenu, `click()`, `getSubmenu()`) and
+  `BfDesktopToastHarness` (message, `clickAction()`, `pressEscape()`). They work by label, so a
+  spec never needs the native option values of the typed choice controls. Choosing in a disabled
+  select, or a disabled option, segment, radio group or segmented control, throws and leaves the
+  value alone, as a user's click would. `BfDialogHarness.getRole()` reads the dialog's own panel
+  (found through the host's `data-bf-dialog-id`), `null` for a `bf-dialog` rendered in the page. Plain native controls
+  (input, textarea, checkbox, toggle, button) get none: query their native element.
+
+### provide-bf-shell-testing
+
+New in `@bitforgehq/ui/mobile` (additive): `provideBfShellTesting({ routes?, config? })`, the test
+providers for an app on the shell: `provideRouter(routes ?? [], withComponentInputBinding(),
+withBfShellRouting())`, `provideBfShell({ swipeBack: false, hapticsOnTabChange: false, ...config })`,
+an in-memory `BF_THEME_STORAGE` (a theme change never reaches `localStorage`) and the same document
+cleanup as `provideBfTesting()` (which needs TestBed's default `destroyAfterEach: true`). It lives
+in `/mobile` so that `/testing` never loads Capacitor.
+
+### tabs
+
+**Breaking:** (ARIA contract) `bf-tabs` provides `BF_TAB_LINKS`, so the `bf-tab-bar` projected
+directly into it is a `nav` of links with `aria-current` (`page` at the tab's root, `true` on a
+child page) instead of a `tablist` (the tabs switch routes, not in-page panels); an in-page bar on
+a tab's page keeps its `tablist`. New `href(id)`: the tab's root URL, `/<tabsPath>/<id>` through
+`LocationStrategy` (base href included), used as each tab's `href`, so Ctrl/Cmd-click opens a tab
+in a new browser tab; a plain click still restores the tab's last page. New `isRoot(id)`: whether
+the current URL is that root. Tab moves between tabs (in Safari and iOS WKWebView only with "Press
+Tab to highlight each item", else Option+Tab); the arrow keys no longer do (they stopped after one
+step before). See Migration 11.
+
+JSDoc of `tab-context.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+JSDoc of `tabs.component.ts` for the API reference: `@slot` docs for `default`; `@param` docs. No
+behaviour change.
+
+**Behaviour:** the bar is driven through `BF_TAB_BAR_CONTROLLER` instead of written into (F-021).
+`current()` (read-only) is the tab of the in-flight navigation's target after redirects once they
+are applied (`router.currentNavigation()`), else of
+the settled URL (`router.lastSuccessfulNavigation()`), keeping the last tab while neither is under
+`tabsPath`: a clicked tab shows at once and a navigation a guard refuses drops back by itself.
+`hidden()` is `keyboard.visible() || keyboard.imminent()`, `hideTransition()` is true on iOS, and
+`select(id)`/`reselect(id)` are the former `changed`/`reselected` handlers. `tabKey()` and
+`isRoot(id)` read the router's navigation signals; the `router.events` subscription and the three
+effects that wrote into the bar are gone. `--bf-tab-bar-inset` (and `--bf-tab-bar-inset-global` on
+`<html>`) is written in the render phase (`afterRenderEffect`). See Migration 24.
+
+**Behaviour:** `--bf-tab-bar-inset` (and `--bf-tab-bar-inset-global`) use the bar's measured height
+instead of the fixed 4 rem (F-051, F-054): an `afterRenderEffect` observes the projected bar's
+`nav` with a `ResizeObserver` and writes
+`calc(<height>px + 8px + max(var(--spacing-safe-bottom), 12px) + 8px)`, or `0px` while the bar is
+hidden; until the first measurement it uses the bar's 64 px minimum. The observer is disconnected on
+destroy. So the page's bottom padding follows a bar grown by large text or slimmed at compact
+heights.
+
+### action
+
+New `BfActionDirective` (`a[bfAction], button[bfAction]`): marks the one interactive element of a
+`bf-card` or `bf-list-item` (`data-bf-action`) and stretches its hit area over the card or row with
+an empty `::after` (`absolute inset-0`), the stretched-link pattern, and gives a `button` the
+pointer cursor a link has. It registers with the nearest card or row (an internal token), which
+draws the pointer, hover and focus ring for its own action only. Under forced colours a
+transparent outline on the `::after` becomes a system-coloured focus indicator around the whole
+card or row (the ring, a box-shadow, is dropped there). See `card` and `list-item`.
+Additive.
+
+JSDoc of `action.directive.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+template handlers and framework hooks marked `@internal`, so the reference leaves them out. No
+behaviour change.
+
+### badge
+
+**Behaviour:** the label and the count pill use `rounded-control` (`--radius-control`, `9999px` by
+default, so they render as before).
+
+JSDoc of `badge.component.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@slot` docs for `default`. No behaviour change.
+
+New `countLabel = input('')` (F-039): with `count` set, it renders visually hidden after the
+number (`<span class="sr-only">`), so the pill reads "99+ unread messages". Ignored without
+`count`.
+
+### field
+
+**Behaviour:** the label of a focused field is `primary-text` (was `primary`).
+
+New export `bfFieldControlClass(state: { size: BfSize; invalid: boolean; disabled: boolean;
+readonly: boolean }): string` (and its `BfFieldControlState` type) from `@bitforgehq/ui`: the class
+list `bf-input` renders on its native `<input>` in the same state (box, height and type per size,
+padding, focus ring, `border-strong` or, while `invalid`, `danger-border`), so a custom control
+inside `bf-field` looks like the library's own fields without copying its classes. The disabled
+and read-only styles come from the control's native `disabled`/`readonly` attributes. `bf-input`
+builds its own list from the same pieces, and a spec asserts the two agree for every size and
+state. The field docs and the `@example` bind the control's `aria-describedby` to the field's
+`describedBy()` through a template reference (`#field`); the new `field/custom-control` example
+does so for a native input styled by `bfFieldControlClass()`.
+
+JSDoc of `field-classes.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+JSDoc of `field.component.ts` for the API reference: `@slot` docs for `default`. No behaviour
+change.
+
+**Behaviour:** the help paragraph renders always (when set) and the error paragraph under it;
+help text no longer disappears on error (F-020). `describedBy()` lists both ids,
+`"<controlId>-help <controlId>-error"`, `"<controlId>-help"`, `"<controlId>-error"` or `null`. A new
+`error` that arrives while a pointer button is held down anywhere in the page shows one task after
+the release (or at once on a key press, or a pointer move with no button down): the press on a
+Save button blurs the field and marks it touched on mousedown, and the message pushed Save about
+22 px down before the mouseup, so the click was lost in every browser. The field holds its layout
+through the press instead of reserving an empty line under every field. See Migration 25.
+
+`fieldDescribedBy(id, errorText, helpText)` (internal, `ɵfieldDescribedBy`) returns
+`"<id>-help <id>-error"`, `"<id>-help"`, `"<id>-error"` or `null`; the new internal
+`ɵfieldErrorMessageId` gives the controls' `aria-errormessage`.
+
+While a press holds a new error back, its paragraph is already rendered, visually hidden
+(`sr-only`), so the controls' `aria-describedby` and `aria-errormessage` always point at an element
+that exists and assistive tech reads the error when focus returns to the field; the same paragraph
+turns visible on release. Only the primary mouse button, a touch or a pen starts a hold (a
+right-click never does). The self-rendering controls (checkbox, toggle, radio group, segmented)
+behave the same way.
+
+### progress
+
+**Behaviour:** the default `primary` tone fills with `primary-strong` (was `primary`), so the fill
+reaches 3:1 on its `surface-sunken` track for any configured primary.
+
+JSDoc of `progress.component.ts` for the API reference: `@summary`/`@since` on the exported symbols.
+No behaviour change.
+
+**Behaviour:** `value` is optional (`input<number | undefined>(undefined)`, was required); without
+it and without `indeterminate` the bar renders 0 %. The redundant `role="progressbar"` attribute on
+the native `<progress>` is dropped (it is a progressbar natively). New `valueText = input('')`,
+rendered as `aria-valuetext` when set (F-039). New `indeterminate` (boolean): the native bar
+renders without `value` (indeterminate for assistive tech) and a 40 % stripe in the tone's fill
+runs across the track (`animate-progress-indeterminate`), standing still at the start under
+`motion-reduce:`. The host is a one-cell `grid` (was `block`) with `overflow-hidden
+rounded-full`, so the stripe shares the track's cell and stays in it.
+
+The indeterminate stripe runs from the inline start: under `dir="rtl"` it takes
+`--animate-progress-indeterminate-rtl` (mirrored keyframes), and stands still under reduced motion
+in both directions.
+
+### icon
+
+JSDoc of `icon.component.ts` for the API reference: `@summary`/`@since` on the exported symbols. No
+behaviour change.
+
+**Behaviour:** `bf-icon` binds `[attr.fill]` on every element it renders (F-065), so the filled
+details of Lucide icons show (`Palette`'s dots and 9 other distinct icons); elements without a Lucide
+`fill` get no attribute and inherit the `none` of the `<svg>`. `tools/lucide-attributes.test.ts`
+fails when an installed Lucide icon sets an attribute the renderer does not bind. See Migration 27.
+
+### content
+
+New exported `BfContentScrollEvent` (`{ scrollTop: number }`), the payload of `scrolled` (was an
+inline object type of the same shape).
+
+JSDoc of `content.component.ts` for the API reference: `@slot` docs for `default`; `@param` docs. No
+behaviour change.
+
+**Behaviour:** `--bf-header-height` is written in the render phase (`afterRenderEffect`), and the
+scroller registers in `BfPageContext` once after the first render (`afterNextRender`) instead of
+from an `effect`; it is still cleared on destroy. Internal timing only, no API change.
+
+`fullscreen` pads the top safe area only while the page's `BfPageContext.safeAreaTop()` is true;
+inside a page-sheet `bf-modal` (false) it adds no top padding (Migration 29).
+
+**Behaviour:** in the page a `bf-stack-outlet` shows, the scroller is the `main` landmark
+(`role="main"`, while `BfPageContext.mainLandmark()` is true). While it overflows and holds nothing
+focusable it is a tab stop (`tabindex="0"`, with an inset focus ring), so a keyboard can scroll it
+in Safari and WKWebView (which never focus a scroll container on their own; Chromium does); a
+control appearing inside takes it out of the Tab order again (re-checked per frame on resize and
+content changes, including `hidden` and `inert` toggles). Hidden, inert and unrendered controls do
+not count, and overflow means more than 2 px (the iOS body's 1 px rubber-band extra is not
+overflow). See Migration 36.
+
+### header
+
+JSDoc of `header.component.ts` for the API reference: `@slot` docs for `start`, `default`, `end`. No
+behaviour change.
+
+The toolbar pads the top safe area (`pt-safe-top`) only while the page's
+`BfPageContext.safeAreaTop()` is true; inside a page-sheet `bf-modal` (false) it adds none
+(Migration 29).
+
+**Behaviour:** large text (F-051). The bar has a minimum height instead of a fixed one
+(`min-h-11` in iOS mode, `min-h-16` in Material mode) and grows with its content; the header
+measures the bar title as `--bf-header-title-height` (the same `ResizeObserver` pass as the slot
+insets) and keeps the bar at least that tall, since the centred iOS title box is absolutely
+positioned. The bar title wraps to at most two lines (`line-clamp-2 wrap-anywhere`, centred in iOS
+mode) instead of truncating. The `start` slot may shrink (`min-w-0 shrink`) and the `end` slot
+never does (`shrink-0`), so actions stay whole. In iOS mode, where the centred title is taken out
+of the row's flow, the `start` slot is capped by `--bf-header-start-max` only when the title does
+not fit on one line beside the slots at their full width: the title may then claim up to half the
+bar, and only a back button's text (`bf-back-button`'s `[data-bf-back-text]`) gives way. The cap
+is never below the slot's other content or 44 px, so two start buttons stay whole, and the title
+inset reads the slot's `scrollWidth` too. It is measured from the bar's width, a hidden one-line
+copy of the title and the slot's full and minimum widths, so it never depends on the capped slot
+itself. A projected title (no `title` input) gets no cap. The large title's font and line height are capped
+at 200 % (`min(var(--text-display), 80px)`, `min(var(--text-display--line-height), 88px)`), in px
+because iOS Dynamic Type scales the root.
+
+**Behaviour:** the collapse range is the large title block's rendered height, bounded to 44–200 px
+(was a fixed 56 px, while the iOS large title renders about 70 px; a block taller than 200 px
+collapses its whole height over 200 px of scroll), re-read whenever it resizes; the snap goes to
+it; `data-bf-scrolled` switches on at full collapse, as before, now at that height (with 0.5 px of
+tolerance for a fractional snap landing). See Migration 31.
+
+**Behaviour:** compact heights (F-054). Under `(max-height: 500px)` (phone landscape, split
+screen; read with `matchMedia` and followed live, the listener removed on destroy) the header
+renders no large title: the title is the bar's `h1`, the bar is at least 44 px in both modes and
+nothing collapses or snaps.
+
+**Behaviour:** without a large title (`largeTitle` false, or a compact height) the scroll never
+moves `--bf-header-progress` and never snaps; a detail page used to snap to 0 or 56 px when a
+scroll stopped in its first 56 px.
+
+### keyboard-assist
+
+New exported `BfKeyboardAssistBehavior` (`'smooth' | 'instant'`), the type of
+`bfKeyboardAssistBehavior` (was an inline union with the same values).
+
+JSDoc of `keyboard-assist.directive.ts` for the API reference: `@summary`/`@since` on the exported
+symbols. No behaviour change.
+
+**Behaviour:** the paddings are measured in the render phase's early read and written in its write
+phase (`afterRenderEffect`) instead of an `effect`, and the settled correction runs after that
+render's write (measured in the early read phase, scrolled in the write phase, and only while the
+keyboard is still shown, also after a deferral); the will-show and settled reactions stay
+`effect`s, since they schedule timers. Internal timing only, no API change.
+
+### overscroll-stretch
+
+JSDoc of `overscroll-stretch.directive.ts` for the API reference: `@summary`/`@since` on the
+exported symbols. No behaviour change.
+
+### motion
+
+JSDoc of `motion.ts` for the API reference: `@summary`/`@since` on the exported symbols. No
+behaviour change.
+
+### horizontal-scroll
+
+JSDoc of `horizontal-scroll.directive.ts` for the API reference: `@summary`/`@since` on the exported
+symbols. No behaviour change.
+
+**Deprecated:** `bfHorizontalScroll` (`BfHorizontalScrollDirective`) is not needed; removed in
+0.4.0. `touch-action` is not inherited, and a touch intersects the values only up to its nearest
+scroll container, so an `overflow-x-auto` row pans on its own under the outlet's
+`touch-action: pan-y`, as a device check on the iOS Simulator and the Android emulator confirmed
+(both scrolled without the directive). The docs and JSDoc now say so; the directive keeps setting
+`touch-action: pan-x pan-y` and `data-bf-horizontal-scroll` until it is removed. See Migration 37.
+
+### nav-controller
+
+JSDoc of `nav-controller.service.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@param` docs; template handlers and framework hooks marked `@internal`, so the reference
+leaves them out. No behaviour change.
+
+The `router.events` subscription says in a comment why it stays: the direction hint belongs to one
+navigation id's start and end. No behaviour change.
+
+### page
+
+JSDoc of `page-context.ts` for the API reference: `@summary`/`@since` on the exported symbols. No
+behaviour change.
+
+JSDoc of `page.component.ts` for the API reference: `@slot` docs for `default`. No behaviour change.
+
+`BfPageContext` gains `safeAreaTop` (a `signal(true)`): whether the page reaches the top of the
+screen, so its header and a `fullscreen` content pad the top safe area. `bf-modal`'s page-sheet
+presentation sets it to false.
+
+`BfPageContext` gains `mainLandmark` (a `signal(true)`): whether the page's `bf-content` is the
+`main` landmark. A `bf-page` outside a `bf-stack-outlet` (a docs illustration) or nested in
+another page sets it to false, so the document keeps one `main` (Migration 36).
+
+### stack-outlet
+
+**Deprecated:** `stackChange` → `stackChanged`, `transitionStart` → `transitionStarted` and
+`transitionEnd` → `transitionEnded`. The new outputs emit the same `BfStackChange` and
+`BfStackTransitionEvent` objects at the same moments; the old names still emit them right after
+until 0.4.0 (see Migration 23).
+
+JSDoc of `stack-outlet.component.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@param` docs; template handlers and framework hooks marked `@internal`, so the reference
+leaves them out. No behaviour change.
+
+Setup in `docs.md`: `provideBfShell()` provides the configuration and the reuse strategy and starts
+the platform services; `BfNavController` and the overlay services are root-provided and
+tree-shakable.
+
+The `router.events` subscription says in a comment why it stays: the stack pairs each navigation
+id's start with its own end. No behaviour change.
+
+**Behaviour:** the iOS edge swipe-back arms only for `pointerType` `touch`: a mouse drag or a
+text selection from the left edge, and a pen, never pop the page (a desktop web page with the mode
+forced to `ios`). See Migration 39.
+
+New `maxLivePages` (through `provideBfShell()`, default `Infinity`): above it, the outlet destroys
+the components of the deepest pages of a stack and keeps a record of each (route, key, history
+position, navigation id, URL and the `bf-content` scroll position); the top `maxLivePages` pages
+stay alive. A pop back to such a page creates it again from the re-activated route in a new frame,
+restores its scroll after the first render and runs the pop transition and lifecycle. Deep pages
+come back fresh: nested outlets inside a destroyed page lose their stacks. With `maxLivePages: 1`
+the swipe-back does not arm (the page below is a record). The deprecated `stackChange`,
+`transitionStart` and `transitionEnd` keep emitting after their replacements.
+
+The host's `touch-action: pan-y` comment and the docs follow the Pointer Events model: page
+scrollers, horizontal rows included, keep their own panning (see `### horizontal-scroll`).
+
+### stack-reuse-strategy
+
+JSDoc of `stack-reuse-strategy.ts` for the API reference: `@summary`/`@since` on the exported
+symbols; `@param` docs. No behaviour change.
+
+### transitions
+
+JSDoc of `transitions.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+### view-lifecycle
+
+JSDoc of `view-lifecycle.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs; template handlers and framework hooks marked `@internal`, so the reference leaves
+them out. No behaviour change.
+
+### haptics
+
+JSDoc of `haptics.service.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+### keyboard
+
+JSDoc of `keyboard.service.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+### platform
+
+JSDoc of `platform.service.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+New token `BF_THEME_STORAGE` (`InjectionToken<Pick<Storage, 'getItem' | 'setItem'>>`, additive):
+`BfPlatformService` reads and writes the theme choice (key `bf-theme`) through it. Its default is
+`localStorage` when available, otherwise an in-memory map (before: every read and write went to
+`localStorage` directly and was skipped where it threw). Provide another store to keep the choice
+elsewhere; `provideBfShellTesting()` provides an in-memory one.
+
+**Behaviour:** `BfPlatformService` applies the `dark` class on `<html>` and stores the theme
+synchronously at construction, so a freshly provided shell has the class before any change
+detection; the `effect` only keeps later changes in sync. No API change.
+
+**Behaviour:** on native iOS and Android with `provideBfShell()` (and `syncSystemBars` not
+`false`), `BfPlatformService` calls Capacitor's `SystemBars.setStyle()` at launch and on every
+change of `dark()` (and of the system theme), so the bar icons stay readable in the in-app theme;
+a failure goes to `console.error` (Migration 30). New exported `bfSystemBarsStyle(dark, platform,
+webViewMajor)`: `Dark` (light icons) for a dark theme, else `Light`, and `Default` on Android
+WebView < 140 (parsed from `Chrome/<n>` in the user agent), which pads the page below the bars so
+that they show the activity's window background, which follows the system theme. Give the window
+the page colour (`android:windowBackground`, see the `/mobile` guide) so the bars match the page
+when both themes agree. The WebView ≥ 140 case assumes `viewport-fit=cover` and the default
+`SystemBars.insetsHandling: 'css'`.
+
+### text-scale
+
+JSDoc of `text-scale.service.ts` for the API reference: `@summary`/`@since` on the exported symbols.
+No behaviour change.
+
+### shell
+
+New exported `BfShellConfigMode` (`'ios' | 'md' | 'auto'`), `BfShellDynamicType`
+(`false | BfShellDynamicTypeLimit`) and `BfShellDynamicTypeLimit` (`{ maxScale: number }`), the
+types of `BfShellConfig.mode` and `dynamicType` (were inline types with the same values).
+
+JSDoc of `provide-bf-shell.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@param` docs. No behaviour change.
+
+JSDoc of `shell-config.ts` for the API reference: `@summary`/`@since` on the exported symbols;
+`@default` on the option properties the code applies. No behaviour change.
+
+**Behaviour:** `provideBfShell()` lists only the shell config, the route reuse strategy,
+`BF_OVERLAY_HOST` and the environment initializer (which still starts the platform, back-button,
+keyboard, haptics and text-scale services). `BfNavController`, the platform services and the
+overlay services (`BfOverlayStack`, `BfOverlayService`, `BfSheetService`, `BfModalService`,
+`BfToastService`, `BfActionSheetService`, `BfAlertDialogService`) are root-provided and
+tree-shakable, so a shell app that never injects an overlay service bundles no overlay code (the
+consumer smoke's new `mobile-shell` build holds no `cdk-overlay-pane` or `cdk-overlay-backdrop`
+string). Under
+`provideBfShell()` in a lazy route's environment injector, the overlay services now resolve from
+the root injector (Migration 22).
+
+New `BfShellConfig.syncSystemBars` (default `true`; also in `BF_SHELL_DEFAULTS`): the native
+system bars follow the in-app theme (see `### platform`); `false` leaves them to the app.
+
+New `BfShellConfig.backAtRoot?: BfBackAtRoot` (`'minimize' | 'exit'`, default `'minimize'`; new
+exported type; also in `BF_SHELL_DEFAULTS`): what the Android back button does when nothing can go
+back. See `### back-button service` and Migration 34.
+
+New `BfShellConfig.maxLivePages?: number` (default `Infinity`, also in `BF_SHELL_DEFAULTS`): how
+many pages of each stack stay alive in every `bf-stack-outlet` (see `### stack-outlet`). No
+behaviour change by default.
+
+`provideBfShell()`'s `BF_OVERLAY_HOST` sets `handlesSystemBack` on native Android, where
+Capacitor's `backButton` event already reaches the overlays, so they create no `CloseWatcher`
+there.
+
+### back-button service
+
+**Behaviour:** when no handler claims the back press (every shown stack at its first page),
+`BfBackButtonService` calls `App.minimizeApp()`, so the app moves to the background and a
+relaunch resumes warm; with `provideBfShell({ backAtRoot: 'exit' })` it calls `App.exitApp()` as
+before. It reads `BF_SHELL_CONFIG` (optional; `'minimize'` without it), and a failure goes to
+`console.error`. See Migration 34.
+
+### toast-ref
+
+JSDoc of `toast-ref.ts` for the API reference: `@summary`/`@since` on the exported symbols. No
+behaviour change.
+
+### choice
+
+JSDoc of `choice.ts` for the API reference: `@summary`/`@since` on the exported symbols. No
+behaviour change.
+
+### avatar
+
+JSDoc of `avatar.component.ts` for the API reference: `@summary`/`@since` on the exported symbols.
+No behaviour change.
+
+**Behaviour:** the circle is at least 4.5ex of its initials (`min-w-[4.5ex] min-h-[4.5ex]`), so at
+Android font scale 2.0 (a text zoom that doubles the rendered initials, and `ex` with them, but not
+em, rem or px lengths) it grows with
+them instead of cutting them off, e.g. the `sm` avatar in a header's `end` slot (F-051). At the
+default size and with iOS Dynamic Type every size is larger than that minimum (with Manrope: sm
+30 px against 26.7, md 40 against 31.5, lg 84 against 63), so nothing changes.
+
+### empty-state
+
+New exported `BfEmptyStateHeadingLevel` (`2 | 3`), the type of `headingLevel` (was an inline union
+with the same values).
+
+JSDoc of `empty-state.component.ts` for the API reference: `@slot` docs for `icon`, `actions`. No
+behaviour change.
+
+### list
+
+JSDoc of `list.component.ts` for the API reference: `@slot` docs for `default`. No behaviour change.
+
+### docs site
+
+Examples and demos use the convention's output names: `(changed)` on `bf-chip`, `bf-tab-bar` and
+`bfMenuItemCheckbox`, `(stackChanged)` on `bf-stack-outlet`, `(refreshRequested)` on
+`bf-refresher`. The API reference index gains an `@bitforgehq/ui/number-input` group for its
+two new types.
+
+The theme configurator derives contrast-safe tokens for any primary: `primary-strong` steps darker
+(light) or lighter (dark) until 4.5:1 on `primary-soft`, `primary-soft-hover`, `bg` and `surface`
+(`#fde047` gave 2.03:1 before); the new `primary-text` steps until 4.5:1 on `bg` and `surface`;
+`on-primary` is white only at ≥ 4.5:1 (was 3:1), else black, and the hover keeps 4.5:1 under it;
+status colours step until 4.5:1 on their soft tint, `bg` and `surface`, and `danger-border` until
+3:1. New "Control radius" slider (0–24 px) with a "Pill" switch (on by default) emitting
+`--radius-control`; a stored config from before (no control radius) reads as a pill.
+`tools/theme-contrast.test.ts` asserts every brand, status and ring pair for the shipped theme
+and for six primaries (`#fde047`, `#0b0b0b`, `#2b26ba`, `#10b981`, `#ef4444`, `#a855f7`) in both
+modes, plus the state indicators against what they sit on (checkbox mark and toggle knob
+on the primary fill, radio dot in its ring, progress fill on its track).
+
+New guides: "Density and sizes" (`/density`: the `BfSize` scale per widget, a live 20-field
+Signal Forms form in all three steps, each a sub-tree with its own `provideBfDefaults()`, setups for
+a desktop app, a sub-tree and a Capacitor app, and the hit-area rule; its filter row is a named
+`role="group"`, and the page states that its density-scaled layout gaps are the demo's own
+convention, read from `BF_DEFAULTS`, which `provideBfDefaults()` never applies to an app's layout)
+and "Labels and language"
+(`/labels`: tables of every built-in string and default validation message rendered from
+`BF_DEFAULT_LABELS`, so they cannot drift, a live German sub-tree under `provideBfLabels()`, and the
+"ss, never ß" rule for German copy); both in the navigation, search, `llms.txt` and the sitemap.
+The Forms guide gains "Typed values" (numeric select ids, `null` for none, `compareWith`,
+`bf-number-input` with `min()`) and "Default messages"; its live example's team select binds
+numeric ids, and its Reactive Forms example types its controls `number | null` and shows default
+messages without any `errorMessage`. The consumer-smoke job also builds and tests a dense (`sm`)
+desktop Signal Forms form with German default messages, typed values and links.
+
+The desktop overlay pages (`dialog`, `desktop-toast`, `menu`, `menu-button`) run their live demos
+in the page itself; the dialog demo adds "Release notes" (a body that scrolls) and "Share…" (a
+`bf-menu-button` in the dialog footer), reports the `confirm()` answer id, and every overlay demo
+marks its triggers and result line with `data-testid`. The install line of a component page now
+names the peers of its entry point: `bun add @bitforgehq/ui @angular/cdk` for
+`@bitforgehq/ui/overlay`, `bun add @bitforgehq/ui @angular/cdk @angular/router @capacitor/core rxjs`
+for `@bitforgehq/ui/mobile`. The `/mobile` overlay pages (alert dialog, toast, modal, sheet, action
+sheet) gain a "Desktop" section pointing to `bf-dialog`, `BfDialogService.confirm()`,
+`BfDesktopToastService` and `bf-menu`. New end-to-end proof at 1280 × 800
+(`e2e/docs/overlay-desktop.spec.ts`): wheeling over an open dialog or its backdrop leaves the page
+where it was and it scrolls again once closed; a long dialog scrolls only its body; the page is
+`inert`, focus is trapped and restored; `confirm()` focuses Cancel and ignores the backdrop;
+history back and a link item close the dialog or menu; `Escape` in a menu inside a dialog closes
+only the menu; a toast sits bottom right, is announced, never locks or isolates the page, pauses
+under the pointer and hands focus back on `Escape`; the full menu-button keyboard path. axe also
+scans the open dialog, confirm, menu, submenu and toast stack at `moderate` impact, light and dark.
+
+Every example is a compiled file, and the Code tab shows exactly the file the Preview renders
+(F-079). The demos moved to `projects/docs/src/app/examples/<name>/overview-example.component.ts`
+(`<Name>OverviewExampleComponent`, `app-example-<name>-overview`) and the guide examples to
+`examples/guides/{forms,density,labels}/`; each loads in its own chunk through the generated
+`examples/example-registry.ts`, and the generated `examples/example-sources.ts` holds every file
+verbatim for the Code tabs. The new `app-example` card renders one example by id: in the page, in
+the phone frame (a `/mobile` component's Code tab is now its mobile-demo showcase page), or as code
+only with no tab list (the Forms guide's Reactive Forms example, a consumer-smoke fixture file).
+The Density and Labels guide examples gain a Code tab. `docs.md` sections can place examples with
+`<!-- example: <id> -->` markers. At 320 px the Preview column takes the full width (it shrinks to
+the demo only from `sm` up, inside `p-4 sm:p-10`), so no widget page's demo frame overflows
+(F-094, list-item); `e2e/docs/widgets.spec.ts` checks every widget page.
+
+Every example in the component docs is a compiled file now (F-092): the fenced `html` and `ts`
+blocks of every `docs.md` became `examples/<name>/<slug>-example.component.ts` files, each with a
+`renderExample()` spec, placed with `<!-- example: <id> -->` markers. A component page shows each
+as its own Preview | Code card; `/mobile` examples are compiled but code-only (`@preview none`),
+as are the few that would cover the page (the floating tab bar, a fixed action bar, an app config
+or a route guard). Markers work in every section (the overview, Theming, Accessibility and the
+notes too), as in the agent pages. A docs file keeps only `css`, `bash`, `json` and `text` fences.
+`tools/docs-contract.test.ts` enforces it (no other fence, no `<bf-` in a fence, every marker
+resolves, every docs file has a marker, no two components share their usage sections), and the
+new `tools/attr-drift.test.ts` parses every example template, every `@example` and every inline
+`<…>` code span with Angular's template parser and fails when an attribute or binding on a library
+element names no input, output, model or alias of it (or a native attribute), so renaming an input
+breaks `bun run test:tools` wherever the docs still use the old name. The generator reads a
+co-located `<component>.docs.md` before the folder's `docs.md` (`bf-tab`, `bf-list-item`). An
+example chunk that fails to load (a stale deploy) shows "Couldn't load the example" and logs the
+error instead of "No demo"; the `app-example` card no longer copies its `id` input onto the host as
+a DOM id (it names its example in `data-example`). The drift check also fails on library markup
+that does not parse (it checks the markup a TypeScript `@example` carries in its comments and
+template literals).
+
+A deep link to a section (`/components/input#with-signal-forms`) keeps its heading in view while
+the cards above it load: for 3 s every resize of the page scrolls to it again, until the user
+scrolls (wheel, touch, a scrollbar drag), clicks or presses a key, or the page navigates on.
+
+A component page no longer downloads `ai/MANIFEST.json` (784 kB, most of it example sources the
+site bundles anyway): `bun run ai:docs` also writes `projects/docs/public/manifest/<name>.json`, the
+component's manifest entry without `examples[].source`, and the page fetches only its own
+(`manifest/button.json`, at most 25 kB raw). `ai/MANIFEST.json` is unchanged for agents;
+`tools/examples.test.ts` checks every site entry against it.
+
+API tables come from the checker (F-082). The columns are Property, Type, Default and
+Description; badges mark a required member, a two-way `model()` (`[(value)]`), a member that
+`[formField]` sets (`invalid`, `touched`, `errors`, …) and a deprecated one. The type cell links
+every public symbol it names (`BfSize` to `/api/bf-size`, a component class to its page) and
+shows the expanded union under an alias. Component pages gain a Slots table (each slot once, with
+its doc) and a Methods section (signature, doc and a parameter table). New API reference:
+`/api` lists every service, directive, function, token, class, interface, type and constant by
+entry point and kind, and `/api/<slug>` renders one from `ai/REFERENCE.json` (fetched on demand):
+its import line, a directive's usage docs with live examples, the signature, a union's values,
+the members (a directive's inputs and outputs, an interface's properties with their defaults),
+the methods, what it uses and what uses it. The overlay services' pages link their options
+types, whose Options tables show the defaults. Titles and descriptions come from the bundled
+`REFERENCE.index.json`; the sitemap lists every reference page. `bfOverscrollStretch`'s
+hand-written input table is gone: its reference page shows the generated one. `/api/<component class slug>`
+(`/api/bf-button-component`) redirects to the component's page.
+
+Every component page (and a directive's reference page) gains a "When to use" section right after
+the Overview, saying when to pick the widget and what to use instead, with links to the related
+component and `/api` pages (F-087). Every interactive widget's Accessibility section ends with a
+"Keyboard" table (`| Key | Action |`, keys as `<kbd>`) of what the code does: native elements list
+the browser's keys, the menu and dialog keep 3c's tables. A "Desktop" section before Theming
+covers hover, the pointer, `focus-visible` and density on desktop for every interactive widget,
+and what to use on desktop for every `/mobile` page (3c's overlay "Desktop" sections are kept).
+The page order is fixed: header, primary example, Overview, When to use, the usage sections,
+Desktop, Theming, Accessibility (with Keyboard), API, Notes, Migration notes. The `bf-tabs` page's
+"Keyboard" section (the soft keyboard) is now "Soft keyboard" (`#soft-keyboard`).
+`tools/docs-contract.test.ts` fails on a missing or misplaced section: When to use in every docs
+file, first, with an "instead" and a `/components` or `/api` link; a Keyboard table for every
+component or directive that is interactive by the extracted API (a model or an output, or a
+`button`, `a`, `input`, `select`, `textarea` or `tabindex` in its template) unless it is on a short
+allow-list with a reason (`bf-content`, `bf-page`, `bf-stack-outlet`, `bf-refresher`); Desktop for
+every interactive and every `/mobile` widget; and every `/components/<name>` and `/api/<slug>`
+link in the docs must name a page that exists. Links to the site's own pages in rendered markdown
+(root-relative or on `https://bitforge-ui.web.app`) resolve against the app's base href, so they
+work on a mirror served under a sub-path and in local builds, and stay real links (middle-click,
+copy link). A heading inside the prose (`### Keyboard`) carries its slug as an id, so
+`/components/menu#keyboard` lands on it at any width. The interactive rule also counts a template
+element that another interactive library widget matches by selector (transitively: the action
+sheet's `bf-list-item` and `bf-button` rows) and host key, click and focus listeners
+(`bfAction`'s focus and blur); `bf-modal`, `bf-sheet`, `bf-tabs` and `bf-header`, whose keys come
+from the overlay core or projected content, are listed by hand, and `bfAction`'s keys are checked
+on the card and list-item pages.
+
+How-to guides. `/testing` covers the CDK dev dependency, the Vitest setup file (the CLI default)
+or a Jest config with `installBfJsdomShims()` and the `transformIgnorePatterns` the library needs,
+`provideBfTesting()` and `provideBfShellTesting()`, zoneless waiting, the harnesses in the page
+and in the overlay container, and a sheet under the shell's test providers; every file it shows is
+a consumer-smoke fixture spec that passes under Vitest. `/mobile` is now the Capacitor how-to
+("Mobile: Capacitor setup"): peers, providers, the root host's height, `index.html`,
+`capacitor.config.ts`, the Android manifest, a tabbed app (routes, `bf-tabs`, `bf-stack-outlet`,
+`bf-page`), keyboard and Dynamic Type, and running on a device. Its files are fixture files under
+`tools/fixtures/consumer/src/mobile/`, which consumer-smoke's `mobile-full` step builds as one app;
+then the phone frame ("Try it") and a Reference of every `/mobile` export, linked. `/theming`
+("Theming and dark mode") shows the theme configurator inline beside a live preview, where the
+generated block goes, dark mode (`dark`, `color-scheme`, the body classes), following the OS and
+remembering the choice, app-wide and sub-tree token overrides, the radius tokens and fonts; the
+configurator's controls are now `app-theme-configurator-panel`, and the floating launcher shows a
+visible "Theme" label from `sm` (its accessible name stays "Theme configurator"). `/overlays`
+("Dialogs, menus and toasts on desktop") has live examples for confirming a delete, a Signal Forms
+form in a dialog, row actions in a menu and undo in a toast, and says when a Capacitor app uses the
+`/mobile` overlays instead. `/troubleshooting` lists seven known failures with cause, fix and link.
+The guide steps live in `consts/testing.const.ts` and `consts/capacitor.const.ts`, which the site
+and `UI_GUIDE.md` both render. The Install row of a `/testing` reference page reads
+`bun add @bitforgehq/ui && bun add -d @angular/cdk`. `fixture/…` example ids may hold dots
+(`fixture/testing/sheet.spec`).
+The Testing guide's Jest path: install `jest`, `jest-environment-jsdom`, `jest-preset-angular` and
+`@types/jest`, set `tsconfig.spec.json`'s `types` to `["jest"]`, and call
+`setupZonelessTestEnv()` before `installBfJsdomShims()` (a bare import of
+`jest-preset-angular/setup-env/zoneless` initialises nothing, so every spec failed with "Need to
+call TestBed.initTestEnvironment() first"); its `transformIgnorePatterns` keeps Angular's locale
+files (`@angular/common/locales/.*\.js$`). consumer-smoke now runs the testing specs, plus a
+`de-CH` locale spec, under Jest with the guide's `jest.config.mjs` and setup file written from the
+same consts. The Capacitor guide says `@capacitor/keyboard` is needed, since the required
+`capacitor.config.ts` imports `KeyboardResize` from it.
+
+The site navigation follows Diátaxis, from one source, `consts/nav.const.ts` (`NAV_GROUPS`, which
+replaces `guides.const.ts`): Get started (Install, Tutorial, Concepts), Guides (Forms and
+validation, Density, Labels and translation, Theming and dark mode, Dialogs, menus and toasts,
+Testing, Capacitor apps, Troubleshooting), Components, Foundations, Reference (API, For agents,
+Compatibility) and Changelog. No existing path changed. The header links Get started, Guides,
+Components, Reference and Changelog and marks the current group; the sidebar and the phone drawer
+show every group as a disclosure, open while it holds the current page; the footer mirrors the
+groups; search, the sitemap and `llms.txt` list the same pages. The home page is desktop first: a
+new subhead and six feature cards (forms and density, desktop overlays, theming, testing, agent
+docs, then the Capacitor shell), and the hero offers the `bun add @bitforgehq/ui` line with
+the version and a copy button. New pages: `/tutorial` ("Build a settings page", five compiled steps: the
+form, validation with the default messages, saving with a desktop toast, a "Delete account"
+confirm dialog and dark mode; consumer-smoke builds the five steps as one app against the packed
+library), `/concepts` (entry points and their peers, tree shaking, tokens, signals and Signal
+Forms, desktop versus Capacitor, client-only for 0.x, labels), `/compatibility` (the peer ranges,
+generated from `package.json`, the toolchain and Angular's supported browsers) and `/changelog`
+(this file, with a list of sections per version; anchors use the version number only, such as
+`#v0-3-0` and `#v0-3-0-migration`, so links survive the release). Each tutorial step is `SettingsComponent` (`app-settings`),
+saved verbatim as `src/app/settings.component.ts`, with step 5's
+`theme-preference.state.service.ts` beside it; consumer-smoke writes exactly those files and the
+page's `app.ts` into the fixture app and builds every step. The `/overlay` Install row now reads
+`@angular/cdk rxjs`, from the same entry point table as Concepts and Compatibility. The page keeps
+5 rem of scroll padding at the bottom, so the Theme launcher never covers a focused element.
+`deploy:docs` runs `ai:docs:check` first.
+
+Every route is prerendered (F-086): `ng build docs` (`outputMode: 'static'`, no SSR server)
+writes one HTML file per path of `app/site-routes.ts` (home, the navigation pages, one page per
+component and per reference symbol from the package indexes, and `/404`), the one list the
+sitemap, the hosting check and the e2e suite read too. Each page carries its own `<title>`,
+description, canonical link and Open Graph tags, and its content: a component page's body is
+prerendered and hydrates when the browser is idle, and the entry it was rendered with comes with
+the page (no second request, no loading state first). Unknown paths answer 404 with the "Page not
+found" page: `firebase.json` drops the catch-all rewrite (`trailingSlash: false`, `no-cache` on
+pages), and `tools/finalize-docs.ts` moves `404/index.html` to `404.html` and fails the build when
+a route has no page or no head of its own; an unknown component name or reference slug falls
+through to the `**` route, so it hydrates the 404 page as prerendered. Example cards load their
+Preview (the example chunk, or the phone frame) only as they near the viewport, and render and
+highlight their code only once the Code tab is first shown. Until then, and while its demo loads,
+a card's Preview keeps the height it last rendered at (`examples/example-heights.json`, measured
+at 412 and 1280 px by `bun tools/measure-examples.ts`), so nothing below it moves: CLS on
+`/components/input` drops from 0.101 to 0.074. A reference page fetches its own
+symbol, `reference/<slug>.json` (written by `ai:docs`; the largest is 8 kB), instead of the whole
+280 kB `REFERENCE.json`, which stays whole for agents. A custom theme from the configurator goes
+on before the first paint (its derived tokens are kept under `bf-docs-theme-tokens`), as dark mode
+already did, and `ThemeStateService` touches no storage on the server. The header's theme toggle
+renders both icons and `styles.css` shows the one `html.dark` calls for, so a dark-mode reader
+sees the sun icon from the first paint, not only after hydration. Every prerendered page
+preloads the fonts. The e2e suite fails on any Angular hydration message (`NG05xx`). A prerendered `/changelog`
+keeps its versions as prerendered and never hydrates them (`@defer (hydrate never)`), so
+`CHANGELOG.md` is neither fetched again nor inlined in the page (561 kB to 361 kB, 149 kB to
+85 kB gzip); its section links are same-page anchors there, and its code fences stay
+unhighlighted.
+
+Every page names a default Open Graph image, `og-image.png` (1200 × 630, with its alt text, as a
+`summary_large_image` card), so link previews show the brand instead of a bare title. It is
+rendered from `tools/og-image.html` (the docs tokens, Manrope, the favicon mark and the home hero's
+copy) by `bun tools/og-image.ts`, run by hand when the brand changes.
+
+Code is highlighted in a web worker (`services/highlight.worker.ts`), so compiling Shiki's
+grammars and tokenizing a page's code never blocks the main thread: Lighthouse's total blocking
+time on the install, forms and mobile pages drops from 270–580 ms to at most 10 ms. Without
+`Worker` it highlights on the main thread as before. A request the worker answers with an error
+is highlighted on the main thread alone; a worker that crashes or leaves a request unanswered for
+10 s is started once more, then highlighting stays on the main thread. `finalize-docs.ts` fails a
+build whose worker bundle imports a chunk the build did not write, and `tools/highlight-worker.test.ts`
+fails a dynamic `import()` in the worker's module graph.
+
+`bun run docs:hosting-check` serves the build in the Firebase hosting emulator (port 4402, a
+`demo-` project, no login) and checks every sitemap URL (200, its own title, description and
+canonical link), that unknown paths answer 404 with the "Page not found" page, and every link in
+`llms.txt` (F-083). `e2e/serve.ts` and Lighthouse answer like Hosting (`tools/static-resolve.ts`).
+Lighthouse now also audits `/components/input`, `/install` and `/forms` (F-091), from port 4410,
+keeping the median of three runs; a page may hold a conscious lower threshold in
+`PAGE_THRESHOLDS`, and none needs one.
+
+The deploy no longer ships `index.csr.html` (`finalize-docs.ts` deletes the unused
+client-rendering shell), the `/mobile-demo/` rewrite takes extension-less paths only, so a missing
+demo script is a 404 instead of the demo's HTML, and the hosting check proves both, stops at once
+when port 4402 already answers, and loads an embedded demo route.
+
+The ⌘K palette searches the full text of the site (F-084): every page and its sections, every
+component with its usage sections (the Keyboard tables included), inputs, outputs and methods,
+every reference symbol and its members, and "Not in Bitforge UI" hints for what the library does
+not provide (tooltip, table or data grid, date picker, combobox or autocomplete, rich text and
+charts), each pointing at what to use instead. Synonyms (dark mode, dropdown, modal, snackbar,
+validation, tailwind, capacitor) lead to the page that answers them. Results are grouped as Pages,
+Components, API, Sections and Hints, best match first; a section opens at its heading, and every
+result is a real link under the base href, so a modifier click opens it in a new tab. The index,
+`search-index.json`, is built after the prerender by `tools/gen-search-index.ts` from
+`MANIFEST.json`, `REFERENCE.json`, the prerendered pages and `consts/search-hints.const.ts`, and
+searched in the browser with MiniSearch. It is fetched once, when the palette first opens; until
+it arrives the palette filters page and component titles as before. `docs:hosting-check` checks it
+is served with its five-minute cache. A result is named by its title, the "Not in Bitforge UI"
+badge and its page, with its text as the description, so a screen reader reads a short name on
+each arrow press; group names are read in plain case; a pointer press keeps focus in the field;
+the field is `aria-expanded` only while there are results; a failed index fetch is retried on the
+next open; and a hint pointing at a page or section that is not indexed fails the build.
+
+A deep link opened from inside the site (a search result, a link to `/components/sheet#snap-points`)
+lands on its heading even when the content above it grows first: a scroll the browser makes as the
+page changes height no longer ends the hold on the heading, only a scroll of the user's does.
+
+The header's large-title collapse is proven in real browser engines (F-071): the new
+`e2e/header.spec.ts` runs on `iphone` (WebKit, iOS mode) and `pixel` (Chromium, Material mode)
+against the mobile demo's header showcase and reads the rendered page. At rest the large title is
+opaque and nothing is under the bar; half-way down its height (held, so the scroll-end snap waits)
+it is part-faded, the toolbar title not fully shown, no `data-bf-scrolled`, and the scroller's
+range is unchanged; nearly collapsed there is still no `data-bf-scrolled`; at the large title's
+height it is gone, the toolbar title shows and `data-bf-scrolled` switches on; back at the top the
+rest state returns. Halving the collapse range or switching the scroll-under trigger back to
+`scrollTop > 0` fails it.
+
+The docs site is checked in WebKit too (F-073): the new `docs-webkit` Playwright project runs the
+page, axe and search specs in Desktop Safari against the same build, so a regression only Safari
+shows fails CI. axe blocks at `moderate` impact on every page (F-077), with an allow-list that takes
+only third-party or iframe content, with a reason, and is empty; it also scans, in both themes, the
+⌘K palette empty, with results and with none, the phone navigation drawer at 390 px, the floating
+and the inline theme configurator, the Code tab of `/components/button` and `/components/sheet`,
+`/`, `/components/button` and `/mobile` under reduced motion, and the desktop overlays. Fixes it
+found: the site header is labelled "Bitforge UI", so its banner stays unique next to the embedded
+demo's; the palette's results scroller is in the tab order, so a keyboard can scroll a long list;
+the extra tab bars on `/components/tab-bar` are named ("Sections", "Feed"); and the phone frame
+writes its iframe `src` only when it changes, so hydrating `/mobile` no longer loads the embedded
+demo a second time (WebKit logged the aborted module scripts as errors). New e2e: a hard-loaded
+`/changelog#<version>` lands on its heading, and the changelog's "On this page" lists the versions,
+jumps to one and follows the scroll.
+
+The docs deploy from CI (F-083): `.github/workflows/docs.yml` verifies every push to `main` (the
+library build, agent docs, tools tests, the docs build, the docs e2e in Chromium and WebKit, the
+hosting check), then
+deploys that tested build to Firebase Hosting once the `FIREBASE_SERVICE_ACCOUNT_BITFORGE_UI` secret
+exists (without it the job prints a notice and skips) and to the GitHub Pages mirror once the
+`DOCS_PAGES_ENABLED` variable is `true`. `ci.yml` also runs the hosting check, and its Lighthouse
+step takes the median of five runs per page; `tools/lighthouse.ts` audits a page that misses a
+threshold once more before it fails. README "Docs deployment" lists the owner's steps. Both
+deploy jobs run only for `main` (a manual run on another branch verifies without deploying), the
+Firebase and Bun actions are pinned to commit SHAs, and the Pages job serves its sub-path build
+under `/BitforgeUI/` and checks its pages, base hrefs, linked assets and 404 before
+uploading (`tools/pages-check.ts`). The palette's results scroller is a group named "Search
+results".
+
+The docs initial bundle grew from 517.98 kB on main to 563.06 kB (139.45 kB transfer; +8.7 %),
+across the nav, prerender/hydration and search work above: the eager nav const and sidebar logic
+of the new site chrome (Task 7, ~+7 kB); `provideClientHydration(withEventReplay(),
+withIncrementalHydration())`, the SEO service and the deep-link fragment hold that ships with
+prerendering (Task 8); and the ⌘K search palette's trigger and result list (Task 9; MiniSearch and
+`search-index.json` themselves stay in the palette's own lazy chunk, loaded only on first open, not
+in this total). Lighthouse still scores ≥ 90 on every audited page. The `initial` budget warning
+(`angular.json`, docs project) is now 580 kB, down from 600 kB, so the next regression is caught
+with less headroom.
+
+The docs site's markdown pipe renders only markup that markdown itself generates (F-093): raw
+HTML, block or inline, renders as text (a bare `<kbd>` excepted, which the Keyboard tables use),
+and a link or image whose URL is not `http:`, `https:`, `mailto:`, relative or a `#fragment`
+renders as its text alone, also in inline mode (member descriptions in the API tables), and also
+when the scheme hides behind a character reference (`javascript&#58;`) or a tab. Together with
+the generator's raw-HTML refusal, an `<img onerror>` in a JSDoc line can no longer run on the site.
+
+New "Rendering" section on the Compatibility page: 0.x is client-rendered only, and what the
+server-render smoke (`tools/ssr-smoke.ts`) shows: all 27 fixtures (every root widget, `bf-icon`,
+`bf-number-input`, two `/mobile` pages and an `/overlay` dialog) render on the server without an
+error and 18 render identically twice; the list of the other 9 is built from the smoke's recorded
+results (`SSR_RECORDED`), and hydration stays unsupported and untested. The README and the UI guide
+gain a "Compatibility" section with the same text.
+
+New examples: the `bf-chip-group` page (`chip-group/overview`, `single`, `multiple`),
+`badge/count-label`, `progress/value-text` and `progress/indeterminate`, `field/help-and-error`
+and `textarea/max-rows`. The Foundations page lists the four pressed tokens, and the theme
+configurator derives `--color-primary-pressed` and `--color-primary-soft-pressed` (the fill 0.12
+darker in light mode, lightness 0.88 in dark; the soft tint at 0.86 / 0.40), with
+`primary-strong` searched to 4.5:1 on the soft pressed tint as well. The demo host spec queues
+`requestAnimationFrame` for every test.
+
+The Foundations page gains Focus, Motion and Z-index sections (F-061, F-062), and
+`docs/design/foundations.md` the same three tables. Focus states both treatments with their exact
+classes: controls `focus-visible:outline-hidden focus-visible:ring-4 focus-visible:ring-ring`
+(keyboard focus only, 4 px) and text-entry controls
+`focus:outline-hidden focus:border-primary focus:ring-2 focus:ring-ring` (any focus, because the
+caret field must show where typing goes), both ≥ 3:1 (WCAG 1.4.11) and the system outline under
+forced colours. Motion lists `--bf-duration-fast`, `--bf-duration-overlay`, `--bf-duration-push`,
+`--ease-ios`, `--ease-md` and `--ease-settle` with their users and the reduced-motion behaviour;
+Z-index lists `--bf-z-dim`, `--bf-z-sticky`, `--bf-z-tabbar` and `--bf-z-overlay`. The spacing
+steps list `--spacing-card-lg`. `tokens.const.spec.ts` fails when a `--bf-duration-*`, `--ease-*`
+or `--bf-z-*` declared in `theme.css` is missing from the tables, and checks the quoted focus
+classes against the class maps. New example `icon/filled` (Lucide icons with filled details).
+Focus also lists the local additions: the `bf-segmented` ring offset
+(`focus-visible:ring-offset-2 focus-visible:ring-offset-surface`) and its selected item's own
+forced-colours ring, and the outline variants' `focus-visible:border-primary`. Motion notes
+`DURATION_MD` (220 ms), the one duration without a CSS token because only Web Animations started
+from TypeScript use it (the Material fade-up, the refresher settle, the overscroll release).
+
+The `/mobile` guide gains the step "Match the system bars to the theme" (what the shell does,
+the `android:windowBackground` and `colors.xml` snippet, and the outcome per Android WebView
+version). "Run it on a device" now says that `cap run ios` cannot deploy on Xcode 27 (no
+Simulator.app) and shows the `xcodebuild`/`simctl` fallback, and passes `--target` to both
+`cap run` commands. The labels guide lists `expand`, `collapse` and `sheetPosition`. The system-bars step states the WebView ≥ 140 preconditions (`viewport-fit=cover`, `insetsHandling: 'css'`).
+
+New examples: `header/long-title` (a long title wrapping in a grown bar, the back text giving way)
+under the header's new "Large text and compact heights" section, and `list-item/long-text` (a
+wrapping row and a `truncate` row) under the row's new "Long text" section.
+
+The shell's `main` is named "Documentation" (`aria-label`), so it stays distinct from the embedded
+phone demo's own `main` landmark (axe `landmark-unique` checks across frames).
+
+New examples: `sheet/autofocus` (`autoFocus: 'first-field'`), `stack-outlet/bounded`
+(`maxLivePages`) and `stack-outlet/scroller` (a horizontal chips row in a stacked page, no
+directive).
+
+Every install surface shows `bun add @bitforgehq/ui`: the home hero, Install step 4 and each
+component and reference page's Install row with the entry point's peers; the generated
+`ai/UI_GUIDE.md`, `llms-full.txt` and package README follow. The header shows the version,
+`v0.3.0`. The repository is `https://github.com/bitforge/BitforgeUI`, and the GitHub Pages
+mirror serves under `/BitforgeUI/`.
+
+### agent docs
+
+`UI_GUIDE.md` has a new API conventions section: the output, value-control, name and type rules,
+and the deprecated 0.2 output names with their replacements.
+
+`UI_GUIDE.md`: Configuration covers when to set which density (desktop nothing, dense `sm`,
+Capacitor `fieldSize: 'lg'`), the hit-area rule and German labels; Forms covers
+`bf-number-input`, typed values (`T | null`, `compareWith`) and typed Reactive controls with
+default messages; a new Links item covers `a[bfButton]`, `bfAction` on cards and list rows, and
+the `nav` of links inside `bf-tabs`. `llms.txt` lists the two new guides. The package README gains
+a "Density and labels" paragraph.
+
+**type**: `MANIFEST.json` entries gain `primaryExample` (an example id: `<name>/overview`, or
+`mobile-demo/showcase/<name>` for a `/mobile` component) and `examples` (`{ id, title, file, source,
+preview }[]`: the primary example, then those the `docs.md` references). Migration for agents: read
+`examples[0].source` for a complete, compiled usage file; `example` stays the short `@example`
+snippet. The `ai/components/*.md` pages replace "Quick example" with "Example", the primary example's
+full source as a `ts` block, and expand every `<!-- example: <id> -->` marker into a `ts` block of
+that file.
+
+**type**: in `MANIFEST.json`, a usage, Theming, Accessibility or notes body now holds `<!-- example: <id> -->`
+markers where it held fenced `html`/`ts` snippets, and `examples` lists every example they place.
+Migration for agents: resolve a marker through the entry's `examples` (by `id`) for the full
+compiled file, or read the `ai/components/*.md` page, where every marker is already expanded.
+`bf-tab` and `bf-list-item` have their own `overview` and `usage`, no longer copies of `bf-tab-bar`
+and `bf-list`.
+
+**type**: the API now comes from the TypeScript checker and the Angular template parser
+(`tools/api-extract.ts`), not from initializer text. `MANIFEST.json` gains `schemaVersion: 2`.
+Members gain `expandedType` (the union with its aliases resolved, e.g. `'sm' | 'md' | 'lg' |
+undefined` for `BfSize | undefined`, only when it differs from `type`), `twoWay` (a `model()`,
+bind it `[(name)]`), `formControlled` (a `FormUiControl` member that `[formField]` sets) and
+`alias` (the public binding name of an aliased member). `slots` are `{ name, doc }[]` (they were
+`string[]`), each named once (the header's two default projections are one slot) with its
+`@slot` doc. Components gain `methods` (`{ name, signature, params, returns, doc }[]`). Identifier
+defaults resolve to their literal (`bf-stack-outlet`'s `name` is `'primary'`, not
+`PRIMARY_OUTLET`), and `bf-number-input`'s `id` is typed `string` (was `any`). Migration for
+agents: read `slots[i].name` where you read `slots[i]`; read `expandedType ?? type` for the
+allowed values; never bind a `formControlled` member next to `[formField]`.
+
+**type**: new `ai/REFERENCE.json` (every public symbol that is not a component: services,
+directives, classes, functions, tokens, constants, interfaces and types, with `signature`,
+`values`, `members`, `methods`, `selector`, `references`, `usedBy`, `alsoExportedFrom` and, for a
+directive with its own `docs.md`, `docs`), `ai/REFERENCE.index.json` (`{ name, slug, kind,
+entryPoint, summary }`) and one `ai/reference/<slug>.md` page per symbol (`BfSheetService` →
+`bf-sheet-service`, a constant keeps its underscores: `BF_LABELS` → `bf_labels`). The option
+interfaces carry the defaults the services apply (`@default`), and a table shows a property's
+default in place of "required" (`BfShellConfig.mode` reads `'auto'`). Migration for agents: look a
+service, directive, token or type up in `REFERENCE.index.json`, then read its
+`ai/reference/<slug>.md` page or its `REFERENCE.json` entry; a deprecated `/mobile` alias of an
+overlay symbol is listed on the overlay symbol under `alsoExportedFrom`.
+
+**type**: every component line of `llms.txt` links its agent page first, then its site page:
+`- [bf-button](<origin>/ai/components/button.md): <summary> ([docs](<origin>/components/button))`,
+and a new `## Reference` section lists every reference page by entry point in the same form.
+`llms-full.txt` appends the reference pages after the component pages. Migration for agents:
+follow the first link of a line for the markdown page, the `docs` link for the rendered page.
+
+The generator refuses to run on raw HTML outside code spans and fences (`<kbd>` excepted) in any
+JSDoc, `docs.md` or this CHANGELOG, naming the file and line (F-093, generator part): the site
+renders that markdown as HTML. The one offender, `bf-alert`'s `dismissLabel` doc, now says it in
+words. `tools/docs-contract.test.ts` requires an 8–15 word `@summary` and a `@since` on every
+exported symbol, a doc on every member, method, parameter and slot, and every export of every
+`public-api.ts` in `MANIFEST.json` or `REFERENCE.json`.
+
+The reference covers `@bitforgehq/ui/testing` too: `REFERENCE.json`, `REFERENCE.index.json`,
+`ai/reference/` and the `## Reference` section of `llms.txt` gain its group, and the site's `/api`
+index lists it after `/mobile`.
+
+**type**: `MANIFEST.json` entries, the site's `manifest/<name>.json` files and a directive's
+`REFERENCE.json` `docs` gain `whenToUse` and `desktop` (markdown, optional: the "When to use" and
+"Desktop" sections of its `docs.md`, which no longer appear in `usage`). The Keyboard table stays
+inside `accessibility` under `### Keyboard`. The `ai/components/*.md` pages follow the site's
+order (the example first, then a new "Overview" heading with the other selectors, the description
+and the overview, then When to use, the usage sections, Desktop, Theming, Accessibility, the API,
+Notes and Migration notes). A root-relative site link in a `docs.md` (`/components/menu`,
+`/api/bf-size`, `/density`) is made absolute (`https://bitforge-ui.web.app/components/menu`)
+everywhere the generator writes it: `MANIFEST.json`, `REFERENCE.json`, the site's
+`manifest/<name>.json` and the `ai/*.md` pages, so every link an agent reads can be followed. The
+site maps those links back onto its own base href. Migration for agents: read
+`whenToUse` to choose between widgets and `desktop` for desktop behaviour; a `usage` section named
+"Desktop" (the `/mobile` overlays) is now `desktop`.
+
+`UI_GUIDE.md` gains a `## Testing` section and a step-by-step setup in `## Mobile shell`, both
+generated from the docs site's guide consts (`<!-- testing -->` and `<!-- mobile-setup -->` in
+`tools/ui-guide.template.md`), with each file shown in full. The hand-written mobile setup text
+(the `capacitor.config.ts` block, `index.html`, text size and Android manifest bullets) is replaced
+by those steps; the content is the same, plus the root host's `block h-dvh`, the providers, a
+tabbed app and running on a device. `llms.txt` lists the four new guides.
+
+**type**: `llms.txt` follows the site navigation: its `## Guides` section becomes one section per group, in
+order (`## Get started`, `## Guides`, `## Components` with a `###` per component category under it,
+`## Foundations`, `## Reference` with the site's reference pages before the symbols by entry
+point, `## Changelog`), and it lists the new Tutorial, Concepts, Compatibility and Changelog
+pages. Migration for agents: find Install under `## Get started`, For agents under
+`## Reference` and Foundations under `## Foundations`, no longer under `## Guides`; a component
+category is now a `###` heading (`### Actions`), no longer a `##`. `bun run ai:docs` also writes the docs site's
+`consts/compat.ts` (`UI_PEERS`) from `package.json`.
+
+### tooling
+
+`bun run ai:docs` enforces one API naming convention (`PROJECT_GUIDE.md` "API conventions",
+F-016): outputs are past-tense events (no `on` prefix, no declared `xChange`), actions emit
+`clicked` (menu items keep `triggered`, the CDK's event, as a named exemption), every value control
+has exactly one `changed`, every component that renders a native input, select or textarea takes
+`label`, `ariaLabel` and `ariaLabelledby`, other names are `<part>Label` or (on an image) `alt`,
+and every union or object type of a public input, model or output, of a `Bf…Options`/`Bf…Config`
+property or of an interface they name is a named type exported from the entry (the written type,
+else the checker's, so a cast is caught). The pure check is `tools/api-conventions.ts`;
+`gen-ai-docs.ts` collects its facts from the extracted API, the checker and the template parser and
+refuses to run on a breach, listing `selector.member: rule`, and on an extraction with no component
+or output, a missing class or an unresolved signal type.
+
+New `bun run typecheck` type-checks every spec (the `tsconfig.spec.json` of `ui`, `web-demo`,
+`mobile-demo` and `docs`), the e2e suite and `tools/` with `tsc`, because Jest compiles specs with
+`isolatedModules` and never type-checks them. CI (`verify`) and `release.yml` run it right after
+the library build. The errors it found are fixed without relaxing a compiler option: bracket access
+on `Keyframe` in `transitions.spec.ts`, the `v`-flag pattern built with `new RegExp(…, 'v')` in
+`input.component.spec.ts`, a throwing `defined()` narrowing helper in `derive-tokens.spec.ts`,
+typed fixtures for the generic `bf-select`, `bf-radio-group` and `bf-segmented` specs, pattern
+labels in the dialog and toast harness specs, the router's third `canMatch` argument in two docs
+guard specs, and `EnvironmentProviders` accepted by the docs `renderExample()` helper.
+
+`stack-outlet.component.spec.ts` waits for no wall-clock time: the deferred transition start and
+the swipe's 600 ms back fallback run on Jest's fake clock (`onFakeClock()`), and the one remaining
+real `setTimeout` is a commented 0 ms macrotask yield for the fake history's popstate order. The
+web and mobile demo Jest projects fail below 60 % branch and 70 % function, line and statement
+coverage (they were at 0). `tools/release-tag.test.ts` pins that any pre-release suffix
+(`v1.2.3-rc.1`) publishes to `next` and that build metadata (`v1.2.3+build.5`) is rejected with the
+shape message; the `TAG` comment and the README's "Releasing" state both rules.
+
+New `tools/effect-usage.test.ts`: fails on an `effect()` in `src`, `mobile` or `overlay` that
+writes DOM or another object's state, unless the line carries `// effect-justified: <reason>`
+(three allowed: the shell's `<html>` class and the menu directives' writes into their own CDK
+host directives). It also flags property assignments on anything but `this`, lifecycle hooks and
+method calls with arguments on injected or queried objects. New `tools/ssr-smoke.ts` and `tools/ssr-smoke.test.ts`
+(in `test:tools`, which runs the smoke in a child process): renders a fixture per root widget,
+`/icons`, `/number-input`, `/mobile` and `/overlay` with `renderApplication()`, checks output each
+widget's own template renders (the native control, its role and state, the dialog panel), and
+compares which render and which are stable across two renders with the recorded `SSR_RECORDED`.
+
+The API convention treats `valueText` (a progress bar's `aria-valuetext`) as content, like
+`helpText`, not as a name input. The server-render smoke renders a `bf-chip-group` fixture
+(28 fixtures, 19 of them stable) and matches the native `<progress>` without its dropped role. `tools/measure-examples.ts`
+honours the `--port <n>` its usage line documents (it always used 4408).
+
+The mobile demo's `initial` budget warning (`angular.json`, the `mobile-demo` production and
+`embedded` configurations) is 630 kB, up from 610 kB. Its initial total grew from 606.72 kB at the
+start of this release's mobile-and-polish work to 622.10 kB (main 488.49 kB, styles 125.23 kB):
++10.3 kB came with the pressed states, contextual badge and progress text, help next to errors and
+the bounded textarea (`@bitforgehq/ui` JS +7.5 kB, CSS +4.0 kB, because `theme.css` generates the
+classes of every entry), the rest from the API naming aliases, the signal refactors and the icon
+`fill` bindings. The docs app stays at 570.40 kB of its 580 kB.
+
+It is now 650 kB, up from 630 kB: the initial total grew from 622.10 kB to 636.44 kB (main
+488.5 → 499.8 kB, styles 125.2 → 128.2 kB) with the mobile features of the same release: +5.7 kB
+for the sheet snap control, its Close button and announcements and the system bars, +4.8 kB for
+the measured header and the px tab bar, and +3.8 kB for the CloseWatcher Escape path, the bounded
+stacks and the `main` landmark. None of it is an accidental inclusion: every demo page is lazy,
+and the library code in `main` is the one `@bitforgehq/ui`, `/mobile` and `/overlay` module each
+that esbuild keeps whole in the initial chunk. The docs app stays at 573.38 kB of its 580 kB.
+
+Every `@deprecated` tag reads `<version> use <X>; removed in <version>`: the overlay core aliases of
+`/mobile` name their `@bitforgehq/ui/overlay` replacement (`use BfOverlayService from
+'@bitforgehq/ui/overlay'`), and the size aliases (`BfFieldSize`, `BfButtonSize`,
+`BfSegmentedSize`) and the card's `interactive`/`clicked` state the 1.0.0 removal Migrations 5 and
+12 promise. `tools/api-conventions.test.ts` checks the form over every non-spec `.ts` file of the
+library.
+
+New `tools/no-inline-svg.test.ts` (F-066): no `<svg` in the non-spec `.ts` and `.html` files of
+`projects/ui/{src,mobile,overlay,number-input,testing}`, the docs site (chrome, pages and
+examples), both demos and the OG image template; `projects/ui/icons` (`bf-icon`) is the only SVG
+renderer, with no exception. New `tools/lucide-attributes.test.ts` (F-065): collects every
+attribute each element type carries across all `lucide` icons and fails on one the `@case` blocks
+of `icon.component.ts` do not bind. The server-render smoke matches the spinner's ring instead of
+its SVG.
+
+`tools/effect-usage.test.ts` allow-lists `BfPlatformService`'s `SystemBars.setStyle()` call (the
+native bars are external to any view). `tools/guides.test.ts` checks that the mobile demo's
+Android window background matches the guide's snippet and the theme's `bg` tokens.
+`tools/docs-contract.test.ts` now derives `BfSheetComponent` as an interactive widget (its grabber
+button and hidden Close) instead of listing it by hand.
+
+New `e2e/large-text.spec.ts` (iphone and pixel): on Today, Projects, a pushed task and Me, at root
+font sizes 100 %, 200 % and 235 % and at a simulated Android font scale 2.0 (every `--text-*` token
+doubled, lengths unchanged, as Android's text zoom does), no header slot leaves the viewport or the
+bar, every tab label shows its text within two lines inside the bar, `--bf-tab-bar-inset-global`
+equals the bar's measured height plus its offsets (±1 px), and no list title is cut with an
+ellipsis unless its row sets `truncate`; in landscape (844×390, 915×412) Today and Projects render
+no large title and leave at least 60 % of the height to content. `e2e/header.spec.ts` now expects
+the full collapse, and the scroll-under state, at the large title's rendered height (the title
+still showing at 56 px).
+
+### packaging
+
+`theme.css` registers `@source './fesm2022/*.mjs'` instead of the whole `fesm2022` folder, so
+Tailwind scans the FESM code and skips the source maps beside it; the maps stay in the package for
+debugging. The consumer smoke's `widgets` build checks that its stylesheet still has
+`.bg-primary-soft`, a class only library code uses, and `tools/theme-source.test.ts` pins the
+glob.
+
+A pre-release heading without entries of its own (`## X.Y.Z-next.N`) is followed by one line
+naming the section that applies, `Pre-release of X.Y.Z: its changes are listed under "X.Y.Z
+(unreleased)" above.`, so a `next` installer reading the shipped CHANGELOG finds the notes.
+`tools/changelog.test.ts` checks that line, that the top heading is `(unreleased)` or dated with
+the `projects/ui/package.json` version, and that `### Migration` opens the top version and every
+unreleased version with breaks.
+
+First npm release: `@bitforgehq/ui` 0.3.0 is published to the `latest` dist-tag
+(`bun add @bitforgehq/ui`). `package.json`'s `repository.url` points at the new home,
+`git+https://github.com/bitforge/BitforgeUI.git` (private). The never-published `0.3.0-next.1` and
+`0.2.0-next.1` headings are folded into their versions, and the 0.2.0 and 0.1.0 headings read
+`(not published)`. `tools/release-tag.test.ts` pins that `v0.3.0` resolves to `latest`. The
+release checklist and README "Releasing" describe the 0.3.0 publish from `bitforge/BitforgeUI`
+(the `NPM_TOKEN` secret and `npm` environment, the `FIREBASE_SERVICE_ACCOUNT_BITFORGE_UI` secret,
+the `v0.3.0` tag, `latest` without provenance).
+
+## 0.2.0 (not published)
+
+### overlay core
+
+New overlay foundation of `@bitforgehq/ui/mobile` on the Angular CDK `Overlay` (no CDK dialog or
+bottom-sheet). `BfOverlayService.open(componentOrTemplate, options)` attaches the content in a
+global-positioned panel (`position`: `center` default, `bottom`, `top`, `fullscreen`; class
+`bf-overlay-panel` plus `panelClass`; scroll strategy as in the "Fixed" note below) over a `bf-overlay-backdrop` backdrop
+(a black scrim, `rgb(0 0 0 / 0.4)`, `0.6` under `.dark`, a new rule in `theme.css`; it fades out
+with the panel's exit, instantly under reduced motion); the panel gets `role` (default `dialog`,
+none for passive overlays), `aria-modal="true"`, `aria-label`/`aria-labelledby`/`aria-describedby`
+and `tabindex="-1"`, a CDK focus trap
+(`trapFocus`), focus on its first tabbable element (else the panel) and focus back to the
+previously focused element on close (`restoreFocus`). `Escape` (`dismissOnEscape`), a backdrop
+click (`dismissOnBackdrop`) and the hardware back button (priority `backPriority`, default 100,
+newest overlay first) close it. Only the topmost non-passive overlay (`BfOverlayStack.isTop()`)
+answers `Escape`, and it always claims the key: one that does not close on it (`dismissOnEscape:
+false`) swallows it, or runs `onEscape` instead, so it never reaches an overlay underneath. The content injects `BF_OVERLAY_DATA` and `BfOverlayRef`
+(`close(result?)`, `afterClosed: Promise<T | undefined>`, `closed` signal, `id`,
+`updatePosition()`); components get a `BfComponentOverlayRef` with `componentRef`; a template
+receives `{ $implicit: ref, data }`. `enter`/`exit` take WAAPI animations (default `fadeIn`/`fadeOut`;
+`close()` awaits the exit before detaching); `slideUp`, `slideDown`, `fadeIn`, `fadeOut` and `scaleIn`
+run 260 ms `cubic-bezier(0.32, 0.72, 0, 1)` and fall back to a 150 ms fade under
+`prefers-reduced-motion`. A `passive` overlay (toasts) has no backdrop, focus handling or back
+handler and leaves the page interactive. `BfOverlayStack` tracks the modal-like overlays (`count`,
+`depth` for `countsAsModal`) and, while any is open, sets `inert` and `--bf-modal-depth` on every
+registered page root; the outermost `bf-stack-outlet` registers its host (`registerRoot`) on init
+and unregisters on destroy. `provideBfShell()` provides both services.
+
+Fixed: outside the shell (no `BF_SHELL_CONFIG`, e.g. a desktop page), a non-passive overlay now
+uses the CDK `block()` scroll strategy, so the document no longer scrolls behind an open dialog,
+sheet or modal (the "scroll bleed" at 1280 px). Passive overlays (toasts) and every overlay inside
+the shell, whose document never scrolls, keep the `noop()` strategy.
+
+### sheet
+
+New `BfSheetService.open(componentOrTemplate, { snapPoints, initial, dismissible, data, ariaLabel })`
+in `@bitforgehq/ui/mobile`, a bottom sheet on the overlay core (`position: 'bottom'`, back priority
+100, not counted as a modal; slides up on open and down on close). It returns a `BfSheetRef`
+(extends `BfOverlayRef`) with `snapTo(index)` and a `snapIndex` signal; the content injects the
+caller's `data` as `BF_OVERLAY_DATA` and the ref as `BfSheetRef` and `BfOverlayRef` (a template
+gets `{ $implicit: ref, data }`). The `bf-sheet` container is a `bg-surface rounded-t-card
+shadow-floating` card with `pb-safe-bottom`, a 36 × 5 px `bg-control-off` grabber (`aria-hidden`,
+`ButtonText` under forced colors)
+in a 24 px `touch-none` handle row and a content region; its height is `--bf-sheet-height`, a snap
+point (fraction of `BfKeyboardService.restHeight()`, else `innerHeight`; default `[0.5, 0.92]`)
+re-applied on resize. Dragging the handle row, any `[data-bf-sheet-drag]` element or the content
+(below the top point, or downward at the top point while scrolled to 0) moves the sheet with
+Pointer Events under pointer capture and a non-passive `touchmove` guard: rubber-banded (30 %)
+above the top point, released onto the nearest point or, faster than 0.3 px/ms, the next one in
+the fling's direction; a release more than 25 % of the lowest point's height below it, or a
+downward fling from it, dismisses. The content scrolls (`overflow-y-auto`) only at the top point,
+`overflow-hidden` below it, always `overscroll-contain`. `dismissible: false` ignores the backdrop,
+`Escape` and downward dismissal and swallows the hardware back button while open. Settling is a
+260 ms WAAPI animation, instant under `prefers-reduced-motion` (the drag still tracks the
+pointer). The panel is `role="dialog"` `aria-modal` with `aria-label` (default "Sheet"), focus
+moves in and returns on close.
+
+Fixed: the handle row shows a `grab` cursor (`grabbing` while pressed) and the grabber darkens to
+`text-muted` on hover.
+
+Fixed (behaviour change): the soft keyboard no longer covers a sheet's focused field and actions.
+While the keyboard overlays the sheet's bottom edge (iOS with `Keyboard.resize: 'none'`, a mobile
+browser), `bf-sheet` is lifted by the covered height (an inline `translate`, bottom safe-area
+padding dropped, since the keyboard covers the home indicator); while the keyboard is up at all
+(also Android, where the WebView resizes and nothing is lifted) its height is capped at the
+keyboard's top edge minus the safe-area top minus 8 px (`max-height`), and the content region
+scrolls at every snap point, with `bfKeyboardAssist` revealing the focused control 24 px above the
+keyboard. The lift follows the keyboard with a 250 ms `translate` transition on the iOS curve
+(instant under `prefers-reduced-motion`), and is left alone once the sheet is closing. The snap
+heights (`--bf-sheet-height`) are unchanged, and a drag of a capped sheet starts from its rendered
+(capped) height, so it moves from the first pixel. Hiding the keyboard removes the lift and the
+cap together and at once (the drop is not animated, so a sheet at a snap point taller than the cap
+never has its top edge above the screen), so the sheet rests at its snap height again, and content
+left scrolled while the keyboard was up returns to its top when the keyboard hides below the top
+snap point (a drag between snap points without the keyboard keeps the scroll offset, as before).
+
+### modal
+
+New `BfModalService.open(component, { data, presentation, dismissible, ariaLabel })` in
+`@bitforgehq/ui/mobile`, a page-level modal on the overlay core (`position: 'fullscreen'`, back
+priority 100, no backdrop dismiss). `presentation: 'sheet'` (default) renders `bf-modal` as a card
+inset 12 px from the top (`bg-bg rounded-t-card shadow-floating`) and, in iOS mode only, counts as
+a modal, driving `--bf-modal-depth` on every registered `bf-stack-outlet` root (see
+`### stack-outlet`) so the page behind scales down (Material mode leaves it unscaled);
+`'fullscreen'` renders it edge to edge (`bg-bg`, no radius or shadow) and does not count towards
+that depth. iOS mode slides the frame up on enter and down on exit; Material mode fades it up 16 px
+on enter and down on exit (new `fadeUp`/`fadeDown` helpers in `overlay-animations.ts`). It returns
+the `BfOverlayRef<T>` the content also injects (with the caller's `data` as `BF_OVERLAY_DATA`) and
+closes with a result through; unlike `bf-sheet` there is no drag-to-dismiss, so the content needs
+its own close control. `dismissible: false` (default true) ignores `Escape` and swallows the
+hardware back button while open instead of closing or falling through to the page behind. Like
+`bf-page`, `bf-modal` provides a fresh `BfPageContext` so the content's own `bf-header`
+(`largeTitle="false"`, typically a close `bf-icon-button` in `start`) and `bf-content` work
+inside it. `provideBfShell()` now also provides `BfSheetService` and `BfModalService`.
+
+Fixed (behaviour change): a `presentation: 'sheet'` modal ends above the soft keyboard. While the
+keyboard overlays the card's bottom edge (iOS, a mobile browser), `bf-modal` gets an inline
+`padding-bottom` of the covered height, so the content's `bf-content` ends at the keyboard's top
+edge and its keyboard assist reveals the focused control there; it goes away with the keyboard. A
+`fullscreen` modal, and Android, where the WebView resizes, are unchanged.
+
+### toast
+
+New `BfToastService.show({ message, action?, duration, position })` in `@bitforgehq/ui/mobile`, a
+queued status pill on the overlay core opened `passive: true` (no backdrop, no focus trap, the page
+stays interactive and it never counts towards `BfOverlayStack.count()`). Only one toast shows at a
+time; later `show()` calls queue in order behind a timed toast and appear once it ends (a persistent
+one gives way, see the behaviour changes below). It returns a `BfToastRef` (`dismiss()`,
+`afterDismissed: Promise<'timeout' | 'action' | 'dismiss'>`) — the toast resolves `'timeout'` after
+`duration` ms (`0` keeps it up until `dismiss()` or its action; the default is 3000 without an
+action and 0 with one, see below), `'action'` when the optional action button is clicked (its
+`handler` runs first), and `'dismiss'` from `dismiss()`, whether the toast is showing or still
+queued. `bf-toast` is an ink `bg-text text-bg rounded-full shadow-floating` pill (message
+`line-clamp-2`, announced through `LiveAnnouncer`, see the "Changed" note below); the action renders
+as a plain underlined `text-bg` button rather than `bf-button`'s `text` variant, which has no
+contrast on the ink surface. `position: 'bottom'` (default) keeps 16 px clear of the floating tab
+bar (`--bf-tab-bar-inset-global` on `<html>`, see `### tabs`) and the soft keyboard, written live as
+`--bf-toast-keyboard`: `BfKeyboardService.height()` where the keyboard overlays the WebView (native
+iOS), `0` where the WebView already resizes (Android, the web); `position: 'top'` sits 16 px below
+the status bar instead, as a top margin (`mt-[calc(var(--spacing-safe-top)+var(--spacing)*4)]`)
+outside the pill: an earlier `pt-safe-top` on the host overrode the pill's own `py-3` (0 top padding
+on the web, about 50 px on a notched iPhone). Enter fades in with a 12 px slide from its anchored
+edge, exit is a plain fade; both collapse to a fade-only under `prefers-reduced-motion`.
+`provideBfShell()` now also provides `BfToastService`. The action button has a 44 px hit area
+(`min-h-hit px-3`) that reaches into the pill's padding (`-my-2.5 -mx-3`), so the pill keeps its 48
+px height and width.
+
+Fixed: the action button shows a pointer cursor and fades to 80 % opacity on hover.
+
+Changed: with the new tab-bar inset (see `### tabs`, which now includes 8 px above the bar) a
+bottom toast sits 16 px above the inset and so clears the floating tab bar by 24 px (was 16 px).
+
+Behaviour change: a toast with an `action` no longer auto-dismisses by default (`duration`
+defaults to `0` with an action, still `3000` without one; an explicit `duration` wins), so an
+"Undo" stays reachable for keyboard, switch and screen-reader users (WCAG 2.2.1). Every toast's
+timer pauses while the pointer is over it or focus is inside it and resumes with the remaining
+time. When a toast that holds focus closes (action or `dismiss()`), focus returns with
+`preventScroll` to the element it came from (the first `focusin`'s `relatedTarget`, else the
+element focused when it opened), if still in the page; before, it fell to `<body>`.
+
+Changed: toasts are announced through CDK `LiveAnnouncer` (`announce(text, 'polite')`, once per
+toast as it shows; the text is the message plus the action label). The `bf-toast` host no longer
+carries `role="status"`/`aria-live="polite"`: a live region inserted together with its text was
+not reliably announced. Tests locating the pill by `role="status"` should use `bf-toast`.
+
+Behaviour change: persistent toasts (`duration` 0, the default with an action) never block the
+queue — the next `show()` dismisses one, visible or still queued, resolving `'dismiss'` (the
+Material snackbar model; a timed toast still queues the next one). `Escape` while focus is inside a
+toast dismisses it (`'dismiss'`) and is claimed there. Focus returns only while the toast still
+holds focus at close time, to the element focused last outside it; once focus has fallen to the
+page body it is not moved to the element that was focused when the toast opened. The service ends
+every toast (timers and document listeners included) when its injector is destroyed, and the
+announcement joins a message ending in `:`, `;` or `,` to the action label with a space.
+
+### mobile entry
+
+New secondary entry point `@bitforgehq/ui/mobile`, the Capacitor app shell for phase 2. Its first
+export is `BfPlatformService` (`providedIn: 'root'`): `isNative` and `platform` (`'ios' | 'android' | 'web'`)
+read once from `Capacitor.isNativePlatform()`/`Capacitor.getPlatform()`; `mode` (`'ios' | 'md'`)
+derives the shell mode from the platform; `theme` is a writable `signal<'system' | 'light' | 'dark'>`
+(default `'system'`) persisted to `localStorage` under `bf-theme`; `dark` follows the OS `prefers-color-scheme` while
+`theme` is `'system'` and otherwise reflects the explicit choice, applied as the `dark` class on
+`<html>` in an effect. `@angular/cdk`, `@angular/router` and `@capacitor/core` are optional peers
+of the package that an app importing `@bitforgehq/ui/mobile` must install (a web-only consumer that
+never imports this entry does not need them); `lucide` is a required peer of the package, since
+`bf-back-button` renders a Lucide icon (see `### packaging`). `@capacitor/app`,
+`@capacitor/keyboard` and `@capacitor/haptics` are optional peers for apps that use those
+plugins. Widgets in `@bitforgehq/ui`/`@bitforgehq/ui/icons` still may not import from
+`mobile/` (lint-enforced); the mobile entry may import widgets.
+
+Added: `resolveShellMode(config, platform)` and `injectShellMode()` exports: the shell mode in
+effect (`config.mode`, or `BfPlatformService.mode()` for `'auto'`), the resolution the stack outlet,
+the modal service, `bf-header` and `bf-back-button` share, so apps can follow the same per-mode
+conventions (e.g. text vs icon header actions).
+
+### stack-outlet
+
+New `bf-stack-outlet`: a router outlet that keeps a stack of live pages instead of destroying the
+one you leave, implementing `RouterOutletContract` in place of `<router-outlet>`. A push slides
+the new page in and parks the previous one (`visibility: hidden`, `inert`, `aria-hidden`, detached
+change detector, scroll and state kept); a pop slides the top page out, destroys it and restores
+the page below with focus returned (`preventScroll`) to whatever had it. Push vs. pop is
+classified from the router's navigation trigger and the history positions the router records
+(`computed` resolution), so `replaceUrl`, redirects, refused guards, `history.go(-n)` and browser
+forward resolve correctly. A pop always goes back to the history entry before the page was pushed,
+in one step, even when the page added entries of its own (query-only or nested child
+navigations); a swipe whose history step does not pop the outlet slides the page back. Transitions follow `BfShellConfig.mode`: iOS is a 500 ms
+slide-and-parallax under a dimming layer with an edge-swipe-back (50 px left edge, Pointer Events,
+scrubs the pop's `currentTime`, completes on velocity or half-width, `Location.back()` on
+completion); Material is a 220 ms fade-up with no gesture; `prefers-reduced-motion` reduces both to
+a 150 ms cross-fade. `stackChange`, `transitionStart` and `transitionEnd` outputs report depth and
+transition state. `BfNavController` (root, `providedIn: 'root'`) exposes `forward()`, `back()`,
+`root()`, `canGoBack` and `depth` (see `### nav controller`; `back()` pops the top page in one
+history step); `withBfShellRouting()` sets
+`canceledNavigationResolution: 'computed'` so a refused back navigation stays in sync with the
+outlet. The outlet binds route params, query params and route data to its pages' inputs itself
+(`bindInputs`), so a parked page's `ActivatedRoute` staying stale after a pop is never a problem.
+Every primary outlet registers with `BfNavController` on init (`registerOutlet(outlet, level)`,
+`level` = number of stack outlets around it) and unregisters on destroy; it no longer registers
+a hardware back handler of its own.
+
+Multi-stack: inside `bf-tabs` (optional `BF_TAB_CONTEXT`) the outlet keeps one stack per tab key
+(`Map<tabKey, StackEntry[]>`). A navigation onto another tab key is a `switch`: the whole current
+stack is parked (every page hidden, `inert`, change detection detached), and the target stack is
+restored — its page for the URL re-activated (attached, visible, focus to its title) with any
+pages above it dropped — or started with a new page; no transition and no gesture. A `root`
+navigation into another tab replaces only that tab's stack. `depth`/`canGoBack` reflect the active
+stack, pops stay within it, and `stackChange` now emits `{ depth, tabKey }` (`tabKey` null outside
+`bf-tabs`). New public methods `lastUrlOf(tabKey)` (URL of a tab's top page), `popToRoot()` (goes back in
+history to the active stack's first page in one step; false when its position is unknown) and
+`scrollActiveContentToTop(behavior?)` (through the active page's `BfPageContext` scroller, which
+the outermost `bf-page` now registers with the outlet).
+
+Nested outlets: an outlet inside a page of another outlet (the outlet in `bf-tabs` on a tabs page
+hosted by the root outlet) keeps its stacks while the outer outlet parks that page. Each page gets
+a per-page host token that tells the outlets inside it whether the page is shown; when the router
+deactivates the inner outlet because the outer one pushed a page above its host (e.g.
+`/tabs/today/task/1` → `/gallery`), the inner outlet suspends instead of destroying its stacks,
+and when the outer outlet pops back it resumes the same page (same DOM nodes, every tab stack
+intact) without a transition. A history step that lands on another page of the inner stack pops
+within it as usual. The page shown by the inner outlet follows its host page's lifecycle: it gets
+`willLeave`/`didLeave` when the host is parked and `willEnter`/`didEnter` when it comes back
+(forwarded only on a real state change, so no duplicate events). An edge swipe is claimed by the
+innermost outlet that can pop — also while that outlet is mid-transition, where the swipe is
+ignored — so nested outlets never pop together.
+
+Modal depth: the outlet's host now carries a scale rule keyed to `--bf-modal-depth` (written by
+`BfOverlayStack` on every registered outlet root while a page-sheet `bf-modal` is open — see
+`### modal`): `transform: scale(calc(1 - var(--bf-modal-depth, 0) * 0.08))
+translateY(calc(var(--bf-modal-depth, 0) * 8px))`, `border-radius: calc(var(--bf-modal-depth, 0) *
+12px)`, a 260 ms transition on both (skipped under `prefers-reduced-motion`), `transform-origin:
+top center`. At depth 0 the rule is a no-op; each stacked modal scales the page stack down another
+8 % and rounds its corners another 12 px.
+
+### nav controller
+
+`BfNavController` keeps a registry of the primary stack outlets and their nesting level; `depth`
+and `canGoBack` follow the **deepest active outlet** (the innermost one whose page is shown: the
+tab stack inside `bf-tabs`, or the root outlet once it pushed a page above the tabs page), and
+`back()` pops the deepest active outlet that has a page to pop, with that outlet's one-step
+history logic. It registers the priority-0 hardware back handler once (instead of one per
+outlet): it pops while an active outlet has more than one page and lets `BfBackButtonService`
+exit the app only when every active outlet is at depth ≤ 1 (a parked outlet cannot be popped, so
+it never blocks the exit). `setDepth()` and `registerPopTarget()` are replaced by
+`registerOutlet(outlet, level)` (called by `bf-stack-outlet`). Fixes a page pushed on the root
+outlet above the tabs page reporting depth 0 (hardware back exited the app) and destroying every
+tab stack, and `nav.root()` from inside the tabs leaving the root outlet without a pop target.
+
+### page
+
+New `bf-page`: the page frame (`absolute inset-0 flex flex-col bg-bg`) that `bf-stack-outlet`
+positions one of per stacked page. Injects the per-page `BfViewLifecycle` the outlet provides
+(falling back to a local, inert instance when used standalone, e.g. in a docs demo) and re-exposes
+it as `viewState` (`computed`) plus outputs `bfViewWillEnter`, `bfViewDidEnter`, `bfViewWillLeave`,
+`bfViewDidLeave`, delivered synchronously through `BfViewLifecycle.on()`: a new page gets
+`bfViewWillEnter` and `bfViewDidEnter` (also the first page, without animation and after
+`nav.root()`), and a popped or root-replaced page gets `bfViewWillLeave` and `bfViewDidLeave` before
+it is destroyed. Carries no `tabindex` itself; the outlet still owns push/pop focus
+management on its own wrapper.
+
+`bf-page` now provides a per-page `BfPageContext` (`providers: [BfPageContext]`) whose `scroller`
+signal (`HTMLElement | null`) is where `bf-content` registers its scroll container on init and
+clears it on destroy, so `bf-header` can follow the page's scroll without querying the DOM. Its
+`headerHeight` signal (px, 0 by default) is where a `translucent` `bf-header` publishes its
+expanded height for `bf-content` to pad by.
+
+Inside `bf-stack-outlet`, the outermost `bf-page` of a stacked page also registers its
+`BfPageContext` with the outlet (a nested `bf-page` leaves it), so the outlet can scroll the page's
+content to the top when its tab is re-selected.
+
+### back-button
+
+New `bf-back-button`: a `bf-icon-button` (`text` variant, chevron-left) that pops the primary
+stack via `BfNavController.back()`, or replaces it with `defaultHref` via `nav.root()` when there
+is nothing to pop back to (a deep link landing directly on the page). Visible when
+`nav.canGoBack()` or `defaultHref` is set, hidden otherwise. `label` (default `"Back"`) is the
+button's accessible name.
+
+Changed: the anatomy follows the shell mode (resolved like `bf-stack-outlet`). iOS: a native
+button with a 24 px chevron-left and `label` as visible text (`text-heading`, regular) in
+`primary`, one 44 px tall control (`h-11 min-w-hit`, text truncated past 192 px), named by its
+text. Material: a bare 24 px arrow-left `bf-icon-button` (`text` variant) with `label` as its
+`aria-label`. `defaultHref` works the same in both.
+
+New `BfBackButtonService` (`providedIn: 'root'`, registered and started at bootstrap by
+`provideBfShell()`'s environment initializer, together with `BfPlatformService`): the hardware
+back button queue. `register(priority, handler)` returns an unregister function; `dispatch()`
+(public, for tests and 2c's overlays) runs the registered handlers from highest to lowest priority
+until one returns true (on equal priority the newest registration runs first, so stacked overlays
+close top-down), then falls back to `App.exitApp()`; `BfNavController` registers the priority-0
+handler that pops the deepest active stack while any stack has more than one page. On native Android it subscribes to
+`App.addListener('backButton', …)` via `await import('@capacitor/app')` in a try/catch (never a
+static import, so a web or iOS bundle never loads the plugin); nothing is registered on iOS or
+web, where `Escape` closes overlays instead.
+
+### horizontal-scroll
+
+New `bfHorizontalScroll`: an attribute directive (`touch-pan-x touch-pan-y` host classes plus a
+`data-bf-horizontal-scroll` marker) that opts a chips row or carousel back into horizontal panning
+inside a `bf-stack-outlet` page. The outlet host is `touch-action: pan-y`, and its pages inherit
+that constraint down to their own scroll containers, so the edge swipe-back can claim horizontal
+drags. It only sets `touch-action`; the outlet's edge guard does
+not inspect the attribute, since the swipe only arms inside the 50 px left-edge zone, where it
+always wins regardless of what's under the finger.
+
+### content
+
+New `bf-content`: the page's single scroll container (host `block min-h-0 flex-1`, scroller
+`h-full overflow-y-auto overscroll-contain touch-pan-y pl-safe-left pr-safe-right` with
+`padding-bottom: var(--bf-tab-bar-inset, 0px)`, plus `pt-safe-top` when `fullscreen`, otherwise
+`padding-top` and `scroll-padding-top` of `var(--bf-header-height, 0px)`, a variable it writes on
+its scroller from `BfPageContext.headerHeight` while a `translucent` header is drawn over it). It applies
+`bfKeyboardAssist` to its scroller (`keyboardAssist`, default `true`), emits `scrolled`
+(`{ scrollTop }`) from a passive listener only while `scrollEvents` is true, offers
+`scrollToTop(behavior = 'smooth')`, `scrollToPoint(x, y, behavior)` and a `scrollElement` getter,
+and registers its scroller in the page's `BfPageContext`.
+
+Changed: the projected content now sits in a plain block body inside the scroller. In iOS mode
+(`BfPlatformService.mode()`) the body is `min-h-[calc(100%+1px)]`, so the scroller always overflows
+by 1 px and WebKit rubber-bands short pages too (it only bounces an overflowing scroller); in
+Material mode the scroller carries `bfOverscrollStretch`, the Android edge stretch the WebView does
+not draw. `bf-refresher` without a page context now tracks its nearest scrolling ancestor (past
+the body wrapper) instead of its parent element. The stretch stays off in iOS WebKit (Safari or a
+home-screen app, where Capacitor reports platform `web` and the mode is Material, detected from an
+`iPhone`/`iPad`/`iPod` user agent or `MacIntel` with more than one touch point), which rubber-bands
+natively, so the two never stack.
+
+Migration: the body's height is `auto`, so children that filled the scroller with `h-full` (a
+centred empty state) now collapse, and `min-h-full` or a `flex-1` inside a wrapper sized that way
+collapses too. Size such a child from its content or the viewport on your own wrapper
+(`min-h-[60dvh]`), not with `h-full`. The overscroll (the iOS bounce, the Android stretch and the
+refresher's iOS bounce mode) follows the engine (`BfPlatformService.mode()`), not
+`provideBfShell({ mode })`: Chrome never reports a negative `scrollTop`, so an Android app forced
+into the iOS look keeps the stretch and the material pull.
+
+Fixed: the scroller's bottom padding also adds `--bf-header-collapse`, the height a solid
+`bf-header` has collapsed by (`pb-[calc(var(--bf-tab-bar-inset,0px)+var(--bf-header-collapse,0px))]`,
+replacing `pb-(--bf-tab-bar-inset,0px)`), so the scroll range stays constant while the large title
+collapses. The keyboard assist's inline `padding-bottom` still overrides it while the keyboard is up.
+
+### header
+
+New `bf-header`: a 44 px toolbar (`pt-safe-top`, `start` | title | `end` slots, `bfSlot="start"` /
+`bfSlot="end"`) and, with `largeTitle` (default `true`), a Meadow Sage large title
+(`text-display`) below it with an optional `subtitle` eyebrow (`text-caption text-text-muted`)
+above the title. Exactly one `h1` carries `data-bf-page-title`, the focus target `bf-stack-outlet`
+moves to after a push — the large title's when `largeTitle` is true, the toolbar's otherwise; with
+`largeTitle`, the toolbar shows a second, `aria-hidden="true"` `span` mirror of the title for the
+visual collapse only. `title` empty projects the default-slot content into whichever `h1` is
+active instead. Reads its sibling scroller from the page's `BfPageContext` (set by `bf-content`)
+through an `effect`: once non-null it attaches a passive `scroll` listener that maps the first
+56 px of scroll to `--bf-header-progress` (0…1, 3 decimals, written to the host only when it
+changes) and detaches on scroller change or destroy. That variable drives the large title's
+opacity and an 8 px upward translate, the toolbar mirror's fade-in and a `divider` hairline that
+fades in with it; the same listener sets the large title block's height to its natural height (measured
+after render and on `ResizeObserver` changes, never per frame) times `1 − progress`, so at
+progress 1 the header is exactly the toolbar. Scrolling schedules no Angular change detection;
+`prefers-reduced-motion` drops the translate. Solid (default), the header is in the page's flow on
+`bg-bg`; `translucent` draws it over the content (`absolute inset-x-0 top-0 z-(--bf-z-sticky)`,
+`bg-bg/85 backdrop-blur`) and publishes its expanded height in `BfPageContext.headerHeight`, which
+`bf-content` pads its scroller by. The large title block is inset by the 16 px screen gutter
+(`px-gutter`, was `px-5`), so it lines up with page content padded the same way.
+
+Fixed: the large title no longer sits half-collapsed or collapses during a rubber-band. The
+progress is computed from `scrollTop` clamped to `[0, scrollHeight − clientHeight]`, so overscroll
+past either end never moves the header, and stays 0 on a page that cannot scroll the full 56 px
+(such as a short iOS page, whose body overflows by only 1 px). When a scroll ends part-way
+(`scrollend`, or 120 ms without a `scroll` event, whichever comes first) with no touch or pointer
+down on the scroller (passive `touchstart`/`touchend`/`touchcancel` and
+`pointerdown`/`pointerup`/`pointercancel` listeners), the header scrolls the scroller to 0 below
+half-way, else to 56 px (`behavior: 'smooth'`, `'instant'` under `prefers-reduced-motion`). The
+snap's own scroll never schedules another, and it is skipped while `BfKeyboardService.visible()`
+is true, on a page hidden by `visibility` (`checkVisibility({ visibilityProperty: true })`) and
+after destroy; its timer is cleared on scroller change and destroy. A mouse released outside the
+scroller is heard on the `document` (`pointerup`/`pointercancel`, listened to only while a press
+is tracked), and a press released without a scroll in between (a tap) schedules no snap.
+
+Fixed: on a page whose rest scroll range lies between 56 px and 56 px plus the large title's
+height, the header flipped between open and part-collapsed on every frame (measured on a search
+page at 393 × 800: `scrollTop/max@progress` `40/72@0 → 35/35@0.714 → 40/72@0 …`): the collapse made
+the scroller taller, the range fell under 56 and the short-page rule reset the progress. The header
+now writes the collapsed height (`largeHeight × progress` in px, the exact height the block gave
+up; `0px` at rest, when translucent or without a large title) as `--bf-header-collapse` on the
+page's scroller together with `--bf-header-progress`, and removes it on destroy (or from a
+replaced scroller); `bf-content` pads the scroller's bottom by it, so `scrollHeight − clientHeight`
+stays the rest range and the short-page rule and the clamp read one stable value.
+
+Fixed: the centred toolbar title sat in the space left between the `start` and `end` slots, so a
+back button or an avatar pushed it off the bar's centre. It is now laid out over the whole toolbar
+row (`absolute`, `pointer-events-none`, truncating) with symmetric insets: the header measures both
+slot containers with its `ResizeObserver` and writes `--bf-header-title-inset` (the 8 px row
+padding + the wider slot's width + 8 px; 16 px without slots) on its host, which the title box
+uses for `left` and `right`.
+
+Changed: the bar follows the shell mode (`provideBfShell({ mode })`, the platform's for `'auto'`,
+resolved like `bf-stack-outlet`; the host carries `data-bf-mode`). iOS: a 44 px bar with the
+title (`text-heading font-semibold`, the closest step to UIKit's 17 pt semibold) centred on it.
+Material: a 64 px bar with the title (`text-heading font-normal`, 18 px, the closest step to
+Material's 22 dp regular title) leading after the `start` slot, 16 px from the edge without one,
+never centred. The large title stays left-aligned and collapses the same way in both modes.
+
+Changed: scroll-under appearance. The scroll listener also sets `data-bf-scrolled` on the host
+while content is under the bar: with a large title once it has fully collapsed (progress 1; like
+UIKit, the large title is part of the scroll-edge bar, so a page too short to collapse never gets
+it), without one (`largeTitle` false) while `scrollTop` (clamped, so a rubber-band past the top does
+not count) is above 0, on any page length. iOS: opaque `bg-bg` at rest; scrolled under, `bg-bg/85` with `backdrop-blur-xl` and a 1 px
+`border`-coloured hairline under the whole header (the host's `::after`, so the header's height
+never changes; it replaces the `divider` hairline that faded in with the collapse). Material: no
+hairline ever; scrolled under, a `surface-muted` tint with a 150 ms colour transition
+(`motion-safe`) and no blur. `translucent` keeps its meaning (drawn over the content, which
+`bf-content` pads) and now takes the same per-mode surface instead of a permanent
+`bg-bg/85 backdrop-blur`.
+
+Changed: the large title's exit is spelled in utilities instead of component CSS (the header has
+no `styles` any more): inside the collapsing clip the block fades (`opacity: 1 − progress`) and
+rises 8 px (`translateY(−8px × progress)`, `motion-safe` only, so reduced motion keeps the fade
+and drops the rise), and the toolbar mirror fades in (`opacity: progress`), all read from
+`--bf-header-progress`, never transitioned.
+
+### keyboard-assist
+
+New `bfKeyboardAssist` directive for a scroll container: on keyboard will-show it sets
+`padding-bottom` to the covered part of the container (`max(0, bottom − (restHeight −
+keyboardHeight))`) and `scroll-padding-bottom` to that plus `bfKeyboardAssistMargin` (default 24),
+then scrolls the focused `input`, `textarea` or `[contenteditable]` until it sits the margin above
+the keyboard — on the container's first `scroll` event after will-show or after 120 ms, whichever
+comes first (after WebKit's own focus scroll), with one instant correction at did-show and the same
+delayed reveal on `focusin` while the keyboard is open. The covered part is measured again at
+did-show and on every window or `visualViewport` resize while the keyboard is up, so on Android,
+where the WebView shrinks about 20 ms after will-show, the padding ends at 0. Both paddings and any
+pending reveal are removed on hide; non-text controls are ignored. `bfKeyboardAssistBehavior` is `'smooth'` (default)
+or `'instant'`; `[bfKeyboardAssist]="false"` turns it off.
+
+Fixed: over-scroll on Android and padding left behind on parked pages. The covered part is now
+`max(0, bottom − BfKeyboardService.keyboardTop())`, so a WebView that has already shrunk at
+will-show gets no padding (it was padded by the whole keyboard, and the engine's focus reveal
+honoured the inflated `scroll-padding-bottom` and pushed the field under the header). A hidden host
+(`checkVisibility({ visibilityProperty: true })` false, so a parked page's `visibility: hidden`
+counts) gets no padding or reveal, drops an earlier padding and cancels a pending reveal;
+every window or `visualViewport` resize measures again whether or not the keyboard is up, so a
+padded scroller always ends at 0. The reveal now waits for the scroller to settle (100 ms after its
+last `scroll` event, 120 ms if none arrives, at most 400 ms) and scrolls once from the settled
+rects; the did-show correction also waits for quiet and is skipped while a reveal is pending.
+
+Fixed: in a container too short for the focused control and both margins (a sheet or modal
+capped by the keyboard in phone landscape), the reveal and the did-show correction no longer
+ping-pong between the two edges and leave the control clipped or 2 px into the keyboard gap: the
+gap above the control shrinks first, then the one above the keyboard, and a control shorter than
+the container stays whole (a taller one keeps its bottom at the keyboard's top edge). With room
+for both margins nothing changes.
+
+New `refresh()`: measures the covered part again and, while the keyboard is up, corrects the
+reveal once, for a container that moves with the keyboard outside the keyboard events (`bf-sheet`
+calls it when its lift transition ends, so a padding measured while the sheet was still sliding up
+does not stay behind).
+
+### overscroll-stretch
+
+New `bfOverscrollStretch` directive for a scroll container: Android-style edge stretch, since an
+Android WebView draws no overscroll effect for an inner scroller. A vertical touch drag past the
+top or bottom edge scales the container's first element child with `scaleY(1 + 0.14 × (1 −
+e^(−pull / 240)))` from that edge (`transform-origin: center top` / `center bottom`,
+`will-change: transform` during the gesture) and springs it back on release with the Web
+Animations API (220 ms, `SETTLE_EASING`; instant under `prefers-reduced-motion`), then clears its
+inline styles. Passive touch listeners only, never `preventDefault`; the axis is decided after
+8 px and a horizontal-dominant gesture is ignored; the top edge is skipped while an enabled
+`bf-refresher` (`[data-bf-refresher]`) is inside the container. `[bfOverscrollStretch]="false"`
+leaves it inert. The gesture follows the finger that started it (by `Touch.identifier`) and ends
+when that finger lifts; other fingers are ignored.
+
+### keyboard service
+
+New `BfKeyboardService` (`providedIn: 'root'`, registered and started at bootstrap by
+`provideBfShell()`): `height`, `visible`, `phase` (`'hidden' | 'showing' | 'shown'`),
+`overlaysContent` (true on native iOS), `restHeight`, `willShow` (a counter that increments on every
+will-show) and `hide()`. On native it loads `@capacitor/keyboard` with a dynamic import (a silent
+no-op without the plugin) and listens to will/did show/hide; either hide event moves straight to
+`hidden`, because iOS can deliver `keyboardDidHide` before `keyboardWillHide`. On the web it falls
+back to `visualViewport` resizes with an 80 px threshold; in Jest and SSR it is inert. `restHeight`
+comes from a fixed `100lvh` probe element appended to `document.body`, never `innerHeight`. The
+height is also written as `--bf-keyboard-height` on `<html>` (`0px` while hidden, removed on
+destroy).
+`hide()` calls `Keyboard.hide()` on native and blurs the focused element on the web.
+
+Added `imminent`, a signal that is true from `focusin` on a text-entry control until its
+`focusout` or either keyboard hide event (never cleared by will-show): on Android the WebView
+shrinks before the plugin's `keyboardWillShow`, so chrome such as the tab bar hides on
+`visible() || imminent()`. When it turns true with the keyboard down it also clears itself after
+2500 ms if neither will-show nor a visible keyboard arrives, so a hardware keyboard (iPad Magic
+Keyboard, a simulator with the host keyboard), which fires no keyboard event, no longer keeps the
+tab bar hidden while a field has focus. Added `keyboardTop()`, the keyboard's top edge in viewport px
+(`restHeight() − height()` on native iOS, the bottom of `visualViewport` — else `innerHeight` —
+where the viewport shrinks, `restHeight()` while hidden). `isTextEntry(element)` is now exported.
+Fixed: the rest height is no longer measured at will-show, where the Android WebView has already
+shrunk (it read 554 instead of 866 px and made `bfKeyboardAssist` over-scroll); it is measured at
+construction and on window resizes while the keyboard is hidden and no text control is focused.
+
+Fixed: on the web, a pinch-zoomed visual viewport (`visualViewport.scale` more than 0.01 from 1)
+is never read as a keyboard, so zooming a web build (zoom stays on there) no longer lifts sheets or
+pads scrollers; zooming in with the keyboard up reports it hidden until the page is back at 1×.
+
+### refresher
+
+New `bf-refresher`: pull-to-refresh, placed as the first child of `bf-content`. It tracks Pointer
+Events on the page's scroller (read from `BfPageContext`, falling back to its own parent element)
+only while `scrollTop === 0`. A press by itself changes nothing; only once a move clears an 8 px
+downward slop (out-vertical'ing any horizontal travel) does it claim the gesture, capture the
+pointer on the scroller, and start resisting the drag at `delta * 0.5` (capped at 72 px) into a
+40 px `bg-surface shadow-raised rounded-full` disc holding a `bf-spinner`, from a resting −48 px
+up to a 64 px threshold — so a plain click on the content underneath (a row, a button) still
+reaches it. Crossing the threshold ticks `BfHapticsService.impact('light')` once; releasing past
+it sets `refreshing` (a readonly signal), parks the disc at 0 and emits `refresh` with `{
+complete: () => void }` — releasing before the threshold animates the disc back to rest instead.
+`complete()` animates the disc away and clears `refreshing`, after which the next pull starts
+working again; `disabled` stops tracking pulls entirely, and further pulls are ignored while
+already `refreshing`. The park/settle/`complete()` transitions use the Web Animations API;
+`prefers-reduced-motion` only skips those — the disc still tracks the pointer 1:1 during the pull
+itself, since direct manipulation isn't motion. For touch, a non-passive `touchmove` guard,
+attached only while a press is tracked, prevents a downward drag at the top (and every move once
+claimed) so the browser does not take it as a pan and cancel the pointer stream; upward drags keep
+scrolling. Only the scroller's own `lostpointercapture` ends a pull, not the bubbling one from the
+row that held the touch's implicit capture. The disc (with its spinner) is `aria-hidden` and
+`visibility: hidden` until a pull is claimed (so its shadow never bleeds above the content); a
+separate, permanent visually hidden `role="status" aria-live="polite"` region is empty at rest and
+reads "Refreshing" while a refresh runs. It never touches the scroller's `overscroll-behavior`.
+
+Changed: on iOS a touch rides the native bounce. In iOS mode (`BfPlatformService.mode()`) a touch
+press (`pointerType === 'touch'`, or a `touchstart`, tracked with passive listeners) is not
+claimed — no pointer capture, no `preventDefault`, no `touchmove` guard — so the scroller
+rubber-bands natively. While a finger is down, passive `scroll` events with a negative `scrollTop`
+show the disc at its resting −48 px, inside the gap the bounce opens, once `−scrollTop > 8`, with
+`opacity` = progress and `scale(0.6 + 0.4 × progress)` (progress = `min(1, −scrollTop / 64)`) and
+one light haptic at 1. Lifting the last finger at `−scrollTop ≥ 64` sets `refreshing`, settles the
+disc to 0 and emits `refresh`; otherwise the disc hides. A negative `scrollTop` with no finger down
+(a fling's overshoot) never shows it. Material mode and a mouse or pen in iOS mode keep the pull
+unchanged. The host carries `data-bf-refresher` while not `disabled`. A pen press in iOS mode,
+which also fires touch events, never starts a bounce, so its trailing `touchend` cannot hide the
+parked disc; the bounce writes the disc's styles only when it shows, changes or hides, not on
+every scroll; and a scroller change or destroy mid-bounce resets the disc's `opacity`, `transform`
+and `visibility`.
+
+### haptics service
+
+New `BfHapticsService` (`providedIn: 'root'`, registered by `provideBfShell()`): `impact('light' |
+'medium' | 'heavy')`, `selection()` and `notification('success' | 'warning' | 'error')`, all
+`Promise<void>`. On native it loads `@capacitor/haptics` with a dynamic import (cached after the
+first call) and forwards to `Haptics.impact()`, `Haptics.selectionChanged()` and
+`Haptics.notification()`; on the web, and when the plugin fails to load, every method resolves as
+a silent no-op without importing anything.
+
+### tabs
+
+New `bf-tabs` (`tabsPath` required input): the tabs page with one navigation stack per tab. It
+provides `BF_TAB_CONTEXT` (`tabKey` signal from `NavigationEnd.urlAfterRedirects`, `keyOf(url)` =
+the primary segment after `tabsPath`, parsed with `Router.parseUrl`, so query, fragment, matrix
+params and auxiliary routes are ignored) to the projected `bf-stack-outlet`, sets the
+projected `bf-tab-bar`'s `active` to the tab key, and handles its selections: another tab navigates
+with `nav.forward()` to where that tab was left (`outlet.lastUrlOf(key)`, else `/<tabsPath>/<key>`)
+and, once it has succeeded, `BfHapticsService.selection()` when `hapticsOnTabChange`, putting the
+bar back (without a haptic) if a guard refuses; the active tab again (`tabReselect`) at depth > 1 pops the stack to its existing root page
+(`outlet.popToRoot()`, one `Location.historyGo(-n)` step computed from the outlet's history
+positions, so the root keeps its DOM, scroll and state), falling back to
+`nav.root(['/', tabsPath, key])` when the position is unknown; at depth 1 it scrolls the active
+page's content to the top. It hides the bar while
+`BfKeyboardService.visible()` (`setHidden()`, animated on iOS only, instant on Android and the web) and writes
+`--bf-tab-bar-inset` on its host: `calc(64px + 24px + var(--spacing-safe-bottom))` while a bar is
+present and visible, `0px` otherwise. The same value is mirrored on `<html>` as
+`--bf-tab-bar-inset-global` for overlays, which render outside the host (the toast reads it), and
+removed on destroy; `bf-content` keeps reading `--bf-tab-bar-inset`, so a page outside `bf-tabs`
+gets no bottom padding.
+
+Fixed: on Android the bar flashed above the keyboard, because the WebView shrinks (lifting the fixed
+bar) before `keyboardWillShow`. The bar now hides on `BfKeyboardService.visible() ||
+BfKeyboardService.imminent()`, i.e. already on `focusin` of a text control.
+
+Fixed: an empty `tabsPath` (the tabs mounted at the root URL) built `['/', '', key]`, a doubled
+slash the router turned into a broken navigation. `onTabChange` and `onTabReselect` now build the
+command array from the non-empty segments of `tabsPath`, so `['/', key]` results when it is empty.
+
+Changed: `--bf-tab-bar-inset` (and `--bf-tab-bar-inset-global`) follows the bar's new position:
+`calc(64px + 8px + max(var(--spacing-safe-bottom), 12px) + 8px)` (the bar's height, its offset of
+8 px above the safe area with a 12 px floor, and 8 px of room above the bar; 114 px on an iPhone
+with a home indicator, was 122 px), replacing `calc(64px + 24px + var(--spacing-safe-bottom))`.
+
+Fixed: the inset counts the bar's height in `rem` (`calc(4rem + 8px + max(var(--spacing-safe-bottom),
+12px) + 8px)`), like the bar's own `h-16`. With iOS Dynamic Type (`BfTextScaleService`) the bar
+grows with the root font size; a fixed 64 px left the end of every page under the bar at the
+accessibility sizes (at AX3 the bar is 150 px tall). Unchanged at the default text size.
+
+### tab-bar
+
+New inputs `hidden` (default `false`) and `hideTransition` (default `true`), both with
+`booleanAttribute` (`hidden` intentionally shadows the global attribute, which is removed from the
+host so a static `<bf-tab-bar hidden>` slides out instead of becoming `display: none`): a hidden bar gets
+`translate-y-[calc(100%+40px)] opacity-0 pointer-events-none` and `aria-hidden="true"` plus
+`inert` on its `nav`, with `transition-[translate,opacity] duration-200` only while
+`hideTransition` (and never under `prefers-reduced-motion`: `motion-reduce:transition-none`). The
+floating bar sits on `z-(--bf-z-tabbar)`, `bottom-[calc(var(--spacing)*6+var(--spacing-safe-bottom))]`. New method `setHidden(hidden, transition?)`, the imperative counterpart for a
+parent that projects the bar (`bf-tabs`); the bar is hidden while the input or it is true, and
+`isHidden` exposes the result. New output `tabReselect`, emitted with the id when the already
+active tab is clicked (`tabChange` still fires only on a change; arrow keys never reselect).
+
+Changed: the floating bar sits 8 px above the bottom safe area, with a 12 px floor where there is
+none, like other apps' floating bars: `bottom-[calc(max(var(--spacing-safe-bottom),12px)+8px)]`
+(42 px from the screen edge on an iPhone, 32 px with Android gesture navigation, 20 px without an
+inset), replacing `bottom-[calc(var(--spacing)*6+var(--spacing-safe-bottom))]` (58 px on an
+iPhone). Hidden, it slides down by `translate-y-[calc(100%+64px)]` (was `100% + 40px`), so it still
+leaves the screen with its shadow.
+
+### action-sheet
+
+New `BfActionSheetService.open({ title?, actions })` in `@bitforgehq/ui/mobile`, resolving
+`Promise<string | undefined>`. Renders `bf-action-sheet` on the overlay core (`position:
+'bottom'`, back priority 100, not counted as a modal, `role="dialog"` with `aria-label` = `title`
+or "Actions"; slides up on open and down on close). The panel (`bg-surface rounded-t-card
+shadow-floating w-screen px-3 pt-3 pb-[max(var(--spacing-safe-bottom),16px)]`, spanning the
+screen with at least 16 px under the cancel button) is an optional `title` caption over a `bf-list
+[inset]="false"` of the non-`cancel` `actions` as interactive rows (an icon from `icon` in the
+leading slot; `destructive`-role labels render `text-danger`, projected through the row's default
+slot since `bf-list-item` has no way to colour its own title), and a separate `tonal` `bf-button`
+(`fullWidth`) for the cancel action — the caller's first `cancel`-role entry if any (further ones are
+ignored), else a synthesized "Cancel". Destructive labels truncate like the other rows.
+Tapping a row resolves with its label; the cancel button, a backdrop tap, `Escape` and the
+hardware back button all resolve `undefined` (the overlay core's defaults, unchanged). The panel's
+`px-3` inset is deliberately tighter than the 16 px gutter: the rows add their own 14 px.
+`provideBfShell()` now also provides `BfActionSheetService`.
+
+### alert-dialog
+
+New `BfAlertDialogService.open({ title, message?, buttons? })` in `@bitforgehq/ui/mobile`,
+resolving `Promise<string>` with the tapped button's label. Renders `bf-alert-dialog` on the
+overlay core (`position: 'center'`, back priority 100, not counted as a modal, no backdrop
+dismiss, `role="alertdialog"` with `aria-labelledby` the generated title id and, when there is a
+message, `aria-describedby` its paragraph). The card (`w-75
+max-w-[calc(100vw-2*var(--spacing-gutter))] bg-surface rounded-card shadow-floating p-6 flex flex-col gap-4`) is an
+`h2.text-heading` title, an optional `text-body text-text-secondary` message and a right-aligned
+`buttons` row (default `[{ label: 'OK' }]`): `cancel`-role renders `text`, `destructive`-role
+`danger`, the first plain button `primary`, further plain ones `tonal`. Unlike every other
+overlay, `Escape` and the hardware back button do not close through the core's
+`dismissOnEscape`/back handling (the service passes `onEscape` and claims the back button itself):
+they
+resolve with the cancel button's label when `buttons` has one, and are otherwise claimed and
+ignored, since an alert with no cancel button can only be answered by tapping a button. Focus
+lands on the first button — the core's first-tabbable search, since the title and message hold no
+focusable content. `provideBfShell()` now also provides `BfAlertDialogService`.
+
+### theme
+
+Type tokens are in rem (same metrics at a 16 px root: `display` 2.5rem/2.75rem, `title`
+1.75rem/2.125rem, `heading` 1.125rem/1.625rem, `body` 0.9375rem/1.5rem, `caption`
+0.8125rem/1.125rem), so a user's font-size preference scales every style together. New type
+tokens for controls and labels: `text-label` (15/20), `text-label-sm` (14/20), `text-label-xs`
+(13/16), `text-micro` (12/16, weight 600), `text-nano` (11/14) and `text-avatar-lg` (26); the
+widgets' `text-[15px]`, `text-sm`, `text-[13px]`, `text-xs` and `text-[11px]` now use them. New
+spacing steps `gutter` (1rem), `card` (1.125rem), `control-sm/md/lg` (2/2.5/3rem), `hit`
+(2.75rem) and `box` (1.375rem), and the arbitrary px sizes became scale steps (`px-4.5`,
+`size-box`, `size-7.5`, `w-13`, `h-4.5`, `size-21`, `w-75`, `py-1.25`, `px-1.75`, `min-h-hit`).
+New `--radius-checkbox` (7px, `rounded-checkbox`), `--color-scrim` (`#000000` in both modes; the
+backdrop rule documents it), motion tokens `--ease-ios`, `--ease-md`, `--ease-settle` and plain
+`:root` variables `--bf-duration-fast/overlay/push` and `--bf-z-sticky/tabbar/dim/overlay`.
+
+WCAG retunes (visual): the focus ring is a darker primary tint, `--color-ring` `#8784dc` (dark
+`#6362af`; was `#c9c8f5` / `#3d3e8a`), 3.03:1 on `bg` and 3.30:1 on `surface` (dark 3.48 / 3.03),
+so it passes WCAG 1.4.11 as the only focus indicator. Control boundaries move to `border-strong`,
+now `#8e8e82` (dark `#686a70`; was `#c9c4b5` / `#3a3d44`), 3.31:1 on `surface` (dark 3.02); `border`
+stays for decorative lines. `control-off` (toggle off track) is `#8d8f84` (dark `#686a70`; was
+`#d9d5c8` / `#3a3d44`), 3.28:1. `text-muted` is `#616b5b` (was `#66705f`): 5.58:1 on `surface`, 4.73
+on `surface-sunken`, 4.54 on `primary-soft`; placeholders and the select's empty value use it now.
+`text-subtle` is `#869181` (was `#95a08f`), 3.29:1, for icons and chevrons only, never text.
+`surface-muted` is `#efece5` (was `#f3f1ea`) so a hover row reads on `bg`; dark `surface-sunken`
+is `#18191c` (was `#0c0d0f`) so tracks (segmented, progress, neutral alert) read on the page. The
+docs theme configurator derives a ring of at least 3:1 from any primary.
+
+`:root` sets `color-scheme: light` and `.dark` sets `color-scheme: dark`, so with `class="dark"`
+on `<html>` the browser's own parts (scrollbars, native form controls, the default canvas) turn
+dark with the palette. Before, only the tokens changed and those stayed light.
+
+Behaviour change: because `:root` now sets `color-scheme: light`, it overrides an app's `<meta
+name="color-scheme" content="light dark">`. An app that relied on the browser's dark canvas and
+scrollbars following the system preference without `.dark` now stays light until it toggles
+`.dark` itself, for example from `matchMedia('(prefers-color-scheme: dark)')` as the docs site
+does. To keep the old behaviour in light mode, add `:root:not(.dark) { color-scheme: normal; }`
+after the theme import.
+
+### motion
+
+New `projects/ui/mobile/motion.ts`, exported from `@bitforgehq/ui/mobile`: `IOS_EASING`,
+`MD_EASING`, `SETTLE_EASING`, `DURATION_FAST` (150), `DURATION_OVERLAY` (260), `DURATION_PUSH`
+(500) and `DURATION_MD` (220). The page transitions, the overlay animations and the refresher
+import them (the refresher's own `SETTLE_EASING` copy is gone); `IOS_DURATION`, `MD_DURATION`,
+`REDUCED_DURATION`, `OVERLAY_DURATION` and `OVERLAY_EASING` stay as aliases. `bf-stack-outlet`'s
+modal-depth transition uses `var(--bf-duration-overlay) var(--ease-ios)` and `var(--radius-tile)`,
+and its dim layer is `bg-scrim/15` on `z-(--bf-z-dim)` (was `bg-text/15`, which dimmed with a
+light colour in dark mode).
+
+### spinner
+
+Sizes are now the `bf-icon` sizes: `sm` 16, `md` 20 (default), `lg` 24 px (were 16/24/32).
+
+Added: `decorative` input (`booleanAttribute`). A decorative spinner has no `role="status"`, no
+`aria-live` and no `sr-only` label, and its wrapper is `aria-hidden="true"`: for a spinner inside a
+control that already reports its busy state, such as a loading `bf-button`.
+
+### button
+
+The loading spinner is `md` (20 px), the size of a default `bf-icon`, so swapping the start icon
+for the spinner no longer changes the button's width. The `outline` border is `border-strong`
+(hover `text-muted`). The label renders in a `data-label` span that truncates with an ellipsis
+(`max-w-full min-w-0 truncate`) when the container is narrower than the label; the icons keep
+their size, and the host and button are capped at `max-w-full`.
+
+Fixed: the enabled button shows a pointer cursor (`cursor-pointer`; Tailwind's preflight gave
+`<button>` the default arrow), `not-allowed` when disabled.
+
+Behaviour change: `loading` no longer sets native `disabled`, so keyboard focus stays on the button
+when an action starts (it fell to `<body>` in Chromium and WebKit). While loading the button carries
+`aria-disabled="true"` and `aria-busy="true"`, stays in the tab order, cancels a click or Enter/Space
+with `preventDefault()` (a `type="submit"` button no longer submits its form) and emits nothing. It
+keeps its variant fill instead of the disabled grey, with a `cursor-progress` cursor (a new `STATE`
+class map: `idle` `cursor-pointer`, `loading` `cursor-progress`). The spinner inside is
+`decorative`, so it adds no second status announcement. Consumers styling `:disabled` on a loading
+button see the change.
+
+### tab
+
+The label is `text-nano` (11/14; the line was 16.5 px). Dropped the `[&>svg]:h-5 [&>svg]:w-5`
+selector, which never matched (icons render inside the `bf-icon` host). A disabled tab uses tokens
+instead of `opacity-40`: `surface-sunken` capsule, `text-disabled` icon and label. The tab can
+shrink (`min-w-0`) and its label is capped at `max-w-full px-1` (it wraps, see "Changed" below), so
+a long label no longer overflows its quarter of the bar.
+
+Fixed: the tab shows a pointer cursor and its capsule a hover (`primary-soft-hover` when active,
+`surface-muted` fill and `text` icon when inactive); a disabled tab keeps its sunken capsule.
+
+Changed: a long label wraps to at most two lines (`line-clamp-2 wrap-anywhere text-center`) instead
+of truncating to one, so "Benachrichtigungen" stays readable in a quarter-width tab.
+
+### list
+
+`bf-list-item`'s title is `text-label` (15/20): its line is 20 px instead of an inherited 22.5, so
+a row without a 40 px leading slot is 2.5 px shorter (a title-only row is 48 px, above the 44 px
+hit area); rows with an avatar keep their 68 px.
+
+Fixed: `bf-list-item` sets `role="listitem"` only inside a `bf-list` (which provides the new internal
+`BF_LIST` token); a standalone row has no role, so axe no longer reports `aria-required-parent` for it.
+
+### alert
+
+The body text is `text-label` (15 px, was 14) like other body copy; the dismiss glyph is
+`text-heading font-normal` (18 px, was 20; the glyph keeps its regular weight).
+
+Fixed: the dismiss button shows a pointer cursor.
+
+Fixed: the title and body break long words anywhere (`wrap-anywhere`), and a dismissible alert's text
+column reserves the dismiss button's width (`pe-10`, was `pr-12` without word breaking), so a long
+word no longer runs under the ×. The dismiss button is placed with `end-3` (was `right-3`).
+
+### field
+
+Fixed: the label, help and error text break long words anywhere (`wrap-anywhere`), so a German or
+Finnish compound no longer runs past the field at 320 px.
+
+### progress
+
+The value's width transition is off under `prefers-reduced-motion`.
+
+### input
+
+The rest border is `border-strong` (was `border`, 1.32:1) and the placeholder `text-muted` (was
+`text-subtle`, 2.73:1); the icon slots stay `text-subtle`.
+
+Changed: the border narrows to 1 px (was 1.5 px); contrast stays ≥ 3:1.
+
+Changed: the focus ring narrows to 2 px (was 4 px); it still shows on mouse focus, not just
+keyboard focus.
+
+Added: `ariaLabel` input (mirrors `bf-toggle`) sets `aria-label` on the native input for a field
+with no visible `label` (e.g. a search box); ignored while `label` is set, so the visible label
+stays the sole accessible name.
+
+Added: `maxLength`, `minLength`, `min`, `max`, `step`, `pattern` (exactly one pattern with no flags,
+`u` or `v` renders the native attribute; other flags such as `i` cannot be expressed in HTML, so the
+form alone validates them), `inputMode`, `enterKeyHint`, `spellcheck` and `autocapitalize` inputs,
+each rendered on the native `<input>` only when set; Signal Forms binds the constraint rules to them
+(`maxLength(p.code, 20)` renders `maxlength="20"`). New exported types `BfInputMode`,
+`BfEnterKeyHint` and `BfAutocapitalize`. `BfInputType` adds `date`, `time`, `datetime-local` and
+`month`, which open the native picker. `ariaLabelledby` sets `aria-labelledby` while there is no
+visible `label`. `focus(options?)` focuses the native control, so Signal Forms'
+`focusBoundControl()` and "focus the first invalid field" on submit now work (they were no-ops).
+
+### textarea
+
+The rest border is `border-strong` and the placeholder `text-muted`, as on `bf-input`.
+
+Changed: the border narrows to 1 px (was 1.5 px), as on `bf-input`.
+
+Changed: the focus ring narrows to 2 px (was 4 px), as on `bf-input`.
+
+Added: `minLength` (native `minlength`), and `ariaLabel` / `ariaLabelledby` for a textarea without a
+visible `label` (ignored while `label` is set). `focus(options?)` focuses the native control, so
+Signal Forms' `focusBoundControl()` and "focus the first invalid field" on submit now work (they
+were no-ops).
+
+### select
+
+The rest border is `border-strong`; the empty value (placeholder) is `text-muted` (was
+`text-subtle`). The chevron stays `text-subtle`.
+
+Changed: the border narrows to 1 px (was 1.5 px); the chevron stroke stays 1.5 px.
+
+Changed: the focus ring narrows to 2 px (was 4 px), as on `bf-input`.
+
+Fixed: the native select shows a pointer cursor and a hover border (`text-muted`, `danger` in the
+error state); focus and disabled borders still win.
+
+Added: `readonly` input. Behaviour change: the control ignored Signal Forms `readonly()` rules and
+could be edited; it now declares `readonly` and blocks changes. While read-only the select keeps its
+value on the `surface-muted` background with `aria-readonly="true"` and stays in the tab order; a
+mouse press focuses it without opening the picker, the picker keys (arrows, Alt+Arrow, Enter, Space,
+F4, type-ahead) are blocked, and a change that still gets through (the platform picker on touch
+screens, which offers no press to cancel) is reverted without writing the model. `ariaLabel` / `ariaLabelledby` name a
+select without a visible `label` (ignored while `label` is set). `focus(options?)` focuses the
+native control, so Signal Forms' `focusBoundControl()` and "focus the first invalid field" on submit
+now work (they were no-ops).
+
+### checkbox
+
+The error text sits 6 px under the row (`gap-1.5`, was 4 px), the label-to-message spacing of the
+other form widgets.
+
+Fixed: hovering an enabled row tints the box (unchecked border `text-muted`, `danger` on error;
+checked `primary-hover`); the label was already `cursor-pointer`.
+
+Added: `readonly` input. Behaviour change: the control ignored Signal Forms `readonly()` rules and
+could be edited; it now declares `readonly` and blocks changes. While read-only the click (which
+Space also triggers) is cancelled, `aria-readonly="true"` is set, the box stays focusable, and the
+box rests on `surface-muted` without hover (default cursor), like a read-only radio; a checked box
+keeps a `primary` border and mark instead of the fill. `focus(options?)` focuses the
+native control, so Signal Forms' `focusBoundControl()` and "focus the first invalid field" on submit
+now work (they were no-ops).
+
+Behaviour change (breaking for a bare attribute): `indeterminate` is now a `model(false)` (it was an
+`input` with `booleanAttribute`). A user change clears it and writes `false` back, so after a click
+the box shows the check mark that assistive tech reports instead of a stale dash; the "select all"
+pattern needs no `(changed)` handler to reset it. Migration: `[indeterminate]="expr"` still works
+one-way and `[(indeterminate)]` binds both ways; a bare `indeterminate` attribute no longer compiles,
+so write `[indeterminate]="true"`.
+
+Fixed: the column is `items-start`, so the label row is only as wide as its content and a click on
+empty space beside it no longer toggles the box.
+
+### radio-group
+
+The legend, the options and the error text sit 6 px apart (legend `mb-1.5`, fieldset `gap-1.5`;
+the legend was 4 px above the options and the error 8 px below them).
+
+Fixed: hovering an enabled, unselected option darkens its ring (`text-muted`, `danger` on
+error).
+
+Added: `readonly` input. Behaviour change: the control ignored Signal Forms `readonly()` rules and
+could be edited; it now declares `readonly` and blocks changes. While read-only clicks (and Space)
+and arrow keys are cancelled, the fieldset carries `aria-readonly="true"`, the radios stay
+focusable, and the rings rest on `surface-muted` without hover. `ariaLabel` / `ariaLabelledby` name
+a group without a visible `label`. `focus(options?)` focuses the checked radio, else the first
+enabled one, so Signal Forms' `focusBoundControl()` works.
+
+Fixed: a disabled option's label dims to `text-disabled` (`has-[input:disabled]:text-text-disabled`
+on the row; `peer-disabled:` could not reach the text through its wrapper span). Vertical option
+rows are `items-start`, so a click on empty space beside an option no longer selects it.
+
+### toggle
+
+The track sits 10 px from the label (`gap-2.5`, was 12 px), like checkbox and radio. Label and
+error text are wrapped in a `flex flex-col items-start gap-1.5` column, so the error sits 6 px
+under the 44 px row (it followed with no gap). Disabled uses tokens instead of `opacity-60`: the
+track is `primary-soft` when checked and `surface-sunken` when unchecked, the label `text-disabled`.
+
+Fixed: hovering an enabled row darkens the track (`primary-hover` on, `text-muted` off).
+
+Added: `readonly` input. Behaviour change: the control ignored Signal Forms `readonly()` rules and
+could be edited; it now declares `readonly` and blocks changes. While read-only the click (which
+Space also triggers) is cancelled and `aria-readonly="true"` is set; the switch stays focusable, the
+track rests on `surface-muted` without hover, bordered `primary` with a `primary` knob when on and
+`control-off` (keeping the ≥ 3:1 boundary) when off. `focus(options?)` focuses the native control, so Signal
+Forms' `focusBoundControl()` and "focus the first invalid field" on submit now work (they were
+no-ops).
+
+### icon-button
+
+The `outline` border is `border-strong` (hover `text-muted`).
+
+Fixed: pointer cursor while enabled, `not-allowed` when disabled.
+
+### chip
+
+The unselected border is `border-strong` (hover `text-muted`). Disabled uses tokens instead of
+`opacity-60`: `surface-sunken` / `text-disabled`, transparent border. The label renders in a
+`data-label` span that truncates with an ellipsis; the chip and its host are capped at
+`max-w-full`. Icon to label stays 6 px (the pill's proportion at 36 px; `bf-button` uses 8).
+
+Fixed: pointer cursor while enabled; a selected chip now has a hover too (`tonal`
+`primary-soft-hover`, `ink` `text-secondary`, fill and border).
+
+### segmented
+
+Each segment's hit area reaches 44 px through an `::after` extension (`after:-inset-y-1` on md
+36 px, `after:-inset-y-1.5` on sm 32 px); the visual size is unchanged. Labels render in a
+`data-label` span (it wraps, see "Changed" below), and segments are `min-w-0`, so a long label in
+`fullWidth` no longer overflows its share. Disabled: unselected segments take `surface-sunken`, the selected one
+keeps its `surface` pill without the shadow; text `text-disabled` as before.
+
+Fixed: every segment shows a pointer cursor while enabled (`not-allowed` when disabled). The
+active segment now also tints on hover (`enabled:hover:bg-surface-muted`), matching the active
+tab's hover in `bf-tab-bar`.
+
+Added: validation state, mirroring `bf-radio-group`. New `required`, `invalid`, `touched`, `errors`
+and `errorMessage` inputs; once touched and invalid (or with an explicit `errorMessage`) the first
+message renders under the track (`id="{id}-error"`), the radiogroup gets `aria-invalid="true"` and
+`aria-describedby`, and the track a 1.5 px `danger-border` ring; `aria-required` follows
+`required`. A required segmented choice no longer fails silently.
+
+Layout change: the host is now a column (`inline-flex flex-col items-start gap-1.5`) so the message
+sits under the track. Without an error it renders as before; `justify-*` or `items-*` utilities a
+consumer put on the host now act on the column.
+
+Added: `readonly` input. Behaviour change: the control ignored Signal Forms `readonly()` rules and
+could be edited; it now declares `readonly` and blocks changes. While read-only `select()` and the
+arrow, Home and End keys do nothing, the group carries `aria-readonly="true"`, the tab stop stays
+focusable, and the track rests on `surface-muted` without segment hover (default cursor).
+`ariaLabel` / `ariaLabelledby` name the group when `label` is not set. `focus(options?)` focuses the
+tab-stop segment, so Signal Forms' `focusBoundControl()` works. `name` is documented as bound but
+not rendered (the control has no native form element).
+
+Fixed: under forced colours the selected label is legible. The selected segment adds
+`forced-colors:forced-color-adjust-none` next to `Highlight`/`HighlightText` (Chromium painted a
+Canvas text backplate under `HighlightText`, white on white in light, black on black in dark) and
+a `CanvasText` focus outline; unselected segments repaint in `ButtonText` on a transparent fill.
+
+Changed: a long label wraps instead of truncating. Segments are `min-h-8`/`min-h-9` with `py-1`
+(were fixed `h-8`/`h-9`, `whitespace-nowrap`), the label span is `wrap-anywhere text-center`, so a
+segment grows taller rather than showing "Tages…".
+
+### card
+
+The `flat` border is `border-strong` (was `border`, 1.32:1).
+
+### action-bar
+
+The bar and its host are capped at `max-w-full`, so a long label no longer pushes the actions out
+of a narrow container (the label keeps its width and the actions wrap, see "Changed" below).
+
+Changed: the label (the selection count) never truncates: it keeps its width (`shrink-0`, breaking a
+long word only past the bar's width), and the bar is `flex-wrap`, so actions that do not fit beside
+it move to a second row.
+
+### platform service
+
+Fixed: `BfPlatformService` now applies the `dark` class to `<html>` and persists the theme choice
+to `localStorage` only when `provideBfShell()` ran (`BF_SHELL_CONFIG` is present, checked via
+`inject(BF_SHELL_CONFIG, { optional: true })`). The `theme`/`dark` signals still compute correctly
+without it. Previously, injecting `BfPlatformService` on its own — e.g. a docs demo that only
+wants `mode`/`platform` for a widget preview — ran the DOM/storage effect anyway, which reverted
+the host page's own theme choice to the OS `prefers-color-scheme` on every change.
+
+The shell now enforces a no-zoom viewport: with `provideBfShell()` on a native platform,
+`BfPlatformService` makes `meta[name=viewport]` contain `maximum-scale=1` and `user-scalable=no`
+(other directives kept; the meta is created with `width=device-width, initial-scale=1,
+maximum-scale=1, user-scalable=no, viewport-fit=cover` if missing). Fixed: iOS zoomed to 16/15 when
+a 15 px field was focused and stayed zoomed after blur; WKWebView honours `user-scalable=no` and
+drops the focus zoom along with pinch and double-tap zoom. See the behaviour change below for the
+recommended `index.html` viewport, which does not carry these directives statically.
+
+**Behaviour change:** the no-zoom lock is native-only by design (the owner's ruling, audit §12),
+and the viewport guidance now says so. The recommended `index.html` viewport is `width=device-width,
+initial-scale=1, viewport-fit=cover` without `maximum-scale`/`user-scalable`, so web builds keep
+pinch zoom and pass axe `meta-viewport`; `provideBfShell()` still adds the lock at boot on iOS and
+Android, where the system text size takes its place (`BfTextScaleService` on iOS, the WebView's
+font scale on Android). The mobile demo's `index.html`, which also serves the web build and the
+docs' embedded phone, no longer locks zoom. Migration: drop `maximum-scale=1, user-scalable=no`
+from your `index.html` if the app also ships to the web; native builds behave as before.
+
+### text scale service
+
+New `BfTextScaleService` (`providedIn: 'root'`, started at bootstrap by `provideBfShell()`): iOS
+Dynamic Type in the native shell. A hidden, persistent probe with `font: -apple-system-body`
+gives the user's body text size (17 px at the default "Large", 21 px at xxL, 40 px at AX3), and
+`<html>` gets `font-size: probe / 17 × 100 %` (rounded to 0.1 %), so every `rem`-based type token
+and spacing step grows with it; a `ResizeObserver` on the probe and `visibilitychange` re-apply it
+when the setting changes while the app runs. The scale (`scale()` signal, 1 by default) never goes
+below 1 and is capped by the new optional `BfShellConfig.dynamicType` member (`{ maxScale: 2.35 }`
+when left out, the AX3 size, at least 200 %; `false` opts out), so a full `BfShellConfig` literal
+written without it still compiles. It acts only with `provideBfShell()` on
+native iOS; Android's WebView applies the system font scale itself, and the web keeps the
+browser's text size and zoom. Destroying the service removes the probe and the root font size.
+Fixed: iOS text could not be enlarged at all in the shell (F-048).
+
+### agent docs
+
+The package ships `ai/MANIFEST.index.json` beside `ai/MANIFEST.json`: one small record per
+component (`name`, `selector`, `className`, `category`, `entryPoint`, `summary`, `since`), generated
+with the rest of `ai/**` (`bun run ai:docs`). An agent can pick a component from it without reading
+the full manifest; the docs site bundles it and fetches the full manifest on demand. Every
+`MANIFEST.json` entry also gains a `summary` field, and `llms.txt` and the `UI_GUIDE.md` component
+table now show it in place of the description's first sentence; each `ai/components/*.md` carries
+it as a line under the title.
+
+### docs site
+
+Every `@bitforgehq/ui/mobile` component page runs a live demo in a drawn phone: the docs'
+`app-phone-frame` embeds the mobile demo's web build at the component's showcase route
+(`mobile-demo/?mode=ios|md&embed=1&start=showcase/<name>`), with an iPhone / Pixel picker
+remembered across pages and an "Open full screen" link. The Mobile page uses the same frame on
+the whole app (`start=tabs`). The phone follows the docs theme: the configurator's tokens and
+light/dark reach the demo through a same-origin `postMessage` (`bf-docs-theme`). The mobile demo
+gains the showcase routes, the `?start=` entry (only `tabs` or a known showcase; a device build
+has no query string and still starts on `tabs`) and, with `?embed=1` only, the theme bridge. The
+frame also takes an Appearance override (follow the docs theme, or pin light/dark) independent of
+the site theme, and sends its drawn status-bar/tab-bar heights to the embedded demo as
+`?insets=<top>,<bottom>` so its header and tab bar clear them.
+
+New this phase: every component page renders from the same fixed skeleton (breadcrumb, title,
+summary, meta chips, install/import snippet, Preview | Code example card, Overview, usage
+sections, Theming, Accessibility, API, notes, migration notes, then previous/next links) sourced
+from the shipped manifest; a command-palette search (`Cmd/Ctrl+K`) finds any component or guide
+page; `SeoService` sets a per-route title, meta description, canonical link and Open Graph/Twitter
+tags, always under the Firebase origin regardless of which host serves the page, and marks the 404
+view `noindex`; every page passes an axe accessibility check (zero `serious`/`critical`
+violations, in light and dark) and the WAI-ARIA patterns for its tabs, search and table of
+contents; and CI's last step runs Lighthouse against five pages, blocking under performance 90,
+accessibility 100, best practices 95 or SEO 100.
+
+Docs correctness: a site-wide pre-release note (an `aside` labelled "Release status") says the
+package is not on npm yet and links to the Install page's "Before the npm release", inside the
+"Add the packages" step: it states that the source repository is private and needs read access,
+clones it beside the app, packs the built library into `../bitforge-ui-packages/` (outside
+`dist/`, which every build wipes), adds that tarball and shows how to update it later; the
+generated guide and README install blocks carry the same note and instructions. The home page's
+install command reads `bun add @bitforgehq/ui@next`, labelled "Pre-release — not on npm yet". The
+Install page is a verified quick start rendered from one source, `INSTALL_STEPS`
+(`projects/docs/src/app/consts/install.const.ts`): prerequisites (Node in the Angular CLI 22
+range `^22.22.3 || ^24.15.0 || >=26.0.0`), `ng new`, `ng add tailwindcss`,
+one `bun add`, the `styles.css` block (no `@tailwindcss/forms`), `bg-bg text-text` on `<body>`,
+dark mode, a first component (removing the welcome page and updating the generated `app.spec.ts`)
+and what you should now see. `ai/UI_GUIDE.md` §Install and the
+install block of `projects/ui/README.md` are generated from the same steps, and the consumer-smoke job builds a
+clean app from them with 0 errors and 0 warnings. A new "Forms and validation" guide (`/forms`)
+covers Signal Forms setup, validators with messages, `[formRoot]` submission with focus on the
+first invalid field and server errors, with a live example whose Code view is the compiled file;
+Reactive Forms (supported through Angular 22's interop, no `ControlValueAccessor`) with an example
+the consumer-smoke job compiles and a precise account of what the interop syncs; template-driven
+forms; and read-only versus disabled. The footer links the guide. Deep links
+to a component-page section (`/components/button#api`) now scroll to it once the deferred body
+renders. The `bf-input` "With Signal Forms" snippet now compiles as shown (the imports,
+`[formRoot]` instead of a bare `(submit)`, and validators with messages). `llms.txt` links to the canonical origin (`https://bitforge-ui.web.app`, was a GitHub
+Pages mirror that returned 404) and lists the guide pages.
+
+### packaging
+
+Behaviour change for installs: the peer metadata now matches what each entry imports.
+`@angular/cdk`, `@angular/router` and `@capacitor/core` are optional peers, so a desktop-only
+install no longer pulls them in; an app that imports `@bitforgehq/ui/mobile` installs them itself.
+`rxjs` (`^7.8.0`, imported by `/mobile`) is declared as an optional peer. `lucide` is now a required
+peer (`bf-back-button` imports its icons statically, and `@bitforgehq/ui/icons` renders Lucide
+data). `@capacitor/app`, `@capacitor/keyboard` and `@capacitor/haptics` stay optional.
+`publishConfig` sets `access: public` and `provenance: false`: the source repository is private,
+and npm generates no provenance for private repositories.
+
+### haptics
+
+Fixed: a missing `@capacitor/haptics` no longer breaks the build. Its dynamic import sits inside a
+`try` with a `.catch()`, so esbuild tolerates the unresolved optional peer and `BfHapticsService`
+resolves every method as a no-op when the plugin is not installed. Before, every
+`@bitforgehq/ui/mobile` import failed to build with `Could not resolve "@capacitor/haptics"`.
+
+### all components
+
+Every boolean `input()` across `projects/ui/src` and `projects/ui/mobile` now carries `{ transform:
+booleanAttribute }`, so a bare HTML-style attribute (`<bf-button disabled fullWidth loading>`,
+`<bf-list-item interactive chevron>`, `<bf-input required readonly>`) compiles and works the same
+as `[disabled]="true"` under `strictTemplates`. A new `tools/boolean-inputs.test.ts` (`bun run
+test:tools`) scans every non-spec source file for a boolean `input()` missing the transform, so a
+regression fails CI. Boolean `model()` inputs are unaffected (a `transform` is not supported on
+`model()`).
+
+### forms
+
+The Signal Forms integration spec now covers all seven value controls (value both ways,
+`disabled()`, `readonly()`, `required` with the message after touch, `reset()`,
+`focusBoundControl()`, `submit()` focusing the first invalid field, and the `maxLength`,
+`minLength` and `pattern` rules on the native attributes). A new Reactive Forms interop spec pins
+`[formControl]` on every control with Angular 22's custom-control support (no
+`ControlValueAccessor`): value both ways, touched through `touch`, `disable()`/`enable()`,
+`Validators.required` to `required`, and errors without a `message`, whose text comes from
+`errorMessage`. `tools/form-spec-members.test.ts` fails when a form control's input, model or output
+is not exercised in its spec: only `setInput('<member>'`, `componentInstance.<member>`, a
+`.<member>(` call or a `[<member>]` / `(<member>)` binding count, never an error `kind` string or a
+DOM property read.
+
+## 0.1.0 (not published)
+
+### theme
+
+Dark surfaces now sit further apart (`surface` #1e2024, `surface-muted` #262930, `surface-sunken` #0c0d0f) so sunken tracks and raised segments stay distinguishable on the neutral dark palette. Default primary changed from the Meadow Sage green (`#2f8f5b`) to indigo `#2b26ba`, with the derived brand tokens (`primary-hover`, `primary-soft`, `primary-soft-hover`, `primary-strong`, `selected`, `ring`) re-tuned in both modes. The dark palette is now neutral gray (surfaces, lines, text) instead of green-tinted, so any primary colour fits without touching the rest of the theme.
+
+Initial widgets: `bf-button`, `bf-badge`, `bf-spinner`, `bf-icon`, the Meadow Sage theme, and the form set `bf-field`, `bf-input`, `bf-textarea`, `bf-select`, `bf-checkbox`, `bf-toggle`, `bf-radio-group` (all Signal Forms ready), and the display set `bf-icon-button`, `bf-chip`, `bf-segmented`, `bf-list`/`bf-list-item`, `bf-card`, `bf-progress`, `bf-avatar`, `bf-alert`, `bf-empty-state`, `bf-action-bar`, `bf-tab-bar`/`bf-tab`.
+
+### input
+
+Field sizes renamed: `sm`/`md` (40/48 px) is now `md`/`lg` (40/48 px), default stays 48 px but the default token changed to `lg`. The host no longer reflects a static `id` attribute onto `<bf-input>`; the id lands only on the native `<input>`.
+
+### textarea
+
+Same `md`/`lg` size rename as `bf-input`. The host no longer reflects a static `id` attribute onto `<bf-textarea>`.
+
+### select
+
+Same `md`/`lg` size rename as `bf-input`. Without a `placeholder`, an unmatched `value` (e.g. the empty string) now renders a hidden, disabled, selected placeholder option so the native control shows no visible selection instead of falling back to the first real option. The inert `[value]` binding on `<select>` was removed; selection is driven entirely by `[selected]` on each `<option>`. The host no longer reflects a static `id` attribute onto `<bf-select>`. Added `bg-none` so consumers loading `@tailwindcss/forms` don't get a second, duplicate chevron drawn by the plugin's default `background-image` alongside the library's own CSS chevron.
+
+### checkbox
+
+The label's cursor styling is now a computed `labelClasses`. The redundant `[attr.aria-checked]` binding was removed from the native checkbox; the native `checked`/`indeterminate` state already conveys it to assistive tech. The focus ring now clears in forced-colors mode. The host no longer reflects a static `id` attribute onto `<bf-checkbox>`. Fixed the checked box never showing its fill: `bg-surface`/`after:opacity-0` and the "on" branch's `bg-primary`/`after:opacity-100` were both present at once, and Tailwind's stylesheet order let `bg-surface` win, leaving a checked box white with an invisible check mark. The base class list and the on/off branches now each emit exactly one background and one after-opacity utility. The label's clickable hit area is now `min-h-11 items-center` instead of a `::after` pseudo-element; a `::after` extension over projected content (the label text) is the wrong tool — `min-h-11` gets the same ≥ 44 px target without an overlay. Dropped the box's `mt-0.5` top-margin nudge; with the row already `min-h-11 items-center`, the box centres on the label line on its own. Added `ariaLabel` (mirrors `bf-toggle`) for an accessible name when there's no visible `label`, e.g. a row-selection box; the label `<span>` no longer renders when `label` is empty, so an `ariaLabel`-only checkbox has no empty gap next to the box. Projected label content and the `label` input share one styled text span, which hides itself when both are empty (`empty:hidden`).
+
+### toggle
+
+Added `errorMessage` and Signal Forms error rendering (matching `bf-checkbox`): a `<p>` under the label, `aria-invalid` and `aria-describedby` on the input. `labelPosition="start"` now stretches the label to `w-full` with `justify-between` for settings-list layouts. The track and knob keep a transparent 1.5px border and the focus ring clears in forced-colors mode. The host no longer reflects a static `id` attribute onto `<bf-toggle>`. Fixed the knob sitting off-centre: the track's padding was `p-[3px]` alongside its `border-[1.5px]`, so the 22px knob had unequal 4.5px/1.5px margins at the two ends of its 20px `translate-x-5` travel; padding is now `p-[1.5px]` for equal 3px margins on both sides. Also removed the redundant `box-border` from the knob (preflight already sets `box-sizing: border-box` globally). The label's clickable hit area is now `min-h-11 items-center` instead of a `::after` pseudo-element, in both `labelPosition` branches, for the same reason as `bf-checkbox`.
+
+### radio-group
+
+The fieldset now carries `role="radiogroup"`. The ring's focus ring clears in forced-colors mode and the selected dot renders in `CanvasText` under forced colors. The host no longer reflects a static `id` attribute onto `<bf-radio-group>`; the id lands on the `<fieldset>`. Each option's label now carries `min-h-11 items-center`, so a stacked row is itself at least 44 px tall and is its own hit area, rather than a `::after` pseudo-element that overlapped into the neighbouring row's 10px gap and stole its clicks near the boundary; the vertical option list's gap tightened from `gap-2.5` to `gap-1` to match the now taller rows.
+
+### field
+
+`disabled` no longer dims the whole field; it dims only the label. Controls already carry their own disabled styling.
+
+### icon-button
+
+New `bf-icon-button`: a round button that holds a single icon, with `tonal` (default), `primary`, `outline` and `text` variants and `sm`/`md`/`lg` (32/40/48 px) square sizes. `label` is required and renders as `aria-label` since the icon alone gives assistive tech no name. `sm` and `md` extend the hit area vertically to 44 px with an invisible `::after`, matching `bf-button`, so adjacent icon buttons in a toolbar don't overlap.
+
+### chip
+
+New `bf-chip`: a toggleable pill for filters and tags, 36 px tall, with `tonal` (default) and `ink` treatments. Renders a `<button aria-pressed>` and shows a `::before` check mark while selected. Two-way `[(selected)]` model plus a `toggled` output fired after a user click; the hit area extends vertically with `::after`, matching `bf-button`. Fixed the check mark rendering as a thin vertical line instead of a tick: the `::before` pseudo-element had no `display` utility, and an inline, non-replaced box ignores explicit `width`/`height`; added `before:block`. Added `deselectable` (default `true`): set it `false` in a single-choice filter row so clicking the already-selected chip does nothing instead of clearing the selection. The unselected state's hover border is now `enabled:hover:border-border-strong` so a disabled chip doesn't show a hover state it can't act on.
+
+### segmented
+
+New `bf-segmented`: a `role="radiogroup"` control for switching between two to four views, implementing `FormValueControl<string>`. `sm`/`md` (32/36 px) item heights, optional `fullWidth`. Keyboard arrow keys move the roving-tabindex selection and wrap around, skipping disabled options; `Home`/`End` jump to the first/last enabled option. The roving tab stop (`tabStop`) now falls back to the first enabled option when the selected value is missing or disabled, instead of leaving every segment at `tabIndex -1`. A keyboard selection also moves DOM focus to the newly selected button. The active segment's fill is now visible under forced-colors (`forced-colors:bg-[Highlight] forced-colors:text-[HighlightText]`), and the inactive segment explicitly clears its background there.
+
+### list
+
+New `bf-list` and `bf-list-item`: a `role="list"` container (inset by default, with a warm background and rounded corners; `inset=false` drops it for rows on a page) and a row with `leading`/`trailing` content slots, `title`/`subtitle` text, an optional trailing chevron, and an `interactive` mode that renders the row as a `<button>` emitting `clicked`. The interactive row's hover background is now `enabled:hover:bg-surface-muted` so a disabled row doesn't show a hover state; removed the unused `relative` from the row's base classes.
+
+### card
+
+The card surface now fills its host (`h-full`), so cards in a stretched grid row end at the same height instead of ragged bottoms; block hosts of auto height are unaffected.
+
+New `bf-card`: a content surface with `header`/default/`footer` slots and four variants — `raised` (default, `shadow-raised`), `tint`, `ink` and `flat`. `padding` is `md` (18 px, default) or `lg` (24 px). `interactive` renders the card as a `<button>` that emits `clicked` and adds a hover shadow and focus ring.
+
+### progress
+
+New `bf-progress`: a determinate `role="progressbar"` for completion and quotas. `value` is clamped to 0–100 and rounded; `size` is `sm` (8 px, default) or `md` (10 px); `tone` (`primary` default, `success`, `warning`, `danger`) colors the fill. `label` is required and becomes the bar's `aria-label`. The native `<progress>` element now carries an explicit `role="progressbar"` attribute (it already had the role implicitly) so consumers and specs can select on it directly. `percent` now guards against a non-finite `value` (e.g. `NaN`), rendering `0` instead of propagating `NaN` into the fill width and `aria-valuenow`.
+
+### avatar
+
+New `bf-avatar`: a round avatar showing a photo (`src`/`alt`) or initials on a tinted circle. `size` is `sm` (30 px), `md` (40 px, default) or `lg` (84 px); `variant` is `tint` (default), `ink`, `warning` or `neutral`. The host now carries `role="img"`/`aria-label` only when `alt` is set; without `alt` the host is `aria-hidden="true"` and decorative, instead of always announcing itself with the initials as a fallback name. The inner `<img>` now always has `alt=""` so the image itself is hidden from the accessibility tree and the host's `aria-label` is the single source of the accessible name.
+
+### alert
+
+New `bf-alert`: an inline `role="status"` (`role="alert"` for `danger`) message with `neutral` (default), `success`, `warning` and `danger` variants, an `icon` slot, a `title`, and an `actions` slot. `dismissible` shows a close button that emits `dismissed`; the component itself never hides. The dismiss button now renders as a sibling of the `role="status"`/`role="alert"` element (both wrapped in an outer `div`) instead of inside it, so assistive tech reading the status/alert region doesn't also announce the dismiss control as part of the message; the visual position (absolute, top-right) is unchanged. Added `dismissLabel` (default `"Dismiss"`) to customize the button's accessible name. The 32 px dismiss button now extends its hit area to 44 px with `after:-inset-1.5`, a self-contained control so the `::after` extension is the right tool here (unlike a control over projected content).
+
+### empty-state
+
+New `bf-empty-state`: a centered placeholder with a 64 px `icon` tile, a required `title`, an optional `description`, and an `actions` slot for the action that fills it. Added `headingLevel` (`2` default or `3`) so the title renders as `h2` or `h3` to fit the page outline.
+
+### action-bar
+
+New `bf-action-bar`: a floating pill for actions on a selection, with an optional leading `label` and a default slot for buttons. It only styles itself; the consumer positions it (fixed bottom-centre on web, `pb-safe-bottom` on mobile). Uses `role="group"` (was toolbar): the bar's contents aren't a fixed, single-tab-stop toolbar of controls, so `group` is the correct ARIA role; `aria-labelledby` now points at the `label` span instead of relying on visible text alone.
+
+### tab-bar
+
+New `bf-tab-bar`: the Meadow Sage floating pill tab bar for mobile navigation, 64 px tall, holding a `role="tablist"` of `bf-tab` children. `active` (model) tracks the selected tab id; `label` (default `Main`) names the tablist; `floating` (default `true`) fixes the bar above the safe area with `shadow-floating`, or renders it inline with `shadow-raised` when false. ArrowLeft/ArrowRight/Home/End navigation moves both selection and focus together across the enabled tabs, wrapping at the ends and skipping disabled ones; selecting a tab emits `tabChange`. The bar and `bf-tab` communicate through the `BF_TAB_BAR` injection token so neither file imports the other. Added a `tabStop` computed, exposed through `BF_TAB_BAR`: the roving tab stop now falls back to the first enabled tab when `active` matches no enabled tab (empty, unresolved, or the active tab is disabled), instead of leaving every tab at `tabIndex -1` and removing the bar from the tab order.
+
+### tab
+
+New `bf-tab`: one destination inside `bf-tab-bar` — an icon in the default slot, `label` under it, and an optional `badge` count. `id` and `label` are required; `disabled` removes it from keyboard navigation and blocks clicks. Renders a native `<button role="tab">` with `aria-selected` and a roving `tabindex` driven by the bar's `tabStop`; the active tab's icon sits on a `primary-soft` capsule (`forced-colors:bg-[Highlight]`) with a `primary-strong` label, inactive tabs are `text-muted`. The host no longer reflects `id` as a DOM attribute (`bf-tab id="today"` previously duplicated `id="today"` onto both the host and the inner `<button>`); the id now lands once, on the button. The badge is `aria-hidden`; a visually hidden `sr-only` span after the label announces it instead (`"{n} new"` for a numeric badge, the string as-is otherwise), so the tab's accessible name carries meaning instead of a bare number.