cursedbelt 5.2.0 → 5.3.1

package/dist/styles-areas/core.css

@@ -144,3 +144,15 @@
 @source inline("w-[var(--control-h-lg)] w-[var(--control-h-md)] w-[var(--control-h-sm)] w-auto w-full w-px white");
 @source inline("whitespace-nowrap whitespace-pre-wrap wrap wrap-break-word z z-10 z-20 z-30 z-40 z-50");
 @source inline("z-[var(--z-popover)]");
+
+/*
+ * Theme variables cursedbelt's components read BY NAME (`var(--color-card)` in a style prop).
+ * Tailwind emits a theme variable only when the app's own pass sees it used, and a `var()` here is
+ * that use — `@source inline` cannot mark one. 9 variable(s), derived by
+ * scripts/generateUtilityStyles.ts → themeVariablesReadByName(). Nothing reads this property.
+ */
+@layer theme {
+  :root, :host {
+    --cb-theme-read-by-name: var(--color-accent) var(--color-border) var(--color-card) var(--color-muted) var(--color-popover) var(--duration-base) var(--ease-out) var(--text-caption) var(--text-sm);
+  }
+}

package/dist/styles-areas/spreadsheet.css

@@ -18,10 +18,10 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 4 candidate(s).
+ * 2 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
  * import closures rather than a hand-written list, is scripts/styleAreas.ts.
  */
-@source inline("--font-sans --text-sm col collapse");
+@source inline("col collapse");

package/dist/styles-areas/workbook-viewer.css

@@ -18,10 +18,10 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 7 candidate(s).
+ * 5 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
  * import closures rather than a hand-written list, is scripts/styleAreas.ts.
  */
-@source inline("--font-sans --text-sm col collapse min-w-16 w w-48");
+@source inline("col collapse min-w-16 w w-48");

package/dist/styles-utilities.css

@@ -4969,3 +4969,15 @@
     }
   }
 }
