bitboss-ui 3.0.0-alpha.5 → 3.0.0-alpha.9

package/README.md

@@ -6,11 +6,29 @@ 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`, and **`index.css`**) plus 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-docs.vercel.app/).
 
 ### Styles
 
 - **Global stylesheet** — import `bitboss-ui/styles.css` once. It bundles design tokens, base rules, and styles for all exported components (built from the library’s PostCSS/Tailwind pipeline).
+- **Optional reset** — `bitboss-ui/reset.css`, only if your app has no reset of its own. Import it _before_ `styles.css` (or let the build plugin inject it with `resetCss: true`).
+
+### TypeScript: use `vue-tsc` 3
+
+Use **`vue-tsc` 3 or newer**. Under `vue-tsc` 2 the template type-checker
+silently checks **nothing** about the props of the nine components declared with
+`generic="T"` — `BbSelect`, `BbSelectPopover`, `BbTable`, `BbTabs`,
+`BbTabsRoot`, `BbTree`, `BbRadioGroup`, `BbCheckboxGroup`, `BbSwitchGroup` —
+because they emit as generic functions rather than `DefineComponent<…>`, a shape
+Vue Language Tools 2 cannot read props out of.
+
+The trap is that the failure is partial and invisible: unknown-**component**
+checking still fires and non-generic components still reject bad props, so the
+gate looks like it is working. A real consumer shipped
+`<BbRadioGroup label="…">` (the prop is `legend`) through six release slices on
+`vue-tsc@^2.2.12` with a green `--noEmit`.
+
+Full detail: `ai/guides/installation-and-plugin-setup.md`.
 
 ### TypeScript: icons
 
@@ -71,13 +89,14 @@ For most **Base\*** and **Bb\*** components, the package exports matching **prop
 
 The same knowledge base the npm package ships is served publicly over a CDN, so
 an agent can read it before anything is installed. `@alpha` tracks the latest
-v3 prerelease; pin an exact version (`bitboss-ui@3.0.0-alpha.4`) for stable
-links.
+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) (~74 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) (~17 KB) — link index into every document.
+- [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) (~2.9 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
+- [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.
 
 Already installed? Prefer the local copy under `node_modules/bitboss-ui/dist/ai/`,
 run `npx bitboss-ui ai-init` to write agent pointers, and
@@ -204,9 +223,17 @@ can **query** the knowledge base (search components, read a contract, validate
 markup) instead of reading files blind:
 
 ```bash
+npm i -D @modelcontextprotocol/sdk zod
 npx bitboss-ui ai-init --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 agent harness launches the server itself (`npx bitboss-ui@<installed version> mcp`,
 pinned so npx can never fall back to fetching a different version from the registry) on demand —
 you never run it by hand. `--mcp` merges the server entry into each harness's
@@ -333,13 +360,16 @@ A standard `llms.txt` discovery file is also published at:
 
 ### Package exports
 
-```ts
-// catalogue entry
-import 'bitboss-ui/ai';
-// or resolve concrete files:
-// bitboss-ui/ai/components.json
-// bitboss-ui/ai/guides/ai-router.md
-```
+These are **resolution paths, not importable modules** — they resolve to
+Markdown and JSON, so a side-effect `import` of them neither type-checks nor
+bundles. Use them with `import.meta.resolve` / `require.resolve`, or read the
+files directly:
+
+| Subpath                             | Resolves to                    |
+| ----------------------------------- | ------------------------------ |
+| `bitboss-ui/ai`                     | `dist/ai/index.md` (catalogue) |
+| `bitboss-ui/ai/components.json`     | `dist/ai/components.json`      |
+| `bitboss-ui/ai/guides/ai-router.md` | `dist/ai/guides/ai-router.md`  |
 
 Agents can also read paths under `node_modules/bitboss-ui/dist/ai/` directly.
 
@@ -376,7 +406,7 @@ MIT — see [`LICENSE`](LICENSE).
 
 The source repository is private while v3 is in development, so there is no
 public issue tracker yet. **Report bugs by email to
-[dev@bitboss.it](mailto:dev@bitboss.it)** — that address is the `bugs` contact
+[hey@bitboss.it](mailto:hey@bitboss.it)** — that address is the `bugs` contact
 in `package.json`, so `npm bugs bitboss-ui` opens it too.
 
 To make a report actionable, include:

package/bin/bitboss-ui-mcp.mjs

