cursedbelt 1.0.0 → 2.5.0

package/src/styles.css

@@ -5,6 +5,55 @@
  *   @import "cursedbelt/theme.css";
  * 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 ──────────────────────────────────
+ * `@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:
+ *
+ *   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
+ *
+ * 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:
+ *
+ *   @import "tailwindcss";
+ *   @import "cursedbelt/styles-static.css";
+ *   @import "cursedbelt/styles-utilities.css";
+ *   @import "cursedbelt/theme.css";
+ *
+ * 🔴 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 —
+ * a file path and a glob are both silently widened to their parent — and
+ * `VirtualList`/`VirtualCardGrid` live at the root of `src/react/`, so the finest
+ * grain an app can write is the whole design system. A relative `@source` reaching
+ * 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.
+ *
+ * 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`.
+ *
+ * 🔴 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.
  */
 
 /* Animation utilities (animate-in/out, fade/zoom/slide-in-from-*) consumed by the

package/src/stylesStaticMatches.spec.ts

@@ -0,0 +1,134 @@
+/**
+ * `src/styles-static.css` is `src/styles.css` minus its `@source` line — and
+ * nothing else (2026-09-14).
+ *
+ * ## What this exists to prevent
+ *
+ * The scoped entry point has to be a SECOND FILE, because a CSS `@import` takes
+ * the whole of the one it is given: an app cannot ask for `styles.css` without
+ * `@source "."`, and `@source "."` is what makes every consumer emit the union
+ * of the entire design system.
+ *
+ * The previous generation's second file was `satellite-kit/styles/belt-static.css`
+ * — a hand-kept copy with the one line deleted and nothing comparing the two.
+ * That is a file that drifts, and drifts SILENTLY: the day someone adds a rule to
+ * `styles.css` and not to the copy, every scoped app quietly loses it. The loss is
+ * invisible in review (the diff looks complete), invisible to `tsc` (it is CSS),
+ * and invisible to Biome (nothing is wrong with either file). It shows up as a
+ * tooltip eating a click, or a Progress bar that never animates, in one app, weeks
+ * later.
+ *
+ * So the copy is OUTPUT — `scripts/generateStaticStyles.ts`, which `bun run build`
+ * runs before it compiles — and this spec is the gate that makes that true rather
+ * than merely intended. `bun run verify` builds before it tests, so a forgotten
+ * regeneration self-heals there; editing `styles.css` and running `bun test src`
+ * alone is where this goes red.
+ *
+ * The assertions deliberately come at it from both sides: one compares the file on
+ * disk to what the generator produces (is the checked-in output current?), and the
+ * rest compare it to `styles.css` DIRECTLY (is the generator still doing only what
+ * it claims?). A spec that only asked the generator to agree with itself would pass
+ * a generator that had started dropping real rules.
+ *
+ * 🔴 `Bun.file`, NOT node:fs — this package's test preload virtualizes node:fs, so
+ * a `readFileSync` here would read MOCK data and pass against files it never
+ * opened. Same trap as `src/publishShape.spec.ts`; see its header.
+ */
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+import {
+	REPO_ROOT,
+	SOURCE_DIRECTIVE,
+	STATIC_STYLESHEET,
+	readStylesheets,
+	staticStylesFrom,
+} from '../scripts/generateStaticStyles';
+
+const { source, expected, onDisk } = await readStylesheets();
+
+/** The command every failure below is fixed by, as a line the owner can paste. */
+const REGENERATE = `cd ${REPO_ROOT} && bun run styles:static`;
+
+const lines = (css: string): string[] => css.split('\n');
+const directives = (css: string): string[] => lines(css).filter((l) => SOURCE_DIRECTIVE.test(l));
+
+describe('styles-static.css is a generated, gated copy of styles.css', () => {
+	it('is checked in and byte-identical to what the generator produces', () => {
+		expect(onDisk, `${STATIC_STYLESHEET} is missing. It is generated:\n  ${REGENERATE}`).not.toBeNull();
+		expect(
+			onDisk,
+			`${STATIC_STYLESHEET} is stale — src/styles.css changed and the static variant was not\n` +
+				'regenerated, so every app importing `cursedbelt/styles-static.css` is missing the\n' +
+				`difference. Run:\n  ${REGENERATE}`,
+		).toBe(expected);
+	});
+
+	it('drops the `@source` line and keeps every other line, in order', () => {
+		// The independent half: compared against styles.css itself, not against the
+		// generator's output. Blank lines are excluded from the sequence check only
+		// because the dropped directive takes its trailing blank line with it; the
+		// exact line-count assertion below is what pins that down.
+		const kept = lines(source).filter((l) => l.trim() !== '' && !SOURCE_DIRECTIVE.test(l));
+		expect(lines(expected).filter((l) => l.trim() !== '')).toEqual(kept);
+	});
+
+	it('removes exactly the directive and the blank line it leaves behind', () => {
+		expect(
+			directives(source),
+			'src/styles.css must carry exactly the one `@source "."` this whole split is about',
+		).toEqual(['@source ".";']);
+		expect(directives(expected), 'the static variant must carry no `@source` at all').toEqual([]);
+		// 2 = the directive + the now-orphaned blank line after it. A third line
+		// going missing means the transform grew a second job.
+		expect(lines(source).length - lines(expected).length).toBe(2);
+	});
+
+	it('is not a pointless duplicate', () => {
+		// If `@source "."` ever leaves styles.css, the two files become identical and
+		// the static subpath is dead weight — but worse, the FULL entry point has
+		// stopped scanning and every consuming app emits no cursedbelt utilities.
+		expect(expected).not.toBe(source);
+	});
+
+	it('is exported as a subpath that resolves into a directory `files` ships', () => {
+		const exports = (pkg as { exports: Record<string, unknown> }).exports;
+		expect(exports['./styles-static.css']).toBe(`./${STATIC_STYLESHEET}`);
+		// It must resolve out of `src/`, exactly like its sibling: `./styles.css`
+		// points at the SOURCE tree (not dist) because `@source "."` has to resolve
+		// relative to the files it is meant to scan, and a pair of app-facing
+		// stylesheets served from two different directories is a difference nobody
+		// can see in CSS.
+		expect(exports['./styles.css']).toBe('./src/styles.css');
+		// `files` ships whole directories, so `src` is what actually puts both of
+		// them in the tarball. publishShape.spec.ts proves the general rule; this is
+		// the one line that makes THIS subpath's failure legible.
+		expect((pkg as { files: string[] }).files).toContain('src');
+	});
+
+	it('resolves as `cursedbelt/styles-static.css` through the real resolver', () => {
+		// The assertions above read the manifest; this one RESOLVES the specifier the
+		// way a consumer's bundler does, through the package's own `exports` map (bun
+		// honours a self-reference by package name). An export entry pointing at a
+		// path that does not exist satisfies every string comparison in this file and
+		// fails here — which is the failure `belt-static.css` would have been.
+		expect(Bun.resolveSync(`${pkg.name}/styles-static.css`, REPO_ROOT)).toBe(
+			`${REPO_ROOT}/${STATIC_STYLESHEET}`,
+		);
+	});
+
+	it('is regenerated by the build, so a stale copy cannot be published', () => {
+		// `prepublishOnly` → `verify` → `build`, so the tarball's copy is always the
+		// one this repo's current styles.css produces. Without this step in `build`,
+		// the only thing standing between a drifted copy and a publish is a person
+		// remembering to run a script.
+		expect((pkg as { scripts: Record<string, string> }).scripts.build).toContain(
+			'scripts/generateStaticStyles.ts',
+		);
+	});
+
+	it('exposes the transform as a pure function', () => {
+		// Cheap guard on the one behaviour every assertion above leans on.
+		expect(staticStylesFrom('a\n@source ".";\n\nb\n')).toBe('a\nb\n');
+		expect(staticStylesFrom('a\nb\n')).toBe('a\nb\n');
+	});
+});

