bitboss-ui 3.0.0-beta.18 → 3.0.0-beta.19

package/README.md

@@ -6,7 +6,7 @@ Vue 3 component library used across BitBoss products. It ships typed building bl
 
 ## What’s in the package
 
-Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, the two stylesheets **`styles.css`** and **`reset.css`**, and the `dist/ai/` knowledge base), plus the **`bin/`** CLI, **`scripts/lib/`** (ESLint plugin and markup validator), the root **`llms.txt`**, and this **README**. The sections below match how the library is organised in code and in the [documentation](https://ui-components-docs.vercel.app/).
+Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, the two stylesheets **`styles.css`** and **`reset.css`**, and the `dist/ai/` knowledge base), plus the **`bin/`** CLI, **`scripts/lib/`** (ESLint plugin and markup validator), the root **`llms.txt`**, and this **README**. The sections below match how the library is organised in code and in the [documentation](https://ui-components.bitboss.it/).
 
 ### Styles
 
@@ -90,7 +90,7 @@ For the public **Bb\*** components, the package exports matching **props**, **ev
 
 **Primary docs (components, props, guides):**
 
-- [BitBoss UI documentation](https://ui-components-docs.vercel.app/) — site with guides and API reference.
+- [BitBoss UI documentation](https://ui-components.bitboss.it/) — site with guides and API reference.
 
 **For AI coding agents:**
 
@@ -100,10 +100,10 @@ v3 prerelease; pin an exact version (`bitboss-ui@3.0.0-alpha.5`) for stable
 links. Sizes grow with the catalogue — treat them as the current order of
 magnitude, not a contract.
 
-- [Core knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-medium.txt) (~110 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
-- [Index](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/llms.txt) (~19 KB) — link index into every document.
-- [components.json](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/ai/components.json) — machine-readable API surface, for programmatic validation.
-- [Complete knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-full.txt) (~3.2 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
+- [Core knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-medium.txt) (~110 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
+- [Index](https://llms-bitboss-ui.bitboss.it/llms.txt) (~19 KB) — link index into every document.
+- [components.json](https://llms-bitboss-ui.bitboss.it/dist/ai/components.json) — machine-readable API surface, for programmatic validation.
+- [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt) (~3.2 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
 
 Already installed? Prefer the local copy under `node_modules/bitboss-ui/dist/ai/`,
 run `npx bitboss-ui ai-init` to write agent pointers, and
@@ -328,6 +328,38 @@ migrations — a value that must move to a slot, directive, or CSS — are repor
 with a migration-guide link but left for you. Run `eslint --fix`, then the
 remaining reports are exactly the by-hand cases.
 
+#### The one v2 break a codemod cannot own: `reverse`
+
+`reverse` on `BbCheckbox` / `BbRadio` / `BbSwitch` kept its **name** and
+inverted its **meaning** in v3. Both versions render the same default layout,
+so only explicit values moved:
+
+| v2                            | v3        |
+| ----------------------------- | --------- |
+| `:reverse="false"`            | `reverse` |
+| `reverse` / `:reverse="true"` | delete it |
+
+That is invisible to every other check — `:reverse="false"` is a declared prop,
+correctly typed, holding its own default value — and it cannot go in the
+rename table above, because the table is keyed by prop _name_: an entry for
+`reverse` would rewrite the legitimate v3 spellings too.
+
+So it has its own rule, `bitboss-ui/no-reverse-false` (in `recommended`). It
+flags only a **literal** `:reverse="false"` and offers both corrections as
+editor suggestions — a dynamic `:reverse="isRtl"` that merely evaluates false
+is left alone. For a bulk sweep of a v2 codebase, opt into the fix:
+
+```js
+{
+	rules: {
+		'bitboss-ui/no-reverse-false': ['error', { assumeV2: true }],
+	},
+}
+```
+
+`assumeV2` is off by default because the two readings produce opposite
+layouts — turn it on only for files you know came from v2, then turn it off.
+
 Every real HTML attribute (plus `aria-*` / `data-*`) falls through untouched, so
 attribute inheritance is never flagged. Escape hatches when you do need one:
 
@@ -406,7 +438,7 @@ MIT — see [`LICENSE`](LICENSE).
 
 ## Support
 
-- **Usage and APIs:** see the [documentation](https://ui-components-docs.vercel.app/).
+- **Usage and APIs:** see the [documentation](https://ui-components.bitboss.it/).
 - **Company / licensing / commercial:** [BitBoss](https://www.bitboss.it/).
 
 ### Reporting a bug

package/dist/ai/BbBaseCheckboxGroup.md

@@ -22,7 +22,7 @@
 | `depsDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) applied when reacting to `dependencies` changes. |
 | `direction` | `"horizontal" \| "vertical" \| undefined` | `"horizontal"` |  | Direction of the group layout. - `horizontal`: options flow in rows - `vertical`: options stack in a column |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables interaction for the whole group. |
-| `enforceCoherence` | `boolean \| undefined` | `false` |  | Enforces that `modelValue` contains only values present in `items`. Incoherent values are removed and `update:modelValue` is emitted with a coherent array. Please check out {@link https://ui-components-docs.vercel.app/it/guides/coherence th… |
+| `enforceCoherence` | `boolean \| undefined` | `false` |  | Enforces that `modelValue` contains only values present in `items`. Incoherent values are removed and `update:modelValue` is emitted with a coherent array. Please check out {@link https://ui-components.bitboss.it/it/guides/coherence the doc… |
 | `hasErrors` | `boolean \| undefined` | `false` |  | Puts the component into an error state adds the error styling class. |
 | `hasWarning` | `boolean \| undefined` | `false` |  | Puts the component into a warning state. Errors take priority when both are set. |
 | `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. |

package/dist/ai/BbBaseSwitchGroup.md

@@ -22,7 +22,7 @@
 | `depsDebounceTime` | `number \| undefined` | `0` |  | Debounce delay (ms) applied when reacting to `dependencies` changes. |
 | `direction` | `"horizontal" \| "vertical" \| undefined` | `"horizontal"` |  | Direction of the group layout. - `horizontal`: options flow in rows - `vertical`: options stack in a column |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables interaction for the whole group. |
-| `enforceCoherence` | `boolean \| undefined` | `false` |  | Enforces that `modelValue` contains only values present in `items`. Incoherent values are removed and `update:modelValue` is emitted with a coherent array. Please check out {@link https://ui-components-docs.vercel.app/it/guides/coherence th… |
+| `enforceCoherence` | `boolean \| undefined` | `false` |  | Enforces that `modelValue` contains only values present in `items`. Incoherent values are removed and `update:modelValue` is emitted with a coherent array. Please check out {@link https://ui-components.bitboss.it/it/guides/coherence the doc… |
 | `hasErrors` | `boolean \| undefined` | `false` |  | Puts the component into an error state adds the error styling class. |
 | `hasWarning` | `boolean \| undefined` | `false` |  | Puts the component into a warning state. Errors take priority when both are set. |
 | `hideLabel` | `boolean \| undefined` | `false` |  | Visually hides each option's label text (the text rendered next to every input) while keeping it accessible to screen readers. |

package/dist/ai/BbDialog.md

@@ -186,6 +186,65 @@ Use the `title` slot to restyle just the title text — it stays wired to
 removes the whole header (the close button then floats over the body corner
 unless `hide-close`), and you own the accessible name.
 
+Add `description` for one muted line under the title — the dialog's subtitle,
+and the only thing `aria-describedby` points at:
+
+**A described dialog**
+
+```vue
+<template>
+	<div
+		class="flex w-full max-w-sm flex-col gap-3 rounded-[var(--bb-radius)] border p-4"
+	>
+		<div>
+			<p class="m-0 text-sm font-medium">INV-2044</p>
+			<p class="m-0 text-xs text-[color:var(--bb-text-muted)]">
+				Northwind Traders · €1,280.00 · paid
+			</p>
+		</div>
+		<div>
+			<BbButton
+				prepend:icon="lucide:trash-2"
+				variant="outline"
+				@click="open = true"
+			>
+				Delete invoice
+			</BbButton>
+		</div>
+	</div>
+	<BbDialog
+		v-model="open"
+		description="This permanently removes the invoice and its payment history."
+		title="Delete invoice INV-2044"
+	>
+		<p class="m-0">
+			Anything that does not fit in one line belongs here, in the body — which
+			is deliberately not what <code>aria-describedby</code> points at.
+		</p>
+		<template #footer>
+			<div class="flex justify-end gap-2">
+				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
+				<BbButton variant="destructive" @click="open = false">Delete</BbButton>
+			</div>
+		</template>
+	</BbDialog>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbDialog } from 'bitboss-ui';
+
+const open = ref(false);
+</script>
+```
+
+Keep it to a sentence; the detail belongs in the body, which is deliberately
+**not** described (pointing `aria-describedby` at arbitrary markup makes a
+screen reader read a whole form as the dialog's description). Use the
+`description` slot when the line needs markup — it receives the prop as `text`.
+A dialog with no `description` keeps its original single-row header, so nothing
+shifts unless you opt in.
+
 Prefer `title` (or the `title` slot) for the standard header. The `header` slot
 replaces the entire header on both surfaces — you own the close control and must
 wire `titleId` for `aria-labelledby`. Give your root element `flex-1` so it fills
@@ -762,6 +821,8 @@ default falls back to `config.adaptive`.
 - The dialog is a true modal (`showModal()`): the browser contains focus within
   it, the page behind is inert, and focus returns to the trigger when it
   closes. `focus-target` only chooses where focus **starts**.
+- `description` is what `aria-describedby` points at, so the dialog announces
+  its purpose and not just its name. Nothing else is described — see above.
 - The header close button carries a localized `aria-label` out of the box
   (`config.locale`).
 - Don't lean on `persistent` to trap users. Keep a visible way out (a Cancel or
@@ -776,6 +837,7 @@ default falls back to `config.adaptive`.
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `adaptive` | `boolean \| undefined` | ``config.adaptive` (`true`)` |  | Adapt the surface to the viewport: render as a `BbOffCanvas` drawer on mobile instead of a centered dialog. The surface is resolved when the dialog opens and stays fixed for that session: resizing across the mobile breakpoint while open nev… |
+| `description` | `string \| undefined` |  |  | One short line under the title, in the header — the shadcn `DialogDescription` shape: same block as the title, lower hierarchy, muted. It is also what `aria-describedby` points at. That wiring was dropped in v3 along with the old `descripti… |
 | `disabled` | `boolean \| undefined` | `false` |  | Disable EVERY user-initiated dismissal: backdrop click, Escape AND the header close (×) button (denied attempts play the deny nudge). Use it while an operation is in flight (e.g. a save) so the dialog cannot be dismissed mid-work. Compare `… |
 | `eager` | `boolean \| undefined` | `false` |  | Render dialog content immediately instead of waiting for the first open. |
 | `focusTarget` | `string \| undefined` |  |  | CSS selector of the element to focus after opening. Defaults to the first tabbable element. |
@@ -800,6 +862,7 @@ default falls back to `config.adaptive`.
 ## Slots
 
 - `default` — scope: `BbDialogDefaultSlotProps` — Primary body content of the dialog, rendered in the scrollable body area.
+- `description` — scope: `BbDialogDescriptionSlotProps` — Replaces the description text under the title. Renders the header even when `title` and `description` are unset — a slotted description is a description, the same rule `#title` follows.
 - `footer` — scope: `object` — Content rendered in the dialog footer, below the body area. Typically used for action buttons.
 - `header` — scope: `BbDialogHeaderSlotProps` — Replaces the entire dialog header section (title + close button) on both surfaces — the desktop `<dialog>` and the mobile off-canvas. Because it replaces the default close (✕), the slot owns closing: render your own control wired to the `cl…
 - `title` — scope: `BbDialogTitleSlotProps` — Replaces the default title text inside the header. Remains linked to the dialog through `aria-labelledby`. Providing this slot renders the header even when `title` is unset — a slotted title is a title.

package/dist/ai/BbOffCanvas.md

@@ -161,6 +161,11 @@ header and footer stay pinned.
 
 - Use the `title` slot to restyle just the title text — it stays wired to
   `aria-labelledby` and receives the `title` prop as `text`.
+- **`description`** adds one muted line under the title — the panel's subtitle,
+  and the only thing `aria-describedby` points at. Keep it to a sentence; the
+  body is deliberately not described. The `description` slot takes markup and
+  receives the prop as `text`. A panel without one keeps its original
+  single-row header.
 - The **`header` slot** replaces the whole header section; it receives
   `titleId`, `title` and `close`, so you can build a custom header and still
   keep the accessible name wired through `titleId`. `BbDialog` supports the
@@ -169,6 +174,55 @@ header and footer stay pinned.
 - Omitting `title` (and the `header` slot) removes the header entirely — you
   then own the accessible name.
 
+**A described panel (via the #description slot)**
+
+```vue
+<template>
+	<BbButton
+		prepend:icon="lucide:user-plus"
+		variant="outline"
+		@click="open = true"
+	>
+		Invite teammate
+	</BbButton>
+	<BbOffCanvas v-model="open" side="right" title="Invite teammate">
+		<!-- The slot takes markup where the prop would only take a string. -->
+		<template #description>
+			They join the <strong>Northwind</strong> workspace as a viewer.
+		</template>
+		<div class="grid gap-3">
+			<BbTextInput
+				v-model="email"
+				compact
+				label="Email"
+				placeholder="ada@northwind.co"
+				type="email"
+			/>
+		</div>
+		<template #footer>
+			<div class="flex justify-end gap-2">
+				<BbButton variant="ghost" @click="open = false">Cancel</BbButton>
+				<BbButton
+					:disabled="!email.trim()"
+					variant="primary"
+					@click="open = false"
+				>
+					Send invite
+				</BbButton>
+			</div>
+		</template>
+	</BbOffCanvas>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbButton, BbOffCanvas, BbTextInput } from 'bitboss-ui';
+
+const open = ref(false);
+const email = ref('');
+</script>
+```
+
 ### A filters drawer
 
 The archetypal off-canvas: search + toggles in the `default` slot, Apply/Reset
@@ -913,6 +967,8 @@ The panel is a native `<dialog>` opened with `showModal()` — the same mechanic
 - The panel is a true modal (`showModal()`): focus is contained within it, the
   page behind is inert, and focus returns to the trigger when it closes.
   `focus-target` only chooses where focus **starts**.
+- `description` is what `aria-describedby` points at, so the panel announces
+  its purpose and not just its name.
 - The header close button carries a localized `aria-label` out of the box
   (`config.locale`).
 - Draggable dismissal is a convenience, not the only way out — the close button,
@@ -929,6 +985,7 @@ The panel is a native `<dialog>` opened with `showModal()` — the same mechanic
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
+| `description` | `string \| undefined` |  |  | One short line under the title, in the header — the shadcn `DialogDescription` shape: same block as the title, lower hierarchy, muted. It is also what `aria-describedby` points at. That wiring was dropped in v3 along with the old `descripti… |
 | `disabled` | `boolean \| undefined` | `false` |  | Disable EVERY user-initiated dismissal: backdrop click, Escape, drag-to-dismiss AND the header close (×) button (denied attempts play the deny nudge). Use it while an operation is in flight (e.g. a save) so the drawer cannot be dismissed mi… |
 | `draggable` | `boolean \| undefined` | `false` |  | Enable drag-to-dismiss. The panel can be dragged from anywhere toward its edge to close, and a grab handle is shown on the inner edge as the affordance. When `false`, the panel is static (dismiss via the close button, backdrop, or Escape on… |
 | `eager` | `boolean \| undefined` | `false` |  | Render offcanvas content immediately instead of waiting for the first open. |
@@ -955,6 +1012,7 @@ The panel is a native `<dialog>` opened with `showModal()` — the same mechanic
 ## Slots
 
 - `default` — scope: `{ close: () => void; }` — Primary body content of the off-canvas panel, rendered in the scrollable body area.
+- `description` — scope: `BbOffCanvasDescriptionSlotProps` — Replaces the description text under the title. Renders the header even when `title` and `description` are unset — a slotted description is a description, the same rule `#title` follows.
 - `footer` — scope: `object` — Content rendered in the panel footer, below the body area. Typically used for action buttons.
 - `header` — scope: `BbOffCanvasHeaderSlotProps` — Replaces the entire off-canvas header section (title + close button). Maintains accessibility wiring via the provided props.
 - `title` — scope: `BbOffCanvasTitleSlotProps` — Replaces the default title text inside the header. Remains linked to the panel through `aria-labelledby`. Providing this slot renders the header even when `title` is unset — a slotted title is a title.

package/dist/ai/BbSelect.md

@@ -613,8 +613,10 @@ later responses don't include them — no need to merge them into every response
 `prefill` controls **when the first load happens**:
 
 - `'interaction'` (default) — on the first open.
-- `true` — immediately on mount, and during SSR (`onServerPrefetch`), so the
-  panel is warm on hydration.
+- `true` — immediately on mount, and during SSR **on hosts that can carry the
+  result to the client** (Nuxt does; see
+  [SSR prefill](./guides/ssr-prefill.md)), so the panel is warm on hydration.
+  Everywhere else the load happens on the client, right after mount.
 - `false` — **search-first**: nothing loads until the user types. Opening is not
   a search, so the panel opens empty and shows a _"search to begin"_ hint until
   the first query. Use it when the result set is too big or too costly to browse
@@ -1337,9 +1339,13 @@ From the vite/nuxt plugin options:
 
 Platform notes:
 
-- **SSR / Nuxt**: `prefill: true` providers also run in `onServerPrefetch`, so
-  server-rendered pages hydrate with options loaded. Keep providers isomorphic
-  (no `window` access).
+- **SSR / Nuxt**: under `bitboss-ui/nuxt`, `prefill: true` providers run in
+  `onServerPrefetch` AND their result travels in the Nuxt payload, so the client
+  hydrates with the options already in hand and never re-requests them. Under any
+  other SSR host the provider does **not** run on the server at all — the server
+  emits the placeholder and the client loads on mount, which keeps hydration
+  clean. Keep providers isomorphic (no `window` access) and have them return
+  plain, serializable rows. See [SSR prefill](./guides/ssr-prefill.md).
 - **Plain HTML forms / Inertia form posts**: give the select a `name` — hidden
   inputs carry the values (JSON-stringified when not strings), and `required`
   participates in native validation.

package/dist/ai/BbSelectPopover.md

@@ -398,8 +398,9 @@ const destinationLabel = computed(
 ### Laziness, prefill and the trigger label
 
 `prefill` controls **when the first load happens**: `'interaction'` (default) on
-first open, `true` immediately on mount (and during SSR via `onServerPrefetch`),
-`false` **search-first** — nothing is fetched until the user types a query.
+first open, `true` immediately on mount (and during SSR via `onServerPrefetch`,
+but only on a host that can transfer the result — see
+[SSR prefill](./guides/ssr-prefill.md)), `false` **search-first** — nothing is fetched until the user types a query.
 Opening the panel is not a search, so it loads nothing; until the first query the
 list shows a _"search to begin"_ hint instead of "no data".
 
@@ -1199,9 +1200,13 @@ floating popover everywhere.
 - **Global config** — `config.adaptive` (default for `adaptive`),
   `config.mobileMaxWidth` (the mobile threshold), `config.locale` (the search
   field's default accessible name and panel string defaults).
-- **SSR / Nuxt** — `prefill: true` providers also run in `onServerPrefetch`, so
-  server-rendered pages hydrate with options loaded; keep providers isomorphic
-  (no `window` access).
+- **SSR / Nuxt** — under `bitboss-ui/nuxt`, `prefill: true` providers run in
+  `onServerPrefetch` and their result rides the Nuxt payload, so the client
+  hydrates with options already loaded and does not fetch again. On other SSR
+  hosts the provider stays client-side and the server renders the placeholder —
+  deliberately, since server markup the client cannot rebuild is a hydration
+  mismatch. Keep providers isomorphic (no `window` access) and returning plain
+  rows. See [SSR prefill](./guides/ssr-prefill.md).
 
 ### Works well with
 

package/dist/ai/BbSwitch.md

@@ -386,6 +386,18 @@ const usageAnalytics = ref(true);
 			name="captions"
 			reverse
 		/>
+		<!-- A described row keeps the same trailing edge: `input-position`
+		     applies on the description path too, and the switch pins to the
+		     label's FIRST line rather than the centre of the two-line block. -->
+		<BbSwitch
+			v-model="downloads"
+			description="Uses storage on this device, and only over Wi-Fi."
+			direction="xxxxxx xx"
+			input-position="right"
+			label="Download for offline"
+			name="downloads"
+			reverse
+		/>
 	</div>
 </template>
 <script setup lang="ts">
@@ -394,6 +406,7 @@ import { BbSwitch } from 'bitboss-ui';
 
 const autoplay = ref(true);
 const captions = ref(false);
+const downloads = ref(true);
 </script>
 ```
 

package/dist/ai/BbTable.md

@@ -2754,10 +2754,13 @@ reader.
   plugin is still on the default locale, which is `it` — set the plugin's
   `locale` option, or override per table with `actions-text` (it is visually
   hidden in the header but read by screen readers).
-- **SSR / Nuxt.** A provider `items` function participates in
-  `onServerPrefetch`, so the first page can render server-side. The table
-  context (and thus `table-id` pagination wiring) is client-side only —
-  hydration-time onward.
+- **SSR / Nuxt.** Under `bitboss-ui/nuxt` a provider `items` function
+  participates in `onServerPrefetch` and its rows travel in the Nuxt payload, so
+  the first page renders server-side and hydrates without re-fetching. On other
+  SSR hosts the provider runs on the client only and the server renders the
+  empty table — see [SSR prefill](./guides/ssr-prefill.md). The table context
+  (and thus `table-id` pagination wiring) is client-side only — hydration-time
+  onward.
 - **Forms.** With `name`, the selection submits as hidden inputs — no JS
   needed between the table and a plain `<form>` POST (Inertia included).
 

package/dist/ai/changelog.json

@@ -1,7 +1,7 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.18",
+	"version": "3.0.0-beta.19",
 	"upgrade": "v2-to-v3",
 	"guide": "ai/guides/migration/v2-to-v3.md",
 	"summary": {

package/dist/ai/components.json

@@ -1,8 +1,8 @@
 {
 	"schemaVersion": 1,
 	"library": "bitboss-ui",
-	"version": "3.0.0-beta.18",
-	"generatedAt": "2026-08-31T15:46:07.123Z",
+	"version": "3.0.0-beta.19",
+	"generatedAt": "2026-09-01T10:39:24.755Z",
 	"composables": [
 		{
 			"name": "useBbConfig",
@@ -1233,7 +1233,7 @@
 					"type": "boolean | undefined",
 					"required": false,
 					"default": "false",
-					"description": "Enforces that `modelValue` contains only values present in `items`.\nIncoherent values are removed and `update:modelValue` is emitted with a\ncoherent array. Please check out {@link https://ui-components-docs.vercel.app/it/guides/coherence the docs} for more information."
+					"description": "Enforces that `modelValue` contains only values present in `items`.\nIncoherent values are removed and `update:modelValue` is emitted with a\ncoherent array. Please check out {@link https://ui-components.bitboss.it/it/guides/coherence the docs} for more information."
 				},
 				{
 					"name": "hasErrors",
@@ -4140,7 +4140,7 @@
 					"type": "boolean | undefined",
 					"required": false,
 					"default": "false",
-					"description": "Enforces that `modelValue` contains only values present in `items`.\nIncoherent values are removed and `update:modelValue` is emitted with a\ncoherent array. Please check out {@link https://ui-components-docs.vercel.app/it/guides/coherence the docs} for more information."
+					"description": "Enforces that `modelValue` contains only values present in `items`.\nIncoherent values are removed and `update:modelValue` is emitted with a\ncoherent array. Please check out {@link https://ui-components.bitboss.it/it/guides/coherence the docs} for more information."
 				},
 				{
 					"name": "hasErrors",
@@ -8043,6 +8043,12 @@
 					"default": "`config.adaptive` (`true`)",
 					"description": "Adapt the surface to the viewport: render as a `BbOffCanvas` drawer on\nmobile instead of a centered dialog. The surface is resolved when the\ndialog opens and stays fixed for that session: resizing across the mobile\nbreakpoint while open never swaps it.\n\nWhen unset, falls back to the global `config.adaptive`."
 				},
+				{
+					"name": "description",
+					"type": "string | undefined",
+					"required": false,
+					"description": "One short line under the title, in the header — the shadcn\n`DialogDescription` shape: same block as the title, lower hierarchy,\nmuted.\n\nIt is also what `aria-describedby` points at. That wiring was dropped in\nv3 along with the old `description` prop, on the reasoning that pointing\nit at arbitrary body content would read whole forms aloud — true, and the\nreason it aims at THIS element only. Keep it to a sentence; anything\nlonger belongs in the body."
+				},
 				{
 					"name": "disabled",
 					"type": "boolean | undefined",
@@ -8151,6 +8157,11 @@
 					"type": "BbDialogDefaultSlotProps",
 					"description": "Primary body content of the dialog, rendered in the scrollable body area."
 				},
+				{
+					"name": "description",
+					"type": "BbDialogDescriptionSlotProps",
+					"description": "Replaces the description text under the title. Renders the header even\nwhen `title` and `description` are unset — a slotted description is a\ndescription, the same rule `#title` follows."
+				},
 				{
 					"name": "footer",
 					"type": "object",
@@ -8195,16 +8206,6 @@
 						"kind": "manual"
 					}
 				},
-				{
-					"name": "description",
-					"new": null,
-					"since": "3.0.0-unreleased",
-					"migration": "ai/guides/migration/components/bb-dialog.md",
-					"silent": true,
-					"fix": {
-						"kind": "manual"
-					}
-				},
 				{
 					"name": "hideHeader",
 					"new": null,
@@ -9437,6 +9438,12 @@
 			"contract": "ai/BbOffCanvas.md",
 			"source": "ai/source/BbOffCanvas.md",
 			"props": [
+				{
+					"name": "description",
+					"type": "string | undefined",
+					"required": false,
+					"description": "One short line under the title, in the header — the shadcn\n`DialogDescription` shape: same block as the title, lower hierarchy,\nmuted.\n\nIt is also what `aria-describedby` points at. That wiring was dropped in\nv3 along with the old `description` prop, on the reasoning that pointing\nit at arbitrary body content would read whole forms aloud — true, and the\nreason it aims at THIS element only. Keep it to a sentence; anything\nlonger belongs in the body."
+				},
 				{
 					"name": "disabled",
 					"type": "boolean | undefined",
@@ -9560,6 +9567,11 @@
 					"type": "{ close: () => void; }",
 					"description": "Primary body content of the off-canvas panel, rendered in the scrollable body area."
 				},
+				{
+					"name": "description",
+					"type": "BbOffCanvasDescriptionSlotProps",
+					"description": "Replaces the description text under the title. Renders the header even\nwhen `title` and `description` are unset — a slotted description is a\ndescription, the same rule `#title` follows."
+				},
 				{
 					"name": "footer",
 					"type": "object",
@@ -9594,16 +9606,6 @@
 						"kind": "manual"
 					}
 				},
-				{
-					"name": "description",
-					"new": null,
-					"since": "3.0.0-unreleased",
-					"migration": "ai/guides/migration/components/bb-offcanvas.md",
-					"silent": true,
-					"fix": {
-						"kind": "manual"
-					}
-				},
 				{
 					"name": "direction",
 					"new": "side",

package/dist/ai/composables/useBbConfig.md

@@ -53,12 +53,53 @@ 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.
 
-**`setConfig` during a server render is the fallback, and it has one rule:**
-call it from a component's `setup` (or a composable a component calls), where
-it can resolve the current app. Called from module scope there is no app to
-address, so the write lands on the process-global build-time defaults and
-leaks into other visitors being served concurrently — it warns in dev when it
-detects this.
+#### 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.

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/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.