cursedbelt 5.1.0 → 5.3.0

package/dist/react/lib/directUpload.js

@@ -0,0 +1,228 @@
+/**
+ * `cursedbelt/react/upload-direct` — browser-side resumable upload, straight from the file input
+ * to binary-server.
+ *
+ * Lifted 2026-09-23 (cursedbelt 5.2.0, task 056-343's browser half) from `src/kit/directUpload.ts`,
+ * identical in collections and family. The server half — minting the session — is
+ * `cursedbelt-server/binary-store/upload-session`'s `createUploadSession`.
+ *
+ * 🔴 THIS FILE RUNS IN A BROWSER. It must never import `node:*`, `binaryStore.ts`, or
+ * anything that reaches a private key — see {@link UploadSession}. Keep it dependency-free.
+ *
+ * ## Why the bytes skip the app server
+ *
+ * Every satellite's upload route reads the whole body (`formData()` → `arrayBuffer()`) before
+ * handing it to binary-server, inside a unit capped at `MemoryMax=300M` on a shared t3.micro
+ * that also runs nginx and every other app. That is why the fleet's upload ceiling is 32 MB
+ * and why raising the number was never the fix: a 10 GB video does not fit in the process, in
+ * the nginx body limit, or in the Cloudflare Tunnel's ~100 MB request wall.
+ *
+ * So a large file does not go through the app server at all. The app server mints a session
+ * token naming exactly one destination key; the browser PUTs bounded parts directly to
+ * binary-server, which assembles them; the app server is told afterwards and records the
+ * metadata. No byte of video touches the EC2 box, which is the owner's standing rule for
+ * video (2026-08-12) and also the only shape that survives the memory limit.
+ *
+ * ## What makes it survive 10 GB
+ *
+ * - **Resume.** `GET /upload-chunk` reports which parts already landed, so an upload that
+ *   dies at 90% resumes instead of restarting. That answer comes from the parts on disk, so
+ *   it survives a binary-server restart too.
+ * - **Bounded concurrency.** A few parts in flight keeps a home upstream saturated without
+ *   putting the whole file in memory. Only one part's bytes are ever read at a time per slot.
+ * - **Per-part retry.** A dropped part costs one part, not the upload.
+ * - **Slicing, not reading.** `Blob.slice` is lazy — the 10 GB file is never materialized.
+ */
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Split `[0, total)` into `chunkBytes`-sized part indices. */
+export const chunkCount = (totalBytes, chunkBytes) => Math.max(1, Math.ceil(totalBytes / chunkBytes));
+const chunkUrl = (s, token, ci) => `${s.baseUrl}/upload-chunk/${s.path
+    .split("/")
+    .map(encodeURIComponent)
+    .join("/")}?token=${encodeURIComponent(token)}&ci=${ci}`;
+const statusUrl = (s, token) => `${s.baseUrl}/upload-chunk/${s.path
+    .split("/")
+    .map(encodeURIComponent)
+    .join("/")}?token=${encodeURIComponent(token)}`;
+/** Which parts binary-server already holds, plus whether the object is already complete.
+ *  A fresh session answers `{ received: [], complete: false }`, so callers need no special
+ *  case for "first attempt". */
+export async function fetchSessionState(session, token = session.token, signal) {
+    const res = await fetch(statusUrl(session, token), { signal });
+    if (!res.ok)
+        return {
+            received: new Set(),
+            complete: false,
+            size: null,
+            checksum: null,
+            freeBytes: null,
+        };
+    const body = (await res.json());
+    return {
+        received: new Set(body.received ?? []),
+        complete: Boolean(body.complete),
+        size: body.size ?? null,
+        checksum: body.checksum ?? null,
+        freeBytes: body.freeBytes ?? null,
+    };
+}
+/** Thrown when binary-server has no room for the file. Distinct from a transport failure so a
+ *  UI can say "the server is full" — which is actionable — rather than "upload failed", which
+ *  invites the person to retry forever against a disk that will never have space. */
+export class InsufficientStorageError extends Error {
+    needBytes;
+    freeBytes;
+    overridable;
+    constructor(needBytes, freeBytes, 
+    /**
+     * 🔴 Vestigial since 2026-08-13 and kept only so an older deployed binary-server can
+     * still be understood: THIS service no longer refuses an upload for disk space at all,
+     * so nothing here should be producing an overridable refusal any more. If you see one,
+     * the origin is running a build from before that change.
+     */
+    overridable = false) {
+        super(freeBytes === null
+            ? "binary-server is out of space for this upload"
+            : `binary-server has ${(freeBytes / 1024 ** 3).toFixed(1)} GB free, which is not enough for a ${(needBytes / 1024 ** 3).toFixed(1)} GB upload`);
+        this.needBytes = needBytes;
+        this.freeBytes = freeBytes;
+        this.overridable = overridable;
+        this.name = "InsufficientStorageError";
+    }
+}
+/**
+ * Upload `file` to binary-server in parts, resuming anything already delivered.
+ *
+ * Resolves once every part has landed and bs has assembled the object. The caller then tells
+ * its own app server to record the metadata — see each app's `/complete` route.
+ */
+export async function uploadDirect(file, session, opts = {}) {
+    const { onProgress, signal, refreshToken } = opts;
+    const concurrency = Math.max(1, opts.concurrency ?? 3);
+    const retries = Math.max(1, opts.retries ?? 5);
+    const { onLowDisk } = opts;
+    const total = session.totalChunks;
+    // A token can expire mid-upload on a slow line; `refreshToken` swaps in a new one and
+    // every subsequent request picks it up.
+    let token = session.token;
+    const prior = await fetchSessionState(session, token, signal);
+    if (prior.complete) {
+        return {
+            key: session.path,
+            size: prior.size ?? file.size,
+            checksum: prior.checksum,
+        };
+    }
+    // Bail before sending anything if the file plainly cannot land. bs keeps a reserve so a
+    // full disk never takes the Mac down, and it reports free space on the status call above —
+    // so an upload with nowhere to go costs one request instead of gigabytes of transfer.
+    const remainingBytes = file.size - prior.received.size * session.chunkBytes;
+    /*
+     * 🔴 NO PREFLIGHT REFUSAL. Owner instruction, 2026-08-13: *"Remove all blockers for space
+     * and only allow warning me. I'll manage space myself beyond that."*
+     *
+     * This used to throw when the remaining bytes exceeded the reported free space. It is gone
+     * rather than softened because a client-side estimate is the WORST place to make this
+     * call: `remainingBytes` counts every part not yet delivered, `freeBytes` was read before
+     * the transfer began, and neither accounts for what the run itself frees or the owner
+     * clears while it goes. binary-server no longer refuses either; the real limit is ENOSPC
+     * from the filesystem, which is about the actual write rather than a projection.
+     *
+     * `onLowDisk` is the replacement, and it only WARNS.
+     */
+    if (prior.freeBytes !== null && remainingBytes > prior.freeBytes) {
+        onLowDisk?.({ freeBytes: prior.freeBytes, needBytes: remainingBytes });
+    }
+    const pending = Array.from({ length: total }, (_, i) => i).filter((i) => !prior.received.has(i));
+    let done = total - pending.length;
+    let assembled = null;
+    const report = () => onProgress?.(total === 0 ? 1 : done / total, done * session.chunkBytes, file.size);
+    report();
+    const sendOne = async (ci) => {
+        const start = ci * session.chunkBytes;
+        // Lazy view onto the file — nothing is read until fetch streams it.
+        const part = file.slice(start, Math.min(start + session.chunkBytes, file.size));
+        let lastErr;
+        for (let attempt = 0; attempt < retries; attempt++) {
+            signal?.throwIfAborted();
+            try {
+                const res = await fetch(chunkUrl(session, token, ci), {
+                    method: "PUT",
+                    body: part,
+                    // bs stores the mime from the assembling request's content-type.
+                    // 🔴 `x-allow-low-disk` is what turns binary-server's disk RESERVE from a
+                    // wall into a warning. Owner instruction 2026-08-13, after a large upload
+                    // stopped dead: *"Do not let the server block me. It can warn me and I can
+                    // say do it anyway or cancel if I want."* The reserve is sized for the worst
+                    // case a chunked upload can transiently need, so it refused uploads that
+                    // would have fit. bs still refuses absolutely below its hard floor, where
+                    // the machine itself is what is at risk.
+                    headers: file.type ? { "content-type": file.type } : undefined,
+                    signal,
+                });
+                if (res.status === 403 && refreshToken) {
+                    // Almost always an expired session token on a long upload. Re-mint once per
+                    // attempt and let the loop retry with it.
+                    token = await refreshToken();
+                    throw new Error("token refreshed, retrying");
+                }
+                // Out of space is terminal — retrying cannot make room, and a 10 GB upload
+                // hammering a full disk five times over is the opposite of helpful.
+                if (res.status === 507) {
+                    const body = (await res.json().catch(() => ({})));
+                    // Terminal — retrying cannot make room, and a 10 GB upload hammering a full
+                    // disk five times over is the opposite of helpful. 🔴 A CURRENT
+                    // binary-server never sends this for its own reserve any more (see
+                    // `overridable`); reaching here means the volume is genuinely out of room
+                    // and the filesystem said so.
+                    throw new InsufficientStorageError(file.size, body.freeBytes ?? null, body.overridable === true);
+                }
+                if (!res.ok)
+                    throw new Error(`chunk ${ci}: HTTP ${res.status}`);
+                const body = (await res.json());
+                if (body.assembled) {
+                    assembled = {
+                        key: body.key ?? session.path,
+                        size: body.size ?? file.size,
+                        checksum: body.checksum ?? null,
+                    };
+                }
+                done++;
+                report();
+                return;
+            }
+            catch (err) {
+                if (signal?.aborted)
+                    throw err;
+                // Terminal: no amount of backoff creates disk space.
+                if (err instanceof InsufficientStorageError)
+                    throw err;
+                lastErr = err;
+                // Backoff, capped — a home connection that dropped needs seconds, not minutes.
+                await sleep(Math.min(1000 * 2 ** attempt, 15_000));
+            }
+        }
+        throw new Error(`chunk ${ci} failed after ${retries} attempts: ${lastErr instanceof Error ? lastErr.message : String(lastErr)}`);
+    };
+    // Bounded worker pool over the pending indices.
+    const queue = [...pending];
+    const workers = Array.from({ length: Math.min(concurrency, queue.length) }, async () => {
+        for (;;) {
+            const next = queue.shift();
+            if (next === undefined)
+                return;
+            await sendOne(next);
+        }
+    });
+    await Promise.all(workers);
+    if (assembled)
+        return assembled;
+    // Every part reported OK but no response carried the assemble result — possible if the
+    // final 201 was the one that got retried after its response was lost. Ask.
+    const after = await fetchSessionState(session, token, signal);
+    if (after.complete) {
+        return { key: session.path, size: after.size ?? file.size, checksum: after.checksum };
+    }
+    throw new Error(`upload finished but binary-server did not assemble ${session.path} (${after.received.size}/${total} parts)`);
+}
+//# sourceMappingURL=directUpload.js.map

