cursedbelt 4.7.0 → 5.0.0

package/scripts/checkAreaStyles.ts

@@ -0,0 +1,150 @@
+#!/usr/bin/env bun
+/**
+ * Does an app's BUILT CSS style every cursedbelt class its BUILT JS uses? — the completeness
+ * check the per-area stylesheets need before any app may adopt them (task 079).
+ *
+ * ── Why adopting the areas was blocked on this ──────────────────────────────────────────
+ * `cursedbelt/styles-areas/*.css` lets an app import `core` plus the areas it renders instead
+ * of the 135 KB union (`scripts/generateAreaStyles.ts` has the numbers). The catch is the one
+ * `apps/flix/scripts/check-belt-styles.ts` was built for: under-select ONE area and the app
+ * typechecks, tests and builds green while a component renders unstyled. A byte count cannot
+ * tell "the right ten areas" from "nine of them" — a 4 KB miss is invisible in it.
+ *
+ * ── How it decides, with no new source of truth ─────────────────────────────────────────
+ *   1. The UNION — every utility cursedbelt's components use — is this package's own
+ *      `src/styles-utilities.css`. Its class selectors are the universe.
+ *   2. What the app's JS references: every whitespace/quote-delimited token in the app's built
+ *      `*.js` that is ALSO a union class. (Tailwind's extractor works the same way; a class
+ *      name survives minification because it is a string.)
+ *   3. What the app's CSS styles: every class selector in the app's built `*.css`.
+ *   4. (2) minus (3) is a class cursedbelt draws with and this app ships no rule for. Each one is
+ *      reported with the AREA that carries it (`src/styles-areas/*.css`), which is the fix.
+ *
+ * A false positive is possible — an app string that happens to equal a utility name and is not
+ * used as a class — and it is the cheap direction: adding the area costs bytes, missing one
+ * costs a broken screen on a live hostname. A class that appears in NO area is excluded (the
+ * area split already proves core-plus-every-area equals the union, `src/stylesAreas.spec.ts`).
+ *
+ * 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
+ * (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 { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** This package's `src`, from `scripts/` (source) or `dist/scripts/` (compiled). */
+const SRC = [resolve(HERE, '../src'), resolve(HERE, '../../src')].find((d) =>
+  existsSync(join(d, 'styles-utilities.css')),
+);
+
+/** Undo CSS identifier escaping: `\:` → `:`, `\32 xl` → `2xl`. */
+function unescapeIdent(raw: string): string {
+  return raw.replace(/\\([0-9a-fA-F]{1,6}) ?|\\(.)/g, (_m, hex: string | undefined, ch: string | undefined) =>
+    hex ? String.fromCodePoint(Number.parseInt(hex, 16)) : (ch ?? ''),
+  );
+}
+
+/** Every class selector in a stylesheet, unescaped. Comments are dropped first. */
+export function classesInCss(css: string): Set<string> {
+  const out = new Set<string>();
+  const code = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  // Only selector text — the part before each `{` — so a `.5rem` in a declaration never counts.
+  for (const selector of code.split('{').map((chunk) => chunk.slice(chunk.lastIndexOf('}') + 1).split(';').pop() ?? '')) {
+    for (const m of selector.matchAll(/\.((?:\\[0-9a-fA-F]{1,6} ?|\\.|[A-Za-z0-9_-])+)/g)) {
+      const name = unescapeIdent(m[1] as string);
+      if (/^[0-9]/.test(name) && !/[a-z]/i.test(name)) continue; // `.5` in a stray number
+      out.add(name);
+    }
+  }
+  return out;
+}
+
+/** Every whitespace/quote/backtick-delimited token in a JS bundle. */
+export function tokensInJs(js: string): Set<string> {
+  return new Set(js.split(/[\s"'`]+/).filter((t) => t.length > 0 && t.length < 200));
+}
+
+function filesUnder(dir: string, ext: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir)) {
+    if (entry === 'node_modules') continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) filesUnder(full, ext, out);
+    else if (entry.endsWith(ext)) out.push(full);
+  }
+  return out;
+}
+
+export interface AreaCheckResult {
+  /** Belt classes the JS uses and the CSS does not style → the area that carries each. */
+  missing: { className: string; area: string }[];
+  jsFiles: number;
+  cssFiles: number;
+  /** How many belt classes the JS references — a zero here means the check saw nothing. */
+  referenced: number;
+}
+
+/** 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'> {
+  const union = classesInCss(belt.union);
+  const areaOf = new Map<string, string>();
+  for (const [area, css] of Object.entries(belt.areas)) {
+    for (const name of classesInCss(css)) if (!areaOf.has(name)) areaOf.set(name, area);
+  }
+  const emitted = new Set<string>();
+  for (const css of input.css) for (const name of classesInCss(css)) emitted.add(name);
+  const referenced = new Set<string>();
+  for (const js of input.js) for (const token of tokensInJs(js)) if (union.has(token) && areaOf.has(token)) referenced.add(token);
+  const missing = [...referenced]
+    .filter((name) => !emitted.has(name))
+    .sort()
+    .map((className) => ({ className, area: areaOf.get(className) as string }));
+  return { missing, referenced: referenced.size };
+}
+
+/** Read this package's union + area sheets. */
+export function readBeltSheets(src: string | undefined = SRC): { union: string; areas: Record<string, string> } {
+  if (!src) throw new Error("cursedbelt's src/styles-utilities.css is not beside this script — the package is incomplete");
+  const areasDir = join(src, 'styles-areas');
+  const areas: Record<string, string> = {};
+  for (const file of readdirSync(areasDir)) if (file.endsWith('.css')) areas[basename(file, '.css')] = readFileSync(join(areasDir, file), 'utf8');
+  return { union: readFileSync(join(src, 'styles-utilities.css'), 'utf8'), areas };
+}
+
+export function checkDist(distDir: string): AreaCheckResult {
+  const jsFiles = filesUnder(distDir, '.js');
+  const cssFiles = filesUnder(distDir, '.css');
+  const result = checkAreaStyles(
+    { js: jsFiles.map((f) => readFileSync(f, 'utf8')), css: cssFiles.map((f) => readFileSync(f, 'utf8')) },
+    readBeltSheets(),
+  );
+  return { ...result, jsFiles: jsFiles.length, cssFiles: cssFiles.length };
+}
+
+if (import.meta.main) {
+  const dir = resolve(process.argv[2] ?? '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);
+  }
+  const result = checkDist(dir);
+  if (result.jsFiles === 0 || result.cssFiles === 0) {
+    console.error(`✗ ${dir} holds ${result.jsFiles} .js and ${result.cssFiles} .css file(s) — nothing to compare.`);
+    process.exit(2);
+  }
+  if (result.missing.length === 0) {
+    console.log(`✓ belt area styles complete: all ${result.referenced} cursedbelt classes the build references are styled (${result.jsFiles} js, ${result.cssFiles} css).`);
+    process.exit(0);
+  }
+  const byArea = new Map<string, string[]>();
+  for (const { className, area } of result.missing) byArea.set(area, [...(byArea.get(area) ?? []), className]);
+  console.error(`✗ ${result.missing.length} cursedbelt class(es) the built JS uses have NO rule in the built CSS.`);
+  console.error('  Import the area that carries them (after core) — `@import "cursedbelt/styles-areas/<area>.css";`:');
+  for (const [area, names] of [...byArea].sort()) console.error(`    ${area}.css  ← ${names.slice(0, 8).join(' ')}${names.length > 8 ? ` … +${names.length - 8}` : ''}`);
+  process.exit(1);
+}

