cursedbelt 3.0.2 → 4.0.0

package/src/styles.css

@@ -6,29 +6,32 @@
  * This `@source` makes Tailwind v4 scan cursedbelt's source files so the utility
  * classes used by its components are generated in the app's stylesheet.
  *
- * ── Two ways in, and which one an app wants ──────────────────────────────────
+ * ── Three ways in, and which one an app wants ────────────────────────────────
  * `@source "."` is the expensive half: it points Tailwind's JIT at cursedbelt's
  * ENTIRE source tree, so the app emits the union of the whole design system
  * whether it renders three components or eighty, and its own build walks 827
  * files it does not own. Everything else in this file is CSS the components
  * genuinely need and no app can do without.
  *
- * A CSS `@import` takes the whole file, so the split is two more subpaths:
+ * A CSS `@import` takes the whole file, so the split is more subpaths:
  *
- *   cursedbelt/styles.css            this file — the real CSS + the `@source` scan
- *   cursedbelt/styles-static.css     the same file MINUS the `@source` line
- *   cursedbelt/styles-utilities.css  the utilities that `@source` line would have
- *                                    produced, precompiled at cursedbelt's build
+ *   cursedbelt/styles.css              this file — the real CSS + the `@source` scan
+ *   cursedbelt/styles-static.css       the same file MINUS the `@source` line
+ *   cursedbelt/styles-utilities.css    the utilities that `@source` line would have
+ *                                      produced, precompiled at cursedbelt's build
+ *   cursedbelt/styles-areas/<area>.css the same utilities, split by component family
  *
- * The second two are a PAIR and neither is usable alone — `styles-static.css` on
- * its own gets the tooltip pointer-events fix, the Progress keyframes, the
- * lightbox bridge, the ambient/glass layer and `tw-animate-css`, and emits none
- * of cursedbelt's utility classes, i.e. an unstyled app:
+ * `styles-static.css` is never usable alone — on its own it gets the tooltip
+ * pointer-events fix, the Progress keyframes, the lightbox bridge, the
+ * ambient/glass layer and `tw-animate-css`, and emits none of cursedbelt's
+ * utility classes, i.e. an unstyled app. It pairs with EITHER of the other two:
  *
- *   @import "tailwindcss";
- *   @import "cursedbelt/styles-static.css";
- *   @import "cursedbelt/styles-utilities.css";
- *   @import "cursedbelt/theme.css";
+ *   @import "tailwindcss";                        @import "tailwindcss";
+ *   @import "cursedbelt/styles-static.css";       @import "cursedbelt/styles-static.css";
+ *   @import "cursedbelt/styles-utilities.css";    @import "cursedbelt/styles-areas/core.css";
+ *   @import "cursedbelt/theme.css";               @import "cursedbelt/styles-areas/data-table.css";
+ *                                                 @import "cursedbelt/theme.css";
+ *      the whole design system                       what this app renders
  *
  * 🔴 Do NOT hand-list cursedbelt's component files to get the utilities back.
  * Tailwind v4 resolves every `@source` to a DIRECTORY and scans it recursively —
@@ -38,22 +41,30 @@
  * into this package's source tree is also a `file:` dependency wearing a
  * stylesheet's clothes, and it buys nothing: it is the thing the previous
  * generation's 29-line-per-app arrangement is remembered for, and those 29 lines
- * were never file-level scoping either.
+ * were never file-level scoping either. Three apps hand-maintained such a list
+ * and one of them ran to 173 lines; all three were deleted, because every one of
+ * them was a directory list wearing a costume.
  *
- * The pair is not SMALLER than this file — measured, both routes emit the same
- * rules within 54 bytes. What it buys is a build that scans nothing of another
- * package's source tree, and a `styles-static.css` that finally has a correct
- * use. The measurements, and what would actually shrink a consumer, are in the
- * header of `scripts/generateUtilityStyles.ts`.
+ * `styles-utilities.css` is not SMALLER than this file — measured, both routes
+ * emit the same rules within 54 bytes; the union is the union however it is
+ * assembled. What it buys is a build that scans nothing of another package's
+ * source tree. 🔴 What makes a consumer smaller is the AREAS, and only the
+ * package could build them: Tailwind cannot aim a `@source` at anything finer
+ * than a directory, but `@tailwindcss/oxide` can be handed a FILE LIST, which is
+ * what `scripts/generateAreaStyles.ts` does. Measured on the fixture consumer
+ * `demo/fixtures/lean-app`, the area route emits 30% less CSS than the union, and
+ * `src/fixtureAppCss.spec.ts` is the ratchet that stops it climbing back. The
+ * area map, and a sentence on what each area is for, is `scripts/styleAreas.ts`.
  *
  * 🔴 This header is in BOTH of the first two files, because one is generated from
  * the other and a test holds them byte-identical apart from the `@source` line.
  * Always edit `src/styles.css`; never `src/styles-static.css`, which
  * `scripts/generateStaticStyles.ts` rewrites on every `bun run build` and
  * `src/stylesStaticMatches.spec.ts` fails on when it is stale. Editing this file
