cursedbelt 1.0.0 → 2.3.0

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

@@ -360,6 +360,110 @@ export function resolveDrop({
   });
 }
 
+export interface KeyboardMoveOptions {
+  nodes: readonly FileTreeNode[];
+  /** The rows on screen — siblings are read off these, which is every sibling by construction. */
+  rows: readonly FileTreeRow[];
+  /** The row the keyboard is on. */
+  row: FileTreeRow;
+  /** `in` demotes into the nearest folder above it; `out` promotes to its grandparent. */
+  direction: 'in' | 'out';
+  lockedReason?: string;
+  canDrop?: (dragId: string | null, target: FileTreeDrop) => string | null;
+}
+
+/**
+ * Where ⌥→ / ⌥← would put the focused row — the keyboard's half of the drag.
+ *
+ * 🔴 It exists because a gesture with no keyboard route is a gesture half the people using
+ * it cannot perform, and because TOUCH has no drag here at all: a sidebar row is a small
+ * target on a surface whose one constant gesture is the flick, so the pointer drag gives
+ * that up and this is what is left. `cursedesk`'s tree has carried it since it was written;
+ * this one shipped with the drag alone.
+ *
+ * The two directions are the only two a keyboard can mean unambiguously. **→ demotes into
+ * the nearest folder ABOVE it among its own siblings** — the one place a demotion can go
+ * without asking which of several folders was meant — and **← promotes out to the folder its
+ * own folder is in**, which is `root` at depth 1.
+ *
+ * 🔴 Every refusal the DRAG honours is honoured here, from the same fields: `acceptsDrop`,
+ * the consumer's `canDrop`, and the descendant rule. 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.
+ *
+ * There is deliberately no ⌥↑/⌥↓ here. Those would move a row among its siblings, which is
+ * only meaningful when the consumer stores an order — and when it does, the sibling before
+ * and after are already reachable as `before`/`after` drops. Offering them unconditionally
+ * would write a position nothing reads and then draw the row back where it started.
+ */
+export function resolveKeyboardMove({
+  nodes,
+  rows,
+  row,
+  direction,
+  lockedReason = 'That folder is locked',
+  canDrop,
+}: KeyboardMoveOptions): DropOffer {
+  const vetted = (target: FileTreeDrop): DropOffer => {
+    const reason = canDrop?.(row.node.id, target);
+    return reason
+      ? { target: null, refused: true, reason }
+      : { target, refused: false, reason: null };
+  };
+
+  if (direction === 'out') {
+    if (row.parentId === null)
+      return { target: null, refused: true, reason: 'It is already at the top level' };
+    const grandparentId = parentIdOf(nodes, row.parentId);
+    if (grandparentId === null) return vetted({ kind: 'root' });
+    const grandparent = findFileTreeNode(nodes, grandparentId);
+    if (grandparent?.acceptsDrop === false)
+      return { target: null, refused: true, reason: lockedReason };
+    return vetted({ kind: 'into', parentId: grandparentId });
+  }
+
+  // A row's siblings are all on screen whenever the row itself is — a shut folder hides its
+  // CHILDREN, never its peers — so the visible rows are the whole level.
+  const level = rows.filter((entry) => entry.parentId === row.parentId);
+  const above = level
+    .filter((entry) => entry.index < row.index && entry.node.kind === 'folder')
+    .at(-1);
+  if (!above)
+    return { target: null, refused: true, reason: 'There is no folder above it to move into' };
+  if (above.node.acceptsDrop === false)
+    return { target: null, refused: true, reason: lockedReason };
+  // Belt and braces: a folder cannot go inside itself, and `above` is a sibling rather than
+  // a descendant — but the rule is the tree's, not this function's, and stating it once here
+  // is cheaper than discovering the day someone changes what `above` means.
+  if (descendantIdsOf(nodes, row.node.id).has(above.node.id))
+    return { target: null, refused: true, reason: 'A folder cannot go inside itself' };
+  return vetted({ kind: 'into', parentId: above.node.id });
+}
+
+/**
+ * Where a drop would put the thing being carried, in words — for the chip under the cursor
+ * and for the screen reader that cannot see it.
+ *
+ * 🔴 A drag that says only WHAT is held answers half the question. Owner, of the tree this
+ * one was ported from: *"dragging an item from one place to another does not have any
+ * indication that it is working until you drop it somewhere new and see it move."* The chip
+ * following the cursor answers "it is working"; this answers "and it is going there", which
+ * is what stops a wrong drop before the pointer is lifted rather than after.
+ *
+ * Empty for no target — a refusal has its own words and this must never carry a second "no".
+ */
+export function describeDrop(nodes: readonly FileTreeNode[], drop: FileTreeDrop | null): string {
+  if (!drop) return '';
+  if (drop.kind === 'root') return 'To the top level';
+  if (drop.kind === 'into') {
+    const folder = findFileTreeNode(nodes, drop.parentId);
+    return folder ? `Into ${folder.name}` : 'Into this folder';
+  }
+  const sibling = findFileTreeNode(nodes, drop.siblingId);
+  const where = drop.kind === 'before' ? 'Above' : 'Below';
+  return sibling ? `${where} ${sibling.name}` : `${where} this row`;
+}
+
 /**
  * The next row whose name starts with `query`, searching from `fromIndex` and wrapping.
  *

package/src/core/layout/index.ts

@@ -1,4 +1,4 @@
-// cursedbelt/layout — re-export of `cwip/layout`, the single source of truth for the
+// src/core/layout — re-export of `cwip/layout`, the single source of truth for the
 // framework-agnostic layout/widget engine core (v2 node model + idempotent migration,
 // pure treeOps, aggregates, container-query grid/style class maps, binding resolution,
 // undo/redo history, wire version). cursedbelt's copy was absorbed into cwip

package/src/core/media/index.ts

@@ -1,5 +1,5 @@
 // cursedbelt/media-core — pure, dependency-free media contract + utilities shared by
-// the Bun server adapter (`cursedbelt/server/media`), the React components
+// the Bun server adapter (`src/server/media-bun`), the React components
 // (`cursedbelt/react/media`), and any consuming app/test. No React, no Bun, no npm
 // dep — the same module loads identically everywhere.
 

package/src/core/media/types.ts

@@ -1,5 +1,5 @@
 // cursedbelt media-core — the pure, dependency-free contract shared by the Bun
-// server adapter (`cursedbelt/server/media`), the React components
+// server adapter (`src/server/media-bun`), the React components
 // (`cursedbelt/react/media`), and any app/test. ZERO npm deps: types + pure
 // functions only, so the exact same module loads identically in Bun, the browser,
 // and a unit test.

package/src/core/media/uploadLimits.ts

@@ -1,6 +1,6 @@
 // Upload size limits — the ONE source of truth shared by the upload client
 // (`cursedbelt/react/media` fileUploadClient) and the server file routes
-// (`cursedbelt/server/storage/files`). Pure constants, no deps, so both the browser
+// (`cursedbelt/server/storage`). Pure constants, no deps, so both the browser
 // and Bun sides import the same numbers and can never drift.
 //
 // The law: NO single HTTP request may carry more than MAX_SINGLE_UPLOAD_BYTES of body.

package/src/core/sharing/model.ts

@@ -74,7 +74,7 @@ export interface ShareResource {
 }
 
 /** One grant. `grantedAt` is an ISO-8601 string, matching the fleet's audit
- *  vocabulary (`cursedbelt/server/audit`) rather than the epoch-millis apps use
+ *  vocabulary (the audit module behind `cursedbelt/server`) rather than the epoch-millis apps use
  *  for their own rows — an audit trail is read by humans far more often than it is
  *  sorted by a machine. */
 export interface ShareGrant {

package/src/ctgr/index.ts

@@ -1,5 +1,5 @@
 /*
- * cursedbelt/ctgr — the isomorphic ctgr codec (browser + Bun, no runtime deps). The
+ * src/ctgr — the isomorphic ctgr codec, re-exported from `cursedbelt/server`; (browser + Bun, no runtime deps). The
  * Hono transport binding (`unGETify` + `buildRoutes`) lives in `cursedbelt/server`;
  * the browser guard + request converter live in `cursedbelt/client`.
  *

package/src/declaredDepsAreImported.spec.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+
+/**
+ * Every declared dependency must be reachable from an import (2026-09-13).
+ *
+ * `dependencies` is not advice — a consumer installs all of it to render one
+ * button. `peerDependencies` is a promise that installing the peer lights a
+ * feature up. Both rot silently: a component gets deleted, its package stays
+ * declared, and nothing anywhere reds. At the time this was written the manifest
+ * carried three runtime deps and five optional peers that no file imported.
+ *
+ * 🔴 The reason this matches an IMPORT SPECIFIER and scans EVERY file type,
+ * rather than grepping .ts for the bare name:
+ *
+ *  - A .ts-only grep says `tw-animate-css` is dead. It is not — it is pulled in
+ *    from CSS (`@import` in src/styles.css), and deleting it would have shipped
+ *    a package whose stylesheet cannot resolve. That is the exact mistake this
+ *    session made on its first pass.
+ *  - A bare-name grep says everything is alive, because names like `diff` and
+ *    `marked` appear in prose in hundreds of files. A gate that cannot fail is
+ *    not a gate.
+ *
+ * devDependencies are deliberately NOT checked: several are installed only so
+ * this repo can typecheck and test an OPTIONAL peer's integration, so "nothing
+ * imports it by name" is the expected state there, not a defect.
+ */
+const ROOTS = ['src', 'scripts'] as const;
+
+// Reading a font or a screenshot as text costs time and can never match.
+const BINARY = /\.(png|jpe?g|gif|webp|avif|ico|mp4|webm|mp3|wav|pdf|zip|gz|woff2?|ttf|otf|eot|wasm)$/i;
+
+/**
+ * `from 'x'` · `import 'x/y.css'` · `import('x')` · `require('x')` · `@import "x"`,
+ * with or without a subpath. Anchored on the specifier quote so a name mentioned
+ * in prose or in a comment does not count as a use.
+ */
+const RE_SPECIAL = /[.*+?^${}()|[\]\\]/g;
+
+const importsPackage = (name: string): RegExp =>
+	new RegExp(`(?:from|import|require|@import)\\s*\\(?\\s*['"]${name.replace(RE_SPECIAL, '\\$&')}(?:/[^'"]*)?['"]`);
+
+// 🔴 Bun.Glob + Bun.file, NOT node:fs — this package's test preload virtualizes
+// node:fs, so a readdirSync/readFileSync scan reads MOCK data and passes against
+// files it never opened. Same trap as publishShape.spec.ts; see its header.
+let cache: Promise<string[]> | undefined;
+const sources = (): Promise<string[]> => {
+	cache ??= (async () => {
+		const repo = `${import.meta.dir}/..`;
+		const texts: string[] = [];
+		for (const root of ROOTS) {
+			const dir = `${repo}/${root}`;
+			for (const rel of new Bun.Glob('**/*').scanSync({ cwd: dir, onlyFiles: true })) {
+				if (BINARY.test(rel)) continue;
+				texts.push(await Bun.file(`${dir}/${rel}`).text());
+			}
+		}
+		return texts;
+	})();
+	return cache;
+};
+
+const unimported = async (block: Record<string, string> | undefined): Promise<string[]> => {
+	const texts = await sources();
+	return Object.keys(block ?? {}).filter((name) => {
+		const re = importsPackage(name);
+		return !texts.some((t) => re.test(t));
+	});
+};
+
+describe('declared dependencies are imported', () => {
+	it('has scanned a real source tree', async () => {
+		// Guards the whole file: if the glob or the fs mock ever returns nothing,
+		// every assertion below passes vacuously and the gate quietly dies.
+		expect((await sources()).length).toBeGreaterThan(100);
+	});
+
+	for (const field of ['dependencies', 'peerDependencies'] as const) {
+		it(`${field} names nothing the code never imports`, async () => {
+			const dead = await unimported((pkg as Record<string, unknown>)[field] as Record<string, string>);
+			expect(
+				dead,
+				`declared in ${field} but imported nowhere in ${ROOTS.join('/')} — import it or drop it:\n  ${dead.join('\n  ')}`,
+			).toEqual([]);
+		});
+	}
+});

package/src/demoFixture.spec.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'bun:test';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+	DEMO_COMMAND,
+	DEMO_DEV_SCRIPT,
+	DEMO_PACKAGE_DIR,
+	DEMO_PORT,
+	DEMO_ROOT,
+	DEMO_SERVE_SCRIPT,
+	DEMO_URL,
+} from '../demo/devServer';
+import { DEMO_TSCONFIG, derivePaths, readDemoTsconfig, renderPathsBlock } from '../demo/generatePaths';
+import pkg from '../package.json';
+
+/**
+ * 🔴 The e2e suite must never be able to sit green while it drives nothing.
+ *
+ * For the whole life of this repo, `e2e/playwright.config.ts` pointed its `webServer`
+ * at `cursedbelt/demo` — a directory that did not exist, because the kitchen-sink demo
+ * was never carried across from `cursed-core` when the package was extracted. All 18
+ * specs failed at web-server startup, and NOTHING noticed: `verify` was
+ * `paths && typecheck && build && test`, and `bun test` only runs `src`. So 2,400 lines
+ * of real assertions — including the `DESIGN.md` §5 44×44 touch-target floor, which the
+ * `touch` Playwright project exists specifically to prove and which no unit test can
+ * check, because `(pointer: coarse)` is about the input DEVICE — read as coverage the
+ * repo did not have.
+ *
+ * `bun run verify` now ends in `bun run e2e`, which is the real proof. These assertions
+ * are the cheap half: they fail in milliseconds naming the exact missing path instead of
+ * after a 120s web-server timeout, and they would have caught the original defect on the
+ * day the package was extracted.
+ *
+ * Note the blunt case: if `demo/` is removed OUTRIGHT this file cannot even load
+ * (`Cannot find module '../demo/devServer'`) and `bun test` fails on it. That is the
+ * intended red — the imports above are the coupling, not an accident of layout.
+ */
+const repoRoot = resolve(import.meta.dir, '..');
+const e2eDir = resolve(repoRoot, 'e2e');
+
+describe('the e2e fixture exists', () => {
+	it('the demo directory Playwright starts is real', () => {
+		expect(existsSync(DEMO_ROOT), `demo root does not exist: ${DEMO_ROOT}`).toBe(true);
+		expect(existsSync(resolve(DEMO_ROOT, 'vite.config.ts')), 'demo/ has no vite.config.ts').toBe(true);
+		expect(DEMO_PACKAGE_DIR, 'the demo must be started from this package').toBe(repoRoot);
+	});
+
+	it('the webServer command names a script this package defines', () => {
+		// A renamed or deleted script is the other way this config goes quietly dead —
+		// the suite would fail at startup with a shell error, not a diff.
+		const scripts = Object.keys(pkg.scripts);
+		expect(DEMO_COMMAND).toBe(`bun run ${DEMO_SERVE_SCRIPT}`);
+		for (const script of [DEMO_DEV_SCRIPT, DEMO_SERVE_SCRIPT]) {
+			expect(scripts, `package.json has no "${script}" script`).toContain(script);
+		}
+		expect(pkg.scripts.demo, 'the demo script must start vite on the demo config').toInclude('demo/vite.config.ts');
+		// Playwright drives the BUILT bundle, not the dev server — see demo/devServer.ts.
+		expect(pkg.scripts['demo:serve'], 'demo:serve must build before it previews').toInclude('demo:build');
+		expect(pkg.scripts['demo:serve']).toInclude('vite preview');
+	});
+
+	it('both servers serve the port the specs are pointed at', () => {
+		// vite silently walks to the next free port unless `strictPort` is set, which is
+		// the same outage wearing a costume: a server that starts perfectly well and a
+		// suite that times out against the port nobody is listening on.
+		const viteConfig = readFileSync(resolve(DEMO_ROOT, 'vite.config.ts'), 'utf8');
+		expect(DEMO_URL).toBe(`http://localhost:${DEMO_PORT}`);
+		// Once for `server` (dev), once for `preview` (what e2e drives).
+		expect(viteConfig.match(/port: DEMO_PORT/g) ?? [], 'both server and preview must pin the port').toHaveLength(2);
+		expect(viteConfig.match(/strictPort: true/g) ?? [], 'both must set strictPort').toHaveLength(2);
+	});
+
+	it('every page the specs navigate to is a real demo entry point', () => {
+		const specs = readdirSync(e2eDir).filter((f) => f.endsWith('.spec.ts'));
+		expect(specs.length, 'e2e/ holds no specs — delete the config and these assertions too').toBeGreaterThan(0);
+
+		const missing: string[] = [];
+		for (const spec of specs) {
+			const text = readFileSync(resolve(e2eDir, spec), 'utf8');
+			for (const [, url] of text.matchAll(/goto\('([^']+)'\)/g)) {
+				// '/' is index.html; '/table-layout.html' is that file in demo/.
+				const file = url === '/' ? 'index.html' : url.replace(/^\//, '');
+				if (!existsSync(resolve(DEMO_ROOT, file))) missing.push(`${spec} → ${url}`);
+			}
+		}
+		expect(missing, `specs navigate to pages demo/ does not serve:\n  ${missing.join('\n  ')}`).toEqual([]);
+	});
+
+	it('a built demo still emits every fixture page', () => {
+		// vite's dev server hands out any .html under its root, but a build only emits
+		// what `rollupOptions.input` lists — so a fixture page can exist, pass the
+		// assertion above, and vanish from the bundle the suite actually drives.
+		const viteConfig = readFileSync(resolve(DEMO_ROOT, 'vite.config.ts'), 'utf8');
+		const unlisted = readdirSync(DEMO_ROOT)
+			.filter((f) => f.endsWith('.html'))
+			.filter((page) => !viteConfig.includes(`'${page}'`));
+		expect(unlisted, `demo/vite.config.ts's rollup input omits:\n  ${unlisted.join('\n  ')}`).toEqual([]);
+	});
+
+	it('verify actually runs the suite', () => {
+		// Everything above proves the fixture resolves. Only this proves anybody looks:
+		// without it, `e2e` drops back out of the gate and this whole file becomes a
+		// comment about a suite nothing runs.
+		expect(pkg.scripts.verify, '`verify` must end in the e2e suite').toInclude('bun run e2e');
+		expect(pkg.scripts.e2e).toInclude('e2e/playwright.config.ts');
+	});
+});
+
+/**
+ * The demo imports cursedbelt by package specifier, and nothing installs
+ * `node_modules/cursedbelt` for it to resolve against. `demo/vite.config.ts` derives its
+ * aliases from the `exports` map at startup; tsc cannot, so `demo/tsconfig.json` carries
+ * a generated `paths` block. This keeps the generated half honest — see
+ * `demo/generatePaths.ts` for why neither resolver is allowed a hand-written list.
+ */
+describe("the demo's tsconfig paths track the export map", () => {
+	it('matches what the exports map derives', () => {
+		expect(readDemoTsconfig().compilerOptions.paths, 'stale — run `bun run demo:paths`').toEqual(derivePaths());
+	});
+
+	it('is rendered in the exact form `bun run demo:paths` writes', () => {
+		// Compare TEXT too: an equal-but-reformatted block would make the writer report a
+		// diff forever, which is how a generated file stops being regenerated.
+		expect(readFileSync(DEMO_TSCONFIG, 'utf8')).toInclude(renderPathsBlock(derivePaths()));
+	});
+
+	it('names only source files that exist', () => {
+		const missing = Object.entries(derivePaths())
+			.filter(([, [target]]) => !existsSync(resolve(DEMO_ROOT, target as string)))
+			.map(([specifier, [target]]) => `${specifier} → ${target}`);
+		expect(missing, `demo/tsconfig.json paths point at missing files:\n  ${missing.join('\n  ')}`).toEqual([]);
+	});
+});

package/src/index.ts

@@ -18,7 +18,7 @@
  * `bun run gate` at the repo root fails when `dist` is older than `src`.
  */
 // cursedbelt core (framework-agnostic utilities). The React UI kit lives in
-// `cursedbelt/react`; the isomorphic ctgr codec in `cursedbelt/ctgr`.
+// `cursedbelt/react`; the isomorphic ctgr codec in `cursedbelt/server`.
 export const VERSION = '0.0.0';
 
 // Color helpers — framework-agnostic, pure over hex strings. `contrastText` is the

package/src/lockfileIsTracked.spec.ts

@@ -0,0 +1,50 @@
+/**
+ * 🔴 Rule 2 of this generation: `bun install --frozen-lockfile` must pass on a
+ * CLEAN CHECKOUT — not merely in the tree an agent happens to be sitting in.
+ *
+ * ── What this cost, 2026-09-13 ──────────────────────────────────────────────
+ * `.gitignore` carried a `bun.lock` stanza with a comment explaining it was
+ * temporary: the only lockfile that could exist at the time recorded a
+ * proof-only local pack of `cwip`, and committing that would have reintroduced
+ * the `file:` dependency the package had just removed. The reasoning was sound
+ * and the expiry condition — "until cwip is on the registry" — was real. It was
+ * also written in a comment, which nothing can evaluate. `cwip@3.0.2` went to
+ * the registry and the stanza stayed, so rule 2 was true of every working tree
+ * and false of every fresh clone: exactly the case the rule exists for, and the
+ * one nobody hits until they are the person doing the clone.
+ *
+ * A temporary ignore needs a check that notices when it stopped being true.
+ * This is that check. `git check-ignore` is the whole mechanism, because the
+ * failure is not "the lockfile is missing" — it is "git has been told to throw
+ * it away", which is invisible in a tree that already has one.
+ *
+ * Deliberately NOT `git ls-files bun.lock`: a regenerated lockfile is untracked
+ * until it is staged, and a check that reds on work-in-progress teaches people
+ * to skip it. Ignored-vs-not is the property that actually regresses.
+ */
+import { describe, expect, test } from 'bun:test'
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url))
+
+describe('bun.lock is part of the checkout', () => {
+  test('the lockfile exists', () => {
+    expect(
+      existsSync(new URL('../bun.lock', import.meta.url)),
+      'no bun.lock — regenerate it with `bun install`, or `bun install --frozen-lockfile` cannot pass for anyone cloning this',
+    ).toBe(true)
+  })
+
+  test('git is not told to ignore it', () => {
+    const git = spawnSync('git', ['check-ignore', '-q', 'bun.lock'], { cwd: repoRoot })
+    if (git.error) return // no git on this host: nothing to assert about ignore rules
+
+    // exit 0 = the path IS ignored; 1 = it is not; anything else = git could not tell us.
+    expect(
+      git.status,
+      'bun.lock is gitignored, so a fresh clone has no lockfile and `bun install --frozen-lockfile` cannot pass there. Delete the stanza from .gitignore rather than the assertion.',
+    ).not.toBe(0)
+  })
+})

