cursedbelt 4.5.0 → 4.7.0

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>

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

@@ -0,0 +1,143 @@
+/**
+ * `useItemMedia`'s cancellation (task 107/461): a resolve is aborted when every mount waiting on
+ * it is gone, NOT while another still waits, and an abandoned entry is evicted so a remount asks
+ * again instead of inheriting the abort — the scrolled-past tile that would otherwise be grey
+ * forever.
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { act, cleanup, render, waitFor } from '@testing-library/react';
+import { type MediaCache, ThumbImg, useItemMedia } from './galleryItemMedia.js';
+import type { MediaGalleryItem, MediaGalleryItemMedia } from './types.js';
+
+afterEach(cleanup);
+
+/** A resolver whose answers the test hands out by hand, recording every signal it was given. */
+function deferredResolver() {
+  const signals: AbortSignal[] = [];
+  const answers: Array<(m: MediaGalleryItemMedia | null) => void> = [];
+  const resolveMedia = (signal?: AbortSignal) =>
+    new Promise<MediaGalleryItemMedia | null>((resolve, reject) => {
+      if (signal) signals.push(signal);
+      answers.push(resolve);
+      // What a `fetch` does with its signal: reject with an AbortError.
+      signal?.addEventListener('abort', () =>
+        reject(Object.assign(new Error('aborted'), { name: 'AbortError' })),
+      );
+    });
+  return { signals, answers, resolveMedia };
+}
+
+function Probe({ item, cache, label }: { item: MediaGalleryItem; cache: MediaCache; label: string }) {
+  const { media, resolving } = useItemMedia(item, cache);
+  return <span data-testid={label}>{resolving ? 'resolving' : (media.url ?? 'none')}</span>;
+}
+
+const newCache = (): MediaCache => ({ current: new Map() });
+/** Past the microtask the abandon check runs in. */
+const settle = () => act(async () => new Promise((resolve) => setTimeout(resolve, 0)));
+
+describe('useItemMedia — abort, refcount, evict', () => {
+  test('the resolve is handed an AbortSignal, and unmounting aborts it', async () => {
+    const r = deferredResolver();
+    const cache = newCache();
+    const item: MediaGalleryItem = { id: 'a', name: 'a.png', resolveMedia: r.resolveMedia };
+    const view = render(<Probe item={item} cache={cache} label='a' />);
+    expect(r.signals).toHaveLength(1);
+    expect(r.signals[0]?.aborted).toBe(false);
+    view.unmount();
+    await waitFor(() => expect(r.signals[0]?.aborted).toBe(true));
+    // 🔴 and EVICTED — the cache must not keep a promise that rejects with an abort.
+    expect(cache.current.has('a')).toBe(false);
+  });
+
+  test('🔴 two mounts on one entry: one unmounting does NOT abort the other', async () => {
+    const r = deferredResolver();
+    const cache = newCache();
+    const item: MediaGalleryItem = { id: 'b', name: 'b.png', resolveMedia: r.resolveMedia };
+    const view = render(
+      <>
+        <Probe item={item} cache={cache} label='grid' />
+        <Probe item={item} cache={cache} label='table' />
+      </>,
+    );
+    expect(r.signals).toHaveLength(1);
+    view.rerender(<Probe item={item} cache={cache} label='table' />);
+    await settle();
+    expect(r.signals[0]?.aborted).toBe(false);
+    expect(cache.current.has('b')).toBe(true);
+    act(() => r.answers[0]?.({ url: '/bytes/b' }));
+    await waitFor(() => expect(view.getByTestId('table').textContent).toBe('/bytes/b'));
+  });
+
+  test('🔴 an abandoned entry is evicted, and a remount re-asks and gets the bytes', async () => {
+    const r = deferredResolver();
+    const cache = newCache();
+    const item: MediaGalleryItem = { id: 'c', name: 'c.png', resolveMedia: r.resolveMedia };
+    render(<Probe item={item} cache={cache} label='first' />).unmount();
+    await waitFor(() => expect(r.signals[0]?.aborted).toBe(true));
+
+    const again = render(<Probe item={item} cache={cache} label='again' />);
+    expect(r.signals).toHaveLength(2);
+    expect(r.signals[1]?.aborted).toBe(false);
+    act(() => r.answers[1]?.({ url: '/bytes/c' }));
+    // Not "none": an abort is never read as "this item has no bytes".
+    await waitFor(() => expect(again.getByTestId('again').textContent).toBe('/bytes/c'));
+  });
+
+  test('a re-render with a NEW resolveMedia closure does not abort the resolve in flight', async () => {
+    // Apps build items inline, so `resolveMedia` is a fresh function every render and the
+    // effect re-runs (cleanup, then setup) each time. The abandon check must not fire on that.
+    const r = deferredResolver();
+    const cache = newCache();
+    const make = (): MediaGalleryItem => ({
+      id: 'd',
+      name: 'd.png',
+      resolveMedia: (signal) => r.resolveMedia(signal),
+    });
+    const view = render(<Probe item={make()} cache={cache} label='d' />);
+    view.rerender(<Probe item={make()} cache={cache} label='d' />);
+    view.rerender(<Probe item={make()} cache={cache} label='d' />);
+    await settle();
+    expect(r.signals).toHaveLength(1);
+    expect(r.signals[0]?.aborted).toBe(false);
+    act(() => r.answers[0]?.({ url: '/bytes/d' }));
+    await waitFor(() => expect(view.getByTestId('d').textContent).toBe('/bytes/d'));
+  });
+
+  test('a SETTLED answer is kept after unmount — the cache still saves the re-sign', async () => {
+    const r = deferredResolver();
+    const cache = newCache();
+    const item: MediaGalleryItem = { id: 'e', name: 'e.png', resolveMedia: r.resolveMedia };
+    const view = render(<Probe item={item} cache={cache} label='e' />);
+    act(() => r.answers[0]?.({ url: '/bytes/e' }));
+    await waitFor(() => expect(view.getByTestId('e').textContent).toBe('/bytes/e'));
+    view.unmount();
+    await settle();
+    expect(r.signals[0]?.aborted).toBe(false);
+    const again = render(<Probe item={item} cache={cache} label='e2' />);
+    await waitFor(() => expect(again.getByTestId('e2').textContent).toBe('/bytes/e'));
+    expect(r.signals).toHaveLength(1);
+  });
+
+  test('a genuine rejection is still "no bytes" for a live mount', async () => {
+    const cache = newCache();
+    const item: MediaGalleryItem = {
+      id: 'f',
+      name: 'f.png',
+      resolveMedia: async () => {
+        throw new Error('gone');
+      },
+    };
+    const view = render(<Probe item={item} cache={cache} label='f' />);
+    await waitFor(() => expect(view.getByTestId('f').textContent).toBe('none'));
+  });
+});
+
+describe('ThumbImg — the tile picture is lazy and decodes off the main thread', () => {
+  test('🔴 loading=lazy and decoding=async', () => {
+    const { container } = render(<ThumbImg src='/t.jpg' alt='' />);
+    const img = container.querySelector('img') as HTMLImageElement;
+    expect(img.getAttribute('loading')).toBe('lazy');
+    expect(img.getAttribute('decoding')).toBe('async');
+  });
+});

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

