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

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/`,
@@ -617,7 +617,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 +637,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) {
@@ -1293,30 +1282,42 @@ 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: entry.css } : {}),
 	};
-	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)
-	) {
+	if (wanted.has('history')) {
+		if (entry.renamed) component.renamed = entry.renamed;
+	} else if (entry.removed?.length || entry.renamed?.length) {
 		component.history = historyLines(entry);
 		delete component.removed;
-		delete component.renamed;
 	}
 
 	const always = guide.filter(
@@ -1451,8 +1452,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 +1474,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.

package/bin/bitboss-ui.mjs

@@ -131,7 +131,7 @@ function coreRules(version) {
 1. **Start at the AI Router**: \`${ROUTER}\` — which file to open next (do not dump the full catalogue into context).
 2. **Obey the agent contract**: \`${CONTRACT}\`.
 3. **Prefer \`Bb*\` consumer components**; never use entries marked "Reference Only - Internal" unless the user explicitly asks for internals. (\`BbBaseButton\` and the \`BbBase*Icon\` glyphs are consumer API; the \`Common*\` building blocks are not.)
-4. **Never invent prop/event/slot names** — open \`${KNOWLEDGE_BASE}/<ComponentName>.md\` (Usage & Guidelines first) or validate against \`${KNOWLEDGE_BASE}/components.json\`.
+4. **Never invent prop/event/slot names** — open \`${KNOWLEDGE_BASE}/<ComponentName>.md\` (Usage & Guidelines first) or its API file \`${KNOWLEDGE_BASE}/manifest/components/<ComponentName>.json\` (one member per line; the list is \`${KNOWLEDGE_BASE}/manifest/index.json\`). Never read \`components.json\` whole: it is the 1.2 MB file the tools use.
 5. **Icons**: discover names first; never invent them (\`${KNOWLEDGE_BASE}/guides/icons-policy.md\`).
 6. **Item-driven components**: declarative \`items\` / \`item-text\` / \`item-value\`, \`dependencies\`, \`enforce-coherence\` — no manual watchers for coherence.
 7. **Whole pages**: one recipe under \`${KNOWLEDGE_BASE}/recipes/{vue|nuxt|inertia}/\` (see the router table).

package/dist/ai/BbAccordion.md

@@ -659,7 +659,7 @@ States are listed in precedence order: when two are on at once and their entries
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbAccordion`. A pt part listed as landing there is set on `BbAccordion` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbAccordion` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbAccordion`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbAccordion`'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 `BbAccordion`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbAccordion`'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/BbAccordion.tree.json`.
 
 - `BbAccordion` _(this component)_ — its own template binds: `header` → `BbBaseButton`, `panel` → `div.bb-accordion__panel`
   - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`

package/dist/ai/BbAlert.md

@@ -519,7 +519,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbAlert`. A pt part listed as landing there is set on `BbAlert` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbAlert` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbAlert`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbAlert`'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 `BbAlert`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbAlert`'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/BbAlert.tree.json`.
 
 - `BbAlert` _(this component)_ — its own template binds: `icon` → `BbIcon`, `close` → `ClearableButton`, `title` → `div.bb-alert__title`, `text` → `div.bb-alert__text`
   - Also mounts `BbIcon`, `ClearableButton`

package/dist/ai/BbAvatar.md

@@ -646,7 +646,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbAvatar`. A pt part listed as landing there is set on `BbAvatar` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbAvatar` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbAvatar`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbAvatar`'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 `BbAvatar`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbAvatar`'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/BbAvatar.tree.json`.
 
 - `BbAvatar` _(this component)_ — its own template binds: `icon` → `BbIcon`
   - Also mounts `BbIcon`

package/dist/ai/BbBadge.md

@@ -923,7 +923,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbBadge`. A pt part listed as landing there is set on `BbBadge` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbBadge` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbBadge`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 the `tree` field of this component in `components.json`.
+- 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`
   - Also mounts `BbIcon`, `BbSpinner`, `BadgeBodyContent`

package/dist/ai/BbBadgeButton.md

@@ -111,7 +111,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbBadgeButton`. A pt part listed as landing there is set on `BbBadgeButton` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbBadgeButton` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbBadgeButton`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbBadgeButton`'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 `BbBadgeButton`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbBadgeButton`'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/BbBadgeButton.tree.json`.
 
 - `BbBadgeButton` _(this component)_
   - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`

package/dist/ai/BbBaseButton.md

@@ -582,7 +582,7 @@ States are listed in precedence order: when two are on at once and their entries
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbBaseButton`. A pt part listed as landing there is set on `BbBaseButton` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbBaseButton` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbBaseButton`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbBaseButton`'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 `BbBaseButton`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbBaseButton`'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/BbBaseButton.tree.json`.
 
 - `BbBaseButton` _(this component)_ — its own template binds: `root` → `RouterComponent`, `root` → `a`, `root` → `component`
   - Also mounts `RouterComponent`

