cursedbelt 4.4.0 → 4.6.0

package/src/react/workbook-viewer/WorkbookViewer.tsx

@@ -1,13 +1,13 @@
 import { type GridCell, GridCellKind, type GridColumn } from '@glideapps/glide-data-grid';
 import { useCallback, useEffect, useMemo, useState } from 'react';
-import { Button } from '../components/Button';
-import { EmptyState } from '../components/EmptyState';
-import { SegmentedControl } from '../components/SegmentedControl';
-import { Skeleton } from '../components/Skeleton';
-import { cn } from '../lib/cn';
-import { SpreadsheetGrid } from '../spreadsheet/SpreadsheetGrid';
-import { useTokenColor } from '../spreadsheet/useGlideTheme';
-import { useGridSelection } from '../spreadsheet/useGridSelection';
+import { Button } from '../components/Button.js';
+import { EmptyState } from '../components/EmptyState.js';
+import { SegmentedControl } from '../components/SegmentedControl.js';
+import { Skeleton } from '../components/Skeleton.js';
+import { cn } from '../lib/cn.js';
+import { SpreadsheetGrid } from '../spreadsheet/SpreadsheetGrid.js';
+import { useTokenColor } from '../spreadsheet/useGlideTheme.js';
+import { useGridSelection } from '../spreadsheet/useGridSelection.js';
 import {
   type CellRange,
   cellAddress,
@@ -17,7 +17,7 @@ import {
   sheetRangeToMarkdown,
   sheetRangeToTsv,
   type Workbook,
-} from './parseWorkbook';
+} from './parseWorkbook.js';
 
 /*
  * WorkbookViewer — a spreadsheet as the author saw it, for READING and COPYING.

package/src/react/workbook-viewer/index.ts

@@ -18,5 +18,5 @@ export {
   sheetRangeToMarkdown,
   sheetRangeToTsv,
   type Workbook,
-} from './parseWorkbook';
-export { WorkbookViewer, type WorkbookViewerProps } from './WorkbookViewer';
+} from './parseWorkbook.js';
+export { WorkbookViewer, type WorkbookViewerProps } from './WorkbookViewer.js';

package/src/react/workbook-viewer/parseWorkbook.spec.ts

@@ -6,7 +6,7 @@ import {
   rangeAddress,
   sheetRangeToMarkdown,
   sheetRangeToTsv,
-} from './parseWorkbook';
+} from './parseWorkbook.js';
 
 // The parse half of the workbook viewer. Two properties matter more than the rest:
 //   • The grid is the sheet AS IT IS — no header promotion, no dropped blank rows — because a

package/src/styles-areas/code-editor.css

@@ -15,7 +15,7 @@
  *
  * An app that imports every area gets exactly what `cursedbelt/styles-utilities.css`
  * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
- * when this file is stale. 263 candidate(s) scanned.
+ * when this file is stale. 262 candidate(s) scanned.
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are

package/src/styles-areas/core.css

@@ -13,7 +13,7 @@
  *
  * An app that imports every area gets exactly what `cursedbelt/styles-utilities.css`
  * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
- * when this file is stale. 5186 candidate(s) scanned.
+ * when this file is stale. 5187 candidate(s) scanned.
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are

package/src/styles-areas/data-table.css

@@ -15,7 +15,7 @@
  *
  * An app that imports every area gets exactly what `cursedbelt/styles-utilities.css`
  * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
- * when this file is stale. 1347 candidate(s) scanned.
+ * when this file is stale. 1349 candidate(s) scanned.
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are

package/src/styles-areas/deep-link.css

@@ -15,7 +15,7 @@
  *
  * An app that imports every area gets exactly what `cursedbelt/styles-utilities.css`
  * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
- * when this file is stale. 186 candidate(s) scanned.
+ * when this file is stale. 188 candidate(s) scanned.
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are

package/src/styles-areas/diff-viewer.css

@@ -15,7 +15,7 @@
  *
  * An app that imports every area gets exactly what `cursedbelt/styles-utilities.css`
  * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
- * when this file is stale. 74 candidate(s) scanned.
+ * when this file is stale. 73 candidate(s) scanned.
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are

package/src/styles-areas/media-gallery.css

@@ -15,7 +15,7 @@
  *
  * An app that imports every area gets exactly what `cursedbelt/styles-utilities.css`
  * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
- * when this file is stale. 2115 candidate(s) scanned.
+ * when this file is stale. 2162 candidate(s) scanned.
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are

package/src/styles-areas/media.css

@@ -15,7 +15,7 @@
  *
  * An app that imports every area gets exactly what `cursedbelt/styles-utilities.css`
  * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
- * when this file is stale. 2825 candidate(s) scanned.
+ * when this file is stale. 2849 candidate(s) scanned.
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are

package/src/styles-areas/pdf-viewer.css

@@ -15,7 +15,7 @@
  *
  * An app that imports every area gets exactly what `cursedbelt/styles-utilities.css`
  * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
- * when this file is stale. 87 candidate(s) scanned.
+ * when this file is stale. 86 candidate(s) scanned.
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are

package/src/stylesAreas.spec.ts

@@ -36,8 +36,8 @@
  */
 import { describe, expect, it } from 'bun:test';
 import pkg from '../package.json';
