cursedbelt 4.5.0 → 4.6.0

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

package/src/react/media/previewGate.ts

@@ -0,0 +1,160 @@
+/**
+ * When a tile is allowed to start a VIDEO load — the gallery's ceiling on byte loads.
+ *
+ * ── 🔴 Why this exists, from `collections`' 2026-09-22 measurement ──────────────────────
+ * One wheel-scroll top to bottom of a 240-row gallery had **176 same-origin requests open at
+ * once** (`apps/collections/e2e/mintCeiling.browser.test.ts`), and none of them were `fetch`
+ * calls an app-side gate could see: they were the tiles' own `<img>` and `<video>` loads. The
+ * `<img>` half is `loading='lazy'` + `decoding='async'` on every tile picture; this file is the
+ * `<video>` half. With "Preview all" on, every tile the virtualizer mounted — the visible rows
+ * AND its overscan — attached an autoplaying `<video>` the moment it rendered, so a fast
+ * scroll opened a stream per row it passed and then abandoned it.
+ *
+ * So an automatic preview now waits for two things: the tile is actually on screen
+ * ({@link useInView}), and it has STAYED there for {@link PREVIEW_SETTLE_MS}
+ * ({@link useSettled}). A tile scrolled past faster than that never starts its load at all,
+ * and one that leaves before settling cancels the pending start. A deliberate hover is not
+ * gated — the pointer being on the tile is the intent the settle exists to infer.
+ *
+ * {@link releaseVideo} is the other end: a `<video>` React removes keeps downloading until it
+ * is garbage-collected, so a tile that stops previewing empties the element's source, which is
+ * what actually closes the connection.
+ */
+import { useEffect, useState } from 'react';
+
+/**
+ * How long a tile must stay on screen before an automatic preview starts. Long enough that a
+ * wheel flick past a row is well under it (a row crosses the viewport in tens of ms at scroll
+ * speed), short enough that a grid the viewer stopped on starts moving without a visible wait.
+ */
+export const PREVIEW_SETTLE_MS = 200;
+
+type Listener = (inView: boolean) => void;
+
+/**
+ * ONE observer for every tile, not one per tile — a 400-row gallery is 400 elements and a
+ * single `IntersectionObserver` handles that in one callback per frame.
+ *
+ * Keyed by the constructor it was built with so a replaced global (a spec installing its own
+ * fake, a polyfill arriving late) is picked up instead of observing through a stale one.
+ */
+let shared: { ctor: typeof IntersectionObserver; observer: IntersectionObserver } | null = null;
+const listeners = new Map<Element, Set<Listener>>();
+
+/**
+ * The environment's `IntersectionObserver`, but only one that can actually REPORT.
+ *
+ * 🔴 happy-dom 20 ships an inert stub — `observe()` is an empty method and the callback is
+ * never called — so "is it defined" is the wrong test: every tile would wait for a
+ * notification that cannot arrive and no preview would ever start, in this repo's specs and in
+ * every consumer's. The real interface carries `thresholds` as a readonly attribute on its
+ * PROTOTYPE (every engine since 2019); the stub does not. An observer without it is treated as
+ * absent, which degrades to the eager behavior every gallery had before this gate.
+ */
+function reportingObserver(): typeof IntersectionObserver | null {
+  const ctor = (globalThis as { IntersectionObserver?: typeof IntersectionObserver })
+    .IntersectionObserver;
+  if (typeof ctor !== 'function') return null;
+  return 'thresholds' in ctor.prototype ? ctor : null;
+}
+
+function sharedObserver(): IntersectionObserver | null {
+  const ctor = reportingObserver();
+  if (!ctor) return null;
+  if (shared?.ctor === ctor) return shared.observer;
+  shared?.observer.disconnect();
+  const observer = new ctor((entries) => {
+    for (const entry of entries) {
+      const set = listeners.get(entry.target);
+      if (!set) continue;
+      for (const listener of set) listener(entry.isIntersecting);
+    }
+  });
+  shared = { ctor, observer };
+  // Anything already registered moves to the new observer rather than going deaf.
+  for (const el of listeners.keys()) observer.observe(el);
+  return observer;
+}
+
+/**
+ * True while the element intersects the viewport (clipped by its scrolling ancestors, which
+ * is what an `IntersectionObserver` with no root measures).
+ *
+ * 🔴 **No `IntersectionObserver` means VISIBLE**, not hidden. jsdom and old browsers have none,
+ * happy-dom has one that never reports (see {@link reportingObserver}), and a gallery whose previews silently never start there is a worse failure than
+ * one that loads eagerly — the eager load is the behavior every one of them had before this.
+ *
+ * `enabled: false` observes nothing and reports false, so a gallery that never asked for
+ * automatic previews registers no element at all.
+ */
+export function useInView(ref: { current: Element | null }, enabled: boolean): boolean {
+  const [inView, setInView] = useState(false);
+  useEffect(() => {
+    if (!enabled) {
+      setInView(false);
+      return;
+    }
+    const el = ref.current;
+    const observer = sharedObserver();
+    if (!el || !observer) {
+      setInView(true);
+      return;
+    }
+    const listener: Listener = (next) => setInView(next);
+    let set = listeners.get(el);
+    if (!set) {
+      set = new Set();
+      listeners.set(el, set);
+      observer.observe(el);
+    }
+    set.add(listener);
+    return () => {
+      const current = listeners.get(el);
+      if (!current) return;
+      current.delete(listener);
+      if (current.size === 0) {
+        listeners.delete(el);
+        shared?.observer.unobserve(el);
+      }
+    };
+    // `ref` is a ref object and is stable by construction.
+  }, [enabled, ref]);
+  return enabled && inView;
+}
+
+/**
+ * `value`, but it only turns TRUE after holding true for `ms` — and turns false at once.
+ *
+ * The asymmetry is the point: starting a load is what costs, stopping one is what saves, so a
+ * flicker of `true` (a tile crossing the viewport during a scroll) never reaches the load and
+ * a `false` is never delayed.
+ */
+export function useSettled(value: boolean, ms: number = PREVIEW_SETTLE_MS): boolean {
+  const [settled, setSettled] = useState(false);
+  useEffect(() => {
+    if (!value) {
+      setSettled(false);
+      return;
+    }
+    const timer = setTimeout(() => setSettled(true), ms);
+    return () => clearTimeout(timer);
+  }, [value, ms]);
+  return value && settled;
+}
+
+/**
+ * Close a `<video>`'s connection. Removing the element from the DOM does not — it keeps
+ * buffering until it is collected — so emptying `src` and calling `load()` is the documented
+ * way to make the browser drop the request (WHATWG media "emptied" / load algorithm).
+ * Tolerates a missing element and a `load` the environment does not implement.
+ */
+export function releaseVideo(el: HTMLVideoElement | null): void {
+  if (!el) return;
+  try {
+    el.pause?.();
+    el.removeAttribute('src');
+    el.load?.();
+  } catch {
+    // A DOM without media support has no connection to close.
+  }
+}

