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

package/llms.txt

@@ -10,7 +10,7 @@ Note: the `dist/` paths below resolve inside the installed npm package (`node_mo
 - [Complete knowledge base](https://llms-bitboss-ui.bitboss.it/dist/llms-full.txt): Everything concatenated (~2 MB). Bulk ingestion only — too large to prompt with.
 - [AI Router](dist/ai/guides/ai-router.md): **Start here** — tiny hop map for any coding agent (which file to open next).
 - [Component index](dist/ai/index.md): Full component catalogue with agent rules, grouped by category. Each entry links a typed contract (props/events/slots/v-model).
-- [Component manifest](dist/ai/components.json): Machine-readable API surface of every component, for programmatic validation.
+- [Component manifest](dist/ai/components.json): Machine-readable API surface of every component, for programmatic validation. Its `types` array lists the public TYPE exports with a `usage` tier (`api` = the ones you reach for) and, on the `api` ones, a `usedBy` array naming the component and prop or event each is the type OF — `BbTableColumn` is `usedBy` `BbTable.columns`, a value you pass, not a tag you write.
 - CLI / MCP: `npx bitboss-ui check` (markup vs components.json), `npx bitboss-ui mcp` (search/get/validate), `npx bitboss-ui ai-init [--mcp]`.
 - [Agent Contract](dist/ai/guides/agent-contract.md): Mandatory rules before writing any component usage code.
 - [Installation & Plugin Setup](dist/ai/guides/installation-and-plugin-setup.md): Canonical installation, style handling, and plugin configuration.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bitboss-ui",
-	"version": "3.0.0-beta.21",
+	"version": "3.0.0-beta.22",
 	"description": "Vue 3 component library by BitBoss: forms, selects, layout, overlays, and more.",
 	"license": "MIT",
 	"type": "module",
@@ -102,6 +102,7 @@
 		"@tanstack/vue-virtual": "^3.13.24",
 		"@vueuse/core": "^14.3.0",
 		"dayjs": "^1.11.20",
+		"ignore": "^7.0.9",
 		"lodash.deburr": "^4.1.0",
 		"lodash.throttle": "^4.1.1",
 		"maska": "^3.2.0",
@@ -148,6 +149,7 @@
 		"@rollup/plugin-terser": "^1.0.0",
 		"@storybook/addon-docs": "^10.4.6",
 		"@storybook/vue3-vite": "^10.4.6",
+		"@tailwindcss/postcss": "^4.3.3",
 		"@types/lodash.deburr": "^4.1.9",
 		"@types/lodash.throttle": "^4.1.9",
 		"@types/mime": "^4.0.0",
@@ -161,7 +163,7 @@
 		"@vitest/browser-playwright": "^4.1.10",
 		"@vue/language-core": "~3.1.5",
 		"@vue/test-utils": "^2.4.11",
-		"autoprefixer": "^10.5.0",
+		"autoprefixer": "^10.5.5",
 		"concurrently": "^9.2.1",
 		"eslint": "^9.39.4",
 		"eslint-config-prettier": "^10.1.8",
@@ -179,16 +181,16 @@
 		"playwright": "^1.61.1",
 		"postcss": "^8.5.14",
 		"postcss-html": "^1.8.1",
-		"postcss-import": "^16.1.1",
+		"postcss-nested": "^8.0.1",
 		"postcss-value-parser": "^4.2.0",
 		"prettier": "3.8.3",
-		"prettier-plugin-tailwindcss": "^0.8.0",
+		"prettier-plugin-tailwindcss": "^0.8.1",
 		"query-string": "^9.4.1",
 		"rollup-plugin-typescript2": "^0.37.0",
 		"storybook": "^10.4.6",
 		"stylelint": "^17.11.0",
 		"stylelint-order": "^8.1.1",
-		"tailwindcss": "^3.4.10",
+		"tailwindcss": "^4.3.3",
 		"typescript": "^6.0.3",
 		"vee-validate": "^4.15.1",
 		"vite": "^8.0.12",

package/scripts/lib/ensure-manifest.mjs

@@ -22,6 +22,15 @@ const ROOT = fileURLToPath(new URL('../..', import.meta.url));
 /** The one path every validator defaults to. */
 export const MANIFEST_PATH = join(ROOT, 'dist/ai/components.json');
 
+/**
+ * `list_changes` reads this, and `generate-docs` does NOT write it — only the
+ * full build does, via `scripts/generate-ai-changelog.mjs`. So an unbuilt gate
+ * job got a `dist/ai` that looked complete and was not: the MCP server answered
+ * `list_changes` with "changelog.json not found", `check:mcp` failed three
+ * assertions and then died on the missing release list.
+ */
+export const CHANGELOG_PATH = join(ROOT, 'dist/ai/changelog.json');
+
 /**
  * Generate the contract when absent. Cheap (~2.5s) and idempotent, so callers
  * can invoke it unconditionally.
@@ -30,10 +39,24 @@ export const MANIFEST_PATH = join(ROOT, 'dist/ai/components.json');
  * @returns {string} the manifest path.
  */
 export function ensureManifest(label = 'ensure-manifest') {
-	if (existsSync(MANIFEST_PATH)) return MANIFEST_PATH;
-	console.log(
-		`[${label}] dist/ai/components.json missing — running generate-docs…`
-	);
-	execSync('npm run generate-docs', { cwd: ROOT, stdio: 'inherit' });
+	if (!existsSync(MANIFEST_PATH)) {
+		console.log(
+			`[${label}] dist/ai/components.json missing — running generate-docs…`
+		);
+		execSync('npm run generate-docs', { cwd: ROOT, stdio: 'inherit' });
+	}
+
+	// Separate check: `generate-docs` writes the contracts but not the
+	// changelog, so a tree can have one and not the other.
+	if (!existsSync(CHANGELOG_PATH)) {
+		console.log(
+			`[${label}] dist/ai/changelog.json missing — running generate-ai-changelog…`
+		);
+		execSync('node scripts/generate-ai-changelog.mjs', {
+			cwd: ROOT,
+			stdio: 'inherit',
+		});
+	}
+
 	return MANIFEST_PATH;
 }

package/scripts/lib/eslint-plugin.d.ts

@@ -28,8 +28,42 @@ export type BitbossUiRuleName =
 	| 'no-unknown-slots'
 	| 'no-active-class-on-root-link'
 	| 'no-navigation-attr-fallthrough'
+	| 'no-unknown-event'
+	| 'no-unknown-token'
 	| 'no-reverse-false';
 
+/** Options accepted by `bitboss-ui/no-unknown-token`. */
+export interface NoUnknownTokenOptions {
+	/**
+	 * Token names to always permit — for `--bb-*` names you declare in your own
+	 * stylesheet, which this rule cannot see. The alternative, and usually the
+	 * better one, is a fallback: `var(--bb-mine, #fff)` is never reported.
+	 */
+	allowTokens?: string[];
+	/**
+	 * Stylesheet to read the declared token list from. Defaults to the
+	 * `dist/styles.css` inside the installed package, so a normal install needs
+	 * no configuration. A path that does not resolve disarms the rule rather
+	 * than failing: no data, no accusation.
+	 */
+	stylesPath?: string;
+}
+
+/** Options accepted by `bitboss-ui/no-unknown-event`. */
+export interface NoUnknownEventOptions {
+	/** Component names to skip entirely. */
+	allowComponents?: string[];
+	/**
+	 * Event names to always permit, on any component.
+	 *
+	 * The escape hatch for a codebase that leans on a specific fallthrough
+	 * listener on purpose — `['close']` where every dialog wrapper listens for
+	 * the native `<dialog>` event — without disabling the rule and losing the
+	 * renamed-event half of it.
+	 */
+	allowEvents?: string[];
+}
+
 /** Options accepted by `bitboss-ui/no-reverse-false`. */
 export interface NoReverseFalseOptions {
 	/** Component names to skip entirely. */
@@ -71,6 +105,7 @@ export const requirePartnerProp: Rule.RuleModule;
 export const noUnknownSlots: Rule.RuleModule;
 export const noActiveClassOnRootLink: Rule.RuleModule;
 export const noNavigationAttrFallthrough: Rule.RuleModule;
+export const noUnknownEvent: Rule.RuleModule;
 export const noReverseFalse: Rule.RuleModule;
 
 /**

package/scripts/lib/eslint-plugin.mjs

@@ -50,20 +50,47 @@
  *     BbBadgeButton), is not an anchor. The attribute renders, inert, and
  *     nothing ever warns (Bottega P3-R2, BTG-006: `<BbBadge href>` painted a
  *     non-interactive pill).
+ *   - `no-unknown-event` — an `@event` a Bb* component does not emit. The
+ *     event twin of `no-navigation-attr-fallthrough`, and the only rule the
+ *     recommended preset sets to `warn`: an undeclared listener falls through
+ *     to the root element, so it may be a deliberate native listener rather
+ *     than a mistake. `<BbDialog @close>` is the case that prompted it — live,
+ *     because that root is a native `<dialog>`, but outside the contract and
+ *     unordered against the component's own `hidden`; a consumer's migration
+ *     report filed it as dead code. `bitboss-ui check` has flagged this since
+ *     Q10.12 via the shared `checkEvent`; the editor never did, because every
+ *     rule here read `bind`/`model` and skipped `on`.
+ *   - `no-unknown-token` — a bare `var(--bb-…)` naming a token the installed
+ *     package does not declare. The first rule here that reads CSS rather than
+ *     the template AST, and the first promoted from a `bitboss-ui check`
+ *     ADVISORY HINT: the same consumer report that filed `no-unknown-event`
+ *     made the structural point that `check` is what nobody runs while ESLint
+ *     runs in the editor and in pre-commit. Only this hint crossed over, of the
+ *     three `check` carries. It is the only one stating a fact rather than a
+ *     guess — an undefined custom property is invalid-at-computed-value-time,
+ *     so CSS discards the entire declaration. The hand-rolled avatar and
+ *     spinner detectors stay in `check` on purpose: they are guesses (a round
+ *     `<img>` is sometimes a logo), and a rule that fires on correct code
+ *     spends the trust every other rule here depends on.
  */
 
 import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findTokenUses, loadKnownTokens } from './hand-roll-hints.mjs';
 import {
 	checkNavAttrFallthrough,
 	checkPartnerProps,
 	createComponentChecker,
 	loadManifest,
 	NAV_ATTRS,
+	unknownComponentFinding,
 	PARTNER_PROP_PAIRS,
 	toCamel,
 } from './validate-bb-markup.mjs';
 import { matchNameStyle, planAttributeFix } from './migrate-fix.mjs';
 
+const HERE = dirname(fileURLToPath(import.meta.url));
 const BB_TAG = /^Bb[A-Za-z0-9]+$/;
 /** `bitboss-ui` and its subpath entrypoints (`bitboss-ui/validated`, …). */
 const BITBOSS_IMPORT = /^bitboss-ui(\/|$)/;
@@ -150,8 +177,15 @@ const noUnknownAttributes = {
 			},
 		],
 		messages: {
-			unknownComponent:
-				'component `{{component}}` is not in the bitboss-ui manifest',
+			/*
+			 * One message with the hint folded in, rather than the bare
+			 * "not in the manifest" this used to print. The three reasons a `Bb*`
+			 * tag is unknown want three different answers — a public TYPE written
+			 * as a tag, a typo, an app-owned component — and the editor is exactly
+			 * where the reader acts on the answer without opening a terminal. See
+			 * `unknownComponentFinding`.
+			 */
+			unknownComponent: '{{message}} — {{hint}}',
 			finding: '{{message}}',
 		},
 	},