package/src/namedSubpathsResolve.spec.ts

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'bun:test';
+import pkg from '../package.json';
+
+/**
+ * Every `cursedbelt/<subpath>` this repo NAMES must be one it actually exports
+ * (2026-09-13).
+ *
+ * Removing the 23 subpaths nothing referenced left 19 sentences in `src` and
+ * `docs` still advertising them — `cursedbelt/ctgr`, `cursedbelt/server/media`,
+ * `cursedbelt/tokens` and friends, each one a copy-pasteable import that now
+ * throws ERR_PACKAGE_PATH_NOT_EXPORTED. Nothing could see them, because a
+ * subpath named in prose is invisible to `tsc` (it is a comment), invisible to
+ * Biome (it is a string), and invisible to `check-paths.ts` (it is not a
+ * filesystem path). The only reason those 19 were found is that one agent
+ * grepped for them by hand while deleting the exports.
+ *
+ * That is the drift this file exists to make impossible: the manifest and the
+ * prose describing it can no longer disagree without something going red.
+ *
+ * 🔴 Bun.Glob + Bun.file, NOT node:fs — this package's test preload virtualizes
+ * node:fs, so a readdirSync/readFileSync scan reads MOCK data and passes against
+ * files it never opened. Same trap as publishShape.spec.ts; see its header.
+ *
+ * Escape hatch: a line that must name a removed subpath (a changelog entry, a
+ * migration note) carries `subpath-check:ignore` and is skipped.
+ */
+const ROOTS = ['src', 'scripts', 'docs'] as const;
+
+const BINARY = /\.(png|jpe?g|gif|webp|avif|ico|mp4|webm|mp3|wav|pdf|zip|gz|woff2?|ttf|otf|eot|wasm)$/i;
+
+const IGNORE = 'subpath-check:ignore';
+
+/**
+ * `cursedbelt/<subpath>` wherever it appears — code, comment or markdown. The
+ * trailing class stops `cursedbelt/react` from matching inside
+ * `cursedbelt/react/timeline`, so a removed deep subpath cannot hide behind a
+ * live shallow one.
+ *
+ * The leading `(?<![\w/.-])` is what separates an IMPORT SPECIFIER from a REPO
+ * PATH: `packages/cursedbelt/src/...` and `../cursedbelt/scripts/...` name files
+ * on disk (check-paths.ts' job), not subpaths, and flagging them would make this
+ * gate unpassable and therefore useless.
+ */
+const NAMED = /(?<![\w/.-])cursedbelt(\/[a-z0-9][a-z0-9._/-]*[a-z0-9])/gi;
+
+/** First segment is a directory in THIS repo ⇒ the mention is a file path. */
+const REPO_DIRS = /^\/(src|scripts|dist|docs|e2e|demo|node_modules|releases)(\/|$)/;
+
+/**
+ * Ends in a file extension ⇒ a file path, not a subpath — except the three CSS
+ * entries, which genuinely ARE exports (`cursedbelt/styles.css`).
+ */
+const FILE_EXT = /\.(?!css$)[a-z0-9]+$/i;
+
+const exported = new Set(Object.keys(pkg.exports).map((k) => k.replace(/^\./, '')));
+
+// This file and the task/report prose quoting the removal are allowed to name them.
+const SELF = 'namedSubpathsResolve.spec.ts';
+
+type Offence = { file: string; line: number; subpath: string; text: string };
+
+let cache: Promise<Offence[]> | undefined;
+const offences = (): Promise<Offence[]> => {
+	cache ??= (async () => {
+		const repo = `${import.meta.dir}/..`;
+		const found: Offence[] = [];
+		for (const root of ROOTS) {
+			const dir = `${repo}/${root}`;
+			for (const rel of new Bun.Glob('**/*').scanSync({ cwd: dir, onlyFiles: true })) {
+				if (BINARY.test(rel) || rel.endsWith(SELF)) continue;
+				const text = await Bun.file(`${dir}/${rel}`).text();
+				const lines = text.split('\n');
+				for (let i = 0; i < lines.length; i++) {
+					const line = lines[i] ?? '';
+					if (line.includes(IGNORE)) continue;
+					for (const m of line.matchAll(NAMED)) {
+						const subpath = m[1] ?? '';
+						if (exported.has(subpath)) continue;
+						if (REPO_DIRS.test(subpath) || FILE_EXT.test(subpath)) continue;
+						found.push({ file: `${root}/${rel}`, line: i + 1, subpath, text: line.trim() });
+					}
+				}
+			}
+		}
+		return found;
+	})();
+	return cache;
+};
+
+describe('subpaths named in this repo resolve', () => {
+	it('has scanned a real source tree', async () => {
+		// Guards the whole file: if the glob or the fs mock ever returns nothing,
+		// the assertion below passes vacuously and the gate quietly dies.
+		const repo = `${import.meta.dir}/..`;
+		let seen = 0;
+		for (const root of ROOTS) {
+			for (const _ of new Bun.Glob('**/*').scanSync({ cwd: `${repo}/${root}`, onlyFiles: true })) seen++;
+		}
+		expect(seen).toBeGreaterThan(100);
+	});
+
+	it('knows what the manifest exports', () => {
+		// If `exports` is ever read wrong, every offence below silently becomes one.
+		expect(exported.has('')).toBe(true); // the "." root entry
+		expect(exported.has('/react')).toBe(true);
+		expect(exported.has('/game')).toBe(false); // removed 2026-09-13
+	});
+
+	it('names no subpath package.json does not export', async () => {
+		const dead = await offences();
+		expect(
+			dead,
+			`these name a cursedbelt subpath that is not in package.json exports — a consumer who\n` +
+				`copies one gets ERR_PACKAGE_PATH_NOT_EXPORTED. Point at the surviving subpath, or at\n` +
+				`the repo path, or mark the line \`${IGNORE}\`:\n` +
+				dead.map((d) => `  ${d.file}:${d.line}  cursedbelt${d.subpath}\n      ${d.text}`).join('\n'),
+		).toEqual([]);
+	});
+});