@@ -12,13 +12,67 @@ import { type MutableRefObject, useCallback, useEffect, useRef, useState } from
 import { staticItemMedia } from './mediaGalleryModel.js';
 import type { MediaGalleryItem, MediaGalleryItemMedia } from './types.js';
 
-export type MediaCache = MutableRefObject<Map<string, Promise<MediaGalleryItemMedia | null>>>;
+/**
+ * One item's in-flight or settled resolve, shared by every view that shows the item.
+ *
+ * `holders` counts the mounts awaiting it right now — a grid tile and a table row can both be
+ * on one entry, and so can the stage. The entry is only ABANDONED (aborted and evicted) when
+ * that count reaches zero before the answer arrived; see {@link useItemMedia}.
+ */
+export interface MediaCacheEntry {
+  promise: Promise<MediaGalleryItemMedia>;
+  controller: AbortController;
+  holders: number;
+  settled: boolean;
+}
+export type MediaCache = MutableRefObject<Map<string, MediaCacheEntry>>;
+
+/**
+ * Start one resolve for `item` and file it in the cache.
+ *
+ * The async wrapper is deliberate: a resolver that throws SYNCHRONOUSLY becomes a rejection
+ * like any other, instead of escaping the effect and taking the tile down.
+ */
+function startResolve(
+  id: string,
+  resolveMedia: MediaGalleryItem['resolveMedia'],
+  cache: MediaCache,
+): MediaCacheEntry {
+  const controller = new AbortController();
+  const promise = (async () => (await resolveMedia?.(controller.signal)) ?? {})();
+  const entry: MediaCacheEntry = { promise, controller, holders: 0, settled: false };
+  const settle = () => {
+    entry.settled = true;
+  };
+  promise.then(settle, settle);
+  cache.current.set(id, entry);
+  return entry;
+}
+
 /**
  * The item's resolved media: static URL fields immediately, `resolveMedia` results merged
  * in when the item needs them (cached per id for the gallery's lifetime).
  *
  * `refresh` throws the cached answer away and asks the app again — see its own note; it is
  * what makes a `403` from a stale signed URL recoverable instead of a sentence on screen.
+ *
+ * ── 🔴 Cancellation, and the two traps in it (task 107/461, 2026-09-22) ─────────────────
+ * Each resolve owns an `AbortController` whose signal is handed to `item.resolveMedia(signal)`.
+ * Before this, a tile that unmounted merely stopped listening: the request ran to completion
+ * for a tile that was gone, and a fast scroll left one open per row it passed.
+ *
+ *  · **Abort only when NOBODY is waiting.** The grid and the table share this cache (the file
+ *    header says why), so a tile and a row — or a tile and the stage — can be on one promise.
+ *    Each mount holds the entry; the abort fires only when the count reaches zero with the
+ *    answer still outstanding. The check runs a microtask AFTER the cleanup, because the
+ *    cleanup of one mount and the setup of its successor are not simultaneous: toggling grid →
+ *    table unmounts every tile before any row mounts, and an app that rebuilds `resolveMedia`
+ *    on each render re-runs this effect (cleanup, then setup) every render. An immediate check
+ *    would abort all of those.
+ *  · **An abandoned entry is EVICTED in the same step.** Otherwise the cache keeps a promise
+ *    that rejects with an abort, the next mount inherits it, and a tile the viewer scrolled past
+ *    is a grey box forever when he scrolls back. An abort is also never turned into "no bytes"
+ *    for a mount still on screen — if one ever sees its entry's signal aborted, it re-asks.
  */
 export function useItemMedia(
   item: MediaGalleryItem,
@@ -48,16 +102,15 @@ export function useItemMedia(
     return true;
   }, [item.id, needsResolve, cache]);
 