@@ -262,7 +296,7 @@ const noUnknownAttributes = {
 						context.report({
 							node: node.startTag,
 							messageId: 'unknownComponent',
-							data: { component: name },
+							data: unknownComponentFinding(name, manifest),
 						});
 						return;
 					}
@@ -919,6 +953,105 @@ const noNavigationAttrFallthrough = {
 	},
 };
 
+/**
+ * An `@event` on a `Bb*` component that names nothing the component emits.
+ *
+ * The check itself is not new — `createComponentChecker`'s `checkEvent` has
+ * driven it in `bitboss-ui check` and the MCP `validate` tool since Q10.12.
+ * What was new is that the EDITOR never ran it: every rule in this plugin read
+ * `bind` and `model` directives and skipped `on` entirely, so the one gate a
+ * consuming agent actually works against was the one gate blind to it.
+ *
+ * That is how `<WhatsAppConnectedCard @close>` shipped. The migration report
+ * that found it called the handler dead code; it was not. BbDialog's root is a
+ * native `<dialog>`, so the listener bound as a real DOM listener and fired.
+ * `close` is in `ELEMENT_DOM_EVENTS` for that reason, and `checkEvent` returns
+ * it as a `fallthrough` finding rather than an unknown one.
+ *
+ * Reported at `warn` in the recommended preset — alone among these rules, all
+ * of which are `error`. That asymmetry is the point. An unknown prop is a typo
+ * with one correct fix. An undeclared event listener may be a deliberate native
+ * listener on a root the author knows, so this rule flags the contract, not a
+ * mistake, and leaves `eslint-disable-next-line` as the answer for anyone who
+ * meant it.
+ * @type {import('eslint').Rule.RuleModule}
+ */
+const noUnknownEvent = {
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				"Flag an `@event` on a Bb* component that the component does not emit. Vue passes an undeclared listener through to the root element, so the markup compiles clean and `vue-tsc` stays quiet outside `strictTemplates`: a renamed event (beta.9's `resize` → `resize:column`) reads as working code, and an element-specific DOM event like `@close` binds to whatever the root happens to be — live on BbDialog, whose root is a native `<dialog>`, inert on BbAlert. A third case is neither: `@success` on BbButton binds the declared `onSuccess` PROP, so it runs, and the rule points at the documented `:on-success` spelling instead. Universal DOM events (`@click`, `@keydown`) are always allowed.",
+			recommended: true,
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					manifestPath: { type: 'string' },
+					failClosed: { type: 'boolean' },
+					allowComponents: { type: 'array', items: { type: 'string' } },
+					allowEvents: { type: 'array', items: { type: 'string' } },
+				},
+				additionalProperties: false,
+			},
+		],
+		messages: {
+			// Two ids, not one: the fallthrough case is a different claim about
+			// the code, and a consumer suppressing one should not lose the other.
+			unknownEvent: '{{message}} — {{hint}}',
+			fallthroughEvent: '{{message}}. {{hint}}',
+		},
+	},
+
+	create(context) {
+		const options = context.options[0] ?? {};
+		const manifest = getManifest(options.manifestPath, options);
+		const sourceCode = context.sourceCode ?? context.getSourceCode();
+		const services = sourceCode.parserServices;
+		if (!manifest || !services?.defineTemplateBodyVisitor) return {};
+
+		const allowComps = new Set(options.allowComponents ?? []);
+		const allowEvents = new Set(options.allowEvents ?? []);
+
+		return services.defineTemplateBodyVisitor({
+			VElement(node) {
+				const name = toPascalTag(node.rawName);
+				if (!BB_TAG.test(name) || allowComps.has(name)) return;
+				const surface = manifest.get(name);
+				if (!surface) return; // unknown component — no-unknown-attributes owns this
+
+				const checker = createComponentChecker(surface);
+
+				for (const attr of node.startTag.attributes) {
+					if (!attr.directive || attr.key.name.name !== 'on') continue;
+					const arg = attr.key.argument;
+					// `v-on="obj"` (no arg) and `@[expr]` (dynamic) are unbounded.
+					if (!arg || arg.type !== 'VIdentifier') continue;
+
+					// `vue-eslint-parser` splits `@click.stop` into an argument plus
+					// modifiers, so the raw name here is already bare — unlike the
+					// compiler AST `checkEvent`'s other caller walks, which keeps the
+					// dots. `checkEvent` strips them either way; nothing to do here.
+					const rawName = arg.rawName ?? arg.name;
+					if (allowEvents.has(rawName)) continue;
+
+					const finding = checker.checkEvent(rawName);
+					if (!finding) continue;
+
+					context.report({
+						node: attr.key,
+						messageId: finding.fallthrough
+							? 'fallthroughEvent'
+							: 'unknownEvent',
+						data: { message: finding.message, hint: finding.hint ?? '' },
+					});
+				}
+			},
+		});
+	},
+};
+
 /*
  * The three v3 controls whose `reverse` prop kept its NAME but inverted its
  * MEANING between v2 and v3. Hardcoded on purpose: this is a fact about one
@@ -1062,6 +1195,151 @@ const noReverseFalse = {
 	},
 };
 
+/*
+ * Every `--bb-*` the installed package declares, keyed by resolved stylesheet
+ * path. Same caching shape as `manifestCache`, including the miss: an absent
+ * stylesheet caches an EMPTY set, and the rule reads that as "say nothing".
+ *
+ * No warning on a miss, unlike the manifest. `dist/styles.css` is a BUILD
+ * artifact, absent in a source checkout that has not run `vite build`, so a
+ * console warning here would fire constantly in this repo's own dev loop.
+ * A missing manifest means every rule is silently inactive, which is worth
+ * shouting about; a missing stylesheet disarms exactly one advisory rule.
+ */
+const tokenCache = new Map();
+function getKnownTokens(stylesPath) {
+	const resolved = stylesPath ?? join(HERE, '..', '..', 'dist', 'styles.css');
+	if (!tokenCache.has(resolved))
+		tokenCache.set(resolved, loadKnownTokens(resolved));
+	return tokenCache.get(resolved);
+}
+
+/**
+ * A bare `var(--bb-…)` in a `<style>` block naming a token the installed
+ * package does not declare.
+ *
+ * WHY THIS ONE MOVED TO ESLINT AND ITS TWO SIBLINGS DID NOT. `bitboss-ui
+ * check` has carried three advisory hints — this, plus the hand-rolled avatar
+ * and spinner detectors. A consumer's migration report (2026-09-09) made the
+ * structural point that `check` is what nobody runs, while ESLint runs in the
+ * editor and in pre-commit, so a check-only warning does not really exist.
+ *
+ * Only this one crossed over, on the owner's ruling, because only this one is
+ * a FACT rather than a guess. An undeclared custom property is
+ * invalid-at-computed-value-time: CSS discards the WHOLE declaration, so the
+ * rule silently does nothing — there is no reading of `var(--bb-canvas)`, with
+ * no such token and no fallback, that is correct code. The avatar and spinner
+ * detectors are guesses by design (a round `<img>` is sometimes a logo), and a
+ * rule that fires on correct code spends the trust that makes every other rule
+ * here worth reading. They stay in `check`, where they cannot fail a build.
+ *
+ * A FALLBACK DISARMS IT, exactly as in the CLI hint: `var(--bb-canvas, #f8fafc)`
+ * is a deliberate override hook with defined behaviour and nothing silently
+ * disappears. Shared with the CLI through `findTokenUses`, so the two can never
+ * disagree about what counts as a use.
+ *
+ * Reported at `warn`, joining `no-unknown-event`: the token may be one the
+ * consumer means to define in their own stylesheet, which this rule cannot see.
+ * @type {import('eslint').Rule.RuleModule}
+ */
+const noUnknownToken = {
+	meta: {
+		type: 'problem',
+		docs: {
+			description:
+				'Flag a bare `var(--bb-…)` naming a token bitboss-ui does not declare. CSS treats an undefined custom property as invalid-at-computed-value-time and throws away the entire declaration, so the rule silently does nothing rather than falling back — an invented token name is invisible at runtime and in review. Supplying a fallback (`var(--bb-x, #fff)`) is defined behaviour and never reported. Reads the token list from the installed `dist/styles.css`, so it can never claim a token is invented when your version declares it; with no stylesheet to read, the rule stays silent.',
+			recommended: true,
+		},
+		schema: [
+			{
+				type: 'object',
+				properties: {
+					stylesPath: { type: 'string' },
+					allowTokens: { type: 'array', items: { type: 'string' } },
+				},
+				additionalProperties: false,
+			},
+		],
+		messages: {
+			unknownToken:
+				'`{{name}}` is not a bitboss-ui token. An undefined custom property invalidates the whole declaration, so this rule silently does nothing at runtime. Check the token list in the design-tokens guide, or supply a fallback (`var({{name}}, …)`) if you define it yourself.',
+		},
+	},
+
+	create(context) {
+		const options = context.options[0] ?? {};
+		const known = getKnownTokens(options.stylesPath);
+		// No stylesheet to compare against — no data, no accusation.
+		if (known.size === 0) return {};
+
+		const sourceCode = context.sourceCode ?? context.getSourceCode();
+		const services = sourceCode.parserServices;
+		if (!services?.getDocumentFragment) return {};
+		const allowTokens = new Set(options.allowTokens ?? []);
+
+		/**
+		 * Report every unknown token in one chunk of CSS text. `offset` is that
+		 * chunk's own start in the FILE, so a match position inside it maps
+		 * straight onto a source location.
+		 */
+		const reportIn = (css, offset) => {
+			for (const use of findTokenUses(css)) {
+				if (known.has(use.name) || allowTokens.has(use.name)) continue;
+				const start = offset + use.index;
+				context.report({
+					loc: {
+						start: sourceCode.getLocFromIndex(start),
+						// `var(` + the name, which is the part worth underlining.
+						end: sourceCode.getLocFromIndex(start + use.name.length + 4),
+					},
+					messageId: 'unknownToken',
+					data: { name: use.name },
+				});
+			}
+		};
+
+		/*
+		 * The two places real CSS lives in an SFC: a `<style>` block, and a
+		 * static `style="…"` attribute. Both are scanned, because `check` reads
+		 * the whole file and a rule that saw only one of them would put the two
+		 * tools back into the disagreement this rule exists to end.
+		 *
+		 * A BOUND `:style` is deliberately NOT scanned: it is a JS expression,
+		 * the token name may be computed, and guessing at string literals inside
+		 * it is how a rule starts firing on correct code.
+		 */
+		const walk = (node) => {
+			if (!node || node.type !== 'VElement') return;
+
+			if (node.rawName === 'style') {
+				for (const text of node.children ?? [])
+					if (text.type === 'VText' && typeof text.value === 'string')
+						reportIn(text.value, text.range[0]);
+			}
+
+			for (const attr of node.startTag?.attributes ?? []) {
+				if (attr.directive || attr.key?.name !== 'style') continue;
+				const value = attr.value;
+				if (!value || typeof value.value !== 'string') continue;
+				// `range` spans the quotes; the value starts one character in.
+				reportIn(value.value, value.range[0] + 1);
+			}
+
+			for (const child of node.children ?? []) walk(child);
+		};
+
+		return {
+			// The template-body visitors every sibling rule uses cannot see a
+			// `<style>` block; the document fragment is the whole SFC.
+			'Program:exit'() {
+				const fragment = services.getDocumentFragment();
+				if (!fragment) return;
+				for (const child of fragment.children ?? []) walk(child);
+			},
+		};
+	},
+};
+
 const plugin = {
 	meta: { name: 'bitboss-ui', version: '1.0.0' },
 	rules: {
@@ -1071,6 +1349,8 @@ const plugin = {
 		'no-unknown-slots': noUnknownSlots,
 		'no-active-class-on-root-link': noActiveClassOnRootLink,
 		'no-navigation-attr-fallthrough': noNavigationAttrFallthrough,
+		'no-unknown-event': noUnknownEvent,
+		'no-unknown-token': noUnknownToken,
 		'no-reverse-false': noReverseFalse,
 	},
 };
@@ -1130,6 +1410,20 @@ plugin.configs = {
 				'bitboss-ui/no-unknown-slots': 'error',
 				'bitboss-ui/no-active-class-on-root-link': 'error',
 				'bitboss-ui/no-navigation-attr-fallthrough': 'error',
+				// The only `warn` in this preset, deliberately. Every other rule
+				// here describes markup with exactly one correct fix. An
+				// undeclared event listener does not: it may be a considered
+				// native listener on a root the author knows, and erroring on a
+				// real JS event would make the plugin wrong about working code.
+				// Warning states the contract and leaves the choice; the CLI
+				// (`bitboss-ui check`) still reports it the same way it always
+				// has, so nothing silently relaxes in CI.
+				'bitboss-ui/no-unknown-event': 'warn',
+				// Also `warn`, for a different reason: the fact is certain (the
+				// declaration is discarded), but the token may be one the consumer
+				// intends to define in their own stylesheet, which this rule cannot
+				// see. `var(--bb-x, fallback)` is the documented way to say so.
+				'bitboss-ui/no-unknown-token': 'warn',
 				'bitboss-ui/no-reverse-false': 'error',
 			},
 		},