package/src/publicSurface.spec.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'bun:test';
+import { run } from '../scripts/publicSurface';
+
+/**
+ * The public-surface ratchet, wired into `bun run verify` at its cheapest correct
+ * home: `verify` already ends in `bun test src`, so this needs no new script and
+ * cannot be a script somebody forgot to chain. The whole measurement is ~1.3s
+ * against a 4m41s suite.
+ *
+ * WHY it exists, WHAT a symbol count includes and excludes, why `bin` targets and
+ * the dependency list are deliberately NOT counted here, and what `--prune` may
+ * and may not do are all in the header of `scripts/publicSurface.ts` — one check,
+ * one baseline (`publicSurface.baseline`), one place that explains itself. This
+ * file is only the wiring.
+ *
+ * 🔴 Verified failing, 2026-09-13, before it was trusted — every branch, not just
+ * the easy one. Each probe was applied, observed, and removed again:
+ *
+ *   · `export const ratchetProbe = 1` appended to `src/core/palette/index.ts`
+ *       → this file's "ceiling" test red, and the CLI:
+ *         "2 subpath(s) that gained exported symbols · ./react — baseline allows 1061,
+ *          exports 1062 now · ./palette — baseline allows 10, exports 11 now".
+ *         TWO, because the `./react` barrel re-exports the palette — which is the
+ *         transitive `export *` walk this file's header promises, seen working.
+ *   · a `"./probe"` subpath added to package.json `exports`
+ *       → "1 export subpath(s) the baseline does not know · ./probe — NEW subpath, 10 exported symbol(s)"
+ *   · `searchInitials` removed from `src/core/palette/index.ts`, no prune
+ *       → "2 baseline entr(y|ies) that no longer match `exports` · ./palette — baseline
+ *          says 10, exports 9 · ./react — baseline says 1061, exports 1060"
+ *   · a `5  ./gone` line added to the baseline by hand
+ *       → same failure, "./gone — baseline says 5, the subpath is gone". An entry
+ *         matching nothing is the half that stops a deleted module leaving an allowance.
+ *   · `--prune` run against the grown surface
+ *       → "refuses while the surface has GROWN — it may only lower the baseline", exit 1
+ *   · `--prune` run against the shrunk surface
+ *       → "pruned to 85 subpath(s), 0 removed, 3806 symbols", exit 0 — `./palette`
+ *         10 → 9 and `./react` 1061 → 1060 in the file, which is the burn-down path
+ *
+ * A ratchet nobody has seen red is a ratchet nobody knows is wired up.
+ */
+const result = await run();
+
+describe('public surface', () => {
+	it('has measured a real surface', () => {
+		// Guards the three assertions below: if `exports` were ever read as empty,
+		// every one of them passes vacuously and the ratchet quietly dies.
+		expect(result.surface.counts.size).toBeGreaterThan(50);
+	});
+
+	it('publishes no export subpath the baseline does not know', () => {
+		expect(
+			result.fresh,
+			`new public subpath(s) — a permanent promise. Add the line to publicSurface.baseline and say why:\n  ${result.fresh.join('\n  ')}`,
+		).toEqual([]);
+	});
+
+	it('exports no more symbols per subpath than the baseline allows', () => {
+		expect(
+			result.grown,
+			`a baseline entry is a ceiling, not an amnesty:\n  ${result.grown.join('\n  ')}`,
+		).toEqual([]);
+	});
+
+	it('has no baseline entry that outlived the surface it recorded', () => {
+		// The half that makes it a RATCHET: a deleted module may not leave an
+		// allowance behind for the next one to grow into.
+		expect(
+			result.stale,
+			`surface came off and the ratchet was not tightened — run \`bun scripts/publicSurface.ts --prune\`:\n  ${result.stale.join('\n  ')}`,
+		).toEqual([]);
+	});
+});

