cursedbelt 4.4.0 → 4.6.0

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/privateClient.spec.ts

@@ -4,8 +4,8 @@ import {
   privateHlsUrlWithToken,
   revealPrivateWithPassword,
   revealPrivateWithToken,
-} from './privateClient';
-import { usePrivateUnlock } from './usePrivateUnlock';
+} from './privateClient.js';
+import { usePrivateUnlock } from './usePrivateUnlock.js';
 
 // Mock fetch — the helpers are pure client plumbing; assert the request they build and the
 // response shape they return.

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

@@ -7,7 +7,7 @@ import {
   sourceFaultFromStatus,
   SourceFaultOverlay,
   sourceFaultMessage,
-} from './sourceFault';
+} from './sourceFault.js';
 
 afterEach(cleanup);
 

package/src/react/media/stageResize.spec.ts

@@ -17,7 +17,7 @@ import {
   STAGE_HEIGHT_KEY,
   stageHeightFromDrag,
   writeStageHeight,
-} from './stageResize';
+} from './stageResize.js';
 
 describe('stageHeightFromDrag', () => {
   test('dragging down makes the viewer bigger, one pixel per pixel', () => {

package/src/react/media/surfaceGesture.spec.ts

@@ -15,8 +15,8 @@
  * breaks if it is dropped, so each gets a case.
  */
 import { describe, expect, test } from 'bun:test';
-import { isSurfaceControl, SURFACE_CONTROL_SELECTOR } from './surfaceGesture';
-import { toggleFullscreenOnSurfaceDoubleClick } from './VideoPlayer';
+import { isSurfaceControl, SURFACE_CONTROL_SELECTOR } from './surfaceGesture.js';
+import { toggleFullscreenOnSurfaceDoubleClick } from './VideoPlayer.js';
 
 /** Build `outer > inner` and hand back the inner element, which is what a press reports. */
 function nest(outerHtml: string, innerTag = 'span'): Element {

package/src/react/media/usePrivateUnlock.ts

@@ -7,7 +7,7 @@ import {
   type RevealedItem,
   revealPrivateWithPassword,
   revealPrivateWithToken,
-} from './privateClient';
+} from './privateClient.js';
 
 // ── usePrivateUnlock ────────────────────────────────────────────────────────────
 // The client state machine for encrypted private media. It drives the cursedbelt-server
@@ -17,7 +17,7 @@ import {
 // shapes live in ./privateClient (hook-free) so a component holding a PASSED-IN token (via a
 // cross-plugin port) can call the same endpoints without this hook's state.
 
-export type { PrivateIndexRow, RevealedItem } from './privateClient';
+export type { PrivateIndexRow, RevealedItem } from './privateClient.js';
 
 export type UsePrivateUnlockOptions = PrivateClientConfig;
 

package/src/react/media/videoChapters.spec.ts

@@ -13,7 +13,7 @@ import {
   MIN_CHAPTER_SECONDS,
   normalizeChapters,
   type VideoChapter,
-} from './videoChapters';
+} from './videoChapters.js';
 
 const at = (startSeconds: number, title: string): VideoChapter => ({ startSeconds, title });
 const shape = (chapters: readonly VideoChapter[]): string =>

package/src/react/media/videoEnhance.spec.ts

@@ -11,7 +11,7 @@ import {
 	isEnhanced,
 	readEnhance,
 	snapshotSize,
-} from "./videoEnhance";
+} from "./videoEnhance.js";
 
 describe("filterString", () => {
 	test("an untouched picture is 'none', never an empty string", () => {

package/src/react/media/videoPoster.spec.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { pickBestFrame, posterCandidateTimes, scoreFrame } from './videoPoster';
+import { pickBestFrame, posterCandidateTimes, scoreFrame } from './videoPoster.js';
 
 /** A solid block of one colour, as RGBA — the fades and flat frames real footage opens on. */
 const flat = (r: number, g: number, b: number, pixels = 64): Uint8ClampedArray => {

package/src/react/media/videoRegion.spec.ts

@@ -18,7 +18,7 @@ import {
 	regionZoom,
 	stageAspectFor,
 	zoomRegion,
-} from "./videoRegion";
+} from "./videoRegion.js";
 
 describe("zoomRegion", () => {
 	test("keeps the centre fixed — the subject does not slide out of view", () => {

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

@@ -34,12 +34,13 @@
 import { formatBytes } from 'cwip/format';
 import type { DragEvent } from 'react';
 import { type ReactNode, useCallback, useEffect, useRef, useState } from 'react';
-import { CATEGORY_LABEL } from '../components/FileTypeIcon';
-import { useResizeObserver } from '../hooks/useResizeObserver';
-import { useCanHover, useScrubPreview } from '../media/HoverScrubVideoThumb';
-import { createdLabel, type MediaCache, ThumbImg, useItemMedia } from './galleryItemMedia';
-import { galleryItemCategory } from './mediaGalleryModel';
-import type { MediaGalleryItem, MediaGalleryOrder } from './types';
+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';
 
 /**
  * Row height in px. It is a CONSTANT rather than a measurement because the spacer-row
@@ -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

@@ -29,8 +29,8 @@ for (const prop of ['clientHeight', 'offsetHeight'] as const) {
 }
 HTMLElement.prototype.getBoundingClientRect = () => RECT;
 
-import { MediaGallery, galleryTileLine, stagePlayableVideo } from './MediaGallery';
-import type { MediaGalleryItem } from './types';
+import { MediaGallery, galleryTileLine, stagePlayableVideo } from './MediaGallery.js';
+import type { MediaGalleryItem } from './types.js';
 
 afterEach(cleanup);
 
@@ -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/ }));
   });