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

package/dist/llms-medium.txt

@@ -5,16 +5,16 @@
 > how to choose a component, and the design language — plus a catalogue
 > of every public component.
 
-Canonical URL: https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-medium.txt
+Canonical URL: https://llms-bitboss-ui.bitboss.it/dist/llms-medium.txt
 
 Need more? Fetch the specific component contract you need — one hop, not
-the whole catalogue: https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/<ComponentName>.md
-Machine-readable API surface: https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/components.json
+the whole catalogue: https://llms-bitboss-ui.bitboss.it/dist/ai/<ComponentName>.md
+Machine-readable API surface: https://llms-bitboss-ui.bitboss.it/dist/ai/components.json
 
 ---
 
 <!-- dist/ai/guides/ai-router.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/ai-router.md -->
+<!-- https://llms-bitboss-ui.bitboss.it/dist/ai/guides/ai-router.md -->
 
 # AI Router
 
@@ -27,13 +27,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)
@@ -133,7 +138,7 @@ nothing else); the command names them if they are missing.
 ---
 
 <!-- dist/ai/guides/agent-contract.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/agent-contract.md -->
+<!-- https://llms-bitboss-ui.bitboss.it/dist/ai/guides/agent-contract.md -->
 
 # Agent Contract
 
@@ -391,7 +396,7 @@ case is not decidable from markup and has no hint.
 ---
 
 <!-- dist/ai/guides/installation-and-plugin-setup.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/installation-and-plugin-setup.md -->
+<!-- https://llms-bitboss-ui.bitboss.it/dist/ai/guides/installation-and-plugin-setup.md -->
 
 # Installation and Plugin Setup
 
@@ -421,19 +426,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
@@ -540,6 +542,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`:
@@ -659,7 +700,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.
 
@@ -753,11 +794,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'`)
 
@@ -775,9 +817,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'`)
 
@@ -896,7 +961,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
@@ -906,6 +971,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
@@ -927,7 +994,7 @@ If one of the checks fails, fix setup before creating component examples.
 ---
 
 <!-- dist/ai/guides/component-picker.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/component-picker.md -->
+<!-- https://llms-bitboss-ui.bitboss.it/dist/ai/guides/component-picker.md -->
 
 # Component Picker
 
@@ -1157,24 +1224,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
@@ -1202,7 +1269,7 @@ See:
 ---
 
 <!-- dist/ai/guides/design-language.md -->
-<!-- https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/guides/design-language.md -->
+<!-- https://llms-bitboss-ui.bitboss.it/dist/ai/guides/design-language.md -->
 
 # Design Language
 
@@ -1254,20 +1321,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
 
@@ -1787,13 +1854,13 @@ text, `--bb-label-weight`
 
 ## Component catalogue
 
-Every public component. Open one contract at `https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/ai/<Name>.md` before using it — never guess a prop name.
+Every public component. Open one contract at `https://llms-bitboss-ui.bitboss.it/dist/ai/<Name>.md` before using it — never guess a prop name.
 
 - **BbAccordion** — Expands and collapses a content panel.
 - **BbAlert** — Shows contextual status messages.
 - **BbAsterisk** — Presentational required-field marker (red "*"). No props/slots/events; placed in custom label content.
 - **BbAvatar** — Displays an avatar and has a fallback content slot.
-- **BbBadge** — Displays compact status counters or labels, the floating mode acts as notification dot.
+- **BbBadge** — Displays a compact inline status counter or label. It sits in the flow — for a bubble or dot anchored OVER another element, use BbIndicator (includes the co-located BbBadgeButton export).
 - **BbBadgeButton** — Makes a badge's body interactive: slotted as a direct child of BbBadge it renders the badge body as a real button/link with full BbBaseButton parity, leaving `clearable` free to remain a separate control.
 - **BbBaseButton** — Unstyled button/link primitive: element resolution (button/anchor/router link) and the full navigation engine, with no visual chrome. Use for any clickable or navigable surface that is not a variant-first BbButton — cards, list rows, custom links.
 - **BbBaseCheckboxIcon** — Standalone checkbox glyph (box + checkmark SVG). Presentational only — no input, no events. Compose it into a fully custom checkbox design, or let BbCheckbox/BbBaseCheckbox render it.