package/scripts/guardrailsEnforce.spec.ts

@@ -791,6 +791,14 @@ describe('no-native-dialog', () => {
     expect(check('no-native-dialog', prompted)).toHaveLength(0);
   });
 
+  test("🔴 a sibling import with the Node `.js` extension is the belt one too (task 269's spelling)", () => {
+    // DeleteButton's own `import { confirm } from '../confirm.js'` was reported as a native
+    // dialog from the day every relative specifier gained its `.js` until 2026-09-23.
+    const source = `import { confirm, type ConfirmOptions } from '../confirm.js';
+    const ok = await confirm({ title: 'Delete?' });`;
+    expect(check('no-native-dialog', source)).toHaveLength(0);
+  });
+
   test('🔴 a belt import does NOT excuse an explicit window.confirm in the same file', () => {
     // The migration's half-done state: one call site converted, one left behind.
     // Exempting the whole FILE on the strength of its import list is how that
@@ -1176,3 +1184,38 @@ describe('--exclude', () => {
     });
   });
 });
+
+describe('no-raw-password', () => {
+  test('🔴 flags the COMPONENT form no-raw-inputs is blind to', () => {
+    expect(check('no-raw-password', `<Input id="ml-current" type="password" />`)).toHaveLength(1);
+    expect(check('no-raw-inputs', `<Input id="ml-current" type="password" />`)).toHaveLength(0);
+  });
+
+  test('flags a raw input, a JSX expression, a props object and template-literal HTML', () => {
+    expect(check('no-raw-password', `<input type='password' />`)).toHaveLength(1);
+    expect(check('no-raw-password', `<TextField type={"password"} />`)).toHaveLength(1);
+    expect(check('no-raw-password', `const field = { name: 'pw', type: 'password' };`)).toHaveLength(1);
+    expect(check('no-raw-password', 'const html = `<input name="pw" type="password">`;')).toHaveLength(1);
+  });
+
+  test("passes SecretInput's own toggle — a ternary IS the eye", () => {
+    expect(check('no-raw-password', `        type={shown ? 'text' : 'password'}`)).toHaveLength(0);
+  });
+
+  test('passes an ignore-commented line, same line or the block above', () => {
+    expect(
+      check('no-raw-password', `<input type="password" /> {/* guardrails-ignore no-raw-password: server page, own eye */}`),
+    ).toHaveLength(0);
+    expect(
+      check(
+        'no-raw-password',
+        `// guardrails-ignore no-raw-password: server-rendered, carries its own reveal button
+const html = \`<input type="password">\`;`,
+      ),
+    ).toHaveLength(0);
+  });
+
+  test('prose in a comment is not a field', () => {
+    expect(check('no-raw-password', `// never write type="password" by hand`)).toHaveLength(0);
+  });
+});