package/src/stylesUtilitiesMatches.spec.ts

@@ -0,0 +1,314 @@
+/**
+ * `src/styles-utilities.css` is a current, COMPLETE precompile of `src/react/**`
+ * (2026-09-14).
+ *
+ * ## What this exists to prevent
+ *
+ * The artifact replaces a `@source` scan the consuming app used to run. The scan
+ * was self-healing — it read whatever was in `src/react` at the app's build time —
+ * and the artifact is not: it is a file, generated once here, and every app that
+ * imports it gets exactly what was checked in.
+ *
+ * Its failure mode is SILENT and it is the worst one available. A stale artifact
+ * is missing the utilities a new component uses, so that component renders
+ * unstyled in every app; a collapsed scan writes an empty utility layer, so the
+ * WHOLE app renders unstyled. Neither is visible to `tsc` (it is CSS), to Biome
+ * (nothing is wrong with the file), or to a byte count read in one direction (a
+ * smaller stylesheet is the thing the split was asked for).
+ *
+ * So the assertions below do not compare size. They compile a consuming app BOTH
+ * ways — `@import "cursedbelt/styles.css"` (today, scanning) against
+ * `styles-static.css` + `styles-utilities.css` with `source(none)` (after
+ * adoption, scanning nothing) — and compare the rules that come out: every
+ * selector, every declaration, every custom property the declarations reference.
+ * `scripts/generateUtilityStyles.ts` owns the WHY and the measurements; this file
+ * is the WHETHER.
+ *
+ * Two differences between the two routes are real, deliberate and normalised for
+ * below rather than papered over — each is asserted to STILL BE the only one of
+ * its kind, so the normalisation cannot quietly widen into an amnesty:
+ *
+ *   · `var(--x)` on the scanning route vs `var(--x, <literal>)` on the
+ *     precompiled one, for tokens that reach the compiler through `@reference`.
+ *     Same variable, same computed value, plus a fallback.
+ *   · `@theme inline` alias declarations (`--color-card: var(--card)`) that the
+ *     scanning route emits into `:root` and nothing ever reads — `inline` means
+ *     the utility itself carries `var(--card)`, so the alias is bookkeeping. Only
+ *     custom properties something actually `var()`s are compared.
+ *
+ * `Bun.file` for every read here, not node:fs — the convention the sibling specs
+ * (`src/publishShape.spec.ts`, `src/declaredDepsAreImported.spec.ts`) state and
+ * the reason they give: a spec that reads through a mockable builtin can pass
+ * against files it never opened. The Tailwind compiler this file drives does use
+ * node:fs internally, which is unavoidable and is the point — it is resolving the
+ * same `@import`s a consumer's bundler will.
+ */
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+import {
+	CONSUMER_PRECOMPILED,
+	CONSUMER_SCANNING,
+	MIN_CANDIDATES,
+	REPO_ROOT,
+	UTILITY_STYLESHEET,
+	compileStylesheet,
+	readUtilityStylesheet,
+} from '../scripts/generateUtilityStyles';
+
+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 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
+// asked for. The precompiled route is built with no candidates at all: everything
+// it emits came out of the artifact on disk.
+const scanning = (await compileStylesheet(CONSUMER_SCANNING)).build(candidates);
+const precompiled = (await compileStylesheet(CONSUMER_PRECOMPILED)).build([]);
+const before = flatten(scanning);
+const after = flatten(precompiled);
+/** Hoisted: both loops below ask this per declaration, over 160 KB of CSS. */
+const readByScanning = referenced(scanning);
+
+describe('styles-utilities.css is a generated, gated precompile of src/react', () => {
+	it('is checked in and byte-identical to what the generator produces', () => {
+		expect(onDisk, `${UTILITY_STYLESHEET} is missing. It is generated:\n  ${REGENERATE}`).not.toBeNull();
+		expect(
+			onDisk,
+			`${UTILITY_STYLESHEET} is stale — src/react (or src/styles.css, which it is compiled\n` +
+				'against) changed and the artifact was not regenerated, so every app importing\n' +
+				`\`cursedbelt/styles-utilities.css\` is missing the difference. Run:\n  ${REGENERATE}`,
+		).toBe(expected);
+	});
+
+	it('was compiled from a scan that did not collapse', () => {
+		// The generator throws below its own floor; this is the assertion that says
+		// what the floor is FOR, and it fails here rather than at publish time.
+		expect(candidates.length).toBeGreaterThanOrEqual(MIN_CANDIDATES);
+	});
+
+	it('has compiled two real consumer stylesheets to compare', () => {
+		// Guards every assertion below: two empty strings agree about everything.
+		expect(before.size).toBeGreaterThan(500);
+		expect(after.size).toBeGreaterThan(500);
+	});
+
+	it('emits every rule the `@source` scan emits, with the same declarations', () => {
+		// The core proof, and the reason this spec does not read a byte count: an
+		// app that adopts the pair must RENDER the same. A missing key is a selector
+		// that vanished; a missing declaration is a property that stopped applying.
+		const lostRules: string[] = [];
+		const lostDeclarations: string[] = [];
+		for (const [key, decls] of before) {
+			const mine = after.get(key);
+			if (!mine) {
+				lostRules.push(key);
+				continue;
+			}
+			const theirs = new Set([...mine].map(dropFallbacks));
+			for (const decl of decls) {
+				// `@theme inline` aliases nothing reads — see the header.
+				const prop = CUSTOM_PROPERTY.exec(decl)?.[1];
+				if (prop && !readByScanning.has(prop)) continue;
+				if (!theirs.has(dropFallbacks(decl))) lostDeclarations.push(`${key} → ${decl}`);
+			}
+		}
+		expect(
+			lostRules,
+			'`styles-static.css` + `styles-utilities.css` emits FEWER rules than\n' +
+				'`styles.css` does. Every selector listed here renders unstyled in any app that\n' +
+				`adopted the pair. Usually staleness:\n  ${REGENERATE}`,
+		).toEqual([]);
+		expect(
+			lostDeclarations,
+			'the precompiled pair emits these selectors but not these declarations, so the\n' +
+				`affected components render PARTLY styled. Usually staleness:\n  ${REGENERATE}`,
+		).toEqual([]);
+	});
+
+	it('reads no custom property the files beside it do not declare', async () => {
+		// The trap the split creates and the scan never could: Tailwind emits only
+		// the theme variables its own build finds a use for, so a utility shipped in
+		// a prebuilt file can reference a `--text-sm` the consuming app never had a
+		// reason to emit — and `font-size: var(--text-sm)` with no `--text-sm` is an
+		// invisible nothing.
+		//
+		// 🔴 Asked of the FILES, not of a compile. Tailwind v4 back-fills: it tracks
+		// the `var()`s in whatever CSS it is handed, so the artifact's whole theme
+		// layer can be deleted and a compiled consumer still declares everything
+		// (verified by deleting it). That back-fill is real and it is why the rule
+		// comparison above passes — but it is Tailwind's promise, not this file's,
+		// and a `<link>` tag gets none of it. This asks what the artifact and the
+		// stylesheets a consumer imports beside it actually WRITE DOWN.
+		const artifact = onDisk ?? '';
+		// styles-static.css carries exactly one bare specifier, and its `@utility`
+		// definitions and `@property` registrations are where the `--tw-enter-*` /
+		// `--tw-animation-*` the artifact reads are declared. Pinned so the coupling
+		// cannot rot into a silent pass.
+		const animateDir = `${REPO_ROOT}/node_modules/tw-animate-css`;
+		expect(
+			(pkg as { dependencies: Record<string, string> }).dependencies['tw-animate-css'],
+			'tw-animate-css is what src/styles.css @imports',
+		).toBeDefined();
+		// Its own `exports` map, not a guessed filename — a CSS-only package resolves
+		// through the `style` condition, which Bun.resolveSync does not follow.
+		const animateManifest = (await Bun.file(`${animateDir}/package.json`).json()) as {
+			exports: Record<string, { style?: string }>;
+		};
+		const animateEntry = animateManifest.exports['.']?.style;
+		expect(animateEntry, 'tw-animate-css no longer exports a `style` entry').toBeDefined();
+		const animateCss = await Bun.file(`${animateDir}/${animateEntry}`).text();
+		expect(animateCss.length, 'tw-animate-css moved its stylesheet').toBeGreaterThan(1_000);
+		const beside = await Promise.all(
+			['src/theme.css', 'src/styles-static.css'].map((f) => Bun.file(`${REPO_ROOT}/${f}`).text()),
+		);
+		const provided = new Set([artifact, animateCss, ...beside].flatMap((css) => [...declared(css)]));
+		// Differential, not an allowlist: whatever the scanning route leaves to the
+		// runtime (`--radix-*`/`--reka-*` from the positioning libraries, `--cb-*`
+		// set inline by components) is fine here too, and nothing NEW is.
+		const declaredByScanning = declared(scanning);
+		const known = [...readByScanning].filter((v) => !declaredByScanning.has(v));
+		expect(
+			[...referenced(artifact)].filter((v) => !provided.has(v) && !known.includes(v)).sort(),
+			`${UTILITY_STYLESHEET} reads these custom properties and neither it, src/theme.css,\n` +
+				'src/styles-static.css nor tw-animate-css declares them. Under the `@source` scan the\n' +
+				"consuming app's own build emitted them; a prebuilt file cannot count on that.\n" +
+				`Run:\n  ${REGENERATE}`,
+		).toEqual([]);
+	});
+
+	it('normalised exactly the two differences its header documents, and no more', () => {
+		// The two allowances above are the difference between a proof and a rubber
+		// stamp, so they are measured rather than trusted: if either grows, this
+		// fails and the header has to be rewritten before the pair ships again.
+		const fallbackOnly: string[] = [];
+		const aliasOnly: string[] = [];
+		const read = referenced(scanning);
+		for (const [key, decls] of before) {
+			const mine = after.get(key);
+			if (!mine) continue;
+			for (const decl of decls) {
+				if (mine.has(decl)) continue;
+				const prop = CUSTOM_PROPERTY.exec(decl)?.[1];
+				if (prop && !read.has(prop)) aliasOnly.push(`${key} → ${decl}`);
+				else fallbackOnly.push(`${key} → ${decl}`);
+			}
+		}
+		// One: `.animate-progress-indeterminate`, whose `@theme` token reaches the
+		// artifact's compile through `@reference "./styles-static.css"`.
+		expect(fallbackOnly.map((d) => d.split(' → ')[0])).toEqual([
+			'@layer utilities ‖ .animate-progress-indeterminate',
+		]);
+		// Four: the `@theme inline` aliases in src/theme.css that no utility reads.
+		// A number, not a list, because which four is an implementation detail of
+		// Tailwind's theme tree-shaking; a JUMP here means the allowance is covering
+		// something it was not written for.
+		expect(aliasOnly.length).toBeLessThanOrEqual(8);
+	});
+
+	it('is exported as a subpath that resolves into a directory `files` ships', () => {
+		const exports = (pkg as { exports: Record<string, unknown> }).exports;
+		expect(exports['./styles-utilities.css']).toBe(`./${UTILITY_STYLESHEET}`);
+		// Out of `src/`, beside the two stylesheets it completes — a trio of
+		// app-facing stylesheets served from two different directories is a
+		// difference nobody can see in CSS.
+		expect(exports['./styles-static.css']).toBe('./src/styles-static.css');
+		expect((pkg as { files: string[] }).files).toContain('src');
+	});
+
+	it('resolves as `cursedbelt/styles-utilities.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-utilities.css`, REPO_ROOT)).toBe(
+			`${REPO_ROOT}/${UTILITY_STYLESHEET}`,
+		);
+	});
+
+	it('is regenerated by the build, so a stale artifact cannot be published', () => {
+		// `prepublishOnly` → `verify` → `build`, so the tarball's copy is always the
+		// one this repo's current src/react produces.
+		expect((pkg as { scripts: Record<string, string> }).scripts.build).toContain(
+			'scripts/generateUtilityStyles.ts',
+		);
+	});
+});

