cursedbelt 4.1.0 → 4.3.0

package/scripts/guardrailsEnforce.ts

@@ -8,13 +8,31 @@
 // invoked from each package's `lint`/`done` script, exiting non-zero on violation).
 //
 // Usage:
-//   bun run ../cursedbelt/scripts/guardrailsEnforce.ts <rule>[,<rule>...] [--scope <name>]
-//     [--reimplements <Name,Name,…>] [root...]
+//   bun run ../cursedbelt/scripts/guardrailsEnforce.ts <rule>[,<rule>...]
+//     [--scope <name> | --baseline <path>]
+//     [--reimplements <Name,Name,…> | --reimplements-from-belt]
+//     [--exclude <path>[,<path>…]] [root...]
 //
 // `--scope <name>` selects the ratchet baseline row (see "Ratchet baseline" below) for
 // the calling package — `cursedbelt` and `cursedshell` each pass their own scope name
 // from their `lint` script. Omitting `--scope` defaults every rule's baseline to 0.
 //
+// A CONSUMING APP uses the other three instead, and needs no wrapper script of its own:
+//
+//   "guardrails": "bun node_modules/cursedbelt/scripts/guardrailsEnforce.ts <rules>
+//                  --baseline scripts/guardrails-baseline.json --reimplements-from-belt src"
+//
+//   --baseline <path>            a flat `{ "<rule>": <count> }` ratchet in the CALLER's
+//                                repo, TWO-SIDED — exceeding a row fails, and so does
+//                                falling below one, which prints the number to paste.
+//                                The rows and the scanned rules must agree exactly, both
+//                                directions. See "a CONSUMER's ratchet" below.
+//   --reimplements-from-belt     derive `no-local-reimplementation`'s name list from THIS
+//                                package's own react index files, so no app hand-maintains
+//                                384 names. Fails closed on an empty list.
+//   --exclude <path>[,<path>…]   drop build output that lives under a source root. Fails
+//                                if it matches nothing.
+//
 // Currently implemented rules:
 //   no-raw-action-button — STANDARDS.md §4a: "a plugin or generated app must not render
 //     a raw <button> for an action (a raw <button> is acceptable only for a purely
@@ -148,7 +166,7 @@
 // ignored (its violations still fire) and a warning is printed.
 
 import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { basename, extname, join, relative } from "node:path";
+import { basename, extname, join, relative, resolve } from "node:path";
 
 const IGNORE_DIR_NAMES = new Set(["node_modules", "dist", "dist-deploy", ".git", "build", "coverage"]);
 const SOURCE_EXTENSIONS = new Set([".tsx", ".jsx", ".css"]);
@@ -1678,18 +1696,122 @@ function loadBaseline(): Baseline {
 	}
 }
 
