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

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

package/dist/ai/BbColorInput.md

@@ -505,7 +505,7 @@ the `BbTextInput` guide.
 
 `pt` reaches a named part of the control with a class list — or, in the
 object form, a style and attributes — optionally only while a state is on.
-Parts: `root` (the container), `label`, `description`, `message` (the errors / warnings region — one node each, only one ever shows), `hint` (the helper line — shown on focus, or always with `persistent-hint`), `box` (the bordered field box), `input` (the native control), `icon` (`prepend:icon` + `append:icon` — a broadcast; the state glyphs are chrome), `spinner` (the spinner shown while `loading`), `prefix`, `suffix`, `clear` (the ✕ that empties the field). Plus `indicator` (the colour dot that opens the palette), `panel` (the palette box — the popover's painted bubble on desktop, the box inside the sheet on a phone), `sheet` (the bottom sheet the color palette opens in on a phone — no node on desktop) and `swatch` (one palette swatch, after the `swatches` prop — a broadcast).
+Parts: `root` (the container), `label`, `description`, `message` (the errors / warnings region — one node each, only one ever shows), `hint` (the helper line — shown on focus, or always with `persistent-hint`), `box` (the bordered field box), `input` (the native control), `icon` (`prepend:icon` + `append:icon` — a broadcast; the state glyphs are chrome), `spinner` (the spinner shown while `loading`), `prefix`, `suffix`, `clear` (the ✕ that empties the field). Plus `indicator` (the colour dot that opens the palette), `panel` (the palette surface — the popover's painted bubble on desktop, the sheet itself on a phone), `sheet` (the bottom sheet the color palette opens in on a phone — no node on desktop) and `swatch` (one palette swatch, after the `swatches` prop — a broadcast).
 States: `errors`, `warnings` (never beside errors), `loading`, `disabled`, `readonly`, `has-value` (written `pt:box:has-value`), on every part; plus `selected` on `swatch` only — the swatch matching the value (`pt:swatch:selected`). A name outside that list is a type error and an
 ESLint error.
 
@@ -718,7 +718,7 @@ of it. The full grammar, the merge rules and the global map are in the
 | `suffix` | The `#suffix` slot's wrapper, inside the box after the input. |
 | `clear` | The ✕ that empties this control (`clearable`) — one node, never a chip's own ✕. |
 | `indicator` | The colour dot in the box that opens the palette. |
-| `panel` | The palette box — the popover's painted bubble on desktop, the box inside the sheet on a phone. |
+| `panel` | The palette surface — the popover's painted bubble on desktop, the sheet itself on a phone. |
 | `sheet` | The bottom sheet the palette opens in on a phone — no node on desktop. |
 | `swatch` | One palette swatch (after the `swatches` prop) — a broadcast resolved per swatch. |
 
@@ -796,7 +796,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - `BbColorInput` _(this component)_ — its own template binds: `controlAttrs` → `input.bb-color-input__input`, `input` → `input.bb-color-input__input`, `indicator` → `button.bb-color-input__indicator`, `suffix` → `span.bb-field-input__suffix`; hands `BbColorPalette` the pt map `{ panel: 'panel', sheet: 'sheet', swatch: 'swatch' }` (ours → theirs)
   - `CommonField` _(internal — not importable, reach it through `BbColorInput`)_ — `BbColorInput`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint-text`, `message` → `div.bb-field__errors`, `message` → `div.bb-field__warnings`
   - `CommonFieldInput` _(internal — not importable, reach it through `BbColorInput`)_ — `BbColorInput`'s pt parts land here: `box` → `span.bb-field-input__box`, `prefix` → `span.bb-field-input__prefix`, `icon` → `BbIcon`, `clear` → `ClearableButton`, `spinner` → `BbSpinner`, `suffix` → `span.bb-field-input__suffix`; documented CSS variables: `--bg`, `--bg-hover`, `--bg-focus`, `--bg-disabled`, `--border-color`, `--border-focus`, `--ring-size`, `--ring-color`, `--elev`, `--frost`, `--inside-label-clearance`; also mounts `ErrorIcon`, `WarningIcon`, `ClearableButton`, `BbIcon`, `BbSpinner`
-  - `BbColorPalette` _(public — [contract](./BbColorPalette.md))_ — its own pt parts (`BbColorPalette`): `swatch` → `button.bb-color-palette__swatch`, `panel` → `div`, `panel` → `CommonPopover`; hands `BbOffCanvas` the pt map `{ sheet: 'root' }` (ours → theirs); also mounts `CommonPopover`
+  - `BbColorPalette` _(public — [contract](./BbColorPalette.md))_ — its own pt parts (`BbColorPalette`): `swatch` → `button.bb-color-palette__swatch`, `panel` → `div`, `panel` → `CommonPopover`; hands `BbOffCanvas` the pt map `{ panel: 'root', sheet: 'root' }` (ours → theirs); also mounts `CommonPopover`
     - `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`
 

package/dist/ai/BbColorPalette.md

@@ -15,6 +15,7 @@
 | pt part | Lands on | In |
 | --- | --- | --- |
 | `pt:panel` | the root of `CommonPopover` | `CommonPopover` _(internal)_ |
+| `pt:panel` | `pt:root` of `BbOffCanvas` | `BbOffCanvas` ([contract](./BbOffCanvas.md)) |
 | `pt:sheet` | `pt:root` of `BbOffCanvas` | `BbOffCanvas` ([contract](./BbOffCanvas.md)) |
 
 ## Usage & Guidelines
@@ -557,11 +558,11 @@ styling (a caret, a highlight). Two props gate interaction:
 
 `pt` reaches a named part with a class list — or, in the object form, a
 style and attributes — optionally only while a state is on. Parts: `root`
-(the floating element — the bottom sheet on a phone), `panel` (the palette box you
-see: the popover's painted bubble on desktop, the box inside the sheet on a
-phone — canvas, sliders, swatches; `pt:panel="px-1"`
-tightens its padding), `sheet` (the bottom sheet on a phone only, applied
-after `root`) and `swatch` (one swatch, named after the `swatches` prop — a
+(the floating element — an invisible positioning wrapper, no node on a
+phone), `panel` (the palette surface you see: the popover's painted bubble on
+desktop, the sheet itself on a phone — canvas, sliders, swatches; `pt:panel="px-1"`
+tightens the bubble's padding), `sheet` (the bottom sheet on a phone only, applied
+after `panel`) and `swatch` (one swatch, named after the `swatches` prop — a
 broadcast). States: `open`, and
 `selected` per swatch (the one matching the value). The canvas and the sliders
 are not parts.
@@ -762,9 +763,9 @@ The full grammar, the merge rules and the global map are in the
 
 | Part | What it is |
 | --- | --- |
-| `root` | The floating element — on a phone, the bottom sheet (as on `BbPopover`). |
-| `panel` | The picker box you see — the popover's painted bubble on desktop, the box inside the sheet on a phone — holding the canvas, the sliders and the swatches. The canvas and the sliders are not parts. |
-| `sheet` | The bottom sheet on a phone only (the `BbOffCanvas` root). Applied after `root`, so it wins a conflict there. |
+| `root` | The floating element — an invisible positioning wrapper; a `class` on the component lands here. No node on the phone sheet: style what you see with `panel`. |
+| `panel` | The picker surface you see — the popover's painted bubble on desktop, the sheet itself on a phone — holding the canvas, the sliders and the swatches. The canvas and the sliders are not parts. |
+| `sheet` | The bottom sheet on a phone only (the `BbOffCanvas` root). Applied after `panel`, so it wins a conflict there. |
 | `swatch` | One swatch (after the `swatches` prop) — a broadcast resolved per swatch. |
 
 States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
@@ -795,7 +796,7 @@ States are listed in precedence order: when two are on at once and their entries
 - **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 `BbColorPalette`'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 `BbColorPalette`'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`.
 
-- `BbColorPalette` _(this component)_ — its own template binds: `swatch` → `button.bb-color-palette__swatch`, `panel` → `div`, `panel` → `CommonPopover`; hands `BbOffCanvas` the pt map `{ sheet: 'root' }` (ours → theirs)
+- `BbColorPalette` _(this component)_ — its own template binds: `swatch` → `button.bb-color-palette__swatch`, `panel` → `div`, `panel` → `CommonPopover`; hands `BbOffCanvas` the pt map `{ panel: 'root', sheet: 'root' }` (ours → theirs)
   - `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`
   - Also mounts `CommonPopover`

package/dist/ai/BbDatePicker.md

@@ -15,6 +15,7 @@
 | pt part | Lands on | In |
 | --- | --- | --- |
 | `pt:panel` | the root of `CommonPopover` | `CommonPopover` _(internal)_ |
+| `pt:panel` | `pt:root` of `BbOffCanvas` | `BbOffCanvas` ([contract](./BbOffCanvas.md)) |
 | `pt:sheet` | `pt:root` of `BbOffCanvas` | `BbOffCanvas` ([contract](./BbOffCanvas.md)) |
 
 ## Usage & Guidelines
@@ -202,6 +203,31 @@ const time = ref<string | null>(null);
 </template>
 ```
 
+### Decorating days
+
+The picker passes its day slots straight to the calendar inside it, so the four
+day-grid slots work here unchanged:
+
+- `#day` replaces every day's number and `#append:day` adds under every day
+  (event dots, prices). Both receive `label`, `selected`, `outside`,
+  `first` / `middle` / `last` and `item` (the day as a dayjs object).
+- `#<YYYY_MM_DD>` and `#append:<YYYY_MM_DD>` do the same for one date, e.g.
+  `#append:2026_12_25`: its local `YYYY-MM-DD` with `_` for `-`. A date's slot
+  wins over the every-day one.
+
+```vue
+<BbDatePicker v-model="pickup">
+	<template #activator="{ props, value }">
+		<BbButton v-bind="props" variant="outline">{{ value ?? 'Pickup day' }}</BbButton>
+	</template>
+	<template #append:2026_12_25><span class="text-[10px]">Closed</span></template>
+</BbDatePicker>
+```
+
+Use per-date slots for a few fixed dates; mark data-driven days through
+`#append:day` and a lookup on `item`. The [BbCalendar](./BbCalendar.md) guide
+has a worked example.
+
 ### Adaptive and positioning
 
 On mobile the calendar opens in a bottom off-canvas sheet instead of a floating
@@ -267,11 +293,11 @@ into, `BbDatePickerInput` when there is.
 
 `pt` reaches a named part with a class list — or, in the object form, a
 style and attributes — optionally only while a state is on. Parts: `root`
-(the floating element — the bottom sheet on a phone), `panel` (the calendar box you
-see: the popover's painted bubble on desktop, the box inside the sheet on a
-phone — it also carries the sizing tokens, so
+(the floating element — an invisible positioning wrapper, no node on a
+phone), `panel` (the calendar surface you see: the popover's painted bubble on
+desktop, the sheet itself on a phone — it also carries the sizing tokens, so
 `pt:panel="[--pad-x:2px]"` tightens the padding and the grid width follows), `sheet` (the
-bottom sheet on a phone only, applied after `root`), `header` (the
+bottom sheet on a phone only, applied after `panel`), `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
@@ -412,7 +438,7 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 
 | Part | What it is |
 | --- | --- |
-| `root` | The floating element — on a phone, the bottom sheet (as on `BbPopover`). |
+| `root` | The floating element — an invisible positioning wrapper; a `class` on the component lands here. No node on the phone sheet: style what you see with `panel`. |
 | `header` | The navigation bar: the previous / next arrows and the month / year headings. |
 | `arrow` | The previous / next buttons — a broadcast. |
 | `month` | The month heading button; it opens the month panel. |
@@ -422,8 +448,8 @@ and digit typeahead; the time rail exposes labelled columns. Always pass a
 | `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. |
-| `panel` | The calendar box you see — the popover's painted bubble on desktop, the box inside the sheet on a phone. It carries the calendar's sizing tokens: `pt:panel="[--cell:36px]"` widens the calendar, `pt:panel="[--pad-x:2px]"` tightens it. |
-| `sheet` | The bottom sheet on a phone only (the `BbOffCanvas` root). Applied after `root`, so it wins a conflict there. |
+| `panel` | The calendar surface you see — the popover's painted bubble on desktop, the sheet itself on a phone. It carries the sizing tokens: `pt:panel="[--cell:36px]"` widens the calendar, `[--pad-x:2px]` tightens. |
+| `sheet` | The bottom sheet on a phone only (the `BbOffCanvas` root). Applied after `panel`, so it wins a conflict there. |
 
 States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
 
@@ -457,6 +483,8 @@ States are listed in precedence order: when two are on at once and their entries
 - `activator` — scope: `BbDatePickerActivatorSlotProps` — Custom activator element. Apply `v-bind="props"` to your trigger.
 - `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
 
@@ -470,9 +498,20 @@ Set these on the element, or on a class you put on it, to retune this component
 | `--nav-button-h` | `.bb-date-picker__panel` | `24px` |  |
 | `--day-slot-allowance` | `.bb-date-picker__panel` | `0px` | Allowance for the day slot append area - needed for the slot to be visible |
 | `--unit-row` | `.bb-date-picker__panel` | `calc(var(--cell) * 1.25)` | Row pitch for the coarse grids (month/year), where a "row" is one of four month rows rather than a week. Roomier than --cell because twelve months in a 4×3 grid have space the 6×7 day grid does not. |
-| `--sheet-cell` | `.bb-date-picker__panel--sheet` | `40px` | Declared on the container so the time rail (the grid's sibling inside the calendar) can align its wheels to the same column grid. |
-| `--cell` | `.bb-date-picker__panel--sheet` | `var(--sheet-cell)` | One touch scale for the whole sheet: 40px day cells (36px marks), and a nav row to match — on the panel, where the tokens live. |
-| `--nav-button-h` | `.bb-date-picker__panel--sheet` | `40px` |  |
+| `--sheet-cell` | `.bb-date-picker-offcanvas` | `40px` |  |
+| `--cell` | `.bb-date-picker-offcanvas` | `var(--sheet-cell)` |  |
+| `--pad-x` | `.bb-date-picker-offcanvas` | `6px` |  |
+| `--pad-y` | `.bb-date-picker-offcanvas` | `8px` |  |
+| `--nav-button-h` | `.bb-date-picker-offcanvas` | `40px` |  |
+| `--day-slot-allowance` | `.bb-date-picker-offcanvas` | `0px` |  |
+| `--unit-row` | `.bb-date-picker-offcanvas` | `calc(var(--cell) * 1.25)` |  |
+| `--sheet-cell` | `.bb-date-picker__panel--sheet` | `inherit` |  |
+| `--cell` | `.bb-date-picker__panel--sheet` | `inherit` |  |
+| `--pad-x` | `.bb-date-picker__panel--sheet` | `inherit` |  |
+| `--pad-y` | `.bb-date-picker__panel--sheet` | `inherit` |  |
+| `--nav-button-h` | `.bb-date-picker__panel--sheet` | `inherit` |  |
+| `--day-slot-allowance` | `.bb-date-picker__panel--sheet` | `inherit` |  |
+| `--unit-row` | `.bb-date-picker__panel--sheet` | `inherit` |  |
 
 ## Component tree
 
@@ -483,7 +522,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 `BbDatePicker`'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 `BbDatePicker`'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`.
 
-- `BbDatePicker` _(this component)_ — its own template binds: `panel` → `div`, `panel` → `CommonPopover`; hands `BbCalendar` the pt map ` passthrough.forward(DATE_PICKER_CALENDAR_PARTS, BB_CALENDAR_PT.states) ` (ours → theirs); hands `BbOffCanvas` the pt map `{ sheet: 'root' }` (ours → theirs)
+- `BbDatePicker` _(this component)_ — its own template binds: `panel` → `div`, `panel` → `CommonPopover`; hands `BbCalendar` the pt map ` passthrough.forward(DATE_PICKER_CALENDAR_PARTS, BB_CALENDAR_PT.states) ` (ours → theirs); hands `BbOffCanvas` the pt map `{ panel: 'root', sheet: 'root' }` (ours → theirs)
   - `BbCalendar` _(public — [contract](./BbCalendar.md))_ — its own pt parts (`BbCalendar`): `header` → `div.bb-calendar__controls`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-calendar__date`, `day-button` → `button.bb-calendar__date-button`; documented CSS variables: `--cell`, `--day-slot-allowance`, `--unit-row`; also mounts `ScaleFade`, `Slide`, `CalendarMonthPanel`, `CalendarYearPanel`
     - `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`