bitboss-ui 3.0.0-beta.2 → 3.0.0-beta.21

package/dist/ai/composables/useBbConfig.md

@@ -34,17 +34,78 @@ declare function setConfig(patch: Partial<DynamicConfig>): void;
 // DynamicConfig = { locale: 'it' | 'en' }
 ```
 
-Merges the patch into the live config object. The change is global, immediate,
-and reactive — every mounted component that reads the key updates.
-
-**SSR caveat — call it on the client only.** On an SSR server (Nuxt, Inertia
-SSR) the config object is a **process-global singleton**, not per-request
-state — the same rule `ssrViewportWidth` documents: there is no per-request
-override. Calling `setConfig` during a server render mutates the config for
-the whole process, leaking that visitor's locale into concurrent and
-subsequent renders for other visitors. A per-visitor locale that is already
-right on the server's first paint is not possible today; the first paint
-renders in the build-time `locale` and the client switches after hydration.
+Merges the patch into **this app's** config. The change is immediate and
+reactive — every mounted component in that app which reads the key updates.
+
+### Per-request locale under SSR
+
+The config is held **per Vue app**, and SSR gives every request its own app,
+so a per-visitor locale is correct on the server's first paint. Set it where
+the app is created:
+
+```ts
+// server entry — one app per request, so this is per-request
+const app = createSSRApp(App);
+app.use(bitbossUiPlugin, { locale: localeFor(request) });
+```
+
+That is the route to prefer. It is right before hydration, so it is what
+crawlers index, what a prerendered search index reads, and what a reader with
+JS disabled keeps.
+
+#### Nuxt
+
+**Do not call `app.use(bitbossUiPlugin)` in Nuxt** — the `bitboss-ui/nuxt`
+module registers the runtime plugin for you, and that plugin provides the
+per-app config itself. `defineNuxtPlugin` runs per request on the server and
+Nuxt builds one Vue app per request, so your own plugin is the per-request
+seam:
+
+```ts
+// plugins/bitboss-locale.ts
+import { useBbConfig } from 'bitboss-ui';
+
+export default defineNuxtPlugin((nuxtApp) => {
+	const locale = localeFor(useRequestEvent());
+	// A plugin has an APP but no component instance, so hand it the app's
+	// injection context — otherwise the write cannot find this app's config
+	// and lands on the process-global defaults.
+	nuxtApp.vueApp.runWithContext(() => {
+		useBbConfig().setConfig({ locale });
+	});
+});
+```
+
+Calling `setConfig` from a component's `setup` works in Nuxt too, and is
+per-request for the same reason. `runWithContext` is only needed where no
+component exists yet.
+
+> Fixed in 3.0.0-beta.19 (Q20.4). Before that the Nuxt runtime plugin never
+> provided the config, so **every** `setConfig` under Nuxt — including from a
+> component's `setup`, the path this page prescribed — wrote the process-global
+> and leaked across concurrent visitors, silently. If you worked around it,
+> you can stop.
+
+#### The rule, and what the dev warning means
+
+**`setConfig` during a server render needs an app to address.** From a
+component's `setup` (or a composable a component calls), or inside
+`app.runWithContext`, it resolves the current app and the write is
+per-visitor. With neither — module scope, say — there is no app, the write
+lands on the process-global build-time defaults, and it leaks into other
+visitors being served concurrently.
+
+The dev warning fires on exactly that: it compares where the write actually
+landed against the build-time object, rather than guessing from the call site.
+So it stays silent for a correct per-app write, and it still fires for a
+global one made from inside a component — which is what a missing plugin (or,
+before beta.19, Nuxt) produced.
+
+On the client none of this matters: one process is one user, and `setConfig`
+from anywhere is fine.
+
+_(Changed in 3.0.0-beta.15 — Q18.2. Before it, the config was a single
+process-global object and a per-visitor locale genuinely was impossible.)_
 
 ## Usage example
 

package/dist/ai/composables/useConfirm.md

@@ -9,7 +9,9 @@ type: composable
 ## Summary
 
 `useConfirm` opens a modal confirm dialog and returns a promise that resolves
-with the user's decision. Dialogs are queued — if one is open, the next waits.
+with the user's decision. **A new `confirm()` replaces the open dialog**: the
+superseded promise resolves `false` and no callback runs. Dialogs do not queue,
+so `await` one before opening the next.
 Per the design language, every `destructive` action must pass through a confirm.
 
 **Requires exactly one `<BbConfirm />` host, mounted at the app root** (`App.vue`
@@ -28,7 +30,7 @@ const { confirm, close, dismissAll } = useConfirm();
 
 **Ownership** — when called inside a component (any effect scope), the
 returned `confirm`'s dialogs are tied to that scope: if it is disposed while a
-dialog is open or queued (browser Back, route change, the component unmounts),
+dialog is open (browser Back, route change, the component unmounts),
 the dialog is dismissed quietly — promise resolved `false`, no callback runs.
 Call `useConfirm()` outside a component scope (app setup, store, module level)
 for app-lifetime confirms.
@@ -71,7 +73,7 @@ promise pending.
 declare function dismissAll(): void;
 ```
 
-Quietly dismisses the open dialog and any queued ones, regardless of owner:
+Quietly dismisses the open dialog, regardless of owner:
 pending promises resolve `false`, no callback runs. An imperative escape hatch
 for app-level events — logout, a global error boundary, or router wiring in
 apps that want route-based dismissal.

package/dist/ai/guides/ai-router.md

@@ -14,13 +14,18 @@ Knowledge base root (installed package):
 Package export entry: `bitboss-ui/ai` → `dist/ai/index.md`.
 Subpaths: `bitboss-ui/ai/components.json`, `bitboss-ui/ai/guides/…`, etc.
 
