cursedbelt 1.0.0 → 2.3.0

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.`,
+	);
+}

package/scripts/testTmpRoot.ts

@@ -41,19 +41,48 @@
  * no behaviour here for an app to get wrong — only a path.
  */
 import { mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
 
 /** Older than this and no live run can still want it. */
 const STALE_MS = 6 * 60 * 60 * 1000;
 
+/**
+ * ## 🔴 Where the scratch root is, and the bug that moved it (2026-09-13)
+ *
+ * This used to assemble the PREVIOUS generation's state root out of the ambient
+ * home directory. It is a preload, so it ran before the first test in this repo on
+ * every `bun test`, which meant every `verify` in this generation was writing into
+ * the last one. Measured the day it was found: 77 MB and 259 process directories
+ * under it, and a single spec run while the task was being written made number 260.
+ * This generation's first law is that nothing may depend on an older one.
+ *
+ * The checker could not see it: an interpolated `${VAR}/…` matches none of the
+ * shapes it looks for, and the line that actually built the path carried no banned
+ * string at all — it was assembled from a variable. So `testTmpRoot.spec.ts` is
+ * what holds this now, and it asserts the RESOLVED root rather than the source.
+ *
+ * `$FORGE_STATE` is this generation's state root and the runner hands it to every
+ * worker, so under autopilot it is always set. A bare checkout with no generation
+ * around it gets a repo-local `.agent.noindex/tmp`, which is already gitignored
+ * here — never a path built from `$HOME`.
+ *
+ * 🔴 `.noindex` stays in the directory name either way: it is the only marker that
+ * keeps Spotlight out of files written LATER into a tree, and a test root is
+ * written to constantly (measured 43× on this machine). `.agent.noindex` already
+ * carries it.
+ */
+export function resolveTestTmpRoot(env: Record<string, string | undefined> = process.env): string {
+	const forgeState = env.FORGE_STATE?.trim();
+	if (forgeState) return join(forgeState, "test-scratch.noindex", "tmp");
+	// This file is `<repo>/scripts/testTmpRoot.ts`; the root is one hop up.
+	return resolve(import.meta.dir, "..", ".agent.noindex", "tmp");
+}
+
 export function redirectTestTmpRoot(): void {
 	// A suite that genuinely wants the real `$TMPDIR` sets this and wins.
 	if (process.env.TMPDIR_TEST_PASSTHROUGH) return;
 
-	// 🔴 `.noindex` is not decoration: it is the only marker that keeps Spotlight
-	// out of files written LATER into a tree, and a test root is written to
-	// constantly (measured 43× on this machine).
-	const appManaged = process.env.APP_MANAGED_HOME ?? `${process.env.HOME}/.app-managed`;
-	const tmpRoot = `${appManaged}/test-scratch.noindex/tmp`;
+	const tmpRoot = resolveTestTmpRoot();
 
 	// Sweep BEFORE claiming ours. A SIGKILLed run cannot clean up after itself —
 	// that is precisely how the 310k pile was built — so the next run is the only

package/src/client/index.ts

@@ -1,7 +1,7 @@
 /*
  * cursedbelt/client — the browser half of the cursedbelt server toolkit:
  *  • the ctgr GET-tunnel (localStorage mode flag, v1 request converter, hard-block guard),
- *    pairing with `cursedbelt/server` (`unGETify`) + `cursedbelt/ctgr` (the codec);
+ *    pairing with `cursedbelt/server` (`unGETify`) + the ctgr codec (`src/ctgr`, re-exported from `cursedbelt/server`);
  *  • the WS hub's auto-reconnecting channel socket (partysocket), pairing with
  *    `cursedbelt/server`'s `createWsHub`.
  */

package/src/core/category/index.ts

@@ -1,4 +1,5 @@
-// `cursedbelt/category` — reusable hierarchical category/folder model. Pure and
+// src/core/category — reusable hierarchical category/folder model, reaching consumers
+// through `cursedbelt/react`'s categoryTree. Pure and
 // React-free (the `TreeView` adapter lives in `cursedbelt/react`), so servers
 // can import the contract + store without pulling any UI runtime.
 

package/src/core/category/types.ts

@@ -1,4 +1,4 @@
-// `cursedbelt/category` — a reusable, hierarchical category/folder model shared
+// src/core/category — a reusable, hierarchical category/folder model shared
 // by content plugins (notes today; snippets/aliases/… later). React-free and
 // storage-agnostic: the pure `Category` data + a host-injected `CategoryStore`
 // contract, mirroring how `cwip`'s `AuditSink` and cursedshell's `NotesStore`

package/src/core/file-tree/fileTreeModel.spec.ts

@@ -10,6 +10,8 @@ import {
   matchTypeahead,
   parentIdOf,
   resolveDrop,
+  resolveKeyboardMove,
+  describeDrop,
 } from './fileTreeModel';
 
 /**
@@ -326,3 +328,135 @@ describe('filterFileTree', () => {
     expect(filterFileTree(TREE, '   ')).toBe(TREE);
   });
 });
+
+/**
+ * ⌥→ / ⌥← — the keyboard's half of the drag, and the only half touch has.
+ *
+ * 🔴 The assertions that matter are the REFUSALS. A keyboard route that can reach a
+ * destination the pointer refuses is a second, weaker opinion about what is legal, and it is
+ * the one nobody looks at because the pointer is what gets tested by hand.
+ */
+describe('resolveKeyboardMove', () => {
+  const rows = flattenFileTree(TREE, []);
+
+  test('→ demotes into the nearest FOLDER above it among its own siblings', () => {
+    // `posters` sits under `simpsons` after `screencaps`; the only unambiguous "in" is the
+    // folder immediately above it at the same level.
+    expect(
+      resolveKeyboardMove({
+        nodes: TREE,
+        rows,
+        row: rowFor(rows, 'simpsons/posters'),
+        direction: 'in',
+      }).target,
+    ).toEqual({ kind: 'into', parentId: 'simpsons/screencaps' });
+  });
+
+  test('→ with nothing above it says so rather than doing nothing', () => {
+    const offer = resolveKeyboardMove({
+      nodes: TREE,
+      rows,
+      row: rowFor(rows, 'simpsons'),
+      direction: 'in',
+    });
+    expect(offer.target).toBeNull();
+    expect(offer.reason).toBe('There is no folder above it to move into');
+  });
+
+  test('🔴 → refuses a LOCKED folder with the consumer‘s words, exactly as a drop does', () => {
+    // `dinos` is `acceptsDrop: false`. `travels` is the row after it, so `dinos` is the
+    // nearest folder above — reachable by keyboard and refused by pointer would be the bug.
+    const offer = resolveKeyboardMove({
+      nodes: TREE,
+      rows,
+      row: rowFor(rows, 'travels'),
+      direction: 'in',
+      lockedReason: 'That album is locked',
+    });
+    expect(offer.target).toBeNull();
+    expect(offer.reason).toBe('That album is locked');
+  });
+
+  test('← promotes to the folder its own folder is in', () => {
+    expect(
+      resolveKeyboardMove({
+        nodes: TREE,
+        rows,
+        row: rowFor(rows, 'simpsons/screencaps/s04'),
+        direction: 'out',
+      }).target,
+    ).toEqual({ kind: 'into', parentId: 'simpsons' });
+  });
+
+  test('← at depth 1 is the top level, and at depth 0 is a refusal with words', () => {
+    expect(
+      resolveKeyboardMove({
+        nodes: TREE,
+        rows,
+        row: rowFor(rows, 'simpsons/posters'),
+        direction: 'out',
+      }).target,
+    ).toEqual({ kind: 'root' });
+    const offer = resolveKeyboardMove({
+      nodes: TREE,
+      rows,
+      row: rowFor(rows, 'travels'),
+      direction: 'out',
+    });
+    expect(offer.target).toBeNull();
+    expect(offer.reason).toBe('It is already at the top level');
+  });
+
+  test('🔴 the consumer‘s `canDrop` gets the last word in both directions', () => {
+    const canDrop = () => 'No route for that on the server';
+    for (const direction of ['in', 'out'] as const) {
+      const offer = resolveKeyboardMove({
+        nodes: TREE,
+        rows,
+        row: rowFor(rows, 'simpsons/posters'),
+        direction,
+        canDrop,
+      });
+      expect(offer.target).toBeNull();
+      expect(offer.reason).toBe('No route for that on the server');
+    }
+  });
+
+  test('a shut folder does not hide its own SIBLINGS, so the level is still whole', () => {
+    // The visible rows are what the level is read off. `screencaps` being shut removes its
+    // children, never its peers — which is what makes reading siblings off `rows` correct.
+    const shut = flattenFileTree(TREE, ['simpsons/screencaps']);
+    expect(
+      resolveKeyboardMove({
+        nodes: TREE,
+        rows: shut,
+        row: rowFor(shut, 'simpsons/posters'),
+        direction: 'in',
+      }).target,
+    ).toEqual({ kind: 'into', parentId: 'simpsons/screencaps' });
+  });
+});
+
+describe('describeDrop', () => {
+  test('names the destination, because "where to" is the question a drag asks', () => {
+    expect(describeDrop(TREE, { kind: 'into', parentId: 'simpsons/screencaps' })).toBe(
+      'Into screencaps',
+    );
+    expect(describeDrop(TREE, { kind: 'root' })).toBe('To the top level');
+    expect(describeDrop(TREE, { kind: 'before', siblingId: 'dinos', parentId: null })).toBe(
+      'Above Dinos',
+    );
+    expect(describeDrop(TREE, { kind: 'after', siblingId: 'dinos', parentId: null })).toBe(
+      'Below Dinos',
+    );
+  });
+
+  test('🔴 no target is SILENT — a refusal has its own words and must not be doubled', () => {
+    expect(describeDrop(TREE, null)).toBe('');
+  });
+
+  test('a target the tree no longer holds still says something true', () => {
+    // The tree can be re-derived from the server between the press and the release.
+    expect(describeDrop(TREE, { kind: 'into', parentId: 'gone' })).toBe('Into this folder');
+  });
+});