bitboss-ui 3.0.0-beta.30 → 3.0.0-beta.32

package/README.md

@@ -244,7 +244,8 @@ npx bitboss-ui ai-init
 # same as: npx bitboss-ui ai-init --update
 ```
 
-Idempotently writes:
+Idempotently writes the pointer files below **and** sets up the MCP server
+(next section); `--no-mcp` skips the server:
 
 | File                                    | Harness                  |
 | --------------------------------------- | ------------------------ |
@@ -256,49 +257,48 @@ Idempotently writes:
 
 Re-run after upgrading `bitboss-ui` so versioned pointers stay fresh.
 
-### MCP server (optional)
+### MCP server
 
-The kickstart above writes static pointer files. Add `--mcp` to also register a
-live [Model Context Protocol](https://modelcontextprotocol.io) server so agents
-can **query** the knowledge base (search components, read a contract, validate
-markup) instead of reading files blind:
+Besides the static pointer files, `ai-init` registers a live
+[Model Context Protocol](https://modelcontextprotocol.io) server so agents can
+**query** the knowledge base (search components, read a contract, validate
+markup) instead of reading files blind. It is on by default; opt out with:
 
 ```bash
-npm i -D @modelcontextprotocol/sdk zod
-npx bitboss-ui ai-init --mcp
+npx bitboss-ui ai-init --no-mcp
 ```
 
-Those two are **optional peer dependencies**, not dependencies: together they
-weigh ~12 MB — more than every runtime dependency of the component library
-combined — and nothing but the MCP server loads them, so installing
-`bitboss-ui` never drags them in. `ai-init --mcp` warns if they are missing,
-and `bitboss-ui mcp` tells you what to install rather than dying on a module
-resolution error.
+The server needs `@modelcontextprotocol/sdk` and `zod`. They are **optional
+peer dependencies**, not dependencies: together they weigh ~12 MB — more than
+every runtime dependency of the component library combined — and nothing but
+the MCP server loads them, so installing `bitboss-ui` never drags them in.
+`ai-init` installs them as dev dependencies with your package manager (npm,
+pnpm, yarn or bun, from your lockfile); if that fails it prints the command to
+run, and `bitboss-ui mcp` tells you what to install rather than dying on a
+module resolution error. `--no-mcp` skips the install too.
 
 The agent harness launches the server itself (`node node_modules/bitboss-ui/bin/bitboss-ui.mjs mcp`,
 the installed binary rather than `npx`, so it can never fetch from the registry, its optional
 peers resolve in your project, and it cannot drift behind an upgrade) on demand —
-you never run it by hand. `--mcp` merges the server entry into each harness's
+you never run it by hand. `ai-init` merges the server entry into each harness's
 own config (never overwriting other servers you've registered), and each write
 is idempotent:
 
-| File                                  | Harness           | Scope                      |
-| ------------------------------------- | ----------------- | -------------------------- |
-| `.mcp.json`                           | Claude Code       | project                    |
-| `.cursor/mcp.json`                    | Cursor            | project                    |
-| `.vscode/mcp.json`                    | VS Code / Copilot | project                    |
-| `~/.codeium/windsurf/mcp_config.json` | Windsurf          | **global (whole machine)** |
+| File               | Harness           |
+| ------------------ | ----------------- |
+| `.mcp.json`        | Claude Code       |
+| `.cursor/mcp.json` | Cursor            |
+| `.vscode/mcp.json` | VS Code / Copilot |
 
-> **Windsurf is global.** Cascade only reads one config in your home directory —
-> it has no per-project scope — so registering it affects **every** project on
-> your machine, not just this one. That is why the dev-server auto-registration
-> below deliberately skips Windsurf; only the explicit `ai-init --mcp` command
-> writes it.
+Windsurf only reads a global config in your home directory, so the server is
+not registered for it — add the same entry to
+`~/.codeium/windsurf/mcp_config.json` yourself if you use it. Its
+`.windsurf/rules` pointer is written as above.
 
-**Zero-command option (dev server):** instead of running `ai-init --mcp`, pass
+**Zero-command option (dev server):** instead of running `ai-init`, pass
 `mcp: true` to the Vite/Nuxt plugin and the dev server registers the
-project-scoped harnesses (Claude Code, Cursor, VS Code) automatically on boot —
-idempotent, and it leaves Windsurf's global config alone:
+same harnesses automatically on boot — idempotent, and it never installs
+anything (run `ai-init` once for the peers):
 
 ```ts
 bitbossUi({ iconDir: './assets/icons', mcp: true });

package/bin/bitboss-ui-mcp.mjs