package/src/react/activity-bar/ActivityBar.tsx

@@ -32,6 +32,23 @@
  * brighter glyph — the same language the file tree's selected row uses, so a person learns
  * it once.
  *
+ * ── 🔴 The graduation verdict, 2026-09-13: THIS one, unchanged ──────────────────────────
+ * `cursedesk` has an `ActivityBar.tsx` of its own and the pair was compared to decide which
+ * should be the shared one. Nothing moved here, and the reason is that they are not two
+ * versions of one component: this is a RAIL that takes {@link ActivityBarProps.top} and
+ * {@link ActivityBarProps.bottom} and draws whatever is in them; the app's is one particular
+ * seven-button composition — Explorer, Search, ⌘P, the command menu, full screen, theme,
+ * settings — hard-wired to that app's `primitives.tsx` and `shortcuts.ts`, with every prop
+ * (`searchOpen`, `onSwitcher`, `shortcutPrefs`, `commandUnavailable`) naming one of them.
+ *
+ * A design system cannot hold that: `onSwitcher` is a door onto a file finder and
+ * `shortcutPrefs` is a preferences table, neither of which a rail has any business knowing.
+ * So the app's copy is deleted rather than moved, and its seven buttons become seven
+ * `ActivityBarItem`s built where the app's state already lives. The one thing it has that
+ * this does not — a command menu rendered by the rail itself — is already expressible:
+ * {@link ActivityBarItem.render} takes the consumer's own popover, and
+ * {@link ActivityBarItem.hasMenu}/{@link ActivityBarItem.menuOpen} say so to a screen reader.
+ *
  * ── Plain CSS, deliberately ─────────────────────────────────────────────────────────────
  * `activityBar.css` under the `cbab-` prefix, the same convention (and the same reason) as
  * `fileTree.css` and `denseGallery.css`: this mounts inside apps whose Tailwind build cannot