bitboss-ui 3.0.0-beta.21 → 3.0.0-beta.22

package/README.md

@@ -11,7 +11,8 @@ Published artifacts are **`dist/`** (ESM JavaScript, `.d.ts`, the two stylesheet
 ### 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`).
+- **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`). A reset is a **prerequisite** of the components, not a nicety: their sizes are written for `border-box`, and native controls and fieldsets are expected to arrive without their browser chrome. Use this one, or your own — Tailwind's Preflight covers it, which is why `resetCss` defaults to off. The component test suite runs against this file.
+- **Cascade layers (opt-in)** — on Tailwind v4 the library must sit in your layer order or its unlayered rules outrank every utility you put on a component. `cssLayers: TAILWIND_V4_LAYERS` in the build plugin (both exported from `bitboss-ui/vite`) places it after Preflight and before the utilities. Details in `ai/guides/installation-and-plugin-setup.md` § Cascade layers.
 
 ### TypeScript: use `vue-tsc` 3
 
@@ -181,6 +182,19 @@ export default defineConfig({
 });
 ```
 
+**Icons, in one paragraph.** `local:` ships every SVG in `iconDir`. Provider
+icons (`lucide:*`, `tabler:*`, any installed `@iconify-json/*` set) ship only
+what the plugin finds as a `prefix:name` literal anywhere in the project — it
+reads every file under the Vite root as bytes, PHP included, skipping only
+gitignored, hidden, binary, `node_modules`/`vendor`/`storage`/`outDir` and
+`iconsScanner.exclude` paths — plus whatever you list in `iconWhitelist`
+(exact names or globs, for names composed at runtime or stored in a database).
+This holds in dev exactly as in prod: dev registers the same set and re-scans a
+file on every save. A name that does not resolve renders a built-in placeholder
+(`data-bb-icon-missing="<name>"`) and logs one error with the fix; it never
+throws. Details: `ai/guides/icons-policy.md` and
+`ai/guides/installation-and-plugin-setup.md` § Icons.
+
 ### Nuxt module
 
 ```ts
@@ -241,8 +255,9 @@ combined — and nothing but the MCP server loads them, so installing
 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 —
+The agent harness launches the server itself (`node node_modules/bitboss-ui/bin/bitboss-ui.mjs mcp`,
+the installed binary rather than `npx`, so it can never fetch from the registry, its optional
+peers resolve in your project, and it cannot drift behind an upgrade) on demand —
 you never run it by hand. `--mcp` merges the server entry into each harness's
 own config (never overwriting other servers you've registered), and each write
 is idempotent:
@@ -360,6 +375,43 @@ is left alone. For a bulk sweep of a v2 codebase, opt into the fix:
 `assumeV2` is off by default because the two readings produce opposite
 layouts — turn it on only for files you know came from v2, then turn it off.
 
+#### The one rule that reads CSS: `no-unknown-token`
+
+`bitboss-ui/no-unknown-token` flags a bare `var(--bb-…)` naming a token the
+installed package does not declare, in a `<style>` block or a static
+`style="…"` attribute. It is a `warn`, like `no-unknown-event`.
+
+An invented token is not a near miss that degrades — CSS treats an undefined
+custom property as invalid-at-computed-value-time and throws away the **whole
+declaration**, so the rule silently does nothing and the element keeps whatever
+it inherited. One pilot lost a calendar grid's separators that way and read it
+as a layout bug.
+
+**A fallback disarms it**, because that is defined behaviour rather than a
+silent drop:
+
+```css
+.panel {
+	background: var(--bb-canvas); /* warns: no such token */
+	background: var(--bb-canvas, #f8fafc); /* fine: yours to define */
+}
+```
+
+The token list is read from the `dist/styles.css` you installed, so the rule
+can never claim a token is invented when your version declares it; with no
+stylesheet to read it stays silent. `allowTokens: string[]` exempts names you
+define yourself, and `stylesPath` points it at a different sheet.
+
+Remember the two tiers before reaching for a `--bb-*` name at all: `--bb-*` is
+the small global theme set, while each component declares its own **unprefixed**
+tokens (`.bb-table { --cell-h: 32px }`). A missing `--bb-*` name usually means
+the knob you want is a component token, not a gap in the library.
+
+Two sibling checks stay in `bitboss-ui check` and are deliberately **not**
+ESLint rules: the hand-rolled avatar and spinner hints. Those are guesses (a
+round `<img>` is sometimes a logo), and a lint rule that fires on correct code
+spends the trust the rest of these depend on.
+
 Every real HTML attribute (plus `aria-*` / `data-*`) falls through untouched, so
 attribute inheritance is never flagged. Escape hatches when you do need one:
 

package/bin/bitboss-ui-mcp.mjs

@@ -36,6 +36,7 @@ import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import {
 	loadManifest,
+	possessive,
 	validateVueSnippet,
 } from '../scripts/lib/validate-bb-markup.mjs';
 
@@ -70,26 +71,180 @@ function getManifestMap() {
 	return cachedManifestMap;
 }
 
-/** `search_components({ query })` — substring match over name/description. */
+/** `search_components({ query })` — token match over name/description. */
 const SEARCH_DEFAULT_LIMIT = 20;
 
 /**
- * Relevance score for one component against a lowercased needle. Higher wins;
+ * Ranking for the manifest's type tiers. `api` types are the ones an app is
+ * expected to reach for — they appear in a component's own props or events —
+ * so they lead. `wrapper` (`<Component>Props`) matters only when wrapping one
+ * of our components, and `advanced` is registries, contexts and adapters.
+ * Publishing 166 exports as a flat list made every one look equally important.
+ */
+const TYPE_USAGE_RANK = { api: 0, wrapper: 1, advanced: 2 };
+
+/**
+ * WHY THIS IS NOT A PLAIN SUBSTRING MATCH ANY MORE.
+ *
+ * It was, and a consumer pilot (2026-09-09) hand-rolled three components the
+ * library ships because the whole query string had to appear verbatim in one
+ * field. `table` found BbTable; `data table` — the term most of the industry
+ * uses — found NOTHING, because no name or description contains that exact
+ * pair. Same for `command palette`, `stepper wizard`, `skeleton loading`.
+ *
+ * An empty result is the worst possible answer for a tool whose stated job is
+ * "find the right Bb* component before writing usage code": it is
+ * indistinguishable from "nothing here, build it yourself". So two things
+ * changed. Multi-word queries are TOKENISED, and every search — hit or miss —
+ * consults the component picker's "Not in this library" table, which is where
+ * the authoritative answers for the invented names already lived.
+ */
+
+/** English filler that would otherwise match half the corpus on its own. */
+const SEARCH_STOPWORDS = new Set([
+	'a',
+	'an',
+	'the',
+	'and',
+	'or',
+	'not',
+	'no',
+	'is',
+	'it',
+	'in',
+	'on',
+	'for',
+	'of',
+	'to',
+	'with',
+	'component',
+	'components',
+	'ui',
+	'view',
+	'widget',
+	'element',
+]);
+
+/** `'data table view'` → `['data', 'table']`. Order is not significant. */
+function tokenize(query) {
+	const raw = String(query ?? '')
+		.toLowerCase()
+		.split(/[^a-z0-9]+/)
+		.filter(Boolean);
+	const meaningful = raw.filter((t) => !SEARCH_STOPWORDS.has(t));
+	// An all-stopword query ('the view') still deserves its literal reading
+	// rather than an empty token list that matches everything.
+	return meaningful.length > 0 ? meaningful : raw;
+}
+
+/**
+ * Relevance score for one component against ONE lowercased token. Higher wins;
  * 0 means "no match". Name hits always outrank description hits so
  * `search_components({ query: 'table' })` leads with BbTable, not with every
  * component whose prose mentions a table.
  */
-function scoreComponent(component, needle) {
+function scoreToken(component, needle) {
 	const name = component.name.toLowerCase();
 	const description = (component.description ?? '').toLowerCase();
 	if (name === needle) return 100;
 	if (name === `bb${needle}`) return 95; // 'button' → BbButton
 	if (name.startsWith(needle) || name.startsWith(`bb${needle}`)) return 80;
 	if (name.includes(needle)) return 60;
-	if (description.includes(needle)) return 30;
+	// Descriptions match at a WORD START, never mid-word: a plain substring made
+	// 'not' hit "notification" and returned four components for a nonsense
+	// query. Trailing suffixes still count, so 'card' finds "cards".
+	if (new RegExp(`\\b${needle}`).test(description)) return 30;
 	return 0;
 }
 
+/**
+ * Score against every token. A component that matches MORE of the query ranks
+ * above one that matches a single token harder, so `data table` puts BbTable
+ * (both tokens) above a component whose description merely says "data".
+ */
+function scoreComponent(component, tokens) {
+	let total = 0;
+	let matched = 0;
+	for (const token of tokens) {
+		const score = scoreToken(component, token);
+		if (score > 0) {
+			matched += 1;
+			total += score;
+		}
+	}
+	return matched === 0 ? { matched: 0, score: 0 } : { matched, score: total };
+}
+
+/**
+ * The picker's "Not in this library" table, parsed from the shipped guide so
+ * there is exactly one source of truth. Rows carry both kinds of answer:
+ * redirects (`BbDrawer` → "It is BbOffCanvas") and verdicts (`BbCard` → "Does
+ * not exist — a card is a <div> with tokens"). Both are better answers to a
+ * miss than an empty array.
+ */
+const PICKER_PATH = join(AI_ROOT, 'guides', 'component-picker.md');
+let cachedNotInLibrary = null;
+
+/** `'BbDataTable'` → `['bbdatatable', 'data', 'table']`. */
+function aliasTokens(cell) {
+	const words = cell
+		.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1') // links → their text
+		.replace(/[`*_]/g, '')
+		.split(/[^A-Za-z0-9]+/)
+		.filter(Boolean);
+	const tokens = new Set();
+	for (const word of words) {
+		tokens.add(word.toLowerCase());
+		// Split CamelCase so `BbDataTable` is reachable by 'data' and 'table'.
+		for (const part of word.replace(/^Bb/, '').split(/(?=[A-Z])/))
+			if (part.length > 1) tokens.add(part.toLowerCase());
+	}
+	return [...tokens].filter((t) => !SEARCH_STOPWORDS.has(t) && t !== 'bb');
+}
+
+function loadNotInLibrary() {
+	if (cachedNotInLibrary) return cachedNotInLibrary;
+	cachedNotInLibrary = [];
+	if (!existsSync(PICKER_PATH)) return cachedNotInLibrary;
+	const md = readFileSync(PICKER_PATH, 'utf-8');
+	const section = md.split(/^## Not in this library\s*$/m)[1];
+	if (!section) return cachedNotInLibrary;
+	for (const line of section.split('\n')) {
+		if (!line.startsWith('|')) continue;
+		// Tolerate a missing trailing `|`: markdown renders such a row fine, so
+		// dropping it here would silently lose an answer (it already did once).
+		const cells = line
+			.replace(/^\|/, '')
+			.replace(/\|\s*$/, '')
+			.split('|');
+		if (cells.length < 2) continue;
+		const assumed = cells[0].trim();
+		const reality = cells[1].trim();
+		// Skip the header and its `---` separator.
+		if (!assumed || /^-+$/.test(assumed) || /^Assumed\b/i.test(assumed))
+			continue;
+		cachedNotInLibrary.push({
+			assumed,
+			reality,
+			tokens: aliasTokens(assumed),
+		});
+	}
+	return cachedNotInLibrary;
+}
+
+/** Picker rows whose assumed-name cell shares a token with the query. */
+function matchNotInLibrary(tokens) {
+	const wanted = new Set(tokens);
+	return loadNotInLibrary()
+		.map((row) => ({
+			row,
+			hits: row.tokens.filter((t) => wanted.has(t)).length,
+		}))
+		.filter(({ hits }) => hits > 0)
+		.sort((a, b) => b.hits - a.hits)
+		.map(({ row }) => ({ assumed: row.assumed, reality: row.reality }));
+}
+
 function searchComponents({ query, limit, includeReferenceOnly } = {}) {
 	const manifest = loadComponentsManifest();
 	const needle = String(query ?? '')
@@ -104,13 +259,65 @@ function searchComponents({ query, limit, includeReferenceOnly } = {}) {
 		? manifest.components
 		: manifest.components.filter((c) => !c.referenceOnly);
 
+	const tokens = tokenize(needle);
+	const notInLibrary = matchNotInLibrary(tokens);
+
+	// A matched picker row NAMES the real component ("`BbDrawer` / `BbSheet` →
+	// It is BbOffCanvas"). Rank those first: the picker knows the answer, and
+	// returning nothing for `drawer` while BbOffCanvas ships is the whole bug.
+	const redirected = new Set();
+	for (const { reality } of notInLibrary)
+		for (const name of reality.match(/\bBb[A-Z][A-Za-z]+/g) ?? [])
+			redirected.add(name);
+
 	const scored = pool
-		.map((c) => ({ c, score: scoreComponent(c, needle) }))
+		.map((c) => {
+			const base = scoreComponent(c, tokens);
+			const bonus = redirected.has(c.name) ? 90 : 0;
+			return bonus > 0
+				? { c, matched: base.matched + 1, score: base.score + bonus }
+				: { c, ...base };
+		})
 		.filter(({ score }) => score > 0)
-		// Ties break alphabetically so results are stable between calls.
-		.sort((a, b) => b.score - a.score || a.c.name.localeCompare(b.c.name));
+		// More of the query matched wins first; then strength; then alphabetical
+		// so results are stable between calls.
+		.sort(
+			(a, b) =>
+				b.matched - a.matched ||
+				b.score - a.score ||
+				a.c.name.localeCompare(b.c.name)
+		);
 
 	const shown = scored.slice(0, max);
+
+	/**
+	 * Public type exports whose name matches the query. Scored the same way as
+	 * a component name (exact, prefix, substring) but never mixed into the
+	 * component list — a type is not something you render, and ranking it
+	 * beside components is how it gets written as a tag.
+	 */
+	const matchedTypes = (manifest.types ?? [])
+		.filter((type) => {
+			const lower = type.name.toLowerCase();
+			return tokens.some(
+				(token) => lower === token || lower.includes(token.toLowerCase())
+			);
+		})
+		// `api` first: those are the types you meet writing markup. The rest are
+		// wrapper props and internals, which rank below anything you would use.
+		.sort((a, b) => TYPE_USAGE_RANK[a.usage] - TYPE_USAGE_RANK[b.usage])
+		.slice(0, max)
+		.map((type) => ({
+			name: type.name,
+			kind: 'type',
+			usage: type.usage,
+			component: type.component,
+			...(type.deprecated ? { deprecated: true } : {}),
+			...(type.replacedBy ? { replacedBy: type.replacedBy } : {}),
+			usedBy: type.usedBy ?? [],
+			import: `import type { ${type.replacedBy ?? type.name} } from 'bitboss-ui';`,
+		}));
+
 	return {
 		query: query ?? '',
 		count: shown.length,
@@ -128,6 +335,23 @@ function searchComponents({ query, limit, includeReferenceOnly } = {}) {
 			referenceOnly: Boolean(c.referenceOnly),
 			contract: c.contract,
 		})),
+		// Authoritative answers for names agents invent. Present on hits too: a
+		// `card` query that ranks BbBaseButton (its description mentions cards)
+		// still needs the picker's verdict that there is no BbCard.
+		...(notInLibrary.length > 0 ? { notInLibrary } : {}),
+		// A query that names a public TYPE gets it back as a type, so the answer
+		// to "is BbTableColumn a thing" is never an empty component list. The
+		// consumer who hit this concluded the export was undocumented and
+		// allowlisted the tag.
+		...(matchedTypes.length > 0 ? { types: matchedTypes } : {}),
+		guidance:
+			notInLibrary.length > 0
+				? 'The `notInLibrary` entries are the authoritative answer for this query — prefer them over the ranked components, and do not hand-roll what they redirect you to.'
+				: shown.length > 0
+					? 'Ranked by relevance. Confirm props with `get_component` before writing usage code.'
+					: matchedTypes.length > 0
+						? 'No component matches, but `types` does: these are TYPE exports. Import one for the value you pass to the prop named in its `usedBy` — never write it as a tag, and never allowlist it.'
+						: 'No manifest match and no picker entry. Zero results does NOT mean "not covered" — search a single plain noun (`table`, not `data table`), then read the guide `component-picker` (its "Not in this library" table is the full list of names that do not exist and what to use instead) before building anything by hand.',
 	};
 }
 
