cursedbelt 3.0.2 → 4.0.0

package/scripts/fixtureAppCss.ts

@@ -0,0 +1,344 @@
+#!/usr/bin/env bun
+/**
+ * `bun scripts/fixtureAppCss.ts [--prune]` — measure what a consuming app emits,
+ * and refuse to let it grow.
+ *
+ * ## What this exists for
+ *
+ * Three apps shipped the union of this design system before anyone counted it,
+ * then four, then five; the fifth arrived with a 173-line `@source` list that
+ * could not have worked and a 494 kB entry chunk. Every one of those numbers was
+ * measured from the CONSUMER side, in a repo that cannot change the thing causing
+ * it, and none of them was measured twice — so nothing here could tell whether the
+ * cost was going up or down.
+ *
+ * 🔴 The check has to live in the package, and it may not reach into `apps/*`:
+ * this generation's third rule is that a repo's gate proves that repo. So the
+ * package keeps its own consumer — `demo/fixtures/lean-app`, a small releases
+ * console built out of cursedbelt's public subpaths — compiles its stylesheet the
+ * way an app's bundler will, and records the byte count here.
+ *
+ * ## The two routes, and why both are compiled every run
+ *
+ *   UNION — `styles-static.css` + `styles-utilities.css`, which is what every app
+ *           ships today and what `@import "cursedbelt/styles.css"` is equivalent
+ *           to (measured at 54 bytes' difference; see generateUtilityStyles.ts).
+ *   AREAS — `styles-static.css` + the areas `demo/fixtures/lean-app/app.css`
+ *           declares, and no `@source` into this package at all.
+ *
+ * Both, not just the second, because a ratchet on one number cannot tell a real
+ * saving from a design system that shrank. The RATIO is the claim; the absolute
+ * area number is the ratchet.
+ *
+ * ## The ratchet
+ *
+ * `fixtureAppCss.baseline` records both counts. `--prune` lowers them and REFUSES
+ * to raise, the same bargain `publicSurface.baseline` makes: a real increase — a
+ * new primitive in `core`, a component the fixture started rendering — is a hand
+ * edit in a commit that says why, which is a reviewable moment rather than a
+ * number that drifts. `src/fixtureAppCss.spec.ts` is what runs it in the gate, and
+ * it asserts the "not unstyled" half too: a stylesheet can always be made smaller
+ * by emitting less than the app needs.
+ */
+import { Scanner } from '@tailwindcss/oxide';
+import { REPO_ROOT } from './generateStaticStyles';
+import { compileStylesheet } from './generateUtilityStyles';
+import { AREAS, CORE, REACT_DIR, areaClosures, buildGraph, transitiveNeeds } from './styleAreas';
+
+/** The named fixture app. One, deliberately: a second one is a second thing to keep honest. */
+export const FIXTURE = 'demo/fixtures/lean-app';
+export const FIXTURE_DIR = `${REPO_ROOT}/${FIXTURE}`;
+export const FIXTURE_CSS = `${FIXTURE_DIR}/app.css`;
+export const BASELINE = `${REPO_ROOT}/fixtureAppCss.baseline`;
+
+/** `@import "cursedbelt/styles-areas/<area>.css";` — the fixture's one knob. */
+const AREA_IMPORT = /@import\s+"cursedbelt\/styles-areas\/([a-z0-9-]+)\.css"/g;
+
+/** Areas the fixture's stylesheet declares, in the order it imports them. */
+export const declaredAreas = async (): Promise<string[]> => {
+	const css = await Bun.file(FIXTURE_CSS).text();
+	return [...css.matchAll(AREA_IMPORT)].map((m) => m[1] as string);
+};
+
+/** `from 'cursedbelt/<subpath>'` in the fixture's TSX, with the names it took. */
+export interface FixtureImport {
+	/** The export subpath, `.`-prefixed as `package.json` spells it (`./react/charts`). */
+	readonly subpath: string;
+	/** Named bindings, for a barrel import. Empty for a deep subpath. */
+	readonly names: string[];
+	readonly file: string;
+}
+
+const IMPORT_BLOCK = /import\s+(?:type\s+)?(?:\{([^}]*)\}|[\w*\s,]+)\s*from\s*'(cursedbelt(?:\/[^']*)?)'/g;
+
+export const fixtureImports = async (): Promise<FixtureImport[]> => {
+	const out: FixtureImport[] = [];
+	for (const rel of new Bun.Glob('**/*.tsx').scanSync({ cwd: FIXTURE_DIR, onlyFiles: true })) {
+		const text = await Bun.file(`${FIXTURE_DIR}/${rel}`).text();
+		for (const match of text.matchAll(IMPORT_BLOCK)) {
+			const names = (match[1] ?? '')
+				.split(',')
+				.map((n) => n.trim().replace(/^type\s+/, ''))
+				// `A as B` exports A; the local alias is the consumer's business.
+				.map((n) => (n.includes(' as ') ? (n.split(/\s+as\s+/)[0] as string) : n))
+				.filter(Boolean);
+			out.push({ subpath: (match[2] as string).replace(/^cursedbelt/, '.'), names, file: `${FIXTURE}/${rel}` });
+		}
+	}
+	return out;
+};
+
+/**
+ * `export { A, type B } from './x'` in the `react` barrel → exported name → module.
+ *
+ * Only the named form, on purpose. A fixture import the barrel re-exports with
+ * `export * from` cannot be attributed to one module by a reader either, and
+ * `resolveFixtureModules` fails naming it rather than guessing — an unattributed
+ * import is exactly the case where an app would silently under-declare its areas.
+ */
+const NAMED_REEXPORT = /export\s+(?:type\s+)?\{([^}]*)\}\s*from\s*'(\.[^']+)'/g;
+
+export const barrelMap = async (): Promise<Map<string, string>> => {
+	const text = await Bun.file(`${REACT_DIR}/index.ts`).text();
+	const out = new Map<string, string>();
+	for (const match of text.matchAll(NAMED_REEXPORT)) {
+		const target = match[2] as string;
+		for (const raw of (match[1] as string).split(',')) {
+			const name = raw.trim().replace(/^type\s+/, '');
+			const exported = name.includes(' as ') ? (name.split(/\s+as\s+/)[1] as string) : name;
+			if (exported) out.set(exported.trim(), target);
+		}
+	}
+	return out;
+};
+
+/** `./react/charts` → `<repo>/src/react/charts/index.ts`, through the export map's `source` condition. */
+const subpathSource = (subpath: string, exportsMap: Record<string, unknown>): string | null => {
+	const entry = exportsMap[subpath];
+	const target = typeof entry === 'string' ? entry : (entry as { source?: string } | undefined)?.source;
+	return typeof target === 'string' ? `${REPO_ROOT}/${target.replace(/^\.\//, '')}` : null;
+};
+
+export interface FixtureResolution {
+	/** Entry modules under `src/react` the fixture's imports land on. */
+	readonly entries: Map<string, FixtureImport>;
+	/** Imports nothing could attribute to a module — always a failure, never a skip. */
+	readonly unresolved: string[];
+}
+
+export const resolveFixtureModules = async (exportsMap: Record<string, unknown>): Promise<FixtureResolution> => {
+	const barrel = await barrelMap();
+	const entries = new Map<string, FixtureImport>();
+	const unresolved: string[] = [];
+	for (const imp of await fixtureImports()) {
+		const source = subpathSource(imp.subpath, exportsMap);
+		if (!source) {
+			unresolved.push(`${imp.file}: cursedbelt${imp.subpath.slice(1)} is not an export subpath`);
+			continue;
+		}
+		// The two barrels re-export the package; attribute each NAME instead, or the
+		// fixture would appear to use every module there is.
+		if (source === `${REACT_DIR}/index.ts`) {
+			for (const name of imp.names) {
+				const target = barrel.get(name);
+				if (!target) {
+					unresolved.push(
+						`${imp.file}: \`${name}\` is not re-exported by name from src/react/index.ts, so no area can be ` +
+							'attributed to it — import it from its own subpath instead',
+					);
+					continue;
+				}
+				const resolved = `${REACT_DIR}/${target.replace(/^\.\//, '')}`;
+				for (const ext of ['.ts', '.tsx', '/index.ts', '/index.tsx']) {
+					if (Bun.file(`${resolved}${ext}`).size > 0) {
+						entries.set(`${resolved}${ext}`, imp);
+						break;
+					}
+				}
+			}
+			continue;
+		}
+		entries.set(source, imp);
+	}
+	return { entries, unresolved };
+};
+
+/** Every module under `src/react` the fixture's imports actually reach. */
+export const fixtureClosure = async (exportsMap: Record<string, unknown>): Promise<{
+	modules: Set<string>;
+	resolution: FixtureResolution;
+}> => {
+	const graph = await buildGraph();
+	const resolution = await resolveFixtureModules(exportsMap);
+	const seen = new Set<string>();
+	const queue = [...resolution.entries.keys()];
+	while (queue.length > 0) {
+		const next = queue.pop() as string;
+		if (seen.has(next)) continue;
+		seen.add(next);
+		for (const dep of graph.get(next) ?? []) queue.push(dep);
+	}
+	return { modules: seen, resolution };
+};
+
+/**
+ * Modules the fixture reaches that no declared area covers.
+ *
+ * 🔴 This, not the byte count, is the assertion that stops the saving being fake.
+ * An app under-declares its areas by adding a component and forgetting the
+ * `@import` — and the symptom is a component with no classes, three repos away,
+ * on a screen nobody opened during review.
+ */
+export const uncoveredModules = async (
+	declared: readonly string[],
+	exportsMap: Record<string, unknown>,
+): Promise<string[]> => {
+	const { closures } = await areaClosures();
+	const covered = new Set<string>();
+	for (const name of [CORE, ...declared]) for (const file of closures.get(name) ?? []) covered.add(file);
+	const { modules } = await fixtureClosure(exportsMap);
+	const owners = (file: string): string[] =>
+		AREAS.filter((a) => closures.get(a.name)?.has(file)).map((a) => a.name);
+	return [...modules]
+		.filter((file) => !covered.has(file))
+		.sort()
+		.map((file) => `${file.replace(`${REPO_ROOT}/`, '')}  — covered by: ${owners(file).join(', ') || 'NO AREA'}`);
+};
+
+/** Declared areas whose `needs` the fixture's stylesheet does not also import. */
+export const missingNeeds = (declared: readonly string[]): string[] => {
+	const have = new Set(declared);
+	return declared
+		.flatMap((name) => transitiveNeeds(name).filter((need) => !have.has(need)).map((need) => `${name} needs ${need}`))
+		.sort();
+};
+
+// ── the two compiles ──────────────────────────────────────────────────────────
+
+/** Everything is resolved against `src/`, the way `styles.css`'s own `@import`s are. */
+const STYLES_BASE = `${REPO_ROOT}/src`;
+
+const buildCss = async (input: string): Promise<string> => {
+	const compiled = await compileStylesheet(input);
+	return compiled.build(new Scanner({ sources: compiled.sources }).scan());
+};
+
+/** The fixture's own classes, whichever route it takes. */
+const HEAD = `@import "tailwindcss" source(none);\n@source "${FIXTURE_DIR}";\n@import "./styles-static.css";\n`;
+const TAIL = '@import "./theme.css";\n';
+
+export const unionRouteCss = (): Promise<string> => buildCss(`${HEAD}@import "./styles-utilities.css";\n${TAIL}`);
+
+export const areaRouteCss = (declared: readonly string[]): Promise<string> =>
+	buildCss(`${HEAD}${declared.map((a) => `@import "./styles-areas/${a}.css";`).join('\n')}\n${TAIL}`);
+
+/**
+ * What the fixture NEEDS: its own classes plus the classes of exactly the
+ * cursedbelt modules it reaches, and nothing else. The area route must be a
+ * superset of this or it is an unstyled app wearing a small byte count.
+ */
+export const requiredCss = async (exportsMap: Record<string, unknown>): Promise<string> => {
+	const { modules } = await fixtureClosure(exportsMap);
+	const compiled = await compileStylesheet(`${HEAD}${TAIL}`);
+	const own = new Scanner({ sources: compiled.sources }).scan();
+	const contents = await Promise.all(
+		[...modules].sort().map(async (file) => ({
+			content: await Bun.file(file).text(),
+			extension: file.slice(file.lastIndexOf('.') + 1),
+		})),
+	);
+	const mine = new Scanner({}).scanFiles(contents);
+	return compiled.build([...new Set([...own, ...mine])].sort());
+};
+
+export { STYLES_BASE };
+
+// ── the baseline ──────────────────────────────────────────────────────────────
+
+export interface Baseline {
+	readonly header: string;
+	readonly counts: Map<string, number>;
+}
+
+export const ROUTES = ['union', 'areas'] as const;
+
+export const parseBaseline = (text: string): Baseline => {
+	const header: string[] = [];
+	const counts = new Map<string, number>();
+	for (const line of text.split('\n')) {
+		if (line.startsWith('#') || line.trim() === '') {
+			if (counts.size === 0) header.push(line);
+			continue;
+		}
+		const [bytes, route] = line.trim().split(/\s+/);
+		if (bytes && route) counts.set(route, Number(bytes));
+	}
+	return { header: header.join('\n'), counts };
+};
+
+export const formatBaseline = (header: string, counts: Map<string, number>): string =>
+	`${header}\n${ROUTES.map((r) => `${String(counts.get(r) ?? 0).padStart(9)}  ${r}`).join('\n')}\n`;
+
+export const readBaseline = async (): Promise<Baseline> => {
+	const file = Bun.file(BASELINE);
+	return (await file.exists()) ? parseBaseline(await file.text()) : { header: '', counts: new Map() };
+};
+
+export interface Measurement {
+	readonly declared: string[];
+	readonly union: number;
+	readonly areas: number;
+}
+
+export const measure = async (): Promise<Measurement> => {
+	const declared = await declaredAreas();
+	const [union, areas] = await Promise.all([unionRouteCss(), areaRouteCss(declared)]);
+	return { declared, union: union.length, areas: areas.length };
+};
+
+if (import.meta.main) {
+	const { declared, union, areas } = await measure();
+	const baseline = await readBaseline();
+	const now = new Map<string, number>([
+		['union', union],
+		['areas', areas],
+	]);
+	const saved = union - areas;
+	console.log(
+		`${FIXTURE} — ${declared.length} areas (${declared.join(', ')})\n` +
+			`  union route  ${union.toLocaleString().padStart(9)} B\n` +
+			`  area route   ${areas.toLocaleString().padStart(9)} B   (−${saved.toLocaleString()} B, ` +
+			`${((saved / union) * 100).toFixed(1)}% smaller)`,
+	);
+	if (process.argv.includes('--prune')) {
+		const next = new Map(baseline.counts);
+		let lowered = 0;
+		for (const route of ROUTES) {
+			const recorded = baseline.counts.get(route);
+			const measured = now.get(route) as number;
+			if (recorded === undefined || measured < recorded) {
+				next.set(route, measured);
+				lowered++;
+			}
+		}
+		if (lowered === 0) {
+			console.log('\nnothing to prune — the baseline already records the smaller number.');
+			process.exit(0);
+		}
+		await Bun.write(BASELINE, formatBaseline(baseline.header, next));
+		console.log(`\n✅ lowered ${lowered} baseline entry/entries in ${BASELINE}.`);
+		process.exit(0);
+	}
+	const grown = ROUTES.filter((r) => (now.get(r) as number) > (baseline.counts.get(r) ?? Number.POSITIVE_INFINITY));
+	if (grown.length > 0) {
+		console.error(
+			`\n❌ the fixture app's CSS GREW:\n` +
+				grown
+					.map((r) => `     ${r}: baseline allows ${baseline.counts.get(r)} B, it emits ${now.get(r)} B now`)
+					.join('\n') +
+				'\n   Raise the number by hand, in a commit that says why — `--prune` only lowers.',
+		);
+		process.exit(1);
+	}
+	process.exit(0);
+}

