bitboss-ui 3.0.0-beta.0 → 3.0.0-beta.2

package/llms.txt

@@ -2,12 +2,12 @@
 
 > Vue 3 component library by BitBoss: forms, selects, layout, overlays, and more.
 
-Note: the `dist/` paths below resolve inside the installed npm package (`node_modules/bitboss-ui/`) and, when this file is fetched over HTTP, against https://cdn.jsdelivr.net/npm/bitboss-ui@alpha. `dist/` is generated and not committed, so when browsing the repository the sources are `ai/` (guides, recipes, composables) and `src/components/<Name>/<Name>.guide.md` (per-component guides).
+Note: the `dist/` paths below resolve inside the installed npm package (`node_modules/bitboss-ui/`) and, when this file is fetched over HTTP, against https://cdn.jsdelivr.net/npm/bitboss-ui@beta. `dist/` is generated and not committed, so when browsing the repository the sources are `ai/` (guides, recipes, composables) and `src/components/<Name>/<Name>.guide.md` (per-component guides).
 
 ## AI Knowledge Base
 
-- [Core knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-medium.txt): **Fetch this if you can only fetch one file** — hard rules, setup, component picker, design language, and the full component catalogue in ~70 KB.
-- [Complete knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@alpha/dist/llms-full.txt): Everything concatenated (~2 MB). Bulk ingestion only — too large to prompt with.
+- [Core knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@beta/dist/llms-medium.txt): **Fetch this if you can only fetch one file** — hard rules, setup, component picker, design language, and the full component catalogue in ~70 KB.
+- [Complete knowledge base](https://cdn.jsdelivr.net/npm/bitboss-ui@beta/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.
@@ -27,40 +27,40 @@ Note: the `dist/` paths below resolve inside the installed npm package (`node_mo
 - [Inertia Helpers](dist/ai/guides/inertia-helpers.md): App-side toolkit for Laravel + Inertia apps — typed page props, lazy props, URL-driven filters, paginated/selection page contexts, promise forms, and navigation guards that pair with bitboss-ui pages.
 - [Migration v2 → v3](dist/ai/guides/migration/v2-to-v3.md): Complete upgrade guide from bitboss-ui 2.x to 3.0 — plugin-based setup, token overhaul, variant registries, global behavioral changes, and the silent-failure audit playbook.
 - [Migration v2→v3: BbAlert](dist/ai/guides/migration/components/bb-alert.md): showClose inverted to hideClose, theme replaced by typed variant.
-- [Migration v2→v3: BbAvatar](dist/ai/guides/migration/components/bb-avatar.md): The color prop is removed — the initials fallback is always primary.
+- [Migration v2→v3: BbAvatar](dist/ai/guides/migration/components/bb-avatar.md): The color prop is removed — retheme the fallback through the --bg-color / --text-color locals.
 - [Migration v2→v3: BbBadge (and where your v2 badges went)](dist/ai/guides/migration/components/bb-badge.md): The v2 BbBadge (floating count/dot) is now BbIndicator; the v3 BbBadge is a new inline pill that also replaces BbChip.
 - [Migration v2→v3: BbBreadcrumbs](dist/ai/guides/migration/components/bb-breadcrumbs.md): Item keys must be strings, the text divider prop is gone, per-item slot names are normalized.
 - [Migration v2→v3: BbButton](dist/ai/guides/migration/components/bb-button.md): Async click handlers now auto-track loading (behavior flip), built-in tooltip props removed, variant locked to the registry.
 - [Migration v2→v3: BbCheckbox / BbRadio / BbSwitch](dist/ai/guides/migration/components/bb-checkbox.md): reverse polarity inverted (explicit values flip, default layout unchanged), checked narrowed to boolean, color removed, BbRadio's name no longer required.
-- [Migration v2→v3: BbCheckboxGroup / BbRadioGroup / BbSwitchGroup](dist/ai/guides/migration/components/bb-checkbox-group.md): labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed, BbRadioGroup's name no longer required.
+- [Migration v2→v3: BbCheckboxGroup / BbRadioGroup / BbSwitchGroup](dist/ai/guides/migration/components/bb-checkbox-group.md): labelPosition renamed legendPosition, per-item disabled is now inert (use selectable), color and the option affix slots removed, BbRadioGroup's name no longer required, and the shared bb-cr-container CSS block split into one per group.
 - [Migration v2→v3: BbChip (removed)](dist/ai/guides/migration/components/bb-chip.md): BbChip is gone — BbBadge with clearable is the replacement; non-clearable chips were badges all along.
 - [Migration v2→v3: BbCollapsible](dist/ai/guides/migration/components/bb-collapsible.md): The tag prop is removed; the root is always a div.
 - [Migration v2→v3: BbColorInput](dist/ai/guides/migration/components/bb-color-input.md): picker renamed to eyeDropper.
 - [Migration v2→v3: BbColorPalette](dist/ai/guides/migration/components/bb-color-palette.md): flip inverted to disableFlip, showArrow removed, picker renamed eyeDropper, update:open dropped, model updates never emit null.
 - [Migration v2→v3: BbDatePickerInput](dist/ai/guides/migration/components/bb-date-picker-input.md): allowWriting inverted to disableWriting and hidePopover renamed to disableCalendar, both with a changed token set; the width prop is removed; adaptive mobile sheet by default; non-floating output carries the local offset instead of UTC `Z` (new `utc` prop restores v2 output).
-- [Migration v2→v3: BbDialog](dist/ai/guides/migration/components/bb-dialog.md): showClose inverted to hideClose, several presentation props removed, default widths changed, adaptive bottom sheet on mobile by default.
+- [Migration v2→v3: BbDialog](dist/ai/guides/migration/components/bb-dialog.md): showClose inverted to hideClose, several presentation props and the #close/#description slots removed, default widths changed, adaptive bottom sheet on mobile by default, --bb-dialog-* tokens replaced by --bb-panel-p plus locals.
 - [Migration v2→v3: BbDropdown](dist/ai/guides/migration/components/bb-dropdown.md): Items now expect text as the label and can carry variants/submenus; arrowPadding removed; adaptive mobile sheet on by default.
 - [Migration v2→v3: BbDropdownButton](dist/ai/guides/migration/components/bb-dropdown-button.md): autoLoading renamed to disableAutoLoading, disabledWhileLoading and theme removed.
 - [Migration v2→v3: BbDropzone](dist/ai/guides/migration/components/bb-dropzone.md): modelValue is typed, accept no longer throws and takes bare tokens, and the hidden native-submit input only renders when name is set.
 - [Migration v2→v3: BbIcon](dist/ai/guides/migration/components/bb-icon.md): The required prop is renamed type→icon, color is removed, and the xxl size key becomes 2xl.
 - [Migration v2→v3: BbIntersection](dist/ai/guides/migration/components/bb-intersection.md): Removed with no replacement — it wrapped IntersectionObserver and carried no styling; use @vueuse/core's useIntersectionObserver.
-- [Migration v2→v3: BbOffCanvas](dist/ai/guides/migration/components/bb-offcanvas.md): direction→side; showClose→hideClose; size defaults change; adaptive drawer configs unify on offCanvasProps.
+- [Migration v2→v3: BbOffCanvas](dist/ai/guides/migration/components/bb-offcanvas.md): direction→side; showClose→hideClose; description and the #close/#description slots removed; size defaults change; adaptive drawer configs unify on offCanvasProps.
 - [Migration v2→v3: BbPagination](dist/ai/guides/migration/components/bb-pagination.md): querykey renamed to queryKey; the loading prop is removed.
 - [Migration v2→v3: BbPopover](dist/ai/guides/migration/components/bb-popover.md): Built-in close button, restoreFocus, theme, and the arrow are gone; close affordances move into your content.
-- [Migration v2→v3: BbRating](dist/ai/guides/migration/components/bb-rating.md): color removed; name no longer required.
+- [Migration v2→v3: BbRating](dist/ai/guides/migration/components/bb-rating.md): color removed; name no longer required; the star state modifier renamed --highlighted to --filled/--empty; --bb-rating-size demoted to a local --size; input-position finally works.
 - [Migration v2→v3: BbSelect](dist/ai/guides/migration/components/bb-select.md): allowWriting inverted to disableWriting, filterBy narrowed to string[], prefill value renamed, chevron/options slots removed, and two behavior changes (second click, mount-time coherence).
 - [Migration v2→v3: BbSelectPopover](dist/ai/guides/migration/components/bb-select-popover.md): flip and allowWriting inverted, arrow props removed, filterBy narrowed, options slots replaced by header/footer; shares BbSelect's behavior changes.
 - [Migration v2→v3: BbSlider](dist/ai/guides/migration/components/bb-slider.md): thumbTranslate inverted to disableThumbTranslate; string model values and color removed.
 - [Migration v2→v3: BbSmoothHeight](dist/ai/guides/migration/components/bb-smooth-height.md): The `tag` prop is narrowed to `div | span`, and the inner measuring element now mirrors it instead of always being a `<div>`.
 - [Migration v2→v3: BbSpinner](dist/ai/guides/migration/components/bb-spinner.md): The color prop is removed; spinners follow currentColor.
-- [Migration v2→v3: BbTable](dist/ai/guides/migration/components/bb-table.md): allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width table cell instead of replacing the row.
-- [Migration v2→v3: BbTabs (was BbTab)](dist/ai/guides/migration/components/bb-tabs.md): Component renamed; querykey→queryKey; animations default on; label slots renamed and all dynamic names/URL slugs normalized.
+- [Migration v2→v3: BbTable](dist/ai/guides/migration/components/bb-table.md): allowSelectAll inverted to disableSelectAll; loading no longer blanks populated tables and now inerts rows; #loading is first-load-only; #no-data fills a full-width table cell instead of replacing the row; columns gained sortable + rowClass, which collide with same-named consumer fields.
+- [Migration v2→v3: BbTabs (was BbTab)](dist/ai/guides/migration/components/bb-tabs.md): Component renamed; querykey→queryKey; animations default on; label slots renamed and all dynamic names/URL slugs normalized; the entire .bb-tab BEM tree renamed to .bb-tabs / .bb-tabs-list / .bb-tabs-panes.
 - [Migration v2→v3: BbTag](dist/ai/guides/migration/components/bb-tag.md): modelValue is strictly string[] now, multiple is removed, and duplicates are rejected case-insensitively by default.
-- [Migration v2→v3: BbTextInput](dist/ai/guides/migration/components/bb-text-input.md): The type prop narrows to the text-like input types — number/date values must move to their dedicated components.
+- [Migration v2→v3: BbTextInput](dist/ai/guides/migration/components/bb-text-input.md): The type prop narrows to the text-like input types — number/date values must move to their dedicated components; a bare `floating` attribute was never a prop, the spelling is label-mode="floating".
 - [Migration v2→v3: BbToast and toast()](dist/ai/guides/migration/components/bb-toast.md): Host placement becomes position with a corner-based value set; toast() options rewritten (variant, duration, actions, portal).
 - [Migration v2→v3: BbTooltip](dist/ai/guides/migration/components/bb-tooltip.md): timeout renamed to delay; theme replaced by typed variant; hideArrow is now a declared prop; block removed; modelValue is new.
 - [Migration v2→v3: BbTree](dist/ai/guides/migration/components/bb-tree.md): Item model rewritten — payload moves under meta, open becomes expanded, identifier becomes itemValue, expansion is a v-model.
-- [Migration v2→v3: confirm() / useConfirm](dist/ai/guides/migration/components/use-confirm.md): yesText/onYes/noText/onNo collapse into yes/no configs, actions becomes an array-or-false, labels are localized, footer buttons default md.
+- [Migration v2→v3: confirm() / useConfirm](dist/ai/guides/migration/components/use-confirm.md): yesText/onYes/noText/onNo collapse into yes/no configs, actions becomes an array-or-false, theme→variant, timeout→duration, autoClose flips to default-true, labels are localized, footer buttons default md.
 - [Migration v2→v3: useBroadcastChannelInstance](dist/ai/guides/migration/components/use-broadcast-channel-instance.md): Removed — cross-tab messaging is not a UI concern; use useBroadcastChannel from @vueuse/core.
 - [Page Shell](dist/ai/guides/page-shell.md): App-side page layout — topbar, content, and a right details sidebar driven by a stack-based context (push a record to peek it, pop to go back). The implementation ships in the per-platform Layout Scaffold recipe; this guide covers when and how to use it.
 - [Validated Forms (vee-validate)](dist/ai/guides/validated-forms.md): The `bitboss-ui/validated` entrypoint — form controls pre-wired to vee-validate. Global rules give an effort-free `rules="required|email"` string syntax; BbForm hosts the form; requiredAsterisk marks required fields.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "bitboss-ui",
-	"version": "3.0.0-beta.0",
+	"version": "3.0.0-beta.2",
 	"description": "Vue 3 component library by BitBoss: forms, selects, layout, overlays, and more.",
 	"license": "MIT",
 	"type": "module",
@@ -39,6 +39,7 @@
 		"check:doc-drift": "node scripts/check-doc-drift.mjs",
 		"check:default-docs": "node --experimental-strip-types scripts/check-default-docs.ts",
 		"check:doc-ts": "node scripts/check-doc-ts.mjs",
+		"check:dist-tag": "node scripts/check-dist-tag.mjs",
 		"check:doc-links": "node scripts/check-doc-links.mjs",
 		"check:docs": "node --experimental-strip-types scripts/generate-component-docs.ts --strict",
 		"check:fixture-types": "node scripts/check-fixture-types.mjs",

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

@@ -44,6 +44,11 @@ const PROP_DIRECTIVE = 7;
 export const toCamel = (attr) =>
 	attr.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
 
+/** `hideLabel` → `hide-label`, `fullscreen` → `fullscreen`. The spelling a
+ * template author actually has to type. */
+export const toKebab = (name) =>
+	name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+
 /**
  * Components with `slotKey()`-normalized, per-item/column/tab/day DYNAMIC
  * named slots — the set of valid names is runtime data (row column keys,
@@ -124,6 +129,14 @@ function editDistance(a, b) {
  * Nearest candidate name to `key` within a length-scaled edit-distance budget,
  * or null when nothing is close. Powers "did you mean" hints on unknown props
  * (`hideLabl` → `hideLabel`) without matching unrelated names.
+ *
+ * The self-match guard compares the RAW names, not the distance. It used to be
+ * `dist > 0`, which also silenced the one near-miss the kebab/camel boundary
+ * actually produces: a multi-word kebab spelling of a single-word prop.
+ * `full-screen` camel-cases to `fullScreen`, whose lowercased distance to the
+ * real `fullscreen` is 0 — so the hint was suppressed exactly where it was
+ * needed most (30 inert `full-screen` sites in one migrated app). Same trap on
+ * `read-only`/`readonly`, `auto-focus`/`autofocus`, `max-length`/`maxlength`.
  * @param {string} key camelCase attribute the author wrote
  * @param {Iterable<string>} candidates camelCase valid names
  */
@@ -131,10 +144,11 @@ export function nearestName(key, candidates) {
 	let best = null;
 	let bestDist = Infinity;
 	for (const cand of candidates) {
+		if (cand === key) continue;
 		// Short names collide by chance (`to`/`id`); demand a tighter match.
 		const budget = Math.min(key.length, cand.length) < 6 ? 1 : 2;
 		const dist = editDistance(key.toLowerCase(), cand.toLowerCase());
-		if (dist > 0 && dist <= budget && dist < bestDist) {
+		if (dist <= budget && dist < bestDist) {
 			best = cand;
 			bestDist = dist;
 		}
@@ -272,7 +286,7 @@ 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, kind: 'unknown-prop' | 'unknown-model' | 'removed-prop' | 'unknown-slot', message: string, hint?: string }} Finding
+ * @typedef {{ component: string, attr: string, line?: number, kind: 'unknown-prop' | 'unknown-model' | 'removed-prop' | 'unknown-slot', message: string, hint?: string }} Finding
  */
 
 /**
@@ -352,18 +366,31 @@ function parseSnippet(code) {
 /**
  * @param {string} code
  * @param {ManifestMap} manifest
+ * @param {{ allowComponents?: Iterable<string> }} [options]
+ *   `allowComponents` — tag names the caller owns. The `Bb` prefix is a naming
+ *   convention, not proof of provenance: an app that ships its own
+ *   `<BbRichEditor>` is not writing invalid library markup, it just picked a
+ *   colliding name. Listed tags are skipped entirely (no unknown-component
+ *   finding, no prop findings), their children still walked. Mirrors the
+ *   ESLint rules' `allowComponents` option so both gates configure alike.
  * @returns {{ findings: Finding[] }}
  */
-export function validateVueSnippet(code, manifest) {
+export function validateVueSnippet(code, manifest, options = {}) {
 	/** @type {Finding[]} */
 	const findings = [];
 	const ast = parseSnippet(code);
 	if (!ast) return { findings };
 
+	const allowComponents = new Set(options.allowComponents ?? []);
+
 	/** @param {{ type: number, tag?: string, props?: unknown[], children?: unknown[] }} node */
 	const walk = (node) => {
 		if (!node || typeof node !== 'object') return;
-		if (node.type === NODE_ELEMENT && BB_TAG_NAME.test(node.tag)) {
+		if (
+			node.type === NODE_ELEMENT &&
+			BB_TAG_NAME.test(node.tag) &&
+			!allowComponents.has(node.tag)
+		) {
 			validateElement(node, manifest, findings);
 		}
 		for (const child of node.children ?? []) walk(child);
@@ -541,6 +568,35 @@ export function createComponentChecker(surface, options = {}) {
 					};
 				}
 
+				/*
+				 * The prop IS on this component — the author just spelled it
+				 * with the wrong word boundaries. Ranked above the
+				 * owners-elsewhere and fuzzy branches because a same-component
+				 * hit is the answer; being told `fullscreen` "belongs to some
+				 * other component" would be actively wrong.
+				 *
+				 * The only shape that reaches here is a name whose camel form
+				 * differs from a real prop by case alone, which is what a kebab
+				 * spelling of a one-word prop (`full-screen` → `fullScreen` vs
+				 * `fullscreen`) produces. A genuinely multi-word prop written in
+				 * kebab (`hide-label`) camel-cases to the real name and never
+				 * gets here at all, so this can never nag correct markup.
+				 */
+				const lowerKey = key.toLowerCase();
+				const caseOnly = [...propKeys].find(
+					(cand) => cand.toLowerCase() === lowerKey
+				);
+				if (caseOnly) {
+					const correct = toKebab(caseOnly);
+					return {
+						attr: attrName,
+						kind: 'unknown-prop',
+						message: `prop \`${attrName}\` is not in ${surface.name}'s API — did you mean \`${correct}\`?`,
+						hint: `Attribute names are camel-cased before matching (\`${attrName}\` → \`${key}\`), so only the exact spelling \`${correct}\` binds — anything else falls through to the DOM and does nothing.`,
+						to: correct,
+					};
+				}
+
 				// The prop is real — on OTHER components. Exact hits elsewhere
 				// beat a fuzzy neighbour here: someone who wrote `hide-close`
 				// on a BbTooltip did not typo, they generalised a prop that