@@ -180,6 +404,32 @@ function getComponent({ name, maxChars } = {}) {
 	const manifest = loadComponentsManifest();
 	const entry = manifest.components.find((c) => c.name === name);
 	if (!entry) {
+		/*
+		 * A public TYPE asked for as a component. `BbTableColumn`,
+		 * `BbDropdownItem`, `BbTabsItem` and `BbBreadcrumbsItem` are exports an
+		 * agent meets in a props table and reasonably looks up here; answering
+		 * "unknown component — try search_components" sent one consumer to the
+		 * `allowComponents` allowlist instead, which silences every check on the
+		 * tag. Answer the real question: what it is, and where it is used.
+		 */
+		const type = (manifest.types ?? []).find((t) => t.name === name);
+		if (type) {
+			const use = type.usedBy?.[0];
+			return {
+				found: true,
+				kind: 'type',
+				name,
+				usage: type.usage,
+				...(type.deprecated ? { deprecated: true } : {}),
+				...(type.replacedBy ? { replacedBy: type.replacedBy } : {}),
+				component: type.component,
+				usedBy: type.usedBy ?? [],
+				import: `import type { ${type.replacedBy ?? name} } from 'bitboss-ui';`,
+				hint: use
+					? `A type, not a component: it types ${possessive(use.component)} \`${use.name}\` ${use.surface}. Call get_component('${use.component}') for the contract that documents its fields.`
+					: 'A type, not a component — import it for the value you pass, never write it as a tag.',
+			};
+		}
 		return {
 			found: false,
 			name,
@@ -199,10 +449,31 @@ function getComponent({ name, maxChars } = {}) {
 		maxChars,
 		`The structured \`component\` field above is COMPLETE (all props/events/slots) — the cut text is guidance prose only.`
 	);
+	/*
+	 * The types this component's own API names, so "what do I import to build
+	 * the value for `columns`?" is answered where the question is asked. Without
+	 * it an agent reads `BbTableColumn<T>[]` in the props table and has nowhere
+	 * to go — one consumer concluded the export was undocumented and allowlisted
+	 * the tag. Only types the component actually uses, never the whole export
+	 * list: a menu is not an answer.
+	 */
+	const types = (manifest.types ?? [])
+		.filter((type) =>
+			(type.usedBy ?? []).some((use) => use.component === entry.name)
+		)
+		.filter((type) => !type.deprecated)
+		.map((type) => ({
+			name: type.name,
+			usage: type.usage,
+			usedBy: (type.usedBy ?? []).filter((use) => use.component === entry.name),
+			import: `import type { ${type.name} } from 'bitboss-ui';`,
+		}));
+
 	return {
 		found: true,
 		// Never truncated: the precision-critical surface.
 		component: entry,
+		...(types.length > 0 ? { types } : {}),
 		contractPath,
 		contractContent: content,
 		...meta,
@@ -469,6 +740,109 @@ function validateCode({ code } = {}) {
  * becomes an `isError` result carrying `Error: <message>` — preserving the
  * exact result shape of the previous hand-rolled dispatch.
  */
+const CHANGELOG_PATH = join(AI_ROOT, 'changelog.json');
+
+/**
+ * Order two versions on this library's line: `3.0.0-beta.21` after
+ * `3.0.0-beta.9` (numeric, not lexical — the bug every hand-rolled compare
+ * has), and any prerelease before its own stable release.
+ */
+function compareVersions(a, b) {
+	const parse = (v) => {
+		const [core, pre = ''] = String(v).split('-');
+		const nums = core.split('.').map((n) => Number.parseInt(n, 10) || 0);
+		const [tag = '', n = ''] = pre.split('.');
+		return { nums, tag, n: Number.parseInt(n, 10) || 0 };
+	};
+	const x = parse(a);
+	const y = parse(b);
+	for (let i = 0; i < 3; i += 1) {
+		if ((x.nums[i] ?? 0) !== (y.nums[i] ?? 0))
+			return (x.nums[i] ?? 0) - (y.nums[i] ?? 0);
+	}
+	// No prerelease tag outranks any prerelease of the same core version.
+	if (!x.tag && y.tag) return 1;
+	if (x.tag && !y.tag) return -1;
+	if (x.tag !== y.tag) return x.tag < y.tag ? -1 : 1; // alpha < beta < rc
+	return x.n - y.n;
+}
+
+/**
+ * `list_changes({ since, until })` — the breaking changes between two releases.
+ *
+ * WHY THIS TOOL EXISTS. A consumer agent on 2026-09-09 asked "what changed
+ * between beta.20 and beta.21?", found nothing in the knowledge base that could
+ * answer it, and diffed the two published tarballs by hand. The data existed
+ * (`dist/ai/changelog.json`) but no tool served it, and its rows carried no
+ * release, so even reading the file could not have answered the question. Both
+ * halves are fixed: rows are stamped with `firstReleasedIn` at build time, and
+ * this serves the slice.
+ */
+function listChanges({ since, until } = {}) {
+	if (!existsSync(CHANGELOG_PATH)) {
+		return {
+			error: `changelog.json not found at ${CHANGELOG_PATH} — reinstall bitboss-ui (or run \`npm run build\` when working in the library repo).`,
+		};
+	}
+	const doc = JSON.parse(readFileSync(CHANGELOG_PATH, 'utf-8'));
+	const releases = doc.releases ?? [];
+	const known = new Set(releases);
+
+	// A typo'd version must not silently return "nothing changed" — that reads
+	// as a clean upgrade and is the worst possible wrong answer here.
+	for (const [label, value] of [
+		['since', since],
+		['until', until],
+	]) {
+		if (value != null && !known.has(String(value))) {
+			return {
+				error: `Unknown ${label} version '${value}'.`,
+				knownReleases: releases,
+				hint: 'Pass a version exactly as listed in knownReleases, or omit both to get every break in the v2 → v3 upgrade.',
+			};
+		}
+	}
+
+	const all = doc.breaking ?? [];
+	// No range asked for: the whole v2 → v3 set, which is what the file has
+	// always meant.
+	if (since == null && until == null) {
+		return {
+			version: doc.version,
+			upgrade: doc.upgrade,
+			guide: doc.guide,
+			releases,
+			summary: doc.summary,
+			count: all.length,
+			breaking: all,
+			hint: 'Narrow to one upgrade hop with list_changes({ since: "<your current version>" }) — that answers "what breaks if I bump".',
+		};
+	}
+
+	const inRange = all.filter((entry) => {
+		const at = entry.firstReleasedIn;
+		// Unreleased rows belong to the future: they ship in whatever comes
+		// next, so they count only when the caller left `until` open.
+		if (at == null) return until == null;
+		if (since != null && compareVersions(at, String(since)) <= 0) return false;
+		if (until != null && compareVersions(at, String(until)) > 0) return false;
+		return true;
+	});
+
+	return {
+		version: doc.version,
+		since: since ?? null,
+		until: until ?? doc.version,
+		count: inRange.length,
+		breaking: inRange,
+		guide: doc.guide,
+		hint:
+			inRange.length === 0
+				? 'No breaking changes recorded in that range — features and fixes are deliberately not tracked here, so an empty result means nothing BREAKS, not that nothing changed.'
+				: 'Each entry names the component and the new spelling; `guide` is the migration page with the full explanation.',
+	};
+}
+
 function toolCallback(fn) {
 	return (args) => {
 		try {
@@ -500,7 +874,7 @@ function buildServer() {
 		'search_components',
 		{
 			description:
-				'Search the bitboss-ui component manifest by name and description, ranked by relevance (exact/prefix name matches first, description matches last). Returns consumer-API components only by default. Use this to find the right Bb* component before writing usage code.',
+				'Search the bitboss-ui component manifest by name and description, ranked by relevance (exact/prefix name matches first, description matches last). Multi-word queries are matched per word, so "data table" finds BbTable. Also returns `notInLibrary`: the component picker\'s authoritative verdicts for names agents commonly invent — either a redirect ("BbDrawer" is BbOffCanvas) or a confirmation that it does not exist and what to do instead. Returns consumer-API components only by default. Use this to find the right Bb* component before writing usage code. An empty result does NOT mean the need is uncovered — read the `component-picker` guide before hand-rolling anything.',
 			inputSchema: {
 				query: z
 					.string()
@@ -571,6 +945,29 @@ function buildServer() {
 		toolCallback(listGuides)
 	);
 
+	server.registerTool(
+		'list_changes',
+		{
+			description:
+				'Breaking changes between two bitboss-ui releases — what breaks if you bump. Call with since=<the version you are on> before upgrading. Omit both arguments for every break in the v2 → v3 upgrade. Only BREAKING changes are tracked; features and fixes are not.',
+			inputSchema: {
+				since: z
+					.string()
+					.optional()
+					.describe(
+						"Exclusive lower bound — the version you are currently on, e.g. '3.0.0-beta.20'. Its own breaks are excluded; you already have them."
+					),
+				until: z
+					.string()
+					.optional()
+					.describe(
+						'Inclusive upper bound (default: the installed version). Unreleased breaks are included only when this is omitted.'
+					),
+			},
+		},
+		toolCallback(listChanges)
+	);
+
 	server.registerTool(
 		'get_guide',
 		{
@@ -659,8 +1056,21 @@ export async function main() {
 	const server = buildServer();
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
+	// Settle on stdin's end as well as the transport's close. `onclose` does
+	// not fire when the host simply closes the pipe, so awaiting it alone left
+	// the caller's top-level `await main()` pending at exit and Node printed
+	// "Detected unsettled top-level await" on every clean shutdown (2026-09-09).
+	// `once` on both, and idempotent resolve, so whichever arrives first wins.
 	return new Promise((resolve) => {
-		transport.onclose = () => resolve();
+		let done = false;
+		const settle = () => {
+			if (done) return;
+			done = true;
+			resolve();
+		};
+		transport.onclose = settle;
+		process.stdin.once('end', settle);
+		process.stdin.once('close', settle);
 	});
 }