package/scripts/generateAreaStyles.ts

@@ -0,0 +1,253 @@
+#!/usr/bin/env bun
+/**
+ * Generate `src/styles-areas/*.css` — cursedbelt's utilities, PRECOMPILED PER AREA,
+ * so a consuming app pays for the components it renders instead of for the union.
+ *
+ * ── The number this exists to move ──────────────────────────────────────────
+ * `cursedbelt/styles.css` and the `styles-static.css` + `styles-utilities.css`
+ * pair emit the same union — the 135,470 B of `src/styles-utilities.css`,
+ * measured, whichever route an app takes — because `@source` cannot be aimed at
+ * anything finer than a directory and `VirtualList`/`VirtualCardGrid` live at the root of `src/react`.
+ * Five apps ship that union today; the heaviest of them draws a 3D orbit scene, a
+ * map frame, a lightbox and two lazy document viewers, and none of them renders
+ * more than a fraction of the design system.
+ *
+ * `scripts/styleAreas.ts` is the map and owns the WHY. This file is the compiler:
+ * one stylesheet per area, each holding the candidates in that area's import
+ * closure MINUS the ones `core` (and whatever the area declares in `needs`)
+ * already ships, so importing core plus five areas duplicates nothing. A consumer's stylesheet becomes:
+ *
+ *   @import "tailwindcss";
+ *   @import "cursedbelt/styles-static.css";
+ *   @import "cursedbelt/styles-areas/core.css";
+ *   @import "cursedbelt/styles-areas/data-table.css";   ← only what it renders
+ *   @import "cursedbelt/theme.css";
+ *
+ * and it scans nothing of this package's source tree, exactly as the
+ * `styles-utilities.css` route already arranged.
+ *
+ * ── What it is worth, measured on the fixture app ───────────────────────────
+ * `demo/fixtures/lean-app` is a real consumer built out of this package's own
+ * deep subpaths: a releases console with stat tiles, a chart, a sortable table
+ * and a virtualized log. Compiled both ways (tailwindcss 4.3.3, unminified, in
+ * this repo, both counts including the app's own utilities and the theme):
+ *
+ *   styles-static.css + styles-utilities.css        (the union)   169,517 B
+ *   styles-static.css + core + charts + data-table
+ *                     + stats + virtual                           119,432 B   −29.5%
+ *
+ * Of that, the cursedbelt half falls from 142,119 B to 92,034 B — a 35% cut, and
+ * the fixture is not a minimal app: it declares five of the 43 areas. `core`
+ * alone is 66,700 B against the 135,470 B union artifact, so the floor for an app
+ * that renders only primitives is roughly half of what every app ships today.
+ *
+ * 🔴 The saving is bounded by how coarse `core` is, NOT by this mechanism. An area
+ * can be one file — `scripts/styleAreas.ts` scans a file LIST, so nothing here has
+ * a directory's granularity in it — and splitting `core` further is a table edit
+ * with a regenerate, not a redesign.
+ *
+ * `src/fixtureAppCss.spec.ts` is what holds that number down — a baseline that
+ * fails when the emitted CSS for the fixture GROWS, which is the check nothing in
+ * this package had while three, then four, then five apps paid for the union.
+ *
+ * ── The trap, and why nothing here is allowed to be hand-written ────────────
+ * Every failure this mechanism can have is SILENT in the same way the
+ * `styles-utilities.css` split was: a missing area, a stale artifact and a
+ * collapsed scan all produce CSS that is smaller, and smaller is what the whole
+ * exercise was asked for. So the area map is CLOSURE-derived rather than listed
+ * (an area cannot be missing what its own components import),
+ * `coverageFault()` fails on a module no area reaches, and
+ * `src/stylesAreas.spec.ts` proves core-plus-every-area emits the union rule for
+ * rule before any of it is allowed to ship.
+ *
+ * Usage:
+ *   bun run styles:areas            # write src/styles-areas/*.css
+ *   bun run styles:areas --check    # exit 1 if any is stale, write nothing
+ */
+import { REPO_ROOT, STATIC_STYLESHEET, readStylesheets } from './generateStaticStyles';
+import { UTILITY_INPUT, compileStylesheet } from './generateUtilityStyles';
+import {
+	AREA_DIR,
+	AREAS,
+	type Area,
+	CORE,
+	areaClosures,
+	candidatesIn,
+	coverageFault,
+	transitiveNeeds,
+} from './styleAreas';
+
+export { AREA_DIR, AREAS, CORE };
+
+/** The stylesheet an area is written to, relative to the repo root. */
+export const areaFile = (name: string): string => `${AREA_DIR}/${name}.css`;
+
+/** The export subpath a consumer imports it by. */
+export const areaSubpath = (name: string): string => `./${AREA_DIR.replace(/^src\//, '')}/${name}.css`;
+
+/**
+ * A floor on `core`'s scan, for the same reason `generateUtilityStyles.ts` has
+ * one: a collapsed scan compiles and writes an EMPTY stylesheet, and every app
+ * that imported it renders unstyled with nothing red anywhere. 5,170 candidates
+ * today; a tripwire, not a ratchet.
+ */
+export const MIN_CORE_CANDIDATES = 1_000;
+
+const banner = (area: Area, candidates: number, subtracted: boolean): string => {
+	const needs = transitiveNeeds(area.name);
+	const imports = [CORE, ...needs, ...(subtracted ? [area.name] : [])]
+		.filter((n, i, all) => all.indexOf(n) === i)
+		.map((n) => ` *   @import "cursedbelt/styles-areas/${n}.css";`)
+		.join('\n');
+	return `/*
+ * cursedbelt — the \`${area.name}\` area. GENERATED BUILD ARTIFACT. Never hand-edit.
+ *
+ * ${area.why}.
+ *
+ * ${
+		subtracted
+			? `Every Tailwind utility the modules in this area's import closure use, MINUS the\n * ones ${[CORE, ...needs].map((n) => `\`styles-areas/${n}.css\``).join(' and ')} already ship${needs.length > 0 ? '' : 's'}. 🔴 Import ALL of these, in\n * this order — this file alone is incomplete:`
+			: 'Every Tailwind utility the primitives and their plumbing use. Import it first,\n * before any other area:'
+	}
+ *
+ *   @import "tailwindcss";
+ *   @import "cursedbelt/styles-static.css";
+${imports}
+ *   @import "cursedbelt/theme.css";
+ *
+ * An app that imports every area gets exactly what \`cursedbelt/styles-utilities.css\`
+ * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
+ * when this file is stale. ${candidates} candidate(s) scanned.
+ *
+ * Written by scripts/generateAreaStyles.ts (\`bun run styles:areas\`), which
+ * \`bun run build\` runs. The map of what is in which area, and why the areas are
+ * import closures rather than a hand-written list, is scripts/styleAreas.ts.
+ */
+`;
+};
+
+export interface BuiltArea {
+	readonly name: string;
+	readonly css: string;
+	/** Candidates this stylesheet was compiled from, after core was subtracted. */
+	readonly candidates: string[];
+	/** Every module in the area's closure, repo-relative — what the spec reports on. */
+	readonly modules: string[];
+}
+
+/**
+ * Compile every area.
+ *
+ * Refuses to run against a stale `styles-static.css` for the same reason
+ * `generateUtilityStyles.ts` does: these are compiled against it through
+ * `@reference`, so a stale one bakes in the wrong tokens with nothing to show for
+ * it in the output.
+ */
+export const buildAreaStyles = async (): Promise<BuiltArea[]> => {
+	const { expected, onDisk } = await readStylesheets();
+	if (onDisk !== expected) {
+		throw new Error(
+			`${STATIC_STYLESHEET} is ${onDisk === null ? 'missing' : 'stale'}, and these artifacts are compiled\n` +
+				`against it (\`@reference\`), so they would bake in the wrong tokens. Run:\n` +
+				`  cd ${REPO_ROOT} && bun run styles:static`,
+		);
+	}
+	const { closures } = await areaClosures();
+	const fault = coverageFault(closures);
+	if (fault) throw new Error(fault);
+
+	const coreClosure = closures.get(CORE) as Set<string>;
+	const coreCandidates = await candidatesIn(coreClosure);
+	if (coreCandidates.size < MIN_CORE_CANDIDATES) {
+		throw new Error(
+			`the scan of \`${CORE}\` found ${coreCandidates.size} candidates (floor ${MIN_CORE_CANDIDATES}).\n` +
+				'That is a collapsed scan, not a small core — the stylesheet it would write emits an\n' +
+				'empty utility layer and every consuming app renders UNSTYLED.',
+		);
+	}
+
+	// Every area's raw candidate set first: `needs` subtracts one area from another,
+	// so no area can be compiled until all of them have been scanned.
+	const raw = new Map<string, Set<string>>([[CORE, coreCandidates]]);
+	for (const area of AREAS) {
+		if (area.name === CORE) continue;
+		raw.set(area.name, await candidatesIn(closures.get(area.name) as Set<string>));
+	}
+
+	const built: BuiltArea[] = [];
+	for (const area of AREAS) {
+		const closure = closures.get(area.name) as Set<string>;
+		const needs = transitiveNeeds(area.name);
+		const subtract =
+			area.name === CORE
+				? new Set<string>()
+				: new Set([...coreCandidates, ...needs.flatMap((n) => [...(raw.get(n) as Set<string>)])]);
+		const only = [...(raw.get(area.name) as Set<string>)].filter((c) => !subtract.has(c)).sort();
+		// 🔴 A fresh compile per area. The object `compile()` returns ACCUMULATES the
+		// candidates it has been built with, so reusing one would make every area after
+		// the first a superset of the ones before it — and each file would still look
+		// plausible on its own. Found by measuring; the symptom was areas growing
+		// monotonically in the order they were compiled.
+		const compiled = await compileStylesheet(UTILITY_INPUT);
+		built.push({
+			name: area.name,
+			css: `${banner(area, only.length, area.name !== CORE)}${compiled.build(only)}`,
+			candidates: only,
+			modules: [...closure].map((f) => f.replace(`${REPO_ROOT}/`, '')).sort(),
+		});
+	}
+	return built;
+};
+
+/** What each area's stylesheet should contain, and what is on disk right now. */
+export const readAreaStyles = async (): Promise<Array<BuiltArea & { onDisk: string | null }>> => {
+	const built = await buildAreaStyles();
+	return Promise.all(
+		built.map(async (area) => {
+			const target = Bun.file(`${REPO_ROOT}/${areaFile(area.name)}`);
+			return { ...area, onDisk: (await target.exists()) ? await target.text() : null };
+		}),
+	);
+};
+
+/** Area stylesheets on disk that `AREAS` no longer names — a renamed area leaves one behind. */
+export const strayAreaFiles = (): string[] => {
+	const known = new Set(AREAS.map((a) => `${a.name}.css`));
+	return [...new Bun.Glob('*.css').scanSync({ cwd: `${REPO_ROOT}/${AREA_DIR}`, onlyFiles: true })]
+		.filter((f) => !known.has(f))
+		.sort();
+};
+
+if (import.meta.main) {
+	const areas = await readAreaStyles();
+	const stale = areas.filter((a) => a.onDisk !== a.css);
+	const stray = strayAreaFiles();
+	if (process.argv.includes('--check')) {
+		if (stale.length === 0 && stray.length === 0) {
+			console.log(`✅ ${AREA_DIR}/ is current (${areas.length} areas).`);
+			process.exit(0);
+		}
+		console.error(
+			`❌ ${AREA_DIR}/ is out of date:\n` +
+				stale.map((a) => `     ${a.onDisk === null ? 'missing' : 'stale'}  ${areaFile(a.name)}`).join('\n') +
+				stray.map((f) => `\n     no longer an area  ${AREA_DIR}/${f}`).join('') +
+				`\n   Run:\n     cd ${REPO_ROOT} && bun run styles:areas`,
+		);
+		process.exit(1);
+	}
+	for (const area of stale) await Bun.write(`${REPO_ROOT}/${areaFile(area.name)}`, area.css);
+	const total = areas.reduce((sum, a) => sum + a.css.length, 0);
+	console.log(
+		stale.length === 0
+			? `✅ ${AREA_DIR}/ already current — ${areas.length} areas, ${total.toLocaleString()} B in total.`
+			: `✅ wrote ${stale.length} of ${areas.length} area stylesheet(s) into ${AREA_DIR}/ ` +
+					`(${total.toLocaleString()} B in total; core is ${areas[0]?.css.length.toLocaleString()} B).`,
+	);
+	if (stray.length > 0) {
+		console.error(
+			`\n❌ ${AREA_DIR}/ still holds ${stray.length} stylesheet(s) no area names — delete them:\n  ` +
+				stray.map((f) => `${REPO_ROOT}/${AREA_DIR}/${f}`).join('\n  '),
+		);
+		process.exit(1);
+	}
+}