package/scripts/guardrailsEnforce.ts

@@ -122,6 +122,10 @@
 //     `--reimplements <Name,…>` from `fleet/standards/CURSEDBELT_INVENTORY.md`; with no
 //     list the rule is inert rather than guessing.
 //
+//   no-raw-password — owner, 2026-09-18: every password field has an eye. Flags
+//     `type="password"` on ANY tag or props object (the `<Input type="password">` form that
+//     `no-raw-inputs` cannot see) and in template-literal HTML. Use `SecretInput`.
+//
 // Opt-out (mirrors this repo's existing `biome-ignore lint/<rule>: <reason>` convention —
 // see e.g. packages/cursedbelt/src/react/components/ButtonGroup.tsx): put a same-shaped
 // line comment as the FIRST thing inside the tag's attribute list (for `no-raw-action-button`
@@ -1487,7 +1491,9 @@ function importsBeltDialog(source: string, fn: string): boolean {
 		// static, from the package
 		new RegExp(`import\\s*${named}\\s*from\\s*${spec}`, "s").test(source) ||
 		// static, from a sibling inside cursedbelt itself
-		new RegExp(`import\\s*${named}\\s*from\\s*['"][./]+(?:react/)?${fn}['"]`, "s").test(source) ||
+		// (with or without the `.js` Node ESM needs — task 269 added it to every relative
+		// specifier, and this pattern then reported `DeleteButton`'s own belt `confirm`)
+		new RegExp(`import\\s*${named}\\s*from\\s*['"][./]+(?:react/)?${fn}(?:\\.[jt]sx?)?['"]`, "s").test(source) ||
 		// dynamic — `const { prompt } = await import('cursedbelt/react/prompt')`
 		new RegExp(`${named}\\s*=\\s*(?:await\\s+)?import\\(\\s*${spec}`, "s").test(source) ||
 		// and its type-only companion, `typeof import('…').prompt`
@@ -1626,6 +1632,44 @@ const noFastTooltip: Rule = {
 	},
 };
 