package/dist/react/lib/directUpload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directUpload.js","sourceRoot":"","sources":["../../../src/react/lib/directUpload.ts"],"names":[],"mappings":"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"}

package/dist/styles-areas/auth.css

@@ -18,12 +18,12 @@
  * 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.
- * 11 candidate(s).
+ * 10 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("caret-transparent com focus-within:border-field-ring focus-within:ring-2");
+@source inline("caret-transparent focus-within:border-field-ring focus-within:ring-2");
 @source inline("focus-within:ring-field-ring/30 h-12 has-[[aria-invalid=true]]:border-field-error min-h-dvh");
 @source inline("self-start self-stretch sm:w-11");

package/dist/styles-areas/core.css

@@ -15,7 +15,7 @@
  * 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.
- * 705 candidate(s).
+ * 706 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
@@ -52,7 +52,7 @@
 @source inline("border-collapse border-current border-destructive/30 border-destructive/40 border-destructive/50");
 @source inline("border-field-border border-success/30 border-success/40 border-success/50 border-t");
 @source inline("border-transparent border-warning/30 border-warning/40 border-warning/50 border-x-4");
-@source inline("border-x-transparent bot bottom bottom-0 break break-all c ca cap capitalize co contain");
+@source inline("border-x-transparent bot bottom bottom-0 break break-all c ca cap capitalize co com contain");
 @source inline("container content contents cursor cursor-col-resize cursor-default cursor-ew-resize");
 @source inline("cursor-pointer cursor-row-resize d dark dark:bg-card-overlay dark:bg-card-raised");
 @source inline("dark:bg-gray-800 data data-[disabled]:hover:bg-border data-[disabled]:opacity-50");
