bitboss-ui 3.0.0-beta.37 → 3.0.0-beta.41

package/bin/bitboss-ui.mjs

@@ -68,9 +68,25 @@ import {
 	disabledChecker,
 	ruleForFinding,
 } from '../scripts/lib/eslint-disable.mjs';
+import {
+	localBbImports,
+	localBbWarning,
+	projectLocalBbComponents,
+} from '../scripts/lib/local-components.mjs';
 import { applyBitbossFixes } from '../scripts/lib/check-fix.mjs';
+import { cssClassFindings } from '../scripts/lib/css-class-check.mjs';
+import {
+	cssLocalFindings,
+	libraryTokens,
+	localReads,
+} from '../scripts/lib/css-local-check.mjs';
+import {
+	HAND_IMPORTED_STYLES_EXTENSIONS,
+	handImportedStylesFindings,
+} from '../scripts/lib/hand-imported-styles.mjs';
+import { syncProjectVariantDts } from '../scripts/lib/project-variant-dts.mjs';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
 import {
 	detectPackageManager,
@@ -82,6 +98,7 @@ import {
 } from '../scripts/lib/mcp-config.mjs';
 import {
 	loadManifest,
+	registeredRuleNames,
 	validateMarkdown,
 	validateVueSnippet,
 } from '../scripts/lib/validate-bb-markup.mjs';
@@ -116,9 +133,13 @@ function coreRules(version) {
 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).
-8. **CSS near components**: \`${KNOWLEDGE_BASE}/guides/design-language.md\`. Two token tiers, and reaching for the wrong one is why apps end up re-skinning by class: \`--bb-*\` is the small GLOBAL theme tier (brand knobs, ~90 names, no numeric ramp — there is no \`--bb-primary-800\`), while each component declares its own **unprefixed** \`--*\` tokens for its look (\`.bb-table { --cell-h: 32px }\`). A missing \`--bb-*\` name is not a gap in the library — it means the knob you want is a component token. Set it on the element that DECLARES it (grep \`${KNOWLEDGE_BASE}/source/<ComponentName>.md\`); a value set further out is masked, not inherited. Prefer tokens, variants and \`pt\`; CSS on \`.bb-*__*\` internals is allowed for fine-tuning but unsupported: it can break on upgrade. \`.bb-common-*\` / \`.bb-field*\` internals: expect it to break. (\`.bb-base-button\` and the three \`.bb-base-*-icon\` glyph classes are consumer API — a supported hook, not an internal.) An override on an internal is a signal to check for a \`pt\` part or request one. **A Tailwind utility on a \`Bb*\` component that does nothing** is not a library bug: Tailwind v4 emits layered CSS and unlayered CSS outranks it, whatever the specificity. The fix is in the BUILD plugin, not in CSS — \`cssLayers: TAILWIND_V4_LAYERS\` (imported from \`bitboss-ui/vite\`) in \`vite.config.*\` / \`nuxt.config.*\`; see \`${KNOWLEDGE_BASE}/guides/installation-and-plugin-setup.md\` § Cascade layers. One primary action per view region.
-9. **Variants are yours to add**: the shipped \`variant\` names are a floor, not a ceiling. When the design needs a colour the library doesn't ship (soft status badges, a brand button tone), **register the name** in the build plugin's \`badgeVariants\`/\`buttonVariants\`/\`alertVariants\`/… and **style \`.bb-badge--<name>\`** (etc.) in a project stylesheet loaded after \`bitboss-ui/styles.css\`. Do both halves — a registered name with no CSS ships an unstyled pill, and CSS with no registration fails \`vue-tsc\`. Never write an unregistered name, and never downgrade the design to a neutral shipped variant to avoid registering. Canonical palette + snippet: \`${KNOWLEDGE_BASE}/guides/design-language.md\` § Getting soft semantic badges.
-10. **After writing bitboss-ui markup**, run \`npx bitboss-ui check\` — validates \`Bb*\` usage against the installed \`components.json\` and catches invented/removed props before review.
+8. **CSS near components**: \`${KNOWLEDGE_BASE}/guides/design-language.md\`. Paint as data is \`${KNOWLEDGE_BASE}/design-tokens.json\` and \`design-tokens.manifest.yaml\` (DESIGN.md-shaped). Grep \`--bb-*\`, not \`--color-*\` or \`--radius-*\`. A repo-root DESIGN.md is not this library. Two token tiers, and reaching for the wrong one is why apps end up re-skinning by class: \`--bb-*\` is the small GLOBAL theme tier (brand knobs, no numeric ramp — there is no \`--bb-primary-800\`), while each component declares its own **unprefixed** \`--*\` tokens for its look (\`.bb-table { --cell-h: 32px }\`). A missing \`--bb-*\` name is not a gap in the library — it means the knob you want is a component token. Set it on the element that DECLARES it (grep \`${KNOWLEDGE_BASE}/source/<ComponentName>.md\`); a value set further out is masked, not inherited. Prefer tokens, variants and \`pt\`; CSS on \`.bb-*__*\` internals is allowed for fine-tuning but unsupported: it can break on upgrade. \`.bb-common-*\` / \`.bb-field*\` internals: expect it to break. (\`.bb-base-button\` and the three \`.bb-base-*-icon\` glyph classes are consumer API — a supported hook, not an internal.) An override on an internal is a signal to check for a \`pt\` part or request one. A Tailwind utility on a \`Bb*\` component that does nothing is rule 9, not a library bug. One primary action per view region.
+9. **Tailwind v4 app: turn on cascade layers when you set bitboss-ui up**, not later when a class "doesn't work". In the build plugin: \`import { bitbossUi, TAILWIND_V4_LAYERS } from 'bitboss-ui/vite'\` and \`bitbossUi({ cssLayers: TAILWIND_V4_LAYERS })\` (Nuxt: \`bitboss: { cssLayers: TAILWIND_V4_LAYERS }\`, same import). Tailwind v4 emits layered CSS; without this the library's CSS is unlayered and beats every utility you put on a \`Bb*\` component or a \`pt:*\` part, whatever the specificity. With it, your utilities win. You still need the runtime plugin (\`app.use(bitbossUiPlugin)\`; Nuxt does it for you): it is what injects the sheet, into that layer. **Do not also \`@import 'bitboss-ui/styles.css'\`**: a hand import adds a second, unlayered copy and undoes the setting. Tailwind v3 or plain CSS: leave it unset. Details: \`${KNOWLEDGE_BASE}/guides/installation-and-plugin-setup.md\` § Cascade layers.
+10. **Set a \`font-family\` on \`body\`** (components inherit it; there is no font token), e.g. \`body { font-family: system-ui, sans-serif; }\`. Without one the whole app renders in the browser's default serif.
+11. **Variants are yours to add**: the shipped \`variant\` names are a floor, not a ceiling. When the design needs a colour the library doesn't ship (soft status badges, a brand button tone), **register the name** in the build plugin's \`badgeVariants\`/\`buttonVariants\`/\`alertVariants\`/… and **style \`.bb-badge--<name>\`** (etc.) in a project stylesheet loaded after \`bitboss-ui/styles.css\`. Do both halves — a registered name with no CSS ships an unstyled pill, and CSS with no registration fails \`vue-tsc\`. After registering, run \`npx bitboss-ui check\`: it writes the project's \`bitboss-ui.d.ts\` so the new name type-checks before Vite has run. Never write an unregistered name, and never downgrade the design to a neutral shipped variant to avoid registering. Canonical palette + snippet: \`${KNOWLEDGE_BASE}/guides/design-language.md\` § Getting soft semantic badges.
+12. **Never name your own components \`Bb…\`** — that prefix is bitboss-ui's. Use your app's prefix (\`App…\`, \`Acme…\`). \`check\` leaves an app's own \`Bb*\` component alone but warns: a future bitboss-ui component could take the name.
+13. **Set \`locale\` explicitly** in the build plugin (\`bitbossUi({ locale: 'it' })\` / nuxt \`bitboss: { locale: 'it' }\`) for any app that is not English: the built-in strings default to English (\`'en'\`, since 3.0.0-beta.41; it was \`'it'\`).
+14. **After writing bitboss-ui markup**, run \`npx bitboss-ui check\` — validates \`Bb*\` usage against the installed \`components.json\` and catches invented/removed props before review.
 
 After upgrading bitboss-ui, re-run: \`npx bitboss-ui ai-init\``;
 }
