cursedbelt 1.0.0 → 2.5.0

package/scripts/generateUtilityStyles.ts

@@ -0,0 +1,215 @@
+/**
+ * Generate `src/styles-utilities.css` — cursedbelt's component utilities, PRECOMPILED.
+ *
+ * ── The hole this fills ─────────────────────────────────────────────────────
+ * `src/styles-static.css` (the sibling generator, `generateStaticStyles.ts`) is
+ * `styles.css` minus its `@source "."`. It was shipped for "an app that pays for
+ * its own scanning" — and until this file existed, no app could pay. Tailwind v4
+ * (4.3.3, measured) resolves every `@source` to a DIRECTORY and scans it
+ * recursively: a file path is silently widened to its parent, a glob is widened
+ * the same way, and `@source not` over a package's own tree subtracts nothing.
+ * All four of these emit byte-for-byte identical CSS in a consuming app:
+ *
+ *   @source ".../cursedbelt/src/react/index.*";
+ *   @source ".../cursedbelt/src/react/styling.*";
+ *   @source ".../cursedbelt/src/react/Virtual*.tsx";
+ *   @source ".../cursedbelt/src/react/*.{ts,tsx}";
+ *
+ * `VirtualList` and `VirtualCardGrid` sit at the ROOT of `src/react/`, so the
+ * finest grain an app can ask for is that directory — whose recursive contents
+ * are the whole design system. Scanning it is the union; not scanning it is an
+ * UNSTYLED app. There was no third option, which made `styles-static.css` as
+ * published a subpath with no correct use. (It also retires a long-standing
+ * misreading: the previous generation's hand-written 29-line `@source` list in
+ * `satellite-kit` was never file-level scoping — every line was widened to its
+ * parent directory, which is why that arrangement still emitted ~113 KB.)
+ *
+ * So the utilities become a BUILD ARTIFACT: compiled once, here, and shipped.
+ * The consumer scans nothing.
+ *
+ * ── What it is worth, measured, so nobody re-runs this blind ────────────────
+ * 🔴 It is NOT smaller. Compiling cursedbelt's own surface both ways (this repo,
+ * tailwindcss 4.3.3, lightningcss-minified):
+ *
+ *   @import "cursedbelt/styles.css"                      131,795 B · 22,490 gz
+ *   styles-static.css + styles-utilities.css             131,741 B · 22,462 gz
+ *
+ * — a 54-byte difference, i.e. the same stylesheet by another route. The union
+ * is the union however it is assembled. The 10.3 kB gzip saving flix measured
+ * came from scanning exactly the 29 modules Rollup put in its chunk, and that is
+ * per-app tree-shaking, which no single shared artifact can do. What this DOES
+ * buy: `styles-static.css` gains a correct use, a consuming app stops reaching
+ * into another package's source tree from its CSS (a `file:` dependency wearing
+ * a stylesheet's clothes), and the app's Tailwind build stops walking 827 files
+ * it does not own. Reaching the 16 KB-of-utilities floor flix measured needs
+ * per-module CSS the bundler can tree-shake — a different, larger change.
+ *
+ * ── Why GENERATED, and what holds it honest ─────────────────────────────────
+ * Same bargain as `styles-static.css`: this script writes it, `bun run build`
+ * runs this script, and `src/stylesUtilitiesMatches.spec.ts` fails when what is
+ * on disk is not what `src/react/**` currently produces. That spec does not
+ * compare SIZE — an unstyled app is invisible to a byte count read in one
+ * direction — it compiles a consumer both ways and compares the emitted rules.
+ *
+ * Usage:
+ *   bun run styles:utilities            # write src/styles-utilities.css
+ *   bun run styles:utilities --check    # exit 1 if it is stale, write nothing
+ */
+import { compile } from '@tailwindcss/node';
+import { Scanner } from '@tailwindcss/oxide';
+import { REPO_ROOT, STATIC_STYLESHEET, readStylesheets } from './generateStaticStyles';
+
+export { REPO_ROOT };
+
+export const UTILITY_STYLESHEET = 'src/styles-utilities.css';
+
+/** Every relative specifier below resolves against `src/`, like `styles.css` does. */
+export const STYLES_BASE = `${REPO_ROOT}/src`;
+
+/**
+ * The compile input.
+ *
+ * `@reference` rather than `@import` for the two cursedbelt stylesheets: it makes
+ * their `@theme` tokens, `@custom-variant dark` and `tw-animate-css`'s `@utility`
+ * definitions available to the compiler while emitting NONE of their CSS — the
+ * consumer imports those files itself, and duplicating them here would be the
+ * drift this whole arrangement exists to prevent. Dropping the
+ * `@reference "./styles-static.css"` line costs 41 rules: every `animate-in` /
+ * `fade-out` / `slide-in-from-*` / `data-[state=open]:*` utility the dialog,
+ * tooltip and collapsible families animate with, plus
+ * `.animate-progress-indeterminate`.
+ *
+ * `./react` and not `.`: `.` would scan `src/` — including this file's own output,
+ * making each generation depend on the last one. It buys nothing anyway; the whole
+ * of `src/` outside `src/react` adds 32 bytes.
+ */
+export const UTILITY_INPUT = `@layer theme, base, components, utilities;
+@import "tailwindcss/theme.css" layer(theme);
+@reference "./styles-static.css";
+@reference "./theme.css";
+@import "tailwindcss/utilities.css" layer(utilities);
+@source "./react";
+`;
+
+/**
+ * What a consuming app's CSS is, today and after adoption — the two inputs
+ * `src/stylesUtilitiesMatches.spec.ts` compiles and compares rule by rule.
+ *
+ * `source(none)` on the second one is the point of the exercise: it forbids
+ * Tailwind from scanning anything at all, so whatever comes out is what the
+ * precompiled artifact supplies and nothing else. A real app drops it and keeps
+ * scanning its OWN sources.
+ */
+export const CONSUMER_SCANNING = '@import "tailwindcss";\n@import "./styles.css";\n@import "./theme.css";\n';
+export const CONSUMER_PRECOMPILED =
+	'@import "tailwindcss" source(none);\n' +
+	'@import "./styles-static.css";\n' +
+	'@import "./styles-utilities.css";\n' +
+	'@import "./theme.css";\n';
+
+/**
+ * A floor on the scan, because the failure this artifact can have is SILENT.
+ * If `src/react` moves, or a `.gitignore` starts swallowing it, or oxide's walk
+ * returns nothing, the compile still succeeds — it just emits an empty utility
+ * layer, and every consumer ships an unstyled app. 16,594 candidates today; this
+ * is a collapse tripwire, not a ratchet.
+ */
+export const MIN_CANDIDATES = 1_000;
+
+/** cursedbelt's stylesheets are self-contained — nothing here loads a JS config. */
+const noDependency = (): void => {};
+
+/** Compile one of the inputs above against `src/`. */
+export const compileStylesheet = (
+	input: string,
+): ReturnType<typeof compile> => compile(input, { base: STYLES_BASE, onDependency: noDependency });
+
+/** The banner the artifact carries, so a reader never mistakes it for a source file. */
+export const BANNER = `/*
+ * cursedbelt component utilities — GENERATED BUILD ARTIFACT. Never hand-edit.
+ *
+ * Every Tailwind utility class cursedbelt's own components (\`src/react/**\`) use,
+ * compiled once at this package's build time so a consuming app does not have to
+ * scan this package's source tree — which Tailwind v4 cannot do at any grain
+ * finer than "the whole design system" anyway. Import it after Tailwind itself,
+ * beside the static entry point:
+ *
+ *   @import "tailwindcss";
+ *   @import "cursedbelt/styles-static.css";
+ *   @import "cursedbelt/styles-utilities.css";
+ *   @import "cursedbelt/theme.css";
+ *
+ * That pair emits the same rules as \`@import "cursedbelt/styles.css"\` — proved
+ * rule by rule, not by byte count, in src/stylesUtilitiesMatches.spec.ts. It is
+ * not SMALLER; see the header of scripts/generateUtilityStyles.ts for the
+ * measurements and for what it does buy.
+ *
+ * Written by scripts/generateUtilityStyles.ts (\`bun run styles:utilities\`),
+ * which \`bun run build\` runs. src/stylesUtilitiesMatches.spec.ts fails when what
+ * is on disk is not what src/react/** currently produces.
+ */
+`;
+
+/**
+ * Compile the utility layer from `src/react/**`.
+ *
+ * Refuses to run against a stale `styles-static.css`, rather than quietly baking
+ * the stale one's tokens in: the two artifacts are generated from the same
+ * `styles.css`, and `bun run build` orders them, but `bun run styles:utilities`
+ * on its own would not.
+ */
+export const buildUtilityStyles = async (): Promise<{ css: string; candidates: string[] }> => {
+	const { expected, onDisk } = await readStylesheets();
+	if (onDisk !== expected) {
+		throw new Error(
+			`${STATIC_STYLESHEET} is ${onDisk === null ? 'missing' : 'stale'}, and this artifact is compiled\n` +
+				`against it (\`@reference\`), so it would bake in the wrong tokens. Run:\n` +
+				`  cd ${REPO_ROOT} && bun run styles:static`,
+		);
+	}
+	const compiled = await compileStylesheet(UTILITY_INPUT);
+	const candidates = new Scanner({ sources: compiled.sources }).scan();
+	if (candidates.length < MIN_CANDIDATES) {
+		throw new Error(
+			`the scan of src/react found ${candidates.length} candidates (floor ${MIN_CANDIDATES}).\n` +
+				'That is a collapsed scan, not a small design system — the artifact it would write\n' +
+				'emits an empty utility layer and every consuming app ships UNSTYLED. Check that\n' +
+				`${STYLES_BASE}/react exists and is not excluded by a .gitignore.`,
+		);
+	}
+	return { css: `${BANNER}${compiled.build(candidates)}`, candidates };
+};
+
+/** The artifact's expected contents and what is on disk right now. */
+export const readUtilityStylesheet = async (): Promise<{
+	expected: string;
+	onDisk: string | null;
+	candidates: string[];
+}> => {
+	const { css, candidates } = await buildUtilityStyles();
+	const target = Bun.file(`${REPO_ROOT}/${UTILITY_STYLESHEET}`);
+	return { expected: css, onDisk: (await target.exists()) ? await target.text() : null, candidates };
+};
+
+if (import.meta.main) {
+	const { expected, onDisk, candidates } = await readUtilityStylesheet();
+	if (process.argv.includes('--check')) {
+		if (onDisk === expected) {
+			console.log(`✅ ${UTILITY_STYLESHEET} is current (${candidates.length} candidates).`);
+			process.exit(0);
+		}
+		console.error(
+			`❌ ${UTILITY_STYLESHEET} is ${onDisk === null ? 'missing' : 'stale'}. Run:\n` +
+				`     cd ${REPO_ROOT} && bun run styles:utilities`,
+		);
+		process.exit(1);
+	}
+	if (onDisk === expected) {
+		console.log(`✅ ${UTILITY_STYLESHEET} already current (${candidates.length} candidates).`);
+	} else {
+		await Bun.write(`${REPO_ROOT}/${UTILITY_STYLESHEET}`, expected);
+		console.log(
+			`✅ wrote ${UTILITY_STYLESHEET} — ${candidates.length} candidates scanned from src/react.`,
+		);
+	}
+}