@@ -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.1.0",
+	"version": "5.3.0",
 	"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.",
@@ -203,6 +203,12 @@
 			"source": "./src/react/components/DropdownMenu.tsx",
 			"import": "./dist/react/components/DropdownMenu.js"
 		},
+		"./react/engagement-beacon": {
+			"types": "./dist/react/engagement/index.d.ts",
+			"bun": "./src/react/engagement/index.ts",
+			"source": "./src/react/engagement/index.ts",
+			"import": "./dist/react/engagement/index.js"
+		},
 		"./react/file-tree": {
 			"types": "./dist/react/file-tree/index.d.ts",
 			"bun": "./src/react/file-tree/index.ts",
@@ -395,6 +401,12 @@
 			"source": "./src/react/components/Switch.tsx",
 			"import": "./dist/react/components/Switch.js"
 		},
+		"./react/upload-direct": {
+			"types": "./dist/react/lib/directUpload.d.ts",
+			"bun": "./src/react/lib/directUpload.ts",
+			"source": "./src/react/lib/directUpload.ts",
+			"import": "./dist/react/lib/directUpload.js"
+		},
 		"./react/workbook-viewer": {
 			"types": "./dist/react/workbook-viewer/index.d.ts",
 			"bun": "./src/react/workbook-viewer/index.ts",

package/scripts/checkAreaStyles.spec.ts

@@ -8,9 +8,14 @@ import {
   classesInCss,
   hasVariantPrefix,
   inlineCandidatesIn,
+  onlyAsPropertyName,
   onlyInMergeTables,
   readBeltSheets,
+  readThemeVariables,
+  themeVariablesIn,
   tokensInJs,
+  undefinedThemeVariables,
+  variablesDeclared,
 } from './checkAreaStyles';
 import { compileStylesheet } from './generateUtilityStyles';
 
@@ -133,6 +138,28 @@ describe('🔴 tailwind-merge tables are not usage (task 2118)', () => {
   });
 });
 
