cursedbelt 4.5.0 → 4.7.0

package/dist/react/media-gallery/types.d.ts

@@ -166,7 +166,14 @@ export interface MediaGalleryItem extends MediaGalleryItemMedia {
      * Called once per item id per gallery mount (cached); return `null` when the bytes
      * are gone. Fields set directly on the item win over resolved ones. If the resolver
      * mints object URLs, revoking them stays the app's job.
+     *
+     * 🔴 `signal` aborts when every tile, row and stage waiting on this answer has unmounted
+     * before it arrived — a tile the viewer scrolled past. Hand it to your `fetch` (or drop the
+     * ask from your own queue) so an abandoned resolve stops costing origin time. The gallery
+     * evicts the abandoned entry, so a remount asks again rather than inheriting the abort; an
+     * abort is never read as "this item has no bytes". Ignoring the parameter is valid — the
+     * answer is then simply thrown away.
      */
-    resolveMedia?: () => Promise<MediaGalleryItemMedia | null>;
+    resolveMedia?: (signal?: AbortSignal) => Promise<MediaGalleryItemMedia | null>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/react/media-gallery/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/react/media-gallery/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,WAAW,GACX,MAAM,GACN,UAAU,CAAC;AAEf;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,qBAAqB;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0FAA0F;IAC1F,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACzE;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;CAC5D"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/react/media-gallery/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,QAAQ,GACR,MAAM,GACN,WAAW,GACX,MAAM,GACN,UAAU,CAAC;AAEf;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0FAA0F;IAC1F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAiB,SAAQ,qBAAqB;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0FAA0F;IAC1F,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;;;;;;;;;;;;;OAiBG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE;QAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACzE;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC;IAC1B;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;CAChF"}

package/dist/styles-areas/file-tree.css

@@ -15,7 +15,7 @@
  *
  * An app that imports every area gets exactly what `cursedbelt/styles-utilities.css`
  * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
- * when this file is stale. 535 candidate(s) scanned.
+ * when this file is stale. 574 candidate(s) scanned.
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are

package/dist/styles-areas/media-gallery.css

@@ -15,7 +15,7 @@
  *
  * An app that imports every area gets exactly what `cursedbelt/styles-utilities.css`
  * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
- * when this file is stale. 2116 candidate(s) scanned.
+ * when this file is stale. 2162 candidate(s) scanned.
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are

package/dist/styles-areas/media.css

@@ -15,7 +15,7 @@
  *
  * An app that imports every area gets exactly what `cursedbelt/styles-utilities.css`
  * emits — proved rule by rule in src/stylesAreas.spec.ts, which is also what fails
- * when this file is stale. 2825 candidate(s) scanned.
+ * when this file is stale. 2849 candidate(s) scanned.
  *
  * Written by scripts/generateAreaStyles.ts (`bun run styles:areas`), which
  * `bun run build` runs. The map of what is in which area, and why the areas are

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt",
-	"version": "4.5.0",
+	"version": "4.7.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The React design system of the cursedbelt split — components, styles, theme. cursedbelt-core below it; server tier in cursedbelt-server.",
@@ -47,6 +47,7 @@
 		"e2e:touch": "playwright test --config e2e/playwright.config.ts --project=touch",
 		"done:serial": "bun run typecheck && bun run lint && bun run test && bun run build",
 		"paths": "bun run scripts/paths.ts",
+		"surface": "public-surface",
 		"verify": "bun run gate",
 		"prepublishOnly": "bun run gate --force",
 		"styles:areas": "bun run scripts/generateAreaStyles.ts",
@@ -645,6 +646,7 @@
 		"@vidstack/react": "1.15.6",
 		"@vitejs/plugin-react": "^5.2.0",
 		"cursedbelt-server": "^4.13.0",
+		"cursedops": "^0.2.7",
 		"diff": "^9.0.0",
 		"emoji-mart": "^5.6.0",
 		"hls.js": "^1.5.0",