@@ -7,8 +7,22 @@
  *
  * Built on `@modelcontextprotocol/sdk` (McpServer over the stdio transport);
  * the SDK owns JSON-RPC framing, capability handshake, and protocol-version
- * negotiation. Tool input schemas are declared as zod shapes (zod ships with
- * the SDK); the SDK renders them to the JSON Schema advertised by tools/list.
+ * negotiation. Tool input schemas are declared as zod shapes; the SDK renders
+ * them to the JSON Schema advertised by tools/list.
+ *
+ * BOTH imports below are OPTIONAL PEERS, not dependencies — together ~12 MB,
+ * more than every runtime dependency of the component library combined, and
+ * loaded by nothing else. `bin/bitboss-ui.mjs` catches the resolution failure
+ * and names them; `missingMcpPeers()` warns at registration time.
+ *
+ * `zod`'s declared range is `^3.25 || ^4.0` — copied verbatim from the SDK's
+ * own dependency range, NOT invented. Do not "simplify" it to `>=` or to a
+ * single major: the schemas built here are validated by the SDK's OWN copy of
+ * zod, so a consumer hoisting a different MAJOR fails the SDK's brand checks
+ * while npm stays silent (both ranges are independently satisfied). Mirroring
+ * the range means it moves when the SDK's does. Everything used here
+ * (`z.string`, `z.enum`, `z.number`, `.describe`, `.int`, `.min`, `.optional`)
+ * 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`.

package/bin/bitboss-ui.mjs

@@ -13,7 +13,6 @@
  *             - .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.
- *   locale    Generate a custom locale blueprint (.locale.ts)
  *   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`/
@@ -35,11 +34,14 @@ import {
 	statSync,
 	writeFileSync,
 } from 'node:fs';
-import { createRequire } from 'node:module';
+import { findHandRollHints } from '../scripts/lib/hand-roll-hints.mjs';
 import { dirname, isAbsolute, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseArgs } from 'node:util';
-import { ensureMcpConfigs } from '../scripts/lib/mcp-config.mjs';
+import {
+	ensureMcpConfigs,
+	missingMcpPeers,
+} from '../scripts/lib/mcp-config.mjs';
 import {
 	loadManifest,
 	validateMarkdown,
@@ -238,6 +240,21 @@ function aiInit({ mcp = false } = {}) {
 				action: result.action,
 			});
 		}
+
+		// 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.
+		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.'
+			);
+		}
 	}
 
 	console.log(`[bitboss-ui] ai-init complete (library v${version})`);
@@ -266,112 +283,6 @@ function aiInit({ mcp = false } = {}) {
 	}
 }
 
