bitboss-ui 3.0.0-beta.42 → 3.0.0-beta.44

package/README.md

@@ -127,7 +127,7 @@ magnitude, not a contract.
 
 - [Core knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-medium.txt) (about 200 KB) — **start here if you can only fetch one file.** Hard rules, setup, component picker, design language, and the full component catalogue.
 - [Index](https://llms-bitboss-ui.bitboss.it/llms.txt) (about 20 KB) — link index into every document.
-- [components.json](https://llms-bitboss-ui.bitboss.it/dist/ai/components.json) — machine-readable API surface, for programmatic validation.
+- [Component API files](https://llms-bitboss-ui.bitboss.it/dist/ai/manifest/index.json) — machine-readable API, one file per component (`manifest/components/<Name>.json`), each one read. The same data in one file for tools: [components.json](https://llms-bitboss-ui.bitboss.it/dist/ai/components.json) (about 1.2 MB).
 - [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt) (about 5 MB) — everything concatenated. Bulk ingestion only; too large to prompt with.
 
 Already installed? Prefer the local copy under `node_modules/bitboss-ui/dist/ai/`,
@@ -327,13 +327,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…] [--fix] [--json]`                          | Validates `Bb*` markup in `.vue` / `.md` files against the installed version; `--fix` applies the v2 → v3 renames first. |
-| `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] [--json]`             | Validates `Bb*` markup in `.vue` / `.md` files against the installed version; `--fix` applies the v2 → v3 renames first; `--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.                                                                                                                                                                               |
 
 ### ESLint plugin
 
@@ -482,6 +482,9 @@ still name the button:
 ```
 
 `BbSpinner` is not covered: without `label` it is decorative, which is correct.
+A `BbBadge` or `BbProgress` marked `aria-hidden="true"` (or `:aria-hidden="true"`)
+is decorative too and is skipped (a `BbButton` is not: it stays focusable); a dynamic `:aria-hidden="flag"` is still checked, since it
+needs a name whenever it is `false`.
 For raw HTML controls, use `eslint-plugin-vuejs-accessibility`.
 
 #### v-model on a const reactive(): `no-reactive-v-model`
@@ -617,7 +620,8 @@ A standard `llms.txt` discovery file is also published at:
 | ------------------------------------- | ------------------------------------------------------------------------------------ |
 | `dist/ai/guides/ai-router.md`         | **Start here** — which file to open next                                             |
 | `dist/ai/index.md`                    | Full catalogue + agent rules                                                         |
-| `dist/ai/components.json`             | Machine-readable API (props/events/slots)                                            |
+| `dist/ai/manifest/index.json`         | Machine-readable API for agents: the component list → `components/<Name>.json`       |
+| `dist/ai/components.json`             | The same API in one file, for tools (`check`, ESLint, MCP)                           |
 | `dist/ai/<ComponentName>.md`          | Guide-first contract per component                                                   |
 | `dist/ai/composables/<name>.md`       | Composable docs                                                                      |
 | `dist/ai/guides/agent-contract.md`    | Mandatory agent rules                                                                |
@@ -636,6 +640,7 @@ files directly:
 | ----------------------------------- | ------------------------------ |
 | `bitboss-ui/ai`                     | `dist/ai/index.md` (catalogue) |
 | `bitboss-ui/ai/components.json`     | `dist/ai/components.json`      |
+| `bitboss-ui/ai/manifest/index.json` | `dist/ai/manifest/index.json`  |
 | `bitboss-ui/ai/guides/ai-router.md` | `dist/ai/guides/ai-router.md`  |
 
 Agents can also read paths under `node_modules/bitboss-ui/dist/ai/` directly.

package/bin/bitboss-ui-mcp.mjs

@@ -31,7 +31,7 @@
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
@@ -48,6 +48,10 @@ import {
 	possessive,
 	validateVueSnippet,
 } from '../scripts/lib/validate-bb-markup.mjs';
+import {
+	agentComponent,
+	firstSentence,
+} from '../scripts/lib/agent-manifest.mjs';
 
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 const AI_ROOT = join(PACKAGE_ROOT, 'dist', 'ai');
@@ -65,19 +69,38 @@ function packageVersion() {
 	}
 }
 
+/*
+ * Parsed once per build of components.json (Q56.46): the 1.2 MB file was
+ * re-read and re-parsed on every tool call. Both caches below (the raw
+ * manifest for the lookup tools, the validator's map for `validate`) are
+ * keyed on the file's mtime, so a rebuild under a running server (library
+ * repo, `npm run build`) is picked up by every tool.
+ */
+let cachedManifest = null;
 function loadComponentsManifest() {
 	if (!existsSync(MANIFEST_PATH)) {
 		throw new Error(
 			`components.json not found at ${MANIFEST_PATH} — reinstall bitboss-ui (or run \`npm run build\` when working in the library repo).`
 		);
 	}