@@ -1038,6 +1094,18 @@ function compilerItemsMayBeAsync(node) {
  */
 function validateElement(node, manifest, findings) {
 	const name = node.tag;
+	/*
+	 * CHK-LINE: every finding carries the 1-based source line, so an agent (or
+	 * a human with an editor) can jump straight to it instead of re-parsing the
+	 * file to find which of three identical `full-screen` findings is which.
+	 * The numbers are exact, not approximate: `parseSnippet` wraps the code as
+	 * `<template>${code}</template>` with NO added newline, so AST lines map
+	 * 1:1 onto the file. (Columns do NOT — line 1 is shifted by the 10-char
+	 * wrapper — which is why only the line is emitted.)
+	 */
+	const tagLine = node.loc?.start?.line;
+	/** The line an attribute was written on, falling back to the tag's. */
+	const propLine = (prop) => prop?.loc?.start?.line ?? tagLine;
 	const surface = manifest.get(name);
 	if (!surface) {
 		// Unknown Bb* tag — surface as a finding so recipes can't invent
@@ -1045,9 +1113,12 @@ function validateElement(node, manifest, findings) {
 		findings.push({
 			component: name,
 			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.',
+			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}\`.`,
 		});
 		return;
 	}
@@ -1062,7 +1133,8 @@ function validateElement(node, manifest, findings) {
 				// Dynamic argument (`v-model:[name]`) can't be checked statically.
 				if (prop.arg && !prop.arg.isStatic) continue;
 				const finding = checker.checkModel(prop.arg?.content ?? 'modelValue');
-				if (finding) findings.push({ component: name, ...finding });
+				if (finding)
+					findings.push({ component: name, ...finding, line: propLine(prop) });
 				continue;
 			}
 			if (prop.name !== 'bind') continue; // @events, v-if/for/show/slot, …
@@ -1070,14 +1142,16 @@ function validateElement(node, manifest, findings) {
 			const finding =
 				checker.checkAttr(prop.arg.content) ??
 				checkNavAttrFallthrough(manifest, name, prop.arg.content);
-			if (finding) findings.push({ component: name, ...finding });
+			if (finding)
+				findings.push({ component: name, ...finding, line: propLine(prop) });
 		} else if (prop.type === PROP_ATTRIBUTE) {
 			if (!VALID_ATTR_NAME.test(prop.name)) continue; // recovered garbage
 			const attrName = prop.name.split('.')[0];
 			const finding =
 				checker.checkAttr(attrName) ??
 				checkNavAttrFallthrough(manifest, name, attrName);
-			if (finding) findings.push({ component: name, ...finding });
+			if (finding)
+				findings.push({ component: name, ...finding, line: propLine(prop) });
 		}
 	}
 
@@ -1099,6 +1173,7 @@ function validateElement(node, manifest, findings) {
 			findings.push({
 				component: name,
 				attr: '(children)',
+				line: tagLine,
 				kind: 'no-default-slot',
 				message:
 					`${name} has no default slot — children passed to it render nothing, ` +
@@ -1118,7 +1193,8 @@ function validateElement(node, manifest, findings) {
 			// (unbounded) can't be — or don't need to be — checked.
 			if (!arg || !arg.isStatic) continue;
 			const finding = checker.checkSlot(arg.content);
-			if (finding) findings.push({ component: name, ...finding });
+			if (finding)
+				findings.push({ component: name, ...finding, line: propLine(prop) });
 		}
 	}
 
@@ -1130,7 +1206,7 @@ function validateElement(node, manifest, findings) {
 		hasSlot: (slotName) => compilerHasSlot(node, slotName),
 		itemsMayBeAsync: compilerItemsMayBeAsync(node),
 	})) {
-		findings.push({ component: name, attr: '', ...finding });
+		findings.push({ component: name, attr: '', ...finding, line: tagLine });
 	}
 
 	// SWP-015: these two were ESLint-only, so `bitboss-ui check` and the MCP
@@ -1143,22 +1219,27 @@ function validateElement(node, manifest, findings) {
 		staticProp: (attr) => compilerStaticProp(node, attr),
 	};
 	for (const finding of checkTableSlotProps(name, slotCtx)) {
-		findings.push({ component: name, ...finding });
+		findings.push({ component: name, ...finding, line: tagLine });
 	}
 	for (const finding of checkRootLinkActiveClass(name, slotCtx)) {
-		findings.push({ component: name, ...finding });
+		findings.push({ component: name, ...finding, line: tagLine });
 	}
 }
 
 /**
  * Extract fenced code blocks from markdown.
+ *
+ * `bodyLine` is the 1-based line of the fence's FIRST body line in the whole
+ * document — the offset that turns a fence-relative finding line into a line a
+ * reader can jump to. Indent stripping never changes line counts, so it is
+ * exact.
  * @param {string} md
  * @param {{ lang?: string }} [opts]
- * @returns {Array<{ lang: string, code: string, info: string, index: number }>}
+ * @returns {Array<{ lang: string, code: string, info: string, index: number, bodyLine: number }>}
  */
 export function extractFences(md, opts = {}) {
 	const want = opts.lang?.toLowerCase();
-	/** @type {Array<{ lang: string, code: string, info: string, index: number }>} */
+	/** @type {Array<{ lang: string, code: string, info: string, index: number, bodyLine: number }>} */
 	const out = [];
 	FENCE_REGEX.lastIndex = 0;
 	let match;
@@ -1176,7 +1257,9 @@ export function extractFences(md, opts = {}) {
 			indent.length > 0
 				? rawCode.replace(new RegExp(`^ {1,${indent.length}}`, 'gm'), '')
 				: rawCode;
-		out.push({ lang, code, info, index });
+		// The opening fence is on `openLine`; the body starts on the next line.
+		const openLine = md.slice(0, match.index).split('\n').length;
+		out.push({ lang, code, info, index, bodyLine: openLine + 1 });
 		index += 1;
 	}
 	return out;
@@ -1198,19 +1281,24 @@ export function blankFences(md) {
 /**
  * @param {string} md
  * @param {ManifestMap} manifest
+ * @param {{ allowComponents?: Iterable<string> }} [options] see `validateVueSnippet`
  * @returns {{ findings: Array<Finding & { fenceIndex: number, fenceInfo: string }> }}
  */
-export function validateMarkdown(md, manifest) {
+export function validateMarkdown(md, manifest, options = {}) {
 	/** @type {Array<Finding & { fenceIndex: number, fenceInfo: string }>} */
 	const findings = [];
 	for (const fence of extractFences(md, { lang: 'vue' })) {
 		const { findings: fenceFindings } = validateVueSnippet(
 			fence.code,
-			manifest
+			manifest,
+			options
 		);
 		for (const f of fenceFindings) {
 			findings.push({
 				...f,
+				// Fence-relative → document-absolute, so the printed line is the
+				// line of the .md file itself.
+				line: f.line == null ? undefined : fence.bodyLine + f.line - 1,
 				fenceIndex: fence.index,
 				fenceInfo: fence.info,
 			});