package/scripts/publicSurface.ts

@@ -0,0 +1,455 @@
+#!/usr/bin/env bun
+/**
+ * `bun scripts/publicSurface.ts [--prune]` — refuse a public surface that grows
+ * without a recorded reason.
+ *
+ * ## What this exists for
+ *
+ * Measured 2026-09-13 across all 845 consumer files on this machine that mention
+ * `cursedbelt`: `1.0.0` published **108 export subpaths and 3,359 exported
+ * symbols**, of which every consumer together imported **406 — 12.1%**.
+ * `cursedbelt/react` alone exposed 1,037 and 178 were used. Nothing objected at
+ * any single step, because no single step was large; the owner's own account of
+ * how it got there is *"worked on over many projects with tons of features
+ * changing"*.
+ *
+ * 🔴 **This is NOT a dead-code check, and 12.1% is not a bug to delete.** Most of
+ * that surface is alive: the `react` barrel re-exports components that live
+ * imports keep mounted, and a design system is SUPPOSED to ship more than any one
+ * app has adopted. Deleting everything safely deletable removed 4% of the package
+ * (tasks 32/33). What was missing was not restraint, it was an INSTRUMENT — the
+ * total was never measured anywhere, so growth was invisible at the only moment
+ * anyone could have judged it. This file makes growth visible and deliberate; it
+ * does not forbid it.
+ *
+ * Both rows below are a DATED RECORD, not a live claim — the live number is
+ * `publicSurface.baseline`, checked against the tree every run, and it can only
+ * go down from the second row:
+ *
+ *                                subpaths   symbols   dependencies   peers
+ *     1.0.0, before tasks 32/33       108     4,167             47      51
+ *     seeded 2026-09-13                85     3,808             44      47
+ *
+ * 🔴 Both rows were measured by THIS file, run against `c01b119` and against the
+ * tree it was seeded from, so they are commensurable with each other and with
+ * every future run. They are NOT the 3,359 in the task that asked for this file:
+ * that number came from an independent walk of the same shape, and this one counts
+ * 4,167 for the same tree. The gap is method, not surface — a `default` export,
+ * a destructured `export const {a, b}`, and a bare `export * from 'cwip/layout'`
+ * are each counted here and were not counted there. Which is the point of the
+ * "What it counts, exactly" section below: two numbers that do not say what they
+ * counted cannot be compared, and only one of them can be a ratchet.
+ *
+ * `subpaths` excludes the three stylesheet exports, which have no symbols; the
+ * `exports` map has three more keys than the count above. The dependency columns
+ * are the second half of the same failure and are asserted by
+ * `src/declaredDepsAreImported.spec.ts` — see "The dependency half" below.
+ *
+ * This file is the reason that second row cannot quietly become the first one
+ * again: **document the WHY; automate the WHETHER.** A paragraph in a doc asking
+ * the next agent to think about whether a new subpath is needed is the failure
+ * mode, not the fix.
+ *
+ * ## The ratchet
+ *
+ * `publicSurface.baseline` holds a COUNT PER SUBPATH, the same shape as
+ * `tools/check-paths.baseline`, which is the mechanism this generation already
+ * trusts. Four ways to fail, and the last two are what make it a ratchet rather
+ * than a high-water mark:
+ *
+ *   1. a subpath in `exports` that the baseline does not list       → NEW SURFACE
+ *   2. a listed subpath whose symbol count went UP                  → GREW
+ *   3. a listed subpath whose count went DOWN, or that is gone      → run --prune
+ *   4. an entry matching no subpath at all                          → run --prune
+ *
+ * (3) and (4) mean a deleted module cannot leave a stale allowance behind for the
+ * next module to grow into. Inherited surface can only fall.
+ *
+ * `--prune` records the burn-down in one deliberate command and REFUSES to raise
+ * anything, so a genuine new export is `--prune`-then-review rather than a number
+ * edited by hand, and it shows up in the diff as surface.
+ *
+ * ## 🔴 What it counts, exactly — and what it does not
+ *
+ * A count is only worth having if it says what it counted; a count that silently
+ * measures less than it claims is a guess wearing a measurement's clothes. This
+ * walks, per export subpath in `package.json`, the TypeScript AST of the entry
+ * module and every `export * from` beneath it, transitively, deduped by name:
+ *
+ *   · `export const/let/var/function/class/interface/type/enum/namespace`
+ *   · `export { x }`, `export { x as y }`, `export type { x }`
+ *   · `export * as ns from './m'`  (one symbol: `ns`)
+ *   · `export default` / `export default function Foo` (one symbol: `default`)
+ *   · `export * from './m'`        (transitive; cycles are visited once)
+ *   · `export * from 'some-package'` — RESOLVED and walked, not skipped. There is
+ *     one today (`src/core/layout/index.ts` re-exports `cwip/layout`) and a
+ *     package's symbols re-exported under this package's name are this package's
+ *     surface. If such a specifier ever resolves to something this cannot parse
+ *     (a `.js` build with no types), the run FAILS rather than counting zero.
+ *
+ * Deliberately NOT counted, each because counting it would make the number lie:
+ *
+ *   · non-TS export targets — `./styles.css`, `./theme.css`, `./workspace.css`.
+ *     A stylesheet has no symbols. They are reported as "asset export(s)" so they
+ *     cannot vanish from the accounting.
+ *   · anything not reachable from an `exports` subpath. Internal modules are not
+ *     public surface. What `src/react/components/**` contains is not the measure;
+ *     what the `./react` barrel re-exports is.
+ *   · the two `bin` targets, `cc-verify` and `cc-promote`. 🔴 They ARE public
+ *     surface — and they are NOT reachable through `exports`, which is exactly why
+ *     an earlier reachability walk seeded from `exports` alone reported a shipped
+ *     CLI as removable. A CLI's interface is its argv, not its export list, so
+ *     counting its exported symbols would measure the wrong thing. Their SHAPE is
+ *     already asserted by `src/publishShape.spec.ts` ("declares bin paths npm will
+ *     actually keep"), and nothing here concludes anything is dead — this tool
+ *     only ever compares `cursedbelt` to its own baseline.
+ *
+ * ## What this may NOT become
+ *
+ *   · Not a usage check. It must never try to know who imports `cursedbelt`; that
+ *     is cross-repo, and a repo's gate proves that repo.
+ *   · Not a ban on growth. New surface is one hand-added line plus a commit
+ *     message that says why — a reviewable moment, not a wall.
+ *   · Not a second guard. One check, one baseline, entry criteria in this header.
+ *
+ * ## The dependency half
+ *
+ * 47 hard dependencies is the number that decides what a consumer pays, and it is
+ * surface by the same argument. It is NOT re-checked here, because it is already
+ * checked once: `src/declaredDepsAreImported.spec.ts` fails on any `dependencies`
+ * or `peerDependencies` entry that no file under `src/` or `scripts/` imports, and
+ * `src/noPathDeps.spec.ts` fails on a `file:`/`link:`/`workspace:`/`portal:` range
+ * in any dependency block. Two ratchets that disagree is the guard sprawl this
+ * generation is trying to avoid, so this file points at them instead of repeating
+ * them.
+ *
+ * 🔴 If you ever move that check here, keep the property that made it correct: it
+ * scans EVERY file type, not just `.ts`. `tw-animate-css` is imported from
+ * `src/styles.css` and a `.ts`-only scan calls it dead.
+ *
+ * Exit 1 on any failure, so it can sit in a verify chain. It sits in the suite
+ * instead — `src/publicSurface.spec.ts` — so `bun run verify` needs no new script
+ * and cannot be a script somebody forgot to chain.
+ */
+import { dirname, join } from 'node:path';
+import ts from 'typescript';
+
+// Resolved from this file, never from `process.cwd()`: the suite imports it and
+// `bun test` can be started from anywhere.
+const ROOT = dirname(import.meta.dir);
+const BASELINE = join(ROOT, 'publicSurface.baseline');
+
+const DEFAULT_HEADER = [
+	'# Public surface of `cursedbelt`: one line per export subpath, `<exported symbols>  <subpath>`.',
+	'#',
+	'# A CEILING, not an amnesty. The check fails on a subpath NOT listed here, on a listed',
+	'# subpath that gained a symbol, and on an entry that no longer matches `package.json`',
+	'# exports — so a deleted module cannot leave a stale allowance behind. Surface can only fall.',
+	'#',
+	'# To record a deliberate change:  bun scripts/publicSurface.ts --prune',
+	'# It refuses to RAISE anything, so new surface is a reviewed diff, never a silent one.',
+	'#',
+	'# What a count includes, what it excludes and why, and the measurement this file is a',
+	'# ratchet against, are in the header of scripts/publicSurface.ts. Say nothing here that',
+	'# the entries below already say.',
+];
+
+export type Surface = {
+	/** subpath (as written in `exports`) → deduped exported symbol count */
+	counts: Map<string, number>;
+	/** subpaths skipped because they resolve to a non-TS asset (the three stylesheets) */
+	assets: string[];
+};
+
+const isRelative = (spec: string): boolean => spec.startsWith('./') || spec.startsWith('../');
+const isWalkable = (file: string): boolean => /\.(m|c)?tsx?$/.test(file);
+
+/** `./a/b` from `src/x/y.tsx` → the first of `src/a/b.ts(x)`, `src/a/b/index.ts(x)`, … that exists. */
+const resolveRelative = async (fromFile: string, spec: string): Promise<string | null> => {
+	const base = join(dirname(fromFile), spec);
+	const candidates = [`${base}.ts`, `${base}.tsx`, `${base}/index.ts`, `${base}/index.tsx`, base];
+	for (const c of candidates) {
+		if (await Bun.file(c).exists()) return c;
+	}
+	return null;
+};
+
+/**
+ * A bare `export * from 'pkg'` — resolved through node resolution so its symbols
+ * are counted rather than silently dropped. Throws when the package resolves to
+ * something with no parseable types, because a zero there would be a lie.
+ */
+const resolveBare = (fromFile: string, spec: string): string => {
+	let resolved: string;
+	try {
+		resolved = Bun.resolveSync(spec, dirname(fromFile));
+	} catch (cause) {
+		throw new Error(
+			`${fromFile}: \`export * from '${spec}'\` re-exports a package that does not resolve, so its ` +
+				'symbols cannot be counted. Install it, or name the symbols — do not let the count lie.',
+			{ cause },
+		);
+	}
+	if (!isWalkable(resolved)) {
+		throw new Error(
+			`${fromFile}: \`export * from '${spec}'\` resolves to ${resolved}, which this measurement cannot ` +
+				'parse. Point it at TypeScript, name the symbols, or teach scripts/publicSurface.ts to read ' +
+				'a declaration bundle — do not let the count lie.',
+		);
+	}
+	return resolved;
+};
+
+// One parse per file, shared across all 88 subpaths: the barrels overlap heavily
+// (every `./react/*` subpath re-parses a slice of what `./react` already walked).
+const parsed = new Map<string, ts.SourceFile>();
+const sourceOf = async (file: string): Promise<ts.SourceFile> => {
+	const hit = parsed.get(file);
+	if (hit !== undefined) return hit;
+	// 🔴 Bun.file, NOT node:fs — this package's test preload shares one process with
+	// specs that virtualize node:fs, so a readFileSync scan reads MOCK data and the
+	// measurement passes against files it never opened. Same trap as
+	// publishShape.spec.ts; see its header.
+	const source = ts.createSourceFile(file, await Bun.file(file).text(), ts.ScriptTarget.ES2022, true);
+	parsed.set(file, source);
+	return source;
+};
+
+/** Every name a binding pattern introduces — `export const { a, b: [c] } = …` is three. */
+const bindingNames = (name: ts.BindingName, out: Set<string>): void => {
+	if (ts.isIdentifier(name)) {
+		out.add(name.text);
+		return;
+	}
+	for (const el of name.elements) {
+		if (ts.isBindingElement(el)) bindingNames(el.name, out);
+	}
+};
+
+/** Deduped exported names of `file`, following `export * from` chains. */
+const exportedNames = async (file: string, seen = new Set<string>()): Promise<Set<string>> => {
+	const names = new Set<string>();
+	if (seen.has(file)) return names;
+	seen.add(file);
+
+	const source = await sourceOf(file);
+	const modifiersOf = (node: ts.Node): readonly ts.Modifier[] =>
+		ts.canHaveModifiers(node) ? (ts.getModifiers(node) ?? []) : [];
+
+	for (const st of source.statements) {
+		if (ts.isExportDeclaration(st)) {
+			if (st.exportClause && ts.isNamedExports(st.exportClause)) {
+				for (const el of st.exportClause.elements) names.add(el.name.text);
+			} else if (st.exportClause && ts.isNamespaceExport(st.exportClause)) {
+				names.add(st.exportClause.name.text);
+			} else {
+				const spec =
+					st.moduleSpecifier && ts.isStringLiteral(st.moduleSpecifier) ? st.moduleSpecifier.text : null;
+				if (spec === null) continue;
+				let target: string | null;
+				if (isRelative(spec)) {
+					target = await resolveRelative(file, spec);
+					if (target === null) throw new Error(`${file}: \`export * from '${spec}'\` resolves to nothing.`);
+				} else {
+					target = resolveBare(file, spec);
+				}
+				for (const n of await exportedNames(target, seen)) names.add(n);
+			}
+			continue;
+		}
+		if (ts.isExportAssignment(st)) {
+			names.add('default');
+			continue;
+		}
+		const modifiers = modifiersOf(st);
+		if (!modifiers.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)) continue;
+		// `export default function Foo()` is imported as `default`, not as `Foo`.
+		if (modifiers.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)) {
+			names.add('default');
+			continue;
+		}
+		if (ts.isVariableStatement(st)) {
+			for (const d of st.declarationList.declarations) bindingNames(d.name, names);
+		} else if (
+			(ts.isFunctionDeclaration(st) ||
+				ts.isClassDeclaration(st) ||
+				ts.isInterfaceDeclaration(st) ||
+				ts.isTypeAliasDeclaration(st) ||
+				ts.isEnumDeclaration(st) ||
+				ts.isModuleDeclaration(st)) &&
+			st.name !== undefined
+		) {
+			if (ts.isIdentifier(st.name) || ts.isStringLiteral(st.name)) names.add(st.name.text);
+		}
+	}
+	return names;
+};
+
+/** The `./src/**` or `./scripts/**` TypeScript file a subpath resolves to, or null when it is an asset. */
+const entryOf = (value: unknown): string | null => {
+	if (typeof value === 'string')
+		return (value.startsWith('./src/') || value.startsWith('./scripts/')) && isWalkable(value)
+			? join(ROOT, value.slice(2))
+			: null;
+	if (typeof value !== 'object' || value === null) return null;
+	// `bun` and `source` are the conditions that point at TypeScript; `types` and
+	// `import` point into `dist`, which is build output and may not exist. Reading
+	// the conditions in this order is what makes the measurement work on a clean
+	// checkout, before `bun run build` has ever run.
+	for (const key of ['bun', 'source', 'types', 'import', 'default']) {
+		if (key in (value as Record<string, unknown>)) {
+			const hit = entryOf((value as Record<string, unknown>)[key]);
+			if (hit !== null) return hit;
+		}
+	}
+	for (const v of Object.values(value as Record<string, unknown>)) {
+		const hit = entryOf(v);
+		if (hit !== null) return hit;
+	}
+	return null;
+};
+
+export const measureSurface = async (pkg: { exports: Record<string, unknown> }): Promise<Surface> => {
+	const counts = new Map<string, number>();
+	const assets: string[] = [];
+	for (const [subpath, value] of Object.entries(pkg.exports)) {
+		const entry = entryOf(value);
+		if (entry === null) {
+			assets.push(subpath);
+			continue;
+		}
+		counts.set(subpath, (await exportedNames(entry)).size);
+	}
+	return { counts, assets };
+};
+
+// ── the baseline ────────────────────────────────────────────────────────────────
+
+export type Baseline = { header: string[]; counts: Map<string, number> };
+
+export const parseBaseline = (text: string): Baseline => {
+	const header = text.split('\n').filter((l) => l.startsWith('#'));
+	const counts = new Map<string, number>();
+	for (const line of text.split('\n')) {
+		if (!line.trim() || line.startsWith('#')) continue;
+		const m = line.match(/^\s*(\d+)\s+(\S.*)$/);
+		if (m?.[2] !== undefined) counts.set(m[2].trim(), Number(m[1]));
+	}
+	return { header: header.length > 0 ? header : DEFAULT_HEADER, counts };
+};
+
+export const readBaseline = async (): Promise<Baseline> => {
+	const f = Bun.file(BASELINE);
+	return parseBaseline((await f.exists()) ? await f.text() : '');
+};
+
+export const formatBaseline = (header: string[], counts: Map<string, number>): string =>
+	`${[...header, ...[...counts.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([k, n]) => `${n}  ${k}`)].join(
+		'\n',
+	)}\n`;
+
+export type Failures = { grown: string[]; fresh: string[]; stale: string[] };
+
+export const compare = (surface: Surface, baseline: Baseline): Failures => {
+	const fresh: string[] = [];
+	const grown: string[] = [];
+	for (const [subpath, n] of surface.counts) {
+		const allowed = baseline.counts.get(subpath);
+		if (allowed === undefined) fresh.push(`${subpath}  — NEW subpath, ${n} exported symbol(s)`);
+		else if (n > allowed) grown.push(`${subpath}  — baseline allows ${allowed}, exports ${n} now`);
+	}
+	const stale = [...baseline.counts.entries()]
+		.filter(([subpath, n]) => (surface.counts.get(subpath) ?? 0) < n)
+		.map(([subpath, n]) =>
+			surface.counts.has(subpath)
+				? `${subpath}  — baseline says ${n}, exports ${surface.counts.get(subpath)}`
+				: `${subpath}  — baseline says ${n}, the subpath is gone`,
+		);
+	return { fresh, grown, stale };
+};
+
+export const run = async (): Promise<Failures & { surface: Surface; baseline: Baseline }> => {
+	const pkg = (await Bun.file(join(ROOT, 'package.json')).json()) as { exports: Record<string, unknown> };
+	const surface = await measureSurface(pkg);
+	const baseline = await readBaseline();
+	return { ...compare(surface, baseline), surface, baseline };
+};
+
+// ── CLI ─────────────────────────────────────────────────────────────────────────
+
+if (import.meta.main) {
+	const argv = process.argv.slice(2);
+	const prune = argv.includes('--prune');
+	const { fresh, grown, stale, surface, baseline } = await run();
+	const total = [...surface.counts.values()].reduce((a, b) => a + b, 0);
+
+	// `--seed` exists once, to record the surface the ratchet starts from. It REFUSES
+	// over an existing baseline, so re-seeding means deleting the file first — two
+	// visible steps and a whole-file diff, rather than one command that quietly
+	// re-baselines whatever grew.
+	if (argv.includes('--seed')) {
+		if (baseline.counts.size > 0) {
+			console.error(`publicSurface --seed refuses: ${BASELINE} already records ${baseline.counts.size} subpath(s).`);
+			console.error('Lower it with --prune. Raising it is a hand edit in a commit that says why.');
+			process.exit(1);
+		}
+		await Bun.write(BASELINE, formatBaseline(baseline.header, surface.counts));
+		console.log(`publicSurface: seeded ${surface.counts.size} subpath(s), ${total} exported symbol(s).`);
+		process.exit(0);
+	}
+
+	if (prune) {
+		// 🔴 It may only LOWER. Growth is the thing this file exists to make visible;
+		// a prune that could absorb it would be the disable switch.
+		if (fresh.length > 0 || grown.length > 0) {
+			console.error('publicSurface --prune refuses while the surface has GROWN — it may only lower the baseline.\n');
+			for (const v of [...fresh, ...grown]) console.error(`  ${v}`);
+			console.error(
+				'\nTo record deliberate new surface, add the line by hand and say in the commit message why the\npackage needs it — that is the reviewable moment this check exists to create.\n',
+			);
+			process.exit(1);
+		}
+		const lowered = new Map<string, number>();
+		for (const [subpath, n] of baseline.counts) {
+			const now = surface.counts.get(subpath);
+			if (now !== undefined) lowered.set(subpath, Math.min(n, now));
+		}
+		await Bun.write(BASELINE, formatBaseline(baseline.header, lowered));
+		console.log(
+			`publicSurface: baseline pruned to ${lowered.size} subpath(s), ` +
+				`${baseline.counts.size - lowered.size} removed, ${[...lowered.values()].reduce((a, b) => a + b, 0)} symbols.`,
+		);
+		process.exit(0);
+	}
+
+	let bad = false;
+	const report = (label: string, lines: string[], advice: string): void => {
+		if (lines.length === 0) return;
+		bad = true;
+		console.error(`\n${lines.length} ${label}:\n`);
+		for (const l of lines) console.error(`  ${l}`);
+		console.error(`\n${advice}\n`);
+	};
+	report(
+		'export subpath(s) the baseline does not know',
+		fresh,
+		'A new subpath is a permanent public promise. If it is genuinely wanted, add its line to\n' +
+			`${BASELINE} and say why in the commit message.`,
+	);
+	report(
+		'subpath(s) that gained exported symbols',
+		grown,
+		'A baseline entry is a ceiling. Raise it by hand, in a commit that says why.',
+	);
+	report(
+		'baseline entr(y|ies) that no longer match `exports`',
+		stale,
+		`Surface came off and the ratchet was not tightened. Run:\n  cd ${ROOT} && bun scripts/publicSurface.ts --prune`,
+	);
+	if (bad) process.exit(1);
+
+	console.log(
+		`publicSurface: ${surface.counts.size} subpath(s), ${total} exported symbol(s), ` +
+			`${surface.assets.length} asset export(s) — none grown.`,
+	);
+}