- * invalidates `src/styles-utilities.css` too — it is compiled against the static
- * variant, `scripts/generateUtilityStyles.ts` rewrites it in the same build step,
- * and `src/stylesUtilitiesMatches.spec.ts` is what fails when it is stale.
+ * invalidates `src/styles-utilities.css` and every `src/styles-areas/*.css` too —
+ * all of them are compiled against the static variant, `bun run styles` rewrites
+ * them in the same build step, and `src/stylesUtilitiesMatches.spec.ts` /
+ * `src/stylesAreas.spec.ts` are what fail when they are stale.
  */
 
 /* Animation utilities (animate-in/out, fade/zoom/slide-in-from-*) consumed by the

package/src/stylesAreas.spec.ts

@@ -0,0 +1,247 @@
+/**
+ * `src/styles-areas/*.css` is a current, COMPLETE, non-overlapping split of
+ * `src/styles-utilities.css` (2026-09-15).
+ *
+ * ## What this exists to prevent
+ *
+ * The per-area split is the first change this package has made that can make a
+ * consuming app SMALLER, and every way it can go wrong produces a smaller
+ * stylesheet — which is the thing five apps asked for. A missing area, a stale
+ * artifact, a collapsed scan and a mis-assigned module all look like success from
+ * the outside. So nothing here reads a byte count in the direction people read it.
+ *
+ * Four properties, and the split is worthless without all four:
+ *
+ *   1. CURRENT — what is on disk is what `src/react/**` produces right now. The
+ *      artifacts replace a scan the app used to run, and a scan was self-healing
+ *      where a checked-in file is not.
+ *   2. COVERING — every module under `src/react` is in some area. A module in no
+ *      area is in no stylesheet, so it renders unstyled in every app that adopted
+ *      this, while still typechecking and still being present in the union that
+ *      apps on the old route import.
+ *   3. COMPLETE — core plus every area emits exactly what the union emits, rule
+ *      for rule. This is the assertion that says the split lost nothing.
+ *   4. SELF-CONTAINED — an area's stylesheet covers everything its own components
+ *      import, which is a property of how an area is DEFINED (the import closure
+ *      of its roots, `scripts/styleAreas.ts`) and is asserted here so a future
+ *      hand-written shortcut cannot quietly take it away.
+ *
+ * `scripts/styleAreas.ts` owns the WHY and the map; `scripts/generateAreaStyles.ts`
+ * is the compiler; this file is the WHETHER.
+ *
+ * 🔴 `Bun.file`/`Bun.Glob` for every read, never node:fs — this package's test
+ * preload virtualizes node:fs, so a `readFileSync` scan here reads MOCK data and
+ * passes against files it never opened. Same trap the sibling specs name; see the
+ * header of `src/publishShape.spec.ts`.
+ */
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+import { flatten, lostRules, referenced } from '../scripts/cssRules';
+import { REPO_ROOT } from '../scripts/generateStaticStyles';
+import {
+	AREAS,
+	CORE,
+	MIN_CORE_CANDIDATES,
+	areaFile,
+	areaSubpath,
+	readAreaStyles,
+	strayAreaFiles,
+} from '../scripts/generateAreaStyles';
+import { compileStylesheet } from '../scripts/generateUtilityStyles';
+import {
+	allModules,
+	areaClosures,
+	candidatesIn,
+	coverageFault,
+	needsGraphFault,
+	nonModuleFiles,
+	transitiveNeeds,
+} from '../scripts/styleAreas';
+
+const areas = await readAreaStyles();
+const { closures } = await areaClosures();
+
+/** The command every staleness failure below is fixed by, as a line the owner can paste. */
+const REGENERATE = `cd ${REPO_ROOT} && bun run styles:areas`;
+
+/** A consumer that imports EVERY area — the only route comparable to the union. */
+const all = AREAS.map((a) => `@import "./styles-areas/${a.name}.css";`).join('\n');
+const union = (
+	await compileStylesheet('@import "tailwindcss" source(none);\n@import "./styles-static.css";\n@import "./styles-utilities.css";\n@import "./theme.css";\n')
+).build([]);
+const split = (
+	await compileStylesheet(`@import "tailwindcss" source(none);\n@import "./styles-static.css";\n${all}\n@import "./theme.css";\n`)
+).build([]);
+const before = flatten(union);
+const after = flatten(split);
+/** Hoisted: the loop below asks this per declaration, over 130 KB of CSS. */
+const readByUnion = referenced(union);
+
+/**
+ * Rules the union emits ONLY because its `@source` scan reads files that are not
+ * modules — this package's own specs, its hand-written `.css`, its JSON corpora.
+ * See `nonModuleFiles()` for why they are correctly dropped; this is what proves
+ * they are the only thing dropped.
+ */
+const specOnly = (async () => {
+	const fromOthers = await candidatesIn(nonModuleFiles());
+	const fromModules = await candidatesIn(allModules());
+	const only = [...fromOthers].filter((c) => !fromModules.has(c)).sort();
+	const compiled = await compileStylesheet('@import "tailwindcss" source(none);\n@import "./styles-static.css";\n@import "./theme.css";\n');
+	return { keys: new Set(flatten(compiled.build(only)).keys()), count: only.length };
+})();
+
+describe('the per-area stylesheets are generated and gated', () => {
+	it('has an area map worth checking at all', () => {
+		// Vacuity guard for everything below: an empty AREAS, or one where `core` is
+		// not first, makes every other assertion pass while proving nothing.
+		expect(AREAS.length).toBeGreaterThan(10);
+		expect(AREAS[0]?.name).toBe(CORE);
+		expect(areas.length).toBe(AREAS.length);
+	});
+
+	it('every area says what it is for, so a consumer can decide to decline it', () => {
+		// An area nobody can explain is an area nobody can leave out, and the whole
+		// mechanism is consumers leaving areas out.
+		const unexplained = AREAS.filter((a) => a.why.trim().length < 20).map((a) => a.name);
+		expect(unexplained, `these areas have no usable \`why\`:\n  ${unexplained.join('\n  ')}`).toEqual([]);
+	});
+
+	it('is checked in and byte-identical to what the generator produces', () => {
+		const stale = areas.filter((a) => a.onDisk !== a.css).map((a) => `${areaFile(a.name)} (${a.onDisk === null ? 'missing' : 'stale'})`);
+		expect(
+			stale,
+			'these area stylesheets are not what src/react currently produces, so every app that\n' +
+				'imports one is missing the difference — a component that renders unstyled in\n' +
+				`production and nowhere else. Run:\n  ${REGENERATE}\n  ` +
+				stale.join('\n  '),
+		).toEqual([]);
+	});
+
+	it('leaves no stylesheet behind for an area that no longer exists', () => {
+		// A renamed area leaves its old file on disk, where it keeps being published and
+		// keeps working — until the day it is stale and nothing regenerates it.
+		expect(strayAreaFiles(), `delete these; no area names them:\n  ${strayAreaFiles().join('\n  ')}`).toEqual([]);
+	});
+
+	it('was compiled from a scan that did not collapse', () => {
+		const core = areas.find((a) => a.name === CORE);
+		expect(core?.candidates.length ?? 0).toBeGreaterThanOrEqual(MIN_CORE_CANDIDATES);
+	});
+
+	it('covers every module under src/react', () => {
+		// Property 2. `coverageFault` is what the generator refuses on; this is the
+		// assertion that fails in milliseconds naming the orphan, rather than at the
+		// next app's build.
+		expect(coverageFault(closures)).toBeNull();
+		// And the walk itself is real — a glob that returns nothing would make the
+		// check above pass vacuously.
+		expect(allModules().length).toBeGreaterThan(300);
+		expect(nonModuleFiles().length).toBeGreaterThan(20);
+	});
+
+	it('has no dangling or circular `needs`', () => {
+		// A cycle is the one failure that corrupts rather than bloats: two areas each
+		// subtracting the other means a shared candidate is emitted by NEITHER.
+		expect(needsGraphFault()).toBeNull();
+	});
+
+	it('is self-contained: an area covers everything its own modules import', () => {
+		// Property 4. True by construction today (an area IS an import closure), and
+		// asserted anyway so a future hand-listed area cannot silently take it away.
+		const holes: string[] = [];
+		for (const area of AREAS) {
+			const mine = closures.get(area.name) as Set<string>;
+			const allowed = new Set([...mine, ...(closures.get(CORE) as Set<string>)]);
+			for (const need of transitiveNeeds(area.name)) for (const f of closures.get(need) ?? []) allowed.add(f);
+			for (const file of mine) if (!allowed.has(file)) holes.push(`${area.name} → ${file}`);
+		}
+		expect(holes, `these areas reach a module they do not ship the CSS for:\n  ${holes.join('\n  ')}`).toEqual([]);
+	});
+
+	it('has compiled two real consumer stylesheets to compare', () => {
+		// Guards the completeness assertion below: two empty strings agree about
+		// everything, and both of these are built with no candidates at all, so a
+		// broken `@import` would produce exactly that.
+		expect(before.size).toBeGreaterThan(500);
+		expect(after.size).toBeGreaterThan(500);
+	});
+
+	it('emits, across all areas, every rule the union emits', async () => {
+		// Property 3 — the core proof, and the reason this file does not compare
+		// sizes. A missing key is a selector that vanished from the design system; a
+		// missing declaration is a property that stopped applying. Same normalisation
+		// the sibling spec documents: `@theme inline` aliases nothing reads are
+		// bookkeeping, not rules.
+		const { rules, declarations } = lostRules(before, after, (prop) => !readByUnion.has(prop));
+		// Everything the split drops must be a test fixture's class and nothing else.
+		// Bounded as well as explained: an amnesty that can absorb 300 rules is not an
+		// explanation, it is a hole.
+		const { keys, count } = await specOnly;
+		expect(count, 'nothing but modules under src/react — the allowance below measures nothing').toBeGreaterThan(0);
+		const unexplained = rules.filter((key) => !keys.has(key));
+		// A bound as well as an explanation: an allowance that can absorb 300 rules is
+		// not an explanation, it is a hole. The drop is the handful of classes only a
+		// `*.spec.tsx` fixture uses, and it is asserted to stay that size.
+		expect(rules.length, `${rules.length} rules dropped — far more than this package's test fixtures use`).toBeLessThan(60);
+		expect(
+			unexplained,
+			'the per-area split emits FEWER rules than `styles-utilities.css` does, and these\n' +
+				'are not explained by the non-module files the union scan sweeps up. Every selector\n' +
+				'listed renders unstyled even in an app that imported EVERY area, which means the\n' +
+				`split lost them, not that an app under-declared. Usually staleness:\n  ${REGENERATE}\n  ` +
+				unexplained.slice(0, 20).join('\n  '),
+		).toEqual([]);
+		expect(
+			declarations,
+			'the split emits these selectors but not these declarations, so the affected\n' +
+				`components render PARTLY styled. Usually staleness:\n  ${REGENERATE}\n  ` +
+				declarations.slice(0, 20).join('\n  '),
+		).toEqual([]);
+	});
+
+	it('is worth having: core is a fraction of the union, not the union renamed', async () => {
+		// The negative control for the whole exercise. If `core` grew until it were the
+		// union again — one careless root away, since a root's closure is transitive —
+		// every assertion above would still pass and no consumer would save a byte.
+		const core = areas.find((a) => a.name === CORE) as (typeof areas)[number];
+		const utilities = await Bun.file(`${REPO_ROOT}/src/styles-utilities.css`).text();
+		expect(
+			core.css.length,
+			`core is ${core.css.length} B against a ${utilities.length} B union — an area map where the\n` +
+				'primitives ARE the design system buys nothing. Move whatever grew it into an area.',
+		).toBeLessThan(utilities.length * 0.75);
+	});
+
+	it('exports every area as a subpath that resolves into a directory `files` ships', () => {
+		const exportsMap = (pkg as { exports: Record<string, unknown> }).exports;
+		const missing = AREAS.filter((a) => exportsMap[areaSubpath(a.name)] !== `./${areaFile(a.name)}`).map((a) => a.name);
+		expect(
+			missing,
+			'these areas are generated but not exported, so `@import "cursedbelt/styles-areas/<x>.css"`\n' +
+				`in an app throws ERR_PACKAGE_PATH_NOT_EXPORTED:\n  ${missing
+					.map((n) => `"${areaSubpath(n)}": "./${areaFile(n)}"`)
+					.join('\n  ')}`,
+		).toEqual([]);
+		// And nothing exported that no area produces — a renamed area leaves the old
+		// key behind, pointing at a file the next build deletes.
+		const known = new Set(AREAS.map((a) => areaSubpath(a.name)));
+		const dead = Object.keys(exportsMap).filter((k) => k.startsWith('./styles-areas/') && !known.has(k));
+		expect(dead, `these export subpaths name no area:\n  ${dead.join('\n  ')}`).toEqual([]);
+		expect((pkg as { files: string[] }).files).toContain('src');
+	});
+
+	it('resolves as `cursedbelt/styles-areas/core.css` through the real resolver', () => {
+		// The assertions above read the manifest; this one RESOLVES the specifier the
+		// way a consumer's bundler does. An export entry pointing at a path that does
+		// not exist satisfies every string comparison in this file and fails here.
+		expect(Bun.resolveSync(`${pkg.name}/styles-areas/${CORE}.css`, REPO_ROOT)).toBe(`${REPO_ROOT}/${areaFile(CORE)}`);
+	});
+
+	it('is regenerated by the build, so a stale area cannot be published', () => {
+		// `prepublishOnly` → `verify` → `build`, so the tarball's copies are always the
+		// ones this repo's current src/react produces.
+		expect((pkg as { scripts: Record<string, string> }).scripts.build).toContain('scripts/generateAreaStyles.ts');
+		expect((pkg as { scripts: Record<string, string> }).scripts.styles).toContain('styles:areas');
+	});
+});