@@ -1811,13 +1878,13 @@ Every public component. Open one contract at `https://cdn.jsdelivr.net/npm/bitbo
 - **BbDatePicker** — Opens an anchored calendar (and optional time rail) popover on a trigger you own — the date analog of BbColorPalette; also the v-bb-date directive.
 - **BbDatePickerInput** — Combines date selection with text input behavior.
 - **BbDialog** — Presents modal dialogs for focused user interactions.
-- **BbDropdown** — Displays contextual action menus and menu content.
+- **BbDropdown** — Displays contextual action menus and menu content (includes the co-located BbDropdownGroup export, which is how a selectable group is bound).
 - **BbDropdownButton** — A button with primary action and all other actions collected in a dropdown.
 - **BbDropdownGroup** — Renderless v-model companion for a group declared in BbDropdown.items, bound by id.
 - **BbDropzone** — Supports drag-and-drop file input flows.
 - **BbForm** — Form host for `bitboss-ui/validated`: owns the vee-validate form (useForm), validates every field on submit, and emits `submit` with the collected values only when the form is valid.
 - **BbIcon** — Renders an icon either from the local icon folder or from a provider.
-- **BbIndicator** — Anchors a notification bubble (count/short text) or a dot over a wrapped element, with floating and corner-placement options.
+- **BbIndicator** — Anchors a notification bubble (count/short text) or a dot over a wrapped element.
 - **BbNumberInput** — Captures and validates numeric form values, emits a number value.
 - **BbOffCanvas** — Shows side-panel overlay content outside normal layout flow.
 - **BbPagination** — Navigates paginated data sets by page index.
@@ -1834,7 +1901,7 @@ Every public component. Open one contract at `https://cdn.jsdelivr.net/npm/bitbo
 - **BbSwitch** — Toggles two-state values with switch semantics.
 - **BbSwitchGroup** — Manages grouped switch options with shared behavior.
 - **BbTable** — Displays tabular data, configurable columns and data mapper.
-- **BbTabs** — Switches between tabbed content views (shadcn-like strip; BbTabRoot enables split layouts).
+- **BbTabs** — Switches between tabbed content views (shadcn-like strip; the co-located BbTabsRoot / BbTabsList / BbTabsPanes exports enable split layouts).
 - **BbTabsList** — The trigger strip of a split BbTabsRoot layout (renders the tab buttons only).
 - **BbTabsPanes** — The pane host of a split BbTabsRoot layout (renders the tab content only).
 - **BbTabsRoot** — Provide/inject root that lets BbTabsList and BbTabsPanes live in separate layout slots.
