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

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

@@ -35,11 +35,15 @@ import {
 	statSync,
 	writeFileSync,
 } from 'node:fs';
+import { findHandRollHints } from '../scripts/lib/hand-roll-hints.mjs';
 import { createRequire } from 'node:module';
 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 +242,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})`);
@@ -550,9 +569,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 +606,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 +663,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 +689,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);
 }
 
@@ -710,7 +780,27 @@ 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;
 	}

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

@@ -642,12 +642,35 @@ Under Inertia, `href` accepts the full visit surface as props, grouped by
 concern:
 
 - **Request shape** — `method` (`get`…`delete`), `data`, `headers`, `only`
-  (partial reloads), `query-string-array-format`.
+  (partial reloads), `except` (the inverse of `only` — pass one or the other),
+  `query-string-array-format`, `component`.
 - **History & scroll** — `replace`, `preserve-scroll`, `preserve-state` (each
-  also accepts a callback form).
+  also accepts a callback form), `preserve-url` (change the page, keep the
+  address bar), `view-transition`.
+- **Prefetching** — `prefetch` (`true`, or `'mount'`/`'hover'`/`'click'`),
+  `cache-for` (a duration, or `[staleAfter, expiresAfter]`), `cache-tags` for
+  group invalidation.
+- **Speed** — `async` (don't block the page), `instant` (navigate optimistically
+  and reconcile on response), `page-props` (props to merge before the server
+  answers).
 - **Lifecycle hooks** — `onBefore`, `onStart`, `onProgress`, `onSuccess`,
-  `onCancel`, `onFinish`, plus `onCancelToken` to capture a cancel handle.
-  Bind them as props (`:on-success="..."`), not `@` listeners.
+  `onError`, `onCancel`, `onFinish`, plus `onCancelToken` to capture a cancel
+  handle and `onPrefetching`/`onPrefetched` for the prefetch pair. Bind them as
+  props (`:on-success="..."`), not `@` listeners.
+
+**`onError` here means VALIDATION errors** — the ordinary 422 — and it is the
+only failure callback `<Link>` accepts. Inertia's other two,
+`onHttpException` (the server answered 5xx) and `onNetworkError` (the request
+never arrived — offline, DNS, connection reset), are **`router.visit()` /
+`useForm()` options, not Link props**; passing them to a link-shaped button
+does nothing. Reach for a form or an explicit visit when you need to tell those
+apart — see the Inertia helpers guide.
+
+Every prop Inertia's own `<Link>` accepts is forwarded, and
+`npm run check:inertia-props` fails the build both when Inertia adds one we
+don't forward and when we declare a callback `<Link>` never accepted. The list
+has to be hand-written, because `@inertiajs/vue3` is an optional peer the
+library's public types are not allowed to import.
 
 ```vue
 <!-- Inertia: href becomes a visit; the whole option set rides along -->
@@ -658,11 +681,19 @@ concern:
 	preserve-scroll
 	:only="['invoices']"
 	:on-success="() => drawer.close()"
+	:on-error="(errors) => (formErrors = errors)"
 >
 	Create invoice
 </BbButton>
 ```
 
+```vue
+<!-- Prefetch on hover so the detail page is already cached by the click -->
+<BbButton href="/invoices/42" prefetch="hover" cache-for="30s" variant="link">
+	Invoice #42
+</BbButton>
+```
+
 ### Works well with
 
 - `BbDropdownButton` — escalate to it when a primary action grows close
@@ -851,18 +882,24 @@ Anti-patterns:
 | `activeClass` | `string \| undefined` |  |  | Class to apply when the link is active. |
 | `append:icon` | `string \| undefined` |  |  | Icon to be added on the right of the text. |
 | `ariaCurrentValue` | `"page" \| "step" \| "location" \| "date" \| "time" \| "true" \| "false" \| undefined` |  |  | Value passed to the attribute `aria-current` when the link is exact active. |
+| `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` |  |  | Displays the component as full width. |
+| `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` |  |  |  |
 | `disableAutoLoading` | `boolean \| undefined` |  |  | Disables the automatic loading state that tracks async click handlers (enabled by default). |
 | `disabled` | `boolean \| undefined` |  |  | Disables the component. |
 | `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 work. Pass a string for the suggested filename. A native-anchor signal alongside `target` and `e… |
 | `exactActiveClass` | `string \| undefined` |  |  | Class to apply when the link is exact active. |
+| `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 — same intent as Nuxt's `external`. A native-anchor signal alongside `target` and `download`. |
 | `falseValue` | `any` | `false` |  | Value emitted when the toggle is deactivated. |
 | `group` | `boolean \| undefined` |  |  | Identifies the button as part of a button group. |
 | `headers` | `object \| undefined` |  |  |  |
 | `href` | `string \| undefined` |  |  | Returns the hyperlink's URL. Can be set, to change the URL. |
 | `icon` | `string \| undefined` |  |  | Used when only an icon with no text should be displayed. |
