bitboss-ui 3.0.0-beta.63 → 3.0.0-beta.64

package/README.md

@@ -296,11 +296,15 @@ 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           |
-| ------------------ | ----------------- |
-| `.mcp.json`        | Claude Code       |
-| `.cursor/mcp.json` | Cursor            |
-| `.vscode/mcp.json` | VS Code / Copilot |
+| File                 | Harness           |
+| -------------------- | ----------------- |
+| `.mcp.json`          | Claude Code       |
+| `.cursor/mcp.json`   | Cursor            |
+| `.vscode/mcp.json`   | VS Code / Copilot |
+| `.zed/settings.json` | Zed               |
+
+Comments in a JSONC config (`.vscode/mcp.json`, `.zed/settings.json`) are
+kept. Zed starts the server once you trust the project.
 
 Windsurf only reads a global config in your home directory, so the server is
 not registered for it — add the same entry to
@@ -329,13 +333,13 @@ part you need.
 
 ### CLI commands
 
-| Command                                                                   | What it does                                                                                                                                                                                                                             |
-| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `npx bitboss-ui ai-init [--update] [--no-mcp]`                            | Writes the agent pointer files and registers the MCP server (installs its optional peers).                                                                                                                                               |
-| `npx bitboss-ui check [paths… \| --changed] [--fix] [--json]`             | Validates `Bb*` markup in `.vue` / `.md` files against the installed version; `--fix` applies the library's renames first (v2 → v3, and between 3.0 betas); `--changed` checks only the files git sees changed vs HEAD (plus untracked). |
-| `npx bitboss-ui changelog --since <version> [--until <version>] [--json]` | Lists the **breaking** changes between the version you are on and the installed one — what breaks if you bump.                                                                                                                           |
-| `npx bitboss-ui mcp`                                                      | Starts the MCP server on stdio (harnesses launch it for you after `ai-init`).                                                                                                                                                            |
-| `npx bitboss-ui --help`                                                   | Every command and flag.                                                                                                                                                                                                                  |
+| Command                                                                   | What it does                                                                                                                                                                                                                                                                                                                                                                                   |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `npx bitboss-ui ai-init [--update] [--no-mcp]`                            | Writes the agent pointer files and registers the MCP server (installs its optional peers).                                                                                                                                                                                                                                                                                                     |
+| `npx bitboss-ui check [paths… \| --changed] [--fix] [--idioms] [--json]`  | Validates `Bb*` markup in `.vue` / `.md` files against the installed version; `--fix` applies the library's renames first (v2 → v3, and between 3.0 betas); `--changed` checks only the files git sees changed vs HEAD (plus untracked); `--idioms` also lists the hand-rolled controls the library ships ([adoption checklist](dist/ai/guides/migration/adoption-checklist.md), report-only). |
+| `npx bitboss-ui changelog --since <version> [--until <version>] [--json]` | Lists the **breaking** changes between the version you are on and the installed one — what breaks if you bump.                                                                                                                                                                                                                                                                                 |
+| `npx bitboss-ui mcp`                                                      | Starts the MCP server on stdio (harnesses launch it for you after `ai-init`).                                                                                                                                                                                                                                                                                                                  |
+| `npx bitboss-ui --help`                                                   | Every command and flag.                                                                                                                                                                                                                                                                                                                                                                        |
 
 ### ESLint plugin
 
