cursedbelt 4.5.0 → 4.6.0

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