+describe('🔴 a property NAME is not class usage (task 2131, station)', () => {
+  // Verbatim from station's build: d3's scale check, inside recharts.
+  const STATION = 'function RE(e){if(e!=null)return"invert"in e&&typeof e.invert=="function"?e.invert:null}';
+
+  test('an `in` test and an object key are excused', () => {
+    expect(onlyAsPropertyName('invert', STATION)).toBe(true);
+    expect(onlyAsPropertyName('invert', 'const o={"invert":1}')).toBe(true);
+  });
+
+  test('refused when the token is ALSO a class, or a lone string value (`cn("italic")` IS usage)', () => {
+    expect(onlyAsPropertyName('invert', `${STATION};x({className:"invert grayscale"})`)).toBe(false);
+    expect(onlyAsPropertyName('italic', 'x=cn("italic",y)')).toBe(false);
+    expect(onlyAsPropertyName('h-8', 'const v={size:{sm:"h-8"}}')).toBe(false);
+    expect(onlyAsPropertyName('invert', '')).toBe(false);
+  });
+
+  test('the station shape reports no `invert` miss', () => {
+    const { missing } = checkAreaStyles({ js: [STATION], css: [''] }, readBeltSheets());
+    expect(missing.map((m) => m.className)).not.toContain('invert');
+  });
+});
+
 describe('an area is `@source inline` candidates since 5.1.0 (task 2124)', () => {
   test('inlineCandidatesIn reads both quote kinds and skips markers', () => {
     const css = `/* banner */\n@source inline("flex sm:hidden peer");\n@source inline('before:content-[""]');\n`;
@@ -203,3 +230,66 @@ 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], { 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 });
+    }
+  });
+});