cursedbelt 4.1.1 → 4.4.0

package/src/demoStaticServer.spec.ts

@@ -0,0 +1,169 @@
+/**
+ * 🔴 The demo's static server, and specifically the fault that used to end the gate.
+ *
+ * `bun run verify` went red about one run in four on an unmodified tree (task 388,
+ * 2026-09-18): `vite preview` — connect on Bun's `node:http` shim — threw
+ * `ERR_STREAM_WRITE_AFTER_END` out of `advanceResponsePipeline` when a Playwright worker
+ * hung up on a response that was still being written, and the throw landed after the
+ * handler had returned, where no middleware could catch it. The process exited 1, the
+ * `webServer` never came ready, and 138 innocent specs went red 120 seconds later.
+ *
+ * So the first assertion here is the one that matters: abort requests mid-flight and prove
+ * the server is still serving afterwards. Everything else in this file is the ordinary
+ * contract that makes the fixture pages reachable at all.
+ */
+import { describe, expect, it } from 'bun:test';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { DEMO_HOST, DEMO_URL } from '../demo/devServer';
+import { isPeerHangup, resolveRequestPath, startDemoServer } from '../scripts/demoServer';
+
+/**
+ * A throwaway `dist` shaped like the one `bun run demo:build` writes. `$TMPDIR` is already
+ * redirected into this repo's scratch root by `scripts/testTmpRoot.ts` in the preload.
+ */
+function fixtureRoot(): string {
+	const root = mkdtempSync(join(tmpdir(), 'demo-server-'));
+	mkdirSync(resolve(root, 'assets'), { recursive: true });
+	writeFileSync(resolve(root, 'index.html'), '<!doctype html><title>kitchen sink</title>');
+	writeFileSync(resolve(root, 'table-layout.html'), '<!doctype html><title>table layout</title>');
+	// Big enough that an abort lands mid-body rather than after the whole thing arrived.
+	writeFileSync(resolve(root, 'assets', 'app.js'), `export const pad = '${'x'.repeat(4_000_000)}';\n`);
+	writeFileSync(resolve(root, 'assets', 'app.css'), ':root { color-scheme: dark; }\n');
+	return root;
+}
+
+/** Runs `body` against a server on an ephemeral port, and always stops it. */
+async function withServer(body: (base: string) => Promise<void>): Promise<void> {
+	const server = startDemoServer({ root: fixtureRoot(), port: 0, hostname: '127.0.0.1' });
+	try {
+		await body(`http://127.0.0.1:${server.port}`);
+	} finally {
+		await server.stop(true);
+	}
+}
+
+describe('🔴 a client that hangs up is a non-event', () => {
+	it('keeps serving after a burst of aborted requests', async () => {
+		await withServer(async (base) => {
+			expect((await fetch(`${base}/`)).status, 'the server must be up before we abort at it').toBe(200);
+
+			// Eight, because that is how many Playwright workers this repo runs, and each one
+			// abandons in-flight subresources on every navigation.
+			for (let i = 0; i < 8; i++) {
+				const control = new AbortController();
+				const inFlight = fetch(`${base}/assets/app.js`, { signal: control.signal });
+				// Abort on the next turn of the loop: late enough that the response is being
+				// written, early enough that the body has not finished.
+				queueMicrotask(() => control.abort());
+				await inFlight.then(
+					async (response) => {
+						// If it won the race, drain it and abort during the read instead.
+						control.abort();
+						await response.text().catch(() => undefined);
+					},
+					() => undefined,
+				);
+			}
+
+			// The whole point. Under `vite preview` the process was gone by now.
+			const after = await fetch(`${base}/`);
+			expect(after.status, 'the server died on a client hang-up — the exact task-388 bug').toBe(200);
+			expect(await after.text()).toInclude('kitchen sink');
+		});
+	});
+
+	it('names the peer faults it tolerates, and nothing else', () => {
+		// 🔴 A blanket handler would keep a broken server alive and let the gate measure a
+		// corpse that answers 200. The list is closed; this is the negative control.
+		expect(isPeerHangup({ code: 'ERR_STREAM_WRITE_AFTER_END' })).toBe(true);
+		expect(isPeerHangup({ code: 'ECONNRESET' })).toBe(true);
+		expect(isPeerHangup({ code: 'EPIPE' })).toBe(true);
+		expect(isPeerHangup(Object.assign(new Error('aborted'), { name: 'AbortError' }))).toBe(true);
+		expect(isPeerHangup(new TypeError('x is not a function'))).toBe(false);
+		expect(isPeerHangup({ code: 'ENOSPC' })).toBe(false);
+		expect(isPeerHangup(null)).toBe(false);
+		expect(isPeerHangup('ECONNRESET')).toBe(false);
+	});
+});
+
+describe('the pages the specs navigate to', () => {
+	it('serves the fixture pages, with the right content type and no caching', async () => {
+		await withServer(async (base) => {
+			const index = await fetch(`${base}/`);
+			expect(index.status).toBe(200);
+			expect(index.headers.get('content-type')).toInclude('text/html');
+			// 🔴 A cached bundle is a gate reading pre-checkout code, which is the trap this
+			// whole change exists to close.
+			expect(index.headers.get('cache-control')).toInclude('no-store');
+
+			const page = await fetch(`${base}/table-layout.html`);
+			expect(page.status).toBe(200);
+			expect(await page.text()).toInclude('table layout');
+
+			const css = await fetch(`${base}/assets/app.css`);
+			expect(css.status).toBe(200);
+			expect(css.headers.get('content-type')).toInclude('text/css');
+		});
+	});
+
+	it('404s what it does not have, rather than answering with index.html', async () => {
+		// A SPA fallback here would make `demoFixture.spec.ts`'s "every page the specs
+		// navigate to is real" assertion unfalsifiable at runtime: a typo'd fixture URL
+		// would load the kitchen sink and fail on a missing selector instead.
+		await withServer(async (base) => {
+			expect((await fetch(`${base}/no-such-page.html`)).status).toBe(404);
+			expect((await fetch(`${base}/assets/`)).status, 'no directory listings').toBe(404);
+		});
+	});
+});
+
+describe('what it refuses to serve', () => {
+	const root = '/tmp/demo-dist';
+
+	it('resolves the shapes the fixture actually uses', () => {
+		expect(resolveRequestPath(root, '/../../etc/passwd')).toBeNull();
+		expect(resolveRequestPath(root, '/%2e%2e/%2e%2e/etc/passwd')).toBeNull();
+		expect(resolveRequestPath(root, '/%zz')).toBeNull();
+		expect(resolveRequestPath(root, '/nope.html')).toBeNull();
+	});
+
+	it('cannot be walked out of its root even through an encoded traversal', async () => {
+		// The pure check above says `null`; this says the socket agrees, because a server
+		// that resolved correctly and then read the file anyway would pass the first.
+		await withServer(async (base) => {
+			for (const path of ['/../package.json', '/%2e%2e/package.json', '/..%2fpackage.json']) {
+				const response = await fetch(`${base}${path}`);
+				expect(await response.text(), `${path} escaped the demo dist`).not.toInclude('cursedbelt');
+			}
+		});
+	});
+});
+
+describe('the port', () => {
+	it('🔴 binds one literal address, so a second server cannot hide beside it', async () => {
+		// Measured 2026-09-18: with `hostname: 'localhost'` two processes bound 4318 at once,
+		// one on `[::1]` and one on `127.0.0.1`, and NEITHER raised EADDRINUSE — `localhost`
+		// resolves to both, so they were never competing for the same socket. The gate would
+		// then test whichever one the client happened to reach.
+		const server = startDemoServer({ root: fixtureRoot(), port: 0 });
+		try {
+			expect(server.hostname, 'a resolvable NAME here is two sockets pretending to be one').toBe(DEMO_HOST);
+			expect(DEMO_URL).toInclude(DEMO_HOST);
+		} finally {
+			await server.stop(true);
+		}
+	});
+
+	it('🔴 refuses a taken port instead of walking to the next one', async () => {
+		// The same rule `strictPort: true` gave the vite servers: a fixture that quietly
+		// moves to 4319 is a suite that times out against the port it was pointed at.
+		const first = startDemoServer({ root: fixtureRoot(), port: 0, hostname: '127.0.0.1' });
+		try {
+			expect(() => startDemoServer({ root: fixtureRoot(), port: first.port, hostname: '127.0.0.1' })).toThrow();
+		} finally {
+			await first.stop(true);
+		}
+	});
+});