@@ -394,7 +415,7 @@ function inSkippedDir(relPath) {
  * `recursive: true` readdir) is what keeps a multi-thousand-file `vendor/`
  * tree from being walked at all.
  */
-function collectCheckFiles(dir, relBase = dir) {
+function collectCheckFiles(dir, relBase = dir, extensions = CHECK_EXTENSIONS) {
 	let entries;
 	try {
 		entries = readdirSync(dir, { withFileTypes: true });
@@ -407,11 +428,11 @@ function collectCheckFiles(dir, relBase = dir) {
 		if (entry.isDirectory()) {
 			if (isSkippedSegment(entry.name)) continue;
 			if (isSkippedSubpath(relative(relBase, full))) continue;
-			out.push(...collectCheckFiles(full, relBase));
+			out.push(...collectCheckFiles(full, relBase, extensions));
 			continue;
 		}
 		if (!entry.isFile()) continue;
-		if (!CHECK_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) continue;
+		if (!extensions.some((ext) => entry.name.endsWith(ext))) continue;
 		out.push(full);
 	}
 	return out;
@@ -559,7 +580,12 @@ function printFindingLegend(findings) {
 	const rows = [];
 	if (kinds.has('removed-prop'))
 		rows.push(
-			'  "was removed from X"   a v2→v3 break. X really had this prop; fix the call site.'
+			'  "was removed from X"   a recorded break (v2→v3, or a v3 beta rename). X really\n' +
+				'  / "was renamed on X"   had this prop or pt key; `check --fix` rewrites the renames.'
+		);
+	if (kinds.has('renamed-slot'))
+		rows.push(
+			'  "slot … was renamed"   a recorded slot rename; `check --fix` rewrites it.'
 		);
 	if (kinds.has('unknown-prop'))
 		rows.push(
@@ -633,8 +659,14 @@ function changelogCommand({ since, until, json: jsonMode }) {
 		['--until', until],
 	]) {
 		if (value != null && !releases.includes(value)) {
+			// A tagged-but-never-published version (beta.34): say where its
+			// changes went instead of "unknown", which reads like a typo.
+			const unpublished = (doc.unpublished ?? []).includes(value);
+			const next = releases.find((r) => compareReleaseVersions(r, value) > 0);
 			console.error(
-				`[bitboss-ui] changelog: unknown ${label} version '${value}'.\n` +
+				(unpublished
+					? `[bitboss-ui] changelog: ${label} ${value} was never published to npm; its changes shipped in ${next ?? 'the next release'}.\n`
+					: `[bitboss-ui] changelog: unknown ${label} version '${value}'.\n`) +
 					`Known releases: ${releases.join(', ')}`
 			);
 			process.exit(1);
@@ -687,8 +719,14 @@ function changelogCommand({ since, until, json: jsonMode }) {
 	for (const entry of rows) {
 		const at = entry.firstReleasedIn ?? 'unreleased';
 		if (entry.kind === 'rename') {
+			// `surface` says what kind of name it is (Q51.19); a slot reads `#…`.
+			const spell = (name) => (entry.surface === 'slot' ? `#${name}` : name);
+			const surface =
+				entry.surface && entry.surface !== 'prop' ? `${entry.surface} ` : '';
 			console.log(
-				`  [${at}] ${entry.components.join(', ')}: \`${entry.from}\` → \`${entry.to}\``
+				`  [${at}] ${entry.components.join(', ')}: ${surface}\`${spell(entry.from)}\` → ` +
+					(entry.to == null ? 'removed' : `\`${spell(entry.to)}\``) +
+					(entry.note ? ` (${entry.note})` : '')
 			);
 		} else {
 			console.log(`  [${at}] ${entry.description}`);
@@ -768,6 +806,30 @@ async function checkCommand(
 	}
 	const manifest = loadManifest(manifestPath);
 
+	/*
+	 * Q53.23: write the project's `bitboss-ui.d.ts` from the build config, the
+	 * file the Vite plugin writes when Vite starts. Agents run `vue-tsc` before
+	 * any dev start, so a name registered in `badgeVariants` was a type error
+	 * (and an `as any`) until then. Same generator as the plugin; a config it
+	 * cannot read is left alone. Not under `--manifest` (an upgrade preview
+	 * must not touch the project).
+	 */
+	if (!manifestOverride) {
+		try {
+			const projectDts = await import(
+				pathToFileURL(join(PACKAGE_ROOT, 'dist', 'project-dts.js')).href
+			);
+			const synced = syncProjectVariantDts(projectRoot, projectDts);
+			if (synced.status === 'written' && !jsonMode)
+				console.log(
+					`[bitboss-ui] Wrote ${synced.path} from your build config: registered variant names now type-check. Commit it.`
+				);
+		} catch {
+			// No built `dist/project-dts.js` (the library repo before a build):
+			// nothing to write with, and nothing for `check` to fail over.
+		}
+	}
+
 	/*
 	 * Every `--bb-*` the INSTALLED package declares, read from the stylesheet
 	 * the consumer actually ships. Read from disk rather than hardcoded so this
@@ -788,10 +850,15 @@ async function checkCommand(
 	// CHK-ALLOWCOMPONENTS: `Bb` is a naming convention, not proof of ownership.
 	// An app component called `BbRichEditor` is not invalid library markup, and
 	// before this the only way to silence it was to rename the component.
-	const allowedComponents = [
+	const explicitlyAllowed = new Set([
 		...configuredAllowComponents(projectRoot),
 		...allowComponents,
-	];
+	]);
+	// Q53.18: the app's own `Bb*` components (`.vue` files in its `components`
+	// dirs, Nuxt path-prefix names included) are skipped with zero config;
+	// imports from the app's own paths are handled per file by the validator.
+	const projectLocal = projectLocalBbComponents(projectRoot);
+	const allowedComponents = [...explicitlyAllowed, ...projectLocal.keys()];
 
 	// Q46.8: `--fix` applies the ESLint plugin's fixes (the registered v2→v3
 	// migrations) with ONLY the bitboss rules, then the check below reports
@@ -822,16 +889,71 @@ async function checkCommand(
 					.join('\n')}`
 			);
 	}
-	const validateOptions = { allowComponents: allowedComponents };
+	// Q46.6: every `var(--x)` the project reads, from a whole-project sweep
+	// (explicit paths included): a local or token the app reads itself is its
+	// own, never "set and unread".
+	const projectReads = new Set();
+	for (const path of collectCheckFiles(
+		projectRoot,
+		projectRoot,
+		HAND_IMPORTED_STYLES_EXTENSIONS
+	))
+		try {
+			for (const name of localReads(readFileSync(path, 'utf-8')))
+				projectReads.add(name);
+		} catch {
+			/* unreadable: its reads are unknown, which only means fewer passes */
+		}
+	// The tokens of the sheet `check` judges against (the installed one, or
+	// the one beside `--manifest`) — read AND declared names both count.
+	if (manifest.localSurface && existsSync(stylesPath))
+		manifest.localSurface.knownTokens = libraryTokens([
+			readFileSync(stylesPath, 'utf-8'),
+			...[join(dirname(stylesPath), 'reset.css')]
+				.filter((path) => existsSync(path))
+				.map((path) => readFileSync(path, 'utf-8')),
+		]);
+	// Q54.2: the rules the project registers with `defineRule`, from the same
+	// whole-project sweep, so a string rule nobody registered is caught.
+	const registeredRules = { names: new Set(), dynamic: false };
+	for (const path of collectCheckFiles(projectRoot, projectRoot, [
+		'.ts',
+		'.js',
+		'.mjs',
+		'.cjs',
+		'.vue',
+	]))
+		try {
+			const found = registeredRuleNames(readFileSync(path, 'utf-8'));
+			for (const name of found.names) registeredRules.names.add(name);
+			if (found.dynamic) registeredRules.dynamic = true;
+		} catch {
+			/* unreadable: fewer names, which only means more caution below */
+			registeredRules.dynamic = true;
+		}
+	const validateOptions = {
+		allowComponents: allowedComponents,
+		projectReads,
+		registeredRules,
+	};
 
 	const findings = [];
 	let suppressed = 0;
+	/** One warning per local `Bb*` component, unless allowlisted (Q53.18). */
+	const warnedLocal = new Set();
+	const warnLocal = (name, file, line) => {
+		if (explicitlyAllowed.has(name) || warnedLocal.has(name)) return;
+		warnedLocal.add(name);
+		warnings.push(localBbWarning(name, file, line));
+	};
 	/*
 	 * Advisory only — see scripts/lib/hand-roll-hints.mjs. Hints never touch the
 	 * exit code, so a guess can never fail a consumer's build. `--no-hints`
 	 * silences them for anyone who finds them noisy.
 	 */
 	const hints = [];
+	/** Findings graded `severity: 'warning'` — printed, never fatal. */
+	const warnings = [];
 	const wantHints = !process.argv.includes('--no-hints');
 	for (const file of files) {
 		const relPath = relative(projectRoot, file);
@@ -846,12 +968,19 @@ async function checkCommand(
 		const isDisabled = file.endsWith('.vue')
 			? disabledChecker(content)
 			: () => false;
+		if (file.endsWith('.vue'))
+			for (const [name, line] of localBbImports(content))
+				warnLocal(name, relPath, line);
 		for (const finding of fileFindings) {
 			if (isDisabled(finding.line, ruleForFinding(finding))) {
 				suppressed++;
 				continue;
 			}
-			findings.push({ file: relPath, ...finding });
+			// A `severity: 'warning'` finding (Q53.15 C9b: a slot spelled the
+			// pre-reset way) is shown and suppressible, but never fails the run.
+			if (finding.severity === 'warning')
+				warnings.push({ file: relPath, ...finding });
+			else findings.push({ file: relPath, ...finding });
 		}
 		// .md files are documentation ABOUT components; a round <img> in a doc
 		// example is illustrative, not a hand-roll.
@@ -862,6 +991,41 @@ async function checkCommand(
 		}
 	}
 
+	for (const [name, file] of projectLocal) warnLocal(name, file);
+
+	// Q25: a hand import of `bitboss-ui/styles.css` while the runtime plugin
+	// injects it. Project-level — the answer needs the build config — so it
+	// reads the style and script files too; with explicit paths, only those.
+	const styleScan = globs.length
+		? files
+		: collectCheckFiles(
+				projectRoot,
+				projectRoot,
+				HAND_IMPORTED_STYLES_EXTENSIONS
+			);
+	findings.push(
+		...handImportedStylesFindings(
+			projectRoot,
+			styleScan.map((path) => ({ path, relPath: relative(projectRoot, path) }))
+		)
+	);
+	// Q46.5: `.bb-*` selectors in the app's stylesheets (the `.vue` `<style>`
+	// blocks are read by the validator above).
+	for (const path of styleScan) {
+		if (!/\.(?:css|scss|sass|less|pcss|postcss|styl)$/.test(path)) continue;
+		const relPath = relative(projectRoot, path);
+		const content = readFileSync(path, 'utf-8');
+		for (const finding of [
+			...cssClassFindings(content, manifest.cssSurface, { stylesheet: true }),
+			// Q46.6: custom properties set where nothing reads them.
+			...cssLocalFindings(content, manifest.cssSurface, manifest.localSurface, {
+				stylesheet: true,
+				projectReads,
+			}),
+		])
+			findings.push({ file: relPath, ...finding });
+	}
+
 	/** One line, so a silenced finding is never invisible. */
 	const printSuppressed = () => {
 		if (suppressed === 0) return;
@@ -870,6 +1034,18 @@ async function checkCommand(
 		);
 	};
 
+	/** Warning block, printed on success and on failure alike. Never fatal. */
+	const printWarnings = () => {
+		if (warnings.length === 0) return;
+		console.log(
+			`\n[bitboss-ui] ${warnings.length} warning(s) — not fatal, but likely wrong:`
+		);
+		for (const warning of warnings) {
+			const at = warning.line != null ? `:${warning.line}` : '';
+			console.log(`  ⚠ ${warning.file}${at} ${warning.message}`);
+		}
+	};
+
 	/** Advisory block, printed on success and on failure alike. Never fatal. */
 	const printHints = () => {
 		if (hints.length === 0) return;
@@ -908,6 +1084,7 @@ async function checkCommand(
 			JSON.stringify(
 				{
 					findings,
+					warnings,
 					hints,
 					suppressed,
 					files: files.length,
@@ -948,11 +1125,13 @@ async function checkCommand(
 			`[bitboss-ui] check OK — ${summarizeFileCounts(files)} file(s), zero unknown Bb* props/v-models/slots/nav-attrs.`
 		);
 		printSuppressed();
+		printWarnings();
 		printHints();
 		return;
 	}
 
 	printSuppressed();
+	printWarnings();
 	const fileCount = new Set(findings.map((f) => f.file)).size;
 	console.error(
 		`[bitboss-ui] check FAILED — ${findings.length} finding(s) across ${fileCount} file(s):`
@@ -1020,6 +1199,13 @@ Commands:
                       nothing (a typo'd CI path validates zero files silently) —
                       pass \`--allow-empty\` when an empty match is expected.
 
+                      It also writes your project's \`bitboss-ui.d.ts\` (the
+                      file the Vite plugin writes on start) from the variant
+                      options in vite.config / nuxt.config, so a newly
+                      registered variant name type-checks before Vite runs.
+                      Left alone when the options are not inline literals, and
+                      under \`--manifest\`.
+
                       \`--fix\` first applies the ESLint plugin's fixes (the
                       registered v2→v3 renames, polarity flips and value
                       remaps) to the matched .vue files with ONLY the
@@ -1052,17 +1238,86 @@ Commands:
                       Same option name as the ESLint rules' \`allowComponents\`,
                       so both gates configure alike.
 
-                      \`--json\` prints \`{ findings: [...], hints: [...], files }\`.
+                      \`--json\` prints \`{ findings: [...], warnings: [...], hints: [...],
+                      suppressed, files, manifestVersion, installedVersion }\`.
                       Each finding: \`{ file, line, component, attr, kind,
                       message, hint?, to? }\` (plus \`fenceIndex\`/\`fenceInfo\`
                       inside a markdown fence; \`line\` is absolute in the file).
-                      \`kind\` is one of: \`removed-prop\` (a v2→v3 break — fix
-                      it), \`unknown-prop\` (not a v3 prop of that component;
+                      \`kind\` is one of: \`removed-prop\` (a recorded break on a
+                      prop or a \`pt\` key, v2→v3 or a v3 beta; \`to\` is the new
+                      name when there is one and \`--fix\` writes it, else the
+                      message says what to do), \`unknown-prop\` (not a v3 prop of that component;
                       may never have been one — see the legend the text output
-                      prints), \`unknown-model\`, \`unknown-slot\`,
+                      prints), \`unknown-component\` (a \`Bb*\` tag the
+                      manifest doesn't have; \`attr\` is the tag),
+                      \`unknown-model\`, \`unknown-event\`, \`unknown-slot\`,
+                      \`unknown-pt-key\` (a key of the \`pt\` object form that
+                      matches no part / state; \`to\` when the part was renamed),
                       \`no-default-slot\`, \`inert-nav-attr\`,
-                      \`missing-partner-prop\`, \`partner-prop\`,
-                      \`validated-only-prop\`.
+                      \`nameless-control\` (an icon-only BbButton or BbBadge,
+                      or a BbProgress, with no accessible name),
+                      \`removed-css-local\` (a component CSS local the
+                      library removed, e.g. \`--day-slot-allowance\`),
+                      \`private-import\` (an import from inside the package's
+                      \`dist/\`), \`not-exported-type\` (a \`Pt*\` pt type
+                      imported from bitboss-ui: type pt through
+                      \`<Component>Props['pt']\` instead),
+                      \`missing-key\` / \`duplicate-row-text\` (a
+                      BbDropdown row or group that needs a \`key\`: selectable,
+                      or identical keyless text in one group),
+                      \`unknown-variant\` (a variant name from another
+                      library, e.g. \`danger\` on BbAlert / BbBadge; the
+                      message names ours),
+                      \`duplicate-field-identity\` (two validated fields in
+                      one \`BbForm\` on the same path: the same \`name\`,
+                      or the same label with no \`name\`),
+                      \`rules-ignored-by-schema\` (a validated field's
+                      \`rules\` inside a \`BbForm\` that has a \`schema\`:
+                      vee-validate reads only the schema),
+                      \`row-without-name\` (a form control in a \`v-for\`
+                      inside a \`BbForm\` with a bound label and no \`name\`),
+                      \`retired-entrypoint\` (an import from
+                      \`bitboss-ui/validated\`, retired: everything is in
+                      \`bitboss-ui\`; \`--fix\` rewrites it in .vue files),
+                      \`unregistered-rule\` (a string rule no
+                      \`defineRule\` in the project registers; silent when
+                      the project registers rules in a loop),
+                      \`wrapper-drops-props\` (a wrapper whose
+                      \`defineProps\` declares a \`Bb*Props\` type, bare,
+                      \`Omit\` or \`Pick\`, and never binds or reads some
+                      of those props: a caller's value is dropped),
+                      \`renamed-slot\` (a slot the library renamed;
+                      \`--fix\` rewrites it), \`missing-partner-prop\`,
+                      \`partner-prop\`,
+                      \`validated-only-prop\`, \`object-items-without-text\`
+                      (object \`items\` with no \`item-text\`; reads only
+                      an inline array, or a \`const\` array, \`ref([…])\` or
+                      \`reactive([…])\` in the same file's
+                      \`<script setup>\`), \`reserved-key\` (a key
+                      whose slot name is one of the component's own slots,
+                      e.g. a BbTable column keyed \`actions\`; read from the
+                      manifest, same-file keys only), \`hand-imported-styles\`
+                      (\`bitboss-ui/styles.css\` imported in CSS, a script or
+                      Nuxt's \`css\` while \`injectStyles\` is on: delete it;
+                      read only when vite.config / nuxt.config says so),
+                      \`unknown-class\` (a selector on a \`.bb-*\` class the
+                      library does not render, in a stylesheet or a
+                      \`<style>\` block; \`suggestion\` is the nearest real
+                      one), \`renamed-class\` (a class the library renamed;
+                      \`to\` is its successor). Your own classes are never
+                      read, nor a \`bb-*\` class the same file adds itself
+                      (\`class\`, \`:class\`, \`pt:*\`), \`inert-token\` (a
+                      \`--bb-*\` SET that the library neither declares nor
+                      reads; \`suggestion\` = the nearest token),
+                      \`inert-local\` (a local set on a \`.bb-*\` block whose
+                      component, and what it mounts, never reads it; \`to\`
+                      when it was renamed). A local on your own ancestor
+                      element, or one your CSS reads, is never judged.
+                      \`warnings[]\` (never fail the run) use the same shape with
+                      \`severity: "warning"\`: \`likely-squashed-slot\` (a slot
+                      name that looks like a camelCase key squashed, e.g.
+                      \`#createdat\`), \`local-bb-component\` (your own
+                      component uses the \`Bb\` prefix; rename it).
   changelog [--since <version>] [--until <version>] [--json]
                       Breaking changes between two releases — "what breaks if I
                       bump". \`--since\` is the version you are ON, and is

package/dist/ai/BbAccordion.md

@@ -573,6 +573,10 @@ A listener on `pt:header` runs after the toggle, never instead of it. The full
 grammar, the merge rules and the global map are in the
 [passthrough guide](./guides/passthrough.md).
 
+A `pt` value written in `<script>` (a constant, a preset, a wrapper's
+`pt` prop) is typed as `BbAccordionProps['pt']`, never an imported `PtValue`: see
+[passthrough § Typing `pt` in `<script>`](./guides/passthrough.md#typing-pt-in-script).
+
 ### Works well with
 
 - `BbIcon` — a rotating chevron in the header, driven by the slot's `open` (see
@@ -617,7 +621,7 @@ grammar, the merge rules and the global map are in the
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `header`, `panel`, `root`. States: `open`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `header`, `panel`, `root`. States: `open`. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbAccordionProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `eager` | `boolean \| undefined` | `false` |  | Prevents rendering content before it's made visible. |
 | `id` | `string \| undefined` |  |  | The root's `id`; the header button's id (`<id>_header`) derives from it. Generated when omitted. |
 | `modelValue` | `boolean \| undefined` | `false` |  | Used by v-model to trigger opening / closing the collapsible. An accordion with no `v-model` starts closed. |
@@ -625,7 +629,7 @@ grammar, the merge rules and the global map are in the
 
 ## Passthrough parts and states
 
-`pt:<part>="…"` restyles a part; `pt:<part>:<state>="…"` applies only while the state is on. A component-wide state is on for every part at once; a _per node_ state resolves on each node of a broadcast part (one row, one option, one day). Grammar and merge rules: `guides/passthrough.md`.
+`pt:<part>="…"` restyles a part; `pt:<part>:<state>="…"` applies only while the state is on. A component-wide state is on for every part at once; a _per node_ state resolves on each node of a broadcast part (one row, one option, one day). Grammar and merge rules: `guides/passthrough.md`. In `<script>`, type a `pt` value as `<Component>Props['pt']` (`<Component>Props<Row>['pt']` on a generic component); `PtValue` is not exported: `guides/passthrough.md` § Typing `pt` in `<script>`.
 
 | Part | What it is |
 | --- | --- |

package/dist/ai/BbAlert.md

@@ -409,6 +409,10 @@ A listener on `pt:close` runs after the alert closes, never instead of it. The
 full grammar, the merge rules and the global map are in the
 [passthrough guide](./guides/passthrough.md).
 
+A `pt` value written in `<script>` (a constant, a preset, a wrapper's
+`pt` prop) is typed as `BbAlertProps['pt']`, never an imported `PtValue`: see
+[passthrough § Typing `pt` in `<script>`](./guides/passthrough.md#typing-pt-in-script).
+
 ### Works well with
 
 - `BbToast` — pair them: the toast confirms _the action_ ("Saved"), the alert
@@ -447,19 +451,19 @@ full grammar, the merge rules and the global map are in the
 
 ## v-model
 
-- `v-model` — type: `boolean`
+- `v-model` — type: `boolean \| undefined`
 
 ## Props
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `close`, `icon`, `root`, `text`, `title`. States: —. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `close`, `icon`, `root`, `text`, `title`. States: —. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbAlertProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 | `ariaLive` | `"off" \| "polite" \| "assertive" \| undefined` |  |  | ARIA live region politeness. Defaults to `'assertive'` for destructive/warning variants, otherwise `'polite'`. |
 | `closeLabel` | `string \| undefined` |  |  | Visually hidden string used to label the close button. |
 | `hideClose` | `boolean \| undefined` | `false` |  | Defines whether to hide the close button. |
 | `icon` | `string \| undefined` |  |  | Name of a registered icon to use, or a full raw `<svg>` string (e.g. an SVG file imported with `?raw`). |
 | `iconSize` | `number \| ({ size?: any; } & string) \| keyof Sizes \| undefined` | `"16"` |  | Size of the icon to use. |
-| `modelValue` | `any` | `true` |  | Used by v-model, set type to any to avoid Vue casting it as false. Alerts are visible on mount; the model dismisses them. |
+| `modelValue` | `boolean \| undefined` | `true` |  | Used by v-model. Alerts are visible on mount; the model dismisses them. |
 | `role` | `"alert" \| "status" \| undefined` |  |  | Accessibility role for the alert container. Defaults to `'alert'` for destructive/warning variants, otherwise `'status'`. |
 | `text` | `string \| undefined` |  |  | Text content of the alert body. |
 | `title` | `string \| undefined` |  |  | Text content of the alert title. |
@@ -468,7 +472,7 @@ full grammar, the merge rules and the global map are in the
 
 ## Passthrough parts and states
 
-`pt:<part>="…"` restyles a part; `pt:<part>:<state>="…"` applies only while the state is on. A component-wide state is on for every part at once; a _per node_ state resolves on each node of a broadcast part (one row, one option, one day). Grammar and merge rules: `guides/passthrough.md`.
+`pt:<part>="…"` restyles a part; `pt:<part>:<state>="…"` applies only while the state is on. A component-wide state is on for every part at once; a _per node_ state resolves on each node of a broadcast part (one row, one option, one day). Grammar and merge rules: `guides/passthrough.md`. In `<script>`, type a `pt` value as `<Component>Props['pt']` (`<Component>Props<Row>['pt']` on a generic component); `PtValue` is not exported: `guides/passthrough.md` § Typing `pt` in `<script>`.
 
 | Part | What it is |
 | --- | --- |

package/dist/ai/BbAsterisk.md

@@ -18,7 +18,7 @@ restyle its root), and it does not read
 `required` or drive validation. You render it yourself wherever you build custom
 label content, so the marker matches the library's styling (`--bb-danger`).
 
-Most consumers never place it by hand: the `bitboss-ui/validated` form controls
+Most consumers never place it by hand: the form controls
 render it for you in their `#label` slot when a field is `required`/has rules and
 `config.requiredAsterisk` is enabled. Reach for `BbAsterisk` directly only when
 you compose a bespoke label outside those controls.
@@ -47,7 +47,7 @@ The practical consequence: the marker is a _visual_ affordance only, and
 without `required` (sighted users see a requirement that assistive tech cannot
 perceive), and never assume the asterisk is doing accessibility work.
 
-`showAsterisk` on the validated controls is also gated on the plugin option, so
+`showAsterisk` on the form controls is also gated on the plugin option, so
 with `requiredAsterisk: false` there is no way to render the marker through
 them at all — placing `BbAsterisk` by hand is then the only route.
 
@@ -76,15 +76,19 @@ control's `required` still carries the requirement.
 The full grammar, the merge rules and the global map are in the
 [passthrough guide](./guides/passthrough.md).
 
+A `pt` value written in `<script>` (a constant, a preset, a wrapper's
+`pt` prop) is typed as `BbAsteriskProps['pt']`, never an imported `PtValue`: see
+[passthrough § Typing `pt` in `<script>`](./guides/passthrough.md#typing-pt-in-script).
+
 ## Props
 
 | Prop | Type | Default | Required | Description |
 | --- | --- | --- | --- | --- |
-| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`. States: —. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. |
+| `pt:<part>`, `pt:<part>:<state>`, `pt` | `PtValue` | | | Passthrough — a class list, or `{ class, style, attrs }`, bound to one named part of the component; the state form applies only while that state is on. Parts: `root`. States: —. What each one is: _Passthrough parts and states_ below. `pt` is the object form with the same keys minus the prefix (`{ icon: '…', 'icon:loading': '…' }`). See `guides/passthrough.md`. In `<script>` a `pt` value is typed `BbAsteriskProps['pt']` (`PtValue` is not exported): § Typing `pt` in `<script>`. |
 
 ## Passthrough parts and states
 
-`pt:<part>="…"` restyles a part; `pt:<part>:<state>="…"` applies only while the state is on. A component-wide state is on for every part at once; a _per node_ state resolves on each node of a broadcast part (one row, one option, one day). Grammar and merge rules: `guides/passthrough.md`.
+`pt:<part>="…"` restyles a part; `pt:<part>:<state>="…"` applies only while the state is on. A component-wide state is on for every part at once; a _per node_ state resolves on each node of a broadcast part (one row, one option, one day). Grammar and merge rules: `guides/passthrough.md`. In `<script>`, type a `pt` value as `<Component>Props['pt']` (`<Component>Props<Row>['pt']` on a generic component); `PtValue` is not exported: `guides/passthrough.md` § Typing `pt` in `<script>`.
 
 | Part | What it is |
 | --- | --- |