@@ -1144,6 +1438,8 @@ export {
 	noUnknownSlots,
 	noActiveClassOnRootLink,
 	noNavigationAttrFallthrough,
+	noUnknownEvent,
+	noUnknownToken,
 	noReverseFalse,
 	resolveOptionalTsParser,
 };

package/scripts/lib/hand-roll-hints.mjs

@@ -26,6 +26,8 @@
  * Hinting about someone else's composable is not this file's job.
  */
 
+import { existsSync, readFileSync } from 'node:fs';
+
 /**
  * @typedef {{ line: number, component: string, message: string }} Hint
  */
@@ -77,6 +79,53 @@ function detectSpinner(source) {
 	};
 }
 
+/**
+ * Every bare `var(--bb-…)` USE in the source, with the offset it starts at.
+ *
+ * Split out from `detectUnknownTokens` so the ESLint rule
+ * (`no-unknown-token`) reports each occurrence at its own location instead of
+ * lumping them onto one line the way the CLI hint does. One regex, one
+ * fallback rule, two consumers — the two can no longer disagree about what
+ * counts as a use.
+ *
+ * @param {string} source
+ * @returns {{ name: string, index: number }[]}
+ */
+export function findTokenUses(source) {
+	return (
+		[...source.matchAll(/var\(\s*(--bb-[a-z0-9-]+)\s*([,)])/gi)]
+			// `,` opens a fallback; `)` closes the function with none.
+			.filter((m) => m[2] === ')')
+			.map((m) => ({ name: m[1].toLowerCase(), index: m.index }))
+	);
+}
+
+/**
+ * Every `--bb-*` the INSTALLED package declares, read from the stylesheet the
+ * consumer actually ships rather than hardcoded, so this can never claim a
+ * token is invented when their version does declare it.
+ *
+ * A missing stylesheet yields an EMPTY set, and every caller treats that as
+ * "say nothing". No data, no accusation.
+ *
+ * @param {string} stylesPath path to the installed `dist/styles.css`
+ * @returns {Set<string>}
+ */
+export function loadKnownTokens(stylesPath) {
+	if (!stylesPath || !existsSync(stylesPath)) return new Set();
+	try {
+		return new Set(
+			[
+				...readFileSync(stylesPath, 'utf-8').matchAll(
+					/(--bb-[a-z0-9-]+)\s*:/gi
+				),
+			].map((m) => m[1].toLowerCase())
+		);
+	} catch {
+		return new Set();
+	}
+}
+
 /**
  * A `var(--bb-…)` name the library does not declare. CSS treats an undefined
  * custom property as invalid-at-computed-value-time and throws away the WHOLE
@@ -99,12 +148,7 @@ function detectSpinner(source) {
  */
 function detectUnknownTokens(source, knownTokens) {
 	if (!knownTokens || knownTokens.size === 0) return null;
-	const used = new Set(
-		[...source.matchAll(/var\(\s*(--bb-[a-z0-9-]+)\s*([,)])/gi)]
-			// `,` opens a fallback; `)` closes the function with none.
-			.filter((m) => m[2] === ')')
-			.map((m) => m[1].toLowerCase())
-	);
+	const used = new Set(findTokenUses(source).map((u) => u.name));
 	const unknown = [...used].filter((name) => !knownTokens.has(name));
 	if (unknown.length === 0) return null;
 	return {

package/scripts/lib/html-attributes.mjs

@@ -280,3 +280,45 @@ export const NATIVE_DOM_EVENTS = new Set([
 	'transitionrun',
 	'transitionstart',
 ]);
+
+/**
+ * Real DOM events that fire on only a HANDFUL of element types, so they are
+ * deliberately NOT in `NATIVE_DOM_EVENTS` above.
+ *
+ * These are the reason the event gate can't simply say "unknown event". A
+ * listener named here is not a typo and it is not dead code: Vue binds it to
+ * whatever the component's root element happens to be, and if that root is the
+ * one element that dispatches it, the handler really does run.
+ *
+ * `<BbDialog @close>` is the case that named this set. BbDialog's root IS a
+ * native `<dialog>`, so `@close` binds as a genuine DOM listener and fires on
+ * `dialog.close()` — a task queued by the browser, unordered against the
+ * component's own `hidden` emit, and dispatched for native closes that never
+ * touched `v-model` (a `<form method="dialog">` submit) so the model goes
+ * stale. A consuming agent's migration report read it as "a dead `@close`
+ * handler shipped"; it was live, mistimed, and outside the component contract.
+ *
+ * Blanket-allowing them (moving them up into `NATIVE_DOM_EVENTS`) would hide
+ * that. Treating them as unknown would call working markup a typo. So they get
+ * their own diagnostic — see `checkEvent`'s `fallthrough` finding — and, in
+ * ESLint, their own severity.
+ */
+export const ELEMENT_DOM_EVENTS = new Set([
+	// <dialog>
+	'cancel',
+	'close',
+	// <details>, <dialog>, popover
+	'beforetoggle',
+	// <form>
+	'formdata',
+	// media elements
+	'canplay',
+	'ended',
+	'loadeddata',
+	'loadedmetadata',
+	'pause',
+	'play',
+	'playing',
+	'timeupdate',
+	'volumechange',
+]);