@@ -1843,7 +1910,7 @@ Every public component. Open one contract at `https://cdn.jsdelivr.net/npm/bitbo
 - **BbTextInput** — Captures single-line text values.
 - **BbTimePicker** — Opens hour/minute(/second) columns in a popover on a trigger you own — the time analog of BbDatePicker; also the v-bb-time directive.
 - **BbTimePickerInput** — Segmented time field with hour/minute columns; 24-hour string model.
-- **BbToast** — Shows transient notification messages.
+- **BbToast** — Shows transient notification messages (includes the co-located BbToastPortal export).
 - **BbToastPortal** — Registers named slot content that toast() renders via `portal`.
 - **BbTooltip** — Displays contextual helper text on interaction.
 - **BbTree** — Renders hierarchical expandable tree structures.

package/dist/llms.txt

@@ -4,8 +4,8 @@
 
 ## AI Knowledge Base
 
-- [Core knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-medium.txt): **Fetch this if you can only fetch one file** — hard rules, setup, component picker, design language, and the full component catalogue in ~70 KB.
-- [Complete knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-full.txt): Everything concatenated (~2 MB). Bulk ingestion only — too large to prompt with.
+- [Core knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-medium.txt): **Fetch this if you can only fetch one file** — hard rules, setup, component picker, design language, and the full component catalogue in ~70 KB.
+- [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt): Everything concatenated (~2 MB). Bulk ingestion only — too large to prompt with.
 - [AI Router](ai/guides/ai-router.md): **Start here** — tiny hop map for any coding agent (which file to open next).
 - [Component index](ai/index.md): Full component catalogue with agent rules, grouped by category. Each entry links a typed contract (props/events/slots/v-model).
 - [Component manifest](ai/components.json): Machine-readable API surface of every component, for programmatic validation.
@@ -32,17 +32,17 @@
 - [Migration v2→v3: BbCheckbox / BbRadio / BbSwitch](ai/guides/migration/components/bb-checkbox.md): reverse polarity inverted (explicit values flip, default layout unchanged), checked narrowed to boolean, color removed, BbRadio's name no longer required.
 - [Migration v2→v3: BbCheckboxGroup / BbRadioGroup / BbSwitchGroup](ai/guides/migration/components/bb-checkbox-group.md): labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed, BbRadioGroup's name no longer required, and the shared bb-cr-container CSS block split into one per group.
 - [Migration v2→v3: BbChip (removed)](ai/guides/migration/components/bb-chip.md): BbChip is gone — BbBadge with clearable is the replacement; non-clearable chips were badges all along.
-- [Migration v2→v3: BbCollapsible](ai/guides/migration/components/bb-collapsible.md): The tag prop is removed; the root is always a div.
+- [Migration v2→v3: BbCollapsible](ai/guides/migration/components/bb-collapsible.md): The tag prop is removed; the root is always a span.
 - [Migration v2→v3: BbColorInput](ai/guides/migration/components/bb-color-input.md): picker renamed to eyeDropper.
 - [Migration v2→v3: BbColorPalette](ai/guides/migration/components/bb-color-palette.md): flip inverted to disableFlip, showArrow removed, picker renamed eyeDropper, update:open dropped, model updates never emit null.
 - [Migration v2→v3: BbDatePickerInput](ai/guides/migration/components/bb-date-picker-input.md): allowWriting inverted to disableWriting and hidePopover renamed to disableCalendar, both with a changed token set; the width prop is removed; adaptive mobile sheet by default; non-floating output carries the local offset instead of UTC `Z` (new `utc` prop restores v2 output).
-- [Migration v2→v3: BbDialog](ai/guides/migration/components/bb-dialog.md): showClose inverted to hideClose, several presentation props and the #close/#description slots removed, default widths changed, adaptive bottom sheet on mobile by default, --bb-dialog-* tokens replaced by --bb-panel-p plus locals.
+- [Migration v2→v3: BbDialog](ai/guides/migration/components/bb-dialog.md): showClose inverted to hideClose, #close removed (description restored in beta.19), default widths changed, adaptive bottom sheet on mobile by default, --bb-dialog-* tokens replaced by --bb-panel-p plus locals.
 - [Migration v2→v3: BbDropdown](ai/guides/migration/components/bb-dropdown.md): Items now expect text as the label and can carry variants/submenus; arrowPadding removed; adaptive mobile sheet on by default.
 - [Migration v2→v3: BbDropdownButton](ai/guides/migration/components/bb-dropdown-button.md): autoLoading renamed to disableAutoLoading, disabledWhileLoading and theme removed.
 - [Migration v2→v3: BbDropzone](ai/guides/migration/components/bb-dropzone.md): modelValue is typed, accept no longer throws and takes bare tokens, and the hidden native-submit input only renders when name is set.
 - [Migration v2→v3: BbIcon](ai/guides/migration/components/bb-icon.md): The required prop is renamed type→icon, color is removed, and the xxl size key becomes 2xl.
 - [Migration v2→v3: BbIntersection](ai/guides/migration/components/bb-intersection.md): Removed with no replacement — it wrapped IntersectionObserver and carried no styling; use @vueuse/core's useIntersectionObserver.
-- [Migration v2→v3: BbOffCanvas](ai/guides/migration/components/bb-offcanvas.md): direction→side; showClose→hideClose; description and the #close/#description slots removed; size defaults change; adaptive drawer configs unify on offCanvasProps.
+- [Migration v2→v3: BbOffCanvas](ai/guides/migration/components/bb-offcanvas.md): direction→side; showClose→hideClose; #close removed (description restored in beta.19); size defaults change; adaptive drawer configs unify on offCanvasProps.
 - [Migration v2→v3: BbPagination](ai/guides/migration/components/bb-pagination.md): querykey renamed to queryKey; the loading prop is removed.
 - [Migration v2→v3: BbPopover](ai/guides/migration/components/bb-popover.md): Built-in close button, restoreFocus, theme, and the arrow are gone; close affordances move into your content.
 - [Migration v2→v3: BbRating](ai/guides/migration/components/bb-rating.md): color removed; name no longer required; the star state modifier renamed --highlighted to --filled/--empty; --bb-rating-size demoted to a local --size; input-position finally works.
@@ -51,7 +51,7 @@
 - [Migration v2→v3: BbSlider](ai/guides/migration/components/bb-slider.md): thumbTranslate inverted to disableThumbTranslate; string model values and color removed.
 - [Migration v2→v3: BbSmoothHeight](ai/guides/migration/components/bb-smooth-height.md): The `tag` prop is narrowed to `div | span`, and the inner measuring element now mirrors it instead of always being a `<div>`.
 - [Migration v2→v3: BbSpinner](ai/guides/migration/components/bb-spinner.md): The color prop is removed; spinners follow currentColor.
-- [Migration v2→v3: BbTable](ai/guides/migration/components/bb-table.md): allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width table cell instead of replacing the row; columns gained sortable + rowClass, which collide with same-named consumer fields.
+- [Migration v2→v3: BbTable](ai/guides/migration/components/bb-table.md): The table renders as a CSS grid of divs with ARIA roles, not a <table> — every element selector (table/thead/tbody/tr/th/td) under .bb-table matches nothing, #thead/#tbody/#tfoot take role-complete div rows, --fill/--natural-width are gone, column widths drift within documented bounds, copy-to-spreadsheet and print header repetition degrade; allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width cell instead of replacing the row; row events drop the selected argument; columns gained sortable + rowClass, which collide with same-named consumer fields.
 - [Migration v2→v3: BbTabs (was BbTab)](ai/guides/migration/components/bb-tabs.md): Component renamed; querykey→queryKey; animations default on; label slots renamed and all dynamic names/URL slugs normalized; the entire .bb-tab BEM tree renamed to .bb-tabs / .bb-tabs-list / .bb-tabs-panes.
 - [Migration v2→v3: BbTag](ai/guides/migration/components/bb-tag.md): modelValue is strictly string[] now, multiple is removed, and duplicates are rejected case-insensitively by default.
 - [Migration v2→v3: BbTextInput](ai/guides/migration/components/bb-text-input.md): The type prop narrows to the text-like input types — number/date values must move to their dedicated components; a bare `floating` attribute was never a prop, the spelling is label-mode="floating".
@@ -61,6 +61,7 @@
 - [Migration v2→v3: confirm() / useConfirm](ai/guides/migration/components/use-confirm.md): yesText/onYes/noText/onNo collapse into yes/no configs, actions becomes an array-or-false, theme→variant, timeout→duration, autoClose flips to default-true, labels are localized, footer buttons default md.
 - [Migration v2→v3: useBroadcastChannelInstance](ai/guides/migration/components/use-broadcast-channel-instance.md): Removed — cross-tab messaging is not a UI concern; use useBroadcastChannel from @vueuse/core.
 - [Page Shell](ai/guides/page-shell.md): App-side page layout — topbar, content, and a right details sidebar driven by a stack-based context (push a record to peek it, pop to go back). The implementation ships in the per-platform Layout Scaffold recipe; this guide covers when and how to use it.
+- [ssr-prefill](ai/guides/ssr-prefill.md): Guide for ssr-prefill usage and decision-making context.
 - [Validated Forms (vee-validate)](ai/guides/validated-forms.md): The `bitboss-ui/validated` entrypoint — form controls pre-wired to vee-validate. Global rules give an effort-free `rules="required|email"` string syntax; BbForm hosts the form; requiredAsterisk marks required fields.
 
 ## Recipes (Page-Level Assemblies)

package/dist/locale-blueprint.json

@@ -138,7 +138,10 @@
 			"selectAllLabel": "Select all items on this page",
 			"selectText": "Select an item",
 			"select": "Select",
-			"selectableLegend": "Select items"
+			"selectableLegend": "Select items",
+			"reorderInstructions": "Use the left and right arrow keys to move between columns; hold Shift to move the column, with Home and End for the ends. Enter sorts a sortable column.",
+			"columnMoved": "{0} moved to position {1} of {2}",
+			"resizeInstructions": "Alt + left or right arrow resizes the column; double-click its edge to restore the declared width."
 		},
 		"baseTimePickerInput": {
 			"emptySelection": "Select a time",

package/dist/nuxt-auto-imports.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The name registry behind the `bitboss-ui/nuxt` module's `autoImport` option.
+ *
+ * v3's default stance is EXPLICIT imports: nothing is globally registered, so
+ * `vueCompilerOptions.checkUnknownComponents` turns a typo'd or unimported
+ * `<BbTabs>` into a `vue-tsc` error instead of a silently missing widget (see
+ * ai/guides/installation-and-plugin-setup.md). `autoImport` deliberately trades
+ * that gate away for Nuxt's zero-import ergonomics — it exists so an app coming
+ * from `@bitboss-dev/bitboss-ui-nuxt`, whose templates were written against
+ * auto-imported components, does not have to add ~60 imports per page in the
+ * same commit that moves it to v3.
+ *
+ * Nuxt needs the names at config time and the published package is `dist/` —
+ * there is no source tree to read them from — so they are written out here.
+ * `nuxt-auto-imports.node.test.ts` diffs these lists against the actual exports
+ * of `src/index.ts` and `src/validated/index.ts` on every run, so a component
+ * added to the library and not to this file fails the suite rather than
+ * quietly never auto-importing.
+ */
+/** The entrypoints an auto-imported name can be pulled from. */
+export declare const CORE_ENTRYPOINT: "bitboss-ui";
+export declare const VALIDATED_ENTRYPOINT: "bitboss-ui/validated";
+export type AutoImportEntrypoint = typeof CORE_ENTRYPOINT | typeof VALIDATED_ENTRYPOINT;
+/**
+ * Every component `bitboss-ui` exports. Mirrors the `export { default as … }`
+ * lines of `src/index.ts`, in the order Nuxt will see them (sorted).
+ */
+export declare const CORE_COMPONENTS: readonly string[];
+/**
+ * Every component `bitboss-ui/validated` exports — the vee-validate-bound form
+ * controls, their `BbForm` host, and `BbAsterisk` (re-exported there so a
+ * validated app gets the required marker from the same entrypoint as the
+ * controls that render it).
+ *
+ * With `validated: true` these SHADOW their core namesakes: `<BbTextInput>` in
+ * a template resolves to the validated wrapper, which is the whole point — the
+ * template stays identical and gains `rules` / `vid` / `validateOn`.
+ */
+export declare const VALIDATED_COMPONENTS: readonly string[];
+/**
+ * Composables `bitboss-ui` exports that are deliberately NOT auto-imported.
+ *
+ * `useId` collides head-on with the `useId` Nuxt already auto-imports from Vue.
+ * Registering ours would silently redirect every `useId()` call in the app —
+ * including ones written long before bitboss-ui was installed — to a different
+ * generator. Apps that want the library's still `import { useId } from
+ * 'bitboss-ui'` explicitly.
+ */
+export declare const EXCLUDED_COMPOSABLES: readonly string[];
+/** Composables auto-imported from `bitboss-ui`. */
+export declare const CORE_COMPOSABLES: readonly string[];
+/** Composables auto-imported from `bitboss-ui/validated` under `validated`. */
+export declare const VALIDATED_COMPOSABLES: readonly string[];
+/**
+ * `autoImport` as written in `nuxt.config.ts`. `true` is shorthand for
+ * `{ components: true, composables: true }` — validated wrappers are opt-in on
+ * top, because swapping them in changes what a `<BbTextInput>` tag resolves to.
+ */
+export type BitbossAutoImportOptions = {
+    /**
+     * Register every `bitboss-ui` component with Nuxt so templates can use them
+     * without an import.
+     *
+     * @defaultValue `true` when `autoImport` is enabled
+     */
+    components?: boolean;
+    /**
+     * Add the library's composables to Nuxt's auto-import presets.
+     *
+     * @defaultValue `true` when `autoImport` is enabled
+     */
+    composables?: boolean;
+    /**
+     * Resolve the form controls from `bitboss-ui/validated` instead of
+     * `bitboss-ui`, and add `BbForm`, `BbAsterisk`, `useBbFormContext` and
+     * `useValidatedField`. Requires the `vee-validate` peer.
+     *
+     * @defaultValue `false`
+     */
+    validated?: boolean;
+};
+export type BitbossAutoImport = boolean | BitbossAutoImportOptions;
+/** One resolved registration: the name Nuxt registers and where it comes from. */
+export type AutoImportEntry = {
+    name: string;
+    from: AutoImportEntrypoint;
+};
+export type ResolvedAutoImports = {
+    components: AutoImportEntry[];
+    composables: AutoImportEntry[];
+};
+/**
+ * Turn the `autoImport` option into the exact list of names the Nuxt module
+ * hands to `addComponent` / `addImports`.
+ *
+ * Kept a pure function — no `@nuxt/kit`, no I/O — so the mapping that decides
+ * whether `<BbTextInput>` is the plain or the validated control is testable on
+ * its own, without booting Nuxt.
+ */
+export declare const resolveAutoImports: (autoImport: BitbossAutoImport | undefined) => ResolvedAutoImports;