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

package/bin/bitboss-ui-mcp.mjs

@@ -25,7 +25,8 @@
  * is stable across zod 3 and 4, so the lower bound costs nothing.
  *
  * Run standalone: `npx bitboss-ui mcp` (delegated from bin/bitboss-ui.mjs).
- * Register with an MCP-capable harness via `npx bitboss-ui ai-init --mcp`.
+ * Registered with every MCP-capable harness by `npx bitboss-ui ai-init`
+ * (on by default; `--no-mcp` skips it).
  */
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -36,6 +37,7 @@ import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import {
 	loadManifest,
+	possessive,
 	validateVueSnippet,
 } from '../scripts/lib/validate-bb-markup.mjs';
 
@@ -70,26 +72,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 +260,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 +336,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 +405,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 +450,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,
@@ -219,16 +491,53 @@ const STYLES_CSS = join(PACKAGE_ROOT, 'dist', 'styles.css');
  * every comma-part is built solely from these — `:root`, `.light`, `:root.dark`
  * and `html.dark` are theme roots; `.bb-tooltip .bb-common-popover__bubble` is
  * not, however many `--bb-*` it redeclares.
+ *
+ * `.bb-theme` is a theme root too: it is the island boundary the derived block
+ * re-specifies its formulas on (design-tokens.md § the CSS mechanic).
+ */
+const THEME_ROOT_PART = /^(?::root|html|body|\.light|\.dark|\.bb-theme)+$/;
+
+/**
+ * Unwrap the `:where(…)` / `:is(…)` a selector list may be wrapped in. The
+ * derived-token block ships as `:where(:root,.light,.dark,.bb-theme)`, and
+ * splitting THAT on commas yields `:where(:root` and `.bb-theme)` — neither of
+ * which is a theme root, so without this every derived token is misreported as
+ * a component rebind with no value. That is not a cosmetic slip: `localRebinds`
+ * is documented to agents as "not something to copy".
  */
-const THEME_ROOT_PART = /^(?::root|html|body|\.light|\.dark)+$/;
+function unwrapSelectorList(selector) {
+	const trimmed = selector.trim();
+	const match = /^:(?:where|is)\((.*)\)$/s.exec(trimmed);
+	return match ? match[1] : trimmed;
+}
+
 function isThemeSelector(selector) {
-	return selector
+	return unwrapSelectorList(selector)
 		.split(',')
 		.every((part) =>
 			THEME_ROOT_PART.test(part.replace(/[\s>+~]+/g, '').trim())
 		);
 }
 
+/**
+ * A theme token is a KNOB (the consumer sets it) or DERIVED (a formula the
+ * library recomputes at every theme boundary). Setting a derived value is the
+ * documented trap — it stops tracking the knob it was computed from.
+ *
+ * The split is structural in the shipped sheet, so it needs no curated list to
+ * drift: knobs are declared on the plain scheme roots, formulas inside the
+ * `:where(…)` boundary block. A name in BOTH is a knob that TRACKS another one
+ * until pinned — and because the boundary block re-specifies it, a pin has to
+ * be repeated at every boundary it is used on, `.dark` included.
+ */
+const isDerivedBlock = (selector) => /^:(?:where|is)\(/.test(selector.trim());
+const tokenKind = (inKnobBlock, inDerivedBlock) =>
+	inKnobBlock && inDerivedBlock
+		? 'knob-tracking'
+		: inDerivedBlock
+			? 'derived'
+			: 'knob';
+
 /**
  * Walk a stylesheet and yield every `--bb-*` declaration WITH the selector that
  * owns it. A flat regex cannot do this: it sees a declaration but not its
@@ -281,7 +590,8 @@ function* eachTokenDeclaration(css) {
  * different components and is only meaningful inside that component's scope.
  * Serving them as one flat list would invite exactly the wrong move — an agent
  * writing `:root { --gap: … }` and wondering why nothing changed. They are
- * documented per component, which `get_component` already serves.
+ * documented per component: `get_component` carries them as `cssProps`, each
+ * with the root class to set it on, its default, and what it is.
  *
  * WHY `dist/styles.css` AND NOT `src/assets/css/variables.css`: `src/` is not
  * in the published package, so the source file does not exist for the consumer
@@ -302,8 +612,15 @@ function listTokens({ filter } = {}) {
 	const css = readFileSync(STYLES_CSS, 'utf-8');
 	const byName = new Map();
 	for (const { name, value, selector } of eachTokenDeclaration(css)) {
-		const entry = byName.get(name) ?? { theme: [], local: [] };
+		const entry = byName.get(name) ?? {
+			theme: [],
+			local: [],
+			knobBlock: false,
+			derivedBlock: false,
+		};
 		if (isThemeSelector(selector)) {
+			if (isDerivedBlock(selector)) entry.derivedBlock = true;
+			else entry.knobBlock = true;
 			// Light first, dark after: report both rather than let one win.
 			if (!entry.theme.includes(value)) entry.theme.push(value);
 		} else if (!entry.local.some((r) => r.selector === selector)) {
@@ -320,8 +637,9 @@ function listTokens({ filter } = {}) {
 	const tokens = [...byName.entries()]
 		.filter(([name]) => !needle || name.toLowerCase().includes(needle))
 		.sort(([a], [b]) => a.localeCompare(b))
-		.map(([name, { theme, local }]) => ({
+		.map(([name, { theme, local, knobBlock, derivedBlock }]) => ({
 			name,
+			kind: tokenKind(knobBlock, derivedBlock),
 			value: theme[0],
 			...(theme.length > 1 ? { themeOverrides: theme.slice(1) } : {}),
 			...(local.length > 0 ? { localRebinds: local } : {}),
@@ -333,7 +651,7 @@ function listTokens({ filter } = {}) {
 		hint:
 			needle && tokens.length === 0
 				? `No token name contains '${needle}'. Call list_tokens with no filter for all ${byName.size} — the names are semantic (primary/danger/panel/text/border/radius/…), not literal colours.`
-				: 'Theme tokens are set by the consumer app (e.g. on :root / .dark); `themeOverrides` is the dark-theme value. `localRebinds` is a component rebinding the token inside its own subtree — not something to copy. Component-level unprefixed tokens are documented per component; see the design-tokens guide via get_guide.',
+				: 'Theme tokens are set by the consumer app (e.g. on :root / .dark); `themeOverrides` is the dark-theme value. `localRebinds` is a component rebinding the token inside its own subtree — not something to copy. `kind` says what you may set: "knob" is yours; "derived" is a formula recomputed at every theme boundary, so setting it stops it tracking the knob it came from — set that knob instead; "knob-tracking" is a knob that follows another until you pin it, and the pin must be repeated at every boundary you use, .dark included. Component-level unprefixed tokens are documented per component; see the design-tokens guide via get_guide.',
 	};
 }
 
@@ -469,6 +787,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 +921,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()
@@ -517,7 +938,7 @@ function buildServer() {
 					.boolean()
 					.optional()
 					.describe(
-						'Include reference-only internal components (BbBase*, Common*). Default false — these are not consumer API and should not be recommended.'
+						'Include reference-only internal components (Common*, listbox internals). Default false — these are not consumer API and should not be recommended. BbBaseButton and the BbBase*Icon glyphs are consumer API and are always included.'
 					),
 			},
 		},
@@ -571,6 +992,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 +1103,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);
 	});
 }