-/**
- * Serialize the blueprint dictionary as a readable TS object literal
- * (single-quoted, tab-indented, matching the library's own locale files).
- */
-function localeObjectLiteral(dictionary) {
-	const quote = (s) =>
-		`'${String(s).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
-	const sections = Object.entries(dictionary)
-		.map(([section, entries]) => {
-			const lines = Object.entries(entries)
-				.map(([key, value]) => `\t\t${key}: ${quote(value)},`)
-				.join('\n');
-			return `\t${section}: {\n${lines}\n\t},`;
-		})
-		.join('\n');
-	return `{\n${sections}\n}`;
-}
-
-function localeBlueprint(key) {
-	const projectRoot = process.cwd();
-
-	if (!key) {
-		console.error(
-			'[bitboss-ui] Usage: npx bitboss-ui locale <key>   (e.g. `npx bitboss-ui locale nl`)'
-		);
-		process.exit(1);
-	}
-	// Keys double as dayjs module names (`dayjs/locale/<key>`) — keep them tame.
-	if (!/^[a-z0-9-]+$/.test(key)) {
-		console.error(
-			`[bitboss-ui] Invalid locale key '${key}' — use lowercase letters, digits and dashes (it doubles as the dayjs locale name, e.g. 'nl', 'ja', 'zh-cn').`
-		);
-		process.exit(1);
-	}
-
-	const blueprintPath = join(PACKAGE_ROOT, 'dist', 'locale-blueprint.json');
-	if (!existsSync(blueprintPath)) {
-		console.error(
-			'[bitboss-ui] dist/locale-blueprint.json not found in the installed package — reinstall bitboss-ui (or run `npm run build` when working in the library repo).'
-		);
-		process.exit(1);
-	}
-	const { builtins, template } = JSON.parse(
-		readFileSync(blueprintPath, 'utf-8')
-	);
-
-	if (builtins.includes(key)) {
-		console.error(
-			`[bitboss-ui] '${key}' is a built-in locale — built-ins cannot be overridden; the \`additionalLocales\` option only adds new ones. Just set \`locale: '${key}'\`.`
-		);
-		process.exit(1);
-	}
-
-	const outPath = join(projectRoot, `${key}.locale.ts`);
-	if (existsSync(outPath)) {
-		console.error(
-			`[bitboss-ui] ${key}.locale.ts already exists — delete it first if you want a fresh blueprint.`
-		);
-		process.exit(1);
-	}
-
-	// Same check the vite plugin performs at build time — surface it here too,
-	// while the consumer is still choosing the key.
-	let dayjsHint = `Calendar (dayjs) locale '${key}' found — calendars will follow automatically.`;
-	try {
-		// Consumer's own resolution first; fall back to the installed package's
-		// (dayjs is a bitboss-ui dependency, so it's always reachable from here).
-		try {
-			createRequire(join(projectRoot, 'package.json')).resolve(
-				`dayjs/locale/${key}.js`
-			);
-		} catch {
-			createRequire(join(PACKAGE_ROOT, 'package.json')).resolve(
-				`dayjs/locale/${key}.js`
-			);
-		}
-	} catch {
-		dayjsHint = `⚠ dayjs ships no locale named '${key}' — calendars will fall back to English (the vite plugin repeats this warning at build time). If a nearby dayjs name exists (e.g. 'zh-cn', 'pt-br'), prefer it as your key: https://github.com/iamkun/dayjs/tree/dev/src/locale`;
-	}
-
-	writeFileSync(
-		outPath,
-		`import type { LocaleOverrides } from 'bitboss-ui';
-
-/**
- * bitboss-ui locale blueprint for '${key}' — generated by \`npx bitboss-ui locale ${key}\`.
- *
- * Translate the English strings below ({0}/{1} placeholders are interpolated
- * arguments — keep them). Keys you delete fall back per-key to the library's
- * default locale. Register it in your vite config:
- *
- *   import ${key.replace(/-/g, '_')} from './${key}.locale';
- *   bitbossUi({ iconDir: '...', locale: '${key}', additionalLocales: { '${key}': ${key.replace(/-/g, '_')} } })
- *
- * The plugin regenerates \`locale-registry.d.ts\` on build start, making
- * '${key}' a valid \`locale\` value everywhere (run dev once after adding it).
- */
-export default ${localeObjectLiteral(template)} satisfies LocaleOverrides;
-`,
-		'utf-8'
-	);
-
-	console.log(`[bitboss-ui] Wrote ${key}.locale.ts (English blueprint).`);
-	console.log(`  ${dayjsHint}`);
-}
-
 // SNT-007: a bare-segment skip list of `node_modules`/`dist`/`.git` let a
 // default (no-glob) `check` sweep straight through a Laravel-style consumer's
 // `vendor/`, `storage/`, and `public/` trees — hundreds of vendored
@@ -550,9 +461,34 @@ function checkCommand(globs, jsonMode, allowEmpty = false) {
 		process.exit(1);
 	}
 	const manifest = loadManifest(manifestPath);
+
+	/*
+	 * Every `--bb-*` the INSTALLED package declares, read from the stylesheet
+	 * the consumer actually ships. Read from disk rather than hardcoded so this
+	 * can never claim a token is invented when their version does declare it.
+	 * Absent stylesheet → an empty set → the unknown-token hint stays silent,
+	 * which is the right failure: no data, no accusation.
+	 */
+	const stylesPath = join(PACKAGE_ROOT, 'dist', 'styles.css');
+	const knownTokens = existsSync(stylesPath)
+		? new Set(
+				[
+					...readFileSync(stylesPath, 'utf-8').matchAll(
+						/(--bb-[a-z0-9-]+)\s*:/gi
+					),
+				].map((m) => m[1].toLowerCase())
+			)
+		: new Set();
 	const files = resolveCheckFiles(projectRoot, globs);
 
 	const findings = [];