package/scripts/guardrailsEnforce.spec.ts

@@ -45,6 +45,68 @@ describe('no-raw-action-button', () => {
   });
 });
 
+// Filed 2026-09-15 after three false positives in three repos, all one defect: the tag
+// walker stopped at the first `>` it saw, including one written in the PROSE of a comment
+// inside the attribute list — which made every attribute below that point invisible, opt-out
+// comment included. The third sighting was the fix for the second: a comment explaining this
+// bug, containing a literal `>`, reproduced it.
+describe('opening-tag extraction (comment-aware)', () => {
+  test('a prose "<select>" in a comment does not hide the opt-out below it', () => {
+    const source = `<button
+      // A radio-like list rather than a <select>, so the row is the control.
+      // guardrails-ignore no-raw-action-button: presentational row in a radio-like list
+      type="button"
+    >Move here</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(0);
+  });
+
+  test('a prose angle bracket does not hide a role="radio" below it', () => {
+    const source = `<button
+      /* A radio-like list rather than a <select>. */
+      role="radio"
+      aria-checked={selected}
+    >Move here</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(0);
+  });
+
+  test('an arrow-function attribute still does not end the tag', () => {
+    const source = `<button
+      onClick={() => setOpen(true)}
+      // guardrails-ignore no-raw-action-button: virtual gamepad key, a real button for AT
+      type="button"
+    >A</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(0);
+    // …and the walker still finds the end of that tag, rather than running on.
+    expect(check('no-raw-action-button', '<button onClick={() => save()}>Save</button>')).toHaveLength(1);
+  });
+
+  test('a "//" inside an attribute string is a URL, not a comment', () => {
+    const source = '<button data-href="https://example.com/x">Go</button><button role="tab">Tab</button>';
+    expect(check('no-raw-action-button', source)).toHaveLength(1);
+  });
+
+  test('a comment does not extend one tag over the NEXT element\'s ignore', () => {
+    const source = `<button
+      // A radio-like list rather than a <select>.
+      type="button"
+    >One</button>
+    <button
+      // guardrails-ignore no-raw-action-button: presentational row
+      type="button"
+    >Two</button>`;
+    expect(check('no-raw-action-button', source)).toHaveLength(1);
+  });
+
+  test('the same defect on <input>: prose above the opt-out', () => {
+    const source = `<input
+      // A raw input rather than a <select>-backed Field — the native file picker.
+      // guardrails-ignore no-raw-inputs: native file picker, no Field equivalent
+      type="file"
+    />`;
+    expect(check('no-raw-inputs', source)).toHaveLength(0);
+  });
+});
+
 describe('no-raw-overflow', () => {
   test('flags inline style overflow: auto', () => {
     expect(check('no-raw-overflow', '<div style={{ overflow: "auto" }} />')).toHaveLength(1);