-**Not installed, or can only fetch URLs?** The same files are served from the
-published package at `https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/…`.
-If you can make only one request, fetch
-[`…@beta/dist/llms-medium.txt`](https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-medium.txt)
+**Not installed, or can only fetch URLs?** The same files are served at
+`https://llms-bitboss-ui.bitboss.it/dist/ai/…`. If you can make only one
+request, fetch
+[`/dist/llms-medium.txt`](https://llms-bitboss-ui.bitboss.it/dist/llms-medium.txt)
 — this router plus the agent contract, setup, component picker, design language
 and the full component catalogue, in ~110 KB.
 
+That host is a thin proxy in front of the published npm tarball. If it is ever
+unreachable, the same paths work directly against
+`https://cdn.jsdelivr.net/npm/bitboss-ui@beta/…` — one hop further from us, and
+pinned to the prerelease channel rather than following it.
+
 ---
 
 ## Mandatory order (every UI task)

package/dist/ai/guides/component-picker.md

@@ -231,24 +231,24 @@ a composable you want is not in this corpus's `composables/` folder — it is no
 here.** Check this list before inventing a name; if the need is genuinely absent,
 compose it or write it yourself.
 
-| Assumed component or composable                                | Reality                                                                                                                                                                                                                                                                                                                                   |
-| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `BbColumnManager` — show/hide/reorder columns                  | Does not exist. Compose `BbPopover` + `BbCheckbox` and persist the ordered visible keys yourself.                                                                                                                                                                                                                                         |
-| `BbKanban` / drag-and-drop board                               | Does not exist. There is no DnD primitive in the library at all — compose the board from `BbTable` (a table/list view of the same data) or hand-roll the drag-and-drop interaction yourself.                                                                                                                                              |
-| `BbModal`                                                      | It is [BbDialog](../BbDialog.md).                                                                                                                                                                                                                                                                                                         |
-| `BbDrawer` / `BbSheet`                                         | It is [BbOffCanvas](../BbOffCanvas.md).                                                                                                                                                                                                                                                                                                   |
-| `BbCombobox` / `BbAutocomplete`                                | It is [BbSelect](../BbSelect.md) / [BbSelectPopover](../BbSelectPopover.md) — search is built in, see `disable-writing`.                                                                                                                                                                                                                  |
-| `BbToggle` / `BbToggleGroup`                                   | It is [BbButton](../BbButton.md) with `v-model` (+ `true-value` / `false-value`), which owns `aria-pressed` and the active class.                                                                                                                                                                                                         |
-| `TagChip` / colored, read-only tag chip                        | It is [BbBadge](../BbBadge.md) — [BbTag](../BbTag.md) is a tags-_input_ only, not a display component. Use `BbBadge` with a registered `soft-*` variant for a fixed palette, or a one-off `--bg`/`--color` override per row for arbitrary/data-driven colors (BbBadge.md § One-off colors) — not a registered variant per distinct color. |
-| `BbTab` (singular)                                             | The consumer API is [BbTabs](../BbTabs.md) / `BbTabsRoot`. `BbTab` appears only as the **v2 "before" side** of the migration diffs.                                                                                                                                                                                                       |
-| `BbCard`                                                       | Does not exist — a card is a `<div>` with tokens. See [design-language](./design-language.md).                                                                                                                                                                                                                                            |
-| `BbList` / `BbListItem` / `BbDescriptionList`                  | Do not exist — a list row is an `<li>` with tokens, and [BbBaseButton](../BbBaseButton.md) makes the whole row navigable. See the note under Data Display.                                                                                                                                                                                |
-| `useLiveFeed` / any polling or cross-tab feed helper           | Does not exist, and neither does a cross-tab helper — `useBroadcastChannelInstance` was removed (cross-tab messaging is not a UI concern). Use `useBroadcastChannel` from `@vueuse/core`; the polling and the merge are yours.                                                                                                            |
-| `BbStepper` / `BbWizard`                                       | Does not exist as a component; the wizard-form recipe composes one.                                                                                                                                                                                                                                                                       |
-| `BbSkeleton` (standalone)                                      | Only `BbTable` ships skeletons, via the column `skeleton` field.                                                                                                                                                                                                                                                                          |
-| `BbCommand` / command palette                                  | Does not exist. Compose `BbDialog` + `BbSelectPopover`.                                                                                                                                                                                                                                                                                   |
-| `BbCalendar` (month / scheduling view)                         | Does not exist. [BbDatePicker](../BbDatePicker.md) is a picker, not a calendar surface.                                                                                                                                                                                                                                                   |
-| `BbChart` / `BbGraph`, `BbCarousel`, `BbTimeline`, `BbDivider` | Do not exist. No charting, carousel or timeline primitive ships here.                                                                                                                                                                                                                                                                     |
+| Assumed component or composable                                | Reality                                                                                                                                                                                                                                                                                                                                                                                                       |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BbColumnManager` — show/hide/reorder columns                  | Does not exist as a component. Order is `v-model:order` on `BbTable` (an array of keys any panel can write; `reorderable` adds the built-in header drag + keyboard handle); visibility is `hidden: true` on the column definition (the column stays declared and keeps its slot in the order; header slots get a `hideColumn()` that fires `hide:column`). Compose the panel from `BbPopover` + `BbCheckbox`. |
+| `BbKanban` / drag-and-drop board                               | Does not exist. There is no reusable DnD primitive in the library (`BbTable`'s header drag is internal to the table) — compose the board from `BbTable` (a table/list view of the same data) or hand-roll the drag-and-drop interaction yourself.                                                                                                                                                             |
+| `BbModal`                                                      | It is [BbDialog](../BbDialog.md).                                                                                                                                                                                                                                                                                                                                                                             |
+| `BbDrawer` / `BbSheet`                                         | It is [BbOffCanvas](../BbOffCanvas.md).                                                                                                                                                                                                                                                                                                                                                                       |
+| `BbCombobox` / `BbAutocomplete`                                | It is [BbSelect](../BbSelect.md) / [BbSelectPopover](../BbSelectPopover.md) — search is built in, see `disable-writing`.                                                                                                                                                                                                                                                                                      |
+| `BbToggle` / `BbToggleGroup`                                   | It is [BbButton](../BbButton.md) with `v-model` (+ `true-value` / `false-value`), which owns `aria-pressed` and the active class.                                                                                                                                                                                                                                                                             |
+| `TagChip` / colored, read-only tag chip                        | It is [BbBadge](../BbBadge.md) — [BbTag](../BbTag.md) is a tags-_input_ only, not a display component. Use `BbBadge` with a registered `soft-*` variant for a fixed palette, or a one-off `--bg`/`--color` override per row for arbitrary/data-driven colors (BbBadge.md § One-off colors) — not a registered variant per distinct color.                                                                     |
+| `BbTab` (singular)                                             | The consumer API is [BbTabs](../BbTabs.md) / `BbTabsRoot`. `BbTab` appears only as the **v2 "before" side** of the migration diffs.                                                                                                                                                                                                                                                                           |
+| `BbCard`                                                       | Does not exist — a card is a `<div>` with tokens. See [design-language](./design-language.md).                                                                                                                                                                                                                                                                                                                |
+| `BbList` / `BbListItem` / `BbDescriptionList`                  | Do not exist — a list row is an `<li>` with tokens, and [BbBaseButton](../BbBaseButton.md) makes the whole row navigable. See the note under Data Display.                                                                                                                                                                                                                                                    |
+| `useLiveFeed` / any polling or cross-tab feed helper           | Does not exist, and neither does a cross-tab helper — `useBroadcastChannelInstance` was removed (cross-tab messaging is not a UI concern). Use `useBroadcastChannel` from `@vueuse/core`; the polling and the merge are yours.                                                                                                                                                                                |
+| `BbStepper` / `BbWizard`                                       | Does not exist as a component; the wizard-form recipe composes one.                                                                                                                                                                                                                                                                                                                                           |
+| `BbSkeleton` (standalone)                                      | Only `BbTable` ships skeletons, via the column `skeleton` field.                                                                                                                                                                                                                                                                                                                                              |
+| `BbCommand` / command palette                                  | Does not exist. Compose `BbDialog` + `BbSelectPopover`.                                                                                                                                                                                                                                                                                                                                                       |
+| `BbCalendar` (month / scheduling view)                         | Does not exist. [BbDatePicker](../BbDatePicker.md) is a picker, not a calendar surface.                                                                                                                                                                                                                                                                                                                       |
+| `BbChart` / `BbGraph`, `BbCarousel`, `BbTimeline`, `BbDivider` | Do not exist. No charting, carousel or timeline primitive ships here.                                                                                                                                                                                                                                                                                                                                         |
 
 App chrome — an app shell, sidebar, page header, selection dock — is
 deliberately **not** a component: it is yours to own. The per-platform

package/dist/ai/guides/design-language.md

@@ -53,20 +53,20 @@ naming rules, the emphasis ladder) lives in
 
 ### Surfaces & structure
 
-| Token                 | Meaning                                                           |
-| --------------------- | ----------------------------------------------------------------- |
-| `--bb-panel`          | Surface/background color of panels, popovers, dialogs             |
-| `--bb-muted`          | Subtle/disabled surface (derived, neutral)                        |
-| `--bb-hover`          | Hover fill for **affordances** (buttons, links, controls)         |
-| `--bb-surface-hover`  | Hover fill for **passive surfaces** (rows, cells, days) — fainter |
-| `--bb-pressed`        | Neutral pressed/active fill                                       |
-| `--bb-border`         | Border color; pair with `--bb-border-w` (1px)                     |
-| `--bb-radius`         | Corner radius of controls (8px)                                   |
-| `--bb-radius-surface` | Corner radius of large surfaces (derived, ×1.8)                   |
-| `--bb-radius-sm`      | Corner radius of small nested elements (derived)                  |
-| `--bb-shadow`         | Global elevation shadow                                           |
-| `--bb-panel-p`        | Content padding of large surfaces (dialog, off-canvas)            |
-| `--bb-z-overlay`      | Z-index for overlays (10)                                         |
+| Token                 | Meaning                                                                                                                           |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `--bb-panel`          | Surface/background color of panels, popovers, dialogs                                                                             |
+| `--bb-muted`          | Subtle/disabled surface (derived, neutral)                                                                                        |
+| `--bb-hover`          | Hover fill for **affordances** (buttons, links, controls)                                                                         |
+| `--bb-surface-hover`  | Hover fill for **passive surfaces** (rows, cells, days) — fainter                                                                 |
+| `--bb-pressed`        | Neutral pressed/active fill                                                                                                       |
+| `--bb-border`         | Border color; pair with `--bb-border-w` (1px)                                                                                     |
+| `--bb-radius`         | Corner radius of controls (8px)                                                                                                   |
+| `--bb-radius-surface` | Corner radius of large surfaces (derived, ×1.8)                                                                                   |
+| `--bb-radius-sm`      | Corner radius of small nested elements (derived)                                                                                  |
+| `--bb-shadow`         | Global elevation shadow                                                                                                           |
+| `--bb-panel-p`        | Content padding of large surfaces (dialog, off-canvas); axis split via the locals `--px`/`--py` on `.bb-dialog` / `.bb-offcanvas` |
+| `--bb-z-overlay`      | Z-index for overlays (10)                                                                                                         |
 
 ### Color semantics
 

package/dist/ai/guides/design-tokens.md

@@ -190,11 +190,11 @@ multipliers — never literals.
 
 ### Scale
 
-| Token            | Default | Notes                                                                                                             |
-| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
-| `--bb-control-h` | `32px`  | Master control height. Inputs are exactly this; buttons/tabs derive their size scale from it via `calc()` offsets |
-| `--bb-fs`        | `14px`  | Master font size. Component font sizes derive via `calc()` offsets                                                |
-| `--bb-panel-p`   | `16px`  | Content padding of large surfaces (dialog, off-canvas; header/footer paddings derive from it)                     |
+| Token            | Default | Notes                                                                                                                                                                                                                                                                                         |
+| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--bb-control-h` | `32px`  | Master control height. Inputs are exactly this; buttons/tabs derive their size scale from it via `calc()` offsets                                                                                                                                                                             |
+| `--bb-fs`        | `14px`  | Master font size. Component font sizes derive via `calc()` offsets                                                                                                                                                                                                                            |
+| `--bb-panel-p`   | `16px`  | Content padding of large surfaces (dialog, off-canvas; header/footer paddings derive from it). Axis split via the component locals `--px`/`--py` on `.bb-dialog` / `.bb-offcanvas`, each branching off `var(--bb-panel-p)`; set the pair (on the component's class) only when the axes differ |
 
 ### Motion
 
@@ -272,10 +272,13 @@ Rules:
    component seals itself.
 3. **Short names are for self-consumption only.** `--h`, `--px`, `--gap`,
    `--fs`, `--r` are fine while the rules using them target the component's
-   own boxes. If a value must be read _inside a nested foreign component_
-   (e.g. dialog padding positioning the close button, which is itself a
-   button defining `--px`), the token gets a distinctive name (`--dialog-px`)
-   or — better — the formula moves to an element the component owns.
+   own boxes. If a value must be read _inside a nested foreign component_,
+   prefer moving the formula to an element the component owns, or a
+   distinctive name. One ruled exception (2026-08-25): the dialog/off-canvas
+   padding pair `--px`/`--py` is read by the nested close button's inset
+   formula — safe because `BbCloseButton` declares neither, a constraint that
+   component must keep (minting `--px`/`--py` there would silently mask the
+   surface's value and break the inset).
 4. **Mint only what varies.** A size variant that overrides four locals is
    four tokens, not four × six sizes. Per-size lookup tables
    (`--h-xs … --h-2xl`) are allowed only when a responsive matrix genuinely
@@ -443,19 +446,22 @@ every derivation that mixes it. It is also the trap. Write
 } /* wrong: not a <percentage> */
 ```
 
-and nothing errors — not the build, not the console. The computed value is
-just `25%`, and every ring paints 1.67× stronger than the `15%` you asked for
-(opacity is the ring's strength; its thickness is `--bb-ring-size`).
+and nothing errors — not the build, not the console. The declaration is
+discarded and the token lands on the registered `initial-value: 15%` — which
+happens to be the very value this override asked for, so a light page looks
+right by accident. Write `0.4` on a dark page instead and the ring quietly
+drops from the shipped `40%` to `15%` (opacity is the ring's strength; its
+thickness is `--bb-ring-size`).
 Percentages need the `%`; colors must be a `<color>` (`transparent` and
 `currentColor` qualify, `none` and a mistyped hex do not). Nothing in the
 toolchain catches it either: `bitboss-ui check` reads `.vue`/`.md`, never
 stylesheets.
 
 Fail-soft is only soft when the initial value is close to the real one. Every
-color knob is registered at its light default, so a rejected color override
-renders the library's own light theme. `--bb-ring-opacity` is registered at
-`25%`, which matches neither shipped scope (light `15%`, dark `40%`), so a
-rejected value there is the one that shows.
+registered knob — `--bb-ring-opacity` included — is registered at its light
+default, so a rejected override renders the library's own light theme. On a
+dark page that is still visible: a rejected `--bb-ring-opacity` lands on the
+light `15%` against the shipped dark `40%`.
 
 Typed knobs are also **animatable**. Add `.theme-animated`
 (main.css) to the element that carries the scheme class or theme overrides:
@@ -609,9 +615,10 @@ escape the host dialog's `overflow: hidden` and centering transform.
 | `--bb-overlay-color` + `--bb-overlay-opacity`                                                                                                                    | `--bb-overlay` (one color with alpha)                                        |
 | `--bb-overlay-z-index`                                                                                                                                           | `--bb-z-overlay`                                                             |
 | inline ring `color-mix()` formulas                                                                                                                               | `--bb-ring` / `--bb-ring-danger` (strength knob: `--bb-ring-opacity`)        |
-| `--bb-dialog-px/pt/pb/gap/…`                                                                                                                                     | `--bb-panel-p` (+ local derivations)                                         |
+| `--bb-dialog-px/pt/pb/gap/…`                                                                                                                                     | `--bb-panel-p` + the local axis pair `--px`/`--py` on the surface roots      |
 | `--bb-button-*`, `--bb-tabs-*`, `--bb-checkbox-*`, `--bb-radio-*`, `--bb-switch-*`, `--bb-rating-*`, `--bb-slider-*`, `--bb-table-cell-h`, `--bb-progress-track` | unprefixed locals in each component's CSS                                    |
-| `--bb-table-offset-*`, `--bb-table-fill`, `--bb-table-natural-width` (JS plumbing)                                                                               | unprefixed locals on `.bb-table` (`--offset-*`, `--fill`, `--natural-width`) |
+| `--bb-table-offset-*` (JS plumbing)                                                                                                                              | unprefixed locals on `.bb-table` (`--offset-*`)                              |
+| `--bb-table-fill`, `--bb-table-natural-width`                                                                                                                    | **removed** with the grid substrate — nothing publishes them any more (v3.0) |
 | `--bb-table-{id}-track-{key}` (parent→nested width bridge)                                                                                                       | `--table-{id}-track-{key}` (distinctive cross-component name, rule 3)        |
 | `--bb-select-option-*`, `--bb-primary-base`, all `--x-light`/`--x-dark` shadows                                                                                  | deleted (dead)                                                               |
 

package/dist/ai/guides/fetch-items-playbook.md

@@ -58,7 +58,7 @@ The corollary: **`prefill` cannot tell you an initial load from a dependency ref
 
 ### The `prefill` prop (`BbSelect` / `BbSelectPopover`)
 
-`prefill` controls **when** the initial load happens: `'interaction'` (default) waits for the first user interaction, `true` loads on mount (SSR-friendly — it also runs in `onServerPrefetch`), `false` is **search-first** — nothing loads until the user types, so opening the panel fetches nothing and the list shows a "search to begin" hint until the first query. Groups and tables always load on mount.
+`prefill` controls **when** the initial load happens: `'interaction'` (default) waits for the first user interaction, `true` loads on mount (SSR-friendly — under `bitboss-ui/nuxt` it also runs in `onServerPrefetch` and the result is transferred to the client; see [SSR prefill](./ssr-prefill.md)), `false` is **search-first** — nothing loads until the user types, so opening the panel fetches nothing and the list shows a "search to begin" hint until the first query. Groups and tables always load on mount.
 
 Reach for `false` when the result set is too large or expensive to browse and the query is the only sensible entry point. Note that `false` and `'interaction'` differ **only** on this point: both skip the mount load, but `'interaction'` fetches on open and `false` waits for a query.
 

package/dist/ai/guides/icons-policy.md

@@ -36,9 +36,13 @@ The `bitbossUi` Vite plugin (`iconDir` option) — or the Nuxt module (config ke
   `lucide:<name>` available; removing it makes them all errors. Nothing to
   configure.
 - **Dev**: all icons of installed sets are registered. Referencing an
-  uninstalled prefix or a non-existent name fails loudly with an actionable
-  message (`"lucide:fo" requires "@iconify-json/lucide" — run: npm install -D …`
-  or `icon "x" does not exist in the lucide icon set`).
+  uninstalled prefix or a non-existent name fails loudly in the Vite error
+  overlay with an actionable message. A typo inside an installed set reads
+  "does not exist in the lucide icon set — did you mean `lucide:…`?"; a set
+  that is not installed reads "no installed icon set has the prefix `mdi`
+  (installed sets: lucide) … run: `npm install -D @iconify-json/mdi`". Read
+  the message: a typo wants a different name, a missing set wants an install,
+  never a guess.
 - **Build**: source files (`.vue`/`.ts`/`.js`/`.tsx`/`.jsx`; tests and stories
   excluded) are scanned for static `provider:name` literals; each referenced
   icon is emitted as its own lazy chunk. This is why rule 4 exists — and why an
@@ -235,8 +239,10 @@ markup) yourself:
 - Decorative icon next to visible text (affixes, button prepend/append,
   dropdown items): no label — the text already announces it; a label would
   duplicate.
-- Meaningful standalone icon: give `BbIcon` a `label` — it adds `role="img"`,
-  `aria-label`, and a `title`.
+- Meaningful standalone icon: give `BbIcon` a `label` — it adds `role="img"`
+  and `aria-label`. Deliberately **no `title`**: that renders a native browser
+  tooltip, which double-tooltips any icon also carrying `v-bb-tooltip` (owner
+  ruling 2026-07-30, `BbIcon.vue:200`). For a visible tip, add `v-bb-tooltip`.
 - Icon-only `BbButton` (the `icon` prop): supply the accessible name through the
   label (default slot, or `text`) — it renders `sr-only` but is still announced.
   `aria-label` is only an override; the one hard rule is that the button must

package/dist/ai/guides/installation-and-plugin-setup.md

@@ -31,19 +31,16 @@ goes stable, so never reach for it here.
 
 Peer dependency: `vue ^3.5.12` — the only required one. `@inertiajs/vue3` is an **optional** peer, needed only in Inertia apps.
 
-`@iconify/collections` is an **optional** peer too, and npm never installs
-optional peers automatically — install it yourself if you want the dev-time
-provider-icon diagnostics:
-
-```bash
-npm install -D @iconify/collections
-```
-
-Without it the plugin has no list of valid Iconify prefixes, so the dev-overlay
-errors below (the "install `@iconify-json/<prefix>`" hint and the "did you
-mean …?" suggestion for a mistyped icon name) never fire — a wrong provider
-icon then surfaces only as `BbIcon`'s generic runtime `Icon "…" does not exist.`
-Nothing else changes: icons that resolve still render, in dev and in production.
+You do **not** need `@iconify/collections`. It is declared as an optional peer
+for one reason only: when it happens to be installed, the dev-overlay message
+for an unknown icon prefix can say for certain whether that prefix is a real
+Iconify set ("requires `@iconify-json/mdi`, run …") or not ("neither an
+installed set nor a known Iconify prefix"). Without it the same overlay fires
+with a hedged wording ("no installed icon set has the prefix `mdi`; if it is an
+Iconify set, run …"). A mistyped name inside a set you **have** installed
+(`lucide:eye-misspelled`) is diagnosed from the set's own data in both cases,
+with a "did you mean …?" suggestion. Nothing else changes: icons that resolve
+still render, in dev and in production.
 
 **Known-good toolchain:** TypeScript **5.x or 6.x** if your build gate runs
 `vue-tsc`. Both type-check cleanly against the shipped `.d.ts`; the library
@@ -150,6 +147,45 @@ export default defineNuxtConfig({
 
 All options below go under the `bitboss` config key. `nuxtLinkName` controls which globally registered component renders router links (default `'NuxtLink'`).
 
+This module supersedes the standalone `@bitboss-dev/bitboss-ui-nuxt` package, which was the v2 Nuxt integration — uninstall it (see [Migration v2 → v3](./migration/v2-to-v3.md)).
+
+### `autoImport?: boolean | { components?: boolean; composables?: boolean; validated?: boolean }` (default: `false`, Nuxt only)
+
+Registers the library's components and composables with Nuxt's auto-import system, so templates write `<BbButton>` and `useToast()` with no import line:
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+	modules: ['bitboss-ui/nuxt'],
+	bitboss: {
+		iconDir: './assets/icons',
+		autoImport: true,
+	},
+});
+```
+
+`true` means `{ components: true, composables: true }`. Pass the object form to
+narrow it, or to add `validated: true` — which resolves the form controls from
+[`bitboss-ui/validated`](./validated-forms.md) instead of `bitboss-ui`, so
+`<BbTextInput>` is the vee-validate-bound wrapper and takes `rules`, and adds
+`BbForm`, `BbAsterisk`, `useBbFormContext` and `useValidatedField`. It needs the
+`vee-validate` peer installed.
+
+**It is off by default on purpose, and leaving it off is the better setup.**
+Explicit imports are what make `vueCompilerOptions.checkUnknownComponents` (see
+section 9) able to fail the build on a mistyped or unimported `Bb*` tag; with
+auto-imports on, every `Bb*` tag resolves and that gate goes quiet. Reach for it
+when you are moving an app off `@bitboss-dev/bitboss-ui-nuxt`, whose templates
+were written against auto-imported components, and adding the imports is a
+separate commit from the upgrade.
+
+Two things it deliberately does not do. It never overrides your own components:
+a `~/components/BbButton.vue` in the app keeps winning, and the library only
+fills names the app has not claimed. And it never registers the library's
+`useId` — Nuxt already auto-imports Vue's, and shadowing it would silently
+redirect every existing `useId()` call in the app; import that one explicitly if
+you want it.
+
 ## 4) Inertia
 
 Inertia apps are Vite apps: configure `bitboss-ui/vite` exactly as in section 2, install `@inertiajs/vue3`, then install the runtime plugin in `createInertiaApp`:
@@ -269,7 +305,7 @@ utilities. (Same trap as the scoped-`<style>` case above, one level up.)
 ## 6) Icons
 
 - `iconDir` (required) is scanned recursively for `.svg` files; each file becomes `local:<basename>`.
-- Provider icons (`lucide:pencil`, `mdi:home`, …) require the matching `@iconify-json/<prefix>` package installed in the consumer app. Missing packages/icons produce actionable dev-overlay errors **only when the optional `@iconify/collections` peer is installed** (see [Install](#1-install)); otherwise you get `BbIcon`'s generic runtime error instead. Production builds report neither — this is a dev-time aid.
+- Provider icons (`lucide:pencil`, `mdi:home`, …) require the matching `@iconify-json/<prefix>` package installed in the consumer app. In dev, every `prefix:name` the registry does not know produces a Vite error overlay with the fix: a mistyped name inside an installed set gets a "did you mean …?" hint, and an uninstalled prefix gets the list of installed sets plus the `npm install -D @iconify-json/<prefix>` command (the optional `@iconify/collections` peer only sharpens that wording, see [Install](#1-install)). A missing `local:` icon is a missing file in `iconDir` and surfaces as `BbIcon`'s runtime error naming it. Production builds report none of this — the scan simply drops what does not resolve, so a wrong name fails at runtime there.
 - Production builds bundle **only statically referenced** provider icons — write icon names as literal strings (`icon="lucide:trash-2"`), never assemble them dynamically.
 - The plugin also writes `node_modules/.bitboss-ui/local-icons.json` and (in dev, unless `vscodeSettings: false`) wires `.vscode/settings.json` so the Iconify editor extension previews local icons.
 
@@ -363,11 +399,12 @@ bitbossUi({
 
 This is a **single global default baked in at build time** (it comes from the
 Vite plugin config), so it is the same for every request — it is _not_ a
-per-request value. There is no per-request/per-visitor override today: the
-viewport signal is a process-wide singleton, so a mobile layout that must be
-correct on the server's first paint (e.g. a modal already open on load) needs a
-client adjustment after hydration, or a fixed `ssrViewportWidth` matching your
-audience.
+per-request value. There is no per-request/per-visitor override: the viewport
+signal is a process-wide singleton, so a mobile layout that must be correct on
+the server's first paint (e.g. a modal already open on load) needs a client
+adjustment after hydration, or a fixed `ssrViewportWidth` matching your
+audience. (Unlike `locale`, which **is** per-request — see below. A width
+cannot be derived from a request without UA sniffing; a locale can.)
 
 ### `defaultInputLabelMode?: 'outside' | 'floating' | 'inside'` (default: `'outside'`)
 
@@ -385,9 +422,32 @@ labels, screen-reader announcements, confirm buttons, …). The library ships
 pl, tr, ru, uk, cs, ro, hu, el, sv, da, nb, fi, ja, ko, zh-cn — but shipping ≠
 bundling: only the **enabled** locales enter your build (next option). Runtime
 switching: `useBbConfig().setConfig({ locale })` — to a locale you enabled.
-`setConfig` is client-only: on an SSR server the config is a process-wide
-singleton (same rule as `ssrViewportWidth` — no per-request override), so a
-per-request call would leak one visitor's locale into other renders.
+
+**Per-request locale under SSR** is supported as of 3.0.0-beta.15: the config
+is held per Vue app, and SSR builds one app per request, so pass it where you
+create the app — `app.use(bitbossUiPlugin, { locale: localeFor(request) })`.
+That is correct on the server's first paint, which is what crawlers index and
+what a JS-disabled reader keeps.
+
+**In Nuxt, do not call `app.use`** — the module registers the runtime plugin,
+which provides the per-app config itself (fixed in 3.0.0-beta.19, Q20.4;
+before that Nuxt had no per-app config at all and every `setConfig` wrote the
+process-global). Set a per-request locale from your own Nuxt plugin, which
+runs per request on the server:
+`nuxtApp.vueApp.runWithContext(() => useBbConfig().setConfig({ locale }))` —
+the `runWithContext` is what hands the write this app's injection context,
+since a plugin has an app but no component instance.
+
+`setConfig` still works for runtime switching; during a server render call it
+from a component's `setup` (or inside `runWithContext`), where it can resolve
+the current app. With neither there is no app to address, the write lands on
+the build-time defaults, and it leaks between concurrent visitors — it warns in
+dev when it sees that, keyed off where the write actually landed rather than
+the call site. See [useBbConfig](../composables/useBbConfig.md).
+
+Note this is a **different rule** from `ssrViewportWidth` above, which really
+is a build-time global: a width cannot be known per request without sniffing,
+a locale can.
 
 ### `enabledLocales?: BuiltinLocaleKey[]` (default: your `locale` + `'en'`)
 
@@ -506,7 +566,7 @@ template emits are already styled by the public `bitboss-ui/styles.css`.
 
 Add `--mcp` to also register a live MCP server (`npx bitboss-ui@<installed version> mcp`, pinned so npx can never fetch a different version from the registry) the harness launches on demand — it merges the entry (never overwriting other servers) into `.mcp.json` (Claude Code), `.cursor/mcp.json` (Cursor), `.vscode/mcp.json` (VS Code / Copilot), and `~/.codeium/windsurf/mcp_config.json` (Windsurf). **Windsurf's config is global** — it has no per-project scope, so registering it affects every project on the machine; that is why only the explicit `ai-init --mcp` command writes it, while the plugin's `mcp: true` dev-server flag (§7) auto-registers the project-scoped harnesses only. Install the server's optional peers first — `npm i -D @modelcontextprotocol/sdk zod` — they are not dependencies of the library (~12 MB used only by the MCP server); the command warns if they are absent. **`--mcp` is optional and skipping it loses you nothing but the transport** — the server only reads the `dist/ai/` files listed above, so run plain `ai-init` and let the agent read that directory if you cannot add the peers (see `mcp?: boolean` in §7).
 
-For a human-in-the-loop (and agent) safety net, add the `bitboss-ui/eslint-plugin` flat-config plugin (`...bitbossUi.configs.recommended`) so unknown/removed `Bb*` props surface as ESLint errors in the editor and CI — the same manifest checks as `bitboss-ui check`, reusing your `eslint-plugin-vue` parser. Real HTML attributes fall through untouched; escape hatches are the standard `<!-- eslint-disable-next-line bitboss-ui/no-unknown-attributes -->` and the rule's `allowAttributes` / `allowComponents` options. **`eslint --fix` also auto-migrates deprecated v2 props** (renames, boolean-polarity inversions like `allowWriting`→`disableWriting`, value remaps like BbToast `placement`→`position`, and deletion of inert removed props); structural migrations that need a slot/directive/CSS are reported but left by hand. **This library is TS-first (recipes ship `<script setup lang="ts">`, some with `generic="T"`), so wire `@typescript-eslint/parser` for both `.ts` and `.vue` files** — without it `vue-eslint-parser` throws a `Parsing error` on those files, which means no rule (including `no-unknown-attributes`) runs on them at all. See the README "ESLint plugin" section for the full config snippet (both parser blocks + the `npm i -D @typescript-eslint/parser` line) and the fix table. `recommended` also enables `bitboss-ui/no-active-class-on-root-link`: `active-class` on a link-capable `Bb*` component (`BbButton`/`BbBaseButton`/`BbBadgeButton`) matches by path PREFIX, so a link whose target is the literal root (`href="/"` / `to="/"`) reads as "active" on every URL — the rule flags that combination and points you at `exact-active-class` instead.
+For a human-in-the-loop (and agent) safety net, add the `bitboss-ui/eslint-plugin` flat-config plugin (`...bitbossUi.configs.recommended`) so unknown/removed `Bb*` props surface as ESLint errors in the editor and CI — the same manifest checks as `bitboss-ui check`, reusing your `eslint-plugin-vue` parser. Real HTML attributes fall through untouched; escape hatches are the standard `<!-- eslint-disable-next-line bitboss-ui/no-unknown-attributes -->` and the rule's `allowAttributes` / `allowComponents` options. **`eslint --fix` also auto-migrates deprecated v2 props** (renames, boolean-polarity inversions like `allowWriting`→`disableWriting`, value remaps like BbToast `placement`→`position`, and deletion of inert removed props); structural migrations that need a slot/directive/CSS are reported but left by hand. One deliberate boundary: the rule's "did you mean `<prop>`?" hints for a mistyped/unknown attribute are advisory message text, not fixes — `eslint --fix` (including an unattended run in a pre-commit hook) never applies them; only the registered v2→v3 migrations above are auto-fixed. A guess applied blind across a codebase would be a silent behavior change, so acting on a hint is always a per-site decision. **This library is TS-first (recipes ship `<script setup lang="ts">`, some with `generic="T"`), so wire `@typescript-eslint/parser` for both `.ts` and `.vue` files** — without it `vue-eslint-parser` throws a `Parsing error` on those files, which means no rule (including `no-unknown-attributes`) runs on them at all. See the README "ESLint plugin" section for the full config snippet (both parser blocks + the `npm i -D @typescript-eslint/parser` line) and the fix table. `recommended` also enables `bitboss-ui/no-active-class-on-root-link`: `active-class` on a link-capable `Bb*` component (`BbButton`/`BbBaseButton`/`BbBadgeButton`) matches by path PREFIX, so a link whose target is the literal root (`href="/"` / `to="/"`) reads as "active" on every URL — the rule flags that combination and points you at `exact-active-class` instead.
 
 **The manifest ships with the package** — `dist/ai/components.json` is inside
 the tarball, and the rules resolve it relative to their own file, so a normal
@@ -516,6 +576,8 @@ nothing), the rules cannot check anything: they now **warn once** saying they
 are inactive rather than passing silently. Pass `failClosed: true` to a rule's
 options if you would rather CI stop than under-check.
 
+`recommended` also enables **`bitboss-ui/no-reverse-false`**, which covers the one v2 break a rename table cannot: `reverse` on `BbCheckbox` / `BbRadio` / `BbSwitch` kept its NAME and inverted its MEANING in v3, so the v2 spelling `:reverse="false"` (control on the right) is now a no-op that renders the control on the LEFT. Nothing else catches it — it is a declared prop, correctly typed, holding its own default value — and it cannot be expressed as a rename, because a rename entry is keyed by prop name and would rewrite the legitimate v3 spellings too. The rule flags only a LITERAL `:reverse="false"` (a dynamic `:reverse="isRtl"` that evaluates false is left alone) and offers both corrections as editor suggestions; pass `{ assumeV2: true }` to promote the v2-intent rewrite to a real `--fix` for a bulk sweep, then remove it — the two readings produce opposite layouts, so it must never be on by default. See [the migration guide](../guides/migration/components/bb-checkbox.md).
+
 It also enables `bitboss-ui/require-partner-prop`: an opt-in prop set without its documented required partner — BbTable `keyboard-navigation` / `v-model:highlighted` without `row-class` (the shipped tint says "current row"; `row-class` says why, and is how you override it), or `loading-text` without `:loading` bound — compiles and mounts clean and just does nothing; the rule names the missing partner and quotes why.
 
 ## 9) Setup Verification Checklist

package/dist/ai/guides/migration/components/bb-checkbox-group.md

@@ -20,6 +20,7 @@ The three groups share their surface (`BbSwitchGroup` re-exports
 | `name: string` required (**BbRadioGroup** only; the other two already optional) | `name?: string` (auto-generated per group when omitted) | relaxation — the generated name is unique per group instance, so options still group and two groups never collide |
 | —                                                                               | `legendMode: 'outside' \| 'inside'`, `description`      | additive                                                                                                          |
 | `BbSwitchGroup` `multiple: false` silently ignored (always array emit)          | honored — emits a bare value in single-select mode      | **⚠ behavioral** (bugfix: the prop was advertised but never forwarded; fixed 2026-07-18)                          |
+| `disabled` / `selectable: false` left a **selected** option interactive         | a selected option is disabled like any other            | **⚠ behavioral** (bugfix, 2026-08-31 — see below)                                                                 |
 
 `max` (checkbox/switch), `required` (radio), and `multiple` defaults are
 unchanged.
@@ -54,6 +55,35 @@ The `item.disabled` change is the dangerous one: nothing errors, options that
 used to render disabled simply become selectable. Grep item-building code for
 `disabled:` near these groups.
 
+## `disabled` now disables the selection too
+
+Until 2026-08-31 a **selected** option in a `disabled` (or
+`selectable: false`) group stayed interactive: it rendered without the native
+`disabled` attribute, and clicking it emitted `update:modelValue` with the
+option removed. So a fieldset switched off to prevent edits still let the user
+clear the value it was showing.
+
+```vue
+<!-- before: "a" was clickable, and clicking it emitted [] -->
+<BbCheckboxGroup v-model="picked" disabled :items="items" legend="Plan" />
+```
+
+The resolver short-circuited on `selected` above both checks. That escape
+exists for the **`max` swap affordance** — at the cap, already-selected options
+stay live so the user can trade one for another — and it now sits only above
+the `max` check, where it belongs. Unchanged:
+
+```vue
+<!-- still works: at max, selected options remain tradeable -->
+<BbCheckboxGroup v-model="picked" :max="1" :items="items" legend="Plan" />
+```
+
+**What to check when you upgrade.** If you relied on the old behaviour to let
+someone _remove_ a value from an otherwise locked group, `disabled` is no
+longer the prop for that — it now means what it says. Use `readonly`, which
+keeps the options focusable and announced (`aria-readonly`) while blocking
+every change, or leave the group enabled and gate on your own handler.
+
 ## DOM: the shared `bb-cr-container` block split three ways
 
 v2 rendered one prefix for all three groups — `bb-cr-container` ("checkbox /