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

package/scripts/lib/mcp-config.mjs

@@ -14,10 +14,22 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 export const MCP_SERVER_NAME = 'bitboss-ui';
-const COMMAND = 'npx';
+const COMMAND = 'node';
+
+/**
+ * Path to the installed CLI, relative to the project root.
+ *
+ * Relative on purpose: harnesses spawn a stdio server with the project root as
+ * its working directory, and a relative path is what lets a committed
+ * `.mcp.json` work on a teammate's machine. An absolute path would pin the
+ * config to whoever ran `ai-init`.
+ *
+ * Forward slashes even on Windows — Node accepts them, and JSON configs are
+ * shared across platforms.
+ */
+export const MCP_BIN_PATH = 'node_modules/bitboss-ui/bin/bitboss-ui.mjs';
 
 /**
  * The MCP server's own runtime needs, declared as OPTIONAL peers rather than
@@ -58,39 +70,31 @@ export function missingMcpPeers(root) {
 }
 
 /**
- * The npx spec MUST be pinned to this package's own version (2026-08-06
- * review): MCP hosts spawn the entry with non-TTY stdio, where `npx` installs
- * without prompting — an unpinned `npx bitboss-ui mcp` in a project whose
- * dependency is absent or not yet installed silently downloads and executes
- * whatever `bitboss-ui@latest` resolves to on the public registry (and even
- * with a local install, answers from a different version's knowledge base
- * than the one the project uses). This file ships as `scripts/lib/*` in the
- * published package, so its own `package.json` — two levels up — IS the
- * installed version.
+ * Invoke the INSTALLED binary directly, never `npx` (2026-09-09, superseding
+ * the 2026-08-06 pinned-npx ruling — see below).
+ *
+ * The 2026-08-06 review pinned the spec to this package's own version because
+ * MCP hosts spawn the entry with non-TTY stdio, where `npx` installs without
+ * prompting: an unpinned `npx bitboss-ui mcp` would silently download and
+ * execute whatever `bitboss-ui@latest` resolved to, and answer from a
+ * different version's knowledge base than the project uses.
+ *
+ * The pin fixed that and broke the server outright. `npx bitboss-ui@x.y.z mcp`
+ * runs the package OUT OF THE NPX CACHE, and the MCP entry resolves its
+ * optional peers (`@modelcontextprotocol/sdk`, `zod`) relative to the package
+ * it is running from. The cache directory never has them, so the server cannot
+ * start no matter what the project has installed — reported from a consumer
+ * project with both peers present.
+ *
+ * A path to the local binary satisfies the original ruling MORE completely
+ * than the pin did: it cannot reach the registry at all, so there is nothing
+ * to download and no `latest` to drift to. It also retires the pin's own
+ * maintenance problem, where a config written at one version kept naming that
+ * version after an upgrade, letting an agent query a manifest that disagreed
+ * with the code it was writing against. The binary on disk IS the installed
+ * version, by construction.
  */