package/src/stylesUtilitiesMatches.spec.ts

@@ -45,6 +45,7 @@
  */
 import { describe, expect, it } from 'bun:test';
 import pkg from '../package.json';
+import { CUSTOM_PROPERTY, declared, dropFallbacks, flatten, referenced } from '../scripts/cssRules';
 import {
 	CONSUMER_PRECOMPILED,
 	CONSUMER_SCANNING,
@@ -60,83 +61,11 @@ const { expected, onDisk, candidates } = await readUtilityStylesheet();
 /** The command every staleness failure below is fixed by, as a line the owner can paste. */
 const REGENERATE = `cd ${REPO_ROOT} && bun run styles:utilities`;
 
-/**
- * Flatten a stylesheet into `at-rule ‖ … ‖ selector` → the set of declarations in
- * that block, merging blocks that repeat (both routes emit `@keyframes spin`
- * twice; a consumer's browser does not care, and neither should a comparison).
- *
- * A hand-rolled walk rather than a CSS parser because the only input is Tailwind's
- * own output: well-formed, and the one construct that could confuse brace counting
- * — a `{` inside a string or a comment — is skipped explicitly.
- */
-const flatten = (css: string): Map<string, Set<string>> => {
-	const out = new Map<string, Set<string>>();
-	const stack: string[] = [];
-	const open: string[][] = [[]];
-	let buf = '';
-	const push = (raw: string): void => {
-		const decl = raw.trim();
-		if (decl) open[open.length - 1]?.push(decl);
-	};
-	for (let i = 0; i < css.length; i++) {
-		const ch = css[i];
-		if (ch === '/' && css[i + 1] === '*') {
-			i = css.indexOf('*/', i) + 1;
-			continue;
-		}
-		if (ch === '"' || ch === "'") {
-			const end = css.indexOf(ch, i + 1);
-			buf += css.slice(i, end + 1);
-			i = end;
-			continue;
-		}
-		if (ch === '{') {
-			stack.push(buf.trim().replace(/\s+/g, ' '));
-			buf = '';
-			open.push([]);
-			continue;
-		}
-		if (ch === '}') {
-			push(buf);
-			buf = '';
-			const key = stack.join(' ‖ ');
-			const set = out.get(key) ?? new Set<string>();
-			for (const decl of open.pop() ?? []) set.add(decl);
-			out.set(key, set);
-			stack.pop();
-			continue;
-		}
-		// At depth 0 a `;` ends a statement at-rule (`@layer a, b;`, `@import …`),
-		// which carries no declarations and must not stick to the next selector.
-		if (ch === ';') {
-			if (stack.length) push(buf);
-			buf = '';
-			continue;
-		}
-		buf += ch;
-	}
-	return out;
-};
-
-/** `var(--x, <anything>)` → `var(--x)`, so a fallback reads as the same declaration. */
-const dropFallbacks = (decl: string): string => decl.replace(/var\((\s*--[\w-]+)[^)]*\)/g, 'var($1)');
-
-const CUSTOM_PROPERTY = /^(--[\w-]+)\s*:/;
-
-/** Every custom property a stylesheet actually reads through `var()`. */
-const referenced = (css: string): Set<string> => {
-	const out = new Set<string>();
-	for (const m of css.matchAll(/var\(\s*(--[\w-]+)/g)) out.add(m[1] as string);
-	return out;
-};
-
-/** Every custom property a stylesheet declares, including `@property` registrations. */
-const declared = (css: string): Set<string> => {
-	const out = new Set<string>();
-	for (const m of css.matchAll(/(?:^|[;{\s])(--[\w-]+)\s*:/g)) out.add(m[1] as string);
-	for (const m of css.matchAll(/@property\s+(--[\w-]+)/g)) out.add(m[1] as string);
-	return out;
-};
+// 🔴 The flattener, the `var()` fallback normalisation and the two custom-property
+// walks used to live here. They moved to `scripts/cssRules.ts` when
+// `src/stylesAreas.spec.ts` needed the same comparison for the per-area split — one
+// copy, because a second flattener is a second thing that can drift from the
+// assertions that rely on it. The reasoning for each is in that file's header.
 
 // The two routes, compiled from the SAME candidate list (the classes cursedbelt's
 // components use), so neither side is credited with utilities the other was never

package/src/testFilesRunInParallel.spec.ts

@@ -0,0 +1,79 @@
+/**
+ * 🔴 `bun test` runs every file in ONE process unless it is told not to. This repo has 269
+ * of them, and that one process was the longest stage in the gate.
+ *
+ * ── What it cost, measured 2026-09-17 ───────────────────────────────────────
+ * `NODE_ENV=development bun test src` — 2,689 tests across 269 files — took **33.8s at
+ * 104% CPU** on a fourteen-core M3 Max. One core. The same suite:
+ *
+ * | workers | wall | pass / fail |
+ * |---|---|---|
+ * | 1 (the default) | 33.8s | 2689 / 0 |
+ * | `--parallel=4` | 17.0s | 2689 / 0 |
+ * | **`--parallel=6`** | **14.6s** | 2689 / 0 |
+ * | `--parallel` (14) | 11.8s | 2689 / 0 |
+ *
+ * Six, not fourteen, and the reason is the one `scripts/verify.ts` gives for its own job
+ * cap: `test` runs BESIDE `e2e` in the graph, and e2e is seven Playwright workers driving
+ * seven browsers. Fourteen more processes on top converts parallelism into thrash, and
+ * browser specs degrade worse than anything else under contention. The gain from 6 → 14 is
+ * 2.8s; the cost is paid by the stage that is already the longest.
+ *
+ * ── 🔴 This is a STRONGER gate, not a smaller one ───────────────────────────
+ * `--parallel` implies `--isolate`: each file gets a fresh global and module registry.
+ * Plain `bun test` shares one registry across all 269 files, so a spec that only passes
+ * because another file left state behind passes there and fails here. All 2,689 tests pass
+ * either way — which is the evidence that the isolation was not load-bearing, and it is
+ * worth knowing rather than assuming.
+ *
+ * The scratch directory was already safe for this: `scripts/testTmpRoot.ts` gives every
+ * PROCESS its own `$TMPDIR` under `$FORGE_STATE/test-scratch.noindex/tmp/<pid>`, written
+ * for exactly this reason before anything ran in parallel.
+ *
+ * ── Why a source assertion ──────────────────────────────────────────────────
+ * Same shape as `src/buildIsStaged.spec.ts`: what regresses is the SCRIPT — somebody
+ * simplifying a flag away, or copying the plain `bun test src` out of another repo — and a
+ * gate that silently goes back to 33.8s single-threaded looks exactly like a gate that is
+ * merely slow. Reading the string costs a millisecond; re-measuring it costs 34 seconds.
+ */
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+
+const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as {
+  scripts: Record<string, string>;
+};
+
+describe('the unit suite runs on more than one core', () => {
+  const script = pkg.scripts.test;
+
+  test('`bun run test` still names a parallel worker count', () => {
+    expect(script, 'package.json has no `test` script').toBeString();
+    expect(
+      /--parallel(=\d+)?\b/.test(script),
+      `\`test\` is "${script}" — with no \`--parallel\`, bun runs all 269 files in one ` +
+        'process on one core, which measured 33.8s against 14.6s. Put the flag back, or ' +
+        'say here why the suite may no longer be isolated per file.',
+    ).toBe(true);
+  });
+
+  test('the worker count stays inside the budget the verify graph assumes', () => {
+    // `scripts/verify.ts` runs up to `jobLimit()` stages at once and `e2e` is seven
+    // browsers. A bare `--parallel` means one worker per core, which is that budget
+    // ignored — so the number is written down, and it is written down here as well as in
+    // package.json because the two have to agree about why.
+    const asked = /--parallel=(\d+)\b/.exec(script);
+    expect(
+      asked,
+      `\`test\` is "${script}" — a bare \`--parallel\` takes one worker per core (14 on ` +
+        'this Mac) while `e2e` is already seven browsers beside it. Name the count.',
+    ).not.toBeNull();
+    const workers = Number(asked?.[1]);
+    expect(workers).toBeGreaterThanOrEqual(2);
+    expect(
+      workers,
+      'more workers than a third of the cores is the over-subscription `scripts/verify.ts` ' +
+        'caps its own stage count to avoid; measured, 6 → 14 workers buys 2.8s and is paid ' +
+        'for by the browser stage running beside it.',
+    ).toBeLessThanOrEqual(8);
+  });
+});

package/src/typecheckCachesAreSeparate.spec.ts

@@ -0,0 +1,128 @@
+/**
+ * 🔴 Four `tsc` projects run AT ONCE in `scripts/verify.ts`. Two of them writing one
+ * `.tsbuildinfo` is a corrupt cache, and a corrupt cache is a typecheck that skips files.
+ *
+ * ## Why this file exists
+ *
+ * Measured 2026-09-17, on a gate that was taking 7 minutes: `src` is type-checked FOUR
+ * times per run — `typecheck:root`, `typecheck:specs`, `build`, and again through
+ * `demo/tsconfig.json`'s `paths` — and not one of those runs remembered anything about the
+ * last one. 764 files, re-checked from cold, four times over, on a commit that changed one
+ * component. `typecheck:root` alone: 6.4s cold, 2.0s after a real edit to the largest
+ * component in the repo, 1.5s with nothing changed.
+ *
+ * Turning `incremental` on is the obvious fix and it brings its own trap with it, which is
+ * what this spec holds. `tsconfig.specs.json`, `tsconfig.scripts.json` and
+ * `tsconfig.build.json` all `extends` `tsconfig.json` — so a `tsBuildInfoFile` named there
+ * and not overridden is INHERITED, and the next project added to this repo gets the
+ * collision for free, silently, with a green gate on either side of it.
+ *
+ * The failure would not look like a failure. tsc would read a cache another process wrote
+ * mid-write, decide some files were current, and check fewer of them than it reported. That
+ * is the false-green shape this repo keeps paying for, so it gets a check rather than a
+ * paragraph in a tsconfig.
+ *
+ * 🔴 The configs are read through `tsc --showConfig`, never parsed here. That is the only
+ * reader that resolves `extends` the way the compiler does — and `extends` is the entire
+ * point: a project that forgets to override the parent's path is exactly the bug. It costs
+ * ~90ms per project because `--showConfig` does no type checking at all.
+ */
+import { describe, expect, it } from 'bun:test';
+import { spawnSync } from 'node:child_process';
+import { dirname, relative, resolve } from 'node:path';
+
+const ROOT = resolve(import.meta.dir, '..');
+
+/** Every tsconfig this repo owns. Globbed, so a new one is covered the day it lands. */
+function projectPaths(): string[] {
+  const glob = new Bun.Glob('**/tsconfig*.json');
+  return [...glob.scanSync({ cwd: ROOT, absolute: true })]
+    .filter((p) => !p.includes(`${ROOT}/node_modules`) && !p.includes('/dist'))
+    .sort();
+}
+
+interface Resolved {
+  /** Repo-relative, for a failure message somebody can act on. */
+  name: string;
+  incremental: boolean;
+  /** Absolute, because two projects in different directories can name the same file. */
+  buildInfo: string | null;
+  emits: boolean;
+}
+
+function resolveProject(path: string): Resolved {
+  const r = spawnSync(process.execPath, ['x', 'tsc', '--showConfig', '-p', path], {
+    cwd: ROOT,
+    encoding: 'utf8',
+  });
+  expect(r.status, `tsc --showConfig failed for ${path}:\n${r.stderr}`).toBe(0);
+  const options = (JSON.parse(r.stdout) as { compilerOptions?: Record<string, unknown> }).compilerOptions ?? {};
+  const info = options.tsBuildInfoFile;
+  return {
+    name: relative(ROOT, path),
+    incremental: options.incremental === true,
+    buildInfo: typeof info === 'string' ? resolve(dirname(path), info) : null,
+    emits: options.noEmit !== true,
+  };
+}
+
+const PROJECTS = projectPaths().map(resolveProject);
+
+describe('the typecheck caches', () => {
+  it('finds every tsconfig in the repo', () => {
+    // A glob that has quietly stopped matching would make every assertion below vacuous.
+    expect(PROJECTS.length, 'no tsconfig found — the glob is wrong, not the repo').toBeGreaterThanOrEqual(5);
+  });
+
+  it('🔴 never lets two projects write the same .tsbuildinfo', () => {
+    const byFile = new Map<string, string[]>();
+    for (const p of PROJECTS) {
+      if (!p.incremental || p.buildInfo === null) continue;
+      byFile.set(p.buildInfo, [...(byFile.get(p.buildInfo) ?? []), p.name]);
+    }
+    const shared = [...byFile.entries()].filter(([, names]) => names.length > 1);
+    expect(
+      shared.map(([file, names]) => `${relative(ROOT, file)} ← ${names.join(', ')}`),
+      'these projects share one incremental cache. `scripts/verify.ts` runs them ' +
+        'concurrently, so both processes write the same file and whatever survives is what ' +
+        'the NEXT run trusts. Give each project its own `tsBuildInfoFile` — an `extends` ' +
+        'inherits the parent\'s.',
+    ).toEqual([]);
+  });
+
+  it('🔴 keeps `incremental` off wherever tsc emits into a staged directory', () => {
+    // `bun run build` deletes `dist.next`, compiles into it, and renames it over `dist`. A
+    // cache that survives that describes outputs which are no longer where it says they are
+    // — and tsc may then SKIP emitting them. `src/buildIsStaged.spec.ts` guards the same
+    // dist against the other way of emptying it.
+    const emittingAndCached = PROJECTS.filter((p) => p.emits && p.incremental).map((p) => p.name);
+    expect(
+      emittingAndCached,
+      'an emitting project must not be incremental here: the build stages into `dist.next` ' +
+        'and swaps, so the cache and the output directory disagree by construction, and the ' +
+        'symptom is a published dist with files missing.',
+    ).toEqual([]);
+  });
+
+  it('🔴 every project that is NOT emitting is cached', () => {
+    // The other direction, and the reason this one is a test: the gate got faster by
+    // remembering, and the tempting way to fix any tsc oddity is to delete `incremental`
+    // from the project that is misbehaving. That would put the four-times-over cold check
+    // back with nothing to notice.
+    const uncached = PROJECTS.filter((p) => !p.emits && !p.incremental).map((p) => p.name);
+    expect(
+      uncached,
+      'these type-only projects re-check every file from cold on every gate run. Give them ' +
+        '`incremental: true` and their own `tsBuildInfoFile` (see `tsconfig.json`).',
+    ).toEqual([]);
+  });
+
+  it('keeps every cache inside the one gitignored directory', () => {
+    // One place to delete when a cache ever does need clearing, and one line in .gitignore
+    // rather than a pattern that has to anticipate the next file name.
+    const stray = PROJECTS.filter((p) => p.buildInfo !== null && !p.buildInfo.startsWith(`${ROOT}/.tscache/`)).map(
+      (p) => `${p.name} → ${relative(ROOT, p.buildInfo as string)}`,
+    );
+    expect(stray, 'every `tsBuildInfoFile` belongs under `.tscache/`, which .gitignore covers').toEqual([]);
+  });
+});

package/src/verifyGraph.spec.ts

@@ -39,6 +39,12 @@ const MUST_RUN = [
 	// checking code that lives elsewhere would be the violation, not the fix. Removed in the
 	// same commit as the stage in scripts/verify.ts, which is what this comment is for.
 	'typecheck:specs',
+	// 🔴 Not part of the original chain — added 2026-09-16 (task 172), and pinned here the
+	// same way, because it is the only thing that compiles `scripts/`. `cursedbelt/guardrails`
+	// is an EXPORT resolving into that tree, so dropping this stage puts four apps back to
+	// inheriting type errors from a file nothing here checks. "Adding a stage is free" cuts
+	// both ways: once added, removing it argues with this list.
+	'typecheck:scripts',
 	'demo:check',
 	'styles',
 	'build',