-	return JSON.parse(readFileSync(MANIFEST_PATH, 'utf-8'));
+	const mtime = statSync(MANIFEST_PATH).mtimeMs;
+	if (cachedManifest?.mtime !== mtime)
+		cachedManifest = {
+			mtime,
+			value: JSON.parse(readFileSync(MANIFEST_PATH, 'utf-8')),
+		};
+	return cachedManifest.value;
 }
 
 let cachedManifestMap = null;
 function getManifestMap() {
-	cachedManifestMap ??= loadManifest(MANIFEST_PATH);
-	return cachedManifestMap;
+	// Missing file: loadManifest throws the install hint.
+	const mtime = existsSync(MANIFEST_PATH)
+		? statSync(MANIFEST_PATH).mtimeMs
+		: null;
+	if (cachedManifestMap?.mtime !== mtime || mtime === null)
+		cachedManifestMap = { mtime, value: loadManifest(MANIFEST_PATH) };
+	return cachedManifestMap.value;
 }
 
 /** `search_components({ query })` — token match over name/description. */
@@ -745,43 +768,9 @@ const SUMMARY_SECTIONS = [/^gotchas/i];
  * keeps EVERY name (a partial prop list is what makes agents invent API) as one
  * line — name, type, default, the description's first sentence — and marks a
  * cut sentence with " …": `members: ['name']` returns the full row.
+ * `firstSentence` lives in scripts/lib/agent-manifest.mjs: the manifest
+ * index (Q56.46) cuts descriptions the same way.
  */
-function firstSentence(text, cap = 160) {
-	const flat = String(text ?? '')
-		.replace(/\s+/g, ' ')
-		.trim();
-	if (!flat) return '';
-	// A sentence ends at ". " before a capital, a backtick or a bracket — not
-	// inside "1.234,56", "v3.0.0" or after "e.g." / "i.e." / "etc.".
-	const ends = [...flat.matchAll(/[.!?](?=\s+[A-Z`([]|$)/g)]
-		.map((m) => m.index)
-		.filter((i) => !/\b(e\.g|i\.e|etc|vs|approx)$/i.test(flat.slice(0, i)));
-	let stop = ends[0] ?? flat.length - 1;
-	// A second sentence that limits the first ("Only …", "Ignored with …",
-	// "Not called in …") changes what the first one means: keep it.
-	const next = flat.slice(stop + 1).trim();
-	if (
-		ends[1] != null &&
-		/^(Only|Not|Never|Ignored|Mutually|Takes precedence|Requires|Must|Has no effect|Without|Unless|Deprecated|Wins over|Overrides)\b/.test(
-			next
-		)
-	)
-		stop = ends[1];
-	// A short, generic first sentence ("The id.") says little: add the next.
-	if (stop + 1 < 60 && ends[ends.indexOf(stop) + 1] != null)
-		stop = ends[ends.indexOf(stop) + 1];
-	let out = flat.slice(0, stop + 1);
-	if (out.length > cap) {
-		let cut = out.lastIndexOf(' ', cap);
-		if (cut < 40) cut = cap;
-		let head = out.slice(0, cut);
-		// Never end inside a code span: an unpaired backtick reads as code.
-		if ((head.match(/`/g) ?? []).length % 2)
-			head = head.slice(0, head.lastIndexOf('`')).trimEnd();
-		out = `${head} …`;
-	} else if (out.length < flat.length) out += ' …';
-	return out;
-}
 
 /** A type as the summary prints it: no ` | undefined` tail, long ones cut. */
 function shortType(type, cap = 180) {
@@ -902,6 +891,96 @@ function historyLines(entry) {
 	];
 }
 