-function resolveNpxSpec() {
-	try {
-		const pkg = JSON.parse(
-			readFileSync(
-				join(
-					dirname(fileURLToPath(import.meta.url)),
-					'..',
-					'..',
-					'package.json'
-				),
-				'utf-8'
-			)
-		);
-		if (pkg.name === MCP_SERVER_NAME && typeof pkg.version === 'string') {
-			return `${MCP_SERVER_NAME}@${pkg.version}`;
-		}
-	} catch {
-		/* fall through to the unpinned spec */
-	}
-	return MCP_SERVER_NAME;
-}
-
-const ARGS = [resolveNpxSpec(), 'mcp'];
+const ARGS = [MCP_BIN_PATH, 'mcp'];
 
 const stdioEntry = () => ({ command: COMMAND, args: [...ARGS] });
 const vscodeEntry = () => ({

package/scripts/lib/public-type-exports.mjs

@@ -0,0 +1,246 @@
+/**
+ * The library's public TYPE exports, read from `src/index.ts`.
+ *
+ * Two problems this solves, both reported from a consumer app:
+ *
+ * 1. `BbTableColumn`, `BbDropdownItem`, `BbTabsItem` and `BbBreadcrumbsItem`
+ *    are real, documented exports — but they are TYPES, not components. They
+ *    were absent from every machine-readable surface, so `get_component` could
+ *    not describe them and `check` treated `<BbDropdownItem>` as an unknown
+ *    component whose only offered remedy was `allowComponents` — which is
+ *    exactly wrong: the library owns the name, the markup is the mistake, and
+ *    allowlisting the tag silences every prop check on it forever.
+ *
+ * 2. The manifest printed prop types under names a consumer cannot import.
+ *    `BbDropdown.items` read `Item[]` (its module-local name; the export is
+ *    `BbDropdownItem`) and `BbTable.columns` read `InternalColumn<T>[]` — a
+ *    type alias declared inside `BbTable.vue` and exported nowhere at all.
+ *
+ * Both are fixed at the source: the export list is emitted into
+ * `components.json` (so the CLI, the ESLint rules and the MCP server can all
+ * answer for a type name), and the same list rewrites extracted type strings
+ * to the importable spelling.
+ *
+ * Parsing is done with the TypeScript AST rather than a regex: the export
+ * blocks carry JSDoc between the braces (`@deprecated` markers on the v2
+ * aliases), which a brace-matching regex reads as export names.
+ */
+import ts from 'typescript';
+
+/**
+ * @typedef {object} PublicTypeExport
+ * @property {string} name       the importable name (`BbDropdownItem`)
+ * @property {string} local      the name inside its module (`Item`)
+ * @property {string} module     the specifier it is re-exported from
+ * @property {string|null} component  owning component, when `module` is a
+ *   component types file (`./components/BbTable/types` → `BbTable`)
+ * @property {boolean} deprecated `@deprecated` in the export's own JSDoc
+ */
+
+/** `./components/BbTable/types` → `BbTable`; anything else → null. */
+function componentFromModule(moduleSpecifier) {
+	const match = /^\.\/components\/([A-Za-z0-9_]+)\/types$/.exec(
+		moduleSpecifier
+	);
+	return match ? match[1] : null;
+}
+
+/**
+ * Every `export type { … } from '…'` name in the given `src/index.ts` source.
+ *
+ * Only type-only re-exports count. A value export (`export { bitbossUiPlugin }`)
+ * is a runtime binding, not a type a consumer would ever write as a tag, and
+ * mixing the two would let `useToast` answer a "did you mean a type?" question
+ * with a composable.
+ *
+ * @param {string} source contents of `src/index.ts`
+ * @returns {PublicTypeExport[]}
+ */
+export function parsePublicTypeExports(source) {
+	const file = ts.createSourceFile(
+		'index.ts',
+		source,
+		ts.ScriptTarget.Latest,
+		/* setParentNodes */ true
+	);
+
+	/** @type {PublicTypeExport[]} */
+	const exports = [];
+
+	for (const statement of file.statements) {
+		if (!ts.isExportDeclaration(statement)) continue;
+		// `export type { … }` — or `export { type X }`, handled per-specifier below.
+		const declarationIsTypeOnly = statement.isTypeOnly;
+		const clause = statement.exportClause;
+		if (!clause || !ts.isNamedExports(clause)) continue;
+		const moduleSpecifier =
+			statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier)
+				? statement.moduleSpecifier.text
+				: '';
+
+		for (const specifier of clause.elements) {
+			if (!declarationIsTypeOnly && !specifier.isTypeOnly) continue;
+			const name = specifier.name.text;
+			const local = specifier.propertyName?.text ?? name;
+			exports.push({
+				name,
+				local,
+				module: moduleSpecifier,
+				component: componentFromModule(moduleSpecifier),
+				deprecated: hasDeprecatedTag(specifier, source),
+			});
+		}
+	}
+
+	return exports;
+}
+
+/**
+ * Whether the JSDoc immediately before a specifier carries `@deprecated`.
+ *
+ * The comment sits inside the braces, attached to nothing the AST calls a
+ * documented node, so `ts.getJSDocTags` finds nothing — the leading trivia of
+ * the specifier is where it actually lives.
+ */
+function hasDeprecatedTag(specifier, source) {
+	const ranges =
+		ts.getLeadingCommentRanges(source, specifier.getFullStart()) ?? [];
+	return ranges.some((range) =>
+		/@deprecated/.test(source.slice(range.pos, range.end))
+	);
+}
+
+/**
+ * Module-local name → importable name, for one module.
+ *
+ * Scoped per module on purpose: `Item` means `BbDropdownItem` inside
+ * `components/BbDropdown/types` and `BbBreadcrumbsItem` inside
+ * `components/BbBreadcrumbs/types`. A global map would have to pick one and
+ * would mislabel the other.
+ *
+ * A deprecated alias never wins: `BbTabsItem` and `BbTabItem` are the same
+ * type, and the manifest should print the name we want written today.
+ *
+ * @param {PublicTypeExport[]} exports
+ * @param {string} moduleSpecifier
+ * @returns {Map<string, string>}
+ */
+export function localToPublicNames(exports, moduleSpecifier) {
+	/** @type {Map<string, PublicTypeExport>} */
+	const chosen = new Map();
+	for (const entry of exports) {
+		if (entry.module !== moduleSpecifier) continue;
+		const held = chosen.get(entry.local);
+		// First one wins, EXCEPT that a live name always displaces a deprecated
+		// one: `BbTableColumn` is re-exported as the deprecated `TableColumn`
+		// first and under its own name second, and source order alone would
+		// print the spelling we are trying to retire.
+		if (!held || (held.deprecated && !entry.deprecated)) {
+			chosen.set(entry.local, entry);
+		}
+	}
+	return new Map([...chosen].map(([local, entry]) => [local, entry.name]));
+}
+
+/**
+ * The type-parameter names an SFC declares in `<script setup generic="…">`.
+ *
+ * These must never be rewritten. `BbSelectPopover` declares `generic="Item =
+ * any"` while `BbDropdown` exports a TYPE whose module-local name is also
+ * `Item` — rewriting by name alone would one day turn a type VARIABLE into
+ * `BbDropdownItem` and quietly publish a contract that says the wrong thing.
+ * No component collides today; this is what keeps that true.
+ *
+ * @param {string} source the .vue file
+ * @returns {Set<string>}
+ */
+export function sfcGenericParameters(source) {
+	const match = /<script[^>]*\bgeneric=("([^"]*)"|'([^']*)')/.exec(source);
+	const declaration = match?.[2] ?? match?.[3];
+	if (!declaration) return new Set();
+
+	/** Split on top-level commas only: `T extends Record<string, any>` is one. */
+	const parts = [];
+	let depth = 0;
+	let current = '';
+	for (const char of declaration) {
+		if (char === '<' || char === '{' || char === '(' || char === '[') depth++;
+		else if (char === '>' || char === '}' || char === ')' || char === ']')
+			depth--;
+		if (char === ',' && depth === 0) {
+			parts.push(current);
+			current = '';
+			continue;
+		}
+		current += char;
+	}
+	parts.push(current);
+
+	return new Set(
+		parts
+			.map((part) => /^\s*([A-Za-z_$][A-Za-z0-9_$]*)/.exec(part)?.[1])
+			.filter((name) => Boolean(name))
+	);
+}
+
+/**
+ * Rewrite bare identifiers in a printed type string through `aliases`.
+ *
+ * Word-boundary matching only — never a substring: `Item` must not touch
+ * `BbTreeItem`, and `Meta` must not touch `Metadata`. Generic arguments,
+ * unions and array suffixes all survive because only the identifier tokens are
+ * replaced (`Array<InternalColumn<K>>` → `Array<BbTableColumn<K>>`).
+ *
+ * @param {string} type
+ * @param {Map<string, string>} aliases
+ * @returns {string}
+ */
+export function rewriteTypeNames(type, aliases) {
+	if (!type || aliases.size === 0) return type;
+	return type.replace(/\b[A-Za-z_$][A-Za-z0-9_$]*\b/g, (identifier) => {
+		// Never rewrite a property name (`{ key: Item }` is fine, `foo.Item` is
+		// a qualified name whose right side is not ours to rename).
+		return aliases.get(identifier) ?? identifier;
+	});
+}
+
+/**
+ * Type names declared inside an SFC's `<script>` blocks.
+ *
+ * These are the names that must never reach a published prop type. A type in a
+ * component's `types.ts` that is not exported is a DECISION — `OffCanvasSize`
+ * is `'xs' | 'sm' | …`, an app writes `size="lg"`, and exporting a name to
+ * spell a string literal would be a permanent compatibility promise bought for
+ * no capability. A type declared in the .vue file is not a decision: it is
+ * plumbing that escaped, and `BbTable.columns` published `InternalColumn<T>[]`
+ * for months because nothing looked.
+ *
+ * The script blocks are extracted before parsing rather than handing the whole
+ * .vue to TypeScript: the template is not TypeScript, and while the parser
+ * tolerates it, what it makes of `<div v-if="x < y">` is not worth relying on.
+ *
+ * @param {string} source the .vue file
+ * @returns {Set<string>}
+ */
+export function sfcDeclaredTypeNames(source) {
+	/** @type {Set<string>} */
+	const names = new Set();
+	for (const [, script] of source.matchAll(
+		/<script\b[^>]*>([\s\S]*?)<\/script>/g
+	)) {
+		const file = ts.createSourceFile(
+			'sfc.ts',
+			script,
+			ts.ScriptTarget.Latest,
+			true
+		);
+		const visit = (node) => {
+			if (ts.isTypeAliasDeclaration(node) || ts.isInterfaceDeclaration(node)) {
+				names.add(node.name.text);
+			}
+			ts.forEachChild(node, visit);
+		};
+		ts.forEachChild(file, visit);
+	}
+	return names;
+}

