cursedbelt 2.3.0 → 2.5.0

package/dist/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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "2.3.0",
+	"version": "2.5.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "Shared Bun + React framework",
@@ -30,13 +30,14 @@
 		"guardrails:report": "bun run scripts/guardrailsEnforce.ts no-raw-action-button,no-raw-overflow,no-raw-inputs,no-hardcoded-colors,no-raw-modal-footer,no-unguarded-editing-modal,control-height-tokens,no-raw-zindex,no-raw-data-table,no-tailwind-palette,no-raw-title-attr,micro-typography-floor,choice-needs-empty-state,no-select-as-action-menu,no-native-dialog,no-fast-tooltip --scope cursedbelt src/react src/styles.css",
 		"format": "biome format --write .",
 		"styles:static": "bun run scripts/generateStaticStyles.ts",
+		"styles:utilities": "bun run scripts/generateUtilityStyles.ts",
 		"test": "NODE_ENV=development bun test src",
 		"test:pg": "bun run scripts/testPg.ts",
 		"demo": "vite --config demo/vite.config.ts",
 		"demo:build": "vite build --config demo/vite.config.ts",
 		"demo:serve": "bun run demo:build && vite preview --config demo/vite.config.ts",
 		"prebuild": "bun run verify:gate",
-		"build": "rm -rf dist.next dist.prev && bun run scripts/generateStaticStyles.ts && tsc --project tsconfig.build.json --outDir dist.next && tsc --project tsconfig.build.server.json --outDir dist.next && CURSEDBELT_DIST_DIR=dist.next bun run scripts/copyDistAssets.ts && { [ -d dist ] && mv dist dist.prev || true; } && mv dist.next dist && rm -rf dist.prev",
+		"build": "rm -rf dist.next dist.prev && bun run scripts/generateStaticStyles.ts && bun run scripts/generateUtilityStyles.ts && tsc --project tsconfig.build.json --outDir dist.next && tsc --project tsconfig.build.server.json --outDir dist.next && CURSEDBELT_DIST_DIR=dist.next bun run scripts/copyDistAssets.ts && { [ -d dist ] && mv dist dist.prev || true; } && mv dist.next dist && rm -rf dist.prev",
 		"e2e": "playwright test --config e2e/playwright.config.ts",
 		"e2e:filter-rail": "playwright test --config e2e/playwright.config.ts filter-rail.spec.ts",
 		"e2e:table-layout": "playwright test --config e2e/playwright.config.ts table-layout.spec.ts",
@@ -488,7 +489,13 @@
 			"source": "./src/server/index.ts",
 			"import": "./dist/server/index.js"
 		},