+// ── no-raw-password (owner, 2026-09-18: "all passwords need eye icon") ─────────
+// A password field the person typing into cannot reveal. `SecretInput` has carried the eye
+// (and an opt-out copy button, `showCopy={false}` for a login form) the whole time, and on
+// 2026-09-19 twenty-eight fields across the fleet still typed into the dark — three of them in
+// cursedbelt's OWN master-lock dialog. They accumulated under an enforced guardrails suite
+// because there was no rule about masked fields at all: `no-raw-inputs` is about bare TAGS, and
+// every one of the three belt fields was `<Input type="password">`, a component it never reads.
+//
+// So this rule is on the ATTRIBUTE, on any tag: a raw `<input>`, a component (`<Input`,
+// `<TextField`), a props object (`{ type: 'password' }`), and server-rendered HTML in a
+// template literal (`<input type="password">`), which is the one place a React primitive
+// cannot reach — that markup takes an eye of its own. `SecretInput`'s own
+// `type={shown ? 'text' : 'password'}` does not match: a ternary is a toggle, which is the
+// point. Comments are blanked first; specs are fixtures and are skipped.
+const PASSWORD_TYPE_RE =
+	/\btype\s*=\s*(?:\{\s*)?["'`]password["'`]|\btype\s*:\s*["'`]password["'`]/;
+const PASSWORD_IGNORE_RE = /guardrails-ignore\s+no-raw-password\s*:/;
+
+const noRawPassword: Rule = {
+	name: "no-raw-password",
+	description:
+		"Owner, 2026-09-18: every password field has an eye. A `type=\"password\"` field the person cannot reveal — on any tag, component or props object — must be cursedbelt's `SecretInput` (`showCopy={false}` for a login form, `autoComplete` passed through). Server-rendered HTML that cannot import it carries its own reveal toggle and takes the per-line opt-out naming it.",
+	check(filePath, source) {
+		if (isTestSource(filePath.replace(/\\/g, "/"))) return [];
+		const raws = source.split("\n");
+		const scan = blankComments(source).split("\n");
+		const out: Violation[] = [];
+		for (const [i, line] of scan.entries()) {
+			if (!PASSWORD_TYPE_RE.test(line)) continue;
+			const raw = raws[i] ?? "";
+			if (PASSWORD_IGNORE_RE.test(raw)) continue;
+			if (PASSWORD_IGNORE_RE.test(raws.slice(Math.max(0, i - 3), i).join("\n"))) continue;
+			out.push({ file: filePath, line: i + 1, snippet: raw.trim() });
+		}
+		return out;
+	},
+};
+
 export const RULES: Record<string, Rule> = {
 	[noRawActionButton.name]: noRawActionButton,
 	[noRawOverflow.name]: noRawOverflow,
@@ -1644,6 +1688,7 @@ export const RULES: Record<string, Rule> = {
 	[noSelectAsActionMenu.name]: noSelectAsActionMenu,
 	[noNativeDialog.name]: noNativeDialog,
 	[noFastTooltip.name]: noFastTooltip,
+	[noRawPassword.name]: noRawPassword,
 };
 
 // ── File-scoped allowances ──────────────────────────────────────────────────────

package/scripts/styleAreas.ts

@@ -419,7 +419,6 @@ const resolveRelative = (fromFile: string, specifier: string): string | null =>
 	const base = `/${stack.join('/')}`.replace(/\.js$/, '');
 	if (SOURCE.test(base)) return base;
 	for (const candidate of [`${base}.ts`, `${base}.tsx`, `${base}/index.ts`, `${base}/index.tsx`]) {
-		// biome-ignore lint/nursery/noAwaitInLoop: synchronous existence check, no await here
 		if (Bun.file(candidate).size > 0) return candidate;
 	}
 	return null;
@@ -442,7 +441,7 @@ export const buildGraph = async (): Promise<Map<string, string[]>> => {
 			for (const match of text.matchAll(SPECIFIER)) {
 				const target = resolveRelative(file, match[1] as string);
 				// Outside `src/react` is outside every area — the utility scan never sees it.
-				if (target && target.startsWith(`${REACT_DIR}/`) && !SPEC.test(target)) out.add(target);
+				if (target?.startsWith(`${REACT_DIR}/`) && !SPEC.test(target)) out.add(target);
 			}
 			graph.set(file, [...out]);
 		}),

package/src/barrelsReachNoOptionalPeer.spec.ts

@@ -92,14 +92,17 @@ const NO_STATIC_OPTIONAL_PEERS = [
   },
 ] as const;
 