+| `instant` | `boolean \| undefined` |  |  | Inertia: navigate optimistically on click and reconcile when the response lands, instead of waiting for the round trip. |
 | `interactiveWhileLoading` | `boolean \| undefined` |  |  | Keeps the button clickable while it is loading. Buttons are disabled while loading by default; this escape hatch exists for toggles that must stay interactive (e.g. the dropdown-button caret). |
 | `loading` | `boolean \| undefined` |  |  | Triggers a loading indicator. |
 | `method` | `"get" \| "post" \| "put" \| "patch" \| "delete" \| undefined` |  |  |  |
@@ -870,14 +907,20 @@ Anti-patterns:
 | `onBefore` | `(() => void) \| undefined` |  |  |  |
 | `onCancel` | `(() => void) \| undefined` |  |  |  |
 | `onCancelToken` | `((cancelToken: unknown) => void) \| undefined` |  |  |  |
+| `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` |  |  |  |
 | `only` | `string[] \| undefined` |  |  |  |
+| `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` |  |  |  |
 | `onStart` | `(() => void) \| undefined` |  |  |  |
 | `onSuccess` | `(() => void) \| undefined` |  |  |  |
+| `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'`). |
 | `prepend:icon` | `string \| undefined` |  |  | Icon to be added on the left of the text. |
 | `preserveScroll` | `boolean \| ((props: Record<string, unknown>) => boolean) \| undefined` |  |  |  |
 | `preserveState` | `boolean \| ((props: Record<string, unknown>) => boolean) \| null \| undefined` |  |  |  |
+| `preserveUrl` | `boolean \| undefined` |  |  | Inertia: keep the current URL in the address bar even though the page content changes. |
 | `queryStringArrayFormat` | `"brackets" \| "indices" \| undefined` |  |  |  |
 | `replace` | `boolean \| undefined` |  |  | Calls `router.replace` instead of `router.push`. |
 | `size` | `Responsive<Sizes> \| undefined` | `"md"` |  | Sets the size of the button. A single value applies at every breakpoint; a per-breakpoint map (e.g. `{ default: 'sm', lg: 'md' }`) switches responsively. Purely CSS-driven — no runtime breakpoint watching. |
@@ -888,6 +931,7 @@ Anti-patterns:
 | `trueValue` | `any` | `true` |  | Value emitted when the toggle is activated. |
 | `type` | `"button" \| "submit" \| "reset" \| undefined` |  |  | Gets the classification and default behavior of the button. |
 | `variant` | `ButtonVariantType \| undefined` | `"primary"` |  | Visual variant of the button. Controls colors and surface style while keeping spacing and sizing unchanged. |
+| `viewTransition` | `boolean \| undefined` |  |  | Inertia: run the page swap inside a View Transition, where the browser supports one. |
 
 ## Events
 

package/dist/ai/BbDropdownButton.md

@@ -354,7 +354,6 @@ activator slot: the toggle button is part of the component's contract.
 ```vue
 <BbDropdownButton
 	right:icon="lucide:ellipsis"
-	size="sm"
 	variant="outline"
 	:items="[
 		{ key: 'open', text: 'Open', href: '#open' },