package/dist/ai/BbBreadcrumbs.md

@@ -742,7 +742,7 @@ States are listed in precedence order: when two are on at once and their entries
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbBreadcrumbs`. A pt part listed as landing there is set on `BbBreadcrumbs` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbBreadcrumbs` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbBreadcrumbs`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbBreadcrumbs`'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 `BbBreadcrumbs`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbBreadcrumbs`'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/BbBreadcrumbs.tree.json`.
 
 - `BbBreadcrumbs` _(this component)_ — its own template binds: `item` → `li.bb-breadcrumbs__item`, `icon` → `BbIcon`, `text` → `span.bb-breadcrumbs__text`
   - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`

package/dist/ai/BbButton.md

@@ -109,13 +109,41 @@ restate a state:
 ```css
 .bb-button--upgrade {
 	--bg: var(--bb-primary);
-	--bg-hover: color-mix(in oklab, var(--bb-primary) 90%, black);
-	--bg-pressed: color-mix(in oklab, var(--bb-primary) 80%, var(--bb-text));
+	--bg-hover: var(--bb-primary-hover);
+	--bg-pressed: var(--bb-primary-pressed);
 	--fg: var(--bb-primary-fg);
 	--ring-color: var(--bb-ring);
 }
 ```
 
+The primary's hover is one 1.25:1 luminance step away from the panel
+(darker in light, lighter in dark), turning toward the panel only when the
+primary has no room left, as the default black in light and white in dark
+do: hover is always visible and never sinks into the surface. Pressed takes
+the same move with a larger 1.6:1 step, so it is always the strongest state
+and never equals rest, and a pressed toggle keeps its pressed fill under
+keyboard focus, with the focus ring still showing. The built-in primary
+moves its frame with the hover and pressed fills and,
+where `contrast-color()` exists, picks each state's label for its own fill
+(a white label on a mid blue can turn dark on the lighter dark-scheme
+hover). That is only the default: a pinned `--bb-primary-fg` paints the
+hover and pressed labels too. One limit: a pin that equals the automatic
+pick (white on a blue that already picks white) reads as automatic, so on a
+lighter dark-scheme hover or pressed fill the label still turns dark. To
+keep your pin on every state, point the state labels at it:
+
+```css
+.bb-button--primary {
+	--fg-hover: var(--bb-primary-fg);
+	--fg-pressed: var(--bb-primary-fg);
+}
+```
+
+The same two lines apply where the browser has `contrast-color()` but not
+CSS `if()`, where pins never reach the hover and pressed labels
+(design-tokens.md § `--bb-primary-fg` auto-contrasts). The measurements are
+in design-tokens.md § The state recipe.
+
 Every state has the full trio. Hover and pressed also take `--fg-hover` /
 `--border-hover` and `--fg-pressed` / `--border-pressed` (both default to the
 resting `--fg` / `--border-color`, so only the fill moves unless you say
@@ -1217,7 +1245,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbButton`. A pt part listed as landing there is set on `BbButton` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbButton` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbButton`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbButton`'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 `BbButton`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbButton`'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/BbButton.tree.json`.
 
 - `BbButton` _(this component)_ — its own template binds: `root` → `BbBaseButton`, `spinner` → `BbSpinner`, `icon` → `BbIcon`, `text` → `span.bb-button__text`
   - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`

package/dist/ai/BbCalendar.md

@@ -662,7 +662,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbCalendar`. A pt part listed as landing there is set on `BbCalendar` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbCalendar` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbCalendar`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbCalendar`'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 `BbCalendar`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbCalendar`'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/BbCalendar.tree.json`.
 
 - `BbCalendar` _(this component)_ — its own template binds: `header` → `div.bb-calendar__header`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-calendar__day`, `dayButton` → `button.bb-calendar__day-button`
   - `BbBaseButton` _(public — [contract](./BbBaseButton.md))_ — its own pt parts (`BbBaseButton`): `root` → `RouterComponent`, `root` → `a`, `root` → `component`; also mounts `RouterComponent`

package/dist/ai/BbCheckbox.md

@@ -29,6 +29,7 @@
 | `--ring-color` | `pt:icon` | `BbBaseCheckboxIcon` | The focus ring's colour, re-pointed by errors and warnings. Both ring declarations read it, so a focused glyph grows its ring in its own colour instead of tweening from a different one. |
 | `--elev` | `pt:icon` | `BbBaseCheckboxIcon` | Resting lift; a no-op until a theme pins `--bb-elev`. |
 | `--bg` | `pt:icon` | `BbBaseCheckboxIcon` | The glyph plate. DECLARED here, not consumed bare, because this glyph renders inside surfaces that declare `--bg` themselves — a table row or header cell, a dialog, an off-canvas sheet. Without the declaration it would inherit that surface's fill, which happens to match at the shipped default and would diverge the moment anyone writes `.my-table { --bg: … }`. Identical to the raw tokens it replaces at every theme. |
+| `--ctrl-line` | `pt:label` | `CommonField` | * First-line alignment of side-by-side fields (Q56.44) * ----------------------------------------------------------------- * In a side-by-side layout the label's FIRST line sits on the control's * first line: the text line of a box, the glyph of a toggle, the first * option of a group. Both sides are anchored to the top of the row, so a * taller label column (a description, a wrapped label) never pulls the * control down to its middle; then whichever side's first line is higher * is pushed down by the difference. * * `--ctrl-line` is where the control's first line is centred, from the * top of the control column: half the box height here, and each control * whose first line sits elsewhere (a textarea, a toggle, a group, the * stars) declares its own on the field root. The label's is half its * line box, `--bb-label-lh`. All of it is tokens, so compact and a * custom scale follow. |
 
 ## Usage & Guidelines
 
@@ -768,10 +769,10 @@ States are listed in precedence order: when two are on at once and their entries
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbCheckbox`. A pt part listed as landing there is set on `BbCheckbox` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbCheckbox` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbCheckbox`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbCheckbox`'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 `BbCheckbox`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbCheckbox`'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/BbCheckbox.tree.json`.
 
 - `BbCheckbox` _(this component)_ — its own template binds: `icon` → `BbBaseCheckboxIcon`
-  - `CommonField` _(internal — not importable, reach it through `BbCheckbox`)_ — `BbCheckbox`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `message` → `div.bb-field__message`; also mounts `BbAsterisk`
+  - `CommonField` _(internal — not importable, reach it through `BbCheckbox`)_ — `BbCheckbox`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
   - Also mounts `BbBaseCheckboxIcon`
 
 ## See Also

package/dist/ai/BbCheckboxGroup.md

@@ -33,6 +33,7 @@
 | `--ring-color` | `pt:icon` | `BbBaseCheckboxIcon` | The focus ring's colour, re-pointed by errors and warnings. Both ring declarations read it, so a focused glyph grows its ring in its own colour instead of tweening from a different one. |
 | `--elev` | `pt:icon` | `BbBaseCheckboxIcon` | Resting lift; a no-op until a theme pins `--bb-elev`. |
 | `--bg` | `pt:icon` | `BbBaseCheckboxIcon` | The glyph plate. DECLARED here, not consumed bare, because this glyph renders inside surfaces that declare `--bg` themselves — a table row or header cell, a dialog, an off-canvas sheet. Without the declaration it would inherit that surface's fill, which happens to match at the shipped default and would diverge the moment anyone writes `.my-table { --bg: … }`. Identical to the raw tokens it replaces at every theme. |
+| `--ctrl-line` | `pt:label` | `CommonField` | * First-line alignment of side-by-side fields (Q56.44) * ----------------------------------------------------------------- * In a side-by-side layout the label's FIRST line sits on the control's * first line: the text line of a box, the glyph of a toggle, the first * option of a group. Both sides are anchored to the top of the row, so a * taller label column (a description, a wrapped label) never pulls the * control down to its middle; then whichever side's first line is higher * is pushed down by the difference. * * `--ctrl-line` is where the control's first line is centred, from the * top of the control column: half the box height here, and each control * whose first line sits elsewhere (a textarea, a toggle, a group, the * stars) declares its own on the field root. The label's is half its * line box, `--bb-label-lh`. All of it is tokens, so compact and a * custom scale follow. |
 
 ## Usage & Guidelines
 
@@ -1088,10 +1089,10 @@ Set these on the element, or on a class you put on it, to retune this component
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbCheckboxGroup`. A pt part listed as landing there is set on `BbCheckboxGroup` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbCheckboxGroup` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbCheckboxGroup`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbCheckboxGroup`'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 `BbCheckboxGroup`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbCheckboxGroup`'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/BbCheckboxGroup.tree.json`.
 
 - `BbCheckboxGroup` _(this component)_ — its own template binds: `icon` → `BbBaseCheckboxIcon`
-  - `CommonField` _(internal — not importable, reach it through `BbCheckboxGroup`)_ — `BbCheckboxGroup`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `message` → `div.bb-field__message`; also mounts `BbAsterisk`
+  - `CommonField` _(internal — not importable, reach it through `BbCheckboxGroup`)_ — `BbCheckboxGroup`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
   - `OptionsContainer` _(internal — not importable, reach it through `BbCheckboxGroup`)_ — `BbCheckboxGroup`'s pt parts land here: `list` → `span`, `item` → `label`, `label` → `span`, `itemDescription` → `span`
   - Also mounts `BbBaseCheckboxIcon`
 

package/dist/ai/BbColorInput.md

@@ -32,6 +32,7 @@
 
 | Variable | Set through | Declared by | What it is |
 | --- | --- | --- | --- |
+| `--ctrl-line` | `pt:label` | `CommonField` | * First-line alignment of side-by-side fields (Q56.44) * ----------------------------------------------------------------- * In a side-by-side layout the label's FIRST line sits on the control's * first line: the text line of a box, the glyph of a toggle, the first * option of a group. Both sides are anchored to the top of the row, so a * taller label column (a description, a wrapped label) never pulls the * control down to its middle; then whichever side's first line is higher * is pushed down by the difference. * * `--ctrl-line` is where the control's first line is centred, from the * top of the control column: half the box height here, and each control * whose first line sits elsewhere (a textarea, a toggle, a group, the * stars) declares its own on the field root. The label's is half its * line box, `--bb-label-lh`. All of it is tokens, so compact and a * custom scale follow. |
 | `--bg` | `pt:box` | `CommonFieldInput` | the shell's fill |
 | `--bg-hover` | `pt:box` | `CommonFieldInput` | fill under the pointer |
 | `--bg-focus` | `pt:box` | `CommonFieldInput` | fill while focus is inside, and under --active |
@@ -796,10 +797,10 @@ Set these on the element, or on a class you put on it, to retune this component
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbColorInput`. A pt part listed as landing there is set on `BbColorInput` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbColorInput` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbColorInput`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbColorInput`'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 `BbColorInput`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbColorInput`'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/BbColorInput.tree.json`.
 
 - `BbColorInput` _(this component)_ — its own template binds: `controlAttrs` → `input.bb-color-input__input`, `input` → `input.bb-color-input__input`, `indicator` → `button.bb-color-input__indicator`, `suffix` → `span.bb-field-input__suffix`; hands `BbColorPalette` the pt map `{ panel: 'panel', sheet: 'sheet', swatch: 'swatch' }` (ours → theirs)
-  - `CommonField` _(internal — not importable, reach it through `BbColorInput`)_ — `BbColorInput`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `message` → `div.bb-field__message`; also mounts `BbAsterisk`
+  - `CommonField` _(internal — not importable, reach it through `BbColorInput`)_ — `BbColorInput`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
   - `CommonFieldInput` _(internal — not importable, reach it through `BbColorInput`)_ — `BbColorInput`'s pt parts land here: `box` → `span.bb-field-input__box`, `prefix` → `span.bb-field-input__prefix`, `icon` → `BbIcon`, `clear` → `ClearableButton`, `spinner` → `BbSpinner`, `suffix` → `span.bb-field-input__suffix`; documented CSS variables: `--bg`, `--bg-hover`, `--bg-focus`, `--bg-disabled`, `--fg-disabled`, `--border-color`, `--border-focus`, `--ring-size`, `--ring-color`, `--elev`, `--frost`, `--inside-label-clearance`; also mounts `ErrorIcon`, `WarningIcon`, `ClearableButton`, `BbIcon`, `BbSpinner`
   - `BbColorPalette` _(public — [contract](./BbColorPalette.md))_ — its own pt parts (`BbColorPalette`): `swatch` → `button.bb-color-palette__swatch`, `panel` → `div`, `panel` → `CommonPopover`; hands `BbOffCanvas` the pt map `{ panel: 'root', sheet: 'root' }` (ours → theirs); documented CSS variables: `--edge`; also mounts `CommonPopover`
     - `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`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`

package/dist/ai/BbColorPalette.md

@@ -817,7 +817,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbColorPalette`. A pt part listed as landing there is set on `BbColorPalette` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbColorPalette` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbColorPalette`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbColorPalette`'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 `BbColorPalette`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbColorPalette`'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/BbColorPalette.tree.json`.
 
 - `BbColorPalette` _(this component)_ — its own template binds: `swatch` → `button.bb-color-palette__swatch`, `panel` → `div`, `panel` → `CommonPopover`; hands `BbOffCanvas` the pt map `{ panel: 'root', sheet: 'root' }` (ours → theirs)
   - `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`, `--stack-fill`, `--stack-transition-duration`, `--px`, `--handle-w`, `--handle-h`, `--handle-bg`, `--safe-top`, `--close-size`

package/dist/ai/BbConfirm.md

@@ -836,7 +836,7 @@ States are listed in precedence order: when two are on at once and their entries
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbConfirm`. A pt part listed as landing there is set on `BbConfirm` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbConfirm` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbConfirm`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbConfirm`'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 `BbConfirm`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbConfirm`'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/BbConfirm.tree.json`.
 
 - `BbConfirm` _(this component)_ — its own template binds: `text` → `div.bb-confirm__text`, `action` → `BbButton`; hands `BbDialog` the pt map `passthrough.forward(DIALOG_PARTS, BB_DIALOG_PT.states)` (ours → theirs)
   - `BbDialog` _(public — [contract](./BbDialog.md))_ — its own pt parts (`BbDialog`): `header` → `div.bb-dialog__header`, `title` → `span.bb-dialog__title`, `description` → `p.bb-dialog__description`, `close` → `CloseButton`, `content` → `div.bb-dialog__content`, `footer` → `div.bb-dialog__footer`; hands `BbOffCanvas` the pt map `{ root: 'root', header: 'header', title: 'title', description: 'description', content: 'content', footer: 'footer', close: 'close', sheet: 'root', }` (ours → theirs); documented CSS variables: `--px`, `--close-size`

package/dist/ai/BbDatePicker.md

@@ -527,7 +527,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbDatePicker`. A pt part listed as landing there is set on `BbDatePicker` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbDatePicker` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbDatePicker`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbDatePicker`'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 `BbDatePicker`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbDatePicker`'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/BbDatePicker.tree.json`.
 
 - `BbDatePicker` _(this component)_ — its own template binds: `panel` → `div`, `panel` → `CommonPopover`; hands `BbCalendar` the pt map ` passthrough.forward(DATE_PICKER_CALENDAR_PARTS, BB_CALENDAR_PT.states) ` (ours → theirs); hands `BbOffCanvas` the pt map `{ panel: 'root', sheet: 'root' }` (ours → theirs)
   - `BbCalendar` _(public — [contract](./BbCalendar.md))_ — its own pt parts (`BbCalendar`): `header` → `div.bb-calendar__header`, `arrow` → `BbBaseButton`, `month` → `BbBaseButton`, `year` → `BbBaseButton`, `day` → `div.bb-calendar__day`, `dayButton` → `button.bb-calendar__day-button`; documented CSS variables: `--cell`, `--unit-row`; also mounts `ScaleFade`, `Slide`, `CalendarMonthPanel`, `CalendarYearPanel`

package/dist/ai/BbDatePickerInput.md

@@ -29,6 +29,7 @@
 
 | Variable | Set through | Declared by | What it is |
 | --- | --- | --- | --- |
+| `--ctrl-line` | `pt:label` | `CommonField` | * First-line alignment of side-by-side fields (Q56.44) * ----------------------------------------------------------------- * In a side-by-side layout the label's FIRST line sits on the control's * first line: the text line of a box, the glyph of a toggle, the first * option of a group. Both sides are anchored to the top of the row, so a * taller label column (a description, a wrapped label) never pulls the * control down to its middle; then whichever side's first line is higher * is pushed down by the difference. * * `--ctrl-line` is where the control's first line is centred, from the * top of the control column: half the box height here, and each control * whose first line sits elsewhere (a textarea, a toggle, a group, the * stars) declares its own on the field root. The label's is half its * line box, `--bb-label-lh`. All of it is tokens, so compact and a * custom scale follow. |
 | `--bg` | `pt:box` | `CommonFieldInput` | the shell's fill |
 | `--bg-hover` | `pt:box` | `CommonFieldInput` | fill under the pointer |
 | `--bg-focus` | `pt:box` | `CommonFieldInput` | fill while focus is inside, and under --active |
@@ -1000,7 +1001,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbDatePickerInput`. A pt part listed as landing there is set on `BbDatePickerInput` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbDatePickerInput` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbDatePickerInput`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbDatePickerInput`'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 `BbDatePickerInput`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbDatePickerInput`'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/BbDatePickerInput.tree.json`.
 
 - `BbDatePickerInput` _(this component)_ — its own template binds: `controlAttrs` → `input.bb-segmented-field__input`, `input` → `input.bb-segmented-field__input`, `activator` → `button.bb-segmented-field__activator`, `suffix` → `span.bb-field-input__suffix`; hands `BbDatePicker` the pt map `passthrough.forward(PICKER_PARTS, BB_DATE_PICKER_PT.states)` (ours → theirs)
   - `BbDatePicker` _(public — [contract](./BbDatePicker.md))_ — its own pt parts (`BbDatePicker`): `panel` → `div`, `panel` → `CommonPopover`; hands `BbCalendar` the pt map ` passthrough.forward(DATE_PICKER_CALENDAR_PARTS, BB_CALENDAR_PT.states) ` (ours → theirs); hands `BbOffCanvas` the pt map `{ panel: 'root', sheet: 'root' }` (ours → theirs); documented CSS variables: `--cell`, `--unit-row`; also mounts `CommonPopover`
@@ -1009,7 +1010,7 @@ Set these on the element, or on a class you put on it, to retune this component
       - `CommonTimeSelector` _(internal — not importable, reach it through `BbCalendar`)_ — its own pt parts (`BbCalendar`): `header` → `div.bb-time-selector__header`, `cellColumnHeader` → `div.bb-time-selector__cell-column-header`, `item` → `BbBaseButton`; documented CSS variables: `--time-mark`; also mounts `BbBaseButton`
     - `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`, `--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`
-  - `CommonField` _(internal — not importable, reach it through `BbDatePickerInput`)_ — `BbDatePickerInput`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `message` → `div.bb-field__message`; also mounts `BbAsterisk`
+  - `CommonField` _(internal — not importable, reach it through `BbDatePickerInput`)_ — `BbDatePickerInput`'s pt parts land here: `root` → `div.bb-field`, `label` → `component`, `description` → `span.bb-field__description`, `hint` → `span.bb-field__hint`, `message` → `div.bb-field__message`; documented CSS variables: `--ctrl-line`; also mounts `BbAsterisk`
   - `CommonFieldInput` _(internal — not importable, reach it through `BbDatePickerInput`)_ — `BbDatePickerInput`'s pt parts land here: `box` → `span.bb-field-input__box`, `prefix` → `span.bb-field-input__prefix`, `icon` → `BbIcon`, `clear` → `ClearableButton`, `spinner` → `BbSpinner`, `suffix` → `span.bb-field-input__suffix`; documented CSS variables: `--bg`, `--bg-hover`, `--bg-focus`, `--bg-disabled`, `--fg-disabled`, `--border-color`, `--border-focus`, `--ring-size`, `--ring-color`, `--elev`, `--frost`, `--inside-label-clearance`; also mounts `ErrorIcon`, `WarningIcon`, `ClearableButton`, `BbIcon`, `BbSpinner`
   - Also mounts `BbIcon`
 

package/dist/ai/BbDialog.md

@@ -1200,7 +1200,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbDialog`. A pt part listed as landing there is set on `BbDialog` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbDialog` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbDialog`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbDialog`'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 `BbDialog`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbDialog`'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/BbDialog.tree.json`.
 
 - `BbDialog` _(this component)_ — its own template binds: `header` → `div.bb-dialog__header`, `title` → `span.bb-dialog__title`, `description` → `p.bb-dialog__description`, `close` → `CloseButton`, `content` → `div.bb-dialog__content`, `footer` → `div.bb-dialog__footer`; hands `BbOffCanvas` the pt map `{ root: 'root', header: 'header', title: 'title', description: 'description', content: 'content', footer: 'footer', close: 'close', sheet: 'root', }` (ours → theirs)
   - `CloseButton` _(internal — not importable, reach it through `BbDialog`)_ — documented CSS variables: `--size`, `--p`

package/dist/ai/BbDropdown.md

@@ -2209,7 +2209,7 @@ Set these on the element, or on a class you put on it, to retune this component
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbDropdown`. A pt part listed as landing there is set on `BbDropdown` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbDropdown` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbDropdown`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbDropdown`'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 `BbDropdown`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbDropdown`'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/BbDropdown.tree.json`.
 
 - `BbDropdown` _(this component)_ — its own template binds: `panel` → `CommonPopover`, `root` → `CommonPopover`, `header` → `div.bb-dropdown__header`, `list` → `span.bb-dropdown__list`, `footer` → `div.bb-dropdown__footer`
   - `BbDropdownList` _(internal — not importable, reach it through `BbDropdown`)_ — also mounts `BbIcon`, `CommonPopover`, `BbDropdownList`

package/dist/ai/BbDropdownButton.md

@@ -714,7 +714,7 @@ States are listed in precedence order: when two are on at once and their entries
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbDropdownButton`. A pt part listed as landing there is set on `BbDropdownButton` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbDropdownButton` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbDropdownButton`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbDropdownButton`'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 `BbDropdownButton`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbDropdownButton`'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/BbDropdownButton.tree.json`.
 
 - `BbDropdownButton` _(this component)_ — hands `BbButton` the pt map `{ main: 'root', icon: 'icon', spinner: 'spinner', text: 'text' }` (ours → theirs); hands `BbDropdown` the pt map `{ panel: 'panel', sheet: 'sheet', header: 'header', footer: 'footer', input: 'input', item: 'item', itemText: 'itemText', itemIcon: 'itemIcon', itemDescription: 'itemDescription' }` (ours → theirs); hands `BbButton` the pt map `{ toggle: 'root' }` (ours → theirs)
   - `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`, `BbSpinner`

package/dist/ai/BbDropzone.md

@@ -1471,7 +1471,7 @@ States are listed in precedence order: when two are on at once and their entries
 - **_internal_** nodes are building blocks with no API of their own: you reach them only through `BbDropzone`. A pt part listed as landing there is set on `BbDropzone` (`pt:<part>`).
 - **_public_** nodes are components with their own contract. `BbDropzone` reaches one only through a pt part of its own that lands on it (shown on the parent node as `part → Component`, e.g. `spinner → BbSpinner`) or through a pt map it hands it (shown as "hands … the pt map", in `BbDropzone`'s words → the child's). The child's other props and parts are not exposed; its contract explains what it renders.
 - **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 `BbDropzone`'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 `BbDropzone`'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 the `tree` field of this component in `components.json`.
+- Listed nodes are the ones `BbDropzone`'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/BbDropzone.tree.json`.
 
 - `BbDropzone` _(this component)_ — its own template binds: `content` → `label.bb-dropzone__content`, `message` → `span.bb-dropzone__message`
   - Also mounts `BbSmoothHeight`