package/scripts/lib/validate-bb-markup.mjs

@@ -17,7 +17,11 @@ import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parse } from 'vue/compiler-sfc';
-import { isFallthroughAttr, NATIVE_DOM_EVENTS } from './html-attributes.mjs';
+import {
+	ELEMENT_DOM_EVENTS,
+	isFallthroughAttr,
+	NATIVE_DOM_EVENTS,
+} from './html-attributes.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_MANIFEST = join(HERE, '../../dist/ai/components.json');
@@ -156,6 +160,61 @@ export function nearestName(key, candidates) {
 	return best;
 }
 
+/**
+ * Event names a consumer reaches for, mapped to the names our components
+ * actually emit, in preference order.
+ *
+ * Edit distance is the wrong tool for events. Props are misspelled, so
+ * `hideLabl` → `hideLabel` works; events are mis-VOCABULARIZED — someone writes
+ * the word their previous library used, or the word the interaction is called
+ * in English. `close` to `hide` is three edits and `close` to `hidden` is five,
+ * so `nearestName` finds nothing and the hint degrades to dumping every emitted
+ * event. That is exactly the case that shipped: `<BbDialog @close>` got
+ * "emitted events: hidden, hide, show, shown, update:modelValue" — a menu, not
+ * an answer.
+ *
+ * Only the resolved candidates that a component REALLY emits are offered, so
+ * this map can list generously without inventing events on components that
+ * don't have them.
+ */
+const EVENT_SYNONYMS = new Map([
+	// `hidden` before `hide`: the native `close` event these authors are
+	// currently getting fires at the END of the close, so `hidden` is the
+	// suggestion that preserves the timing they already have. `cancel` keeps
+	// `hide` first for the same reason — it fires when close is REQUESTED.
+	['close', ['hidden', 'hide', 'update:modelValue']],
+	['closed', ['hidden', 'hide']],
+	['dismiss', ['hidden', 'hide']],
+	['dismissed', ['hidden', 'hide']],
+	['hidden', ['hide']],
+	['open', ['show', 'shown', 'update:modelValue']],
+	['opened', ['shown', 'show']],
+	['reveal', ['show', 'shown']],
+	['shown', ['show']],
+	['toggle', ['update:modelValue']],
+	['change', ['update:modelValue']],
+	['changed', ['update:modelValue']],
+	['update', ['update:modelValue']],
+	['input', ['update:modelValue']],
+	['cancel', ['hide', 'hidden']],
+]);
+
+/**
+ * The event this component emits that the author most likely meant by `name`:
+ * a spelling near-miss first (`resizecolumn` → `resize:column`), then the
+ * vocabulary map above. Null when neither has an answer.
+ * @param {string} name event name exactly as written, modifiers stripped
+ * @param {Set<string>} declared events this component emits
+ */
+export function nearestEventName(name, declared) {
+	const near = nearestName(name, declared);
+	if (near) return near;
+	for (const candidate of EVENT_SYNONYMS.get(name) ?? []) {
+		if (declared.has(candidate)) return candidate;
+	}
+	return null;
+}
+
 /**
  * The opposite-polarity spellings of a boolean prop name.
  *
@@ -286,7 +345,11 @@ const INTENT_ALIASES = {
  * @typedef {{ name: string, new?: string | null, since?: string, migration?: string, silent?: boolean }} RemovedEntry
  * @typedef {{ name: string, props: Array<{ name: string }>, models: Array<{ name: string }>, referenceOnly?: boolean, removed?: RemovedEntry[], renamed?: Array<{ from: string, to: string }> }} ComponentSurface
  * @typedef {Map<string, ComponentSurface>} ManifestMap
- * @typedef {{ component: string, attr: string, line?: number, kind: 'unknown-prop' | 'unknown-model' | 'removed-prop' | 'unknown-slot' | 'unknown-event', message: string, hint?: string }} Finding
+ * `fallthrough` marks a finding that describes markup which is not a typo and
+ * may well be doing something today — a native listener reaching the root
+ * element — but is outside the component's contract. It is the flag a caller
+ * uses to report at a lower severity; see `checkEvent`.
+ * @typedef {{ component: string, attr: string, line?: number, kind: 'unknown-prop' | 'unknown-model' | 'removed-prop' | 'unknown-slot' | 'unknown-event', message: string, hint?: string, fallthrough?: boolean }} Finding
  */
 
 /**
@@ -316,6 +379,20 @@ export function manifestFromComponents(input) {
 	const list = Array.isArray(input) ? input : (input.components ?? []);
 	/** @type {ManifestMap} */
 	const map = new Map();