package/src/publishShape.spec.ts

@@ -52,6 +52,31 @@ const typesThatAreNotDeclarations = (exports: Record<string, unknown>): string[]
 		.filter(([, target]) => !target.endsWith('.d.ts'))
 		.map(([subpath, target]) => `${subpath} → ${target}`);
 
+/**
+ * Every `[subpath, condition, target]` this manifest resolves OUTSIDE `dist/`.
+ *
+ * `./dist/` is deliberately excluded: those are `scripts/checkDistExports.ts`' job, and it
+ * has to be a build step because `dist/` is the one directory no spec here may open
+ * (`src/verifyGraph.spec.ts` asserts it, because `build` runs beside `test`). Everything
+ * else is a file that is already on disk when the tests run, so it belongs here.
+ *
+ * A string-valued export (`'./styles.css': './src/styles.css'`) is one target under the
+ * implicit `default` condition — 48 of this manifest's entries are that shape.
+ */
+const targetsOutsideDist = (exports: Record<string, unknown>): [string, string, string][] => {
+	const out: [string, string, string][] = [];
+	for (const [subpath, entry] of Object.entries(exports)) {
+		const conditions: Record<string, unknown> =
+			typeof entry === 'string' ? { default: entry } : typeof entry === 'object' && entry !== null ? (entry as Record<string, unknown>) : {};
+		for (const [condition, target] of Object.entries(conditions)) {
+			if (typeof target === 'string' && target.startsWith('./') && !target.startsWith('./dist/')) {
+				out.push([subpath, condition, target]);
+			}
+		}
+	}
+	return out;
+};
+
 describe('publish shape', () => {
 	it('ships every directory its exports resolve into', () => {
 		const files = (pkg as { files?: string[] }).files ?? [];
@@ -147,7 +172,61 @@ describe('publish shape', () => {
 		expect(typesThatAreNotDeclarations({ './a': { types: './dist/a.js' } })).toHaveLength(1);
 	});
 
+	it('🔴 points every non-dist export condition at a file that EXISTS', async () => {
+		// ── The third of three ways this manifest can lie, and the only one nothing watched ──
+		// `publishShape` above proves an export's ROOT directory is in `files`;
+		// `scripts/checkDistExports.ts` proves every `./dist/` target was emitted. Between
+		// them sits the condition a consumer actually RUNS — `bun`/`source`/`default`, which
+		// for this package is raw `./src/**` and `./scripts/guardrailsEnforce.ts` — and
+		// nothing proved those files are there. `files` ships whole directories, so renaming
+		// or moving one leaves the root shipped, the tarball valid, and the target dangling.
+		//
+		// It is not hypothetical and it is not ours to survive: since task 202 folded
+		// `--baseline` into the scanner, SIX apps run
+		// `bun node_modules/cursedbelt/scripts/guardrailsEnforce.ts …` inside their own
+		// `verify`. That path and this manifest's `./guardrails` conditions name the same
+		// file, so the day it moves, six repos go red in a file none of them wrote — the
+		// exact three-repos-away failure that tasks 172 and 219 each cost a session to find.
+		//
+		// The 48 string-valued CSS entries are the sharper half: they are GENERATED
+		// (`bun run styles:areas`) and have no second condition to fall through to, so a
+		// generator that stops emitting one is an unresolvable import for every consumer
+		// with nothing red on this side at all.
+		const repo = `${import.meta.dir}/..`;
+		const missing: string[] = [];
+		for (const [subpath, condition, target] of targetsOutsideDist(pkg.exports as unknown as Record<string, unknown>)) {
+			// 🔴 Bun.file, NOT node:fs — the preload virtualizes node:fs and an existsSync
+			// here would answer from MOCK data. Same trap as the header of this file.
+			if (!(await Bun.file(`${repo}/${target.slice(2)}`).exists())) missing.push(`${subpath} [${condition}] → ${target}`);
+		}
+		expect(
+			missing,
+			'these export conditions name a file that is not on disk. A consumer does not get a\n' +
+				'helpful error — the resolver falls through to whatever condition is left, or fails\n' +
+				'outright for the CSS entries, which have none:\n  ' +
+				missing.join('\n  '),
+		).toEqual([]);
+	});
+
+	it('catches a dangling non-dist target, and leaves dist to the build step', () => {
+		// The negative control for the rule above. Without it, `targetsOutsideDist` could
+		// quietly stop matching and the assertion would be green against nothing.
+		const found = targetsOutsideDist({
+			'./guardrails': { types: './dist/scripts/guardrailsEnforce.d.ts', bun: './scripts/moved.ts' },
+			'./styles.css': './src/styles.css',
+			'./react': { types: './dist/react/index.d.ts', import: './dist/react/index.js' },
+		});
+		// The `./dist/` conditions are checkDistExports' to police, so neither appears here.
+		expect(found).toEqual([
+			['./guardrails', 'bun', './scripts/moved.ts'],
+			['./styles.css', 'default', './src/styles.css'],
+		]);
+	});
+
 	it('reads the real manifest, so the rule cannot pass vacuously', () => {
+		// The scan above must see the whole non-dist surface, not a handful of it: 97 targets
+		// across the `bun`/`source`/`default` conditions and the 48 bare CSS entries.
+		expect(targetsOutsideDist(pkg.exports as unknown as Record<string, unknown>).length).toBeGreaterThan(90);
 		// `types` is what every conditional export in this package leads with; if the scan
 		// ever returns nothing, both assertions above are green about a manifest they never
 		// looked at.

package/src/react/components/Autocomplete.tsx

@@ -138,7 +138,17 @@ export function AutocompleteField<S = string>({
       </Autocomplete.InputGroup>
 
       <Autocomplete.Portal>
-        <Autocomplete.Positioner sideOffset={4} collisionPadding={FLOATING_COLLISION_PADDING}>
+        {/* 🔴 The z-index goes on the POSITIONER, not only the popup. Base UI's positioner is
+            the element that is `position: absolute` (with a transform); the popup inside it is
+            `position: static`, so the popup's own `z-[var(--z-popover)]` does nothing and the
+            list painted UNDER any sibling with a z-index — measured 2026-09-22 in the
+            binary-server inspector, a sticky table header (z-index 1) covering the second option
+            of an open MultiSelectField. */}
+        <Autocomplete.Positioner
+          sideOffset={4}
+          collisionPadding={FLOATING_COLLISION_PADDING}
+          className='z-[var(--z-popover)]'
+        >
           <Autocomplete.Popup
             className={cn(
               FLOATING_CONTENT_BASE,

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

@@ -53,6 +53,18 @@ describe('ComboboxField (single)', () => {
     expect(getByText('Banana')).not.toBeNull();
   });
 
+  test('🔴 the POSITIONER carries the popover z-index — the popup is static inside it', () => {
+    const { container, getByRole } = render(<Controlled />);
+    const trigger = container.querySelector('[aria-label="Toggle options"]') as HTMLElement;
+    act(() => {
+      fireEvent.click(trigger);
+    });
+    const popup = getByRole('listbox').closest('[data-side]') as HTMLElement;
+    const positioner = popup.parentElement?.closest('[data-side]') as HTMLElement;
+    expect(positioner).not.toBeNull();
+    expect(positioner.className).toContain('z-[var(--z-popover)]');
+  });
+
   test('disabled prevents the trigger from responding', () => {
     const onChange = mock(() => {});
     const { container } = render(

package/src/react/components/ComboboxField.tsx

@@ -291,7 +291,17 @@ export function ComboboxField(props: ComboboxFieldProps) {
       </Combobox.InputGroup>
 
       <Combobox.Portal>
-        <Combobox.Positioner sideOffset={4} collisionPadding={FLOATING_COLLISION_PADDING}>
+        {/* 🔴 The z-index goes on the POSITIONER, not only the popup. Base UI's positioner is
+            the element that is `position: absolute` (with a transform); the popup inside it is
+            `position: static`, so the popup's own `z-[var(--z-popover)]` does nothing and the
+            list painted UNDER any sibling with a z-index — measured 2026-09-22 in the
+            binary-server inspector, a sticky table header (z-index 1) covering the second option
+            of an open MultiSelectField. */}
+        <Combobox.Positioner
+          sideOffset={4}
+          collisionPadding={FLOATING_COLLISION_PADDING}
+          className='z-[var(--z-popover)]'
+        >
           <Combobox.Popup
             className={cn(
               FLOATING_CONTENT_BASE,

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');
+  });
+});