package/src/tapTargetStylesheet.spec.ts

@@ -0,0 +1,150 @@
+import { describe, expect, it } from 'bun:test';
+import { Scanner } from '@tailwindcss/oxide';
+import { compile } from 'tailwindcss';
+import {
+	TAP_TARGET,
+	TAP_TARGET_ALWAYS,
+	TAP_TARGET_HALO,
+	TAP_TARGET_HEIGHT,
+	TAP_TARGET_SQUARE,
+} from './react/lib/tapTarget';
+
+/**
+ * 🔴 THE TAP FLOOR SURVIVES THE JIT.
+ *
+ * `src/react/lib/tapTarget.ts` collapsed 48 hand-written copies of `DESIGN.md`
+ * §5's 44px floor — and 12 of the hover-reveal fix that goes with it — into five
+ * constants. That refactor has one failure mode, and it is silent: **Tailwind's
+ * JIT scans source TEXT, it does not evaluate code.** A
+ * class that stops being a literal inside this package's own `@source "."` glob —
+ * moved to a file the glob does not cover, assembled from a variable, split
+ * across a template it cannot read — is a class Tailwind never emits. Nothing
+ * reds. The types are fine, the build is fine, every component still carries the
+ * class name in its `className`, and the rule it names simply does not exist in
+ * the stylesheet any more. Every tap target on every phone in the fleet quietly
+ * loses its floor.
+ *
+ * So this compiles the REAL `src/styles.css` — its own `@source` directive, its
+ * own scan of this package's tree, Tailwind's own candidate extractor — and
+ * asserts the emitted CSS still carries a rule for every utility the constants
+ * name. It is the one check that can tell "the constant is exported" apart from
+ * "the constant does anything".
+ *
+ * 🔴 NOTHING IN THIS FILE MAY SPELL A TAP UTILITY OUT. The `@source` glob covers
+ * `src/`, and a spec is source: the first draft of this header quoted the height
+ * class in its own prose, and that comment alone kept the class in the candidate
+ * set after the constant had been broken. The check passed against a stylesheet
+ * held up by a sentence about the check. Utilities come from the imports above
+ * and from nowhere else in here.
+ *
+ * Verified failing, 2026-09-14, before it was trusted — each probe applied,
+ * observed and removed again:
+ *   · `TAP_TARGET_HEIGHT` rewritten as a template that interpolates its `11`
+ *       → both the extraction test and "utilities the emitted stylesheet has no
+ *         rule for: <the height class>". `TAP_TARGET` composes the same constant,
+ *         so every button in the package loses the floor from this one edit.
+ *   · `TAP_TARGET_HEIGHT` truncated to its scale-less prefix (the trailing `11`
+ *     dropped) → same failure, which is the anchored-selector half. A plain
+ *     `includes()` would have PASSED this one: the truncated name is a substring
+ *     of the rule the untruncated class emits elsewhere in the same stylesheet.
+ *     🔴 Truncating by one DIGIT instead does not fail, and should not — the
+ *     result is another real Tailwind utility with a real rule; what would be
+ *     broken there is the design, not the pipeline this file measures.
+ *   · the `@source` line removed from `src/styles.css` → "scanned no candidates",
+ *     the guard below that stops every other assertion passing vacuously.
+ *
+ * ~1.5s: one Tailwind compile of ~118 KB over ~25k candidates.
+ */
+
+const REPO_ROOT = import.meta.dir.replace(/\/src$/, '');
+
+/** Directory half of an absolute path — `node:path` is virtualized by the test preload. */
+const dirOf = (path: string): string => path.slice(0, path.lastIndexOf('/'));
+
+/**
+ * Resolve a CSS `@import` the way a bundler would.
+ *
+ * 🔴 `Bun.file`, never `node:fs`: this package's test preload virtualizes node
+ * builtins, so a `readFileSync` here would read MOCK data and the whole
+ * measurement would be of nothing (same trap as `publishShape.spec.ts`). A CSS
+ * package announces its entry through the `style` condition, not `main`.
+ */
+const loadStylesheet = async (
+	id: string,
+	base: string,
+): Promise<{ path: string; base: string; content: string }> => {
+	const read = async (path: string) => ({
+		path,
+		base: dirOf(path),
+		content: await Bun.file(path).text(),
+	});
+	if (id.startsWith('.')) return read(`${base}/${id}`);
+	const packageDir = `${REPO_ROOT}/node_modules/${id}`;
+	const manifest = (await Bun.file(`${packageDir}/package.json`).json()) as {
+		exports?: { '.'?: { style?: string } };
+		style?: string;
+		main?: string;
+	};
+	const entry = manifest.exports?.['.']?.style ?? manifest.style ?? manifest.main;
+	if (!entry) throw new Error(`no stylesheet entry for "${id}"`);
+	return read(`${packageDir}/${entry.replace(/^\.\//, '')}`);
+};
+
+/** Every utility the five constants name, deduped — the thing that must survive. */
+const UTILITIES = [
+	...new Set(
+		[TAP_TARGET_HEIGHT, TAP_TARGET, TAP_TARGET_SQUARE, TAP_TARGET_HALO, TAP_TARGET_ALWAYS]
+			.join(' ')
+			.split(/\s+/)
+			.filter(Boolean),
+	),
+];
+
+const emitted = await (async () => {
+	// An app imports Tailwind first, then this package's stylesheet — exactly the
+	// two lines `src/styles.css`'s own header tells a consumer to write.
+	const source = await Bun.file(`${REPO_ROOT}/src/styles.css`).text();
+	const compiler = await compile(`@import "tailwindcss";\n${source}`, {
+		base: `${REPO_ROOT}/src`,
+		loadStylesheet,
+	});
+	const candidates = new Scanner({ sources: compiler.sources }).scan();
+	return { candidates, css: compiler.build(candidates) };
+})();
+
+describe('the tap floor reaches the stylesheet', () => {
+	it('scanned this package for candidates at all', () => {
+		// Guards every assertion below: with no `@source` directive the scan returns
+		// nothing, `build([])` emits no utilities, and "the rule is missing" would be
+		// indistinguishable from "the refactor broke it".
+		expect(emitted.candidates.length).toBeGreaterThan(1000);
+	});
+
+	it('names utilities Tailwind actually extracted from the source text', () => {
+		// The JIT half: each class is a literal in a file the `@source` glob covers.
+		expect(UTILITIES.filter((u) => !emitted.candidates.includes(u))).toEqual([]);
+	});
+
+	it('emits a CSS rule for every utility the tap-target constants name', () => {
+		// A `:` is backslash-escaped inside a selector, so the class `a:b` is written
+		// `.a\:b` in the output — and a candidate that survived extraction but
+		// generated no rule (a utility Tailwind does not know) still fails here.
+		//
+		// 🔴 Anchored on the END of the class name, not a substring: a class truncated
+		// by one character is a prefix of the rule its untruncated self emits, so a
+		// plain `includes()` would have found it in a stylesheet that never had it.
+		const missing = UTILITIES.filter((u) => {
+			// The utility → its escaped selector text → a regex matching that text, with
+			// the CSS backslash itself escaped a second time for the regex.
+			const selectorText = `.${u.replace(/:/g, '\\:')}`;
+			const anchored = new RegExp(
+				`${selectorText.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w\\\\-])`,
+			);
+			return !anchored.test(emitted.css);
+		});
+		expect(
+			missing,
+			`utilities the emitted stylesheet has no rule for: ${missing.join(', ')}`,
+		).toEqual([]);
+	});
+});