+// ── `--baseline <path>`: a CONSUMER's ratchet, in the consumer's own repo ───────
+// The packaged baseline above cannot be a consuming app's: it lives inside
+// `node_modules/cursedbelt`, so nobody can check their debt ceiling in beside their
+// code. Nine apps each carried an identical ~140-line wrapper to work around that
+// (`apps/*/scripts/guardrails.ts`, deleted 2026-09-18 by tasks/…/202-*.md); this flag
+// is that wrapper, folded into the one place it belongs.
+//
+// The file is FLAT — `{ "<rule>": <count> }`, no scope level, because a repo's
+// baseline is about one repo. A `"$comment"` key is reserved for the why (desk's row
+// list carries fifty lines of it) and is the only non-numeric value tolerated:
+// anything else non-numeric is a typo in a row, and a typo read as `?? 0` would demand
+// a whole inherited pile in one commit, so it is refused by name instead.
+//
+// 🔴 It is TWO-SIDED, and the packaged `--scope` baseline is not. Deliberate, and the
+// asymmetry is the point: `--scope` names a row the CALLER cannot edit (it ships inside
+// the package), so failing a consumer for a number only a cursedbelt release can lower
+// would be a gate nobody can turn green. `--baseline` names a file in the caller's own
+// repo, which they lower in the same commit — so falling below a row fails, printing
+// the number to paste. A one-sided ratchet accumulates slack: fix forty colours, leave
+// the row at 353, and forty may quietly come back. Same idiom as the generation's
+// `check-paths` baseline — inherited debt only falls.
+type FlatBaseline = Record<string, number>;
+
+const BASELINE_COMMENT_KEY = "$comment";
+
+/** Parse a flat `{rule: count}` baseline, refusing anything that is not a count. */
+function parseFlatBaseline(json: string, label: string): FlatBaseline {
+	let raw: unknown;
+	try {
+		raw = JSON.parse(json);
+	} catch (error) {
+		throw new Error(`${label}: invalid JSON — ${(error as Error).message}`);
+	}
+	if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+		throw new Error(`${label}: expected an object of {"<rule>": <count>}`);
+	}
+	const rows: FlatBaseline = {};
+	for (const [rule, value] of Object.entries(raw as Record<string, unknown>)) {
+		if (rule === BASELINE_COMMENT_KEY) continue;
+		if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+			throw new Error(`${label}: "${rule}" is ${JSON.stringify(value)}, not a violation count`);
+		}
+		rows[rule] = value;
+	}
+	return rows;
+}
+
+/**
+ * Both directions of "the rows and the rules must agree", which is the hole this
+ * closes for the wrappers that used to do it by hand. A rule with no row is scored 0
+ * and demands its whole inherited pile in one commit; a row with no rule is coverage
+ * that is not there — the same defect as a `check-paths` baseline entry matching
+ * nothing. Returns the complaints, empty when the two lists agree.
+ */
+function baselineDisagreements(rows: FlatBaseline, ruleNames: readonly string[]): string[] {
+	const complaints: string[] = [];
+	const missing = ruleNames.filter((name) => !(name in rows));
+	const orphans = Object.keys(rows).filter((name) => !ruleNames.includes(name));
+	if (missing.length > 0) complaints.push(`no row for rule(s) being scanned: ${missing.join(", ")}`);
+	if (orphans.length > 0) complaints.push(`row(s) for rules nobody scans: ${orphans.join(", ")}`);
+	return complaints;
+}
+
+// ── `--reimplements-from-belt`: the name list, off this package's own exports ───
+// `no-local-reimplementation` matches app-declared names against the ones cursedbelt
+// exports (384 of them as this lands). A hand-kept copy of a dependency's export list
+// is a second source of truth that drifts the moment the belt publishes, so the list
+// is read off the react index files of the INSTALLED package — this file's own
+// package, whatever version resolved. `--reimplements <Name,…>` stays for a caller
+// with a list of its own (the CURSEDBELT_INVENTORY.md path in the rule's header).
+const BELT_REACT_ROOT = join(import.meta.dir, "..", "src", "react");
+
+export function beltExportedComponentNames(reactRoot: string = BELT_REACT_ROOT): string[] {
+	const names = new Set<string>();
+	const indexFiles: string[] = [];
+	// `withFileTypes` rather than a `statSync` per entry — the react tree is ~1,300
+	// entries, and one syscall each is 4s of a gate that is meant to be under a minute.
+	const collect = (dir: string) => {
+		for (const entry of readdirSync(dir, { withFileTypes: true })) {
+			const full = join(dir, entry.name);
+			if (entry.isDirectory()) collect(full);
+			else if (entry.name === "index.ts" || entry.name === "index.tsx") indexFiles.push(full);
+		}
+	};
+	collect(reactRoot);
+	for (const file of indexFiles) {
+		const source = readFileSync(file, "utf8");
+		for (const block of source.matchAll(/export\s*\{([^}]*)\}/gs)) {
+			for (const part of block[1]?.split(",") ?? []) {
+				const trimmed = part.trim();
+				if (!trimmed || trimmed.startsWith("type ")) continue;
+				const name = (trimmed.split(/\s+as\s+/).pop() ?? "").trim();
+				if (/^[A-Z][A-Za-z0-9]*$/.test(name)) names.add(name);
+			}
+		}
+	}
+	return [...names];
+}
+
 function main() {
 	const [ruleArg, ...rest] = process.argv.slice(2);
 	const ruleNames = ruleArg ? ruleArg.split(",") : [];
 	const rules = ruleNames.map((n) => RULES[n]).filter((r): r is Rule => Boolean(r));
 	if (ruleNames.length === 0 || rules.length !== ruleNames.length) {
 		console.error(
-			`Usage: bun run guardrailsEnforce.ts <rule>[,<rule>...] [--scope <name>] [--reimplements <Name,…>] [root...]\nKnown rules: ${Object.keys(RULES).join(", ")}`,
+			`Usage: bun run guardrailsEnforce.ts <rule>[,<rule>...] [--scope <name> | --baseline <path>]\n` +
+				`       [--reimplements <Name,…> | --reimplements-from-belt] [--exclude <path>[,<path>…]] [root...]\n` +
+				`Known rules: ${Object.keys(RULES).join(", ")}`,
 		);
 		process.exit(2);
 	}
 
 	let scope: string | undefined;
+	let baselinePath: string | undefined;
+	let fromBelt = false;
+	const excludes: string[] = [];
 	const roots: string[] = [];
 	for (let i = 0; i < rest.length; i++) {
 		if (rest[i] === "--scope") {
@@ -1697,6 +1819,12 @@ function main() {
 			i++;
 			continue;
 		}
+		// A flat `{rule: count}` ratchet in the CALLER's repo — see "a CONSUMER's ratchet".
+		if (rest[i] === "--baseline") {
+			baselinePath = rest[i + 1];
+			i++;
+			continue;
+		}
 		// The inventoried component names `no-local-reimplementation` looks for. Passed
 		// in rather than hardcoded so the list lives beside the inventory it comes from
 		// (fleet/standards/CURSEDBELT_INVENTORY.md) — see that rule's header.
@@ -1705,10 +1833,73 @@ function main() {
 			i++;
 			continue;
 		}
+		if (rest[i] === "--reimplements-from-belt") {
+			fromBelt = true;
+			continue;
+		}
+		// Build output that lives under a source root (desk's `src/generated/assets.ts` is
+		// the compiled browser app, inlined as a module and rewritten by every build). Named
+		// here rather than by listing every sibling root, because "name the siblings" fails
+		// OPEN — a directory added later is silently unscanned.
+		if (rest[i] === "--exclude") {
+			for (const part of (rest[i + 1] ?? "").split(",")) {
+				const trimmed = part.trim();
+				if (trimmed) excludes.push(resolve(trimmed));
+			}
+			i++;
+			continue;
+		}
 		roots.push(rest[i]);
 	}
+
+	if (scope && baselinePath) {
+		console.error("--scope and --baseline are two different ratchets; pass one.");
+		process.exit(2);
+	}
+
+	let flatBaseline: FlatBaseline | undefined;
+	if (baselinePath) {
+		if (!existsSync(baselinePath)) {
+			console.error(`--baseline ${baselinePath}: no such file (relative to ${process.cwd()})`);
+			process.exit(2);
+		}
+		try {
+			flatBaseline = parseFlatBaseline(readFileSync(baselinePath, "utf8"), baselinePath);
+		} catch (error) {
+			console.error((error as Error).message);
+			process.exit(2);
+		}
+		const complaints = baselineDisagreements(flatBaseline, ruleNames);
+		if (complaints.length > 0) {
+			console.error(`${baselinePath} and the rules being scanned disagree:`);
+			for (const complaint of complaints) console.error(`  ${complaint}`);
+			process.exit(2);
+		}
+	}
+
+	if (fromBelt) {
+		// 🔴 Fails CLOSED. An empty list makes `no-local-reimplementation` inert — it would
+		// print "0 violations" for a check that never ran, and a ratchet row of 0 would then
+		// look earned. If the react tree has moved, the run stops instead.
+		let names: string[] = [];
+		try {
+			names = beltExportedComponentNames();
+		} catch (error) {
+			console.error(`--reimplements-from-belt: cannot read ${BELT_REACT_ROOT} — ${(error as Error).message}`);
+			process.exit(2);
+		}
+		if (names.length === 0) {
+			console.error(`--reimplements-from-belt: ${BELT_REACT_ROOT} exports no component names — refusing to scan against an empty list.`);
+			process.exit(2);
+		}
+		setReimplementedNames(names);
+	}
+
 	const baseline = loadBaseline();
-	const scopeBaseline = (scope && baseline[scope]) || {};
+	const scopeBaseline: Record<string, number> = flatBaseline ?? (scope ? (baseline[scope] ?? {}) : {});
+	// `--baseline` names a file the caller owns and can lower; `--scope` does not. That is
+	// the whole reason one is two-sided and the other suggests.
+	const twoSided = flatBaseline !== undefined;
 
 	const searchRoots = roots.length > 0 ? roots : ["."];
 	const files: string[] = [];
@@ -1721,6 +1912,17 @@ function main() {
 			// every directory, e.g. a plugin package with no `apps/` dir)
 		}
 	}
+	if (excludes.length > 0) {
+		const kept = files.filter((file) => !excludes.some((dir) => resolve(file) === dir || resolve(file).startsWith(`${dir}/`)));
+		if (kept.length === files.length) {
+			// An exclusion matching nothing is either a typo or a directory that has moved,
+			// and both read as "that build output is handled" while it is being scanned.
+			console.error(`--exclude matched no scanned file: ${excludes.join(", ")}`);
+			process.exit(2);
+		}
+		files.length = 0;
+		files.push(...kept);
+	}
 
 	const sourcesByFile = new Map<string, string>();
 	for (const file of files) sourcesByFile.set(file, readFileSync(file, "utf8"));
@@ -1751,13 +1953,28 @@ function main() {
 		}
 
 		const allowedByBaseline = scopeBaseline[rule.name] ?? 0;
-		if (violations.length <= allowedByBaseline) {
+		if (violations.length === allowedByBaseline) {
 			console.log(
 				`✓ ${rule.name}: ${violations.length} violation(s) across ${files.length} files (baseline allows ${allowedByBaseline})`,
 			);
-			if (violations.length < allowedByBaseline) {
+			continue;
+		}
+		if (violations.length < allowedByBaseline) {
+			// The ratchet's other side. Under `--scope` this is a suggestion printed at the
+			// end; under `--baseline` it is a failure, because the caller owns that file and
+			// leaving slack in it is how a row stops meaning anything.
+			if (!twoSided) {
+				console.log(
+					`✓ ${rule.name}: ${violations.length} violation(s) across ${files.length} files (baseline allows ${allowedByBaseline})`,
+				);
 				lowerableBaselines[rule.name] = violations.length;
+				continue;
 			}
+			anyExceededBaseline = true;
+			console.error(
+				`✗ ${rule.name}: ${violations.length} violation(s), below the baseline of ${allowedByBaseline} — lower "${rule.name}" ` +
+					`to ${violations.length} in ${baselinePath} (the ratchet only falls)`,
+			);
 			continue;
 		}
 

package/src/iframesMakeNoRealRequest.spec.ts

@@ -0,0 +1,92 @@
+/**
+ * 🔴 An `<iframe src>` in a spec must not put a request on a real socket (2026-09-17).
+ *
+ * happy-dom loads an iframe's `src` for real, and `happydom.ts` registers the window at
+ * `http://localhost/`, so `<IsolatedFrame src='/preview/abc'>` used to issue an actual
+ * request to `http://localhost/preview/abc`. Two things came of that, and both are
+ * expensive:
+ *
+ * 1. Nothing listens there, so the socket errored — after `afterEach(cleanup)` had
+ *    unmounted the frame, and therefore after the spec that caused it had finished.
+ *    `bun test --parallel=6` hands a late unhandled error to whatever file is running, and
+ *    the stack (`happy-dom/lib/fetch/Fetch.js:540`) names no cursedbelt code at all. One
+ *    session spent twenty minutes reading that error against a test which is 8 pass /
+ *    0 fail on its own.
+ * 2. If anything ever DOES listen on that host and path, the unit suite hits it. On a
+ *    machine that runs one shared dev host, "nothing is listening" is a property of the
+ *    afternoon, not of the test.
+ *
+ * `happydom.ts` fixes it with `settings.navigation.disableChildFrameNavigation` — see the
+ * comment there for the measured trap in the flag you would reach for first.
+ *
+ * ── Why a live server rather than reading the setting ───────────────────────
+ * The setting is one line in a preload nobody opens, and the symptom of losing it is an
+ * error attributed to an innocent file — the exact failure this repo just paid for. So the
+ * assertion is the behaviour, not the spelling: bind a real port, frame it, and prove the
+ * handler never ran. Verified failing by removing the setting from `happydom.ts`, where
+ * `hits` becomes 1.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import type { Server } from 'bun';
+
+type AnyServer = Server<undefined>;
+
+/** `globalThis.happyDOM`, which `@happy-dom/global-registrator` defines but does not type. */
+const happyDOM = (globalThis as unknown as {
+  happyDOM?: {
+    settings: { navigation: { disableChildFrameNavigation: boolean } };
+    waitUntilComplete: () => Promise<void>;
+  };
+}).happyDOM;
+
+let server: AnyServer | undefined;
+
+afterEach(() => {
+  server?.stop(true);
+  server = undefined;
+  document.body.innerHTML = '';
+});
+
+describe('an iframe src in a spec never reaches the network', () => {
+  test('framing a URL that IS being served does not call the server', async () => {
+    let hits = 0;
+    server = Bun.serve({
+      port: 0,
+      fetch: () => {
+        hits += 1;
+        return new Response('<p>framed</p>', { headers: { 'content-type': 'text/html' } });
+      },
+    });
+
+    const frame = document.createElement('iframe');
+    // A raw element, not a React render: this is about happy-dom's loader, and going
+    // through a component would only add that component's own `onLoad` state update.
+    frame.title = 'network probe';
+    frame.src = `http://127.0.0.1:${server.port}/preview/abc`;
+    document.body.append(frame);
+
+    // Drains happy-dom's async task manager — with navigation enabled the iframe's fetch
+    // IS such a task, so this waits for exactly the request we are claiming never happens.
+    await happyDOM?.waitUntilComplete();
+    await Bun.sleep(50);
+
+    expect(
+      hits,
+      'an <iframe src> in a spec made a real HTTP request. happy-dom loads iframe `src` ' +
+        'for real; `happydom.ts` sets `settings.navigation.disableChildFrameNavigation` to ' +
+        'stop it. Without that, the request outlives the test, fails on `afterEach(cleanup)` ' +
+        'unmounting the frame, and `--parallel=6` prints the NetworkError against whichever ' +
+        'innocent spec is running. Restore the setting rather than the URL.',
+    ).toBe(0);
+  });
+
+  test('the preload setting that makes that true is still on', () => {
+    // Cheap second opinion on the same fact: if the probe above ever goes green for an
+    // unrelated reason (a loader change, a port that would not bind), this still reds when
+    // the preload loses the setting.
+    expect(
+      happyDOM?.settings.navigation.disableChildFrameNavigation,
+      'happydom.ts must register with `settings: { navigation: { disableChildFrameNavigation: true } }`.',
+    ).toBe(true);
+  });
+});

package/src/react/components/IsolatedFrame.spec.tsx

@@ -1,15 +1,33 @@
 import { afterEach, describe, expect, test } from 'bun:test';
-import { cleanup, fireEvent, render } from '@testing-library/react';
+import { act, cleanup, fireEvent, render } from '@testing-library/react';
+import type { ReactElement } from 'react';
 import { IsolatedFrame } from './IsolatedFrame';
 
 afterEach(cleanup);
 
+/**
+ * `render` plus a microtask flush inside `act`, for the cases that pass a `src`.
+ *
+ * happy-dom still runs its iframe loader when `src` is set — `happydom.ts` only stops it
+ * reaching the NETWORK (`navigation.disableChildFrameNavigation`), and the refused
+ * navigation still resolves and fires a real `load` on the next tick. That lands on
+ * `IsolatedFrame`'s `onLoad` → `setLoadedSource`, i.e. a genuine state update arriving
+ * just after a synchronous test body has returned, which React reports as
+ * "An update to IsolatedFrame inside a test was not wrapped in act(...)" against whatever
+ * file is running. Flushing it here keeps that update inside the test that caused it.
+ */
+const renderFramed = async (ui: ReactElement) => {
+  const result = render(ui);
+  await act(async () => {});
+  return result;
+};
+
 // The fullscreen modal is Radix-Dialog-backed (focus-trap + portal) and asserted
 // in e2e against the studio; here we lock the props contract: which mode frames
 // what, the src/srcDoc precedence, the loading skeleton, and the error slot.
 describe('IsolatedFrame', () => {
-  test('desktop: frames the src url with the given accessible title', () => {
-    const { getByTitle } = render(
+  test('desktop: frames the src url with the given accessible title', async () => {
+    const { getByTitle } = await renderFramed(
       <IsolatedFrame mode='desktop' src='/preview/abc' title='App preview' />,
     );
     const frame = getByTitle('App preview') as HTMLIFrameElement;
@@ -17,8 +35,8 @@ describe('IsolatedFrame', () => {
     expect(frame.getAttribute('src')).toBe('/preview/abc');
   });
 
-  test('src wins over srcDoc when both are provided', () => {
-    const { getByTitle } = render(
+  test('src wins over srcDoc when both are provided', async () => {
+    const { getByTitle } = await renderFramed(
       <IsolatedFrame mode='desktop' src='/preview/abc' srcDoc='<p>inline</p>' title='pv' />,
     );
     const frame = getByTitle('pv') as HTMLIFrameElement;
@@ -62,8 +80,8 @@ describe('IsolatedFrame', () => {
     expect(queryByTitle('pv')).toBeNull();
   });
 
-  test('mobile: frames the src inside a fixed-size device bezel', () => {
-    const { getByTitle } = render(
+  test('mobile: frames the src inside a fixed-size device bezel', async () => {
+    const { getByTitle } = await renderFramed(
       <IsolatedFrame mode='mobile' src='/preview/abc' title='mobile pv' />,
     );
     const frame = getByTitle('mobile pv') as HTMLIFrameElement;
@@ -73,8 +91,8 @@ describe('IsolatedFrame', () => {
     expect(bezel.style.height).toBe('720px');
   });
 
-  test('fullscreen: frames the src inside a modal dialog', () => {
-    const { getByRole, getByTitle } = render(
+  test('fullscreen: frames the src inside a modal dialog', async () => {
+    const { getByRole, getByTitle } = await renderFramed(
       <IsolatedFrame mode='fullscreen' src='/preview/abc' title='fs pv' onClose={() => {}} />,
     );
     expect(getByRole('dialog')).toBeTruthy();

package/src/react/master-lock/MasterLockDialog.tsx

@@ -22,7 +22,6 @@ import {
 	MAX_IDLE_MS,
 	MIN_IDLE_MS,
 	deriveMasterLockVerifier,
-	newMasterLockKdfParams,
 } from "cursedbelt-core/master-lock";
 import { ActionBar } from "../components/ActionBar";
 import { Button } from "../components/Button";
@@ -107,13 +106,31 @@ export function MasterLockDialog({
 		setNote({ text: "Deriving…", tone: "ok" });
 		try {
 			const currentVerifier = await deriveMasterLockVerifier(current, kdf);
-			const nextKdf = newMasterLockKdfParams();
-			const verifier = await deriveMasterLockVerifier(next, nextKdf);
+			/*
+			 * 🔴 BOTH verifiers derive under the app's EXISTING `kdf`, and the request carries
+			 * no `kdf` at all.
+			 *
+			 * Until 2026-09-17 this minted a fresh salt (`newMasterLockKdfParams()`) and sent it
+			 * along — the shape the wire had before accounts existed, when one app meant one
+			 * password. Every account on an app now derives under ONE shared descriptor, so a
+			 * fresh salt here would store a verifier hash nothing could ever match: the owner
+			 * sets a new password, the rotation logs him out, and neither the old nor the new
+			 * one opens the app. It would also invalidate every SIBLING account's stored hash
+			 * at once — rotating account 2 would silently lock him out of account 1.
+			 *
+			 * `cursedbelt-server`'s guard refuses the old shape with `409 {"error":"stale-client"}`
+			 * rather than honouring it, so this dialog did not corrupt anything; it simply
+			 * stopped working, and the owner could not change his master password from inside
+			 * any app. The salt never rotating is the accepted cost — it is 16 random bytes
+			 * whose job is to stop precomputation across apps, and it does that for as long as
+			 * it exists. `MasterLockChangeRequest` in `cursedbelt-core` carries the same note.
+			 */
+			const verifier = await deriveMasterLockVerifier(next, kdf);
 			const res = await fetch(MASTER_LOCK_PATHS.change, {
 				method: "POST",
 				credentials: "same-origin",
 				headers: { "content-type": "application/json" },
-				body: JSON.stringify({ currentVerifier, kdf: nextKdf, verifier }),
+				body: JSON.stringify({ currentVerifier, verifier }),
 			});
 			if (!res.ok) {
 				const body = (await res.json().catch(() => null)) as { error?: string } | null;
@@ -123,7 +140,9 @@ export function MasterLockDialog({
 							? "That is not the current master password."
 							: body?.error === "unconfigured"
 								? "This app's stored lock cannot be read — it needs re-seeding at the machine."
-								: "The change was refused.",
+								: res.status === 409
+									? "This page is out of date. Reload it and try again."
+									: "The change was refused.",
 					tone: "error",
 				});
 				setBusy(false);

package/src/react/master-lock/MasterLockProvider.spec.tsx

@@ -87,3 +87,42 @@ describe("the idle watcher", () => {
 		await waitFor(() => expect(locked).toBeGreaterThan(0), { timeout: IDLE_MS + 4_000 });
 	});
 });
+
+/**
+ * 🔴 The rotation's request body, pinned by reading the SHIPPED source.
+ *
+ * `MasterLockDialog` minted a fresh `kdf` salt on every rotation until 2026-09-17 — the wire
+ * shape from before accounts existed. Every account on an app now derives under one shared
+ * descriptor, so a fresh salt stores a verifier hash nothing can ever match: the owner sets a
+ * new password, the rotation logs him out, and neither the old nor the new one opens the app.
+ * `cursedbelt-server`'s guard answers that shape `409 stale-client` rather than honouring it,
+ * so the dialog did not corrupt anything — it simply refused, and the owner could not change
+ * his master password from inside any app for as long as it shipped.
+ *
+ * A rendering test cannot see this: the dialog renders identically either way and the bug is
+ * in two words of a fetch body. So this reads the module's own source, which is the only thing
+ * that would have caught the regression on the day it was written.
+ */
+describe("🔴 the rotation never mints a KDF", () => {
+	test("the dialog derives under the app's existing params and sends no kdf", async () => {
+		const raw = await Bun.file(
+			new URL("./MasterLockDialog.tsx", import.meta.url).pathname,
+		).text();
+		// 🔴 Comments STRIPPED before asserting. The note in the source explains the bug by
+		// naming `newMasterLockKdfParams()`, so a naive grep over the raw file fails on the
+		// documentation of the fix — which would teach the next person to delete the note.
+		const code = raw.replace(/\/\*[\s\S]*?\*\//g, "").replace(/\/\/.*$/gm, "");
+
+		// The body that goes to POST /__lock/change carries exactly the two verifiers.
+		expect(code).toContain("JSON.stringify({ currentVerifier, verifier })");
+		// Nothing in the file can produce a salt: the mint is not imported, so it is not in scope.
+		expect(code).not.toContain("newMasterLockKdfParams");
+		// Both verifiers derive under the SAME params — the ones the server published.
+		expect(code).toContain("deriveMasterLockVerifier(current, kdf)");
+		expect(code).toContain("deriveMasterLockVerifier(next, kdf)");
+		// `kdf` survives only as the PROP the server's params arrive on — never as a key in a
+		// request body. Pinned on the body itself above rather than by grepping the identifier,
+		// which would also hit that declaration.
+		expect(code).toContain("kdf: MasterLockKdfParams;");
+	});
+});

package/src/react/master-lock/MasterLockProvider.tsx

@@ -243,6 +243,25 @@ export interface MasterLockMenuItemsProps {
  * collections lock or other locks like that."*
  *
  * Renders nothing when no master password is configured for the app.
+ *
+ * ── 🔴 The second entry is a LINK now, not a dialog (2026-09-17) ─────────────────────────
+ * It used to call {@link MasterLockControl.openSettings}, and that dialog minted a FRESH `kdf`
+ * salt on every rotation — the shape the wire had before accounts existed. Every account on an
+ * app now derives under ONE shared descriptor, so honouring that salt would store a verifier
+ * hash nothing could ever match: the owner sets a new password, the rotation logs him out, and
+ * neither the old nor the new one opens the app. `cursedbelt-server`'s guard therefore answers
+ * that shape `409 {"error":"stale-client"}` — deliberately distinguishable from a wrong
+ * password, because it describes a broken CLIENT. So the entry did not merely look wrong; it
+ * refused, and the owner could lock a site and enroll a first password but could not CHANGE one.
+ *
+ * `cursedbelt-server` serves a richer replacement at `GET /__lock/accounts`, from the same guard
+ * that serves the lock page: server-rendered, content-negotiated, listing the accounts and
+ * adding/renaming them as well as rotating. This package does NOT link to it yet — the path
+ * constant lives in `cursedbelt-core@2`'s wire and this package is still on `^1.1.0`, so the
+ * link is a task, not a one-liner (`tasks/Not_Started`, filed 2026-09-17). What IS fixed here
+ * is the dialog itself: `MasterLockDialog` no longer mints a salt, so this entry works again
+ * rather than 409ing. `apps/collections` links to the page directly from its own rail in the
+ * meantime, and says why in a comment there.
  */
 export function MasterLockMenuItems({ close, itemClassName }: MasterLockMenuItemsProps) {
 	const lock = useMasterLock();

package/src/react/media/CanvasVideoPlayer.tsx

@@ -1,9 +1,8 @@
 import React from 'react';
-import type { PlayableVideo } from 'cursedbelt-core/media';
 import { Button } from '../components/Button';
 import { IconButton } from '../components/IconButton';
 import { useHlsSource } from './hlsSource';
-import { DEFAULT_VIDEO_ASPECT_RATIO, ProcessingIndicator } from './VideoPlayer';
+import { DEFAULT_VIDEO_ASPECT_RATIO, type PlayerVideo, ProcessingIndicator } from './VideoPlayer';
 
 // ── The green-frame-immune fallback player ───────────────────────────────────────
 // On some GPUs Chrome composites a hardware-decoded <video> as a solid GREEN frame when it's
@@ -12,7 +11,7 @@ import { DEFAULT_VIDEO_ASPECT_RATIO, ProcessingIndicator } from './VideoPlayer';
 // reintroduced it). The decode is correct — drawing the video to a <canvas> yields right pixels.
 // So this keeps a HIDDEN <video> as the decode/audio/seek engine and paints each presented frame
 // to a <canvas> (composited as an ordinary texture, immune to the bug). It's a drop-in swap for
-// the Vidstack <VideoPlayer> (same PlayableVideo + props); switch to it if you see green frames.
+// the Vidstack <VideoPlayer> (same PlayerVideo + props); switch to it if you see green frames.
 // Ported from ca's CanvasVideoPlayer (Tailwind, themed off cursedbelt's --accent token). The
 // source attach — native HLS / hls.js / progressive — is `hlsSource.ts`, shared with the
 // gallery's native stage.
@@ -26,7 +25,8 @@ function fmtTime(s: number): string {
 }
 
 export interface CanvasVideoPlayerProps {
-  video: PlayableVideo;
+  /** Same clip shape as {@link VideoPlayer} — see {@link PlayerVideo}. */
+  video: PlayerVideo;
   autoPlay?: boolean;
   muted?: boolean;
   className?: string;
@@ -204,7 +204,8 @@ export function CanvasVideoPlayer({
   };
 
   const status = video.processingStatus;
-  const showProcessing = status != null && status !== 'ready';
+  // An unreachable ladder is its own reason to draw — see `VideoPlayer`'s copy of this line.
+  const showProcessing = (status != null && status !== 'ready') || video.playbackDegraded === true;
 
   return (
     // Same intrinsic-sizing contract as <VideoPlayer>: aspect-ratio keeps the surface visible
@@ -234,7 +235,11 @@ export function CanvasVideoPlayer({
       />
 
       {showProcessing ? (
-        <ProcessingIndicator status={status} progress={video.processingProgress} />
+        <ProcessingIndicator
+          status={status}
+          progress={video.processingProgress}
+          playbackDegraded={video.playbackDegraded}
+        />
       ) : null}
 
       {/* Controls */}