-		"./server/guard/revocations": {
+		"./server/login-throttle": {
+		"types": "./dist/server/auth/loginThrottle.d.ts",
+		"bun": "./src/server/auth/loginThrottle.ts",
+		"source": "./src/server/auth/loginThrottle.ts",
+		"import": "./dist/server/auth/loginThrottle.js"
+	},
+	"./server/guard/revocations": {
 			"types": "./dist/server/guard/revocationStore.d.ts",
 			"bun": "./src/server/guard/revocationStore.ts",
 			"source": "./src/server/guard/revocationStore.ts",
@@ -514,6 +521,7 @@
 		},
 		"./styles.css": "./src/styles.css",
 		"./styles-static.css": "./src/styles-static.css",
+		"./styles-utilities.css": "./src/styles-utilities.css",
 		"./theme.css": "./src/theme.css",
 		"./workspace.css": "./src/workspace.css",
 		"./react/keep-awake": {
@@ -771,6 +779,8 @@
 		"@lezer/highlight": "^1.2.3",
 		"@node-rs/argon2": "^2.0.2",
 		"@playwright/test": "^1.61.0",
+		"@tailwindcss/node": "^4.3.1",
+		"@tailwindcss/oxide": "^4.3.1",
 		"@tailwindcss/vite": "^4.3.1",
 		"@tanstack/react-query": "5.101.2",
 		"@testing-library/dom": "^10.4.1",

package/scripts/generateUtilityStyles.ts

@@ -0,0 +1,215 @@
+/**
+ * Generate `src/styles-utilities.css` — cursedbelt's component utilities, PRECOMPILED.
+ *
+ * ── The hole this fills ─────────────────────────────────────────────────────
+ * `src/styles-static.css` (the sibling generator, `generateStaticStyles.ts`) is
+ * `styles.css` minus its `@source "."`. It was shipped for "an app that pays for
+ * its own scanning" — and until this file existed, no app could pay. Tailwind v4
+ * (4.3.3, measured) resolves every `@source` to a DIRECTORY and scans it
+ * recursively: a file path is silently widened to its parent, a glob is widened
+ * the same way, and `@source not` over a package's own tree subtracts nothing.
+ * All four of these emit byte-for-byte identical CSS in a consuming app:
+ *
+ *   @source ".../cursedbelt/src/react/index.*";
+ *   @source ".../cursedbelt/src/react/styling.*";
+ *   @source ".../cursedbelt/src/react/Virtual*.tsx";
+ *   @source ".../cursedbelt/src/react/*.{ts,tsx}";
+ *
+ * `VirtualList` and `VirtualCardGrid` sit at the ROOT of `src/react/`, so the
+ * finest grain an app can ask for is that directory — whose recursive contents
+ * are the whole design system. Scanning it is the union; not scanning it is an
+ * UNSTYLED app. There was no third option, which made `styles-static.css` as
+ * published a subpath with no correct use. (It also retires a long-standing
+ * misreading: the previous generation's hand-written 29-line `@source` list in
+ * `satellite-kit` was never file-level scoping — every line was widened to its
+ * parent directory, which is why that arrangement still emitted ~113 KB.)
+ *
+ * So the utilities become a BUILD ARTIFACT: compiled once, here, and shipped.
+ * The consumer scans nothing.
+ *
+ * ── What it is worth, measured, so nobody re-runs this blind ────────────────
+ * 🔴 It is NOT smaller. Compiling cursedbelt's own surface both ways (this repo,
+ * tailwindcss 4.3.3, lightningcss-minified):
+ *
+ *   @import "cursedbelt/styles.css"                      131,795 B · 22,490 gz
+ *   styles-static.css + styles-utilities.css             131,741 B · 22,462 gz
+ *
+ * — a 54-byte difference, i.e. the same stylesheet by another route. The union
+ * is the union however it is assembled. The 10.3 kB gzip saving flix measured
+ * came from scanning exactly the 29 modules Rollup put in its chunk, and that is
+ * per-app tree-shaking, which no single shared artifact can do. What this DOES
+ * buy: `styles-static.css` gains a correct use, a consuming app stops reaching
+ * into another package's source tree from its CSS (a `file:` dependency wearing
+ * a stylesheet's clothes), and the app's Tailwind build stops walking 827 files
+ * it does not own. Reaching the 16 KB-of-utilities floor flix measured needs
+ * per-module CSS the bundler can tree-shake — a different, larger change.
+ *
+ * ── Why GENERATED, and what holds it honest ─────────────────────────────────
+ * Same bargain as `styles-static.css`: this script writes it, `bun run build`
+ * runs this script, and `src/stylesUtilitiesMatches.spec.ts` fails when what is
+ * on disk is not what `src/react/**` currently produces. That spec does not
+ * compare SIZE — an unstyled app is invisible to a byte count read in one
+ * direction — it compiles a consumer both ways and compares the emitted rules.
+ *
+ * Usage:
+ *   bun run styles:utilities            # write src/styles-utilities.css
+ *   bun run styles:utilities --check    # exit 1 if it is stale, write nothing
+ */
+import { compile } from '@tailwindcss/node';
+import { Scanner } from '@tailwindcss/oxide';
+import { REPO_ROOT, STATIC_STYLESHEET, readStylesheets } from './generateStaticStyles';
+
+export { REPO_ROOT };
+
+export const UTILITY_STYLESHEET = 'src/styles-utilities.css';
+
+/** Every relative specifier below resolves against `src/`, like `styles.css` does. */
+export const STYLES_BASE = `${REPO_ROOT}/src`;
+
+/**
+ * The compile input.
+ *
+ * `@reference` rather than `@import` for the two cursedbelt stylesheets: it makes
+ * their `@theme` tokens, `@custom-variant dark` and `tw-animate-css`'s `@utility`
+ * definitions available to the compiler while emitting NONE of their CSS — the
+ * consumer imports those files itself, and duplicating them here would be the
+ * drift this whole arrangement exists to prevent. Dropping the
+ * `@reference "./styles-static.css"` line costs 41 rules: every `animate-in` /
+ * `fade-out` / `slide-in-from-*` / `data-[state=open]:*` utility the dialog,
+ * tooltip and collapsible families animate with, plus
+ * `.animate-progress-indeterminate`.
+ *
+ * `./react` and not `.`: `.` would scan `src/` — including this file's own output,
+ * making each generation depend on the last one. It buys nothing anyway; the whole
+ * of `src/` outside `src/react` adds 32 bytes.
+ */
+export const UTILITY_INPUT = `@layer theme, base, components, utilities;
+@import "tailwindcss/theme.css" layer(theme);
+@reference "./styles-static.css";
+@reference "./theme.css";
+@import "tailwindcss/utilities.css" layer(utilities);
+@source "./react";
+`;
+
+/**
+ * What a consuming app's CSS is, today and after adoption — the two inputs
+ * `src/stylesUtilitiesMatches.spec.ts` compiles and compares rule by rule.
+ *
+ * `source(none)` on the second one is the point of the exercise: it forbids
+ * Tailwind from scanning anything at all, so whatever comes out is what the
+ * precompiled artifact supplies and nothing else. A real app drops it and keeps
+ * scanning its OWN sources.
+ */
+export const CONSUMER_SCANNING = '@import "tailwindcss";\n@import "./styles.css";\n@import "./theme.css";\n';
+export const CONSUMER_PRECOMPILED =
+	'@import "tailwindcss" source(none);\n' +
+	'@import "./styles-static.css";\n' +
+	'@import "./styles-utilities.css";\n' +
+	'@import "./theme.css";\n';
+
+/**
+ * A floor on the scan, because the failure this artifact can have is SILENT.
+ * If `src/react` moves, or a `.gitignore` starts swallowing it, or oxide's walk
+ * returns nothing, the compile still succeeds — it just emits an empty utility
+ * layer, and every consumer ships an unstyled app. 16,594 candidates today; this
+ * is a collapse tripwire, not a ratchet.
+ */
+export const MIN_CANDIDATES = 1_000;
+
+/** cursedbelt's stylesheets are self-contained — nothing here loads a JS config. */
+const noDependency = (): void => {};
+
+/** Compile one of the inputs above against `src/`. */
+export const compileStylesheet = (
+	input: string,
+): ReturnType<typeof compile> => compile(input, { base: STYLES_BASE, onDependency: noDependency });
+
+/** The banner the artifact carries, so a reader never mistakes it for a source file. */
+export const BANNER = `/*
+ * cursedbelt component utilities — GENERATED BUILD ARTIFACT. Never hand-edit.
+ *
+ * Every Tailwind utility class cursedbelt's own components (\`src/react/**\`) use,
+ * compiled once at this package's build time so a consuming app does not have to
+ * scan this package's source tree — which Tailwind v4 cannot do at any grain
+ * finer than "the whole design system" anyway. Import it after Tailwind itself,
+ * beside the static entry point:
+ *
+ *   @import "tailwindcss";
+ *   @import "cursedbelt/styles-static.css";
+ *   @import "cursedbelt/styles-utilities.css";
+ *   @import "cursedbelt/theme.css";
+ *
+ * That pair emits the same rules as \`@import "cursedbelt/styles.css"\` — proved
+ * rule by rule, not by byte count, in src/stylesUtilitiesMatches.spec.ts. It is
+ * not SMALLER; see the header of scripts/generateUtilityStyles.ts for the
+ * measurements and for what it does buy.
+ *
+ * Written by scripts/generateUtilityStyles.ts (\`bun run styles:utilities\`),
+ * which \`bun run build\` runs. src/stylesUtilitiesMatches.spec.ts fails when what
+ * is on disk is not what src/react/** currently produces.
+ */
+`;
+
+/**
+ * Compile the utility layer from `src/react/**`.
+ *
+ * Refuses to run against a stale `styles-static.css`, rather than quietly baking
+ * the stale one's tokens in: the two artifacts are generated from the same
+ * `styles.css`, and `bun run build` orders them, but `bun run styles:utilities`
+ * on its own would not.
+ */
+export const buildUtilityStyles = async (): Promise<{ css: string; candidates: string[] }> => {
+	const { expected, onDisk } = await readStylesheets();
+	if (onDisk !== expected) {
+		throw new Error(
+			`${STATIC_STYLESHEET} is ${onDisk === null ? 'missing' : 'stale'}, and this artifact is compiled\n` +
+				`against it (\`@reference\`), so it would bake in the wrong tokens. Run:\n` +
+				`  cd ${REPO_ROOT} && bun run styles:static`,
+		);
+	}
+	const compiled = await compileStylesheet(UTILITY_INPUT);
+	const candidates = new Scanner({ sources: compiled.sources }).scan();
+	if (candidates.length < MIN_CANDIDATES) {
+		throw new Error(
+			`the scan of src/react found ${candidates.length} candidates (floor ${MIN_CANDIDATES}).\n` +
+				'That is a collapsed scan, not a small design system — the artifact it would write\n' +
+				'emits an empty utility layer and every consuming app ships UNSTYLED. Check that\n' +
+				`${STYLES_BASE}/react exists and is not excluded by a .gitignore.`,
+		);
+	}
+	return { css: `${BANNER}${compiled.build(candidates)}`, candidates };
+};
+
+/** The artifact's expected contents and what is on disk right now. */
+export const readUtilityStylesheet = async (): Promise<{
+	expected: string;
+	onDisk: string | null;
+	candidates: string[];
+}> => {
+	const { css, candidates } = await buildUtilityStyles();
+	const target = Bun.file(`${REPO_ROOT}/${UTILITY_STYLESHEET}`);
+	return { expected: css, onDisk: (await target.exists()) ? await target.text() : null, candidates };
+};
+
+if (import.meta.main) {
+	const { expected, onDisk, candidates } = await readUtilityStylesheet();
+	if (process.argv.includes('--check')) {
+		if (onDisk === expected) {
+			console.log(`✅ ${UTILITY_STYLESHEET} is current (${candidates.length} candidates).`);
+			process.exit(0);
+		}
+		console.error(
+			`❌ ${UTILITY_STYLESHEET} is ${onDisk === null ? 'missing' : 'stale'}. Run:\n` +
+				`     cd ${REPO_ROOT} && bun run styles:utilities`,
+		);
+		process.exit(1);
+	}
+	if (onDisk === expected) {
+		console.log(`✅ ${UTILITY_STYLESHEET} already current (${candidates.length} candidates).`);
+	} else {
+		await Bun.write(`${REPO_ROOT}/${UTILITY_STYLESHEET}`, expected);
+		console.log(
+			`✅ wrote ${UTILITY_STYLESHEET} — ${candidates.length} candidates scanned from src/react.`,
+		);
+	}
+}

package/src/styles-static.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