@bitforgehq/ui 0.3.0

package/ai/UI_GUIDE.md

@@ -0,0 +1,1159 @@
+<!-- GENERATED by tools/gen-ai-docs.ts from tools/ui-guide.template.md and the component sources. Do not edit by hand; run `bun run ai:docs`. -->
+
+# @bitforgehq/ui — guide for implementer agents
+
+You are working in an app that uses `@bitforgehq/ui`, Bitforge's shared Angular 22 component
+library (Meadow Sage design, Tailwind CSS v4, signals-first). **Before creating any UI primitive
+(button, input, card, list, badge, …), check the component index below and use the library
+component.** Per-component pages with the full API, examples and dos/don'ts are in
+`node_modules/@bitforgehq/ui/ai/components/<name>.md`; the machine-readable version is
+`node_modules/@bitforgehq/ui/ai/MANIFEST.json`.
+
+## Install
+
+### 1. Check the prerequisites
+
+Node 22.22.3 or later in the 22 line, 24.15 or later in the 24 line, or 26 and later (the Angular CLI 22 range `^22.22.3 || ^24.15.0 || >=26.0.0`; it refuses older versions and warns on odd releases such as 23 and 25), Bun 1.3 or later and the Angular CLI 22.
+
+```bash
+node --version # v22.22.3+, v24.15+ or v26+
+bun --version # 1.3 or later
+bun add --global @angular/cli@22
+```
+
+### 2. Create the app
+
+A new Angular 22 app with plain CSS styles. Skip this step in an existing app.
+
+```bash
+ng new my-app --style css --package-manager bun
+cd my-app
+```
+
+### 3. Add Tailwind CSS
+
+The theme is a Tailwind CSS 4 theme. `ng add tailwindcss` installs Tailwind and its PostCSS plugin and writes `.postcssrc.json`.
+
+```bash
+ng add tailwindcss
+```
+
+### 4. Add the packages
+
+`lucide` provides the icon data for `bf-icon`; the two `@fontsource` packages provide the Manrope and JetBrains Mono fonts.
+
+```bash
+bun add @bitforgehq/ui lucide @fontsource/manrope @fontsource/jetbrains-mono
+```
+
+### 5. Wire the theme into styles.css
+
+Replace the contents of `src/styles.css`. Keep `tailwindcss` first: the theme redefines the palette its utilities read, and registers the package as a Tailwind source, so no `tailwind.config.js` is needed.
+
+```css
+@import 'tailwindcss';
+@import '@bitforgehq/ui/theme.css';
+@import '@fontsource/manrope/500.css';
+@import '@fontsource/manrope/600.css';
+@import '@fontsource/manrope/700.css';
+@import '@fontsource/manrope/800.css';
+@import '@fontsource/jetbrains-mono/400.css';
+```
+
+### 6. Theme the page
+
+In `src/index.html`, give `<body>` the theme background and text colour, so the page itself follows light and dark mode.
+
+```html
+<body class="bg-bg text-text">
+  <app-root></app-root>
+</body>
+```
+
+### 7. Switch to dark mode
+
+Add the `dark` class to `<html>` (and remove it for light mode). Every token is redefined under `.dark`, and the theme sets `color-scheme`, so scrollbars and native controls follow too. Components need no `dark:` classes.
+
+```html
+<html lang="en" class="dark">
+  <!-- head and body stay as they are -->
+</html>
+```
+
+### 8. Use a first component
+
+Import a widget from `@bitforgehq/ui` into the component that uses it. Replace `src/app/app.ts` with the code below and delete the welcome page it no longer uses, `app.html` and `app.css`. `app.spec.ts` tests that welcome page too: delete its `should render title` case (or make it check the button), so `ng test` keeps passing.
+
+```ts
+import { Component } from '@angular/core';
+import { BfButtonComponent } from '@bitforgehq/ui';
+
+@Component({
+  selector: 'app-root',
+  imports: [BfButtonComponent],
+  template: `<bf-button variant="primary">Save</bf-button>`,
+})
+export class App {}
+```
+
+### 9. Check it
+
+Run the app and open it: you should now see an indigo, pill-shaped **Save** button in Manrope on the theme background. With `class="dark"` on `<html>`, the whole page is dark.
+
+```bash
+ng serve
+```
+
+Required peers: `@angular/common`, `@angular/core`, `@angular/forms` and `lucide`. An app that
+imports `@bitforgehq/ui/overlay` (the overlay core: no Capacitor, no router) also installs
+`@angular/cdk` and `rxjs` (a CDK peer); an app that imports `@bitforgehq/ui/mobile` installs those
+plus `@angular/router` and `@capacitor/core`. They are declared optional so a desktop-only
+install of the widgets stays free of them.
+
+`styles.css` is the same for web and mobile apps. Nothing else: `theme.css` registers the library
+as a Tailwind source itself. Do not create a `tailwind.config.js`, and add no Tailwind plugin:
+the widgets style their native controls themselves.
+
+Optional per-app overrides go after the import. A brand colour is a set: override
+`--color-primary` together with `--color-primary-text` (primary as text, ≥ 4.5:1 on `bg` and
+`surface`) and the rest of the `--color-primary-*` tokens, in `@theme` and in `.dark`; the docs
+site's theme configurator derives the whole contrast-checked set from one colour.
+`--radius-control` (`9999px`, pills) reshapes buttons, chips, badges, segmented, the tab bar, the
+action bar and toggles at once:
+
+```css
+@theme {
+  --color-primary: #123456;
+  --color-primary-text: #123456;
+  --radius-control: 8px;
+}
+```
+
+## Compatibility
+
+`@bitforgehq/ui` 0.x is client-rendered only. SSR, hydration and prerendering of pages that render
+its components are not supported or tested. Component ids come from a module-level counter and can
+differ between server and client, and the shell's theme is read from `localStorage` on the client.
+Render library components only in the browser, for example in a `@defer` block or a client-only
+route. Support will be decided before 1.0.
+
+The one server-side check is a render smoke, not a support test: the library repository's
+`tools/ssr-smoke.ts` renders 28 fixtures with `renderApplication()` (every root widget, `bf-icon`,
+`bf-number-input`, a `/mobile` page with `provideBfShell()`, `bf-page`, `bf-header` and
+`bf-content`, `bf-tabs` with `bf-stack-outlet` under the router, and an `/overlay` dialog), and all
+of them render without an error. 19 of them render identically twice. The other 9 number their ids
+differently on every render, from a module-level counter, so they could not hydrate: `bf-checkbox`,
+`bf-input`, `bf-radio-group`, `bf-segmented`, `bf-select`, `bf-textarea`, `bf-toggle`,
+`bf-number-input` and the `/overlay` dialog. Hydration itself is still not supported or tested, and
+more stands in its way: `/mobile` writes to `<html>` and adds a keyboard probe to `<body>`, and an
+`/overlay` dialog renders outside the app root and marks it inert.
+
+## Keeping this guide in sync
+
+This file is installed by the `bf-ui` CLI that ships with the package. Run `bunx bf-ui sync-ai`
+to write (or refresh) `.ai/UI_GUIDE.md` in the consuming project, and add the CLAUDE.md/AGENTS.md
+snippet it prints. `bunx bf-ui sync-ai --check` exits non-zero when the installed copy is missing
+or out of date — wire it into CI so agent guidance never drifts from the installed package version.
+
+## Using components
+
+- Import the standalone class into the component that uses it:
+  `import { BfButtonComponent } from '@bitforgehq/ui';` and add it to `imports: [...]`.
+- Icons: `import { BfIconComponent } from '@bitforgehq/ui/icons';` plus the icon data from
+  `lucide` (`import { Search } from 'lucide'`), then `<bf-icon [icon]="Search" />`. Every icon
+  position in every widget is a content slot (`<bf-icon bfSlot="icon-start" ... />`).
+- Number field: `import { BfNumberInputComponent } from '@bitforgehq/ui/number-input';`. It is
+  the one widget in its own entry point, because it loads Angular Forms (`@angular/forms`, a
+  required peer); `@bitforgehq/ui` itself loads no forms code, so an app without forms ships none.
+- Layout classes go on the element (`<bf-button class="mt-4">`); never restyle a widget's internals.
+- Colors: use only the semantic tokens (`bg-primary`, `text-text-muted`, `bg-surface`,
+  `border-border`, `rounded-field`, `shadow-raised`, `text-body`). Never raw palette classes and
+  never `dark:` variants; put `dark` on `<html>` and the theme re-colors everything.
+- Forms: `bf-input`, `bf-number-input`, `bf-textarea`, `bf-select`, `bf-checkbox`, `bf-toggle`,
+  `bf-radio-group` and `bf-segmented` expose `value` / `checked` as `model()` and implement
+  Signal Forms' `FormValueControl` / `FormCheckboxControl`. Bind either `[formField]="form.field"` or
+  `[(value)]` / `[(checked)]`, never both. Import `FormField`, `FormRoot`, `form` and the
+  validators from `@angular/forms/signals`. The first error shows once the field is touched: its
+  own `message` (`required(p.email, { message: 'Enter your email' })`), else the default text for
+  its kind from `provideBfLabels()` ("Fill in this field", "Use at least 5 characters", …), so a
+  field never turns red without text. Wrap the fields in
+  `<form [formRoot]="myForm">` with `submission: { action, onInvalid }` in `form()`'s options, so
+  an empty submit shows every message instead of the browser's bubbles; errors the `action`
+  returns show under their field. `errorMessage` is for errors from outside the form.
+- Typed values: `bf-select`, `bf-radio-group` and `bf-segmented` are generic over their option
+  values (`BfSelectOption<number>`, `BfRadioOption<T>`, `BfSegmentOption<T>`; `string` by
+  default) and bind `T | null`, where `null` means nothing is chosen (start the field at `null`;
+  `required()` treats it as empty; `(changed)` emits only a chosen `T`). Options match with
+  `Object.is`; for object values pass `[compareWith]="byId"`. Numbers bind to `bf-number-input`
+  (`number | null`, `null` while empty; `min()`/`max()` reach the native input; unreadable text is
+  a `parse` error on the bound field, blocking `submit()`), never to a `string` model on
+  `bf-input type="number"`.
+- Reactive Forms work through Angular 22's built-in interop: `[formControl]` and
+  `formControlName` bind every form widget above with no `ControlValueAccessor` (never add one).
+  Value, touched, dirty, validity, pending, disabled, required and errors flow into the widget;
+  the widget writes back only its value (marking the control dirty) and touched on blur. There is
+  no read-only state in Reactive Forms: bind `[readonly]` yourself. `Validators.*` errors carry no
+  message, so a touched invalid field shows the default text for the error's kind (`required`,
+  `minlength`, … read from the error's `context`); pass `errorMessage` only for your own text.
+  Type controls like the widgets' values: `new FormControl<number | null>(null, Validators.min(1))`
+  on a `bf-number-input` or a select of numeric ids.
+- Links: navigation is a real `<a>`. `<a bfButton routerLink="/new">` styles a link as a
+  `bf-button` (same `variant`/`size`; import `BfButtonComponent`). For a clickable `bf-card` or
+  `bf-list-item`, put `bfAction` (`BfActionDirective`) on the one `<a>` or `<button>` holding the
+  heading or title, `<h3><a bfAction routerLink="/projects/1">Atlas</a></h3>`: it stretches over
+  the surface while the heading stays a heading; give other controls inside `class="relative z-1"`.
+  Never use the deprecated `bf-card [interactive]`. Inside `bf-tabs` the tab bar renders a `nav` of
+  links with `aria-current`; a standalone `bf-tab-bar` keeps `tablist` semantics.
+
+## API conventions
+
+Every public output, name input and type follows one convention (the generator enforces it), so
+you can guess a binding without looking it up:
+
+- Outputs are events in the past tense: `(clicked)`, `(changed)`, `(dismissed)`, `(focused)`,
+  `(blurred)`, `(scrolled)`, `(reselected)`, `(stackChanged)`, `(transitionStarted)`,
+  `(refreshRequested)`. None starts with `on`, and no declared output is `xChange` (that name is
+  the implicit output of a `model()`, `[(value)]`). Exceptions: `touch` (the Signal Forms
+  contract) and the page lifecycle `bfViewWillEnter`/`bfViewDidEnter`/`bfViewWillLeave`/`bfViewDidLeave`.
+- Actions emit `(clicked)`; a sub-part's action is `<part>Clicked` (the desktop toast's
+  `actionClicked`). Exception: menu items (`bfMenuItem`, `bfMenuItemCheckbox`, `bfMenuItemRadio`)
+  emit `(triggered)`, mirroring the CDK menu, and it fires on `Enter` and `Space` too; binding
+  `(clicked)` on a menu item never fires.
+- Every value control (a `value`/`checked`/`selected`/`active` model: the form fields, `bf-chip`,
+  `bf-tab-bar`, `bfMenuItemCheckbox`) has exactly one `(changed)`, emitted with the new value right
+  after a user change, never for a programmatic write.
+- Names: `label` is a component's own name (visible, or the accessible name of an icon button,
+  spinner, tab bar, progress or icon); every component that renders a native input, select or
+  textarea (checkbox and toggle included) also takes `ariaLabel` and `ariaLabelledby` for when no
+  visible `label` is shown; a built-in sub-control's name is `<part>Label` (`dismissLabel`,
+  `closeLabel`, `actionLabel`); `alt` only on `bf-avatar`.
+- Types: every union or object type of an input, model, output, `Bf…Options`/`Bf…Config` property
+  or an interface they name is a named type exported from the same entry
+  (`BfToggleLabelPosition`, `BfRefresherRefreshEvent`, `BfDialogRole`, …), so type your own state
+  with it instead of repeating the literals. A field's "left off" value `''` has its own type
+  (`BfInputInputMode`, `BfInputEnterKeyHint`, `BfInputAutocapitalize`); `BfInputMode`,
+  `BfEnterKeyHint` and `BfAutocapitalize` list only the native keywords.
+- Renamed 0.2 outputs keep working as deprecated aliases that emit together with the new name
+  until 0.4.0: `bf-chip` `toggled` → `changed`, `bf-tab-bar` `tabChange` → `changed` and
+  `tabReselect` → `reselected`, `bf-stack-outlet` `stackChange` → `stackChanged`,
+  `transitionStart` → `transitionStarted` and `transitionEnd` → `transitionEnded`, `bf-refresher`
+  `refresh` → `refreshRequested`. Write new code with the new names.
+
+## Configuration
+
+Two optional providers from `@bitforgehq/ui` set app-wide widget defaults. Each returns a plain
+`Provider` merged over the nearest parent injector's value, so it works in
+`ApplicationConfig.providers` and in a component's `providers` (for a sub-tree, e.g. a dense
+toolbar or a German settings page); a key you leave out keeps the parent's value.
+
+- `provideBfDefaults({ size, fieldSize, controlSize })` sets the height step (`BfSize`: `sm` 32,
+  `md` 40, `lg` 48 px) a widget uses when its own `size` input is unset. `fieldSize` covers the
+  text fields (`bf-input`, `bf-number-input`, `bf-select`, `bf-textarea`), `controlSize` the
+  actions and choice controls (`bf-button`, `bf-icon-button`, `bf-chip`, `bf-segmented`,
+  `bf-checkbox`, `bf-toggle`, `bf-radio-group`); `size` sets both, and an explicit
+  `fieldSize`/`controlSize` wins over it. The library default is compact `md` for both (desktop
+  first): a desktop web app sets nothing, a data-dense app or sub-tree (a table toolbar, a filter
+  row) sets `{ size: 'sm' }`, a Capacitor app sets `{ fieldSize: 'lg' }` once. Never hard-code
+  `size` on every widget to change density; set it in a provider. Under a fine pointer the visible
+  box is the hit area (≥ 24 px, 32 px and up for sized controls); under a coarse pointer every
+  action and choice control reaches 44 px through an invisible extension, and text fields do not
+  (hence `fieldSize: 'lg'` for touch). Keep `gap-2` or more between wrapping rows of `sm` controls.
+- `provideBfLabels({ ... })` replaces the built-in English strings (`loading`, `dismiss`, `tabBar`,
+  `tabBadge(count)`, `back`, `ok`, `cancel`, `actions`, `sheet`, `modal`, `refreshing`, `close`,
+  `dialog`) and the
+  default error text per validator kind (`validation`: `required`, `email`, `pattern`, `parse`,
+  `min(n)`, `max(n)`, `minLength(n)`, `maxLength(n)`, `minDate(d)`, `maxDate(d)`, `fallback`),
+  merged key by key; a key set to `undefined` also keeps the parent's string. Use it for any
+  non-English app instead of passing `errorMessage`/`ariaLabel` text to every widget; German copy
+  writes "ss", never "ß" (`dismiss: 'Schliessen'`).
+  `bfValidationMessage(error, labels.validation)` returns the text a widget shows for one error:
+  its own `message`, else the default for its kind. `bf-sheet` and `bf-modal` opened without an
+  `ariaLabel` are named by the first heading in their content (also one that renders later), and
+  fall back to `sheet`/`modal`.
+- What a component-level `provideBfLabels()` covers: the widgets, form controls and
+  `bf-back-button`/`bf-refresher` rendered inside that component (`loading`, `dismiss`, `tabBar`,
+  `tabBadge`, `back`, `refreshing`, `validation`). The overlay services (`BfAlertDialogService`
+  `ok`, `BfActionSheetService` `cancel`/`actions`, `BfSheetService` `sheet`, `BfModalService`
+  `modal`, `BfDialogService` `close`/`dialog`/`ok`/`cancel`, `BfDesktopToastService`
+  `notifications`) are root singletons: they read the app-level labels unless the call passes the
+  feature's injector, `open(…, { injector: inject(Injector) })`, which also makes it the parent of
+  the overlay content's injector, so the content sees the feature's providers too.
+
+```ts
+// Desktop web app: nothing to configure; md is the default. Localise the strings once.
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideBfLabels({
+      back: 'Zurück',
+      cancel: 'Abbrechen',
+      tabBadge: (count) => `${count} neu`,
+      validation: { required: 'Pflichtfeld' },
+    }),
+  ],
+};
+
+// Capacitor app: 48 px text fields as on a phone (use { size: 'lg' } to enlarge every control).
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideRouter(routes, withBfShellRouting()),
+    provideBfShell(),
+    provideBfDefaults({ fieldSize: 'lg' }),
+  ],
+};
+```
+
+## Overlays (`@bitforgehq/ui/overlay`)
+
+A desktop or plain web app (no Capacitor, no router required) installs `@angular/cdk` and `rxjs`
+alongside `@bitforgehq/ui` and imports this entry for a centred dialog, a stacked toast and
+keyboard-operable menus. Open every overlay from code through its service; never place `bf-dialog`
+or `bf-desktop-toast` in a template outside the service that renders them.
+
+- **Dialog vs sheet/modal:** `BfDialogService.open(component | template, config)` opens a centred
+  `bf-dialog` (`role="dialog"`, or `"alertdialog"` for `confirm()`) that traps focus, locks page
+  scroll and is sized `sm`/`md`/`lg`/`xl`. Use it for any desktop or web app screen. `/mobile`'s
+  `BfSheetService`/`BfModalService` render phone-shaped, edge-anchored panels for the Capacitor
+  shell — do not use them in a desktop-only app; use `bf-dialog` there instead, even for a form
+  that would be a sheet on a phone.
+- **Confirm:** `BfDialogService.confirm({ title, message?, buttons?, size?, injector? })` opens an
+  alert dialog and resolves the pressed button's `id ?? label` (default `cancel`/`ok`); focus
+  starts on the cancel button, `Escape` answers with it (or is ignored without one, per APG alert
+  dialog). It is the desktop equivalent of `/mobile`'s `BfAlertDialogService.open()`.
+- **Desktop toast vs mobile toast:** `BfDesktopToastService.show({ message, action?, duration?,
+injector? })` stacks up to three cards bottom-right (configurable with
+  `provideBfDesktopToast()`), following the same timing/persistence/replace rules as `/mobile`'s
+  `BfToastService` (which shows one phone-width toast at a time). Use the desktop service outside
+  the Capacitor shell; never both in the same app screen.
+- **Menu:** `bf-menu` (a `CdkMenu` panel) opened from `[bfMenuTriggerFor]` on any element, or from
+  the styled `bf-menu-button`. Items are `bfMenuItem` (`<button>` or `<a>`), `bfMenuItemCheckbox`,
+  `bfMenuItemRadio` (grouped with `bfMenuGroup`), dividers with `bfMenuDivider`, and submenus by
+  nesting another `[bfMenuTriggerFor]` on an item. Keyboard follows APG menu button/menu: open
+  keys, arrow navigation with wrap, Home/End, type-ahead, `Escape`/`Tab` close with focus back on
+  the trigger, `ArrowRight`/`ArrowLeft` for submenus. A menu opened from inside a `bf-dialog`:
+  `Escape` closes only the menu, never the dialog underneath.
+- **`closeOnNavigation`:** every overlay (`BfDialogConfig`, `confirm()`, and the `/mobile` sheet,
+  modal, action sheet and alert options) closes when the URL path changes by default (`true`);
+  pass `closeOnNavigation: false` to keep one open across a navigation (e.g. a draft that must
+  survive browser back). Toasts (both desktop and mobile) never close on navigation.
+- **The `injector` option:** `BfDialogService.open()`/`confirm()`, `BfDesktopToastService.show()`
+  and the `/mobile` sheet, modal, action sheet and alert services all take an `injector` (default
+  the root injector), which becomes the parent of the content's injector and is what a
+  feature-level `provideBfLabels()` or other providers must reach through — pass
+  `inject(Injector)` from the calling feature, not the app root's. The `/mobile` `BfToastService`
+  has no `injector` option (its one-at-a-time toast never opens a labelled stack).
+- **Focus rules:** a dialog traps Tab/Shift+Tab inside its pane and restores focus to the opener
+  on close (`autoFocus`: `'first-tabbable'`, the default, or `'panel'` for long content with no
+  natural first control); a menu returns focus to its trigger on `Escape`, `Tab` or an item
+  activation. Initial focus in `confirm()`/alert-style overlays lands on the `cancel`-role button
+  (APG alert dialog), not the first button.
+- **`F6` for toasts:** pressing `F6` on the page moves focus to the action of the newest toast
+  that has one; `F6` inside the toast stack moves focus back to where it was (the key is left to
+  the browser otherwise) — this is the desktop toast's only keyboard path to its action beyond Tab
+  through the page content. It does nothing while a modal overlay is open (`BfOverlayStack.count()
+  > 0`), so it never escapes that overlay's focus trap.
+- **Scroll lock and inert outside the shell:** without `provideBfShell()` (a desktop or plain web
+  app), an open non-passive overlay (dialog, confirm) blocks document scroll and makes every other
+  direct child of `<body>` `inert` except the CDK overlay container and live-announcer elements
+  (mark an element that must stay usable, such as your own live region, `data-bf-overlay-keep`).
+  Inside the shell (`provideBfShell()`) nothing changes: the document never scrolls, so no lock is
+  applied, and the page stack (not the whole body) is made inert instead. Toasts never lock scroll
+  or make anything inert, on either entry.
+- **Import migration:** the overlay core (`BfOverlayService`, `BfOverlayRef`, `BfOverlayStack`,
+  the animations, …) moved from `@bitforgehq/ui/mobile` to `@bitforgehq/ui/overlay` in 0.3.0;
+  `/mobile`'s old exports are deprecated aliases removed in 0.4.0. See the CHANGELOG's `### overlay
+entry` migration table for the full old-import → new-import list.
+
+## Mobile shell (`@bitforgehq/ui/mobile`)
+
+A Capacitor app additionally imports `@bitforgehq/ui/mobile` for the native app shell. Three
+rules, then the setup, step by step (the docs site's `/mobile` page shows the same steps):
+
+- The app renders inside a fixed page frame — the frame itself never scrolls.
+- `bf-content` is the only scroller inside a page: one per `bf-page`, after its `bf-header`.
+- Routed pages read route state (params, query params, data) through `input()`, never by
+  injecting `ActivatedRoute` directly in the page.
+
+### 1. Add the shell and its peers
+
+Start from an app set up as on [Install](https://bitforge-ui.web.app/install). `@bitforgehq/ui/mobile` needs `@angular/cdk`, `@angular/router`, `@capacitor/core` and `rxjs`: optional peers of the package, required for this entry. The shell's Capacitor plugins are optional peers, and the entry builds and runs without the ones you skip, but a shell app needs `@capacitor/keyboard`: the `capacitor.config.ts` of step 5 imports `KeyboardResize` from it for the required `resize: 'none'`, as the mobile demo's does. The plugins:
+
+- `@capacitor/app` (optional): the Android hardware back button;
+- `@capacitor/keyboard` (needed): the keyboard height and events, and the `Keyboard` config;
+- `@capacitor/haptics` (optional): the tick on a tab change.
+
+List the plugins in the `dependencies` of the `package.json` beside `capacitor.config.ts`. The Capacitor CLI finds plugins only there: `cap sync` skips a plugin listed only in a workspace root, so check its "Found N Capacitor plugins" lines.
+
+```bash
+bun add @angular/cdk @angular/router @capacitor/core rxjs
+bun add @capacitor/app @capacitor/keyboard @capacitor/haptics
+bun add -d @capacitor/cli
+```
+
+### 2. Provide the shell
+
+In `src/app/app.config.ts`, add `provideBfShell()` and pass `withComponentInputBinding()` and `withBfShellRouting()` to `provideRouter()`. The shell does not render correctly without `provideBfShell()` and `withBfShellRouting()`; `withComponentInputBinding()` binds route params and data to the pages' inputs. `provideBfDefaults({ fieldSize: 'lg' })` gives text fields their 48 px phone height (see [Density](https://bitforge-ui.web.app/density#capacitor-app)).
+
+`app.config.ts`:
+
+```ts
+import { type ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
+import { provideRouter, withComponentInputBinding } from '@angular/router';
+import { provideBfDefaults } from '@bitforgehq/ui';
+import { provideBfShell, withBfShellRouting } from '@bitforgehq/ui/mobile';
+import { routes } from './app.routes';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideBrowserGlobalErrorListeners(),
+    provideRouter(routes, withComponentInputBinding(), withBfShellRouting()),
+    provideBfShell(),
+    // 48 px text fields, as on a phone; buttons and choice controls keep md with a 44 px touch area.
+    provideBfDefaults({ fieldSize: 'lg' }),
+  ],
+};
+```
+
+### 3. Give the root a height
+
+The root component (`src/app/app.ts`) hosts one `bf-stack-outlet`, and the outlet is `height: 100%` of it. Give the root's host `block h-dvh`: without a height the outlet is zero pixels tall and nothing renders, with no error in the console.
+
+`app.ts`:
+
+```ts
+import { Component } from '@angular/core';
+import { BfStackOutletComponent } from '@bitforgehq/ui/mobile';
+
+@Component({
+  selector: 'app-root',
+  // The outlet is `height: 100%`: without a height here it has zero height and shows nothing.
+  host: { class: 'block h-dvh' },
+  imports: [BfStackOutletComponent],
+  template: `<bf-stack-outlet />`,
+})
+export class App {}
+```
+
+### 4. Set the viewport and the body
+
+In `src/index.html`:
+
+- `viewport-fit=cover` lets the page reach under the notch and the home indicator, and the shell pads itself by the safe areas.
+- Leave out `maximum-scale` and `user-scalable`, so the web build keeps pinch zoom (WCAG 1.4.4). On native platforms `provideBfShell()` adds `maximum-scale=1, user-scalable=no` at boot: WKWebView zooms into a focused control whose text is under 16 px and never zooms back, so the native shell forbids zoom and follows the system text size instead.
+- `bg-bg text-text` on `<body>` gives the page the theme colours, in light and dark mode.
+
+```html
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+<!-- … -->
+<body class="bg-bg text-text">
+  <app-root></app-root>
+</body>
+```
+
+### 5. Configure Capacitor
+
+Create `capacitor.config.ts` beside `package.json` (it imports `KeyboardResize` from `@capacitor/keyboard`, installed in step 1), with the `appId`, `appName` and the `webDir` your `ng build` writes. Keep each of these keys; the keyboard handling and the safe areas depend on every one:
+
+- `ios.scrollEnabled: false`: the document never scrolls, so WKWebView cannot jump the page when focus moves between fields. `bf-content` is the only scroller.
+- `plugins.Keyboard.resize: 'none'` (`KeyboardResize.None`): on iOS the keyboard overlays a stable page, and `bf-content` pads itself and reveals the focused field. Never set `Keyboard.resizeOnFullScreen`: the SystemBars plugin owns the Android keyboard inset.
+- `plugins.SystemBars.insetsHandling: 'css'`: on Android the WebView resizes with the keyboard and the safe-area insets stay correct. `initialViewportFitValueHint: 'cover'` avoids a viewport jump at launch.
+
+`capacitor.config.ts`:
+
+```ts
+import type { CapacitorConfig } from '@capacitor/cli';
+import { KeyboardResize } from '@capacitor/keyboard';
+
+const config: CapacitorConfig = {
+  appId: 'com.example.myapp',
+  appName: 'My App',
+  webDir: 'dist/my-app/browser',
+  // The document never scrolls: no WKWebView page jumps between fields.
+  ios: { scrollEnabled: false },
+  plugins: {
+    // 'none': on iOS the keyboard overlays a stable frame, and bf-content reveals the field.
+    Keyboard: { resize: KeyboardResize.None },
+    // Android: the WebView resizes with the keyboard and the safe-area insets stay correct.
+    SystemBars: { insetsHandling: 'css', initialViewportFitValueHint: 'cover' },
+  },
+};
+
+export default config;
+```
+
+### 6. Check the Android manifest
+
+`bunx cap add android` (step 11) writes `android/app/src/main/AndroidManifest.xml`. Keep its activity as generated:
+
+- `uiMode` stays in `android:configChanges`, so switching the system's dark mode does not restart the app.
+- Add no `android:windowSoftInputMode`: the SystemBars plugin resizes the WebView with the keyboard.
+- Edge to edge needs no setting. From `targetSdkVersion` 35 Android draws the app under the system bars, and SystemBars passes their insets to the page (`--safe-area-inset-*`, and `env(safe-area-inset-*)` on WebView 140 and later), which the theme's `safe-*` spacing reads. Capacitor 8 has no `adjustMarginsForEdgeToEdge` option any more.
+
+```xml
+<activity
+    android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"
+    android:name=".MainActivity"
+    android:exported="true">
+    <!-- … no android:windowSoftInputMode … -->
+</activity>
+```
+
+### 7. Route a tabbed app
+
+In `src/app/app.routes.ts`, a `tabs` route holds the tab bar page, and its children are the tabs. Every page of a tab starts with the tab's segment (`home`, `home/:id`), so it pushes onto that tab's own navigation stack. Routed pages read their params and data through `input()`, which `withComponentInputBinding()` binds; they never inject `ActivatedRoute`.
+
+`app.routes.ts`:
+
+```ts
+import { type Routes } from '@angular/router';
+
+export const routes: Routes = [
+  { path: '', pathMatch: 'full', redirectTo: 'tabs' },
+  {
+    path: 'tabs',
+    loadComponent: () => import('./tabs.page').then((m) => m.TabsPage),
+    // One navigation stack per tab, keyed by the segment after `tabs/`.
+    children: [
+      { path: 'home', loadComponent: () => import('./home.page').then((m) => m.HomePage) },
+      {
+        path: 'settings',
+        loadComponent: () => import('./settings.page').then((m) => m.SettingsPage),
+      },
+      { path: '', pathMatch: 'full', redirectTo: 'home' },
+    ],
+  },
+];
+```
+
+### 8. Add the tab bar
+
+`src/app/tabs.page.ts` is the `tabs` route's page: [`bf-tabs`](https://bitforge-ui.web.app/components/tabs) around one [`bf-stack-outlet`](https://bitforge-ui.web.app/components/stack-outlet) and a [`bf-tab-bar`](https://bitforge-ui.web.app/components/tab-bar). Each [`bf-tab`](https://bitforge-ui.web.app/components/tab)'s `id` is its route segment, and `tabsPath` is the route's path.
+
+`tabs.page.ts`:
+
+```ts
+import { Component } from '@angular/core';
+import { BfTabBarComponent, BfTabComponent } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfStackOutletComponent, BfTabsComponent } from '@bitforgehq/ui/mobile';
+import { House, Settings } from 'lucide';
+
+@Component({
+  selector: 'app-tabs',
+  host: { class: 'block h-full' },
+  imports: [
+    BfTabsComponent,
+    BfStackOutletComponent,
+    BfTabBarComponent,
+    BfTabComponent,
+    BfIconComponent,
+  ],
+  template: `
+    <bf-tabs tabsPath="tabs">
+      <bf-stack-outlet />
+      <bf-tab-bar label="Main">
+        <!-- Each tab's id is its route segment under tabs/. -->
+        <bf-tab id="home" label="Home"><bf-icon [icon]="house" /></bf-tab>
+        <bf-tab id="settings" label="Settings"><bf-icon [icon]="settings" /></bf-tab>
+      </bf-tab-bar>
+    </bf-tabs>
+  `,
+})
+export class TabsPage {
+  protected readonly house = House;
+  protected readonly settings = Settings;
+}
+```
+
+### 9. Add the first page
+
+Every page is a [`bf-page`](https://bitforge-ui.web.app/components/page): a [`bf-header`](https://bitforge-ui.web.app/components/header), then one [`bf-content`](https://bitforge-ui.web.app/components/content), the only scroller of the page. The app frame never scrolls.
+
+`home.page.ts`:
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfButtonComponent, BfCardComponent } from '@bitforgehq/ui';
+import { BfContentComponent, BfHeaderComponent, BfPageComponent } from '@bitforgehq/ui/mobile';
+
+@Component({
+  selector: 'app-home',
+  imports: [
+    BfPageComponent,
+    BfHeaderComponent,
+    BfContentComponent,
+    BfCardComponent,
+    BfButtonComponent,
+  ],
+  template: `
+    <bf-page>
+      <bf-header title="Home" />
+      <!-- bf-content is the page's only scroller. -->
+      <bf-content>
+        <div class="flex flex-col gap-4 px-4 pt-2 pb-6">
+          <bf-card>
+            <p class="text-body">Tapped {{ taps() }} times.</p>
+          </bf-card>
+          <bf-button (clicked)="taps.update((n) => n + 1)">Tap</bf-button>
+        </div>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class HomePage {
+  protected readonly taps = signal(0);
+}
+```
+
+### 10. Add the second tab
+
+The Settings tab has the same shape.
+
+`settings.page.ts`:
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfListComponent, BfListItemComponent, BfToggleComponent } from '@bitforgehq/ui';
+import { BfContentComponent, BfHeaderComponent, BfPageComponent } from '@bitforgehq/ui/mobile';
+
+@Component({
+  selector: 'app-settings',
+  imports: [
+    BfPageComponent,
+    BfHeaderComponent,
+    BfContentComponent,
+    BfListComponent,
+    BfListItemComponent,
+    BfToggleComponent,
+  ],
+  template: `
+    <bf-page>
+      <bf-header title="Settings" />
+      <bf-content>
+        <bf-list class="px-4 pt-2">
+          <bf-list-item>
+            <bf-toggle label="Notifications" labelPosition="start" [(checked)]="notifications" />
+          </bf-list-item>
+        </bf-list>
+      </bf-content>
+    </bf-page>
+  `,
+})
+export class SettingsPage {
+  protected readonly notifications = signal(true);
+}
+```
+
+### 11. Leave the keyboard and text size to the shell
+
+- The shell keeps the focused field clear of the soft keyboard: `bf-content` pads and scrolls itself, and a sheet lifts above the keyboard. Add no keyboard handling of your own. To place something by the keyboard, read [`BfKeyboardService`](https://bitforge-ui.web.app/api/bf-keyboard-service), never `window.innerHeight`.
+- On iOS, [`BfTextScaleService`](https://bitforge-ui.web.app/api/bf-text-scale-service), which `provideBfShell()` starts, follows Dynamic Type. It sets the `<html>` font size to the system body size over 17 px, capped at `dynamicType.maxScale` (default 2.35) and never below 100 %, and follows live changes. Android's WebView applies the system font scale itself.
+- Size text and layout in `rem`, as the library's tokens are, so they scale together; a fixed `px` height clips enlarged text. Opt out with `provideBfShell({ dynamicType: false })`, and never set a `px` font size on `html`.
+
+### 12. Match the system bars to the theme
+
+On native iOS and Android `provideBfShell()` keeps the status-bar and navigation-bar icons readable in the in-app theme (`BfPlatformService.dark()`): it calls Capacitor's `SystemBars.setStyle()` at launch and on every theme change, with light icons in the dark theme and dark icons in the light theme. `provideBfShell({ syncSystemBars: false })` leaves the bars to your app.
+
+An Android WebView older than 140 pads the page below the bars instead of drawing it under them, so the bar areas show the activity's window background, which follows the system theme, not the in-app one. On those WebViews the shell uses the `Default` style (icons for the system theme). Give the window the page colour, so the bars match the page whenever the two themes agree: in `android/app/src/main/res/values/styles.xml` add the item to `AppTheme.NoActionBar` (its parent is already a `DayNight` theme), and add `res/values/colors.xml` and `res/values-night/colors.xml`.
+
+| WebView | App theme vs system theme | Result                                                                    |
+| ------- | ------------------------- | ------------------------------------------------------------------------- |
+| ≥ 140   | any                       | The bars draw over the page (edge-to-edge) with icons in the in-app theme |
+| < 140   | same                      | Bars in the page colour, readable icons                                   |
+| < 140   | different                 | Bars in the system colour with readable icons                             |
+
+The last row is a known limitation: only app-side native code can recolour the window background.
+
+The ≥ 140 row needs the setup of steps 4 and 5: `viewport-fit=cover` in the viewport meta and `SystemBars.insetsHandling: 'css'` (the default), so the WebView reaches under the bars and SystemBars passes their insets to the page. With `insetsHandling: 'disable'` or `'native'`, or without `viewport-fit=cover`, the page never draws under the bars, and they show the window background as on WebView < 140. The shell reads the WebView version from `Chrome/<n>` in the user agent.
+
+```xml
+<!-- res/values/styles.xml, in <style name="AppTheme.NoActionBar"> -->
+<item name="android:windowBackground">@color/bf_window_background</item>
+
+<!-- res/values/colors.xml -->
+<resources>
+    <color name="bf_window_background">#f7f5ef</color>
+</resources>
+
+<!-- res/values-night/colors.xml -->
+<resources>
+    <color name="bf_window_background">#111214</color>
+</resources>
+```
+
+### 13. Run it on a device
+
+Build the web app, add the native platforms once, then copy the build into them and run it on a device or simulator. Xcode builds the iOS app and Android Studio the Android one. `cap sync` lists the plugins it found: check that all three from step 1 are there. `cap run android` runs Gradle, which needs a JDK it supports, such as 21 (`JAVA_HOME`); `--list` shows the device ids.
+
+`cap run ios` builds with `xcodebuild`, then deploys through `Xcode.app/Contents/Developer/Applications/Simulator.app`. Xcode 27 has no Simulator.app there, so the build succeeds and the deploy fails ("There was an error opening simulator"). Then build, install and launch with `xcodebuild` and `simctl` instead, as below (the scheme is `App`; `ios/App/build` is git-ignored), or run the app from Xcode.
+
+```bash
+ng build
+bun add @capacitor/ios @capacitor/android
+bunx cap add ios
+bunx cap add android
+bunx cap sync
+bunx cap run android --target <device-id>
+bunx cap run ios --target <simulator-id>
+
+# iOS without Simulator.app (Xcode 27): build, boot, install and launch
+cd ios/App
+xcodebuild -project App.xcodeproj -scheme App -configuration Debug -sdk iphonesimulator \
+  -destination "id=<simulator-id>" -derivedDataPath build build
+xcrun simctl boot <simulator-id> || true # already booted is fine
+xcrun simctl install <simulator-id> build/Build/Products/Debug-iphonesimulator/App.app
+xcrun simctl launch <simulator-id> <appId>
+```
+
+### Keyboard
+
+The shell keeps the focused text field clear of the soft keyboard; don't add your own keyboard
+handling on top.
+
+- On a page, `bf-content` pads and scrolls itself (`bfKeyboardAssist`); a custom scroll container
+  inside a page takes `bfKeyboardAssist` itself.
+- A sheet lifts above the keyboard (iOS), is capped below the safe-area top while the keyboard is
+  up (both platforms), scrolls its content and reveals the focused field 24 px above the keyboard;
+  a page-sheet modal ends its content at the keyboard's top edge. Hiding the keyboard returns
+  both to their resting size.
+- Keep a sheet's primary action directly below its fields and a modal's in its header, so it
+  stays reachable while the keyboard is up.
+- Read the keyboard from `BfKeyboardService` (`visible()`, `height()`, `keyboardTop()`, the
+  `--bf-keyboard-height` CSS variable), never from `window.innerHeight`.
+
+### Overlays
+
+Overlays (`BfOverlayService` and the sheet, modal, toast, action-sheet and alert services built on
+it) are opened from code through a service, never placed in a template. The overlay core
+(`BfOverlayService`, `BfOverlayRef`, `BF_OVERLAY_DATA`, `BfOverlayStack`, the animations) is
+shared with the desktop overlays and imported from `@bitforgehq/ui/overlay` (see "Overlays
+(`@bitforgehq/ui/overlay`)" above for `closeOnNavigation`, the `injector` option and the inert/
+scroll-lock rules outside the shell); the `/mobile` re-exports of those names are deprecated.
+Shell-specific rules:
+
+- Open overlays through their service (`BfSheetService.open(Component, options)`,
+  `BfModalService`, `BfToastService.show()`, `BfActionSheetService.open()`,
+  `BfAlertDialogService.open()`); never render `bf-sheet`, `bf-modal`, `bf-toast`,
+  `bf-action-sheet` or `bf-alert-dialog` yourself.
+- A content component reads its input with `inject(BF_OVERLAY_DATA)` and closes itself with
+  `inject(BfOverlayRef).close(result)` (`BfSheetRef` in a sheet); the caller awaits
+  `ref.afterClosed` (`open()` returns the promise directly for action sheets and alert dialogs).
+- A sheet's content region is the only scroller inside a sheet: no `bf-content` and no nested
+  `overflow-auto` in its content; mark the content's header `data-bf-sheet-drag`.
+- An alert dialog needs a `cancel`-role button to be dismissible: without one, `Escape` and the
+  hardware back button are ignored and only a button answers it.
+- A toast with an `action` persists until the action, `Escape` inside it, `dismiss()` or the next
+  `show()` (which replaces any persistent toast) ends it; don't give it a short `duration`, and
+  `dismiss()` its ref once it is stale. Every toast pauses while hovered or focused, returns focus
+  to where it came from when it closes holding focus, and is announced once through
+  `LiveAnnouncer` — never wrap one in your own live region.
+- A desktop web app (no Capacitor) shows toasts with `BfDesktopToastService` from
+  `@bitforgehq/ui/overlay` instead of `BfToastService` (see "Overlays (`@bitforgehq/ui/overlay`)"
+  above).
+
+While a modal-like overlay is open the page stack is `inert`; outside the shell (a desktop page
+using the overlays without `provideBfShell()`) every other child of `<body>` is `inert` instead
+(mark an element that must stay usable, such as your own live region, `data-bf-overlay-keep`;
+this works only on a direct child of `<body>`, never inside the app root).
+Inside the shell no scroll lock is needed (the document never scrolls); outside it the overlay
+core blocks document scroll behind every non-passive overlay. `Escape` closes the top dismissible
+overlay, and under `provideBfShell()` so does the hardware back button (neither ever reaches one
+underneath); a backdrop tap closes sheets and action sheets only — modals and alerts ignore it.
+Toasts are passive and never block the page or its scroll.
+
+## Testing
+
+Specs of an app on `@bitforgehq/ui` run under the Angular CLI's Vitest (or Jest) with
+`@bitforgehq/ui/testing`: the jsdom shims, the test providers and CDK harnesses (the docs site's
+`/testing` page shows the same steps).
+
+### 1. Add the CDK as a dev dependency
+
+`@bitforgehq/ui/testing` holds the jsdom shims, `provideBfTesting()` and the component harnesses. The harnesses build on `@angular/cdk/testing`, so the entry needs `@angular/cdk`; a dev dependency is enough. An app that uses `@bitforgehq/ui/overlay` or `@bitforgehq/ui/mobile` already has the CDK as a dependency: skip this step.
+
+```bash
+bun add -d @angular/cdk
+```
+
+### 2. Set up Vitest, the CLI default
+
+An Angular 22 app runs its specs with Vitest and jsdom through `ng test`. jsdom has no Web Animations (`Element.animate`), no `PointerEvent` and no `matchMedia`, which the overlays and gestures use. Name a setup file in the `test` target of `angular.json`, and in it call `installBfJsdomShims()`, which installs a stand-in for each one that is missing.
+
+```json
+"test": {
+  "builder": "@angular/build:unit-test",
+  "options": {
+    "setupFiles": ["src/test-setup.ts"]
+  }
+}
+```
+
+`test-setup.ts`:
+
+```ts
+/*
+ * The test runner's setup file (`setupFiles` of the `test` target in angular.json): the browser
+ * APIs jsdom lacks and the library needs (Web Animations, PointerEvent, matchMedia), installed only
+ * where missing. `@bitforgehq/ui/testing` needs `@angular/cdk` as a dev dependency.
+ */
+import { installBfJsdomShims } from '@bitforgehq/ui/testing';
+
+installBfJsdomShims();
+```
+
+### 3. Or set up Jest
+
+With Jest and `jest-preset-angular`: install them (`bun add -d jest jest-environment-jsdom jest-preset-angular @types/jest`), and in `tsconfig.spec.json` set `"types": ["jest"]` in place of `vitest/globals`. Then add the two files below: the setup file calls `setupZonelessTestEnv()` (without it every spec fails with "Need to call TestBed.initTestEnvironment() first"), then `installBfJsdomShims()`.
+
+The library ships ES modules (`.mjs`), which the preset's own `transformIgnorePatterns` lets through, together with Angular's locale files. A config that sets its own `transformIgnorePatterns` replaces that default: keep `.mjs`, `@angular/common/locales/`, `@bitforgehq/` and `lucide` in it, or the first import fails with `SyntaxError: Cannot use import statement outside a module`.
+
+```js
+// jest.config.mjs
+export default {
+  preset: 'jest-preset-angular',
+  setupFilesAfterEnv: ['<rootDir>/src/setup-jest.ts'],
+  testEnvironment: 'jsdom',
+  transformIgnorePatterns: ['node_modules/(?!.*\\.mjs$|@angular/common/locales/.*\\.js$|@bitforgehq/|lucide)'],
+};
+
+// src/setup-jest.ts
+import { setupZonelessTestEnv } from 'jest-preset-angular/setup-env/zoneless';
+import { installBfJsdomShims } from '@bitforgehq/ui/testing';
+
+setupZonelessTestEnv();
+installBfJsdomShims();
+```
+
+### 4. Add the test providers
+
+Add one provider to `TestBed.configureTestingModule()`, as the specs below do:
+
+- `provideBfTesting()` from `@bitforgehq/ui/testing`, for the widgets and the desktop overlays. It takes the `defaults` and `labels` the app runs with. After each test it removes what overlays and the theme leave on the document: the `dark` class, the scroll block, `inert` on body children and stray overlay panes.
+- `provideBfShellTesting()` from `@bitforgehq/ui/mobile`, for a Capacitor app. It provides the router with `withComponentInputBinding()` and `withBfShellRouting()`, the shell with swipe-back and haptics off, an in-memory theme store and the same cleanup.
+
+The cleanup runs when TestBed tears the test environment down. Keep TestBed's default `teardown: { destroyAfterEach: true }`: with `false`, nothing is cleaned between tests.
+
+### 5. Wait until the fixture is stable
+
+Angular 22 apps are zoneless: nothing runs change detection between the steps of a test. After you create a component or change its state, `await fixture.whenStable()` before you read the DOM. Harness methods wait on their own.
+
+`app.component.spec.ts`:
+
+```ts
+import { Component } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { BfButtonComponent } from '@bitforgehq/ui';
+
+@Component({
+  imports: [BfButtonComponent],
+  template: `<bf-button variant="tonal">Save</bf-button>`,
+})
+class HostComponent {}
+
+describe('bf-button in a consumer app (Vitest)', () => {
+  it('renders a native button with the projected label', async () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    await fixture.whenStable();
+    const button = (fixture.nativeElement as HTMLElement).querySelector('button');
+    expect(button).not.toBeNull();
+    expect(button?.textContent?.trim()).toBe('Save');
+  });
+});
+```
+
+### 6. Drive a form widget through its harness
+
+The entry ships CDK harnesses for the widgets whose markup is not obvious to drive: `BfSelectHarness`, `BfRadioGroupHarness`, `BfSegmentedHarness`, `BfDialogHarness`, `BfMenuHarness`, `BfMenuItemHarness`, `BfMenuButtonHarness` and `BfDesktopToastHarness`. `with({ label })` finds a widget by its label. Load an in-page widget with `TestbedHarnessEnvironment.loader(fixture)`.
+
+`select-harness.spec.ts`:
+
+```ts
+/*
+ * A Signal Forms `bf-select` with numeric options, driven through `BfSelectHarness` by label: the
+ * form model holds the option's number, and a touched required select shows the default message.
+ */
+import { Component, signal } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { TestbedHarnessEnvironment } from '@angular/cdk/testing/testbed';
+import { FormField, form, required } from '@angular/forms/signals';
+import { BfSelectComponent, type BfSelectOption } from '@bitforgehq/ui';
+import { BfSelectHarness, provideBfTesting } from '@bitforgehq/ui/testing';
+
+@Component({
+  imports: [BfSelectComponent, FormField],
+  template: `<bf-select label="Quantity" [options]="quantities" [formField]="order.quantity" />`,
+})
+class OrderFormComponent {
+  readonly quantities: readonly BfSelectOption<number>[] = [
+    { value: 1, label: 'One' },
+    { value: 2, label: 'Two' },
+    { value: 3, label: 'Three' },
+  ];
+  private readonly model = signal<{ quantity: number | null }>({ quantity: null });
+  readonly order = form(this.model, (path) => {
+    required(path.quantity);
+  });
+}
+
+describe('BfSelectHarness in a consumer app (Vitest)', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ providers: [provideBfTesting()] });
+  });
+
+  async function setup() {
+    const fixture = TestBed.createComponent(OrderFormComponent);
+    await fixture.whenStable();
+    const select = await TestbedHarnessEnvironment.loader(fixture).getHarness(
+      BfSelectHarness.with({ label: 'Quantity' }),
+    );
+    return { fixture, select };
+  }
+
+  it('selects an option by label and the form model holds its number', async () => {
+    const { fixture, select } = await setup();
+
+    expect(await select.getOptionLabels()).toEqual(['One', 'Two', 'Three']);
+    await select.selectOption('Two');
+
+    expect(fixture.componentInstance.order.quantity().value()).toBe(2);
+    expect(await select.getValueLabel()).toBe('Two');
+  });
+
+  it('shows the default required message once the select was touched', async () => {
+    const { select } = await setup();
+
+    expect(await select.getErrorText()).toBe('');
+    await select.focus();
+    await select.blur();
+
+    expect(await select.getErrorText()).toBe('Fill in this field');
+  });
+});
+```
+
+### 7. Drive a dialog from the document root
+
+Dialogs, menus and toasts render in the CDK overlay container at the end of `<body>`, outside the fixture. Load their harnesses with `TestbedHarnessEnvironment.documentRootLoader(fixture)`.
+
+`dialog-harness.spec.ts`:
+
+```ts
+/*
+ * A `confirm()` alert dialog through `BfDialogHarness`: dialogs render in the CDK overlay
+ * container, so the harness comes from the document root loader.
+ */
+import { Component, inject } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { TestbedHarnessEnvironment } from '@angular/cdk/testing/testbed';
+import { BfDialogService } from '@bitforgehq/ui/overlay';
+import { BfDialogHarness, provideBfTesting } from '@bitforgehq/ui/testing';
+
+@Component({ template: '' })
+class ProjectActionsComponent {
+  private readonly dialogs = inject(BfDialogService);
+
+  confirmDelete(): Promise<string | undefined> {
+    return this.dialogs.confirm({
+      title: 'Delete project?',
+      message: 'This cannot be undone.',
+      buttons: [
+        { id: 'cancel', label: 'Cancel', role: 'cancel' },
+        { id: 'delete', label: 'Delete', role: 'destructive' },
+      ],
+    });
+  }
+}
+
+describe('BfDialogHarness in a consumer app (Vitest)', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ providers: [provideBfTesting()] });
+  });
+
+  it('reads a confirm() alert dialog and resolves the pressed button id', async () => {
+    const fixture = TestBed.createComponent(ProjectActionsComponent);
+    await fixture.whenStable();
+    const answer = fixture.componentInstance.confirmDelete();
+
+    const dialog = await TestbedHarnessEnvironment.documentRootLoader(fixture).getHarness(
+      BfDialogHarness.with({ label: 'Delete project?' }),
+    );
+    expect(await dialog.getRole()).toBe('alertdialog');
+    expect(await dialog.getText()).toBe('This cannot be undone.');
+
+    await dialog.clickButton('Delete');
+    await expect(answer).resolves.toBe('delete');
+  });
+});
+```
+
+### 8. Test a sheet in a Capacitor app
+
+Under `provideBfShellTesting()` the shell's overlay services work as they do in the app. Open a sheet in an injection context, then find it in the document. A theme change stays in memory, so `localStorage` is never written, and the `dark` class is gone after the test.
+
+`sheet.spec.ts`:
+
+```ts
+/*
+ * The mobile shell under a consumer's Vitest: `provideBfShellTesting()` (router, shell, in-memory
+ * theme, document cleanup); a `bf-sheet` opens into the document and is gone once dismissed, and
+ * no theme class is left on `<html>` afterwards.
+ */
+import { Component, inject } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { BfPlatformService, BfSheetService, provideBfShellTesting } from '@bitforgehq/ui/mobile';
+
+@Component({
+  selector: 'app-sheet-body',
+  template: `<p class="p-4">Sheet body</p>`,
+})
+class SheetBodyComponent {}
+
+describe('bf-sheet in a consumer app (Vitest)', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ providers: [provideBfShellTesting()] });
+  });
+
+  it('opens a sheet into the document and removes it once dismissed', async () => {
+    const ref = TestBed.runInInjectionContext(() =>
+      inject(BfSheetService).open(SheetBodyComponent),
+    );
+    TestBed.inject(BfPlatformService).theme.set('dark');
+    TestBed.tick();
+
+    expect(document.querySelector('bf-sheet')?.textContent).toContain('Sheet body');
+    expect(document.documentElement.classList.contains('dark')).toBe(true);
+    expect(window.localStorage.getItem('bf-theme')).toBeNull();
+
+    ref.close();
+    await ref.afterClosed;
+
+    expect(document.querySelector('bf-sheet')).toBeNull();
+    expect(document.body.textContent).not.toContain('Sheet body');
+
+    // What runs after each test: the environment's teardown clears the theme class.
+    TestBed.resetTestingModule();
+    expect(document.documentElement.classList.contains('dark')).toBe(false);
+  });
+});
+```
+
+### 9. Assert on roles, text and values
+
+Test what a user and the rest of the app see:
+
+- the role and accessible name of an element, or a harness found by its label;
+- the text a widget shows, such as its validation message;
+- the values it writes into the form model or emits from its outputs.
+
+Don't assert on the library's CSS classes or internal markup. They are styling details, not API, and they change with the design.
+
+## Design foundations (Meadow Sage)
+
+Warm off-white canvas (`bg-bg`), white surfaces, sage green primary, pill-shaped controls,
+radii 12/16/24 px (`rounded-tile/field/card`), 1.5 px control borders, soft layered shadows
+(`shadow-raised`, `shadow-floating`), Manrope type (`text-display/title/heading/body/caption`).
+
+### Type and spacing scale
+
+- Type (rem tokens; px at a 16 px root): `text-display` 40, `text-title` 28, `text-heading` 18,
+  `text-body` 15/24 and `text-label` 15/20, `text-label-sm` 14, `text-caption` 13/18 and
+  `text-label-xs` 13/16, `text-micro` 12 (weight 600), `text-nano` 11. Never `text-[15px]` or
+  Tailwind's `text-sm`/`text-xs`.
+- Spacing: 2 · 4 · 6 · 8 · 10 · 12 · 14 · 16 · 18 · 20 · 24 · 32 · 48 px as `--spacing` multiples
+  (`p-3.5`, `px-4.5`); never arbitrary px. Semantic steps: `gutter` 16, `card` 18,
+  `control-sm/md/lg` 32/40/48, `hit` 44 (`min-h-hit`), `box` 22 (`size-box`).
+- Also `rounded-checkbox` (7 px), `bg-scrim` (black in both modes), `ease-ios`/`ease-md`/`ease-settle`.
+
+## Component index
+
+Grouped by category. Each page in `ai/components/<name>.md` follows the same order as the docs
+site: overview, usage sections with examples, inputs, outputs, slots, dos and don'ts, migration
+notes.
+
+### Actions
+
+| Component        | Entry point      | Purpose                                                                        |
+| ---------------- | ---------------- | ------------------------------------------------------------------------------ |
+| `bf-action-bar`  | `@bitforgehq/ui` | Floating pill of contextual actions that appears while items are selected      |
+| `bf-button`      | `@bitforgehq/ui` | Pill-shaped action button with five variants, three sizes and a loading state  |
+| `bf-icon-button` | `@bitforgehq/ui` | Round icon-only button for toolbars and rows, with a required accessible label |
+
+### Forms
+
+| Component         | Entry point                   | Purpose                                                                                     |
+| ----------------- | ----------------------------- | ------------------------------------------------------------------------------------------- |
+| `bf-checkbox`     | `@bitforgehq/ui`              | Rounded checkbox with an optional label that binds to Signal Forms                          |
+| `bf-chip`         | `@bitforgehq/ui`              | Toggleable filter chip with a check mark when selected, in tonal or ink style               |
+| `bf-chip-group`   | `@bitforgehq/ui`              | Named row of chips that picks one like radios, or groups independent toggles                |
+| `bf-field`        | `@bitforgehq/ui`              | Label, help text and error text wrapper that wires ids for assistive tech                   |
+| `bf-input`        | `@bitforgehq/ui`              | Single-line text field with label, help and error text, icon slots and Signal Forms binding |
+| `bf-number-input` | `@bitforgehq/ui/number-input` | Number field that binds number or null, with native min, max and step                       |
+| `bf-radio-group`  | `@bitforgehq/ui`              | Group of radio buttons for choosing one option, with optional per-option descriptions       |
+| `bf-segmented`    | `@bitforgehq/ui`              | Segmented control for switching between two to four views, keyboard-navigable like radios   |
+| `bf-select`       | `@bitforgehq/ui`              | Native single-choice dropdown styled like the text field, with Signal Forms binding         |
+| `bf-textarea`     | `@bitforgehq/ui`              | Multi-line text field with label, help and error text, and Signal Forms binding             |
+| `bf-toggle`       | `@bitforgehq/ui`              | On/off switch for settings that apply immediately, with Signal Forms binding                |
+
+### Data display
+
+| Component      | Entry point      | Purpose                                                                                 |
+| -------------- | ---------------- | --------------------------------------------------------------------------------------- |
+| `bf-avatar`    | `@bitforgehq/ui` | Round avatar showing a photo or initials, in three sizes and four color variants        |
+| `bf-badge`     | `@bitforgehq/ui` | Small status label in semantic tones, or a compact numeric pill for counts              |
+| `bf-card`      | `@bitforgehq/ui` | Content surface with an optional header slot, in four visual styles from raised to flat |
+| `bf-list`      | `@bitforgehq/ui` | Container for list rows, inset by default with rounded corners on a warm background     |
+| `bf-list-item` | `@bitforgehq/ui` | List row with leading slot, title, subtitle, trailing slot and an optional chevron      |
+| `bf-progress`  | `@bitforgehq/ui` | Progress bar in two sizes and four tones for completion, quotas and unknown waits       |
+
+### Feedback
+
+| Component        | Entry point      | Purpose                                                                            |
+| ---------------- | ---------------- | ---------------------------------------------------------------------------------- |
+| `bf-alert`       | `@bitforgehq/ui` | Inline status message in four tones with a title and an optional dismiss button    |
+| `bf-empty-state` | `@bitforgehq/ui` | Placeholder for an empty screen or list with icon, title, message and action       |
+| `bf-spinner`     | `@bitforgehq/ui` | Indeterminate loading spinner in three sizes that inherits its parent's text color |
+
+### Navigation
+
+| Component         | Entry point             | Purpose                                                                                     |
+| ----------------- | ----------------------- | ------------------------------------------------------------------------------------------- |
+| `bf-back-button`  | `@bitforgehq/ui/mobile` | Header back button that pops the page stack or falls back to a default route                |
+| `bf-content`      | `@bitforgehq/ui/mobile` | Page's single scroll container that keeps focused fields clear of the soft keyboard         |
+| `bf-header`       | `@bitforgehq/ui/mobile` | Page header toolbar with a large title that collapses into the toolbar on scroll            |
+| `bf-page`         | `@bitforgehq/ui/mobile` | Frame for one stacked mobile screen that supplies lifecycle events and shared page state    |
+| `bf-refresher`    | `@bitforgehq/ui/mobile` | Pull-to-refresh indicator with haptic feedback, native iOS bounce and an Android-style pull |
+| `bf-stack-outlet` | `@bitforgehq/ui/mobile` | Router outlet keeping a live page stack with slide transitions and iOS swipe back           |
+| `bf-tab`          | `@bitforgehq/ui`        | One tab bar destination with an icon, a label and an optional count badge                   |
+| `bf-tab-bar`      | `@bitforgehq/ui`        | Floating pill tab bar for mobile apps with arrow-key selection and count badges             |
+| `bf-tabs`         | `@bitforgehq/ui/mobile` | Tabs page with one navigation stack per tab, wiring the tab bar to the router               |
+
+### Overlays
+
+| Component          | Entry point              | Purpose                                                                                       |
+| ------------------ | ------------------------ | --------------------------------------------------------------------------------------------- |
+| `bf-action-sheet`  | `@bitforgehq/ui/mobile`  | Bottom panel of labelled actions with a separate cancel button, destructive ones shown in red |
+| `bf-alert-dialog`  | `@bitforgehq/ui/mobile`  | Centred confirmation dialog with a title, message and a row of role-styled buttons            |
+| `bf-desktop-toast` | `@bitforgehq/ui/overlay` | Desktop notification card in a bottom corner stack of up to three                             |
+| `bf-dialog`        | `@bitforgehq/ui/overlay` | Desktop modal dialog with a title, scrolling body, footer actions and focus trap              |
+| `bf-menu`          | `@bitforgehq/ui/overlay` | Keyboard-operable menu panel with items, checkbox and radio items, groups and submenus        |
+| `bf-menu-button`   | `@bitforgehq/ui/overlay` | Styled button that opens a menu, with outline, text, tonal and icon-only looks                |
+| `bf-modal`         | `@bitforgehq/ui/mobile`  | Modal overlay shown as an inset card over the scaled-down page, or full screen                |
+| `bf-sheet`         | `@bitforgehq/ui/mobile`  | Bottom sheet with snap points, drag to dismiss and a backdrop                                 |
+| `bf-toast`         | `@bitforgehq/ui/mobile`  | Passive status pill with an optional action that never steals focus                           |
+
+### Icons
+
+| Component | Entry point            | Purpose                                                                               |
+| --------- | ---------------------- | ------------------------------------------------------------------------------------- |
+| `bf-icon` | `@bitforgehq/ui/icons` | Tree-shakable Lucide icon renderer, decorative by default or labelled when meaningful |
+
+## Upgrading
+
+Each component page ends with its migration notes per version. `MANIFEST.json` marks deprecated
+members with their replacement.
+
+0.3.0 moved the overlay core (`BfOverlayService`, `BfOverlayRef`, `BfOverlayStack`, the animations,
+…) from `@bitforgehq/ui/mobile` to the new `@bitforgehq/ui/overlay` entry; `/mobile`'s old exports
+are deprecated aliases of the same classes and tokens, removed in 0.4.0. The package
+`CHANGELOG.md` (shipped in `@bitforgehq/ui`), `## 0.3.0`, `### overlay entry` carries the full
+old-import → new-import table — run a project-wide replace of the import specifier for every name
+in it rather than editing one call site at a time.