cursedbelt 4.1.1 → 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/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 */}

package/src/react/media/FrameGrabber.spec.tsx

@@ -1,7 +1,8 @@
 import { afterEach, describe, expect, test } from 'bun:test';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { cleanup, render } from '@testing-library/react';
+import type React from 'react';
+import { cleanup, fireEvent, render } from '@testing-library/react';
 import { FrameGrabber } from './FrameGrabber';
 
 afterEach(cleanup);
@@ -173,3 +174,58 @@ describe('FrameGrabber — the exit is named in the dialog itself', () => {
     expect(text, 'nothing tells the reader how to leave without saving').toContain('escape');
   });
 });
+
+/**
+ * 🔴 The dialog SAYS when it has no film, and keeps its hands off the save buttons.
+ *
+ * The turn dialog's report (`ideas/collections-09-14.md`: *"When I click the turn the video
+ * button I see a black screen"*) turned out to be true of four siblings, this one included: it
+ * was mounted `src={item.streamUrl ?? item.url ?? ''}` off the raw row, and an item is allowed
+ * to carry neither field (`resolveMedia` is the documented path for a signed URL). Here the
+ * consequence is a step beyond a bad preview: every output of this dialog is pixels read back
+ * off the `<video>`, so a black frame came with two live-looking save buttons that could only
+ * fail at `toBlob` — after somebody had scrubbed for their moment.
+ */
+describe('FrameGrabber — when it cannot show the film', () => {
+  const openWith = (props: Partial<React.ComponentProps<typeof FrameGrabber>>) =>
+    render(
+      <FrameGrabber
+        src=''
+        name='wedding.mp4'
+        onClose={() => {}}
+        onSaveThumbnail={() => {}}
+        onSaveSnapshot={() => {}}
+        {...props}
+      />,
+    );
+
+  test('🔴 no source at all is a stated reason, not a black box', () => {
+    const { getByRole } = openWith({});
+    expect(body().querySelector('video')).toBeNull();
+    expect(getByRole('status').textContent).toContain('no video source');
+  });
+
+  test('🔴 the save button is HELD, because there is nothing to read a frame from', () => {
+    const { getByRole } = openWith({});
+    const keep = getByRole('button', { name: /thumbnail/i }) as HTMLButtonElement;
+    // DISABLED and still on screen, which is the `DESIGN.md` rule for a control that cannot
+    // work here: hiding it would make "this film has not arrived" look like "this app cannot
+    // choose a thumbnail", and the reason is already stated on the frame beside it.
+    expect(keep.disabled).toBe(true);
+    expect(body().contains(keep)).toBe(true);
+  });
+
+  test('🔴 a source that fails to load says so too', () => {
+    const { getByRole, queryByRole } = openWith({ src: '/films/gone.mp4' });
+    const film = body().querySelector('video');
+    expect(film).not.toBeNull();
+    expect(queryByRole('status')).toBeNull();
+    fireEvent.error(film as HTMLVideoElement);
+    expect(getByRole('status').textContent).toContain('could not be loaded');
+  });
+
+  test('a source still being resolved reads as "on its way", not as a failure', () => {
+    const { getByRole } = openWith({ src: '', resolving: true });
+    expect(getByRole('status').textContent).toContain('Finding this film');
+  });
+});