-import { flatten, lostRules, referenced } from '../scripts/cssRules';
-import { REPO_ROOT } from '../scripts/generateStaticStyles';
+import { flatten, lostRules, referenced } from '../scripts/cssRules.js';
+import { REPO_ROOT } from '../scripts/generateStaticStyles.js';
 import {
 	AREAS,
 	CORE,
@@ -46,8 +46,8 @@ import {
 	areaSubpath,
 	readAreaStyles,
 	strayAreaFiles,
-} from '../scripts/generateAreaStyles';
-import { compileStylesheet } from '../scripts/generateUtilityStyles';
+} from '../scripts/generateAreaStyles.js';
+import { compileStylesheet } from '../scripts/generateUtilityStyles.js';
 import {
 	allModules,
 	areaClosures,
@@ -56,7 +56,7 @@ import {
 	needsGraphFault,
 	nonModuleFiles,
 	transitiveNeeds,
-} from '../scripts/styleAreas';
+} from '../scripts/styleAreas.js';
 
 const areas = await readAreaStyles();
 const { closures } = await areaClosures();

package/src/stylesStaticMatches.spec.ts

@@ -42,7 +42,7 @@ import {
 	STATIC_STYLESHEET,
 	readStylesheets,
 	staticStylesFrom,
-} from '../scripts/generateStaticStyles';
+} from '../scripts/generateStaticStyles.js';
 
 const { source, expected, onDisk } = await readStylesheets();
 

package/src/stylesUtilitiesMatches.spec.ts

@@ -45,7 +45,7 @@
  */
 import { describe, expect, it } from 'bun:test';
 import pkg from '../package.json';
-import { CUSTOM_PROPERTY, declared, dropFallbacks, flatten, referenced } from '../scripts/cssRules';
+import { CUSTOM_PROPERTY, declared, dropFallbacks, flatten, referenced } from '../scripts/cssRules.js';
 import {
 	CONSUMER_PRECOMPILED,
 	CONSUMER_SCANNING,
@@ -54,7 +54,7 @@ import {
 	UTILITY_STYLESHEET,
 	compileStylesheet,
 	readUtilityStylesheet,
-} from '../scripts/generateUtilityStyles';
+} from '../scripts/generateUtilityStyles.js';
 
 const { expected, onDisk, candidates } = await readUtilityStylesheet();
 

package/src/tapTargetStylesheet.spec.ts

@@ -7,7 +7,7 @@ import {
 	TAP_TARGET_HALO,
 	TAP_TARGET_HEIGHT,
 	TAP_TARGET_SQUARE,
-} from './react/lib/tapTarget';
+} from './react/lib/tapTarget.js';
 
 /**
  * 🔴 THE TAP FLOOR SURVIVES THE JIT.

package/src/testTmpRoot.spec.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'bun:test';
 import { isAbsolute, resolve, sep } from 'node:path';
-import { resolveTestTmpRoot } from '../scripts/testTmpRoot';
+import { resolveTestTmpRoot } from '../scripts/testTmpRoot.js';
 
 /**
  * 🔴 THE CHECKER CANNOT SEE THIS ONE, WHICH IS WHY IT IS A TEST.

package/scripts/publicSurface.ts

@@ -1,455 +0,0 @@
-#!/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.`,
-	);
-}