cursedbelt 3.0.2 → 4.1.0

package/scripts/styleAreas.ts

@@ -0,0 +1,585 @@
+/**
+ * The AREA MAP — which of cursedbelt's own modules a consuming app has to pay for,
+ * and which it can decline.
+ *
+ * ── What this is for ────────────────────────────────────────────────────────
+ * `cursedbelt/styles.css` ends in `@source "."`, so every app that imports it
+ * emits the union of the whole design system — the 135,470 B of utilities in
+ * `src/styles-utilities.css` — whether it renders three components or eighty. `styles-utilities.css` precompiled that
+ * union so the app stops scanning this package's tree, but it is the SAME union —
+ * measured at 54 bytes' difference (see `scripts/generateUtilityStyles.ts`).
+ *
+ * The reason no consumer could do better is that Tailwind v4 resolves every
+ * `@source` to a DIRECTORY and scans it recursively — a file path and a glob are
+ * both silently widened to their parent — so the finest grain an app can ask for
+ * is `src/react`, whose recursive contents ARE the design system. flix measured
+ * the ceiling from the consumer side and found no move available to it; the third
+ * and fourth and fifth consumers each re-derived the same dead end, one of them
+ * with a 173-line `@source` list that could never have worked.
+ *
+ * 🔴 The package is not stuck where the consumer is, and the lever is NOT its
+ * directory layout. `@tailwindcss/oxide`'s `Scanner.scanFiles()` takes a list of
+ * FILE CONTENTS, so cursedbelt can scan an arbitrary set of its own modules —
+ * per file, at any grain it likes — and ship the result as CSS. Moving
+ * `VirtualList`/`VirtualCardGrid` off the root of `src/react` into a `virtual/`
+ * directory (the breaking export change the task costed) buys exactly nothing
+ * that this does not, because nothing here asks Tailwind to walk a directory.
+ * The layout stays; the granularity comes from the file list.
+ *
+ * ── How an area is defined ──────────────────────────────────────────────────
+ * An area is a NAME and a set of ROOT modules. Its file set is the transitive
+ * import closure of those roots inside `src/react`, so an area is self-contained
+ * by construction: it can never be missing the CSS of something its own
+ * components render. That is the property a hand-listed area would get wrong on
+ * its second edit, and the failure would be invisible — a component that renders
+ * unstyled only in the apps that declined the area it silently needed.
+ *
+ * `core` is the area every consumer imports: the primitives, the theme plumbing
+ * and everything they reach. Every other area's stylesheet carries only what core
+ * — and whatever it declares in `needs` — does not already, so importing core plus
+ * five areas duplicates nothing.
+ *
+ * ── The two gates ───────────────────────────────────────────────────────────
+ * 1. COVERAGE — every non-spec module under `src/react` is in some area's
+ *    closure. A new component that no area reaches would be in no stylesheet at
+ *    all, i.e. unstyled in every app that adopted this. `coverageFault()` names
+ *    the orphans; `src/stylesAreas.spec.ts` fails on them.
+ * 2. COMPLETENESS — core plus every area emits exactly the rules the union
+ *    (`styles-utilities.css`) emits. Same assertion shape as
+ *    `src/stylesUtilitiesMatches.spec.ts`, and for the same reason: an area split
+ *    that loses a rule is invisible to `tsc`, to Biome, and to a byte count read
+ *    in the direction everybody reads it.
+ */
+import { Scanner } from '@tailwindcss/oxide';
+import { REPO_ROOT } from './generateStaticStyles';
+
+/** Where every path below is relative to. */
+export const REACT_DIR = `${REPO_ROOT}/src/react`;
+
+/** Directory the generated per-area stylesheets are written to, relative to the repo root. */
+export const AREA_DIR = 'src/styles-areas';
+
+export interface Area {
+	/** File name (`<name>.css`) and the subpath a consumer imports. */
+	readonly name: string;
+	/** Why this is a separable purchase — an area nobody can explain is an area nobody can decline. */
+	readonly why: string;
+	/**
+	 * Root modules, relative to `src/react`. A directory means its `index.ts`; a
+	 * directory with no index means every module directly inside it. The area is
+	 * the transitive closure of these, so this list is entry points, not contents.
+	 */
+	readonly roots: readonly string[];
+	/**
+	 * Modules included WITHOUT walking their imports.
+	 *
+	 * For `src/react/index.ts` and nothing else so far: the barrel re-exports the
+	 * entire package, so expanding it would pull every area into core and collapse
+	 * this whole file back into the union it exists to break up. It renders nothing
+	 * itself, so its own candidates are all it can contribute — but it is still a
+	 * module under `src/react`, and coverage is deliberately the strict "every
+	 * module is in some area" rather than a candidate comparison, because two areas
+	 * can share a class without sharing the component that uses it.
+	 */
+	readonly leaves?: readonly string[];
+	/**
+	 * Areas this one COMPOSES, and therefore subtracts as well as core.
+	 *
+	 * An area's stylesheet is its closure's candidates minus core's, so two areas
+	 * whose closures overlap each ship the overlap and an app importing both pays
+	 * for it twice. That is fine for the incidental overlap between, say, `chat` and
+	 * `notifications` — a few hundred bytes — and it is not fine for a composite:
+	 * `ChartTablePanel` renders a chart AND a DataTable, so without this it would
+	 * carry a second copy of both, and `charts` would drag the whole DataTable into
+	 * every app that draws a line chart.
+	 *
+	 * 🔴 A consumer MUST import an area's `needs` alongside it, which is what the
+	 * generated banner says and what `src/fixtureAppCss.spec.ts` checks of the
+	 * fixture's own stylesheet. `needs` is transitive and may not cycle.
+	 */
+	readonly needs?: readonly string[];
+}
+
+/**
+ * 🔴 `core` FIRST and always — the rest of this file subtracts it.
+ *
+ * What is in it: the primitives an app cannot render a screen without, plus the
+ * plumbing every one of them imports (hooks, lib, styling, icons, portal, slots,
+ * the colour-scheme and scale providers). What is deliberately NOT: anything a
+ * whole app can decline — charts, media, the spreadsheet, the calendar, the
+ * editors, the viewers, the gallery. Measured, that line puts `core.css` at
+ * 66,700 B against the union artifact's 135,470 — so an app that renders only
+ * primitives ships roughly half of what every app ships today, and an app that
+ * renders four families ships a little more than that.
+ */
+export const AREAS: readonly Area[] = [
+	{
+		name: 'core',
+		why: 'the primitives and the plumbing every screen renders; every consumer imports this one',
+		roots: [
+			'styling.ts',
+			'icons.tsx',
+			'compat.ts',
+			'authSignal.ts',
+			'sessionAuth.ts',
+			'createApiHooks.ts',
+			'usePagedList.ts',
+			'confirm.tsx',
+			'prompt.tsx',
+			'Toast.tsx',
+			'colorScheme',
+			'constants',
+			'layout',
+			'namespace',
+			'portal',
+			'slots',
+			'uiScale',
+			'hooks',
+			'lib',
+			'components/Accordion.tsx',
+			'components/ActionBar.tsx',
+			'components/ActionGroup.tsx',
+			'components/Alert.tsx',
+			'components/AsyncPanel.tsx',
+			'components/Avatar.tsx',
+			'components/AvatarStack.tsx',
+			'components/Badge.tsx',
+			'components/Button.tsx',
+			'components/ButtonGroup.tsx',
+			'components/ButtonLink.tsx',
+			'components/CardTapTarget.tsx',
+			'components/Checkbox.tsx',
+			'components/ChoiceMenu.tsx',
+			'components/Collapsible.tsx',
+			'components/ConfirmDialog.tsx',
+			'components/CopyButton.tsx',
+			'components/CopyableText.tsx',
+			'components/DeleteButton.tsx',
+			'components/DisclosureButton.tsx',
+			'components/DismissButton.tsx',
+			'components/DropdownMenu.tsx',
+			'components/EmptyState.tsx',
+			'components/ErrorBoundary.tsx',
+			'components/ErrorCard.tsx',
+			'components/Field.tsx',
+			'components/FieldLabel.tsx',
+			'components/Grid.tsx',
+			'components/HoverCard.tsx',
+			'components/IconButton.tsx',
+			'components/InfoHint.tsx',
+			'components/Input.tsx',
+			'components/Modal.tsx',
+			'components/OnlineDot.tsx',
+			'components/Page.tsx',
+			'components/PanelSeparator.tsx',
+			'components/PathText.tsx',
+			'components/Popover.tsx',
+			'components/Progress.tsx',
+			'components/QueryBoundary.tsx',
+			'components/ScrollArea.tsx',
+			'components/Section.tsx',
+			'components/SegmentedControl.tsx',
+			'components/SelectField.tsx',
+			'components/Skeleton.tsx',
+			'components/Slider.tsx',
+			'components/Spinner.tsx',
+			'components/SplitButton.tsx',
+			'components/StatusPill.tsx',
+			'components/Surface.tsx',
+			'components/Switch.tsx',
+			'components/Tabs.tsx',
+			'components/Tooltip.tsx',
+			'components/TooltipImpl.tsx',
+			'components/TruncatedText.tsx',
+			'components/dialog.tsx',
+			'components/layout.tsx',
+			'components/revealOnHover.ts',
+		],
+		leaves: ['index.ts'],
+	},
+	{
+		name: 'activity-bar',
+		why: 'the `cursedbelt/react/activity-bar` rail — app chrome most apps do not mount',
+		roots: ['activity-bar'],
+	},
+	{ name: 'analytics', why: 'the analytics panel and its drilldown', roots: ['analytics'] },
+	{
+		name: 'auth',
+		why: 'the sign-in / register surfaces and the aurora front door — one screen, and never in the app shell',
+		roots: ['components/auth', 'AuthGate.tsx'],
+	},
+	{ name: 'calendar', why: 'the date-picker family: a calendar grid is a whole layout nothing else shares', roots: ['components/calendar'] },
+	{ name: 'charts', why: 'the recharts wrappers — an app with no dashboard renders none of them', roots: ['charts'] },
+	{
+		name: 'chart-table',
+		why: 'ChartTablePanel, the chart-with-its-own-data-table composite — 14,838 B of it is the DataTable and the charts it already needs',
+		roots: ['components/ChartTablePanel.tsx'],
+		needs: ['charts', 'data-table'],
+	},
+	{ name: 'chat', why: 'the chat transcript, composer and message list', roots: ['chat'] },
+	{ name: 'clipboard', why: 'the clipboard-paste surfaces', roots: ['clipboard'] },
+	{ name: 'code-editor', why: 'the CodeMirror host and its chrome (an optional peer already)', roots: ['code-editor'] },
+	{ name: 'companion-link', why: 'the companion-device pairing flow', roots: ['companion-link'] },
+	{ name: 'dashboard-grid', why: 'the draggable widget grid', roots: ['dashboard-grid'] },
+	{ name: 'data-table', why: 'the DataTable — the largest single component in the package', roots: ['components/DataTable'] },
+	{ name: 'deep-link', why: 'the deep-link resolver surfaces', roots: ['deep-link'] },
+	{ name: 'diff-viewer', why: 'the side-by-side diff view', roots: ['diff-viewer'] },
+	{ name: 'disk-usage', why: 'the disk-usage treemap and its legend', roots: ['disk-usage'] },
+	{ name: 'emoji', why: 'the emoji picker — a whole third-party grid', roots: ['emoji', 'components/EmojiField.tsx', 'components/ReactionBar.tsx', 'components/ReactionPicker.tsx'] },
+	{
+		name: 'fields',
+		why: 'the long tail of form controls beyond Input/Select/Checkbox/Switch — an app renders a handful, never all',
+		roots: [
+			'components/Autocomplete.tsx',
+			'components/FieldInput.tsx',
+			'components/AutoGrowTextarea.tsx',
+			'components/CodeArea.tsx',
+			'components/CodeChip.tsx',
+			'components/CodeFieldInput.tsx',
+			'components/ColorField.tsx',
+			'components/ComboboxField.tsx',
+			'components/EnvCompare.tsx',
+			'components/EnvEditor.tsx',
+			'components/InlineEditableText.tsx',
+			'components/JsonEditor.tsx',
+			'components/MultiSelectField.tsx',
+			'components/NativeSelect.tsx',
+			'components/OtpInput.tsx',
+			'components/RatingField.tsx',
+			'components/RenderField.tsx',
+			'components/SecretInput.tsx',
+			'components/SliderField.tsx',
+			'components/StarRating.tsx',
+			'components/SwatchPicker.tsx',
+			'components/TagStrip.tsx',
+			'components/TagsInput.tsx',
+		],
+	},
+	{ name: 'file-tree', why: 'the flat (non-nested) file list and its row chrome', roots: ['file-tree'] },
+	{ name: 'filter-rail', why: 'the faceted filter rail', roots: ['filter-rail'] },
+	{ name: 'folder-tree', why: 'the nested folder tree', roots: ['folder-tree'] },
+	{ name: 'keep-awake', why: 'the keep-awake toggle and its badge', roots: ['keep-awake'] },
+	{ name: 'layout-engine', why: 'the persisted pane/grid layout engine — apps with a fixed layout render none of it', roots: ['layoutEngine'] },
+	{ name: 'markdown', why: 'the rendered-markdown document', roots: ['markdown', 'markdown/MarkdownDoc.tsx'] },
+	{ name: 'master-detail', why: 'the master/detail shell', roots: ['master-detail'] },
+	{ name: 'master-lock', why: 'the master-lock gate', roots: ['master-lock'] },
+	{
+		name: 'media',
+		why: 'the video/audio player, the upload client and the player strip',
+		roots: ['media', 'media/FrameGrabber.tsx', 'media/poster.ts'],
+	},
+	{
+		name: 'media-gallery',
+		why: 'the photo album, the lightbox and the gallery chrome',
+		// `MediaMetaEditor` is named explicitly for the same reason `media/FrameGrabber.tsx` is
+		// two entries up: the gallery reaches it through `React.lazy(() => import(…))`, and the
+		// closure walk reads static specifiers only — so a lazily-imported dialog is an orphan
+		// unless it is its own root. The coverage gate is what says so, by name, at build time.
+		roots: ['media-gallery', 'media-gallery/MediaMetaEditor.tsx', 'components/Lightbox.tsx'],
+	},
+	{
+		name: 'nav',
+		why: 'the AppShell chrome — the command palette, the nav rail, the place bar and the app menus',
+		roots: ['nav', 'nav/BreadcrumbMenus.tsx', 'nav/SideNavCustomize.tsx', 'components/AppShell.tsx'],
+	},
+	{ name: 'notifications', why: 'the notification centre and its feed', roots: ['notifications'] },
+	{
+		name: 'overlays',
+		why: 'the dialogs and drawers beyond the plain Modal/Confirm pair',
+		roots: [
+			'components/Drawer.tsx',
+			'components/DiscardConfirmDialog.tsx',
+			'components/ImpactDialog.tsx',
+			'components/PromptDialog.tsx',
+			'components/ElsewhereNotice.tsx',
+			'components/AddItemsMenu.tsx',
+		],
+	},
+	{ name: 'palette', why: 'the theme/colour palette editor', roots: ['palette'] },
+	{ name: 'pdf-viewer', why: 'the lazy PDF viewer (an optional peer already)', roots: ['pdf-viewer'] },
+	{ name: 'problem-detail', why: 'the RFC-7807 problem renderer', roots: ['problem-detail'] },
+	{ name: 'rich-text', why: 'the TipTap editor and its toolbar', roots: ['rich-text'] },
+	{ name: 'sharing', why: 'the share sheet and its permission rows', roots: ['sharing', 'components/sharing'] },
+	{ name: 'spreadsheet', why: 'the glide-data-grid host (an optional peer already)', roots: ['spreadsheet'] },
+	{
+		name: 'stats',
+		why: 'the KPI/meter/timeline family — dashboards render them, forms and lists never do',
+		roots: [
+			'components/EventTimeline.tsx',
+			'components/FindingsList.tsx',
+			'components/HudPill.tsx',
+			'components/LogViewer.tsx',
+			'components/MeterList.tsx',
+			'components/Sparkline.tsx',
+			'components/StatStrip.tsx',
+			'components/StatTile.tsx',
+			'components/StatTileGrid.tsx',
+			'components/ThresholdMeter.tsx',
+			'components/BuildFreshness.tsx',
+		],
+	},
+	{ name: 'test-report', why: 'the test-report reader', roots: ['testReport'] },
+	{
+		name: 'virtual',
+		why: 'VirtualList and VirtualCardGrid — at the ROOT of src/react, and separable anyway because nothing about a stylesheet cares where a module lives',
+		roots: ['VirtualList.tsx', 'VirtualCardGrid.tsx'],
+	},
+	{
+		name: 'workbench',
+		why: 'the resizable/split/panelled work surfaces and the drag-and-drop affordances',
+		roots: [
+			'components/PanelGrid.tsx',
+			'components/ResponsiveWorkbench.tsx',
+			'components/SplitPane.tsx',
+			'components/WidgetHeader.tsx',
+			'components/DragHandle.tsx',
+			'components/DropIndicator.tsx',
+			'components/DropSlot.tsx',
+			'components/SelectableRow.tsx',
+			'components/TreeView.tsx',
+			'components/PluginCard.tsx',
+			'components/IsolatedFrame.tsx',
+			'components/ScrollToTopButton.tsx',
+			'components/ChipFilterStrip.tsx',
+			// Beside the chips it renders, not in `core`: `ListToolbar`'s only non-core
+			// import IS `ChipFilterStrip`, so an app that mounts the toolbar already buys
+			// this area — and putting it in core would drag the chips into every consumer.
+			'components/ListToolbar.tsx',
+			'components/CommentThread.tsx',
+			'components/ConnectionHealer.tsx',
+			'components/ExternalLink.tsx',
+			'components/FileActions.tsx',
+			'components/FileDropZone.tsx',
+			'components/FileLocation.tsx',
+			'components/FileTypeIcon.tsx',
+			'components/InheritBadge.tsx',
+			'components/AmbientBackdrop.tsx',
+		],
+	},
+	{ name: 'wizard', why: 'the multi-step Wizard and its step chrome', roots: ['components/Wizard'] },
+	{ name: 'workbook-viewer', why: 'the lazy XLSX viewer (an optional peer already)', roots: ['workbook-viewer'] },
+];
+
+export const CORE = 'core';
+
+/** A module the graph walk can reach. Absolute paths, so nothing here is relative to a cwd. */
+const SOURCE = /\.(ts|tsx)$/;
+const SPEC = /\.spec\.(ts|tsx)$/;
+
+/** Every non-spec module under `src/react` — the set coverage is measured against. */
+export const allModules = (): string[] =>
+	[...new Bun.Glob('**/*.{ts,tsx}').scanSync({ cwd: REACT_DIR, onlyFiles: true })]
+		.filter((rel) => !SPEC.test(rel))
+		.map((rel) => `${REACT_DIR}/${rel}`)
+		.sort();
+
+/**
+ * Everything under `src/react` that is NOT a module an area can contain: the
+ * `*.spec.tsx` fixtures, the hand-written `.css` files, the `.json` corpora.
+ *
+ * 🔴 They are in no area, and they are the ONE deliberate difference between the
+ * areas and the union. `styles-utilities.css` is compiled from a `@source` scan of
+ * the `src/react` DIRECTORY, and a directory scan reads every file type it finds —
+ * so the union every app ships today emits `.antialiased` because `fileTree.css`
+ * writes `-webkit-font-smoothing: antialiased`, and `.slide-in-from-left` because
+ * a spec asserts on the string. Nothing renders any of it, so the areas correctly
+ * drop them; `src/stylesAreas.spec.ts` asserts they are the ONLY thing the split
+ * drops, which is what keeps "correct" from widening into "whatever went missing".
+ */
+export const nonModuleFiles = (): string[] => {
+	const modules = new Set(allModules());
+	return [...new Bun.Glob('**/*').scanSync({ cwd: REACT_DIR, onlyFiles: true })]
+		.map((rel) => `${REACT_DIR}/${rel}`)
+		.filter((file) => !modules.has(file))
+		.sort();
+};
+
+/**
+ * Relative import specifiers in a module — `from '…'`, bare `import '…'` and
+ * `import('…')` alike.
+ *
+ * A regex and not the TypeScript AST on purpose: this runs over 700 modules on
+ * every build, the only thing it has to understand is a string literal after a
+ * keyword, and a miss cannot go unnoticed — a module nothing reaches is an orphan,
+ * and `coverageFault()` fails the build naming it.
+ */
+const SPECIFIER = /(?:\bfrom\s*|\bimport\s*|\brequire\s*\(\s*)['"](\.[^'"]*)['"]/g;
+
+/** `./x` → the module it resolves to, or null when it is CSS, an asset, or missing. */
+const resolveRelative = (fromFile: string, specifier: string): string | null => {
+	const dir = fromFile.slice(0, fromFile.lastIndexOf('/'));
+	const parts = `${dir}/${specifier}`.split('/');
+	const stack: string[] = [];
+	for (const part of parts) {
+		if (part === '.' || part === '') continue;
+		if (part === '..') stack.pop();
+		else stack.push(part);
+	}
+	const base = `/${stack.join('/')}`;
+	if (SOURCE.test(base)) return base;
+	for (const candidate of [`${base}.ts`, `${base}.tsx`, `${base}/index.ts`, `${base}/index.tsx`]) {
+		// biome-ignore lint/nursery/noAwaitInLoop: synchronous existence check, no await here
+		if (Bun.file(candidate).size > 0) return candidate;
+	}
+	return null;
+};
+
+/**
+ * The import graph of `src/react`, as `module → modules it imports`.
+ *
+ * Built once and shared: the closure of 45 areas over 700 modules is 45 walks of
+ * the same graph, and reading every file 45 times is the difference between a
+ * generator that runs in a second and one nobody runs.
+ */
+export const buildGraph = async (): Promise<Map<string, string[]>> => {
+	const modules = allModules();
+	const graph = new Map<string, string[]>();
+	await Promise.all(
+		modules.map(async (file) => {
+			const text = await Bun.file(file).text();
+			const out = new Set<string>();
+			for (const match of text.matchAll(SPECIFIER)) {
+				const target = resolveRelative(file, match[1] as string);
+				// Outside `src/react` is outside every area — the utility scan never sees it.
+				if (target && target.startsWith(`${REACT_DIR}/`) && !SPEC.test(target)) out.add(target);
+			}
+			graph.set(file, [...out]);
+		}),
+	);
+	return graph;
+};
+
+/** A root, as written in `AREAS`, expanded to the module(s) it names. */
+export const expandRoot = (root: string): string[] => {
+	const path = `${REACT_DIR}/${root}`;
+	if (SOURCE.test(root)) return [path];
+	for (const index of [`${path}/index.ts`, `${path}/index.tsx`]) {
+		if (Bun.file(index).size > 0) return [index];
+	}
+	// A directory with no barrel (`components/calendar`, `components/auth`): every
+	// module directly inside it is a root, because nothing else names them.
+	const inside = [...new Bun.Glob('**/*.{ts,tsx}').scanSync({ cwd: path, onlyFiles: true })]
+		.filter((rel) => !SPEC.test(rel))
+		.map((rel) => `${path}/${rel}`);
+	if (inside.length === 0) throw new Error(`area root "${root}" names nothing under ${REACT_DIR}`);
+	return inside;
+};
+
+/** Transitive closure of an area's roots through the import graph. */
+export const closureOf = (area: Area, graph: Map<string, string[]>): Set<string> => {
+	const seen = new Set<string>();
+	const queue = area.roots.flatMap(expandRoot);
+	for (const leaf of area.leaves ?? []) seen.add(`${REACT_DIR}/${leaf}`);
+	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 seen;
+};
+
+export interface AreaClosures {
+	readonly graph: Map<string, string[]>;
+	/** Area name → every module in its closure, core included where it overlaps. */
+	readonly closures: Map<string, Set<string>>;
+}
+
+export const areaClosures = async (areas: readonly Area[] = AREAS): Promise<AreaClosures> => {
+	const graph = await buildGraph();
+	const closures = new Map<string, Set<string>>();
+	for (const area of areas) closures.set(area.name, closureOf(area, graph));
+	return { graph, closures };
+};
+
+/**
+ * 🔴 COVERAGE. Modules no area's closure reaches, and area names that collide.
+ *
+ * An orphan module's utilities are in NO stylesheet, so the component renders
+ * unstyled in every app that adopted the areas — and nothing else in this repo can
+ * see it, because the module still typechecks, still lints, and is still in the
+ * union `styles-utilities.css` that apps on the old route import. This is the
+ * whole reason the area map is allowed to be a hand-written table: the table can
+ * be wrong, and this says so by name.
+ */
+export const coverageFault = (closures: Map<string, Set<string>>, areas: readonly Area[] = AREAS): string | null => {
+	if (areas[0]?.name !== CORE) return `the first area must be \`${CORE}\`, which every other area subtracts`;
+	const names = new Set(areas.map((a) => a.name));
+	if (names.size !== areas.length) return 'two areas share a name, so one stylesheet would overwrite the other';
+	const needsFault = needsGraphFault(areas);
+	if (needsFault) return needsFault;
+	const covered = new Set<string>();
+	for (const files of closures.values()) for (const file of files) covered.add(file);
+	const orphans = allModules().filter((file) => !covered.has(file));
+	if (orphans.length === 0) return null;
+	return (
+		`${orphans.length} module(s) under src/react are in no area, so their utility classes are in no\n` +
+		'stylesheet and every component they render is UNSTYLED in an app that imports the areas.\n' +
+		`Add each to an existing area's \`roots\` in scripts/styleAreas.ts, or give it an area:\n  ` +
+		orphans.map((f) => f.replace(`${REPO_ROOT}/`, '')).join('\n  ')
+	);
+};
+
+/**
+ * 🔴 `needs` names areas that exist, never itself, and never a cycle.
+ *
+ * A dangling name would silently subtract nothing — the area would ship the
+ * overlap it was written to drop, which is only a size regression. A CYCLE is the
+ * one that corrupts: two areas each subtracting the other means a candidate that
+ * is in both is emitted by neither, and every component using it renders unstyled
+ * in an app that imported both. Checked before anything is compiled.
+ */
+export const needsGraphFault = (areas: readonly Area[] = AREAS): string | null => {
+	const byName = new Map(areas.map((a) => [a.name, a]));
+	for (const area of areas) {
+		if (area.name === CORE && (area.needs ?? []).length > 0) return `\`${CORE}\` may not \`need\` another area — everything subtracts it`;
+		for (const need of area.needs ?? []) {
+			if (need === area.name) return `area \`${area.name}\` needs itself`;
+			if (!byName.has(need)) return `area \`${area.name}\` needs \`${need}\`, which is not an area`;
+			if (need === CORE) return `area \`${area.name}\` needs \`${CORE}\`, which every area already subtracts`;
+		}
+	}
+	// Kahn: anything left when nothing more resolves is in a cycle.
+	const done = new Set<string>([CORE]);
+	for (;;) {
+		const ready = areas.filter((a) => !done.has(a.name) && (a.needs ?? []).every((n) => done.has(n)));
+		if (ready.length === 0) break;
+		for (const a of ready) done.add(a.name);
+	}
+	const stuck = areas.filter((a) => !done.has(a.name)).map((a) => a.name);
+	return stuck.length > 0 ? `a cycle in \`needs\`, so a shared candidate would be in NO area: ${stuck.join(', ')}` : null;
+};
+
+/** `needs`, transitively — the areas a consumer must import alongside this one. */
+export const transitiveNeeds = (name: string, areas: readonly Area[] = AREAS): string[] => {
+	const byName = new Map(areas.map((a) => [a.name, a]));
+	const out = new Set<string>();
+	const queue = [...(byName.get(name)?.needs ?? [])];
+	while (queue.length > 0) {
+		const next = queue.pop() as string;
+		if (out.has(next)) continue;
+		out.add(next);
+		for (const more of byName.get(next)?.needs ?? []) queue.push(more);
+	}
+	return [...out].sort();
+};
+
+/**
+ * Tailwind candidates in a set of modules.
+ *
+ * 🔴 A FRESH `Scanner` every call. Oxide's scanner remembers what it has already
+ * been shown and returns only what is new, so one shared instance would credit
+ * every shared candidate to whichever area happened to be scanned first — and the
+ * areas scanned later would ship stylesheets missing the utilities they use. Cost
+ * an hour to find while measuring this; the symptom was `media-gallery` reporting
+ * 591 candidates and 127 bytes.
+ */
+export const candidatesIn = async (files: Iterable<string>): Promise<Set<string>> => {
+	const contents = await Promise.all(
+		[...files].sort().map(async (file) => ({
+			content: await Bun.file(file).text(),
+			extension: file.slice(file.lastIndexOf('.') + 1),
+		})),
+	);
+	return new Set(new Scanner({}).scanFiles(contents));
+};

package/scripts/verify.ts

@@ -76,6 +76,11 @@ export const STAGES: readonly Stage[] = [
 	{ script: "paths" },
 	{ script: "typecheck:root" },
 	{ script: "typecheck:specs" },
+	// 🔴 Added 2026-09-16 (task 172). `tsconfig.json` includes `src` only, so the eleven
+	// files under `scripts/` were compiled by nothing — including `guardrailsEnforce.ts`,
+	// which package.json EXPORTS as `cursedbelt/guardrails`. Four apps were typechecking a
+	// file this repo's own gate had never looked at, and inheriting its errors.
+	{ script: "typecheck:scripts" },
 	{ script: "demo:check" },
 	{ script: "styles" },
 	{