cursedbelt 3.0.2 → 4.0.0

package/scripts/verify.ts

@@ -76,6 +76,11 @@ export const STAGES: readonly Stage[] = [
 	{ script: "paths" },
 	{ script: "typecheck:root" },
 	{ script: "typecheck:specs" },
+	// 🔴 Added 2026-09-16 (task 172). `tsconfig.json` includes `src` only, so the eleven
+	// files under `scripts/` were compiled by nothing — including `guardrailsEnforce.ts`,
+	// which package.json EXPORTS as `cursedbelt/guardrails`. Four apps were typechecking a
+	// file this repo's own gate had never looked at, and inheriting its errors.
+	{ script: "typecheck:scripts" },
 	{ script: "demo:check" },
 	{ script: "styles" },
 	{

package/src/barrelsReachNoOptionalPeer.spec.ts

@@ -70,9 +70,18 @@ const REPO = fileURLToPath(new URL('..', import.meta.url));
  * task above is about; a `await import('sharp')` inside the function that needs it is
  * exactly the right shape and stays legal here.
  *
- * Limitation, stated rather than hidden: the externals are read out of the bundle's import
- * statements textually, so an import bun emits across several lines would be missed. That
- * makes this half a floor, not a ceiling — the runtime fixture above is the strict one.
+ * The externals are read out of the bundle's import statements textually.
+ *
+ * ⛔ **Corrected 2026-09-15 (task 149).** This paragraph used to admit the scan as "a floor,
+ * not a ceiling" because it only matched an import bun emitted on ONE line — and the
+ * admission was worth more than it looked. Bundling `./react` and diffing the result against
+ * the manifest showed the old pattern silently missing `cmdk` and `@tanstack/react-table`,
+ * both of which bun emits as a multi-line `import {\n … \n} from "pkg";`. Nothing was red at
+ * the time, because both are hard `dependencies` rather than optional peers — but the
+ * MEASUREMENT half of task 149 ran off this same scan, and a dependency graph with two
+ * packages missing from it is the kind of thing a decision gets made on. So the matcher is
+ * anchored on `from "…"` wherever it appears now, plus the bare `import "…";` form, and the
+ * limitation is gone rather than documented.
  */
 const NO_STATIC_OPTIONAL_PEERS = [
   {
@@ -92,8 +101,14 @@ const OPTIONAL_PEERS = new Set(
     .map(([name]) => name),
 );
 
-/** `import x from "pkg"`, `import "pkg"`, `export … from "pkg"` — one line each, as bun emits. */
-const STATIC_SPECIFIER = /^(?:import|export)\s[^\n]*?["']([^"'\n]+)["'];?$|^import\s*["']([^"'\n]+)["'];?$/gm;
+/**
+ * `import x from "pkg"` · `export … from "pkg"` · the side-effect-only `import "pkg";`.
+ *
+ * 🔴 Anchored on the `from` clause, NOT on a line starting with `import`, so a multi-line
+ * named import still counts (see the correction above). A DYNAMIC `import("pkg")` matches
+ * neither branch and must not: that is the lazy shape this whole file exists to permit.
+ */
+const STATIC_SPECIFIER = /\bfrom\s*["']([^"'\n]+)["']|^\s*import\s*["']([^"'\n]+)["'];?\s*$/gm;
 
 /**
  * 🔴 An OUTDIR, not stdout, and this repo is why (2026-09-15).
@@ -107,7 +122,7 @@ const STATIC_SPECIFIER = /^(?:import|export)\s[^\n]*?["']([^"'\n]+)["'];?$|^impo
  * `.js` it emits — a stylesheet cannot import a package, so the CSS output is
  * irrelevant to the question and only the JS is read.
  */
-const staticOptionalPeersOf = (entry: string): string[] => {
+const staticExternalsOf = (entry: string): Set<string> => {
   const outdir = `${process.env.TMPDIR ?? '/tmp'}/cursedbelt-barrel-scan/${entry.replace(/[^a-z0-9]+/gi, '-')}`;
   const build = Bun.spawnSync(
     ['bun', 'build', entry, '--target=bun', '--packages=external', '--outdir', outdir],
@@ -123,13 +138,64 @@ const staticOptionalPeersOf = (entry: string): string[] => {
   const found = new Set<string>();
   for (const match of bundle.matchAll(STATIC_SPECIFIER)) {
     const specifier = match[1] ?? match[2];
-    if (specifier === undefined || specifier.startsWith('.')) continue;
+    if (specifier === undefined || specifier.startsWith('.') || specifier.startsWith('bun:')) {
+      continue;
+    }
     // `@scope/name/deep` → `@scope/name`, `pkg/deep` → `pkg`.
     const parts = specifier.split('/');
     const name = specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
-    if (name !== undefined && OPTIONAL_PEERS.has(name)) found.add(name);
+    if (name !== undefined) found.add(name);
   }
-  return [...found].sort();
+  return found;
+};
+
+const staticOptionalPeersOf = (entry: string): string[] =>
+  [...staticExternalsOf(entry)].filter((name) => OPTIONAL_PEERS.has(name)).sort();
+
+/**
+ * 🔴 The INVERSE of everything above, and the half task 149 had to add (2026-09-15).
+ *
+ * The rule the optional-peer check enforces — *the barrel must not drag a package a
+ * consumer may never call* — has an exact mirror that nothing was enforcing: **a hard
+ * `dependency` the barrel never touches is a package EVERY consumer installs and no
+ * consumer's `cursedbelt/react` import can reach.** Both are the same defect measured
+ * from opposite ends, and the second one is the expensive one, because it is invisible:
+ * the manifest is green, the import graph is clean, and the app just pays.
+ *
+ * Measured into an empty directory at 3.0.2, before this check existed: eight of the
+ * thirty-five runtime `dependencies` were in exactly that state — `emoji-mart` and its
+ * two siblings (already loaded through `await import()` in `emoji/EmojiPicker.tsx` and
+ * `emoji/emojiSearch.ts`), `@git-diff-view/react` + `diff` (only `./react/diff-viewer`),
+ * `marked` (only `./react/markdown-doc`), `react-grid-layout` (only
+ * `./react/dashboard-grid`) and `@hookform/resolvers` (only `lib/form.ts`). They cost a
+ * `Button` consumer **31 of 127 packages and 56 of 231 MB** and bought it nothing. All
+ * eight are optional peers at 4.0.0, and this test is what stops the ninth.
+ *
+ * 🔴 It is also the reason the twelve leaf Radix packages, `clsx`, `tailwind-merge` and
+ * `class-variance-authority` STAYED hard dependencies against task 149's own 23-row
+ * list: the barrel reaches every one of them, so by this rule they are correctly
+ * declared. `docs/STANDARDS.md` carries the measurement that says what moving them
+ * anyway would have bought (3 MB) and cost (`Button`, `Tooltip`, `cn`, and eleven more
+ * components out of `cursedbelt/react`). Read it before re-opening that question.
+ *
+ * The two `@atlaskit/pragmatic-drag-and-drop-{auto-scroll,hitbox}` packages are on that
+ * list too, and they are stuck for a different reason worth writing down once: `hitbox`'s
+ * `getReorderDestinationIndex` is called by `reorderByEdge`
+ * (`src/react/hooks/useDragReorder.tsx:112`), an exported **pure synchronous** function, and
+ * `attachClosestEdge` runs inside a drop target's `getData`, which the engine calls
+ * synchronously mid-drag. Making either lazy changes a public pure function's signature to
+ * async, for the 3 packages the pair costs. `DataTable`'s row drag puts the base engine in
+ * the barrel regardless, so moving the drag hooks behind a subpath would not free it either.
+ *
+ * Verified failing before it was trusted: reverting `emoji-mart` to a `dependency` reds
+ * with *"declared as runtime `dependencies` but `cursedbelt/react` never reaches them"*.
+ */
+const DEPS_THE_BARREL_NEED_NOT_REACH: Record<string, string> = {
+  // The one honest exception, and it is not a JS dependency at all: `src/styles.css`
+  // pulls it with a CSS `@import`, so no JS bundle can ever contain it. Deleting it
+  // ships a stylesheet that cannot resolve — see `declaredDepsAreImported.spec.ts`,
+  // which made exactly that mistake on its first pass.
+  'tw-animate-css': '@import-ed from src/styles.css; never reachable from a JS bundle',
 };
 
 
@@ -152,3 +218,45 @@ describe('barrels reach no optional peer statically', () => {
     });
   }
 });
+
+describe('every runtime dependency is one the barrel actually needs', () => {
+  const reached = staticExternalsOf('src/react/index.ts');
+  const declared = Object.keys(
+    (pkg as { dependencies?: Record<string, string> }).dependencies ?? {},
+  );
+
+  it('has measured a real barrel', () => {
+    // Guards the assertion below the same way the optional-peer half guards its own: an
+    // empty `reached` set would make every declared dependency look unreachable, and an
+    // empty `declared` list would make the test pass having proved nothing.
+    expect(reached.size, 'the bundle scan found no external imports at all').toBeGreaterThan(20);
+    expect(declared.length, 'package.json declares no runtime dependencies').toBeGreaterThan(20);
+  });
+
+  it('declares no dependency `cursedbelt/react` cannot reach', () => {
+    const unreachable = declared
+      .filter((name) => !reached.has(name) && DEPS_THE_BARREL_NEED_NOT_REACH[name] === undefined)
+      .sort();
+    expect(
+      unreachable,
+      'these are declared as runtime `dependencies` but `cursedbelt/react` never reaches them, ' +
+        'so every consumer installs them to render a Button and no barrel import can ever use ' +
+        'them. Make each one an OPTIONAL peer (`peerDependencies` + `peerDependenciesMeta.' +
+        '<name>.optional` + a `devDependencies` entry so this repo still typechecks it), which ' +
+        'is what `recharts` and the CodeMirror set already are. If it genuinely cannot be ' +
+        'reached from JS at all, add it to DEPS_THE_BARREL_NEED_NOT_REACH with the reason:\n  ' +
+        unreachable.join('\n  '),
+    ).toEqual([]);
+  });
+
+  it('keeps no excuse that has stopped being true', () => {
+    // An allowlist entry for a package that is no longer declared — or that the barrel now
+    // reaches anyway — is an excuse nobody re-reads. Same ratchet as `check-paths.ts`.
+    const stale = Object.keys(DEPS_THE_BARREL_NEED_NOT_REACH).filter(
+      (name) => !declared.includes(name) || reached.has(name),
+    );
+    expect(stale, 'DEPS_THE_BARREL_NEED_NOT_REACH excuses a dependency that needs no excuse').toEqual(
+      [],
+    );
+  });
+});

package/src/docsMatchTheSplit.spec.ts

@@ -0,0 +1,98 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'bun:test';
+
+/**
+ * 🔴 **The document a reader reads first may not claim a tier this package does not ship.**
+ *
+ * `cursedbelt` was one package and is now three: this React design system,
+ * `cursedbelt-core` beneath it, and the Bun/Hono server in `cursedbelt-server`.
+ * `package.json`'s `description` says so. `docs/API-REFERENCE.md` did not — until
+ * 2026-09-15 its "Foundation choices" list read:
+ *
+ *   > - Server: **Hono on Bun** (one framework). … DB: SQLite (bun:sqlite) + a
+ *   >   migration runner + Kysely-typed plumbing.
+ *
+ * That cost a real session real time: a task to build a **server-side request-telemetry
+ * sink** (Analytics Engine when bound, SQLite when not) was written against `cursedbelt`
+ * and fenced to it, on the strength of that sentence. The seam belongs in — and landed
+ * in — `cursedbelt-server@1.1.0`. A stale ownership claim in a doc is not a typo; it
+ * routes work to the wrong repo, where the gate cannot prove it (generation rule 3).
+ *
+ * So this is the check rather than a corrected sentence. Two halves, and BOTH matter:
+ * the code really is server-free, and the doc really says so.
+ */
+
+const ROOT = join(import.meta.dir, '..');
+const read = (rel: string) => readFileSync(join(ROOT, rel), 'utf8');
+
+/**
+ * Terms that name the server tier. If one appears in the doc, the SAME LINE must name the
+ * package that owns it — otherwise the line reads as a claim about this package.
+ */
+const SERVER_TIER_TERMS = [
+  'bun:sqlite',
+  'Hono on Bun',
+  'migration runner',
+  'Kysely',
+] as const;
+
+/** The packages a server-tier mention is allowed to be attributed to. */
+const OWNERS = ['cursedbelt-server', 'cursedbelt-core'] as const;
+
+/**
+ * The per-line excuse, because the rule has one honest false-positive class: a sentence
+ * that mentions a term in order to DENY it ("nothing here imports `bun:sqlite`") reads to
+ * a line matcher exactly like a claim. The generation's convention is to excuse the line
+ * and keep the rule — never to delete the rule — so this is spelled the same way
+ * `check-paths.ts` spells its own: an inline HTML comment carrying a reason.
+ *
+ *   <!-- split:ignore the reason -->
+ */
+const IGNORE = /<!--\s*split:ignore\b/;
+
+describe('this package ships no server tier', () => {
+  it('no file under src/ imports bun:sqlite or hono', async () => {
+    const offenders: string[] = [];
+    const files = new Bun.Glob('**/*.{ts,tsx}').scanSync({ cwd: join(ROOT, 'src') });
+    for (const rel of files) {
+      const text = readFileSync(join(ROOT, 'src', rel), 'utf8');
+      // Import/require of the module itself — not a mention inside a comment, which is
+      // how this very file talks about the split.
+      if (/(?:from|require\()\s*['"](?:bun:sqlite|hono(?:\/[^'"]*)?)['"]/.test(text)) {
+        offenders.push(`src/${rel}`);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+});
+
+describe('docs/API-REFERENCE.md does not claim the server tier', () => {
+  const doc = read('docs/API-REFERENCE.md');
+
+  it('attributes every server-tier mention to the package that owns it', () => {
+    const unattributed: string[] = [];
+    for (const [i, line] of doc.split('\n').entries()) {
+      if (!SERVER_TIER_TERMS.some((t) => line.includes(t))) continue;
+      if (OWNERS.some((owner) => line.includes(owner))) continue;
+      if (IGNORE.test(line)) continue;
+      unattributed.push(`docs/API-REFERENCE.md:${i + 1}: ${line.trim()}`);
+    }
+    // A line naming `bun:sqlite` or the migration runner WITHOUT naming
+    // `cursedbelt-server` is the 2026-09-15 defect, exactly.
+    expect(unattributed).toEqual([]);
+  });
+
+  it('says plainly, near the top, that the server tier is elsewhere', () => {
+    const top = doc.split('\n').slice(0, 20).join('\n');
+    expect(top).toContain('cursedbelt-server');
+    expect(top).toMatch(/ships NO server tier/i);
+  });
+
+  it("agrees with package.json's own description of the split", () => {
+    const { description } = JSON.parse(read('package.json')) as { description: string };
+    // The description is the claim the registry serves; the doc must not contradict it.
+    expect(description).toContain('cursedbelt-server');
+    expect(doc).toContain('cursedbelt-server');
+  });
+});

package/src/fixtureAppCss.spec.ts

@@ -0,0 +1,177 @@
+/**
+ * 🔴 The check three apps, then four, then five, were paying for the absence of:
+ * what a consuming app EMITS, measured from inside the package, and refused when
+ * it grows.
+ *
+ * ## Why it has to be here, and why it has to be a fixture
+ *
+ * `flix`, `patterns`, `collections`, `music` and `family` all ship the union of
+ * this design system. Every measurement of that cost was taken in a consumer, in a
+ * repo that cannot change the thing causing it — and none of them was taken twice,
+ * so nothing could tell whether the number was going up. This generation's third
+ * rule forbids the obvious fix: a repo's gate proves that repo, so no check here
+ * may reach into `apps/*`.
+ *
+ * So the package keeps its own consumer. `demo/fixtures/lean-app` is a small
+ * releases console — header, stat tiles, a chart, a sortable table, a virtualized
+ * log — built entirely out of cursedbelt's public subpaths, and
+ * `demo/fixtures/lean-app/app.css` is the stylesheet an app copies. Not the
+ * kitchen-sink demo: the demo renders every component, so its CSS can never
+ * shrink and a ratchet on it would measure nothing.
+ *
+ * ## The two halves, because either one alone is a lie
+ *
+ *   SIZE — the fixture's CSS on the area route is at or below the byte count in
+ *          `fixtureAppCss.baseline`, and materially below the union route it
+ *          replaces. `bun scripts/fixtureAppCss.ts --prune` lowers the baseline
+ *          and refuses to raise it.
+ *   TRUTH — the area route still emits every rule the fixture needs, and every
+ *          cursedbelt module the fixture reaches is covered by an area its
+ *          stylesheet declares. A stylesheet can always be made smaller by
+ *          emitting less than the app renders; that is what "unstyled" IS, and it
+ *          is the only failure mode this whole mechanism has.
+ *
+ * `scripts/fixtureAppCss.ts` owns the measurement and the baseline format; this
+ * file is the WHETHER.
+ */
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+import { flatten, lostRules, referenced } from '../scripts/cssRules';
+import {
+	BASELINE,
+	FIXTURE,
+	ROUTES,
+	areaRouteCss,
+	declaredAreas,
+	fixtureClosure,
+	fixtureImports,
+	measure,
+	missingNeeds,
+	readBaseline,
+	requiredCss,
+	uncoveredModules,
+	unionRouteCss,
+} from '../scripts/fixtureAppCss';
+import { REPO_ROOT } from '../scripts/generateStaticStyles';
+import { CORE } from '../scripts/styleAreas';
+
+const exportsMap = (pkg as { exports: Record<string, unknown> }).exports;
+const declared = await declaredAreas();
+const baseline = await readBaseline();
+const { union, areas } = await measure();
+
+/** The one command that changes any number below, as a line the owner can paste. */
+const REPRUNE = `cd ${REPO_ROOT} && bun scripts/fixtureAppCss.ts --prune`;
+
+describe('the fixture app measures a real consumer', () => {
+	it('imports cursedbelt the way an app does', async () => {
+		// Vacuity guard for the whole file: a fixture that imports nothing emits no
+		// cursedbelt CSS, so every size assertion below would pass triumphantly.
+		const imports = await fixtureImports();
+		expect(imports.length, `${FIXTURE} imports no cursedbelt subpath`).toBeGreaterThan(2);
+		const { modules, resolution } = await fixtureClosure(exportsMap);
+		expect(
+			resolution.unresolved,
+			`these imports in ${FIXTURE} cannot be attributed to a module, so no area can be\n` +
+				`checked against them:\n  ${resolution.unresolved.join('\n  ')}`,
+		).toEqual([]);
+		expect(modules.size, 'the fixture reaches almost nothing — it is not a realistic app').toBeGreaterThan(30);
+	});
+
+	it('declares core first, and the `needs` of everything it declares', () => {
+		expect(declared[0], `${FIXTURE}/app.css must import styles-areas/${CORE}.css first`).toBe(CORE);
+		expect(new Set(declared).size, 'an area is imported twice').toBe(declared.length);
+		const missing = missingNeeds(declared);
+		expect(
+			missing,
+			`${FIXTURE}/app.css declares an area without the areas it composes, so the parts of\n` +
+				`it that are subtracted into those areas render unstyled:\n  ${missing.join('\n  ')}`,
+		).toEqual([]);
+	});
+
+	it('declares an area for every cursedbelt module it reaches', async () => {
+		// 🔴 The assertion that stops the saving being fake. Under-declaring is the
+		// mistake an app makes — add a component, forget the `@import` — and its
+		// symptom is a component with no classes, three repos away, on a screen nobody
+		// opened during review.
+		const uncovered = await uncoveredModules(declared, exportsMap);
+		expect(
+			uncovered,
+			`${FIXTURE} renders these cursedbelt modules, and ${FIXTURE}/app.css imports no area\n` +
+				'that ships their CSS — so they render UNSTYLED. Add the area named beside each:\n  ' +
+				uncovered.join('\n  '),
+		).toEqual([]);
+	});
+});
+
+describe('the fixture app is materially smaller on the area route', () => {
+	it('has a baseline recording both routes', () => {
+		// A missing baseline must fail, not seed itself: a check that writes its own
+		// expectation the first time it runs can never fail again.
+		for (const route of ROUTES) {
+			expect(
+				baseline.counts.get(route),
+				`${BASELINE} records no \`${route}\` byte count. Seed it:\n  ${REPRUNE}`,
+			).toBeGreaterThan(0);
+		}
+	});
+
+	it('does not emit more CSS than the baseline allows', () => {
+		const grown = ROUTES.map((route) => ({ route, now: route === 'union' ? union : areas, was: baseline.counts.get(route) ?? 0 }))
+			.filter((r) => r.now > r.was)
+			.map((r) => `${r.route}: baseline allows ${r.was} B, it emits ${r.now} B now (+${r.now - r.was})`);
+		expect(
+			grown,
+			`the CSS a consuming app ships GREW. This is the check that exists because nothing\n` +
+				'measured it while five apps paid for the union. If the growth is deliberate — a new\n' +
+				`primitive in \`${CORE}\`, a component the fixture started rendering — raise the number in\n` +
+				`${BASELINE} by hand, in a commit that says why; \`--prune\` only lowers.\n  ` +
+				grown.join('\n  '),
+		).toEqual([]);
+	});
+
+	it('is a real saving, not a rounding error', () => {
+		// The ratio, not the absolute number: a ratchet on one count cannot tell a
+		// genuine saving from a design system that happened to shrink.
+		expect(union, 'the union route emitted almost nothing — the compile is broken').toBeGreaterThan(100_000);
+		expect(
+			areas / union,
+			`the area route emits ${areas} B against the union's ${union} B. If this stops being a\n` +
+				'material saving, the area map has collapsed back into the union and the split is\n' +
+				'carrying its cost for nothing.',
+		).toBeLessThan(0.8);
+	});
+});
+
+describe('the smaller stylesheet is not an unstyled one', () => {
+	it('emits every rule the fixture actually needs', async () => {
+		// The half a byte count cannot see. `requiredCss` is the fixture's own classes
+		// plus exactly the classes of the cursedbelt modules it reaches — nothing else
+		// — so anything missing here is a rule that would not reach the browser.
+		const [required, actual] = await Promise.all([requiredCss(exportsMap), areaRouteCss(declared)]);
+		const need = flatten(required);
+		const have = flatten(actual);
+		expect(need.size, 'the required stylesheet is empty — the comparison would be vacuous').toBeGreaterThan(200);
+		const readByRequired = referenced(required);
+		const { rules, declarations } = lostRules(need, have, (prop) => !readByRequired.has(prop));
+		expect(
+			rules,
+			`${FIXTURE} renders these selectors and its own stylesheet does not emit them —\n` +
+				'the app is UNSTYLED in exactly those places. Usually a missing area in\n' +
+				`${FIXTURE}/app.css:\n  ${rules.slice(0, 20).join('\n  ')}`,
+		).toEqual([]);
+		expect(
+			declarations,
+			`${FIXTURE} emits these selectors but not these declarations, so those components\n` +
+				`render PARTLY styled:\n  ${declarations.slice(0, 20).join('\n  ')}`,
+		).toEqual([]);
+	});
+
+	it('still emits everything the union route does for the fixture, minus what it does not render', async () => {
+		// The negative control for the assertion above: the union route is a superset
+		// by construction, so if the area route were somehow LARGER, `requiredCss` is
+		// measuring the wrong thing and the proof above is worthless.
+		const full = (await unionRouteCss()).length;
+		expect(areas).toBeLessThan(full);
+	});
+});

package/src/namedSubpathsResolve.spec.ts

@@ -54,6 +54,28 @@ const FILE_EXT = /\.(?!css$)[a-z0-9]+$/i;
 
 const exported = new Set(Object.keys(pkg.exports).map((k) => k.replace(/^\./, '')));
 
+/**
+ * A mention that STOPS at a placeholder, inside a subpath family that exists
+ * (2026-09-15, the `styles-areas/*` split).
+ *
+ * `@import "cursedbelt/styles-areas/${name}.css"` and the prose form
+ * `cursedbelt/styles-areas/<area>.css` are not copy-pasteable imports — they name
+ * a family, and `NAMED` truncates at the `$`/`<` because neither is a subpath
+ * character. Flagging them would mean 32 `subpath-check:ignore` markers on the
+ * lines that DOCUMENT the feature, which is how a gate gets turned off.
+ *
+ * Narrow on purpose, so a removed family still fails: exempt only when the match
+ * is a strict prefix of something `exports` actually has AND the next character in
+ * the line is the `/` the match could not consume. `cursedbelt/tokens/${x}` is
+ * still an offence, because nothing under `./tokens/` is exported.
+ */
+const familyPrefixes = new Set(
+	[...exported].flatMap((subpath) => {
+		const parts = subpath.split('/').filter(Boolean);
+		return parts.slice(0, -1).map((_, i) => `/${parts.slice(0, i + 1).join('/')}`);
+	}),
+);
+
 // This file and the task/report prose quoting the removal are allowed to name them.
 const SELF = 'namedSubpathsResolve.spec.ts';
 
@@ -77,6 +99,8 @@ const offences = (): Promise<Offence[]> => {
 						const subpath = m[1] ?? '';
 						if (exported.has(subpath)) continue;
 						if (REPO_DIRS.test(subpath) || FILE_EXT.test(subpath)) continue;
+						// A family name followed by the placeholder that truncated the match.
+						if (familyPrefixes.has(subpath) && line[(m.index ?? 0) + (m[0]?.length ?? 0)] === '/') continue;
 						found.push({ file: `${root}/${rel}`, line: i + 1, subpath, text: line.trim() });
 					}
 				}
@@ -106,6 +130,17 @@ describe('subpaths named in this repo resolve', () => {
 		expect(exported.has('/game')).toBe(false); // removed 2026-09-13
 	});
 
+	it('excuses a placeholder only inside a family that exists', () => {
+		// The control for the allowance above: it must not become "anything with a
+		// slash in it is fine". `/styles-areas/core.css` is exported, so the family is;
+		// `/tokens` was removed in task 33 and nothing under it is.
+		expect(familyPrefixes.has('/styles-areas')).toBe(true);
+		expect(familyPrefixes.has('/react')).toBe(true);
+		expect(familyPrefixes.has('/tokens')).toBe(false);
+		// And a whole-file subpath is never a family — `/styles.css` has no children.
+		expect(familyPrefixes.has('/styles.css')).toBe(false);
+	});
+
 	it('names no subpath package.json does not export', async () => {
 		const dead = await offences();
 		expect(

package/src/publishShape.spec.ts

@@ -35,6 +35,23 @@ const emittedInSrc = (): string[] => {
 	});
 };
 
+/**
+ * Every `types` condition, as `subpath → target`. Pure, so the assertion below has a
+ * negative control that does not need a broken manifest on disk to prove it works.
+ */
+const typesTargets = (exports: Record<string, unknown>): [string, string][] =>
+	Object.entries(exports).flatMap(([subpath, entry]) => {
+		if (typeof entry !== 'object' || entry === null) return [];
+		const target = (entry as Record<string, unknown>).types;
+		return typeof target === 'string' ? [[subpath, target] as [string, string]] : [];
+	});
+
+/** A `types` that is not a declaration file — tsc COMPILES those instead of reading them. */
+const typesThatAreNotDeclarations = (exports: Record<string, unknown>): string[] =>
+	typesTargets(exports)
+		.filter(([, target]) => !target.endsWith('.d.ts'))
+		.map(([subpath, target]) => `${subpath} → ${target}`);
+
 describe('publish shape', () => {
 	it('ships every directory its exports resolve into', () => {
 		const files = (pkg as { files?: string[] }).files ?? [];
@@ -86,4 +103,54 @@ describe('publish shape', () => {
 			.map(([k]) => k);
 		expect(wrong, `"types" must be the first condition:\n  ${wrong.join('\n  ')}`).toEqual([]);
 	});
+
+	it('🔴 points every "types" condition at a .d.ts, never at raw source', () => {
+		// ── What this cost, found 2026-09-15, fixed in task 172 ────────────────────────
+		// `./guardrails` shipped `"types": "./scripts/guardrailsEnforce.ts"` — the SOURCE.
+		// A consumer's `tsc` does not READ that the way it reads a declaration file, it
+		// pulls it into the consumer's own program and COMPILES it, under the consumer's
+		// `@types/node` and the consumer's strictness. `skipLibCheck` cannot help: it skips
+		// `.d.ts`, and this is not one, so there is no flag an app can set to opt out.
+		//
+		// So one wrong line here — `let entries: ReturnType<typeof readdirSync>`, which
+		// silently changed meaning when @types/node 24 made `Dirent` generic — became five
+		// errors in four apps' gates, in a file none of them wrote, that this repo's own
+		// typecheck had never compiled. `apps/flix`'s `bun run typecheck` was red on `main`
+		// for a reason that had nothing to do with flix.
+		//
+		// The type surface a package publishes must be its own compiler's OUTPUT, not its
+		// input: `dist/**/*.d.ts` is already checked here, by us, before it is emitted.
+		const raw = typesThatAreNotDeclarations(pkg.exports as unknown as Record<string, unknown>);
+		expect(
+			raw,
+			'these "types" conditions hand a consumer something tsc will COMPILE rather than read,\n' +
+				'so every consumer inherits our type errors and cannot suppress one (skipLibCheck skips\n' +
+				'.d.ts, and these are not). Emit a declaration into dist and point at that:\n  ' +
+				raw.join('\n  '),
+		).toEqual([]);
+	});
+
+	it('catches a raw-source "types" rather than passing on an empty manifest', () => {
+		// The negative control for the rule above, and it is the export that actually WAS
+		// broken. Without this, `typesThatAreNotDeclarations` could quietly stop matching
+		// anything — the assertion above would still be green, against nothing.
+		expect(
+			typesThatAreNotDeclarations({
+				'./guardrails': { types: './scripts/guardrailsEnforce.ts' },
+				'./button': { types: './dist/react/components/Button.d.ts' },
+				'./styles.css': './src/styles.css',
+			}),
+		).toEqual(['./guardrails → ./scripts/guardrailsEnforce.ts']);
+		// A `.tsx` component entry point is the same defect wearing the other extension,
+		// and a `.js` is one too — a consumer gets inferred-from-JS types or none at all.
+		expect(typesThatAreNotDeclarations({ './a': { types: './src/react/A.tsx' } })).toHaveLength(1);
+		expect(typesThatAreNotDeclarations({ './a': { types: './dist/a.js' } })).toHaveLength(1);
+	});
+
+	it('reads the real manifest, so the rule cannot pass vacuously', () => {
+		// `types` is what every conditional export in this package leads with; if the scan
+		// ever returns nothing, both assertions above are green about a manifest they never
+		// looked at.
+		expect(typesTargets(pkg.exports as unknown as Record<string, unknown>).length).toBeGreaterThan(40);
+	});
 });