+	/*
+	 * Public TYPE exports, carried as a property on the map rather than as
+	 * entries in it. `manifest.get(name)` means "this is a component I can
+	 * check the props of" at nine call sites across the ESLint rules and the
+	 * doc scanners; a type answering that lookup would make every one of them
+	 * validate attributes against an empty surface. The property is invisible
+	 * to `get`, to iteration, and to those call sites.
+	 */
+	map.types = new Map(
+		(Array.isArray(input) ? [] : (input.types ?? [])).map((entry) => [
+			entry.name,
+			entry,
+		])
+	);
 	for (const entry of list) {
 		map.set(entry.name, {
 			name: entry.name,
@@ -401,7 +478,7 @@ export function validateVueSnippet(code, manifest, options = {}) {
 }
 
 /**
- * @typedef {{ attr: string, kind: 'unknown-prop' | 'unknown-model' | 'removed-prop' | 'unknown-slot' | 'unknown-event', message: string, hint?: string }} AttrFinding
+ * @typedef {{ attr: string, kind: 'unknown-prop' | 'unknown-model' | 'removed-prop' | 'unknown-slot' | 'unknown-event', message: string, hint?: string, fallthrough?: boolean }} AttrFinding
  */
 
 /**
@@ -673,15 +750,37 @@ export function createComponentChecker(surface, options = {}) {
 		 * unknown component events only under `strictTemplates`. A consumer's
 		 * migration report found it.
 		 *
-		 * Accepted without consulting the manifest: any NATIVE DOM event, since
+		 * Accepted without consulting the manifest: any UNIVERSAL DOM event, since
 		 * Vue passes an undeclared listener through to the root element —
 		 * `@click` on BbButton is good markup even though BbButton emits only
 		 * `update:modelValue`.
 		 *
+		 * That blanket pass used to cover every DOM event we listed, and it hid
+		 * a second bug class. An event that fires on only a few element types —
+		 * `close`, `cancel`, `play` — falls through the same way, but whether it
+		 * ever fires depends on what the component's root element happens to be,
+		 * which is an internal detail no consumer should be reasoning about.
+		 * `<BbDialog @close>` works, because that root is a native `<dialog>`;
+		 * `<BbAlert @close>` is inert. Both compile clean and neither is a typo.
+		 * Those names (`ELEMENT_DOM_EVENTS`) get their own `fallthrough` finding
+		 * so the caller can say "this is not the contract" instead of the
+		 * flatly-wrong "this event does not exist" — the wording that led one
+		 * migration report to file a live `@close` handler as dead code.
+		 *
 		 * Silent when the component declares no events at all: that is true of
 		 * reference-only surfaces and of anything whose manifest entry predates
 		 * event extraction, and guessing there would cry wolf — the same guard
 		 * `checkSlot` uses.
+		 *
+		 * A third case is neither of those: `@x` where the component declares a
+		 * PROP called `onX`. Vue compiles every `@x` to an `onX` vnode entry, and
+		 * prop resolution claims it before listeners are ever considered — so the
+		 * handler runs, bound to the prop. BbButton's Inertia visit callbacks are
+		 * exactly this shape (`onSuccess`, `onFinish`, `onCancelToken`, …), which
+		 * is why `<BbButton href @success>` has always worked. It is not a typo
+		 * and not a fall-through; it is the documented `:on-success` prop reached
+		 * by a spelling the guides tell you not to use, because it silently
+		 * breaks the moment someone adds a modifier or a second handler.
 		 */
 		checkEvent(rawName) {
 			if (!rawName) return null;
@@ -700,14 +799,48 @@ export function createComponentChecker(surface, options = {}) {
 			if (name.startsWith('update:') && modelKeys.has(toCamel(name.slice(7))))
 				return null;
 
-			const near = nearestName(name, declared);
+			// `@success` → the declared `onSuccess` PROP. Real, working markup in
+			// the one spelling the guides steer away from.
+			const camel = toCamel(name);
+			const callbackProp = `on${camel.charAt(0).toUpperCase()}${camel.slice(1)}`;
+			if (propKeys.has(callbackProp)) {
+				return {
+					attr: `@${rawName}`,
+					kind: 'unknown-event',
+					fallthrough: true,
+					message:
+						`${surface.name} does not emit \`${name}\`, but it declares \`${callbackProp}\` as a PROP, ` +
+						'so Vue binds this handler to that prop and it does run. Prefer the prop spelling: ' +
+						'the listener form takes no modifiers, and a second handler for the same name silently ' +
+						'becomes an array the prop is not typed for',
+					hint: `use \`:${toKebab(callbackProp)}="…"\``,
+				};
+			}
+
+			const near = nearestEventName(name, declared);
+			const suggestion = near
+				? `did you mean \`@${near}\`?`
+				: `emitted events: ${[...declared].sort().join(', ')}`;
+
+			if (ELEMENT_DOM_EVENTS.has(name)) {
+				return {
+					attr: `@${rawName}`,
+					kind: 'unknown-event',
+					fallthrough: true,
+					message:
+						`${surface.name} does not emit \`${name}\`, so this listener falls through to its root ` +
+						"element as a native DOM listener. It fires on the element's own schedule, not the " +
+						"component's, and only if that root happens to be an element that dispatches " +
+						`\`${name}\` — which is internal and can change without a breaking release`,
+					hint: suggestion,
+				};
+			}
+
 			return {
 				attr: `@${rawName}`,
 				kind: 'unknown-event',
 				message: `event \`${name}\` is not emitted by ${surface.name}`,
-				hint: near
-					? `did you mean \`@${near}\`?`
-					: `emitted events: ${[...declared].sort().join(', ')}`,
+				hint: suggestion,
 			};
 		},
 		checkSlot(rawName) {
@@ -1126,6 +1259,69 @@ function compilerItemsMayBeAsync(node) {
 	return false; // `items` not bound at all — defaults to `[]`, definitely sync.
 }
 
+/**
+ * `BbTabs` → `BbTabs'`, `BbTable` → `BbTable's`. Shared so the CLI, the ESLint
+ * rule and the MCP server all form the same sentence about a component.
+ * @param {string} owner
+ */
+export const possessive = (owner) =>
+	owner.endsWith('s') ? `${owner}'` : `${owner}'s`;
+
+/**
+ * Message + hint for a `Bb*` tag that is not a component.
+ *
+ * Three different situations wore one message, and the hint offered the same
+ * remedy to all three — allowlist it — which is right for exactly one:
+ *
+ * - **A public TYPE written as a tag.** `BbTableColumn`, `BbDropdownItem` and
+ *   friends are real exports, so a consumer reasonably assumes they are
+ *   components. They are not: they type a prop. Allowlisting is the worst
+ *   available answer, because the markup IS wrong and the allowlist then
+ *   silences every real check on that tag forever. Reported from a consumer app
+ *   that took the hint.
+ * - **A typo.** `BbButtn` is one edit from `BbButton`, and the prop checker has
+ *   suggested nearest names for years while this one dead-ended at "check the
+ *   spelling".
+ * - **An app-owned component** that happens to start with `Bb`. The one case
+ *   the allowlist is for — now stated with what it costs.
+ *
+ * @param {string} name
+ * @param {ManifestMap} manifest
+ * @returns {{ message: string, hint: string }}
+ */
+export function unknownComponentFinding(name, manifest) {
+	const type = manifest.types?.get(name);
+	if (type) {
+		const use = type.usedBy?.[0];
+		const where = use
+			? `it types ${possessive(use.component)} \`${use.name}\` ${use.surface}`
+			: type.component
+				? `it belongs to ${type.component}`
+				: 'it is part of the public API surface, not the component set';
+		const importName = type.replacedBy ?? name;
+		const deprecation = type.replacedBy
+			? ` \`${name}\` is a deprecated alias — import \`${type.replacedBy}\`.`
+			: '';
+		return {
+			message: `\`${name}\` is a type export, not a component`,
+			hint:
+				`${where}, so pass it as a value instead of writing it as a tag: ` +
+				`\`import type { ${importName} } from 'bitboss-ui'\`.${deprecation} ` +
+				'Do NOT allowlist it — the library owns this name.',
+		};
+	}
+
+	const suggestion = nearestName(name, manifest.keys());
+	return {
+		message: `component \`${name}\` is not in the bitboss-ui manifest`,
+		hint:
+			(suggestion ? `Did you mean \`${suggestion}\`? ` : '') +
+			'Check the spelling against dist/ai/index.md Consumer API. If your app owns this component, allowlist it: ' +
+			`\`bitboss-ui.allowComponents: ["${name}"]\` in package.json, or \`--allow-component ${name}\` — ` +
+			'which skips the tag entirely, so no prop, event or slot on it is ever checked again.',
+	};
+}
+
 /**
  * Validate one `<Bb…>` element node against the manifest surface.
  * @param {{ tag: string, props: Array<Record<string, any>> }} node
@@ -1155,10 +1351,7 @@ function validateElement(node, manifest, findings) {
 			attr: '',
 			line: tagLine,
 			kind: 'unknown-prop',
-			message: `component \`${name}\` is not in the bitboss-ui manifest`,
-			hint:
-				'Check the spelling against dist/ai/index.md Consumer API. If your app owns this component, allowlist it: ' +
-				`\`bitboss-ui.allowComponents: ["${name}"]\` in package.json, or \`--allow-component ${name}\`.`,
+			...unknownComponentFinding(name, manifest),
 		});
 		return;
 	}