package/src/react/media-gallery/GalleryTable.tsx

@@ -37,6 +37,7 @@ import { type ReactNode, useCallback, useEffect, useRef, useState } from 'react'
 import { CATEGORY_LABEL } from '../components/FileTypeIcon.js';
 import { useResizeObserver } from '../hooks/useResizeObserver.js';
 import { useCanHover, useScrubPreview } from '../media/HoverScrubVideoThumb.js';
+import { releaseVideo, useInView, useSettled } from '../media/previewGate.js';
 import { createdLabel, type MediaCache, ThumbImg, useItemMedia } from './galleryItemMedia.js';
 import { galleryItemCategory } from './mediaGalleryModel.js';
 import type { MediaGalleryItem, MediaGalleryOrder } from './types.js';
@@ -411,12 +412,19 @@ function TableVideoPreview({
 }) {
   const ref = useRef<HTMLVideoElement | null>(null);
   useScrubPreview(ref, { active, durationSeconds: item.durationSeconds });
+  // Removing the element does not close its connection; emptying its source does.
+  useEffect(() => {
+    const el = ref.current;
+    return () => releaseVideo(el);
+  }, []);
   return (
     // biome-ignore lint/a11y/useMediaCaption: a muted 56px preview of an arbitrary user file
     <video
       ref={ref}
       src={src}
       poster={poster}
+      // Mounted only once previewing, so metadata is the most it fetches before it plays.
+      preload='metadata'
       muted
       loop
       autoPlay
@@ -477,7 +485,11 @@ function GalleryTableRow({
   const previewSrc = category === 'video' ? (media.streamUrl ?? media.url) : undefined;
   // `autoPreview` is suppressed on a coarse pointer exactly as the grid tile suppresses it, so
   // a phone never opens forty video connections under a finger. A deliberate hover still does.
-  const previewing = previewSrc != null && ((autoPreview && canHover) || hovering);
+  // 🔴 And it waits until the row is on screen and has SETTLED there (`previewGate.ts`), the
+  // same gate the grid tile uses — a table scrolled past fast must not open a stream per row.
+  const thumbRef = useRef<HTMLButtonElement | null>(null);
+  const autoReady = useSettled(useInView(thumbRef, previewSrc != null && autoPreview && canHover));
+  const previewing = previewSrc != null && (autoReady || hovering);
 
   return (
     <tr
@@ -523,6 +535,7 @@ function GalleryTableRow({
         <button
           // guardrails-ignore no-raw-action-button: the row's own open affordance; see above.
           type='button'
+          ref={thumbRef}
           className='cbgt-open cbgt-open--thumb'
           onClick={onOpen}
           aria-label={`Open ${item.name}`}

package/src/react/media-gallery/MediaGallery.spec.tsx

@@ -166,6 +166,50 @@ describe('MediaGallery browse grid', () => {
     );
     expect(calls).toBe(1);
   });
+
+  test('🔴 grid tiles AND table rows draw their pictures lazy + async (the load ceiling)', () => {
+    const { getByRole, container } = render(<MediaGallery items={ITEMS} />);
+    const gridImgs = [...container.querySelectorAll('.cbgd-photo-tile img')];
+    expect(gridImgs.length).toBeGreaterThan(0);
+    for (const img of gridImgs) {
+      expect(img.getAttribute('loading')).toBe('lazy');
+      expect(img.getAttribute('decoding')).toBe('async');
+    }
+    fireEvent.click(getByRole('button', { name: /Table/ }));
+    const rowImgs = [...container.querySelectorAll('.cbgt-root img')];
+    expect(rowImgs.length).toBeGreaterThan(0);
+    for (const img of rowImgs) {
+      expect(img.getAttribute('loading')).toBe('lazy');
+      expect(img.getAttribute('decoding')).toBe('async');
+    }
+  });
+
+  test('🔴 toggling grid → table mid-resolve neither aborts nor re-asks (one shared entry)', async () => {
+    const signals: AbortSignal[] = [];
+    let answer: ((m: { url: string; thumbnailUrl: string }) => void) | undefined;
+    const lazy: MediaGalleryItem = {
+      id: 'lazy2',
+      name: 'slow.png',
+      resolveMedia: (signal) =>
+        new Promise((resolve) => {
+          if (signal) signals.push(signal);
+          answer = resolve;
+        }),
+    };
+    const { getByRole, container } = render(<MediaGallery items={[lazy]} />);
+    expect(signals).toHaveLength(1);
+    // Every grid tile unmounts before any table row mounts — the moment a naive refcount aborts.
+    fireEvent.click(getByRole('button', { name: /Table/ }));
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    expect(signals).toHaveLength(1);
+    expect(signals[0]?.aborted).toBe(false);
+    answer?.({ url: '/resolved/lazy2', thumbnailUrl: '/resolved-thumb/lazy2' });
+    await waitFor(() =>
+      expect(container.querySelector('.cbgt-root img')?.getAttribute('src')).toBe(
+        '/resolved-thumb/lazy2',
+      ),
+    );
+  });
 });
 
 describe('MediaGallery multi-select (opt-in)', () => {
@@ -1723,13 +1767,16 @@ describe('🔴 Preview all reaches the TABLE, not only the grid', () => {
     fireEvent.click(view.getByRole('button', { name: /Table/ }));
   };
 
-  test('a video row swaps its still for a live preview when the toggle is on', () => {
+  test('a video row swaps its still for a live preview when the toggle is on', async () => {
     const view = render(<MediaGallery items={ITEMS} />);
     showTable(view);
     // Off: every row is a still, the film's included.
     expect(view.container.querySelector('.cbgt-root video')).toBeNull();
 
     fireEvent.click(view.getByRole('button', { name: /Preview all/ }));
+    // Not at once: an automatic preview waits for the row to SETTLE (`previewGate.ts`).
+    expect(view.container.querySelector('.cbgt-root video')).toBeNull();
+    await waitFor(() => expect(view.container.querySelector('.cbgt-root video')).not.toBeNull());
     const preview = view.container.querySelector('.cbgt-root video') as HTMLVideoElement;
     expect(preview).not.toBeNull();
     expect(preview.getAttribute('src')).toBe('/files/vid1');
@@ -1743,12 +1790,14 @@ describe('🔴 Preview all reaches the TABLE, not only the grid', () => {
     fireEvent.click(view.getByRole('button', { name: /Preview all/ }));
   });
 
-  test('a STILL row is untouched by the toggle', () => {
+  test('a STILL row is untouched by the toggle', async () => {
     const view = render(<MediaGallery items={ITEMS} />);
     showTable(view);
     fireEvent.click(view.getByRole('button', { name: /Preview all/ }));
     // beach.jpg and report.pdf keep their images; only the film becomes a `<video>`.
-    expect(view.container.querySelectorAll('.cbgt-root video')).toHaveLength(1);
+    await waitFor(() =>
+      expect(view.container.querySelectorAll('.cbgt-root video')).toHaveLength(1),
+    );
     fireEvent.click(view.getByRole('button', { name: /Preview all/ }));
   });
 

package/src/react/media-gallery/MediaGallery.tsx

@@ -735,7 +735,15 @@ function DocThumb({
     <>
       {/* `key={src}`: a new thumbnail URL is a new attempt and must not inherit the
           previous one's recorded failure. */}
-      <img key={src} src={src} alt={alt} loading='lazy' onError={() => setFailed(true)} />
+      <img
+        key={src}
+        src={src}
+        alt={alt}
+        // Lazy + async like every tile picture — see `ThumbImg` for the measurement.
+        loading='lazy'
+        decoding='async'
+        onError={() => setFailed(true)}
+      />
       <span className='cbmg-doc-badge'>
         <FileTypeIcon category={category} />
       </span>