cursedbelt 2.3.0 → 2.5.1

package/src/styles.css

@@ -6,32 +6,54 @@
  * 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 entry points, and which one an app wants ─────────────────────────────
+ * ── 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
- * (113 KB / 846 selectors, measured in the previous generation) whether it
- * renders three components or eighty. Everything else in this file is CSS the
- * components genuinely need and no app can do without.
+ * 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 a second subpath:
+ * 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.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 static one is for an app that pays for its own scanning — 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, so whatever component utilities it needs must come from
- * sources IT registers. Do not hand-list cursedbelt's component files to get
- * them back: a relative `@source` reaching into this package's source tree is a
- * `file:` dependency wearing a stylesheet's clothes, and it is the thing the
- * previous generation's 29-line-per-app arrangement is remembered for.
+ * 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:
  *
- * 🔴 This header is in BOTH 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
+ *   @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.
+ * `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/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',
+		);
+	});
+});