+/**
+ * Q57.6: the `css.classes` of the internal parts a component mounts
+ * (`CommonPopover`, `CommonField`, the listboxes), by part. The class surface
+ * lists a block once, on its owner, and an internal owner is no component a
+ * consumer asks about: `.bb-common-popover__bubble` was on no BbDropdown or
+ * BbPopover answer. A public child (BbBaseButton) answers for its own.
+ */
+function internalClasses(entry, manifest) {
+	const byName = new Map(manifest.components.map((c) => [c.name, c]));
+	const out = {};
+	const walk = (nodes = []) => {
+		for (const node of nodes) {
+			if (node.kind !== 'internal') continue;
+			const classes = byName.get(node.name)?.css?.classes;
+			if (classes && !out[node.name]) out[node.name] = classes;
+			walk(node.children);
+		}
+	};
+	walk(entry.tree?.nodes);
+	return out;
+}
+
+/** `css` of a get_component answer: its own classes, plus `shared` (Q57.6). */
+function cssAnswer(entry, manifest) {
+	const shared = internalClasses(entry, manifest);
+	return Object.keys(shared).length ? { ...entry.css, shared } : entry.css;
+}
+
+/** Every `.bb-*` block a component renders, its own and its internal parts'. */
+function renderedBlocks(entry, manifest) {
+	return new Set([
+		...Object.keys(entry.css?.classes ?? {}),
+		...Object.values(internalClasses(entry, manifest)).flatMap(Object.keys),
+	]);
+}
+
+/**
+ * Q57.7: does a changelog row reach this component? By name, or — for a CSS
+ * rename (`surface: cssVar | class`), whose Component cell is a selector
+ * (`.bb-table`) or prose ("every form control") — by a `.bb-*` block of the
+ * row the component renders: `--padding-y → --py` on `.bb-table` never
+ * reached BbTable's history or `list_changes({ component: 'BbTable' })`.
+ */
+function rowReaches(row, name, blocks) {
+	if (
+		(row.components ?? []).some((c) => c.toLowerCase() === name.toLowerCase())
+	)
+		return true;
+	if (!blocks || (row.surface !== 'cssVar' && row.surface !== 'class'))
+		return false;
+	const text = [...(row.components ?? []), row.from, row.to].join(' ');
+	return [...text.matchAll(/\.(bb-[a-z0-9]+(?:-[a-z0-9]+)*)/g)].some((m) =>
+		blocks.has(m[1])
+	);
+}
+
+/** The CSS renames (cssVar, class) that reach a component, one line each. */
+function cssRenameLines(entry, manifest) {
+	if (!existsSync(CHANGELOG_PATH)) return [];
+	const doc = JSON.parse(readFileSync(CHANGELOG_PATH, 'utf-8'));
+	const blocks = renderedBlocks(entry, manifest);
+	return (doc.breaking ?? [])
+		.filter(
+			(row) =>
+				(row.surface === 'cssVar' || row.surface === 'class') &&
+				rowReaches(row, entry.name, blocks)
+		)
+		.map(
+			(row) =>
+				`${/^f\d/.test(row.id) ? `${row.id} ` : ''}${row.surface} ${row.from} → ${row.to ?? 'removed'}${row.firstReleasedIn ? ` (${row.firstReleasedIn})` : ''}`
+		);
+}
+
+/**
+ * The history lines, plus the CSS locals renamed on the component's blocks;
+ * the class renames only as a count (include: ['history'] lists them).
+ */
+function historyWithCss(entry, manifest) {
+	const css = cssRenameLines(entry, manifest);
+	const vars = css.filter((line) => / cssVar |^cssVar /.test(line));
+	const classes = css.length - vars.length;
+	return [
+		...historyLines(entry),
+		...vars,
+		...(classes
+			? [`${classes} .bb-* class rename(s) on its blocks: include: ['history']`]
+			: []),
+	];
+}
+
 /** The compact `component` of the summary answer. */
 function summarizeComponent(entry, manifest) {
 	const shared = sharedProps(manifest);
@@ -943,9 +1022,10 @@ function summarizeComponent(entry, manifest) {
 		...(entry.cssProps?.length
 			? { cssProps: entry.cssProps.map((c) => c.name ?? c) }
 			: {}),
-		...(entry.removed?.length || entry.renamed?.length
-			? { history: historyLines(entry) }
-			: {}),
+		...(() => {
+			const history = historyWithCss(entry, manifest);
+			return history.length ? { history } : {};
+		})(),
 		...(entry.attrTargets ? { attrTargets: entry.attrTargets } : {}),
 		...(entry.referenceOnly ? { referenceOnly: true } : {}),
 	};
@@ -1244,7 +1324,9 @@ function getComponent({
 			...(wanted.has('cssProps') && entry.cssProps
 				? { cssProps: entry.cssProps }
 				: {}),
-			...(wanted.has('css') && entry.css ? { css: entry.css } : {}),
+			...(wanted.has('css') && entry.css
+				? { css: cssAnswer(entry, manifest) }
+				: {}),
 			...(wanted.has('ptProps')
 				? (() => {
 						const { kept, ...rest } = capParts(ptRows, 'PtProps');
@@ -1252,7 +1334,11 @@ function getComponent({
 					})()
 				: {}),
 			...(wanted.has('history')
-				? { removed: entry.removed ?? [], renamed: entry.renamed ?? [] }
+				? {
+						removed: entry.removed ?? [],
+						renamed: entry.renamed ?? [],
+						cssRenames: cssRenameLines(entry, manifest),
+					}
 				: {}),
 			...(wanted.has('contract')
 				? (() => {
@@ -1293,30 +1379,46 @@ function getComponent({
 		};
 	}
 
+	/*
+	 * The whole entry is the shipped agent file, dist/ai/manifest/components/
+	 * <Name>.json (Q56.46: one builder), with the MCP's own compaction on top:
+	 * the types go in the answer's `types` (with import lines), the cssProps
+	 * as names, the register as one history line per old name.
+	 */
+	const { types: _agentTypes, ...agent } = agentComponent(entry, manifest);
 	const component = {
-		...entry,
-		props: (wanted.has('ptProps')
-			? entry.props
-			: entry.props.filter((p) => !ptRows.includes(p))
-		).map(({ required, ...prop }) => (required ? { ...prop, required } : prop)),
-		...(entry.cssProps && !wanted.has('cssProps')
-			? { cssProps: entry.cssProps.map((c) => c.name ?? c) }
+		...agent,
+		...(wanted.has('ptProps')
+			? {
+					props: entry.props.map(({ required, ...prop }) =>
+						required ? { ...prop, required } : prop
+					),
+				}
+			: {}),
+		...(entry.cssProps
+			? {
+					cssProps: wanted.has('cssProps')
+						? entry.cssProps
+						: entry.cssProps.map((c) => c.name ?? c),
+				}
+			: {}),
+		...(wanted.has('tree') && entry.tree ? { tree: entry.tree } : {}),
+		// The rendered `.bb-*` classes (Q46.5) are for tools (`check`,
+		// `validate`); an agent restyles through pt and the locals.
+		...(wanted.has('css') && entry.css
+			? { css: cssAnswer(entry, manifest) }
 			: {}),
 	};
-	if (!wanted.has('tree')) delete component.tree;
-	// The rendered `.bb-*` classes (Q46.5) are for tools (`check`, `validate`);
-	// an agent restyles through pt and the locals. include: ['css'] lists them.
-	if (!wanted.has('css')) delete component.css;
 	// `removed` and `renamed` repeat each other with migration metadata; one
 	// line per old name answers "what happened to X" (include 'history' for
 	// the records the fixers use).
-	if (
-		!wanted.has('history') &&
-		(entry.removed?.length || entry.renamed?.length)
-	) {
-		component.history = historyLines(entry);
+	if (wanted.has('history')) {
+		if (entry.renamed) component.renamed = entry.renamed;
+		component.cssRenames = cssRenameLines(entry, manifest);
+	} else {
+		const history = historyWithCss(entry, manifest);
+		if (history.length) component.history = history;
 		delete component.removed;
-		delete component.renamed;
 	}
 
 	const always = guide.filter(
@@ -1372,7 +1474,7 @@ function getComponent({
 						: {}),
 				}
 			: {}),
-		hint: `Structured API above is complete. Read guide sections with get_component({ name: '${entry.name}', sections: ['<title from guide.sections>'] }); add include: ['tree' | 'cssProps' | 'css' | 'ptProps' | 'history' | 'contract'] for the component tree, CSS variables with descriptions, the .bb-* classes it renders, every pt:* row, the full v2/beta rename records, or the whole contract. search_docs finds a topic across all docs.`,
+		hint: `Structured API above is complete. Read guide sections with get_component({ name: '${entry.name}', sections: ['<title from guide.sections>'] }); add include: ['tree' | 'cssProps' | 'css' | 'ptProps' | 'history' | 'contract'] for the component tree, CSS variables with descriptions, the .bb-* classes it renders (css.shared: the ones its internal parts render), every pt:* row, the full v2/beta rename records (cssRenames: the CSS local and class renames on its blocks), or the whole contract. search_docs finds a topic across all docs.`,
 	};
 }
 
@@ -1451,8 +1553,16 @@ function* eachTokenDeclaration(css) {
 	const stack = [];
 	let buffer = '';
 	let quote = null;
+	// Parenthesis depth: CSS `if()` separates its branches with `;`, and a
+	// branch may read `style(--bb-x: …)`. Only a top-level `;` ends a
+	// declaration, and only a name at its START is the property it sets
+	// (Q56.48: `--fg-hover: if(style(--bb-primary-fg: …)…)` was served as a
+	// local rebind of --bb-primary-fg).
+	let depth = 0;
 	const declaration = () => {
-		const m = buffer.match(/(--bb-[a-z0-9-]+)\s*:\s*([\s\S]+)/);
+		const m = buffer
+			.replace(/\/\*[\s\S]*?\*\//g, '')
+			.match(/^\s*(--bb-[a-z0-9-]+)\s*:\s*([\s\S]+)/);
 		buffer = '';
 		return m ? { name: m[1], value: m[2].trim() } : null;
 	};
@@ -1465,6 +1575,11 @@ function* eachTokenDeclaration(css) {
 		if (char === '"' || char === "'") {
 			quote = char;
 			buffer += char;
+		} else if (char === '(' || char === ')') {
+			depth = Math.max(0, depth + (char === '(' ? 1 : -1));
+			buffer += char;
+		} else if (depth > 0) {
+			buffer += char;
 		} else if (char === '{') {
 			// A comment before a rule would otherwise prefix its selector or
 			// hide the `@supports` it opens.
@@ -1576,7 +1691,7 @@ function listTokens({ filter } = {}) {
 			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. ${FONT_NOTE}`
 				: FONT_NOTE +
-					' 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. `conditional` is a value that applies only under an @supports condition (`when`) — e.g. an auto-contrast formula with literal fallbacks for older browsers; pinning a fallback literal defeats the formula. `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.',
+					' 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. `conditional` is a value that applies only under an @supports condition (`when`) — e.g. an auto-contrast formula with literal fallbacks for older browsers; pinning a fallback literal defeats the formula. `kind` says what you may set: "knob" is yours; "derived" is a formula recomputed at every theme boundary: theme-wide, set the knob it came from (a derived value you set stops tracking it); a scoped override (one `.bb-table`) is fine, but stops at a nested .dark / .bb-theme; "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.',
 	};
 }
 
@@ -2543,6 +2658,7 @@ function listChanges({
 	// Resolve the component the way get_component does ('bb-select',
 	// 'Select'), and say so when it is no component at all — an empty list
 	// would read as "nothing breaks".
+	let blocks = null;
 	if (component) {
 		const resolved = resolveComponent(loadComponentsManifest(), component);
 		// A retired name (BbTabsPanes) is still a key in the rows it renamed.
@@ -2554,15 +2670,17 @@ function listChanges({
 				didYouMean: nearestComponents(loadComponentsManifest(), component),
 			};
 		}
-		if (resolved?.entry) component = resolved.entry.name;
+		if (resolved?.entry) {
+			component = resolved.entry.name;
+			// Q57.7: a CSS rename reaches it through the blocks it renders.
+			blocks = renderedBlocks(resolved.entry, loadComponentsManifest());
+		}
 	}
+
 	const rows = detail === 'rows';
 	const filtered = (doc.breaking ?? []).filter(
 		(row) =>
-			(!component ||
-				(row.components ?? []).some(
-					(c) => c.toLowerCase() === String(component).toLowerCase()
-				)) &&
+			(!component || rowReaches(row, String(component), blocks)) &&
 			(!surface ||
 				(row.surface ?? (row.kind === 'rename' ? 'prop' : null)) === surface) &&
 			(!kind || row.kind === kind)