+
+/*
+ * Theme variables cursedbelt's components read BY NAME (`var(--color-card)` in a style prop).
+ * Tailwind emits a theme variable only when the app's own pass sees it used, and a `var()` here is
+ * that use — `@source inline` cannot mark one. 9 variable(s), derived by
+ * scripts/generateUtilityStyles.ts → themeVariablesReadByName(). Nothing reads this property.
+ */
+@layer theme {
+  :root, :host {
+    --cb-theme-read-by-name: var(--color-accent) var(--color-border) var(--color-card) var(--color-muted) var(--color-popover) var(--duration-base) var(--ease-out) var(--text-caption) var(--text-sm);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "5.2.0",
+	"version": "5.3.1",
 	"license": "ISC",
 	"type": "module",
 	"description": "The React design system of the cursedbelt split — components, styles, theme. cursedbelt-core below it; server tier in cursedbelt-server.",

package/scripts/checkAreaStyles.spec.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'bun:test';
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import {
   cascadeFaults,
   checkAreaStyles,
@@ -11,10 +11,21 @@ import {
   onlyAsPropertyName,
   onlyInMergeTables,
   readBeltSheets,
+  readThemeVariables,
+  scanLeaks,
+  themeVariablesIn,
   tokensInJs,
+  undefinedThemeVariables,
+  variablesDeclared,
 } from './checkAreaStyles';
 import { compileStylesheet } from './generateUtilityStyles';
 
+/**
+ * The CLI also runs the scan-leak check over its cwd. These fixtures live in a temp dir — which this
+ * repo's test preload puts under `.agent.noindex/` — so tell git the temp dir is in NO work tree.
+ */
+const noRepoEnv = (dir: string) => ({ ...process.env, GIT_CEILING_DIRECTORIES: dirname(dir) });
+
 const BELT = {
   union: `@layer utilities { .flex { display: flex } .rounded-full { border-radius: 9999px } .hover\\:bg-muted { &:hover { @media (hover: hover) { background: var(--muted) } } } .recharts-tip { opacity: .5; } }`,
   areas: {
@@ -82,7 +93,7 @@ describe('checkAreaStyles', () => {
     const dir = mkdtempSync(join(tmpdir(), 'belt-area-check-'));
     try {
       const run = () =>
-        Bun.spawnSync(['bun', join(import.meta.dir, 'checkAreaStyles.ts'), dir], { stdout: 'pipe', stderr: 'pipe' });
+        Bun.spawnSync(['bun', join(import.meta.dir, 'checkAreaStyles.ts'), dir], { cwd: dir, env: noRepoEnv(dir), stdout: 'pipe', stderr: 'pipe' });
       expect(run().exitCode).toBe(2);
       const { union } = readBeltSheets();
       // `truncate` is a core utility in every build of the union.
@@ -218,7 +229,7 @@ describe('🔴 the ORDER check — a base utility after a variant that sets the
       mkdirSync(join(dir, 'assets'));
       writeFileSync(join(dir, 'assets', 'index.js'), 'const c="truncate";');
       writeFileSync(join(dir, 'assets', 'index.css'), '@layer utilities{@media(min-width:40rem){.sm\\:flex{display:flex}}.truncate{overflow:hidden}.hidden{display:none}}');
-      const r = Bun.spawnSync(['bun', join(import.meta.dir, 'checkAreaStyles.ts'), dir], { stdout: 'pipe', stderr: 'pipe' });
+      const r = Bun.spawnSync(['bun', join(import.meta.dir, 'checkAreaStyles.ts'), dir], { cwd: dir, env: noRepoEnv(dir), stdout: 'pipe', stderr: 'pipe' });
       expect(r.exitCode).toBe(1);
       expect(r.stderr.toString()).toContain('.hidden (later) overrides .sm:flex');
     } finally {
@@ -226,3 +237,179 @@ describe('🔴 the ORDER check — a base utility after a variant that sets the
     }
   });
 });
+
+describe('🔴 the THEME VARIABLE check — a `var()` of a theme variable no built stylesheet declares (5.3.0)', () => {
+  // station's DataTable frozen column and DropIndicator, verbatim in shape from its minified bundle.
+  const STATION_JS =
+    'style:Je?{"--cb-frozen-bg":ke%2===1?"color-mix(in srgb, var(--color-muted) 50%, var(--color-card))":"var(--color-card)"}:void 0,' +
+    'function ni({orientation:e,side:t,color:r}){const n=r??"var(--color-accent)"}';
+  const APP = '@import "tailwindcss" source(none);\n@import "./styles-static.css";\n';
+  const THEME_READ_BLOCK = /\n\/\*\n \* Theme variables cursedbelt's components read BY NAME[\s\S]*$/;
+
+  test("station's pre-fix shape — core WITHOUT the theme-read block — is RED on exactly the three it lost", async () => {
+    const core = readBeltSheets().areas.core ?? '';
+    expect(core).toMatch(THEME_READ_BLOCK); // the block exists, so stripping it below is the 5.2.0 core
+    const preFix = (await compileStylesheet(`${APP}${core.replace(THEME_READ_BLOCK, '\n')}\n@import "./theme.css";\n`)).build([]);
+    expect(undefinedThemeVariables({ js: [STATION_JS], css: [preFix] }, readThemeVariables())).toEqual([
+      '--color-accent',
+      '--color-card',
+      '--color-muted',
+    ]);
+  });
+
+  test('the fix: the shipped core makes the app\'s ONE pass declare every theme variable a component reads by name', async () => {
+    const fixed = (await compileStylesheet(`${APP}@import "./styles-areas/core.css";\n@import "./theme.css";\n`)).build([]);
+    expect(undefinedThemeVariables({ js: [STATION_JS], css: [fixed] }, readThemeVariables())).toEqual([]);
+    // …and what core names is what the check scopes to — every one a theme variable.
+    const block = THEME_READ_BLOCK.exec(readBeltSheets().areas.core ?? '')?.[0] ?? '';
+    const named = [...block.matchAll(/var\((--[\w-]+)\)/g)].map((m) => m[1]);
+    const theme = readThemeVariables();
+    expect(named.filter((n) => !theme.has(n as string))).toEqual([]);
+    for (const v of ['--color-card', '--color-muted', '--color-accent', '--text-caption']) expect(named).toContain(v);
+  });
+
+  test('scope: a runtime-set or plain custom property is not a theme variable, and a fallback does not excuse one', () => {
+    const theme = new Set(['--color-card']);
+    const js = ['"var(--offset-right)" "var(--radix-popper-available-height)" "var(--color-card, white)"'];
+    expect(undefinedThemeVariables({ js, css: [''] }, theme)).toEqual(['--color-card']);
+    expect(undefinedThemeVariables({ js, css: [':root{--color-card:var(--card)}'] }, theme)).toEqual([]);
+  });
+
+  test('themeVariablesIn reads every @theme form and skips Tailwind\'s `initial` (unset) keys', () => {
+    const css =
+      '@theme inline { --color-card: var(--card); }\n@theme default { --text-sm: .875rem; ' +
+      '--default-font-feature-settings: --theme(--font-sans--font-feature-settings, initial); --x: initial; }\n:root { --card: #fff; }';
+    expect([...themeVariablesIn(css)].sort()).toEqual(['--color-card', '--text-sm']);
+    expect(readThemeVariables().has('--color-card')).toBe(true); // theme.css
+    expect(readThemeVariables().has('--ease-out')).toBe(true); // tailwindcss/theme.css, resolved
+    expect([...variablesDeclared('@property --tw-x{syntax:"*"}.a{--b:1;color:var(--c)}')].sort()).toEqual(['--b', '--tw-x']);
+  });
+
+  test('the CLI exits 1 on a build that reads an undeclared theme variable, naming it', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'belt-theme-var-check-'));
+    try {
+      mkdirSync(join(dir, 'assets'));
+      writeFileSync(join(dir, 'assets', 'index.js'), `const c="truncate";${STATION_JS}`);
+      writeFileSync(join(dir, 'assets', 'index.css'), '@layer theme{:root{--color-muted:var(--muted);--color-accent:var(--accent)}}@layer utilities{.truncate{overflow:hidden}}');
+      const r = Bun.spawnSync(['bun', join(import.meta.dir, 'checkAreaStyles.ts'), dir], { cwd: dir, env: noRepoEnv(dir), stdout: 'pipe', stderr: 'pipe' });
+      expect(r.exitCode).toBe(1);
+      expect(r.stderr.toString()).toContain('--color-card');
+      expect(r.stderr.toString()).not.toContain('--color-muted');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe('🔴 the SCAN-LEAK check — a scanned file ignored only by the global gitignore (5.3.1, family 0a298a5)', () => {
+  /** A git repo whose "machine-global" excludes file is a temp file — the real ~/.gitignore_global is never read. */
+  function fixture() {
+    const base = mkdtempSync(join(tmpdir(), 'belt-scan-leak-'));
+    const repo = join(base, 'app');
+    mkdirSync(repo);
+    const globalIgnore = join(base, 'gitignore_global');
+    writeFileSync(globalIgnore, '.DS_Store\n.agent.noindex/\n*.agent.*\nnode_modules\n');
+    const gitconfig = join(base, 'gitconfig');
+    writeFileSync(gitconfig, `[core]\n\texcludesFile = ${globalIgnore}\n`);
+    const env = { ...process.env, GIT_CONFIG_GLOBAL: gitconfig, GIT_CONFIG_NOSYSTEM: '1' };
+    expect(Bun.spawnSync(['git', 'init', '-q', repo], { env }).exitCode).toBe(0);
+    writeFileSync(join(repo, '.gitignore'), 'dist/\n');
+    mkdirSync(join(repo, 'src'));
+    writeFileSync(join(repo, 'src', 'App.tsx'), 'export const A = () => <div className="flex" />;');
+    // The scratch that made family's "core only" build look complete.
+    mkdirSync(join(repo, '.agent.noindex'));
+    writeFileSync(join(repo, '.agent.noindex', 'compare-styles.agent.ts'), 'const c = "truncate rounded-full grid-cols-3";');
+    writeFileSync(join(repo, 'src', 'probe.agent.tsx'), '<p className="sr-only" />');
+    // Globally ignored but nothing an extractor reads: binary, and inside node_modules.
+    writeFileSync(join(repo, '.DS_Store'), Buffer.from([0, 0, 0, 1, 66, 117, 100, 49, 0]));
+    mkdirSync(join(repo, 'node_modules', 'x'), { recursive: true });
+    writeFileSync(join(repo, 'node_modules', 'x', 'index.js'), 'const c = "flex";');
+    // Ignored by the repo itself — Tailwind skips it too.
+    mkdirSync(join(repo, 'dist'));
+    writeFileSync(join(repo, 'dist', 'index.js'), 'const c="truncate";');
+    return { base, repo, env, globalIgnore };
+  }
+
+  test('RED: each globally-ignored TEXT path is named with the file and pattern that matched', () => {
+    const { base, repo, env, globalIgnore } = fixture();
+    try {
+      const leaks = scanLeaks(repo, env);
+      expect(leaks?.map((l) => l.path)).toEqual(['.agent.noindex/', 'src/probe.agent.tsx']);
+      // `*.agent.*` (line 3) matches `.agent.noindex/` too, and the LAST match in a file decides.
+      expect(leaks?.[0]?.source).toBe(`${globalIgnore}:3`);
+      expect(leaks?.[0]?.textFiles).toBe(1);
+      expect(leaks?.[1]?.pattern).toBe('*.agent.*');
+      // From a SUBDIRECTORY root, only what is under it.
+      expect(scanLeaks(join(repo, 'src'), env)?.map((l) => l.path)).toEqual(['probe.agent.tsx']);
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test("GREEN once the repo's OWN .gitignore names them — the global file still matches, but no longer decides", () => {
+    const { base, repo, env } = fixture();
+    try {
+      writeFileSync(join(repo, '.gitignore'), 'dist/\n.agent.noindex/\n*.agent.*\n');
+      expect(scanLeaks(repo, env)).toEqual([]);
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test('.git/info/exclude is not the repo\'s .gitignore either — RED', () => {
+    const { base, repo, env } = fixture();
+    try {
+      writeFileSync(join(repo, '.gitignore'), 'dist/\n.agent.noindex/\n*.agent.*\n');
+      writeFileSync(join(repo, 'notes.md'), 'bg-primary');
+      writeFileSync(join(repo, '.git', 'info', 'exclude'), 'notes.md\n');
+      expect(scanLeaks(repo, env)?.map((l) => [l.path, l.source])).toEqual([['notes.md', '.git/info/exclude:1']]);
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test('an app root that is itself git-ignored cannot be measured — it throws (the CLI exits 2)', () => {
+    const { base, repo, env } = fixture();
+    try {
+      expect(() => scanLeaks(join(repo, '.agent.noindex'), env)).toThrow(/itself git-ignored/);
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
+  test('outside any git work tree there is nothing to disagree about — null, not []', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'belt-scan-leak-nogit-'));
+    try {
+      expect(scanLeaks(dir, noRepoEnv(dir))).toBeNull();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test('the CLI exits 1 on a leak even when every class is styled, and 0 once the repo ignores it', () => {
+    const { base, repo, env } = fixture();
+    try {
+      writeFileSync(join(repo, 'dist', 'index.css'), '.truncate{overflow:hidden}');
+      const run = () =>
+        Bun.spawnSync(['bun', join(import.meta.dir, 'checkAreaStyles.ts'), 'dist'], { cwd: repo, env, stdout: 'pipe', stderr: 'pipe' });
+      const red = run();
+      expect(red.exitCode).toBe(1);
+      expect(red.stderr.toString()).toContain('.agent.noindex/');
+      expect(red.stderr.toString()).toContain('src/probe.agent.tsx');
+      // --root reads the same repo from anywhere.
+      const elsewhere = Bun.spawnSync(['bun', join(import.meta.dir, 'checkAreaStyles.ts'), join(repo, 'dist'), '--root', repo], {
+        cwd: base,
+        env,
+        stdout: 'pipe',
+        stderr: 'pipe',
+      });
+      expect(elsewhere.exitCode).toBe(1);
+      writeFileSync(join(repo, '.gitignore'), 'dist/\n.agent.noindex/\n*.agent.*\n');
+      const green = run();
+      expect(green.stderr.toString()).toBe('');
+      expect(green.exitCode).toBe(0);
+    } finally {
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+});

package/scripts/checkAreaStyles.ts

@@ -29,13 +29,33 @@
  * {@link cascadeFaults}: a base utility after a variant that sets the same property is two sorted
  * Tailwind passes concatenated, and the base wins at every width. Both halves exit 1.
  *
- * Usage, from an app, after its build:
- *   bun node_modules/cursedbelt/scripts/checkAreaStyles.ts dist
- * Exit 0 = complete, 1 = a class is unstyled (listed with its area), 2 = could not measure
+ * ── …and whether every THEME variable the build reads is defined (5.3.0) ────────────────
+ * {@link undefinedThemeVariables}: a `var(--color-card)` in the built JS or CSS whose `--color-card`
+ * no built stylesheet declares. Tailwind prunes theme variables nothing in its pass names, and a
+ * component that reads one by name from a style prop is invisible to the class check above — the
+ * hole station's frozen DataTable column fell through (F4, 2026-09-23). Exit 1 as well.
+ *
+ * ── …and whether the build could have SEEN files the repo does not own (5.3.1) ───────────
+ * {@link scanLeaks}: Tailwind v4's automatic source detection honours the repo's OWN `.gitignore`
+ * files but NOT the machine-global `core.excludesFile`. So agent scratch — `.agent.noindex/`,
+ * `*.agent.*`, ignored only globally — is scanned, adds its classes to the build, and every check
+ * above passes on a stylesheet a clean checkout cannot reproduce. Measured in apps/family
+ * (0a298a5, 2026-09-23): its first "core only" adoption was green, and a clean build was 65
+ * cursedbelt classes short. Any text file under the app root that git ignores through something
+ * other than a repo `.gitignore` (`git check-ignore -v` names the file that matched) is exit 1;
+ * the fix is the line in the repo's own `.gitignore`, which Tailwind does read.
+ *
+ * Usage, from an app ROOT (the directory Tailwind scans), after its build:
+ *   bun node_modules/cursedbelt/scripts/checkAreaStyles.ts dist [--root <app root, default cwd>]
+ * Exit 0 = complete, 1 = a class is unstyled (listed with its area), a base utility follows a
+ * variant, a theme variable read is declared nowhere, or a scanned file is ignored only
+ * outside the repo's own `.gitignore`; 2 = could not measure
  * (no JS or no CSS under the directory — a check that measured nothing has not passed).
  */
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
-import { basename, dirname, join, resolve } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { closeSync, existsSync, lstatSync, openSync, readdirSync, readFileSync, readSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -271,6 +291,180 @@ export function cascadeFaults(cssTexts: readonly string[]): CascadeFault[] {
   return faults;
 }
 
+// ── the THEME VARIABLE check (5.3.0) ───────────────────────────────────────────────────
+
+/**
+ * Every custom property an `@theme` block declares (any `@theme inline`/`static`/… form). These — and
+ * only these — are what Tailwind PRUNES: it emits a theme variable into `:root` only when its pass
+ * sees it used. Every other custom property is written down by a stylesheet unconditionally or set
+ * at runtime (`--radix-*`, sonner's `--offset`, a component's `--cb-frozen-bg`), and an area split
+ * cannot lose it — which is why the check is scoped here and needs no allowlist.
+ */
+export function themeVariablesIn(css: string): Set<string> {
+  const out = new Set<string>();
+  const code = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  for (const m of code.matchAll(/@theme\b[^{]*\{/g)) {
+    let depth = 1;
+    let i = (m.index ?? 0) + m[0].length;
+    const start = i;
+    for (; i < code.length && depth > 0; i++) {
+      if (code[i] === '{') depth++;
+      else if (code[i] === '}') depth--;
+    }
+    for (const d of code.slice(start, i).matchAll(/(?:^|[;{\s])(--[\w-]+)\s*:\s*([^;}]*)/g)) {
+      // `initial` is Tailwind's "unset" — `--default-font-feature-settings: --theme(--font-sans--…, initial)`
+      // is declared only when the app sets the key it names, and preflight reads it with a fallback.
+      // Measured on station's union build: the four `--default-*-settings` were the only noise.
+      if (/^(?:initial|--theme\([^)]*,\s*initial\))$/.test((d[2] as string).trim())) continue;
+      out.add(d[1] as string);
+    }
+  }
+  return out;
+}
+
+/** Every custom property a stylesheet DECLARES: `--x:` in any block, or `@property --x`. */
+export function variablesDeclared(css: string): Set<string> {
+  const out = new Set<string>();
+  const code = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  for (const m of code.matchAll(/(?:^|[;{\s])(--[\w-]+)\s*:/g)) out.add(m[1] as string);
+  for (const m of code.matchAll(/@property\s+(--[\w-]+)/g)) out.add(m[1] as string);
+  return out;
+}
+
+/** Every `var(--x…)` a text reads — a JS bundle's style strings or a stylesheet's values. */
+export function variablesReferenced(text: string): Set<string> {
+  return new Set([...text.matchAll(/var\(\s*(--[\w-]+)/g)].map((m) => m[1] as string));
+}
+
+/**
+ * 🔴 The THEME variables the built JS or CSS reads with `var()` that no built stylesheet declares.
+ * Each one is a value that silently resolves to nothing — `var(--color-card)` as a background is
+ * transparent, not an error. A fallback (`var(--x, red)`) does not excuse one: it renders, but not
+ * as the theme says, which is the same divergence from the union.
+ */
+export function undefinedThemeVariables(input: { js: string[]; css: string[] }, theme: ReadonlySet<string>): string[] {
+  const declared = new Set<string>();
+  for (const css of input.css) for (const name of variablesDeclared(css)) declared.add(name);
+  const read = new Set<string>();
+  for (const text of [...input.js, ...input.css]) for (const name of variablesReferenced(text)) read.add(name);
+  return [...read].filter((name) => theme.has(name) && !declared.has(name)).sort();
+}
+
+/**
+ * The theme a cursedbelt consumer compiles against: this package's `theme.css` and
+ * `styles-static.css`, and Tailwind's own `theme.css` (resolved from this package, which in an app
+ * is the app's copy). 🔴 Throws rather than shrinking the set when Tailwind cannot be found — a
+ * check over half the theme would pass on exactly the variables it cannot see.
+ */
+export function readThemeVariables(src: string | undefined = SRC): Set<string> {
+  if (!src) throw new Error("cursedbelt's src/ is not beside this script — the package is incomplete");
+  const tailwindTheme = createRequire(join(src, '..', 'package.json')).resolve('tailwindcss/theme.css');
+  const out = new Set<string>();
+  for (const file of [join(src, 'theme.css'), join(src, 'styles-static.css'), tailwindTheme]) {
+    for (const name of themeVariablesIn(readFileSync(file, 'utf8'))) out.add(name);
+  }
+  return out;
+}
+
+// ── the SCAN-LEAK check (5.3.1) ───────────────────────────────────────────────────────
+
+export interface ScanLeak {
+  /** The ignored path, relative to the app root (`.agent.noindex/`, `notes.agent.md`). */
+  path: string;
+  /** The ignore file that matched — never a repo `.gitignore` — and its line and pattern. */
+  source: string;
+  pattern: string;
+  /** How many TEXT files it holds (what Tailwind's extractor reads). */
+  textFiles: number;
+}
+
+/** Tailwind never scans these; a leak inside them cannot reach the build. */
+const NEVER_SCANNED = new Set(['node_modules', '.git']);
+
+/** Text = no NUL byte in the first 8 KB — the test git and Tailwind's extractor both effectively apply. */
+function isTextFile(file: string): boolean {
+  const fd = openSync(file, 'r');
+  try {
+    const buf = Buffer.alloc(8192);
+    const n = readSync(fd, buf, 0, buf.length, 0);
+    return !buf.subarray(0, n).includes(0);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Text files at or under `path`, not following symlinks, skipping node_modules/.git; stops counting at `cap`. */
+function countTextFiles(path: string, cap = 1000): number {
+  let st: ReturnType<typeof lstatSync>;
+  try {
+    st = lstatSync(path);
+  } catch {
+    return 0;
+  }
+  if (st.isSymbolicLink()) return 0;
+  if (st.isFile()) return st.size > 0 && isTextFile(path) ? 1 : 0;
+  if (!st.isDirectory()) return 0;
+  let n = 0;
+  for (const entry of readdirSync(path)) {
+    if (NEVER_SCANNED.has(entry)) continue;
+    n += countTextFiles(join(path, entry), cap - n);
+    if (n >= cap) break;
+  }
+  return n;
+}
+
+function git(root: string, args: string[], env: NodeJS.ProcessEnv | undefined, input?: string) {
+  return spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', input, env: env ?? process.env, maxBuffer: 64 * 1024 * 1024 });
+}
+
+/**
+ * 🔴 Every path under `root` that exists, would be scanned (a text file, or a directory holding
+ * one, outside node_modules/.git), and is ignored by git ONLY through something that is not one of
+ * the repo's own `.gitignore` files — `core.excludesFile` (the machine-global one) or
+ * `.git/info/exclude`. Tailwind v4 reads neither, so each is a source of classes a clean checkout
+ * does not have. `git check-ignore -v` reports the DECIDING pattern, and a repo `.gitignore` outranks
+ * both, so a path the repo ignores itself is never reported however the global file also matches.
+ *
+ * Returns `null` when `root` is not inside a git work tree: then no gitignore of any kind applies, to
+ * git or to Tailwind, and there is nothing for the two to disagree about. `env` is for tests (a
+ * hermetic `GIT_CONFIG_GLOBAL`).
+ */
+export function scanLeaks(root: string, env?: NodeJS.ProcessEnv): ScanLeak[] | null {
+  const top = git(root, ['rev-parse', '--show-toplevel'], env);
+  if (top.status !== 0) return null;
+  const topLevel = top.stdout.trim();
+  const rootRel = relative(topLevel, resolve(root));
+  if (rootRel && git(root, ['check-ignore', '-q', '--', `${resolve(root)}/`], env).status === 0) {
+    // git cannot list "the ignored files under an ignored directory", and which of them Tailwind reads
+    // is then a question about ITS walker. An app root is never inside an ignored directory; refuse.
+    throw new Error(`${root} is itself git-ignored in ${topLevel} — run from the app's root`);
+  }
+  const listed = git(root, ['ls-files', '--others', '--ignored', '--exclude-standard', '--directory', '-z', '--', '.'], env);
+  if (listed.status !== 0) throw new Error(`git ls-files failed in ${root}: ${listed.stderr.trim()}`);
+  const paths = listed.stdout
+    .split('\0')
+    .filter((p) => p.length > 0)
+    .filter((p) => !p.split('/').some((seg) => NEVER_SCANNED.has(seg)));
+  if (paths.length === 0) return [];
+  const matched = git(root, ['check-ignore', '-v', '-z', '--stdin'], env, `${paths.join('\0')}\0`);
+  // Exit 1 = none of them ignored (cannot happen for ls-files -i output, but is not an error).
+  if (matched.status !== 0 && matched.status !== 1) throw new Error(`git check-ignore failed in ${root}: ${matched.stderr.trim()}`);
+  const fields = matched.stdout.split('\0');
+  const leaks: ScanLeak[] = [];
+  for (let i = 0; i + 3 < fields.length; i += 4) {
+    const [source, line, pattern, path] = fields.slice(i, i + 4) as [string, string, string, string];
+    if (!source) continue;
+    const abs = isAbsolute(source) ? source : resolve(root, source);
+    const inRepo = !relative(topLevel, abs).startsWith('..') && !isAbsolute(relative(topLevel, abs));
+    const inGitDir = relative(topLevel, abs).split(sep)[0] === '.git';
+    if (basename(abs) === '.gitignore' && inRepo && !inGitDir) continue; // the repo's own — Tailwind reads it
+    const textFiles = countTextFiles(join(root, path));
+    if (textFiles === 0) continue; // .DS_Store, a screenshot: nothing an extractor could read
+    leaks.push({ path, source: `${source}:${line}`, pattern, textFiles });
+  }
+  return leaks.sort((a, b) => a.path.localeCompare(b.path));
+}
+
 function filesUnder(dir: string, ext: string, out: string[] = []): string[] {
   for (const entry of readdirSync(dir)) {
     if (entry === 'node_modules') continue;
@@ -290,13 +484,15 @@ export interface AreaCheckResult {
   referenced: number;
   /** {@link cascadeFaults} over the built CSS — base utilities that override a variant. */
   outOfOrder: CascadeFault[];
+  /** {@link undefinedThemeVariables} — theme variables read by `var()` and declared by no built CSS. */
+  undefinedVariables: string[];
 }
 
 /** The measurement, over explicit texts — what the spec drives. */
 export function checkAreaStyles(
   input: { js: string[]; css: string[] },
   belt: { union: string; areas: Record<string, string> },
-): Omit<AreaCheckResult, 'jsFiles' | 'cssFiles' | 'outOfOrder'> {
+): Omit<AreaCheckResult, 'jsFiles' | 'cssFiles' | 'outOfOrder' | 'undefinedVariables'> {
   const union = classesInCss(belt.union);
   const areaOf = new Map<string, string>();
   for (const [area, css] of Object.entries(belt.areas)) {
@@ -332,11 +528,22 @@ export function checkDist(distDir: string): AreaCheckResult {
     readBeltSheets(),
   );
   const cssTexts = cssFiles.map((f) => readFileSync(f, 'utf8'));
-  return { ...result, outOfOrder: cascadeFaults(cssTexts), jsFiles: jsFiles.length, cssFiles: cssFiles.length };
+  const jsTexts = jsFiles.map((f) => readFileSync(f, 'utf8'));
+  return {
+    ...result,
+    outOfOrder: cascadeFaults(cssTexts),
+    undefinedVariables: undefinedThemeVariables({ js: jsTexts, css: cssTexts }, readThemeVariables()),
+    jsFiles: jsFiles.length,
+    cssFiles: cssFiles.length,
+  };
 }
 
 if (import.meta.main) {
-  const dir = resolve(process.argv[2] ?? 'dist');
+  const args = process.argv.slice(2);
+  const rootAt = args.indexOf('--root');
+  const root = resolve(rootAt >= 0 ? (args[rootAt + 1] ?? '.') : '.');
+  if (rootAt >= 0) args.splice(rootAt, 2);
+  const dir = resolve(args[0] ?? 'dist');
   if (!existsSync(dir)) {
     console.error(`✗ ${dir} does not exist — build the app first. A check that measured nothing has not passed.`);
     process.exit(2);
@@ -346,6 +553,22 @@ if (import.meta.main) {
     console.error(`✗ ${dir} holds ${result.jsFiles} .js and ${result.cssFiles} .css file(s) — nothing to compare.`);
     process.exit(2);
   }
+  let leaks: ScanLeak[];
+  try {
+    leaks = scanLeaks(root) ?? [];
+  } catch (e) {
+    console.error(`✗ could not tell which files Tailwind scanned: ${(e as Error).message}`);
+    process.exit(2);
+  }
+  if (leaks.length > 0) {
+    console.error(
+      `✗ ${leaks.length} path(s) under ${root} are ignored by git only OUTSIDE the repo's own .gitignore — Tailwind v4 scans them anyway,`,
+    );
+    console.error('  so their classes are in this build and a clean checkout\'s build would be short of them (apps/family 0a298a5: 65 classes):');
+    for (const l of leaks.slice(0, 12)) console.error(`    ${l.path}  (${l.textFiles} text file(s); ${l.source} \`${l.pattern}\`)`);
+    if (leaks.length > 12) console.error(`    … +${leaks.length - 12} more`);
+    console.error("  Add each pattern to the repo's own .gitignore (e.g. `.agent.noindex/` and `*.agent.*`), rebuild, and check again.");
+  }
   if (result.outOfOrder.length > 0) {
     console.error(`✗ ${result.outOfOrder.length} base utilit(y|ies) come AFTER a variant that sets the same property, so the base wins at every width:`);
     for (const f of result.outOfOrder.slice(0, 12)) console.error(`    .${f.base} (later) overrides .${f.variant}  — ${f.properties.join(', ')}`);
@@ -353,11 +576,21 @@ if (import.meta.main) {
     console.error('  Two sorted Tailwind passes were concatenated — cursedbelt ≤ 5.0.x precompiled areas after the app\'s own.');
     console.error('  cursedbelt ≥ 5.1.0 areas are candidates for the app\'s ONE pass: upgrade, and rebuild.');
   }
+  if (result.undefinedVariables.length > 0) {
+    console.error(
+      `✗ ${result.undefinedVariables.length} theme variable(s) the build reads with var() are declared by NO built stylesheet — ` +
+        'each resolves to nothing (a transparent background, an unset size):',
+    );
+    console.error(`    ${result.undefinedVariables.join(' ')}`);
+    console.error('  Tailwind emits a theme variable only when its pass sees it used. cursedbelt ≥ 5.3.0 names every one its');
+    console.error('  components read in styles-areas/core.css — import core, on ≥ 5.3.0. A variable of the app\'s own: name it');
+    console.error('  in a file the app\'s Tailwind pass scans.');
+  }
   if (result.missing.length === 0) {
-    if (result.outOfOrder.length > 0) process.exit(1);
+    if (result.outOfOrder.length > 0 || result.undefinedVariables.length > 0 || leaks.length > 0) process.exit(1);
     console.log(
       `✓ belt area styles complete: all ${result.referenced} cursedbelt classes the build references are styled, ` +
-        `and no base utility follows a variant (${result.jsFiles} js, ${result.cssFiles} css).`,
+        `no base utility follows a variant, every theme variable read is declared, and nothing scanned is ignored only globally (${result.jsFiles} js, ${result.cssFiles} css).`,
     );
     process.exit(0);
   }

package/scripts/generateAreaStyles.ts

@@ -84,7 +84,7 @@
  */
 import { REPO_ROOT, STATIC_STYLESHEET, readStylesheets } from './generateStaticStyles';
 import { classesInCss } from './checkAreaStyles';
-import { UTILITY_INPUT, compileStylesheet } from './generateUtilityStyles';
+import { UTILITY_INPUT, compileStylesheet, themeReadBlock, themeVariablesReadByName } from './generateUtilityStyles';
 import {
 	AREA_DIR,
 	AREAS,
@@ -195,7 +195,7 @@ export const inlineCandidates = async (candidates: readonly string[], area: stri
 	// Tailwind escapes a selector the CSS.escape way; a candidate whose escaped form is in the
 	// output is kept even when unescaping would not round-trip it (a `…` from a doc comment did not).
 	// A `--token` candidate is a THEME VARIABLE the modules read (\`var(--text-sm)\` in a style
-	// prop): Tailwind emits it into \`:root\` only because the scan saw it, so it stays too.
+	// prop). It is kept for the proof below, then dropped from what is written — see the return.
 	const kept = writable.filter(
 		(c) => emitted.has(c) || full.includes(`.${cssEscape(c)}`) || (/^--[\w-]+$/.test(c) && full.includes(`${c}:`)),
 	);
@@ -207,7 +207,11 @@ export const inlineCandidates = async (candidates: readonly string[], area: stri
 				'widen the filter rather than lose it.',
 		);
 	}
-	return kept;
+	// …but a `--token` is not WRITTEN: `@source inline` cannot mark a theme variable (tailwindcss
+	// 4.3.3 adds inline candidates without the `--` branch scanned ones take — measured), so one
+	// here would claim a variable the app never gets. `core` carries every one of them instead,
+	// as a `var()` the app's pass does see (`themeReadBlock`, 5.3.0).
+	return kept.filter((c) => !/^--[\w-]+$/.test(c));
 };
 
 /** `CSS.escape` for a class name — what Tailwind writes into a selector. */
@@ -291,6 +295,10 @@ export const buildAreaStyles = async (): Promise<BuiltArea[]> => {
 		raw.set(area.name, await candidatesIn(closures.get(area.name) as Set<string>));
 	}
 
+	// 🔴 The theme variables components read BY NAME go in core, whole: an area is candidates, and
+	// no candidate can make the app's pass emit one (`themeVariablesReadByName` has the measurement).
+	const themeRead = themeReadBlock(await themeVariablesReadByName());
+
 	const built: BuiltArea[] = [];
 	for (const area of AREAS) {
 		const closure = closures.get(area.name) as Set<string>;
@@ -311,7 +319,7 @@ export const buildAreaStyles = async (): Promise<BuiltArea[]> => {
 		}
 		built.push({
 			name: area.name,
-			css: `${banner(area, inline.length, area.name !== CORE)}${inlineSource(inline)}`,
+			css: `${banner(area, inline.length, area.name !== CORE)}${inlineSource(inline)}${area.name === CORE ? themeRead : ''}`,
 			candidates: inline,
 			modules: [...closure].map((f) => f.replace(`${REPO_ROOT}/`, '')).sort(),
 		});

package/scripts/generateUtilityStyles.ts

@@ -58,6 +58,7 @@
 import { compile } from '@tailwindcss/node';
 import { Scanner } from '@tailwindcss/oxide';
 import { REPO_ROOT, STATIC_STYLESHEET, readStylesheets } from './generateStaticStyles';
+import { allModules, candidatesIn, nonModuleFiles } from './styleAreas';
 
 export { REPO_ROOT };
 
@@ -124,6 +125,78 @@ export const compileStylesheet = (
 	input: string,
 ): ReturnType<typeof compile> => compile(input, { base: STYLES_BASE, onDependency: noDependency });
 
+// ── Theme variables the components read BY NAME (5.3.0) ─────────────────────────────────
+
+/**
+ * The custom property whose value names every theme variable {@link themeVariablesReadByName}
+ * returns. Nothing reads it; it exists so the app's Tailwind pass sees a `var()` of each.
+ */
+export const THEME_READ_PROPERTY = '--cb-theme-read-by-name';
+
+/** Every theme a consumer imports, and nothing scanned — what decides "Tailwind would prune this". */
+const THEME_PROBE_INPUT = '@import "tailwindcss" source(none);\n@import "./styles-static.css";\n@import "./theme.css";\n';
+
+/** A collapse tripwire, not a ratchet: 9 on the day it was set (tailwindcss 4.3.3). */
+export const MIN_THEME_READ_BY_NAME = 4;
+
+const declaresVariable = (css: string, name: string): boolean =>
+	new RegExp(`(^|[\\s;{])${name.replace(/[-]/g, '\\-')}\\s*:`).test(css);
+
+/**
+ * 🔴 The THEME variables cursedbelt's components read by NAME, which Tailwind emits only when
+ * something in the app's own pass names them.
+ *
+ * `DataTable` sets `--cb-frozen-bg` inline to `var(--color-card)`, `DropIndicator` paints with
+ * `var(--color-accent)`, `focusViewer.css` sizes a caption with `var(--text-caption)`. Tailwind v4
+ * emits a theme variable into `:root` only when it is USED — by a utility, by a `var()` in CSS it
+ * compiles, or by a `--name` token its scanner finds in a source file. The union route scans this
+ * package's tree, so it sees the names; an area is class candidates, so an app on the areas had
+ * NO `--color-card` and station's frozen DataTable column went transparent (F4, 2026-09-23,
+ * `reports/2026-09-23/2026-09-23-f4-station-desk-flix-final-adoption.md`).
+ *
+ * `@source inline("--color-card")` does NOT fix it — measured on tailwindcss 4.3.3: inline
+ * candidates skip the `--` branch the scanner's candidates take, so they mark nothing. A `var()`
+ * in CSS the app's pass compiles does, so {@link themeReadBlock} writes one.
+ *
+ * DERIVED, never listed: every `--token` the scanner finds in a module or hand-written `.css` under
+ * `src/react` that a theme-only compile emits when named and omits when not. A new
+ * `var(--color-ring)` in a component joins the list at the next `bun run build`;
+ * `scripts/checkAreaStyles.ts` is what fails an app build when one is still missing anyway.
+ */
+export const themeVariablesReadByName = async (): Promise<string[]> => {
+	const files = [...allModules(), ...nonModuleFiles().filter((f) => f.endsWith('.css'))];
+	const named = [...(await candidatesIn(files))].filter((c) => /^--[\w-]+$/.test(c)).sort();
+	const bare = (await compileStylesheet(THEME_PROBE_INPUT)).build([]);
+	const marked = (await compileStylesheet(THEME_PROBE_INPUT)).build(named);
+	const pruned = named.filter((v) => declaresVariable(marked, v) && !declaresVariable(bare, v));
+	if (pruned.length < MIN_THEME_READ_BY_NAME) {
+		throw new Error(
+			`only ${pruned.length} theme variable(s) read by name were found (floor ${MIN_THEME_READ_BY_NAME}) — ` +
+				`a collapsed scan of ${files.length} file(s), not a design system that stopped reading them.`,
+		);
+	}
+	return pruned;
+};
+
+/**
+ * The declaration that makes an app's Tailwind pass emit `vars`: one custom property on `:root`
+ * whose value `var()`s each of them. The VALUES stay the theme's, so an app that re-themes a
+ * variable keeps its own; this names them and defines nothing.
+ */
+export const themeReadBlock = (vars: readonly string[]): string => `
+/*
+ * Theme variables cursedbelt's components read BY NAME (\`var(--color-card)\` in a style prop).
+ * Tailwind emits a theme variable only when the app's own pass sees it used, and a \`var()\` here is
+ * that use — \`@source inline\` cannot mark one. ${vars.length} variable(s), derived by
+ * scripts/generateUtilityStyles.ts → themeVariablesReadByName(). Nothing reads this property.
+ */
+@layer theme {
+  :root, :host {
+    ${THEME_READ_PROPERTY}: ${vars.map((v) => `var(${v})`).join(' ')};
+  }
+}
+`;
+
 /** 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.
@@ -177,7 +250,9 @@ export const buildUtilityStyles = async (): Promise<{ css: string; candidates: s
 				`${STYLES_BASE}/react exists and is not excluded by a .gitignore.`,
 		);
 	}
-	return { css: `${BANNER}${compiled.build(candidates)}`, candidates };
+	// The theme variables components read by name ride along: the pair's consumer scans nothing
+	// of this package either, so it has the areas' hole exactly (see themeVariablesReadByName).
+	return { css: `${BANNER}${compiled.build(candidates)}${themeReadBlock(await themeVariablesReadByName())}`, candidates };
 };
 
 /** The artifact's expected contents and what is on disk right now. */

package/src/react/media/hlsSource.spec.ts

@@ -58,8 +58,11 @@ describe('attachHlsSource — every road ends at something playable', () => {
     // master it cannot parse is a permanent spinner, which is worse than the slow copy.
     const el = videoEl(false);
     const detach = attachHlsSource(el, { hlsUrl: LADDER, streamUrl: REMUX });
-    await Promise.resolve();
-    await new Promise((r) => setTimeout(r, 0));
+    // Poll, not one tick: the fallback lands after the dynamic `import('hls.js')` settles, and on a
+    // cold module cache (publish's `gate --force`, 2026-09-23) that took longer than one macrotask.
+    for (const deadline = Date.now() + 5000; el.src === '' && Date.now() < deadline; ) {
+      await new Promise((r) => setTimeout(r, 5));
+    }
     expect(el.src).toBe(REMUX);
     detach();
   });

package/src/styles-areas/core.css

@@ -144,3 +144,15 @@
 @source inline("w-[var(--control-h-lg)] w-[var(--control-h-md)] w-[var(--control-h-sm)] w-auto w-full w-px white");
 @source inline("whitespace-nowrap whitespace-pre-wrap wrap wrap-break-word z z-10 z-20 z-30 z-40 z-50");
 @source inline("z-[var(--z-popover)]");
+
+/*
+ * Theme variables cursedbelt's components read BY NAME (`var(--color-card)` in a style prop).
+ * Tailwind emits a theme variable only when the app's own pass sees it used, and a `var()` here is
+ * that use — `@source inline` cannot mark one. 9 variable(s), derived by
+ * scripts/generateUtilityStyles.ts → themeVariablesReadByName(). Nothing reads this property.
+ */
+@layer theme {
+  :root, :host {
+    --cb-theme-read-by-name: var(--color-accent) var(--color-border) var(--color-card) var(--color-muted) var(--color-popover) var(--duration-base) var(--ease-out) var(--text-caption) var(--text-sm);
+  }
+}

package/src/styles-areas/spreadsheet.css

@@ -18,10 +18,10 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 4 candidate(s).
+ * 2 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
  * import closures rather than a hand-written list, is scripts/styleAreas.ts.
  */
-@source inline("--font-sans --text-sm col collapse");
+@source inline("col collapse");

package/src/styles-areas/workbook-viewer.css

@@ -18,10 +18,10 @@
  * after an app's responsive variant (task 2124). An app that imports every area gets exactly
  * what `cursedbelt/styles-utilities.css` emits — proved rule by rule in
  * src/stylesAreas.spec.ts, which is also what fails when this file is stale.
- * 7 candidate(s).
+ * 5 candidate(s).
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are
  * import closures rather than a hand-written list, is scripts/styleAreas.ts.
  */
-@source inline("--font-sans --text-sm col collapse min-w-16 w w-48");
+@source inline("col collapse min-w-16 w w-48");

package/src/styles-utilities.css

@@ -4969,3 +4969,15 @@
     }
   }
 }
+
+/*
+ * Theme variables cursedbelt's components read BY NAME (`var(--color-card)` in a style prop).
+ * Tailwind emits a theme variable only when the app's own pass sees it used, and a `var()` here is
+ * that use — `@source inline` cannot mark one. 9 variable(s), derived by
+ * scripts/generateUtilityStyles.ts → themeVariablesReadByName(). Nothing reads this property.
+ */
+@layer theme {
+  :root, :host {
+    --cb-theme-read-by-name: var(--color-accent) var(--color-border) var(--color-card) var(--color-muted) var(--color-popover) var(--duration-base) var(--ease-out) var(--text-caption) var(--text-sm);
+  }
+}