+	/*
+	 * Advisory only — see scripts/lib/hand-roll-hints.mjs. Hints never touch the
+	 * exit code, so a guess can never fail a consumer's build. `--no-hints`
+	 * silences them for anyone who finds them noisy.
+	 */
+	const hints = [];
+	const wantHints = !process.argv.includes('--no-hints');
 	for (const file of files) {
 		const relPath = relative(projectRoot, file);
 		const content = readFileSync(file, 'utf-8');
@@ -562,10 +498,34 @@ function checkCommand(globs, jsonMode, allowEmpty = false) {
 		for (const finding of fileFindings) {
 			findings.push({ file: relPath, ...finding });
 		}
+		// .md files are documentation ABOUT components; a round <img> in a doc
+		// example is illustrative, not a hand-roll.
+		if (wantHints && !file.endsWith('.md')) {
+			for (const hint of findHandRollHints(content, knownTokens)) {
+				hints.push({ file: relPath, ...hint });
+			}
+		}
 	}
 
+	/** Advisory block, printed on success and on failure alike. Never fatal. */
+	const printHints = () => {
+		if (hints.length === 0) return;
+		console.log(
+			`\n[bitboss-ui] ${hints.length} hint(s) — advisory, not errors:`
+		);
+		for (const hint of hints) {
+			console.log(`  ${hint.file}:${hint.line}`);
+			console.log(`    → ${hint.message}`);
+		}
+		console.log(
+			'  Deliberate? Ignore these, record them in a HANDROLLED note, or pass --no-hints.'
+		);
+	};
+
 	if (jsonMode) {
-		console.log(JSON.stringify({ findings, files: files.length }, null, 2));
+		console.log(
+			JSON.stringify({ findings, hints, files: files.length }, null, 2)
+		);
 		if (findings.length > 0) process.exit(1);
 		if (files.length === 0 && globs.length > 0 && !allowEmpty) process.exit(1);
 		return;
@@ -595,6 +555,7 @@ function checkCommand(globs, jsonMode, allowEmpty = false) {
 		console.log(
 			`[bitboss-ui] check OK — ${summarizeFileCounts(files)} file(s), zero unknown Bb* props/v-models/slots/nav-attrs.`
 		);
+		printHints();
 		return;
 	}
 
@@ -620,6 +581,7 @@ function checkCommand(globs, jsonMode, allowEmpty = false) {
 	console.error(
 		'\nFix the markup (or the component API) so it stays copy-safe for agents.'
 	);
+	printHints();
 	process.exit(1);
 }
 
@@ -654,9 +616,6 @@ Commands:
   mcp                 Start a stdio MCP server exposing the dist/ai knowledge
                       base (search_components, get_component, list_recipes,
                       get_recipe, validate) to MCP-capable agent harnesses.
-  locale <key>        Generate <key>.locale.ts at the project root — an English
-                      blueprint dictionary to translate and pass to the plugin's
-                      \`additionalLocales\` option (additions only; built-ins are refused).
   help                Show this help.
 `);
 }
@@ -710,22 +669,30 @@ switch (command) {
 		break;
 	}
 	case 'mcp': {
-		const { main } = await import('./bitboss-ui-mcp.mjs');
+		// `@modelcontextprotocol/sdk` + `zod` are OPTIONAL peers, not
+		// dependencies: together they weigh ~12 MB — more than every runtime
+		// dependency of the component library combined, and the SDK drags in a
+		// whole HTTP stack (express, hono, cors, jose). Only this subcommand
+		// needs them, so consumers who never run the MCP server do not pay for
+		// it. That makes the import failure a SUPPORTED path, and a bare
+		// ERR_MODULE_NOT_FOUND stack is not an answer — say what to install.
+		let main;
+		try {
+			({ main } = await import('./bitboss-ui-mcp.mjs'));
+		} catch (error) {
+			if (error?.code !== 'ERR_MODULE_NOT_FOUND') throw error;
+			console.error(
+				'bitboss-ui mcp needs two optional peer dependencies that are not installed:\n' +
+					'\n  npm i -D @modelcontextprotocol/sdk zod\n\n' +
+					'They are optional because they are ~12 MB and only this subcommand uses them.\n' +
+					`Resolution failed with: ${error.message}`
+			);
+			process.exitCode = 1;
+			break;
+		}
 		await main();
 		break;
 	}
-	case 'locale': {
-		const { positionals } = parseCommandArgs(
-			command,
-			commandArgs,
-			{},
-			{
-				allowPositionals: true,
-			}
-		);
-		localeBlueprint(positionals[0]);
-		break;
-	}
 	case 'help':
 	case '--help':
 	case '-h':

package/dist/ai/BbAlert.md