@@ -25,7 +25,8 @@
  * is stable across zod 3 and 4, so the lower bound costs nothing.
  *
  * Run standalone: `npx bitboss-ui mcp` (delegated from bin/bitboss-ui.mjs).
- * Register with an MCP-capable harness via `npx bitboss-ui ai-init --mcp`.
+ * Registered with every MCP-capable harness by `npx bitboss-ui ai-init`
+ * (on by default; `--no-mcp` skips it).
  */
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

package/bin/bitboss-ui.mjs

@@ -11,8 +11,10 @@
  *             - .github/copilot-instructions.md fragment (GitHub Copilot)
  *             - .claude/skills/bitboss-ui/SKILL.md (Claude Code)
  *             - .windsurf/rules/bitboss-ui.md (Windsurf)
- *             Accepts an optional --mcp flag (combinable with --update) to also
- *             register the `bitboss-ui mcp` server in .mcp.json.
+ *             Also registers the `bitboss-ui mcp` server for Claude Code,
+ *             Cursor and VS Code and installs its optional peers
+ *             (`@modelcontextprotocol/sdk`, `zod`) with the project's package
+ *             manager; pass --no-mcp to skip both.
  *   check     Validate Bb* markup in .vue/.md files against the installed
  *             components.json manifest (unknown props, removed props, bad
  *             v-models, unknown `<template #slot>` names, `href`/`to`/
@@ -43,6 +45,7 @@
  * Plain ESM JavaScript on purpose: shipped as-is in the package, no build.
  */
 
+import { spawnSync } from 'node:child_process';
 import {
 	existsSync,
 	globSync,
@@ -60,6 +63,8 @@ import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
 import {
+	detectPackageManager,
+	devInstallCommand,
 	ensureMcpConfigs,
 	missingMcpPeers,
 	MCP_BIN_PATH,
@@ -209,7 +214,7 @@ function tryWrite(label, fn) {
 	}
 }
 
-function aiInit({ mcp = false } = {}) {
+function aiInit({ mcp = true } = {}) {
 	const projectRoot = process.cwd();
 	const version = packageVersion();
 
@@ -258,11 +263,7 @@ function aiInit({ mcp = false } = {}) {
 	];
 
 	if (mcp) {
-		// Explicit command → register every harness, including Windsurf's global
-		// (home-dir) config.
-		for (const result of ensureMcpConfigs(projectRoot, {
-			includeWindsurf: true,
-		})) {
+		for (const result of ensureMcpConfigs(projectRoot)) {
 			const suffix = result.reason ? ` (${result.reason})` : '';
 			results.push({
 				path: `${result.path} [${result.label}]${suffix}`,
@@ -271,18 +272,34 @@ function aiInit({ mcp = false } = {}) {
 		}
 
 		// The harness launches the server on demand, long after this command
-		// ran — so a missing peer would surface inside an agent as a server
-		// that never starts. Say it here, where the person is still watching.
+		// ran — a missing peer would surface inside an agent as a server that
+		// never starts. They are optional peers (~12 MB only the server loads),
+		// so installing the library never adds them; registering the server is
+		// the moment the project opts in, so install them here.
 		const missing = missingMcpPeers(projectRoot);
 		if (missing.length > 0) {
-			console.warn(
-				`[bitboss-ui] the MCP server needs ${missing.join(' and ')}, which ${
-					missing.length > 1 ? 'are' : 'is'
-				} not installed:\n` +
-					`\n  npm i -D ${missing.join(' ')}\n\n` +
-					'  Optional peers, not dependencies — ~12 MB that only the MCP\n' +
-					'  server uses. The harness entries above are written either way.'
+			const [cmd, ...args] = devInstallCommand(
+				detectPackageManager(projectRoot),
+				missing
 			);
+			const printed = [cmd, ...args].join(' ');
+			console.log(`[bitboss-ui] installing the MCP server's peers: ${printed}`);
+			const installed = spawnSync(cmd, args, {
+				cwd: projectRoot,
+				stdio: 'inherit',
+				// npm/pnpm/yarn are .cmd shims on Windows, which only a shell runs.
+				shell: process.platform === 'win32',
+			});
+			if (installed.status === 0) {
+				results.push({ path: missing.join(', '), action: 'installed' });
+			} else {
+				console.warn(
+					`[bitboss-ui] could not install ${missing.join(' and ')} — run it yourself:\n` +
+						`\n  ${printed}\n\n` +
+						'  The harness entries are written either way; the server starts\n' +
+						'  once the peers are installed.'
+				);
+			}
 		}
 	}
 
@@ -295,11 +312,11 @@ function aiInit({ mcp = false } = {}) {
 	);
 	if (mcp) {
 		console.log(
-			'MCP: registered the bitboss-ui server for Claude Code (.mcp.json), Cursor (.cursor/mcp.json), VS Code/Copilot (.vscode/mcp.json), and Windsurf (~/.codeium global) — restart your harness to pick it up.'
+			'MCP: registered the bitboss-ui server for Claude Code (.mcp.json), Cursor (.cursor/mcp.json) and VS Code/Copilot (.vscode/mcp.json) — restart your harness to pick it up. `--no-mcp` skips this.'
 		);
 	} else {
 		console.log(
-			'Tip: `npx bitboss-ui ai-init --mcp` also registers the MCP server across Claude Code / Cursor / VS Code / Windsurf so agents can query the knowledge base instead of reading files.'
+			'MCP: skipped (--no-mcp). Re-run without it to let agents query the knowledge base through the bitboss-ui MCP server instead of reading files.'
 		);
 	}
 	console.log('Re-run after upgrading bitboss-ui to refresh the pointers.');
@@ -904,14 +921,16 @@ Usage:
   npx bitboss-ui <command>
 
 Commands:
-  ai-init [--update] [--mcp]
+  ai-init [--update] [--no-mcp]
                       Inject AI-agent knowledge-base pointers into the current
                       project (AGENTS.md, Cursor rules, Copilot instructions,
-                      Claude skill, Windsurf rules). Idempotent — safe to re-run
-                      after upgrades. \`--mcp\` also registers the bitboss-ui MCP
-                      server for Claude Code (.mcp.json), Cursor (.cursor/mcp.json),
-                      VS Code/Copilot (.vscode/mcp.json), and Windsurf (~/.codeium
-                      global) — merges, never overwrites other servers.
+                      Claude skill, Windsurf rules), register the bitboss-ui MCP
+                      server for Claude Code (.mcp.json), Cursor
+                      (.cursor/mcp.json) and VS Code/Copilot (.vscode/mcp.json) —
+                      merges, never overwrites other servers — and install its
+                      optional peers with the project's package manager.
+                      \`--no-mcp\` skips the server and the install. Idempotent —
+                      safe to re-run after upgrades.
   check [glob…] [--json] [--allow-empty] [--allow-component <Name>]
                       [--no-hints] [--manifest <path>]
                       Validate \`Bb*\` markup in .vue/.md files against the
@@ -1000,9 +1019,11 @@ switch (command) {
 	case 'ai-init': {
 		const { values } = parseCommandArgs(command, commandArgs, {
 			update: { type: 'boolean' },
-			mcp: { type: 'boolean' },
+			// The MCP server is registered by default: people ran ai-init, got
+			// the pointers, and never learned the server existed.
+			'no-mcp': { type: 'boolean' },
 		});
-		aiInit({ mcp: values.mcp ?? false });
+		aiInit({ mcp: !values['no-mcp'] });
 		break;
 	}
 	case 'check': {
@@ -1059,7 +1080,7 @@ switch (command) {
 			// from, so a cached copy can never see the project's node_modules no
 			// matter what is installed there. Telling that user to install peers
 			// they already have is what sent a consumer down a dead end
-			// (2026-09-09). `ai-init --mcp` now writes the local binary instead
+			// (2026-09-09). `ai-init` now writes the local binary instead
 			// of `npx`, so the fix is to rewrite the config.
 			const fromNpxCache = /[/\\]_npx[/\\]/.test(
 				fileURLToPath(import.meta.url)
@@ -1071,7 +1092,7 @@ switch (command) {
 						'its optional peers resolve there, not in your project, so the server cannot start\n' +
 						`even though this project has them installed (${MCP_PEERS.join(', ')}).\n\n` +
 						'Fix the harness config to invoke the installed binary:\n\n' +
-						'  npx bitboss-ui ai-init --mcp\n\n' +
+						'  npx bitboss-ui ai-init\n\n' +
 						`which writes \`node ${MCP_BIN_PATH} mcp\`. To run it right now:\n\n` +
 						`  node ${MCP_BIN_PATH} mcp\n\n` +
 						`Resolution failed with: ${error.message}`

package/dist/ai/BbBadge.md

@@ -73,6 +73,11 @@ the soft palette from
 `.bb-badge--<name>` in your project stylesheet. Never invent `variant="success"`
 — that name is not built-in and ships no CSS.
 
+`variant="none"` renders the badge with no variant class at all — the base
+tokens stay until you set `--bg` / `--fg` on it. It is the same escape hatch
+`BbButton` has; prefer a registered variant or a one-off `--bg` / `--fg`
+override on a normal variant.
+
 **Invoice status pills + plan tiers**
 
 ```vue
@@ -559,7 +564,7 @@ anchor an overlay directly — no wrapper element, no `defineExpose`:
 			variant="secondary"
 			@click:clear="status = 'Open'"
 		>
-			<BbBadgeButton ref="statusChip">Status: {{ status }}</BbBadgeButton>
+			<BbBadgeButton ref="status-chip">Status: {{ status }}</BbBadgeButton>
 		</BbBadge>
 
 		<!-- The ref resolves to the rendered button element, so it anchors the
@@ -588,7 +593,7 @@ type Status = (typeof options)[number];
 
 const status = ref<Status>('Open');
 const open = ref(false);
-const statusChip = useTemplateRef('statusChip');
+const statusChip = useTemplateRef('status-chip');
 
 const onPick = (option: Status) => {
 	status.value = option;
@@ -847,7 +852,7 @@ The full grammar, the merge rules and the global map are in the
 | `loading` | `boolean \| undefined` | `false` |  | Shows a spinner in place of the leftmost icon, mirroring `BbButton`: it replaces the `icon` glyph or the `prepend:icon` when one is set; when the `append:icon` is the sole icon it replaces that instead (e.g. a select-activator chevron while… |
 | `prepend:icon` | `string \| undefined` |  |  | Icon rendered before the label. |
 | `size` | `keyof Sizes \| undefined` | `"md"` |  | Preset size of the badge. |
-| `variant` | `keyof BadgeVariantRegistry \| undefined` | `"primary"` |  | Visual variant: `primary`, `secondary`, `destructive`, or `outline`. Register more via the vite plugin `badgeVariants` option and style `.bb-badge--<variant>` (set `--bg` / `--fg`). |
+| `variant` | `BadgeVariantType \| undefined` | `"primary"` |  | Visual variant: `primary`, `secondary`, `destructive`, or `outline`. Register more via the vite plugin `badgeVariants` option and style `.bb-badge--<variant>` (set `--bg` / `--fg`). `'none'` renders no variant class — an escape hatch for a … |
 
 ## Passthrough parts and states
 

package/dist/ai/BbBaseCheckboxIcon.md

@@ -157,7 +157,7 @@ from an ancestor — so `--size` set on a wrapper `div` is simply ignored
 ### Restyling with passthrough
 
 `pt` reaches the one part with a class list — or, in the object form, a
-style and attributes. Part: `root` (the drawn glyph). States: `checked`, `indeterminate`, `readonly`, `disabled`, `warnings`, `errors`, `focused`, `focus-visible` — each
+style and attributes. Part: `root` (the drawn glyph). States: `checked`, `indeterminate`, `readonly`, `disabled`, `warnings`, `errors`, `focused`, `focusVisible` — each
 true exactly while the glyph paints it, so they follow its own rules:
 `warnings` is off while `errors` is on.
 
@@ -202,7 +202,7 @@ The full grammar, the merge rules and the global map are in the
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`. States: `checked`, `disabled`, `errors`, `focus-visible`, `focused`, `indeterminate`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`. States: `checked`, `disabled`, `errors`, `focused`, `focusVisible`, `indeterminate`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `checked` | `boolean \| undefined` | `false` |  | Renders the checked state (fills the box and draws the checkmark). |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the glyph (muted fill, not-allowed cursor). Purely visual. |
 | `focused` | `boolean \| undefined` | `false` |  | Whether the paired native input has focus — any focus, mouse included. Paints `--focused`, the hook the `focused` passthrough state aliases (T19); draws nothing by itself — the ring stays on `focusVisible`. |
@@ -231,7 +231,7 @@ States are listed in precedence order: when two are on at once and their entries
 | `warnings` | Component-wide: the toggle shows warnings and no errors. |
 | `errors` | Component-wide: the toggle shows errors — the glyph and the message line turn red. |
 | `focused` | Component-wide: the native input has focus — any focus, mouse included, like the `focused` slot prop. |
-| `focus-visible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
+| `focusVisible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
 
 ## Events
 

package/dist/ai/BbBaseRadioIcon.md

@@ -171,7 +171,7 @@ from an ancestor — so `--size` set on a wrapper `div` is simply ignored
 ### Restyling with passthrough
 
 `pt` reaches the one part with a class list — or, in the object form, a
-style and attributes. Part: `root` (the drawn glyph). States: `checked`, `readonly`, `disabled`, `warnings`, `errors`, `focused`, `focus-visible` — each
+style and attributes. Part: `root` (the drawn glyph). States: `checked`, `readonly`, `disabled`, `warnings`, `errors`, `focused`, `focusVisible` — each
 true exactly while the glyph paints it, so they follow its own rules:
 `warnings` is off while `errors` is on.
 
@@ -217,7 +217,7 @@ The full grammar, the merge rules and the global map are in the
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`. States: `checked`, `disabled`, `errors`, `focus-visible`, `focused`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`. States: `checked`, `disabled`, `errors`, `focused`, `focusVisible`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `checked` | `boolean \| undefined` | `false` |  | Renders the checked state (grows the inner dot). |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the glyph (muted fill, not-allowed cursor). Purely visual. |
 | `focused` | `boolean \| undefined` | `false` |  | Whether the paired native input has focus — any focus, mouse included. Paints `--focused`, the hook the `focused` passthrough state aliases (T19); draws nothing by itself — the ring stays on `focusVisible`. |
@@ -244,7 +244,7 @@ States are listed in precedence order: when two are on at once and their entries
 | `warnings` | Component-wide: the toggle shows warnings and no errors. |
 | `errors` | Component-wide: the toggle shows errors — the glyph and the message line turn red. |
 | `focused` | Component-wide: the native input has focus — any focus, mouse included, like the `focused` slot prop. |
-| `focus-visible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
+| `focusVisible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
 
 ## Events
 

package/dist/ai/BbBaseSwitchIcon.md

@@ -167,7 +167,7 @@ from an ancestor — so `--w` set on a wrapper `div` is simply ignored
 ### Restyling with passthrough
 
 `pt` reaches the one part with a class list — or, in the object form, a
-style and attributes. Part: `root` (the drawn glyph). States: `checked`, `indeterminate`, `readonly`, `disabled`, `warnings`, `errors`, `focused`, `focus-visible` — each
+style and attributes. Part: `root` (the drawn glyph). States: `checked`, `indeterminate`, `readonly`, `disabled`, `warnings`, `errors`, `focused`, `focusVisible` — each
 true exactly while the glyph paints it, so they follow its own rules:
 `warnings` is off while `errors` is on.
 
@@ -213,7 +213,7 @@ The full grammar, the merge rules and the global map are in the
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`. States: `checked`, `disabled`, `errors`, `focus-visible`, `focused`, `indeterminate`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`. States: `checked`, `disabled`, `errors`, `focused`, `focusVisible`, `indeterminate`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `checked` | `boolean \| undefined` | `false` |  | Renders the checked state (fills the track and slides the thumb to the end). |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables the glyph (muted track, not-allowed cursor). Purely visual. |
 | `focused` | `boolean \| undefined` | `false` |  | Whether the paired native input has focus — any focus, mouse included. Paints `--focused`, the hook the `focused` passthrough state aliases (T19); draws nothing by itself — the ring stays on `focusVisible`. |
@@ -242,7 +242,7 @@ States are listed in precedence order: when two are on at once and their entries
 | `warnings` | Component-wide: the toggle shows warnings and no errors. |
 | `errors` | Component-wide: the toggle shows errors — the glyph and the message line turn red. |
 | `focused` | Component-wide: the native input has focus — any focus, mouse included, like the `focused` slot prop. |
-| `focus-visible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
+| `focusVisible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
 
 ## Events
 

package/dist/ai/BbBreadcrumbs.md

@@ -707,6 +707,9 @@ States are listed in precedence order: when two are on at once and their entries
 - `item:append` — scope: `BbBreadcrumbsItemSlotProps` — Content rendered after **every** breadcrumb item's link/button. Generic fallback below a per-item `<key>:append` slot and above the item's `append:icon`.
 - `item:prepend` — scope: `BbBreadcrumbsItemSlotProps` — Content rendered before **every** breadcrumb item's link/button, in the leading edge region. Generic fallback: a per-item `<key>:prepend` slot takes precedence, and the item's `prepend:icon` is used when neither slot is present.
 - `prepend` — scope: `BbBreadcrumbsEdgeSlotProps` — Content rendered before the breadcrumb list, in a dedicated prepend region.
+- `#<key>` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — One crumb's label, by its `key` through `slotKey`; falls back to `item.text`. A crumb folded into the overflow menu follows BbDropdown's slot rules instead.
+- `#<key>:prepend` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — The glyph before one crumb's label; beats `item:prepend`, which beats its `prepend:icon`.
+- `#<key>:append` (named from data) — scope: `BbBreadcrumbsItemSlotProps` — The glyph after one crumb's label; beats `item:append`, which beats its `append:icon`.
 
 ## Component tree
 
@@ -722,7 +725,7 @@ States are listed in precedence order: when two are on at once and their entries
   - `BbDropdown` _(public — [contract](./BbDropdown.md))_ — its own pt parts (`BbDropdown`): `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `div.bb-dropdown__header`, `list` → `span.bb-dropdown__items-container`, `footer` → `div.bb-dropdown__footer`; documented CSS variables: `--menu-inset`; also mounts `CommonPopover`, `DropdownPipelineResolver`
     - `BbDropdownList` _(internal — not importable, reach it through `BbDropdown`)_ — also mounts `BbBaseButton`, `BbIcon`, `CommonPopover`, `BbDropdownList`
       - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear-button`; documented CSS variables: `--bg`, `--fg`, `--border-width`, `--ring`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--font-size`, `--icon-size`, `--gap`, `--padding-inline`, `--clear-size`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
-    - `AdaptiveDropdown` _(internal — not importable, reach it through `BbDropdown`)_ — hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', sheet: 'root' }` (ours → theirs); also mounts `BbSmoothHeight`, `BbDropdownList`
+    - `AdaptiveDropdown` _(internal — not importable, reach it through `BbDropdown`)_ — hands `BbOffCanvas` the pt map `{ header: 'header', footer: 'footer', panel: 'root', sheet: 'root' }` (ours → theirs); also mounts `BbSmoothHeight`, `BbDropdownList`
       - `BbOffCanvas` _(public — [contract](./BbOffCanvas.md))_ — its own pt parts (`BbOffCanvas`): `header` → `div.bb-offcanvas__header`, `title` → `span.bb-offcanvas__title`, `description` → `p.bb-offcanvas__description`, `close` → `CloseButton`, `content` → `div.bb-offcanvas__body`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--close-size`
         - `CloseButton` _(internal — not importable, reach it through `BbOffCanvas`)_ — documented CSS variables: `--size`, `--p`
       - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__content`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring`, `--bw`, `--fg-hover`, `--border-hover`, `--fg-pressed`, `--border-pressed`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--opacity-disabled`, `--elev-tier`, `--elev`; also mounts `BbIcon`, `BbBaseButton`, `BbSpinner`

package/dist/ai/BbCalendar.md

@@ -376,6 +376,77 @@ const summary = computed(() => {
 </script>
 ```
 
+### Decorating days
+
+Four slots decorate the day grid. Each receives the day's state: `label` (the
+day number), `selected`, `outside` (a day of the previous or next month),
+`first` / `middle` / `last` (range edges) and `item` (the day as a dayjs
+object).
+
+| Slot                   | Renders                                     |
+| ---------------------- | ------------------------------------------- |
+| `#day`                 | every day's label, **replacing** the number |
+| `#append:day`          | under every day (dots, prices, badges)      |
+| `#<YYYY_MM_DD>`        | one date's label, e.g. `#2026_12_25`        |
+| `#append:<YYYY_MM_DD>` | under one date, e.g. `#append:2026_12_25`   |
+
+A date's slot name is its local `YYYY-MM-DD` with `_` for `-`, and it wins over
+the matching every-day slot for that date. Per-date slots suit a few fixed
+dates (holidays, a launch day); for data-driven marks — events from an API —
+use `#append:day` and look the day up from `item`. The per-date slots cover the
+day grid only, not the month and year panels. Keep decorations small: they
+render in every visible cell.
+
+**Holiday hours on specific dates**
+
+```vue
+<template>
+	<div class="grid w-fit gap-3 rounded-(--bb-radius) border p-4">
+		<div>
+			<p class="m-0 text-sm font-medium">Pickup day</p>
+			<p class="m-0 text-xs text-(--bb-text-muted)">
+				The shop keeps holiday hours over Christmas.
+			</p>
+		</div>
+		<BbCalendar
+			v-model="pickup"
+			aria-label="Pickup day"
+			floating
+			:selectable="isOpen"
+		>
+			<!-- One slot per date: its `YYYY-MM-DD` with `_` for `-`. -->
+			<template #append:2026_12_24>
+				<span class="holiday-note">Half day</span>
+			</template>
+			<template #append:2026_12_25>
+				<span class="holiday-note">Closed</span>
+			</template>
+			<template #append:2026_12_26>
+				<span class="holiday-note">Closed</span>
+			</template>
+		</BbCalendar>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { BbCalendar } from 'bitboss-ui';
+
+const pickup = ref<string | null>('2026-12-22');
+
+const closed = new Set(['2026-12-25', '2026-12-26']);
+const isOpen = (date: string) => !closed.has(date);
+</script>
+
+<style scoped>
+.holiday-note {
+	color: var(--bb-text-muted);
+	font-size: 0.625rem;
+	line-height: 1;
+}
+</style>
+```
+
 ### Keyboard and accessibility
 
 The calendar is an ordinary control in the tab order: **one tab stop** lands
@@ -399,20 +470,20 @@ and attributes — optionally only while a state is on. Parts: `root` (the
 calendar's box, where a consumer `class` lands too; it carries the sizing
 tokens, so `pt:root="[--pad-x:2px]"` tightens the padding and the grid width
 follows), `header` (the navigation bar), `arrow` (the previous / next
-buttons), `month` and `year` (the heading buttons), `column-header` (each
-weekday letter), `day` (one whole day cell) and `day-button` (the button
-inside it), `month-item` and `year-item` (one button of the month / year
+buttons), `month` and `year` (the heading buttons), `columnHeader` (each
+weekday letter), `day` (one whole day cell) and `dayButton` (the button
+inside it), `monthItem` and `yearItem` (one button of the month / year
 panel).
 
 States: `root` is `disabled` while the calendar is; `arrow` is `disabled` at a
 `min` / `max` bound; `month` and `year` are `active` while their panel is
-open. The cells resolve per node — on `day` and `day-button`: `selected`,
+open. The cells resolve per node — on `day` and `dayButton`: `selected`,
 `disabled`, `today`, `outside` (a day of the previous or next month),
-`range-start` / `range-end` / `in-range` (a committed range) and `highlighted`
+`rangeStart` / `rangeEnd` / `inRange` (a committed range) and `highlighted`
 (the keyboard cursor). The panel items carry the same set without `today` and
 `outside`.
 
-`day` is the whole cell and `day-button` the rounded mark inside it: a
+`day` is the whole cell and `dayButton` the rounded mark inside it: a
 background on `pt:day` paints the full cell square, so restyle the mark on
 `pt:day-button`. The time rail is not a part.
 
@@ -451,7 +522,7 @@ the page is `BbDatePicker`.
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `arrow`, `column-header`, `day`, `day-button`, `header`, `month`, `month-item`, `root`, `year`, `year-item`. States: `active`, `disabled`, `highlighted`, `in-range`, `outside`, `range-end`, `range-start`, `selected`, `today`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `arrow`, `columnHeader`, `day`, `dayButton`, `header`, `month`, `monthItem`, `root`, `year`, `yearItem`. States: `active`, `disabled`, `highlighted`, `inRange`, `outside`, `rangeEnd`, `rangeStart`, `selected`, `today`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `activeSegment` | `BbCalendarSegment \| undefined` |  |  | Which end the time rail edits in range + `type="datetime"` (`v-model:active-segment`). Standalone use manages this internally; an embedding host (the date input) drives it from its focused field. Ignored outside range + datetime. |
 | `ampm` | `boolean \| undefined` | `false` |  | 12-hour display with an AM/PM column (requires `type="datetime"`); emits stay 24h. |
 | `disabled` | `boolean \| undefined` | `false` |  | Disables every cell, the navigation and the time rail. |
@@ -481,22 +552,22 @@ the page is `BbDatePicker`.
 | `arrow` | The previous / next buttons — a broadcast. |
 | `month` | The month heading button; it opens the month panel. |
 | `year` | The year heading button; it opens the year panel. |
-| `column-header` | Each weekday letter above the grid — a broadcast. |
-| `day` | One whole day cell — a broadcast resolved per day. A background here paints the full cell square; restyle the round mark on `day-button`. |
-| `day-button` | The button inside a day cell — the mark that shows selection. A broadcast resolved per day. |
-| `month-item` | One month button of the month panel (the home grid of `type="month"`) — a broadcast resolved per month. |
-| `year-item` | One year button of the year list — a broadcast resolved per year. |
+| `columnHeader` | Each weekday letter above the grid — a broadcast. |
+| `day` | One whole day cell — a broadcast resolved per day. A background here paints the full cell square; restyle the round mark on `dayButton`. |
+| `dayButton` | The button inside a day cell — the mark that shows selection. A broadcast resolved per day. |
+| `monthItem` | One month button of the month panel (the home grid of `type="month"`) — a broadcast resolved per month. |
+| `yearItem` | One year button of the year list — a broadcast resolved per year. |
 
 States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
 
 | State | When it is on |
 | --- | --- |
-| `outside` | Per node, on `day` / `day-button`: a day of the previous or next month, shown to fill the grid. |
-| `today` | Per node, on `day` / `day-button`: today. |
-| `in-range` | Per node, on the cells (`day`, `day-button`, `month-item`, `year-item`): inside a committed range, between its ends. |
+| `outside` | Per node, on `day` / `dayButton`: a day of the previous or next month, shown to fill the grid. |
+| `today` | Per node, on `day` / `dayButton`: today. |
+| `inRange` | Per node, on the cells (`day`, `dayButton`, `monthItem`, `yearItem`): inside a committed range, between its ends. |
 | `selected` | Per node, on the cells: a chosen day, month or year. |
-| `range-start` | Per node, on the cells: a committed range's first day, month or year. |
-| `range-end` | Per node, on the cells: a committed range's last day, month or year. |
+| `rangeStart` | Per node, on the cells: a committed range's first day, month or year. |
+| `rangeEnd` | Per node, on the cells: a committed range's last day, month or year. |
 | `disabled` | Component-wide while the calendar is `disabled`. Also per node: on the cells, one outside `min` / `max` or refused by `selectable`; on `arrow`, at a bound or while the month / year panel is open. |
 | `active` | Per node, on `month` / `year`: its panel is open. |
 | `highlighted` | Per node, on the cells: the keyboard cursor. |
@@ -513,6 +584,8 @@ States are listed in precedence order: when two are on at once and their entries
 
 - `append:day` — scope: `BbCalendarDaySlotProps` — Appends content below each calendar day.
 - `day` — scope: `BbCalendarDaySlotProps` — Replaces the day button label inside each calendar day.
+- `#<YYYY_MM_DD>` (named from data) — scope: `BbCalendarDaySlotProps` — One date's button label (e.g. `#2024_03_15`: the local `YYYY-MM-DD` through `slotKey`); beats `day`. Day grid only.
+- `#append:<YYYY_MM_DD>` (named from data) — scope: `BbCalendarDaySlotProps` — Content under one date's cell; beats `append:day`.
 
 ## CSS custom properties
 
@@ -537,7 +610,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **CSS custom properties** listed on a node are declared on THAT node's root and read by elements inside it. Set one on that node's root or on the element inside it that reads it — the pt part that lands there is how you reach it (`pt:box="[--border-color:…]"` on a text input) — never on `BbCalendar`'s root, where the node's own declaration masks it (design-tokens guide, _Overriding one from a consumer app_, rule 0).
 - Listed nodes are the ones `BbCalendar`'s API reaches or that declare a documented CSS variable; the rest fold into "also mounts". The complete tree, repeats and undocumented locals included, is the `tree` field of this component in `components.json`.
 
-- `BbCalendar` _(this component)_ — its own template binds: `header` → `div.bb-calendar__controls`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-calendar__date`, `day-button` → `button.bb-calendar__date-button`
+- `BbCalendar` _(this component)_ — its own template binds: `header` → `div.bb-calendar__controls`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-calendar__date`, `dayButton` → `button.bb-calendar__date-button`
   - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
   - `CommonTimeSelector` _(internal — not importable, reach it through `BbCalendar`)_ — documented CSS variables: `--time-mark`; also mounts `BbBaseButton`
   - Also mounts `ScaleFade`, `Slide`, `CalendarMonthPanel`, `CalendarYearPanel`

package/dist/ai/BbCheckbox.md

@@ -670,7 +670,7 @@ map are in the [passthrough guide](./guides/passthrough.md).
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `description`, `hint`, `icon`, `label`, `message`, `root`. States: `checked`, `disabled`, `errors`, `focus-visible`, `focused`, `indeterminate`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `description`, `hint`, `icon`, `label`, `message`, `root`. States: `checked`, `disabled`, `errors`, `focused`, `focusVisible`, `indeterminate`, `readonly`, `warnings`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
 | `checked` | `boolean \| undefined` | `undefined` |  | Defines the input as checked. |
 | `description` | `string \| undefined` |  |  | Descriptive text displayed below the label and above the input. Unlike the hint it is always visible, and it is linked to the input via `aria-describedby` (after any `errors` / `warnings`, before the `hint`). |
@@ -721,7 +721,7 @@ States are listed in precedence order: when two are on at once and their entries
 | `warnings` | Component-wide: the toggle shows warnings and no errors. |
 | `errors` | Component-wide: the toggle shows errors — the glyph and the message line turn red. |
 | `focused` | Component-wide: the native input has focus — any focus, mouse included, like the `focused` slot prop. |
-| `focus-visible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
+| `focusVisible` | Component-wide: that focus is keyboard-visible — where a focus ring belongs. |
 
 ## Events