@@ -379,14 +383,15 @@ export default [
 **It also migrates v2 → v3 with `eslint --fix`.** Deprecated props are rewritten
 in place — the rule is a codemod, not just a linter:
 
-| You wrote                                 | `--fix` produces                         | Kind                      |
-| ----------------------------------------- | ---------------------------------------- | ------------------------- |
-| `<BbIcon type="star" />`                  | `<BbIcon icon="star" />`                 | rename                    |
-| `<BbTable :allow-select-all="x" />`       | `<BbTable :disable-select-all="!(x)" />` | polarity inversion        |
-| `<BbSelect allow-writing="not-mobile" />` | `<BbSelect disable-writing="mobile" />`  | rename + value remap      |
-| `<BbHost />`                              | `<BbHost />`                             | value map                 |
-| `<BbPopover show-arrow />`                | `<BbPopover />`                          | removed & inert → deleted |
-| `<BbBadge content="5" />`                 | _(unchanged — reported)_                 | needs a slot: manual      |
+| You wrote                                 | `--fix` produces                        | Kind                      |
+| ----------------------------------------- | --------------------------------------- | ------------------------- |
+| `<BbIcon type="star" />`                  | `<BbIcon icon="star" />`                | rename                    |
+| `<BbTable :allow-select-all="x" />`       | `<BbTable :disable-select-all="!x" />`  | polarity inversion        |
+| `<BbTabs :animate-x="false" />`           | `<BbTabs disable-animate-x />`          | inversion, literal folded |
+| `<BbSelect allow-writing="not-mobile" />` | `<BbSelect disable-writing="mobile" />` | rename + value remap      |
+| `<BbHost />`                              | `<BbHost />`                            | value map                 |
+| `<BbPopover show-arrow />`                | `<BbPopover />`                         | removed & inert → deleted |
+| `<BbBadge content="5" />`                 | _(unchanged — reported)_                | needs a slot: manual      |
 
 The fixer is conservative: it only rewrites when the transform is provably
 correct (and never toward a name that isn't a real prop), so structural

package/bin/bitboss-ui.mjs

@@ -14,7 +14,7 @@
  *             - `vueCompilerOptions.checkUnknownComponents: true` in the
  *               tsconfig (Q60.6), unless the project already names it
  *             Also registers the `bitboss-ui mcp` server for Claude Code,
- *             Cursor and VS Code and installs its optional peers
+ *             Cursor, VS Code and Zed 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
@@ -69,6 +69,7 @@ import {
 	findHandRollHints,
 	loadKnownTokens,
 } from '../scripts/lib/hand-roll-hints.mjs';
+import { loadAdoptionRows, scanIdioms } from '../scripts/lib/idiom-scan.mjs';
 import {
 	disabledChecker,
 	ruleForFinding,
@@ -105,6 +106,7 @@ import {
 	staleDefinePresetFindings,
 } from '../scripts/lib/define-preset-copy.mjs';
 import {
+	readOptionsApiOff,
 	readRegisteredVariants,
 	syncNotice,
 	syncProjectVariantDts,
@@ -136,7 +138,7 @@ import {
 	presetDefinitions,
 	validateMarkdown,
 	validateVueSnippet,
-	VARIANT_INTENT_OPTIONS,
+	REGISTERED_VARIANT_OPTIONS,
 } from '../scripts/lib/validate-bb-markup.mjs';
 
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
@@ -393,7 +395,7 @@ function aiInit({ mcp = true } = {}) {
 	);
 	if (mcp) {
 		console.log(
-			'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.'
+			'MCP: registered the bitboss-ui server for Claude Code (.mcp.json), Cursor (.cursor/mcp.json), VS Code/Copilot (.vscode/mcp.json) and Zed (.zed/settings.json) — restart your harness to pick it up; Zed starts it once you trust the project. `--no-mcp` skips this.'
 		);
 	} else {
 		console.log(
@@ -945,6 +947,7 @@ async function checkCommand(
 		manifest: manifestOverride,
 		fix,
 		changed: changedOnly,
+		idioms: wantIdioms,
 	}
 ) {
 	const projectRoot = process.cwd();
@@ -1149,8 +1152,9 @@ async function checkCommand(
 		// A variant the build plugin registers is the project's own name.
 		registeredVariants: readRegisteredVariants(
 			projectRoot,
-			Object.values(VARIANT_INTENT_OPTIONS)
+			REGISTERED_VARIANT_OPTIONS
 		),
+		optionsApiOff: readOptionsApiOff(projectRoot),
 	};
 
 	const findings = [];
@@ -1250,6 +1254,31 @@ async function checkCommand(
 		}
 	}
 
+	// Q76.0: `--idioms`, the adoption checklist's patterns. Opt-in and
+	// report-only (scripts/lib/idiom-scan.mjs): never a finding, never the exit
+	// code. Same file scope as the portal names: scripts hold confirms and
+	// mobile checks too.
+	const idioms = [];
+	if (wantIdioms) {
+		const rows = loadAdoptionRows();
+		const exts = new Set(rows.flatMap((row) => row.ext));
+		const TEST_FILE = /\.(?:test|spec)(?:-d)?\.[cm]?[jt]sx?$/;
+		const scope = changed ? changed.all : globs.length ? files : projectSources;
+		for (const path of scope) {
+			const ext = path.slice(path.lastIndexOf('.') + 1);
+			if (!exts.has(ext) || path.endsWith('.d.ts') || TEST_FILE.test(path))
+				continue;
+			let content;
+			try {
+				content = readText(path);
+			} catch {
+				continue;
+			}
+			for (const hit of scanIdioms(content, ext, rows))
+				idioms.push({ file: relative(projectRoot, path), ...hit });
+		}
+	}
+
 	for (const [name, file] of projectLocal) warnLocal(name, file);
 	// Q60.6: a `vue-tsc` below 3, read from package.json. One line, never
 	// fatal. (A missing `checkUnknownComponents` is no longer warned about:
@@ -1347,6 +1376,26 @@ async function checkCommand(
 		);
 	};
 
+	/** The adoption checklist's report (`--idioms`). Never fatal. */
+	const printIdioms = () => {
+		if (!wantIdioms) return;
+		if (idioms.length === 0) {
+			console.log(
+				'\n[bitboss-ui] idioms: no hand-rolled pattern from the adoption checklist found.'
+			);
+			return;
+		}
+		console.log(
+			`\n[bitboss-ui] ${idioms.length} idiom(s) — hand-rolled patterns the library ships, report-only:`
+		);
+		for (const idiom of idioms)
+			console.log(`  ${idiom.file}:${idiom.line} [${idiom.id}] → ${idiom.use}`);
+		console.log(
+			'  Rows, replacements and the scope rule: node_modules/bitboss-ui/dist/ai/guides/migration/adoption-checklist.md.\n' +
+				'  Kept on purpose? Say why in one line of a HANDROLLED note.'
+		);
+	};
+
 	/*
 	 * Which API the verdict is against. Silent when it is the installed one —
 	 * that is the assumption, and a banner on every run trains people to skip
@@ -1380,6 +1429,7 @@ async function checkCommand(
 					findings,
 					warnings,
 					hints,
+					...(wantIdioms ? { idioms } : {}),
 					suppressed,
 					files: files.length,
 					...(changed ? { changed: true } : {}),
@@ -1418,6 +1468,7 @@ async function checkCommand(
 		console.log(
 			'[bitboss-ui] check: no .vue/.md files matched — nothing to do.'
 		);
+		printIdioms();
 		return;
 	}
 
@@ -1428,6 +1479,7 @@ async function checkCommand(
 		printSuppressed();
 		printWarnings();
 		printHints();
+		printIdioms();
 		return;
 	}
 
@@ -1466,6 +1518,7 @@ async function checkCommand(
 	);
 	printFindingLegend(findings);
 	printHints();
+	printIdioms();
 	process.exit(1);
 }
 
@@ -1481,7 +1534,8 @@ Commands:
                       project (AGENTS.md, Cursor rules, Copilot instructions,
                       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) —
+                      (.cursor/mcp.json), VS Code/Copilot (.vscode/mcp.json) and
+                      Zed (.zed/settings.json) —
                       merges, never overwrites other servers — and install its
                       optional peers with the project's package manager. Sets
                       \`vueCompilerOptions.checkUnknownComponents: true\` in the
@@ -1520,7 +1574,7 @@ Commands:
                       run add again. --yes is accepted and does nothing (the
                       commands never prompt).
   check [glob…] [--changed] [--json] [--allow-empty] [--allow-component <Name>]
-                      [--no-hints] [--manifest <path>] [--fix]
+                      [--no-hints] [--manifest <path>] [--fix] [--idioms]
                       Validate \`Bb*\` markup in .vue/.md files against the
                       installed components.json manifest (unknown/removed props,
                       bad v-models, unknown \`<template #slot>\` names,
@@ -1557,6 +1611,15 @@ Commands:
                       then reports what is left. Needs \`eslint\` and
                       \`vue-eslint-parser\` in the project.
 
+                      \`--idioms\` also lists the hand-rolled controls still in
+                      the app that the library ships (radio cards, segmented
+                      controls, sortable headers, steppers, app sheets, app
+                      confirms, …) with file:line and the replacement: the
+                      adoption checklist's own rows, run over .vue and script
+                      files. Report-only and opt-in: it never changes the exit
+                      code, and plain \`check\` never runs it. Guide:
+                      dist/ai/guides/migration/adoption-checklist.md.
+
                       Honours ESLint disable comments in .vue files: a finding
                       silenced for the matching \`bitboss-ui/*\` rule (or by a
                       bare \`eslint-disable\`) is not reported, only counted:
@@ -1586,7 +1649,8 @@ Commands:
 
                       \`--json\` prints \`{ findings: [...], warnings: [...], hints: [...],
                       suppressed, files, manifestVersion, installedVersion }\`
-                      (plus \`changed: true\` under \`--changed\`).
+                      (plus \`changed: true\` under \`--changed\`, and
+                      \`idioms: [{ file, line, id, use }]\` under \`--idioms\`).
                       Each finding: \`{ file, line, component, attr, kind,
                       message, hint?, to? }\` (plus \`fenceIndex\`/\`fenceInfo\`
                       inside a markdown fence; \`line\` is absolute in the file).
@@ -1816,6 +1880,7 @@ switch (command) {
 				fix: { type: 'boolean' },
 				manifest: { type: 'string' },
 				changed: { type: 'boolean' },
+				idioms: { type: 'boolean' },
 				// Accepted and ignored here — read straight off argv inside
 				// checkCommand, but parseArgs is strict, so it must be declared.
 				'no-hints': { type: 'boolean' },
@@ -1829,6 +1894,7 @@ switch (command) {
 			allowComponents: values['allow-component'] ?? [],
 			manifest: values.manifest,
 			changed: values.changed ?? false,
+			idioms: values.idioms ?? false,
 		});
 		break;
 	}

package/dist/ai/BbAlert.md

@@ -495,7 +495,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `close`, `icon`, `root`, `text`, `title`. States: —. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbAlertProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `close`, `icon`, `root`, `text`, `title`. States: `destructive`, `outline`, `primary`, `warning`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbAlertProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `ariaLive` | `"off" \| "polite" \| "assertive" \| undefined` |  |  | ARIA live region politeness. Unset, it follows `role` when you set one (`'alert'` → `'assertive'`, `'status'` → `'polite'`), else the variant: `'assertive'` for destructive/warning, otherwise `'polite'`. |
 | `closeLabel` | `string \| undefined` |  |  | Visually hidden string used to label the close button. |
 | `hideClose` | `boolean \| undefined` | `false` |  | Defines whether to hide the close button. |
@@ -521,6 +521,15 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 | `text` | The body copy. |
 | `close` | The ✕ that dismisses the alert. |
 
+States are listed in precedence order: when two are on at once and their entries conflict, the later one wins.
+
+| State | When it is on |
+| --- | --- |
+| `destructive` | Component-wide: `variant: 'destructive'`. Below the real states, like every variant. |
+| `outline` | Component-wide: `variant: 'outline'`. Merged after the part's base entry and before its states, so the real states still win. |
+| `primary` | Component-wide: `variant: 'primary'`. Below the real states, like every variant. |
+| `warning` | Component-wide: `variant: 'warning'`. Below the real states, like every variant. |
+
 ## Events
 
 - `update:modelValue` — `(value: boolean): void` — Emitted with the new value whenever `v-model` changes.

package/dist/ai/BbBadge.md

@@ -265,6 +265,13 @@ hidden accessible label — always supply it.
 </div>
 ```
 
+The slots named after the props (`#icon`, `#prepend:icon`, `#append:icon`)
+replace them and render inside the `icon` part, so `pt:icon`, `--icon-size`
+and the loading spinner still apply. Their scope is the badge's states,
+`{ activeLink, exactActiveLink, loading }`: a filter chip linking to a page
+can show a solid glyph while that page is open. What you put in a slot is
+yours: a `BbIcon` takes the part's size, anything else you size.
+
 ### Loading state
 
 Add `loading` to show a spinner on the badge. It takes the place of the
@@ -476,6 +483,16 @@ Three structural rules follow from the takeover:
 - **`append:icon` and the clear button stay outside** it, on the badge's
   trailing side. That is what keeps `clearable` compatible (below).
 
+A `BbBadgeButton` link's default slot gets `{ activeLink, exactActiveLink }`,
+as `BbBaseButton`'s does, and the link state reaches the whole chip: the
+badge's own parts (`pt:root:active-link`, …) and its icon slots. What renders
+outside the button (the badge's root, and on a `clearable` badge its trailing
+side: the append icon and the ✕) gets it only after hydration. The state is
+read in the `BbBadgeButton`, which renders after the badge's root, so a
+server-rendered page paints those plain and they switch once the page
+hydrates. The two renders agree, so there is no mismatch. Everything inside
+the button (the label, the leading icon) has it from the server on.
+
 #### Full `BbBaseButton` parity
 
 `BbBadgeButton` composes `BbBaseButton`, so the badge body accepts that
@@ -683,6 +700,12 @@ Both sides carry the pill's radius and inline padding, so each hit area runs
 extreme right edge presses the clear. The clear button's hit region spans the
 full pill height even though only the glyph's circle looks interactive.
 
+So the pill itself has no padding: `px-*` on the badge (or `pt:root`) does
+nothing. The side padding is two tokens, `--pad-left` / `--pad-right`, both
+derived from `--px`, which each size sets (an icon side takes 65% of it, the
+clear side 40%, an icon-only badge 35%). Rescale both sides with `--px`, or
+set one side directly, inline: `:style="{ '--px': '10px' }"`.
+
 Focus is always ringed on the **whole pill** (never on the inner control), for
 the body and the clear button alike; the clear button additionally lights its
 glyph. The class hooks above are the supported styling surface —
@@ -871,10 +894,10 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `clear`, `icon`, `root`, `spinner`, `text`. States: `loading`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbBadgeProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `clear`, `icon`, `root`, `spinner`, `text`. States: `activeLink`, `destructive`, `exactActiveLink`, `loading`, `outline`, `primary`, `secondary`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbBadgeProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `append:icon` | `string \| undefined` |  |  | Icon rendered after the label. On a `clearable` badge it shares the trailing slot with the clear button: the icon shows at rest and the clear button reveals over it on hover/focus. |
 | `clearable` | `boolean \| undefined` | `false` |  | Renders a trailing clear button and emits `click:clear` when pressed — turns the badge into a dismissible token (the pattern formerly served by `BbChip`). |
-| `clearableLabel` | `string \| undefined` |  |  | Accessible name of the clear button. Rarely needed: unset, it is composed from the localized `badge.clearLabel` verb and the badge text ("Remove Italy"), or the verb alone when a `BbBadgeButton` owns the body. |
+| `clearableLabel` | `string \| undefined` |  |  | Accessible name of the clear button, whole: set, it is the name on any body ("Remove the filter Deleted"). Rarely needed: unset, the name is composed from the localized `badge.clearLabel` verb and the badge text ("Remove Italy"), or the verb alone when a `BbBadgeButton` owns the body. |
 | `icon` | `string \| undefined` |  |  | Renders an icon-only badge. When set, `prepend:icon` / `append:icon` are ignored and the default slot becomes the badge's visually hidden accessible label — always provide it. |
 | `loading` | `boolean \| undefined` | `false` |  | Shows a spinner in place of the leftmost icon (`icon` or `prepend:icon`; the `append:icon` when it is the only one; else the leading slot), as `BbButton` does, with a hidden loading announcement. |
 | `prepend:icon` | `string \| undefined` |  |  | Icon rendered before the label. |
@@ -897,7 +920,13 @@ States are listed in precedence order: when two are on at once and their entries
 
 | State | When it is on |
 | --- | --- |
+| `activeLink` | Component-wide: the badge's `BbBadgeButton` is a link to the current page or one of its ancestors. The weakest state. |
+| `exactActiveLink` | Component-wide: the badge's `BbBadgeButton` is a link to the current page itself (`activeLink` is on too). |
 | `loading` | Component-wide: `loading` is on; the spinner takes an icon's place. |
+| `destructive` | Component-wide: `variant: 'destructive'`. Below the real states, like every variant. |
+| `outline` | Component-wide: `variant: 'outline'`. Below the real states, like every variant. |
+| `primary` | Component-wide: `variant: 'primary'`. Merged after the part's base entry and before its states, so the real states still win. |
+| `secondary` | Component-wide: `variant: 'secondary'`. Below the real states, like every variant. |
 
 ## Events
 
@@ -905,7 +934,10 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Slots
 
+- `append:icon` — scope: `BbBadgeIconSlotProps` `{ activeLink: boolean; exactActiveLink: boolean; loading: boolean }` — The trailing icon, replacing `append:icon`; inside the `icon` part.
 - `default` — scope: `object` — The badge's label content. When `icon` is set this becomes the visually hidden accessible label. Render a `BbBadgeButton` here to make the badge body interactive (the wrapper stays a passive `<span>`).
+- `icon` — scope: `BbBadgeIconSlotProps` `{ activeLink: boolean; exactActiveLink: boolean; loading: boolean }` — The glyph of an icon-only badge, replacing the `icon` prop. Renders inside the `icon` part: `pt:icon`, `--icon-size` and the loading spinner apply.
+- `prepend:icon` — scope: `BbBadgeIconSlotProps` `{ activeLink: boolean; exactActiveLink: boolean; loading: boolean }` — The leading icon, replacing `prepend:icon`; inside the `icon` part.
 
 ## CSS custom properties
 
@@ -944,7 +976,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 `BbBadge`'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 `BbBadge`'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 `manifest/components/BbBadge.tree.json`.
 
-- `BbBadge` _(this component)_ — its own template binds: `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`
+- `BbBadge` _(this component)_ — its own template binds: `spinner` → `BbSpinner`, `icon` → `span.bb-badge__append-icon`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`
   - Also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
 
 ## See Also

package/dist/ai/BbBadgeButton.md

@@ -12,7 +12,7 @@
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`. States: `disabled`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbBadgeButtonProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`. States: `activeLink`, `disabled`, `exactActiveLink`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbBadgeButtonProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `activeClass` | `string \| undefined` | `'router-link-active'` |  | 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` | `'page'` |  | 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` | `false` |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
@@ -66,6 +66,8 @@ States are listed in precedence order: when two are on at once and their entries
 
 | State | When it is on |
 | --- | --- |
+| `activeLink` | Component-wide: a link to the current page or one of its ancestors (`/users` on `/users/5`) — exactly when `activeClass` is on. The default slot gets it too, as `activeLink`. |
+| `exactActiveLink` | Component-wide: a link to the current page itself — exactly when `exactActiveClass` is on (`activeLink` is on too). The default slot gets it as `exactActiveLink`. |
 | `disabled` | Component-wide: the button is `disabled`. |
 
 ## Events
@@ -74,7 +76,7 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Slots
 
-- `default` — scope: `object` — The action's label — what the badge displays as its body.
+- `default` — scope: `BbLinkSlotProps` `{ activeLink: boolean; exactActiveLink: boolean }` — The action's label — what the badge displays as its body. A link's slot gets `{ activeLink, exactActiveLink }`, as on `BbBaseButton`.
 
 ## CSS custom properties
 

package/dist/ai/BbBaseButton.md

@@ -305,7 +305,11 @@ added on a path-prefix match, `exact-active-class` on an exact match (defaults
 (`to`), and ported by the library for `href` links — against the Inertia page
 under Inertia, or `window.location` in a plain app. On every platform the
 exact-active link also gets `aria-current` (default `page`, tune
-with `aria-current-value`). The [`BbButton` active-state
+with `aria-current-value`). The same match is the `activeLink` /
+`exactActiveLink` `pt` states (`pt:root:active-link="font-semibold"`) and the
+default slot's `{ activeLink, exactActiveLink }` props, so content can change
+with it (a solid icon on the current page); a `to` link takes vue-router's own
+answer for all three. The [`BbButton` active-state
 section](./BbButton.md) covers the matching rules in depth.
 
 Because the primitive attaches only the class name, an unstyled nav item is a
@@ -538,7 +542,7 @@ A `pt` value written in `<script>` (a constant, a preset, a wrapper's
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`. States: `disabled`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbBaseButtonProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`. States: `activeLink`, `disabled`, `exactActiveLink`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbBaseButtonProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `activeClass` | `string \| undefined` | `'router-link-active'` |  | 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` | `'page'` |  | 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` | `false` |  | Inertia: runs the visit without blocking — the page stays interactive and several async visits can be in flight at once. |
@@ -594,6 +598,8 @@ States are listed in precedence order: when two are on at once and their entries
 
 | State | When it is on |
 | --- | --- |
+| `activeLink` | Component-wide: a link to the current page or one of its ancestors (`/users` on `/users/5`) — exactly when `activeClass` is on. The default slot gets it too, as `activeLink`. |
+| `exactActiveLink` | Component-wide: a link to the current page itself — exactly when `exactActiveClass` is on (`activeLink` is on too). The default slot gets it as `exactActiveLink`. |
 | `disabled` | Component-wide: the button is `disabled`. |
 
 ## Events
@@ -602,7 +608,7 @@ States are listed in precedence order: when two are on at once and their entries
 
 ## Slots
 
-- `default` — scope: `object` — Primary content rendered inside the button element. Falls back to the `text` prop when empty.
+- `default` — scope: `BbLinkSlotProps` `{ activeLink: boolean; exactActiveLink: boolean }` — Primary content rendered inside the button element. Falls back to the `text` prop when empty.
 
 ## Component tree
 

package/dist/ai/BbBreadcrumbs.md

@@ -748,11 +748,11 @@ States are listed in precedence order: when two are on at once and their entries
   - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`
   - `BbDropdown` _(public — [contract](./BbDropdown.md))_ — its own pt parts (`BbDropdown`): `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `div.bb-dropdown__header`, `list` → `span.bb-dropdown__list`, `footer` → `div.bb-dropdown__footer`; documented CSS variables: `--menu-inset`; also mounts `CommonPopover`, `DropdownPipelineResolver`
     - `BbDropdownList` _(internal — not importable, reach it through `BbDropdown`)_ — also mounts `BbIcon`, `ErrorIcon`, `CommonPopover`, `BbDropdownList`
-      - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
+      - `BbBadge` _(public — [contract](./BbBadge.md))_ — its own pt parts (`BbBadge`): `spinner` → `BbSpinner`, `icon` → `span.bb-badge__append-icon`, `icon` → `BbIcon`, `clear` → `button.bb-badge__clear`; documented CSS variables: `--bg`, `--fg`, `--bw`, `--ring-color`, `--ring-size`, `--min-size-md`, `--min-size`, `--elev`, `--r`, `--fs`, `--icon-size`, `--gap`, `--px`, `--clear-size`, `--bg-disabled`, `--fg-disabled`, `--border-disabled`, `--pad-left`; also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`
     - `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__content`, `footer` → `div.bb-offcanvas__footer`; documented CSS variables: `--stack-x`, `--snap-y`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--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__text`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring-color`, `--ring-size`, `--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`
+      - `BbButton` _(public — [contract](./BbButton.md))_ — its own pt parts (`BbButton`): `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `span.bb-button__icon`, `icon` → `BbIcon`, `icon` → `span.bb-button__prepend-icon`, `text` → `span.bb-button__text`, `icon` → `span.bb-button__append-icon`; documented CSS variables: `--h-xs`, `--h`, `--icon-size`, `--px`, `--fs`, `--r`, `--gap`, `--bg`, `--bg-hover`, `--bg-pressed`, `--fg`, `--border-color`, `--ring-color`, `--ring-size`, `--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`
   - Also mounts `BbIcon`
 
 ## See Also