+  const { id, resolveMedia } = item;
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `attempt` is the re-ask — not read in the body, it is what re-runs it (see `refresh`).
   useEffect(() => {
     if (!needsResolve) return;
     let live = true;
-    let promise = cache.current.get(item.id);
-    if (!promise) {
-      promise = (item.resolveMedia?.() ?? Promise.resolve(null)).then((m) => m ?? {});
-      cache.current.set(item.id, promise);
-    }
+    const entry = cache.current.get(id) ?? startResolve(id, resolveMedia, cache);
+    entry.holders += 1;
     setResolving(true);
-    promise
+    entry.promise
       .then((m) => {
         if (!live) return;
         setResolved(m);
@@ -65,14 +118,27 @@ export function useItemMedia(
       })
       .catch(() => {
         if (!live) return;
+        if (entry.controller.signal.aborted) {
+          // Our own abandonment reached a mount that is still here — re-ask rather than
+          // report an abort as a missing file. The entry is already evicted.
+          if (cache.current.get(id) === entry) cache.current.delete(id);
+          setAttempt((n) => n + 1);
+          return;
+        }
         setResolved({});
         setResolving(false);
       });
     return () => {
       live = false;
+      entry.holders -= 1;
+      queueMicrotask(() => {
+        if (entry.holders > 0 || entry.settled || entry.controller.signal.aborted) return;
+        // Abandoned: nobody is waiting and the answer never arrived.
+        if (cache.current.get(id) === entry) cache.current.delete(id);
+        entry.controller.abort();
+      });
     };
-    // `attempt` is the re-ask: it is not read in the body, it is what re-runs it.
-  }, [item.id, needsResolve, cache, item.resolveMedia, attempt]);
+  }, [id, needsResolve, cache, resolveMedia, attempt]);
 
   return { media: { ...(resolved ?? {}), ...staticMedia }, resolving, refresh };
 }
@@ -141,7 +207,12 @@ export function ThumbImg({
     <img
       src={failed && canFallBack ? (fallbackSrc as string) : src}
       alt={alt}
+      // 🔴 Both, on every tile picture: `lazy` keeps an off-screen tile from opening a request,
+      // `async` keeps a wall of decodes off the main thread during a scroll. The tiles' own
+      // `<img>` loads are invisible to any app-side fetch gate (collections measured 176 open
+      // at once on one scroll, 2026-09-22), so this is the only place they can be bounded.
       loading='lazy'
+      decoding='async'
       {...(draggable === undefined ? {} : { draggable })}
       {...(style && Object.keys(style).length > 0 ? { style } : {})}
       onError={canFallBack ? () => setFailed(true) : undefined}

package/src/react/media-gallery/types.ts

@@ -171,6 +171,13 @@ 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>;
 }

package/src/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/src/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/src/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