package/src/declaredImports.spec.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'bun:test';
+import { builtinModules } from 'node:module';
+import pkg from '../package.json';
+
+/**
+ * 🔴 Every bare module `src/` imports is declared in `package.json` — or no bundler has to agree.
+ *
+ * Measured 2026-09-18 (task 329): `mediabunny` and `react-filerobot-image-editor` were imported by
+ * the media barrel and declared nowhere, because 3.0.0 dropped them from `package.json` while the
+ * source kept both. Eight apps build with Vite, which treats an unresolvable dynamic import as a
+ * WARNING; `binary-server` builds with `Bun.build`, which fails the whole build. So the gap was
+ * invisible in eight repos and fatal in the ninth — and on 2026-09-22 a clean checkout of this
+ * repo could not even typecheck, because only this Mac's stale `node_modules` still held both.
+ * A `package.json` that is right for one bundler is documentation, not a contract; this makes it one.
+ *
+ * Specs are exempt (they may import devDependencies); `import type` is not — a consumer's
+ * typecheck resolves it too.
+ */
+const declared = new Set([
+  pkg.name,
+  ...Object.keys((pkg as { dependencies?: Record<string, string> }).dependencies ?? {}),
+  ...Object.keys((pkg as { peerDependencies?: Record<string, string> }).peerDependencies ?? {}),
+]);
+const builtin = new Set(builtinModules);
+
+/** `@scope/pkg/deep` → `@scope/pkg`, `react/jsx-runtime` → `react`. */
+export const packageOf = (specifier: string): string => {
+  const parts = specifier.split('/');
+  return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : (parts[0] as string);
+};
+
+const IMPORT = /(?:\bfrom\s*|\bimport\s*\(\s*|\bimport\s+|\brequire\(\s*)(['"])([^'"]+)\1/g;
+
+export const undeclaredIn = (text: string, known: ReadonlySet<string>): string[] => {
+  const out: string[] = [];
+  for (const m of text.matchAll(IMPORT)) {
+    const spec = m[2] as string;
+    if (spec.startsWith('.') || spec.startsWith('/') || spec.startsWith('node:') || spec.startsWith('bun:')) continue;
+    if (spec.startsWith('virtual:') || spec.includes('?')) continue;
+    const name = packageOf(spec);
+    if (builtin.has(name) || known.has(name)) continue;
+    out.push(spec);
+  }
+  return out;
+};
+
+describe('declared imports', () => {
+  it('the scanner sees a bare dynamic import, a scoped deep import and a type import', () => {
+    const known = new Set(['react']);
+    const text = "import('mediabunny');\nimport x from '@scope/pkg/deep';\nimport type { T } from 'zod';\nimport 'react/jsx-runtime';\nimport './local';\nimport fs from 'node:fs';";
+    expect(undeclaredIn(text, known)).toEqual(['mediabunny', '@scope/pkg/deep', 'zod']);
+  });
+
+  it('🔴 every bare module src/ imports is a dependency or peerDependency', () => {
+    const offenders: string[] = [];
+    // Bun.Glob, not node:fs — this suite's preload may virtualize node:fs (see publishShape).
+    for (const rel of new Bun.Glob('**/*.{ts,tsx}').scanSync({ cwd: import.meta.dir })) {
+      if (/\.(spec|test)\.tsx?$/.test(rel) || rel.endsWith('.d.ts')) continue;
+      const text = require('node:fs').readFileSync(`${import.meta.dir}/${rel}`, 'utf8') as string;
+      // Comments and prose may NAME a package; only code imports one.
+      const code = text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1');
+      for (const spec of undeclaredIn(code, declared)) offenders.push(`src/${rel}: ${spec}`);
+    }
+    expect(offenders, `imported but declared nowhere — add it to dependencies or (optional) peerDependencies:\n  ${offenders.join('\n  ')}`).toEqual([]);
+  });
+});

package/src/publicSurface.spec.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'bun:test';
-import { run } from '../scripts/publicSurface.js';
+import { dirname } from 'node:path';
+import { run } from 'cursedops/public-surface';
 
 /**
  * The public-surface ratchet, wired into `bun run verify` at its cheapest correct
@@ -9,10 +10,15 @@ import { run } from '../scripts/publicSurface.js';
  *
  * 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,
+ * and may not do are all in the header of `cursedops/src/publicSurface.ts` — one check,
  * one baseline (`publicSurface.baseline`), one place that explains itself. This
  * file is only the wiring.
  *
+ * Since 2026-09-22 (task 084) the measurement is ONE body, `cursedops/public-surface`, a
+ * devDependency: this package's own `scripts/publicSurface.ts` had forked from the other
+ * two libraries' copies. `bun run surface [--prune]` is the CLI. The probes below were
+ * run against that former copy; the shared body measured identical per-subpath counts.
+ *
  * 🔴 Verified failing, 2026-09-13, before it was trusted — every branch, not just
  * the easy one. Each probe was applied, observed, and removed again:
  *
@@ -38,7 +44,9 @@ import { run } from '../scripts/publicSurface.js';
  *
  * A ratchet nobody has seen red is a ratchet nobody knows is wired up.
  */
-const result = await run();
+// The package this spec lives in — resolved from this file, never from `process.cwd()`,
+// because `bun test` can be started from anywhere.
+const result = await run({ root: dirname(import.meta.dir) });
 
 describe('public surface', () => {
 	it('has measured a real surface', () => {
@@ -69,7 +77,7 @@ describe('public surface', () => {
 		// 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  ')}`,
+			`surface came off and the ratchet was not tightened — run \`bun run surface --prune\`:\n  ${result.stale.join('\n  ')}`,
 		).toEqual([]);
 	});
 });

package/src/react/file-tree/FileTree.tsx

@@ -189,6 +189,7 @@ import {
   toggleSelected,
   topmostSelected,
 } from './fileTreeSelection.js';
+import { useInView } from '../media/previewGate.js';
 import './fileTree.css';
 
 /** How far a press travels before it stops being a click and becomes a drag. */
@@ -597,6 +598,16 @@ function DefaultIcon({ node, open }: { node: FileTreeNode; open: boolean }): Rea
  *
  * `loading='lazy'` and `decoding='async'` because the consumer hands over a URL per row and a
  * 2,000-row tree must not open 2,000 connections to draw the twelve rows on screen.
+ *
+ * 🔴 …and `src` is withheld until the row has actually been ON SCREEN, because `lazy` alone
+ * does not bound it. A browser's lazy threshold is thousands of pixels past the viewport, and
+ * rows are ~24 px: measured 2026-09-22 in `apps/collections`' browser check, a 240-row folder
+ * in the rail had **174** thumbnail loads open at once under `loading='lazy'` — the whole of
+ * the owner's "I could not close the dev tools" peak, from sixteen-pixel pictures. `useInView`
+ * reports true only while the row is visible inside its scrolling ancestors; the first time it
+ * does, the picture is latched and the row stops being observed. The `<img>` itself stays in
+ * place meanwhile, so the row keeps its one glyph box — an off-screen row is blank, which
+ * nobody is looking at. No reporting observer (jsdom, happy-dom) means visible at once.
  */
 function RowGlyph({
   node,
@@ -610,12 +621,19 @@ function RowGlyph({
   const [failed, setFailed] = useState<string | null>(null);
   const icon = renderIcon ? renderIcon(node) : <DefaultIcon node={node} open={open} />;
   const src = node.thumbnailUrl;
+  const ref = useRef<HTMLImageElement>(null);
+  const [seen, setSeen] = useState(false);
+  const inView = useInView(ref, Boolean(src) && failed !== src && !seen);
+  useEffect(() => {
+    if (inView) setSeen(true);
+  }, [inView]);
   if (!src || failed === src) return icon;
   return (
     <img
+      ref={ref}
       key={src}
       className='cbft-thumb'
-      src={src}
+      src={seen || inView ? src : undefined}
       alt=''
       aria-hidden='true'
       loading='lazy'

package/src/react/file-tree/fileTreeThumbs.spec.tsx

@@ -0,0 +1,90 @@
+/**
+ * The rail's row thumbnails load only once their row has been ON SCREEN — `RowGlyph` in
+ * `FileTree.tsx`. `loading='lazy'` alone let a 240-row folder open 174 thumbnail loads at once
+ * (measured 2026-09-22 in `apps/collections`' browser check), because a browser's lazy threshold
+ * is thousands of pixels and a row is ~24.
+ *
+ * happy-dom's `IntersectionObserver` never reports, so this installs one it can drive, the way
+ * `media/previewGate.spec.tsx` does.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { act, cleanup, render } from '@testing-library/react';
+import { FileTree } from './FileTree.js';
+
+type Callback = (entries: Array<{ target: Element; isIntersecting: boolean }>) => void;
+let observers: FakeObserver[] = [];
+
+class FakeObserver {
+  targets = new Set<Element>();
+  constructor(private readonly callback: Callback) {
+    observers.push(this);
+  }
+  observe(el: Element) {
+    this.targets.add(el);
+  }
+  unobserve(el: Element) {
+    this.targets.delete(el);
+  }
+  disconnect() {
+    this.targets.clear();
+  }
+  takeRecords() {
+    return [];
+  }
+  get thresholds(): number[] {
+    return [0];
+  }
+  fire(el: Element, isIntersecting: boolean) {
+    this.callback([{ target: el, isIntersecting }]);
+  }
+}
+
+const g = globalThis as { IntersectionObserver?: unknown };
+const original = g.IntersectionObserver;
+
+beforeEach(() => {
+  observers = [];
+  g.IntersectionObserver = class extends FakeObserver {};
+});
+
+afterEach(() => {
+  cleanup();
+  if (original === undefined) delete g.IntersectionObserver;
+  else g.IntersectionObserver = original;
+});
+
+const rows = Array.from({ length: 3 }, (_, i) => ({
+  id: `p${i}`,
+  name: `photo${i}.jpg`,
+  kind: 'file' as const,
+  thumbnailUrl: `/t/p${i}.jpg`,
+}));
+
+describe('a row thumbnail waits for its row to be seen', () => {
+  test('🔴 an off-screen row asks for nothing; the first sight loads it, and it stays loaded', () => {
+    const { container } = render(<FileTree nodes={rows} selectedId={null} onSelect={() => undefined} />);
+    const imgs = [...container.querySelectorAll('img.cbft-thumb')] as HTMLImageElement[];
+    expect(imgs).toHaveLength(3);
+    // Nothing reported yet: no row has a src, so no request has gone out.
+    expect(imgs.map((img) => img.getAttribute('src'))).toEqual([null, null, null]);
+
+    const observer = observers.find((o) => o.targets.size > 0) as FakeObserver;
+    const [first] = imgs;
+    act(() => observer.fire(first as Element, true));
+    expect(first?.getAttribute('src')).toBe('/t/p0.jpg');
+    expect(imgs[1]?.getAttribute('src')).toBeNull();
+
+    // Scrolled away again: the picture is kept, and the row is no longer observed.
+    act(() => observer.fire(first as Element, false));
+    expect(first?.getAttribute('src')).toBe('/t/p0.jpg');
+    expect(observer.targets.has(first as Element)).toBe(false);
+    expect(observer.targets.size).toBe(2);
+  });
+
+  test('with no reporting observer every thumbnail loads at once — the old behavior, never none', () => {
+    delete g.IntersectionObserver;
+    const { container } = render(<FileTree nodes={rows} selectedId={null} onSelect={() => undefined} />);
+    const srcs = [...container.querySelectorAll('img.cbft-thumb')].map((img) => img.getAttribute('src'));
+    expect(srcs).toEqual(['/t/p0.jpg', '/t/p1.jpg', '/t/p2.jpg']);
+  });
+});

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

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from 'bun:test';
-import { cleanup, fireEvent, render } from '@testing-library/react';
+import { cleanup, fireEvent, render, waitFor } from '@testing-library/react';
 import type { PlayableVideo } from 'cursedbelt-core/media';
 import { HoverScrubVideoThumb } from './HoverScrubVideoThumb.js';
 
@@ -68,9 +68,10 @@ describe('HoverScrubVideoThumb', () => {
     expect(container.querySelectorAll('svg').length).toBeLessThan(before);
   });
 
-  test('autoPlay mode previews without hover and renders without onOpen as a non-button', () => {
+  test('autoPlay mode previews without hover and renders without onOpen as a non-button', async () => {
     const { container, queryByRole } = render(<HoverScrubVideoThumb video={video} autoPlay />);
-    expect(container.querySelector('video')).not.toBeNull();
+    // No IntersectionObserver in happy-dom → the tile counts as visible, and starts once settled.
+    await waitFor(() => expect(container.querySelector('video')).not.toBeNull());
     expect(queryByRole('button')).toBeNull();
   });
 

package/src/react/media/HoverScrubVideoThumb.tsx

@@ -4,6 +4,7 @@ import type { PlayableVideo } from 'cursedbelt-core/media';
 import { formatTimecode } from 'cursedbelt-core/media';
 import { cn } from '../lib/cn.js';
 import { NO_EDIT, previewTransform, swapsAxes } from './pictureEdit.js';
+import { releaseVideo, useInView, useSettled } from './previewGate.js';
 import type { MediaOrientation } from './VideoTurner.js';
 
 /**
@@ -104,7 +105,13 @@ export interface HoverScrubVideoThumbProps {
    * - `loop`: plays from the start, muted, looping.
    */
   previewMode?: 'scrub' | 'loop';
-  /** Preview continuously without hover — the watch page's silent side tiles. */
+  /**
+   * Preview continuously without hover — the watch page's silent side tiles.
+   *
+   * 🔴 Gated: the preview starts only once the tile is ON SCREEN and has stayed there for
+   * `PREVIEW_SETTLE_MS` (`previewGate.ts`), so a grid scrolled past fast never opens a stream
+   * per row. Without an `IntersectionObserver` the tile counts as visible.
+   */
   autoPlay?: boolean;
   /** Small overlay chips (top-left slot) — e.g. a quality badge. */
   badge?: ReactNode;
@@ -149,7 +156,11 @@ export function HoverScrubVideoThumb({
   // On touch devices ignore `autoPlay` — an unrequested video playing under the
   // finger reads as a bug (and iOS shows a stack of them below the watch player).
   // Touch-and-hold still triggers `hovering` → a preview on demand.
-  const previewing = (autoPlay && canHover) || hovering;
+  const boxRef = useRef<HTMLDivElement>(null);
+  const wantsAuto = autoPlay && canHover;
+  // A hover is not gated: the pointer on the tile IS the intent the settle exists to infer.
+  const autoReady = useSettled(useInView(boxRef, wantsAuto));
+  const previewing = autoReady || hovering;
   const holdTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
   const videoRef = useRef<HTMLVideoElement>(null);
 
@@ -167,15 +178,23 @@ export function HoverScrubVideoThumb({
     durationSeconds: video.durationSeconds,
   });
 
+  // A preview that stops closes its connection — an unmounted `<video>` keeps buffering.
+  useEffect(() => {
+    if (!previewing) return;
+    const el = videoRef.current;
+    return () => releaseVideo(el);
+  }, [previewing]);
+
   const turned = turnStyle(orientation);
 
   const media = (
-    <div className='relative aspect-video w-full overflow-hidden bg-muted'>
+    <div ref={boxRef} className='relative aspect-video w-full overflow-hidden bg-muted'>
       {video.posterUrl && !posterFailed ? (
         <img
           src={video.posterUrl}
           alt={video.name}
           loading='lazy'
+          decoding='async'
           /*
            * 🔴 A poster URL that 404s falls back to the Play mark, and this is
            * REQUIRED rather than defensive.
@@ -255,6 +274,9 @@ export function HoverScrubVideoThumb({
         <video
           ref={videoRef}
           src={video.streamUrl}
+          // Only mounted once previewing (settled or hovered), so metadata is the most it may
+          // fetch before it plays — never the whole-file `auto` a browser may default to.
+          preload='metadata'
           muted
           loop
           autoPlay

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

@@ -0,0 +1,144 @@
+/**
+ * The video half of the gallery's load ceiling (`previewGate.ts`): an automatic preview starts
+ * only once its tile is on screen AND has settled there, and a tile scrolled past never starts.
+ *
+ * happy-dom's `IntersectionObserver` never reports, so each test installs a fake it can drive —
+ * a fresh class per test, which is also what proves the shared observer follows a replaced
+ * global instead of observing through a stale one.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { act, cleanup, render, waitFor } from '@testing-library/react';
+import type { PlayableVideo } from 'cursedbelt-core/media';
+import { HoverScrubVideoThumb } from './HoverScrubVideoThumb.js';
+import { PREVIEW_SETTLE_MS, releaseVideo } from './previewGate.js';
+
+const video: PlayableVideo = {
+  id: 'v1',
+  name: 'Clip one',
+  streamUrl: 'https://example.test/v1.mp4',
+  posterUrl: 'https://example.test/v1.jpg',
+  durationSeconds: 90,
+};
+
+type Callback = (entries: Array<{ target: Element; isIntersecting: boolean }>) => void;
+let observers: FakeObserver[] = [];
+
+class FakeObserver {
+  targets = new Set<Element>();
+  constructor(private readonly callback: Callback) {
+    observers.push(this);
+  }
+  observe(el: Element) {
+    this.targets.add(el);
+  }
+  unobserve(el: Element) {
+    this.targets.delete(el);
+  }
+  disconnect() {
+    this.targets.clear();
+  }
+  takeRecords() {
+    return [];
+  }
+  /** On the PROTOTYPE, as the real interface has it — what `reportingObserver` checks for. */
+  get thresholds(): number[] {
+    return [0];
+  }
+  fire(isIntersecting: boolean) {
+    this.callback([...this.targets].map((target) => ({ target, isIntersecting })));
+  }
+}
+
+const g = globalThis as { IntersectionObserver?: unknown };
+/** Whatever the environment had, restored after each test so no later spec file inherits a fake. */
+const original = g.IntersectionObserver;
+
+beforeEach(() => {
+  observers = [];
+  // A NEW class each test: the gate must rebuild its shared observer for a replaced global.
+  g.IntersectionObserver = class extends FakeObserver {};
+});
+
+afterEach(() => {
+  cleanup();
+  if (original === undefined) delete g.IntersectionObserver;
+  else g.IntersectionObserver = original;
+});
+
+const live = () => observers.find((o) => o.targets.size > 0) as FakeObserver;
+const pause = (ms: number) =>
+  act(async () => {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+  });
+
+describe('previewGate — an automatic preview waits until the tile is on screen and settled', () => {
+  test('🔴 an off-screen autoPlay tile has no <video> — no src, nothing autoplaying', async () => {
+    const { container } = render(<HoverScrubVideoThumb video={video} onOpen={() => {}} autoPlay />);
+    await waitFor(() => expect(live()).toBeDefined());
+    act(() => live().fire(false));
+    await pause(PREVIEW_SETTLE_MS + 60);
+    expect(container.querySelector('video')).toBeNull();
+    // The poster still stands in, and it is itself lazy.
+    expect(container.querySelector('img')?.getAttribute('loading')).toBe('lazy');
+  });
+
+  test('in view: nothing at once, the preview after it settles — with preload capped', async () => {
+    const { container } = render(<HoverScrubVideoThumb video={video} onOpen={() => {}} autoPlay />);
+    await waitFor(() => expect(live()).toBeDefined());
+    act(() => live().fire(true));
+    // Not yet: a tile crossing the viewport during a scroll is exactly this moment.
+    expect(container.querySelector('video')).toBeNull();
+    await waitFor(() => expect(container.querySelector('video')).not.toBeNull());
+    const el = container.querySelector('video') as HTMLVideoElement;
+    expect(el.getAttribute('src')).toBe(video.streamUrl);
+    expect(el.getAttribute('preload')).toBe('metadata');
+  });
+
+  test('🔴 a tile that leaves before settling never starts its load — the fast scroll', async () => {
+    const { container } = render(<HoverScrubVideoThumb video={video} onOpen={() => {}} autoPlay />);
+    await waitFor(() => expect(live()).toBeDefined());
+    act(() => live().fire(true));
+    await pause(PREVIEW_SETTLE_MS / 3);
+    act(() => live().fire(false));
+    await pause(PREVIEW_SETTLE_MS + 60);
+    expect(container.querySelector('video')).toBeNull();
+  });
+
+  test('a preview that scrolls off stops at once and its connection is released', async () => {
+    const { container } = render(<HoverScrubVideoThumb video={video} onOpen={() => {}} autoPlay />);
+    await waitFor(() => expect(live()).toBeDefined());
+    act(() => live().fire(true));
+    await waitFor(() => expect(container.querySelector('video')).not.toBeNull());
+    const el = container.querySelector('video') as HTMLVideoElement;
+    act(() => live().fire(false));
+    expect(container.querySelector('video')).toBeNull();
+    // Removing the element does not close its request; emptying `src` does.
+    expect(el.hasAttribute('src')).toBe(false);
+  });
+
+  test('🔴 an INERT observer (happy-dom 20 ships one) counts as absent, so the tile still previews', async () => {
+    g.IntersectionObserver = class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+      takeRecords() {
+        return [];
+      }
+    };
+    const { container } = render(<HoverScrubVideoThumb video={video} onOpen={() => {}} autoPlay />);
+    await waitFor(() => expect(container.querySelector('video')).not.toBeNull());
+  });
+
+  test('without autoPlay no tile is observed at all', () => {
+    render(<HoverScrubVideoThumb video={video} onOpen={() => {}} />);
+    expect(observers.every((o) => o.targets.size === 0)).toBe(true);
+  });
+
+  test('releaseVideo tolerates null and an element with no media support', () => {
+    expect(() => releaseVideo(null)).not.toThrow();
+    const el = document.createElement('video');
+    el.setAttribute('src', '/x.mp4');
+    releaseVideo(el);
+    expect(el.hasAttribute('src')).toBe(false);
+  });
+});