cursedbelt 5.3.0 → 5.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "5.3.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,
@@ -12,6 +12,7 @@ import {
   onlyInMergeTables,
   readBeltSheets,
   readThemeVariables,
+  scanLeaks,
   themeVariablesIn,
   tokensInJs,
   undefinedThemeVariables,
@@ -19,6 +20,12 @@ import {
 } 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: {
@@ -86,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.
@@ -222,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 {
@@ -284,7 +291,7 @@ describe('🔴 the THEME VARIABLE check — a `var()` of a theme variable no bui
       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], { 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('--color-card');
       expect(r.stderr.toString()).not.toContain('--color-muted');
@@ -293,3 +300,116 @@ describe('🔴 the THEME VARIABLE check — a `var()` of a theme variable no bui
     }
   });
 });
+
+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

@@ -35,15 +35,27 @@
  * 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.
  *
- * Usage, from an app, after its build:
- *   bun node_modules/cursedbelt/scripts/checkAreaStyles.ts dist
+ * ── …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, or a theme variable read is declared nowhere; 2 = could not measure
+ * 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 { 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, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
@@ -354,6 +366,105 @@ export function readThemeVariables(src: string | undefined = SRC): Set<string> {
   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;
@@ -428,7 +539,11 @@ export function checkDist(distDir: string): AreaCheckResult {
 }
 
 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);
@@ -438,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(', ')}`);
@@ -456,10 +587,10 @@ if (import.meta.main) {
     console.error('  in a file the app\'s Tailwind pass scans.');
   }
   if (result.missing.length === 0) {
-    if (result.outOfOrder.length > 0 || result.undefinedVariables.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, ` +
-        `no base utility follows a variant, and every theme variable read is declared (${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/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();
   });