@@ -207,9 +207,13 @@ click handler for something a link can do.
 </div>
 ```
 
-These are the only two slots — there is no default or actions slot. A short
-inline link in `#text` (as above) is fine; anything more interactive belongs
-outside the alert, or in a `BbDialog`.
+**The default slot is the text slot.** `<BbAlert>Something went wrong</BbAlert>`
+is the shortest form and the one to reach for; `text` as a prop is for when a
+string is all you have (an `:items` loop, a server message). When more than one
+is present the most specific wins: `#text` > children > `text`.
+
+There is no `actions` slot. A short inline link in the text (as above) is fine;
+anything more interactive belongs outside the alert, or in a `BbDialog`.
 
 #### Brand art via a raw SVG
 
@@ -353,9 +357,6 @@ const publish = () => {
 
 ### Gotchas & anti-patterns
 
-- **There is no default slot.** `<BbAlert>some text</BbAlert>` renders
-  nothing — Vue drops an unconsumed default slot silently, with no warning.
-  Use `title`/`text` (or `#title`/`#text`, see above).
 - **Omitting `v-model` does not make an alert permanent** — the close button
   still dismisses it locally. Use `hide-close` for that.
 - Don't rebuild dismissal with your own button + `v-if`; the built-in close
@@ -407,7 +408,8 @@ const publish = () => {
 
 ## Slots
 
-- `text` — scope: `BbAlertTextSlotProps` — Replaces the default alert body text.
+- `default` — scope: `any` — The alert body — the shortest form, and the one to reach for: `<BbAlert>Something went wrong</BbAlert>`. Same idiom as the rest of the `text`-prop family (BbButton, BbBaseButton, BbTooltip, BbIndicator). When more than one source is present…
+- `text` — scope: `BbAlertTextSlotProps` — Replaces the default alert body text. Wins over children and `text`.
 - `title` — scope: `BbAlertTitleSlotProps` — Replaces the default alert title text.
 
 ## See Also

package/dist/ai/BbAvatar.md

@@ -439,10 +439,12 @@ const feed: FeedEntry[] = [
 Load failures are normally caught by the image's `error` event. As a safety
 net — mainly for SSR/hydrated pages where the events fired before hydration —
 the component also checks the image `timeout` ms after mount (default `400`)
-and switches to the fallback if it hasn't loaded correctly by then. This makes
-`timeout` an effective **deadline**: an image slower than `timeout` falls back
-and stays on the fallback until `src` changes. If your avatars come from a
-slow origin, raise `timeout` rather than accepting spurious fallbacks.
+and switches to the fallback if it hasn't loaded correctly by then. The
+`<img>` stays mounted (visually hidden) through that switch, so the deadline
+is **not** terminal: a slow image shows the fallback at `timeout` and swaps
+itself back in the moment it finishes loading. Only a real `error` is
+permanent until `src` changes. If your avatars come from a slow origin, raise
+`timeout` rather than accepting a visible fallback-then-photo flip.
 
 Platform notes: the component is SSR-safe (Nuxt/Inertia) with no client-only
 markup; the only global config it reads is `iconDefaultSizes` for the size
@@ -461,15 +463,20 @@ keys.
 
 ### Gotchas & anti-patterns
 
-- **There is no `color` prop.** The fallback is always primary-token colored;
-  don't reach for per-avatar inline backgrounds. Use variants and target the generated `bb-avatar--{{variant}}` or retheme `--bb-primary` /
-  `--bb-primary-fg` if the palette is wrong.
+- **There is no `color` prop, and no `variant` either.** The fallback is always
+  primary-token colored; don't reach for per-avatar inline backgrounds. If the
+  palette is wrong, retheme `--bb-primary` / `--bb-primary-fg` — theming here
+  happens through the tokens, not a prop.
 - **Default `timeout` can false-fallback slow images** (see above) — tune it,
   don't reimplement image loading around the component.
 - Don't hand-position presence dots with absolute CSS — `BbIndicator dot`
   exists for that.
 - Don't wrap the avatar in a raw `<span @click>` for menus — put it inside
   `BbBaseButton`/`BbDropdown` so focus and keyboard behavior come for free.
+- **The shape is a circle, and it is not configurable.** `border-radius: 50%`
+  is baked in. A rounded-SQUARE avatar — common in dense tables, where a square
+  reads as "entity" and a circle as "person" — has no answer here; build that
+  one yourself rather than fighting the radius.
 - Don't pre-crop sources to circles — the component center-crops; ship square
   or larger originals.
 - Don't leave `alt` empty for meaningful avatars: fallbacks lose their

package/dist/ai/BbBadgeButton.md

@@ -14,24 +14,36 @@
 | --- | --- | --- | --- | --- |
 | `activeClass` | `string \| undefined` |  |  | CSS class applied when the component renders as a link and the target of the link is the current route or the url matches partially. Ported for Inertia compatibility. |
 | `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` |  |  | Value forwarded to the `aria-current` attribute when the component renders as a router link and the target route is an exact match. Use to communicate the current location to assistive technologies. |
+| `async` | `boolean \| undefined` |  |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
+| `cacheFor` | `string \| number \| (string \| number)[] \| undefined` |  |  | Inertia: how long a prefetched response stays fresh before it is re-fetched. A single duration, or `[staleAfter, expiresAfter]`. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be in… |
+| `cacheTags` | `string \| string[] \| undefined` |  |  | Inertia: tags to file this visit's prefetch cache under, so a later request can invalidate the whole tagged group. |
+| `component` | `string \| undefined` |  |  | Inertia: the page component this visit resolves to. Rarely set by hand — the server normally decides it. |
 | `data` | `object \| undefined` |  |  | Request payload forwarded to Inertia when navigating via `href` in an Inertia-enabled app. Ignored when not using Inertia. |
 | `disabled` | `boolean \| undefined` |  |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"`, and prevents navigation while keeping focusable semanti… |
 | `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download. Renders a plain `<a download>` doing a native navigation — never an Inertia/router visit — so file downloads (including same-origin, `blob:` and `data:` URLs) work. Pass a string to set the suggested file… |
 | `exactActiveClass` | `string \| undefined` |  |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
+| `except` | `string[] \| undefined` |  |  | Inertia: the inverse of `only` — properties to EXCLUDE from a partial reload. Pass one or the other, not both. |
 | `external` | `boolean \| undefined` |  |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target… |
 | `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
 | `href` | `string \| undefined` |  |  | Hyperlink reference used when rendering as an anchor (or as an Inertia link in Inertia-enabled apps). If provided and not disabled, the component renders as an anchor/Inertia link. |
+| `instant` | `boolean \| undefined` |  |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
 | `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  | HTTP method used for Inertia navigation when `href` is provided in an Inertia-enabled app. Ignored otherwise. |
 | `onBefore` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia right before the request is sent. |
 | `onCancel` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request is cancelled. |
 | `onCancelToken` | `((cancelToken: unknown) => void) \| undefined` |  |  | Receives the Inertia cancel token source when a request is initiated. Can be used to cancel the request. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
+| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when the server responds with VALIDATION errors — the ordinary 422 path. This is the only failure callback Inertia's `Link` accepts. `onHttpException` (server answered 5xx) and `onNetworkError` (the request… |
 | `onFinish` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia after the request has finished (regardless of success or error). |
 | `only` | `string[] \| undefined` |  |  | Limits the properties that are preserved in Inertia partial reloads. |
+| `onPrefetched` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link has completed and is cached. |
+| `onPrefetching` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link starts. |
 | `onProgress` | `((progress: { percentage: number \| undefined; }) => void) \| undefined` |  |  | Progress callback invoked by Inertia with the upload/download percentage when available. |
 | `onStart` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request starts. |
 | `onSuccess` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request succeeds. |
+| `pageProps` | `Record<string, unknown> \| ((currentProps: Record<string, unknown>, sharedProps: Record<string, unknown>) => Record<string, unknown>) \| null \| undefined` |  |  | Inertia: props to merge into the next page optimistically, before the server responds. Either an object or a function of the current props. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue… |
+| `prefetch` | `string \| boolean \| string[] \| undefined` |  |  | Inertia: fetch and cache this link's page ahead of the click. `true` uses the default trigger; a string or list of strings picks them (`'mount'`, `'hover'`, `'click'`). |
 | `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` |  |  | Controls whether Inertia should preserve the current scroll position after navigation. Can be a boolean or a predicate receiving the visit props. |
 | `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` |  |  | Controls whether Inertia should preserve the current state after navigation. Can be a boolean or a predicate receiving the visit props. |
+| `preserveUrl` | `boolean \| undefined` |  |  | Inertia: keep the current URL in the address bar even though the page content changes. |
 | `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` |  |  | Format to use when serializing array values into the query string for Inertia requests. |
 | `rel` | `string \| undefined` |  |  | Relationship between the current document and the linked resource. Useful for security when opening new tabs (e.g. `noopener noreferrer`). |
 | `replace` | `boolean \| undefined` |  |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
@@ -39,6 +51,7 @@
 | `target` | `string \| undefined` |  |  | Target browsing context for anchor/Inertia links (e.g. `_self`, `_blank`). Ignored when rendering as a native button. |
 | `to` | `string \| wt \| bt \| undefined` |  |  | Route location to navigate to. When provided (and not disabled), the component renders as a Vue Router link. |
 | `type` | `"button" \| "submit" \| "reset" \| undefined` |  |  | Native `type` attribute used when rendering as a button (e.g. `button`, `submit`, `reset`). |
+| `viewTransition` | `boolean \| undefined` |  |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
 
 ## Events
 

package/dist/ai/BbBaseButton.md

@@ -102,9 +102,12 @@ const pinged = ref(false);
 ### It ships no chrome — you style it
 
 The only classes it applies are structural: `bb-base-button` (a focus-ring
-scaffold, `cursor`, inherited text color and transitions), `bb-base-button--block`
-and `bb-base-button--disabled`. There is **no padding, background, border, or
-variant appearance** — that is the whole point. Give it a class (your own, or
+scaffold, `cursor` and transitions), `bb-base-button--block` and
+`bb-base-button--disabled`. There is **no padding, background, border, or
+variant appearance** — that is the whole point. It sets **no text color**, so a
+`text-*` utility on the element just works with no specificity fight; the text
+inherits from its container (in anchor mode, the browser's blue-and-underlined
+link chrome is neutralized so it inherits too). Give it a class (your own, or
 Tailwind utilities) and it looks like whatever you draw. This is what makes it
 the right base for a clickable card or a bespoke nav item:
 
@@ -454,25 +457,37 @@ const sent = ref(false);
 | --- | --- | --- | --- | --- |
 | `activeClass` | `string \| undefined` |  |  | CSS class applied when the component renders as a link and the target of the link is the current route or the url matches partially. Ported for Inertia compatibility. |
 | `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` |  |  | Value forwarded to the `aria-current` attribute when the component renders as a router link and the target route is an exact match. Use to communicate the current location to assistive technologies. |
+| `async` | `boolean \| undefined` |  |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
 | `block` | `boolean \| undefined` |  |  | Makes the component take the full available width (block-level layout). Adds the `bb-base-button--block` modifier class. |
+| `cacheFor` | `string \| number \| (string \| number)[] \| undefined` |  |  | Inertia: how long a prefetched response stays fresh before it is re-fetched. A single duration, or `[staleAfter, expiresAfter]`. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be in… |
+| `cacheTags` | `string \| string[] \| undefined` |  |  | Inertia: tags to file this visit's prefetch cache under, so a later request can invalidate the whole tagged group. |
+| `component` | `string \| undefined` |  |  | Inertia: the page component this visit resolves to. Rarely set by hand — the server normally decides it. |
 | `data` | `object \| undefined` |  |  | Request payload forwarded to Inertia when navigating via `href` in an Inertia-enabled app. Ignored when not using Inertia. |
 | `disabled` | `boolean \| undefined` |  |  | Disables user interaction. - When rendering as a native button, sets the `disabled` attribute. - When rendering as a link (anchor/Inertia), removes `href`, adds `aria-disabled="true"`, and prevents navigation while keeping focusable semanti… |
 | `download` | `string \| boolean \| undefined` |  |  | Marks an `href` link as a download. Renders a plain `<a download>` doing a native navigation — never an Inertia/router visit — so file downloads (including same-origin, `blob:` and `data:` URLs) work. Pass a string to set the suggested file… |
 | `exactActiveClass` | `string \| undefined` |  |  | CSS class applied when the component renders as a link and the target of the link and the url matches exactly. Ported for Inertia compatibility. |
+| `except` | `string[] \| undefined` |  |  | Inertia: the inverse of `only` — properties to EXCLUDE from a partial reload. Pass one or the other, not both. |
 | `external` | `boolean \| undefined` |  |  | Forces an `href` link to render as a plain `<a>` (native navigation), bypassing Inertia/router interception — the same intent as Nuxt's `NuxtLink` `external`. Use for links outside the SPA. One of the native-anchor signals alongside `target… |
 | `headers` | `object \| undefined` |  |  | Additional HTTP headers forwarded to Inertia when navigating via `href` in an Inertia-enabled app. |
 | `href` | `string \| undefined` |  |  | Hyperlink reference used when rendering as an anchor (or as an Inertia link in Inertia-enabled apps). If provided and not disabled, the component renders as an anchor/Inertia link. |
+| `instant` | `boolean \| undefined` |  |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
 | `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  | HTTP method used for Inertia navigation when `href` is provided in an Inertia-enabled app. Ignored otherwise. |
 | `onBefore` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia right before the request is sent. |
 | `onCancel` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request is cancelled. |
 | `onCancelToken` | `((cancelToken: unknown) => void) \| undefined` |  |  | Receives the Inertia cancel token source when a request is initiated. Can be used to cancel the request. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue3` to be installed. |
+| `onError` | `((errors: Record<string, string>) => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when the server responds with VALIDATION errors — the ordinary 422 path. This is the only failure callback Inertia's `Link` accepts. `onHttpException` (server answered 5xx) and `onNetworkError` (the request… |
 | `onFinish` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia after the request has finished (regardless of success or error). |
 | `only` | `string[] \| undefined` |  |  | Limits the properties that are preserved in Inertia partial reloads. |
+| `onPrefetched` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link has completed and is cached. |
+| `onPrefetching` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a prefetch for this link starts. |
 | `onProgress` | `((progress: { percentage: number \| undefined; }) => void) \| undefined` |  |  | Progress callback invoked by Inertia with the upload/download percentage when available. |
 | `onStart` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request starts. |
 | `onSuccess` | `(() => void) \| undefined` |  |  | Lifecycle hook invoked by Inertia when a request succeeds. |
+| `pageProps` | `Record<string, unknown> \| ((currentProps: Record<string, unknown>, sharedProps: Record<string, unknown>) => Record<string, unknown>) \| null \| undefined` |  |  | Inertia: props to merge into the next page optimistically, before the server responds. Either an object or a function of the current props. Typed platform-agnostically (matching BbButton) so the library's types never require `@inertiajs/vue… |
+| `prefetch` | `string \| boolean \| string[] \| undefined` |  |  | Inertia: fetch and cache this link's page ahead of the click. `true` uses the default trigger; a string or list of strings picks them (`'mount'`, `'hover'`, `'click'`). |
 | `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` |  |  | Controls whether Inertia should preserve the current scroll position after navigation. Can be a boolean or a predicate receiving the visit props. |
 | `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` |  |  | Controls whether Inertia should preserve the current state after navigation. Can be a boolean or a predicate receiving the visit props. |
+| `preserveUrl` | `boolean \| undefined` |  |  | Inertia: keep the current URL in the address bar even though the page content changes. |
 | `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` |  |  | Format to use when serializing array values into the query string for Inertia requests. |
 | `rel` | `string \| undefined` |  |  | Relationship between the current document and the linked resource. Useful for security when opening new tabs (e.g. `noopener noreferrer`). |
 | `replace` | `boolean \| undefined` |  |  | Uses history replacement instead of push navigation. - With Vue Router (`to`), calls `router.replace`. - With Inertia (`href`), performs a replace visit. |
@@ -481,6 +496,7 @@ const sent = ref(false);
 | `text` | `string \| undefined` |  |  | Fallback text content rendered when no default slot is provided. |
 | `to` | `string \| wt \| bt \| undefined` |  |  | Route location to navigate to. When provided (and not disabled), the component renders as a Vue Router link. |
 | `type` | `"button" \| "submit" \| "reset" \| undefined` | `"button"` |  | Native `type` attribute used when rendering as a button (e.g. `button`, `submit`, `reset`). |
+| `viewTransition` | `boolean \| undefined` |  |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
 
 ## Events
 

package/dist/ai/BbBaseRating.md

@@ -17,6 +17,7 @@
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
 | `ariaDescribedby` | `string \| undefined` |  |  | Id(s) of elements describing this rating input for assistive technologies. |
+| `ariaLabelledby` | `string \| undefined` |  |  | Id(s) of the element(s) that NAME this rating group. Supplying one is what promotes the inner container to `role="radiogroup"` (Q4.5): an unnamed `radiogroup` announces as a bare "radio group" and is no better than the role-less `<span>` it… |
 | `autofocus` | `Booleanish \| undefined` |  |  | Sets autofocus on page load. |
 | `clearable` | `boolean \| undefined` | `false` |  | Allows clearing the selected rating by clicking the current value. |
 | `disabled` | `boolean \| undefined` |  |  | Disable all interactions with the rating. |