-const OPTIONAL_PEERS = new Set(
-  Object.entries(
+const OPTIONAL_PEERS = new Set([
+  ...Object.entries(
     (pkg as { peerDependenciesMeta?: Record<string, { optional?: boolean }> })
       .peerDependenciesMeta ?? {},
   )
     .filter(([, meta]) => meta?.optional === true)
     .map(([name]) => name),
-);
+  // Optional in every sense but npm's (task 2087): declared in `unpeered`, not peered only
+  // because npm cannot resolve them. The barrel must not reach them statically either.
+  ...Object.keys((pkg as { unpeered?: { packages?: Record<string, string> } }).unpeered?.packages ?? {}),
+]);
 
 /**
  * `import x from "pkg"` · `export … from "pkg"` · the side-effect-only `import "pkg";`.

package/src/bundlerOnlyEntries.spec.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'bun:test';
+import { existsSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import pkg from '../package.json';
+
+/**
+ * `bundlerOnly.subpaths` in `package.json` is EXACTLY the set of export subpaths whose
+ * built graph imports a stylesheet — in both directions.
+ *
+ * Task 2087: every cursedbelt publish runs `tools/proveInstall.ts`, and Node refused 12 of its
+ * entries with `ERR_UNKNOWN_FILE_EXTENSION ".css"`. That is by design (a component that ships
+ * its own stylesheet needs a bundler), but a proof that is red on every publish trains people to
+ * ignore it. The fix is an excuse the package DECLARES rather than one the tool grants globally —
+ * and a declaration only stays true if something re-derives it. This does: every subpath is
+ * bundled with its packages external, and a subpath counts when its output has a CSS sibling (its
+ * own `.css` imports) or imports a package's `.css` (`@vidstack/…/theme.css`). A new CSS import
+ * on an undeclared subpath is red here, before it is red in a publish; a declared subpath that
+ * stopped importing CSS is red too, so the excuse cannot outlive its reason.
+ */
+
+const REPO = fileURLToPath(new URL('..', import.meta.url));
+
+type Reason = 'css' | 'directoryImport';
+const declared = (reason: Reason): string[] =>
+  [...((pkg as { bundlerOnly?: Record<Reason, string[]> }).bundlerOnly?.[reason] ?? [])].sort();
+
+/** A deep specifier into a package with NO `exports` map, naming a directory — Node ESM refuses it. */
+const isDirectoryImport = (specifier: string): boolean => {
+  const parts = specifier.split('/');
+  const n = specifier.startsWith('@') ? 2 : 1;
+  if (parts.length <= n) return false;
+  const name = parts.slice(0, n).join('/');
+  const manifest = `${REPO}node_modules/${name}/package.json`;
+  if (!existsSync(manifest) || JSON.parse(readFileSync(manifest, 'utf8')).exports) return false;
+  const target = `${REPO}node_modules/${specifier}`;
+  return existsSync(target) && statSync(target).isDirectory();
+};
+
+const SPECIFIER = /\bfrom\s*["']([^"'\n]+)["']|^\s*import\s*["']([^"'\n]+)["'];?\s*$/gm;
+
+async function measure(): Promise<Record<Reason, string[]>> {
+  const entries = Object.entries(pkg.exports as Record<string, unknown>).flatMap(([subpath, target]) => {
+    const source = (target as { source?: string }).source;
+    return source && /\.tsx?$/.test(source) ? [[subpath, source.replace(/^\.\//, '')] as const] : [];
+  });
+  const outdir = `${process.env.TMPDIR ?? '/tmp'}/cursedbelt-bundler-only-${process.pid}`;
+  try {
+    const result = await Bun.build({
+      entrypoints: entries.map(([, source]) => `${REPO}${source}`),
+      root: REPO,
+      target: 'bun',
+      packages: 'external',
+      outdir,
+    });
+    if (!result.success) throw new Error(`could not bundle — a check that cannot measure is not a pass:\n${result.logs.join('\n')}`);
+    const emitted = new Set(result.outputs.map((o) => o.path));
+    const out: Record<Reason, string[]> = { css: [], directoryImport: [] };
+    for (const [subpath, source] of entries) {
+      const js = `${outdir}/${source.replace(/\.tsx?$/, '.js')}`;
+      const code = readFileSync(js, 'utf8');
+      const specifiers = [...code.matchAll(SPECIFIER)].map((m) => (m[1] ?? m[2]) as string);
+      if (emitted.has(js.replace(/\.js$/, '.css')) || specifiers.some((s) => s.endsWith('.css'))) out.css.push(subpath);
+      if (specifiers.some((s) => !s.startsWith('.') && isDirectoryImport(s))) out.directoryImport.push(subpath);
+    }
+    out.css.sort();
+    out.directoryImport.sort();
+    return out;
+  } finally {
+    rmSync(outdir, { recursive: true, force: true });
+  }
+}
+
+describe('bundlerOnly', () => {
+  it('declares exactly the subpaths that import a stylesheet, and exactly those that reach a directory import', async () => {
+    const measured = await measure();
+    // The measurement must have seen the cases it exists for, or it measured nothing.
+    expect(measured.css).toContain('./react/media');
+    expect(measured.directoryImport).toContain('./react/disk-usage');
+    for (const reason of ['css', 'directoryImport'] as const) {
+      expect({
+        reason,
+        undeclared: measured[reason].filter((s) => !declared(reason).includes(s)),
+        stale: declared(reason).filter((s) => !measured[reason].includes(s)),
+      }).toEqual({ reason, undeclared: [], stale: [] });
+    }
+  });
+
+  it('names only subpaths that exist', () => {
+    const exported = Object.keys(pkg.exports as Record<string, unknown>);
+    for (const reason of ['css', 'directoryImport'] as const) expect(declared(reason).filter((s) => !exported.includes(s))).toEqual([]);
+  });
+});
+
+describe('unpeered', () => {
+  it('is disjoint from peerDependencies — a package is peered or unpeered, never both', () => {
+    const unpeered = Object.keys((pkg as { unpeered?: { packages?: Record<string, string> } }).unpeered?.packages ?? {});
+    expect(unpeered.length).toBeGreaterThan(0);
+    const peers = Object.keys((pkg as { peerDependencies?: Record<string, string> }).peerDependencies ?? {});
+    expect(unpeered.filter((name) => peers.includes(name))).toEqual([]);
+  });
+});

package/src/declaredImports.spec.ts

@@ -20,6 +20,10 @@ const declared = new Set([
   pkg.name,
   ...Object.keys((pkg as { dependencies?: Record<string, string> }).dependencies ?? {}),
   ...Object.keys((pkg as { peerDependencies?: Record<string, string> }).peerDependencies ?? {}),
+  // `unpeered` — imported by a subpath, declared, and kept OUT of peerDependencies only
+  // because npm cannot resolve them beside this package's own peers (task 2087; the block says
+  // why for each).
+  ...Object.keys((pkg as { unpeered?: { packages?: Record<string, string> } }).unpeered?.packages ?? {}),
 ]);
 const builtin = new Set(builtinModules);
 

package/src/optionalPeersTable.spec.ts

@@ -0,0 +1,127 @@
+import { describe, expect, it } from 'bun:test';
+import { readFileSync, rmSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import pkg from '../package.json';
+
+/**
+ * 🔴 `docs/API-REFERENCE.md`'s "What you install" table is the ONE place an importing app learns
+ * that `cursedbelt/react/charts` needs `recharts` — and this spec is what keeps it true.
+ *
+ * Task 104 (2026-09-17): *"`cursedbelt/react/charts` hard-fails the build without `recharts`,
+ * and the error names a `__vite-optional-peer-dep` module rather than the package."* The fix is
+ * one install; the cost was entirely in not knowing. The table says what to install, but it was
+ * hand-written — and measured the day this spec arrived it had already missed a subpath:
+ * `./react/media-gallery` statically reaches `@glideapps/glide-data-grid`, `@vidstack/react` and
+ * `marked`, and no row said so. (`peers-by-subpath.json` died of exactly this — task 272.)
+ *
+ * So: every public `./react/*` subpath is bundled with its packages left external, the OPTIONAL
+ * peers each one imports STATICALLY are read out of the bundle, and each must be named in that
+ * subpath's row of the table. A static optional peer is the case that breaks a build; a lazy
+ * `await import()` one breaks only the feature that loads it, and is the documented shape to
+ * copy, so it is not required here (a row may still name it).
+ *
+ * A row names a peer when its second cell carries the name in backticks, or a `@scope/*` set
+ * that covers it (the `@codemirror/*` set).
+ */
+
+const REPO = fileURLToPath(new URL('..', import.meta.url));
+const DOC = `${REPO}docs/API-REFERENCE.md`;
+const HEADING = '### What you install, and what you don\'t';
+
+const OPTIONAL = new Set([
+  ...Object.entries(
+    (pkg as { peerDependenciesMeta?: Record<string, { optional?: boolean }> }).peerDependenciesMeta ??
+      {},
+  )
+    .filter(([, meta]) => meta?.optional === true)
+    .map(([name]) => name),
+  // `unpeered` (task 2087): optional peers npm cannot resolve, so not in peerDependencies —
+  // an app still has to install them, so the table still has to name them.
+  ...Object.keys((pkg as { unpeered?: { packages?: Record<string, string> } }).unpeered?.packages ?? {}),
+]);
+
+/** Same matcher as `barrelsReachNoOptionalPeer.spec.ts` — anchored on `from`, never on a dynamic import. */
+const STATIC_SPECIFIER = /\bfrom\s*["']([^"'\n]+)["']|^\s*import\s*["']([^"'\n]+)["'];?\s*$/gm;
+
+const packageOf = (specifier: string): string => {
+  const parts = specifier.split('/');
+  return (specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0]) ?? specifier;
+};
+
+/** `./react/charts` → the optional peers its bundle imports statically. */
+async function staticOptionalPeersBySubpath(): Promise<Map<string, string[]>> {
+  const entries = Object.entries(pkg.exports as Record<string, unknown>).flatMap(([subpath, target]) => {
+    const source = (target as { source?: string }).source;
+    return subpath.startsWith('./react/') && source && /\.tsx?$/.test(source) ? [[subpath, source] as const] : [];
+  });
+  const outdir = `${process.env.TMPDIR ?? '/tmp'}/cursedbelt-optional-peers-${process.pid}`;
+  try {
+    const result = await Bun.build({
+      entrypoints: entries.map(([, source]) => `${REPO}${source.replace(/^\.\//, '')}`),
+      root: `${REPO}src`,
+      target: 'bun',
+      packages: 'external',
+      outdir,
+    });
+    if (!result.success) throw new Error(`could not bundle the subpaths — a check that cannot measure is not a pass:\n${result.logs.join('\n')}`);
+    const out = new Map<string, string[]>();
+    for (const [subpath, source] of entries) {
+      const emitted = `${outdir}/${source.replace(/^\.\/src\//, '').replace(/\.tsx?$/, '.js')}`;
+      const text = readFileSync(emitted, 'utf8');
+      const found = new Set<string>();
+      for (const m of text.matchAll(STATIC_SPECIFIER)) {
+        const specifier = m[1] ?? m[2];
+        if (specifier && !specifier.startsWith('.') && OPTIONAL.has(packageOf(specifier))) found.add(packageOf(specifier));
+      }
+      out.set(subpath, [...found].sort());
+    }
+    return out;
+  } finally {
+    rmSync(outdir, { recursive: true, force: true });
+  }
+}
+
+/** The table's rows: every `cursedbelt/react/<name>` its first cell names (`…/y` continues the last), → its second cell. */
+export function tableRows(markdown: string): Map<string, string> {
+  const start = markdown.indexOf(HEADING);
+  if (start < 0) throw new Error(`${DOC} has no "${HEADING}" section — the table this spec keeps honest is gone`);
+  const rows = new Map<string, string>();
+  for (const line of markdown.slice(start).split('\n').slice(1)) {
+    if (line.startsWith('#')) break;
+    if (!line.startsWith('|')) continue;
+    const [first = '', second = ''] = line.split('|').slice(1, 3);
+    for (const m of first.matchAll(/`cursedbelt\/(react\/[\w/-]+)`/g)) rows.set(`./${m[1]}`, second);
+    for (const m of first.matchAll(/`…\/([\w-]+)`/g)) rows.set(`./react/${m[1]}`, second);
+  }
+  return rows;
+}
+
+/** Does this cell name `peer` — literally, or through a `@scope/*` set? */
+export function names(cell: string, peer: string): boolean {
+  if (cell.includes(`\`${peer}\``)) return true;
+  const scope = peer.startsWith('@') ? peer.split('/')[0] : null;
+  return scope !== null && cell.includes(`\`${scope}/*\``);
+}
+
+describe("the docs' what-you-install table", () => {
+  it('🔴 fails on a subpath whose static optional peer no row names — the task-104 shape', () => {
+    const rows = tableRows(`${HEADING}\n| import this | also \`bun add\` this |\n| --- | --- |\n| \`cursedbelt/react/code-editor\` | the \`@codemirror/*\` set |\n`);
+    expect(names(rows.get('./react/code-editor') ?? '', '@codemirror/view')).toBe(true);
+    expect(rows.get('./react/charts')).toBeUndefined();
+    expect(names('`marked`', 'recharts')).toBe(false);
+  });
+
+  it('names every optional peer each ./react/* subpath imports statically', async () => {
+    const rows = tableRows(readFileSync(DOC, 'utf8'));
+    const bySubpath = await staticOptionalPeersBySubpath();
+    // The measurement must have seen the case this exists for, or it measured nothing.
+    expect(bySubpath.get('./react/charts')).toContain('recharts');
+    const missing: string[] = [];
+    for (const [subpath, peers] of bySubpath) {
+      for (const peer of peers) {
+        if (!names(rows.get(subpath) ?? '', peer)) missing.push(`cursedbelt/${subpath.slice(2)} → ${peer}`);
+      }
+    }
+    expect(missing, `add these to the table in ${DOC}`).toEqual([]);
+  });
+});

package/src/react/chat/index.ts

@@ -6,6 +6,14 @@ export { MessageScroller, type MessageScrollerProps } from './MessageScroller.js
 export { MessageThread, type MessageThreadProps } from './MessageThread.js';
 export { PresenceRoster, type PresenceRosterProps } from './PresenceRoster.js';
 export { StatusMarker, type StatusMarkerProps } from './StatusMarker.js';
+export {
+  PRESENCE_RETRY_MS,
+  type PresenceEntryLike,
+  type PresenceSubscription,
+  presenceUsers,
+  type UsePresenceOptions,
+  usePresence,
+} from './usePresence.js';
 export type {
   ChatAttachment,
   ChatAuthor,