perf(app): progressive thumbnail loading (400→800→1200) on zoom

Replaces the static _800.webp variant with a tier-aware loader:

- Initial paint loads _400.webp (~6 KB, ~1.9 MB total) — fast.
- nodeCanvasObject receives globalScale, computes the on-screen
  device-pixel size of each visible node, and picks the smallest
  pipeline tier (400/800/1200) that comfortably covers it.
- If that tier isn't loaded yet, ensureNodeTier() kicks off a fetch
  and force-graph repaints when it lands (no jank, no physics restart).
- pickBestLoadedTier falls back to a smaller tier during the upgrade
  so nodes never go blank.

force-graph only invokes nodeCanvasObject for visible nodes, so
zooming in fetches hi-res only for what the user is actually looking
at — no fan-out to off-screen specs.

New helpers (all unit-tested): RESOLUTION_TIERS, buildVariantUrl,
pickTier, pickBestLoadedTier, ensureNodeTier. Smoke test fixtures
updated for the new MapNode shape (imgs Map + pendingTiers Set).

Refs #5646

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MarkusNeusinger

app/src/pages/MapPage.helpers.test.ts

@@ -6,6 +6,9 @@ import {
   weightedJaccard,
   buildKNNLinks,
   selectMapThumbUrl,
+  buildVariantUrl,
+  pickTier,
+  pickBestLoadedTier,
   type SpecMapItem,
 } from './MapPage.helpers';
 
@@ -160,28 +163,79 @@ describe('buildKNNLinks', () => {
 
 
 describe('selectMapThumbUrl', () => {
-  it('returns the _800.webp variant for the current theme', () => {
+  it('returns the dark URL in dark mode and light URL in light mode', () => {
     const s = spec('a', null);
-    expect(selectMapThumbUrl(s, true)).toBe('https://example.com/a-dark_800.webp');
-    expect(selectMapThumbUrl(s, false)).toBe('https://example.com/a-light_800.webp');
+    expect(selectMapThumbUrl(s, true)).toBe('https://example.com/a-dark.png');
+    expect(selectMapThumbUrl(s, false)).toBe('https://example.com/a-light.png');
   });
 
-  it('falls back to the other theme variant when the preferred URL is missing', () => {
+  it('falls back to the other theme when the preferred URL is missing', () => {
     const s: SpecMapItem = { ...spec('a', null), preview_url_dark: null };
-    expect(selectMapThumbUrl(s, true)).toBe('https://example.com/a-light_800.webp');
+    expect(selectMapThumbUrl(s, true)).toBe('https://example.com/a-light.png');
   });
 
   it('returns null when no preview URLs at all', () => {
     const s: SpecMapItem = { ...spec('a', null), preview_url_light: null, preview_url_dark: null };
     expect(selectMapThumbUrl(s, false)).toBeNull();
   });
+});
+
+
+describe('buildVariantUrl', () => {
+  it('rewrites .png to _{tier}.webp', () => {
+    expect(buildVariantUrl('https://example.com/plot.png', 400)).toBe('https://example.com/plot_400.webp');
+    expect(buildVariantUrl('https://example.com/plot-light.png', 800)).toBe('https://example.com/plot-light_800.webp');
+    expect(buildVariantUrl('https://example.com/plot-dark.png', 1200)).toBe('https://example.com/plot-dark_1200.webp');
+  });
+
+  it('passes through URLs that do not end in .png', () => {
+    expect(buildVariantUrl('https://example.com/plot.svg', 400)).toBe('https://example.com/plot.svg');
+  });
+});
+
+
+describe('pickTier', () => {
+  it('returns 400 when device pixel size fits in 400 with headroom', () => {
+    expect(pickTier(100)).toBe(400);
+    expect(pickTier(300)).toBe(400);
+  });
+
+  it('returns 800 when 400 would require upscaling', () => {
+    expect(pickTier(500)).toBe(800);
+    expect(pickTier(600)).toBe(800);
+  });
+
+  it('returns 1200 for very large device sizes', () => {
+    expect(pickTier(1000)).toBe(1200);
+    expect(pickTier(2000)).toBe(1200);
+  });
+});
+
+
+describe('pickBestLoadedTier', () => {
+  function img(): HTMLImageElement {
+    return document.createElement('img');
+  }
+
+  it('returns the desired tier when loaded', () => {
+    const a = img();
+    const imgs = new Map([[400 as const, a]]);
+    expect(pickBestLoadedTier(imgs, 400)).toBe(a);
+  });
+
+  it('returns a higher-resolution variant when desired is not loaded', () => {
+    const a = img();
+    const imgs = new Map([[800 as const, a]]);
+    expect(pickBestLoadedTier(imgs, 400)).toBe(a);
+  });
+
+  it('falls back to a smaller tier when nothing larger is loaded', () => {
+    const a = img();
+    const imgs = new Map([[400 as const, a]]);
+    expect(pickBestLoadedTier(imgs, 800)).toBe(a);
+  });
 
-  it('returns the original URL unchanged if it does not end in .png', () => {
-    const s: SpecMapItem = {
-      ...spec('a', null),
-      preview_url_light: 'https://example.com/a-light.svg',
-      preview_url_dark: null,
-    };
-    expect(selectMapThumbUrl(s, false)).toBe('https://example.com/a-light.svg');
+  it('returns null when nothing is loaded', () => {
+    expect(pickBestLoadedTier(new Map(), 400)).toBeNull();
   });
 });

app/src/pages/MapPage.helpers.ts

@@ -21,13 +21,22 @@ export interface SpecMapItem {
   impl_tags: Record<string, string[]> | null;
 }
 
-/** Node shape passed to ForceGraph2D. `img` populated lazily as thumbnails resolve. */
+/** Resolution tiers baked by the responsive-image pipeline (responsiveImage.ts). */
+export const RESOLUTION_TIERS = [400, 800, 1200] as const;
+export type ResolutionTier = (typeof RESOLUTION_TIERS)[number];
+
+/**
+ * Node shape passed to ForceGraph2D. Holds a lazy collection of image variants
+ * keyed by resolution tier (400/800/1200). The page populates the 400 tier
+ * eagerly on load and progressively upgrades on zoom-in.
+ */
 export interface MapNode {
   id: string;
   title: string;
   tags: string[];
-  thumbUrl: string | null;
-  img?: HTMLImageElement;
+  thumbUrl: string | null;                       // base theme-aware .png URL
+  imgs: Map<ResolutionTier, HTMLImageElement>;   // loaded variants
+  pendingTiers: Set<ResolutionTier>;             // tiers with an in-flight fetch
 }
 
 /** Link shape passed to ForceGraph2D. `weight` = weighted-Jaccard sim ∈ (0, 1]. */
@@ -143,36 +152,101 @@ export function buildKNNLinks(
 }
 
 /**
- * Pick the best thumbnail URL for the current theme and downsize it to the
- * `_800.webp` variant produced by the responsive-image pipeline. _800 stays
- * crisp under typical zoom-in (the smaller _400 variant pixelates quickly),
- * while keeping the 312-thumbnail payload at ~5 MB total instead of the
- * ~15 MB the full-size originals would cost.
- *
- * Falls back to the original full-size URL if the convention can't be
- * applied (e.g. URL doesn't end in `.png`).
+ * Pick the theme-aware base preview URL (the original `.png`). Variant
+ * selection happens at draw time via {@link buildVariantUrl} + {@link pickTier}
+ * so we only fetch higher-resolution thumbnails for nodes the user actually
+ * zooms into.
  */
 export function selectMapThumbUrl(spec: SpecMapItem, isDark: boolean): string | null {
-  const full = selectPreviewUrl(spec, isDark);
-  if (!full) return null;
-  if (!full.endsWith('.png')) return full;
-  return full.replace(/\.png$/, '_800.webp');
+  return selectPreviewUrl(spec, isDark);
+}
+
+/**
+ * Derive the URL of a specific resolution variant from the base `.png` URL.
+ * `.../plot-light.png` + 800 → `.../plot-light_800.webp`. Returns the original
+ * URL unchanged if it doesn't end in `.png` (no variants available).
+ */
+export function buildVariantUrl(baseUrl: string, tier: ResolutionTier): string {
+  if (!baseUrl.endsWith('.png')) return baseUrl;
+  return baseUrl.replace(/\.png$/, `_${tier}.webp`);
+}
+
+/**
+ * Pick the smallest pipeline tier whose source resolution comfortably covers
+ * the requested device-pixel size. Source needs to be ≥ device pixels for
+ * crisp rendering — we add a small headroom factor so a tiny zoom-in nudge
+ * doesn't immediately re-fetch the next tier.
+ */
+export function pickTier(devicePxSize: number): ResolutionTier {
+  const HEADROOM = 1.25;
+  const target = devicePxSize * HEADROOM;
+  if (target <= 400) return 400;
+  if (target <= 800) return 800;
+  return 1200;
+}
+
+/**
+ * Return the highest-resolution tier that's already loaded and at least as
+ * big as `desired`. Falls back to a smaller tier if nothing larger is loaded
+ * yet (better than blank during the lazy upgrade).
+ */
+export function pickBestLoadedTier(
+  imgs: Map<ResolutionTier, HTMLImageElement>,
+  desired: ResolutionTier
+): HTMLImageElement | null {
+  for (const t of RESOLUTION_TIERS) {
+    if (t >= desired && imgs.has(t)) return imgs.get(t)!;
+  }
+  for (let i = RESOLUTION_TIERS.length - 1; i >= 0; i--) {
+    const t = RESOLUTION_TIERS[i];
+    if (imgs.has(t)) return imgs.get(t)!;
+  }
+  return null;
+}
+
+/**
+ * Lazily fetch the requested tier for a node and call `onLoad` when it lands.
+ * Idempotent — safe to call repeatedly from `nodeCanvasObject` on every paint.
+ * force-graph only invokes that callback for visible nodes, so off-screen
+ * specs never trigger a higher-tier fetch.
+ */
+export function ensureNodeTier(
+  node: MapNode,
+  tier: ResolutionTier,
+  onLoad: () => void
+): void {
+  if (!node.thumbUrl) return;
+  if (node.imgs.has(tier) || node.pendingTiers.has(tier)) return;
+  node.pendingTiers.add(tier);
+  const img = document.createElement('img');
+  img.onload = () => {
+    node.imgs.set(tier, img);
+    node.pendingTiers.delete(tier);
+    onLoad();
+  };
+  img.onerror = () => {
+    node.pendingTiers.delete(tier);
+  };
+  img.src = buildVariantUrl(node.thumbUrl, tier);
 }
 
 /**
- * Eager-preload every node's thumbnail. Resolves once all images either
- * loaded or errored — failures are swallowed (image stays undefined and
- * the node renders as a plain dot in nodeCanvasObject's fallback path).
+ * Eager-preload every node's thumbnail at the smallest tier (400 px wide ≈ 6 KB
+ * webp). Resolves once all images either loaded or errored — failures are
+ * swallowed (the node renders as a plain dot in the fallback path).
  *
  * `onLoad` fires per-image so the page can call fgRef.refresh() to re-paint
- * without re-running the simulation. This is what produces the "thumbnails
- * pop in organically" UX rather than a blocking wait.
+ * without re-running the simulation, producing the "thumbnails pop in
+ * organically" UX rather than a blocking wait. Higher-resolution tiers are
+ * lazy-loaded on demand by {@link ensureNodeTier} from `nodeCanvasObject`
+ * when the user zooms in.
  */
 export async function preloadImages(
   items: { id: string; thumbUrl: string | null }[],
-  onLoad?: (id: string, img: HTMLImageElement) => void
+  onLoad?: (id: string, tier: ResolutionTier, img: HTMLImageElement) => void
 ): Promise<Map<string, HTMLImageElement>> {
   const out = new Map<string, HTMLImageElement>();
+  const tier: ResolutionTier = 400;
   await Promise.all(
     items.map(({ id, thumbUrl }) => {
       if (!thumbUrl) return Promise.resolve();
@@ -186,11 +260,11 @@ export async function preloadImages(
         // becomes "tainted", which is fine — we never read it back).
         img.onload = () => {
           out.set(id, img);
-          onLoad?.(id, img);
+          onLoad?.(id, tier, img);
           resolve();
         };
         img.onerror = () => resolve();
-        img.src = thumbUrl;
+        img.src = buildVariantUrl(thumbUrl, tier);
       });
     })
   );

app/src/pages/MapPage.test.tsx

@@ -109,17 +109,15 @@ function mockFetchSuccess() {
 // jsdom doesn't ship ResizeObserver; stub it so the page's useEffect doesn't crash
 // AND fire the callback once with non-zero dimensions so the `size.w > 0` gate that
 // guards <ForceGraph2D> mounting is satisfied.
+type ResizeCb = (entries: { contentRect: { width: number; height: number } }[]) => void;
 class MockResizeObserver {
-  cb: ResizeObserverCallback;
-  constructor(cb: ResizeObserverCallback) {
+  cb: ResizeCb;
+  constructor(cb: ResizeCb) {
     this.cb = cb;
   }
-  observe(target: Element) {
+  observe(_target: Element) {
     setTimeout(() => {
-      this.cb(
-        [{ contentRect: { width: 800, height: 600 } } as unknown as ResizeObserverEntry],
-        this as unknown as ResizeObserver,
-      );
+      this.cb([{ contentRect: { width: 800, height: 600 } }]);
     }, 0);
   }
   unobserve() {}
@@ -188,9 +186,9 @@ describe('MapPage', () => {
     render(<MapPage />);
     await waitFor(() => expect(lastFgProps.current).not.toBeNull());
 
-    const drawNode = lastFgProps.current!.nodeCanvasObject as (n: unknown, c: unknown) => void;
+    const drawNode = lastFgProps.current!.nodeCanvasObject as (n: unknown, c: unknown, gs?: number) => void;
     const ctx = makeCtxStub();
-    drawNode({ id: 'scatter-basic', x: 100, y: 100 }, ctx);
+    drawNode({ id: 'scatter-basic', x: 100, y: 100, imgs: new Map(), pendingTiers: new Set() }, ctx, 1);
 
     // Without an attached image, the fallback rect path runs.
     expect(ctx.fillRect).toHaveBeenCalled();
@@ -203,10 +201,14 @@ describe('MapPage', () => {
     render(<MapPage />);
     await waitFor(() => expect(lastFgProps.current).not.toBeNull());
 
-    const drawNode = lastFgProps.current!.nodeCanvasObject as (n: unknown, c: unknown) => void;
+    const drawNode = lastFgProps.current!.nodeCanvasObject as (n: unknown, c: unknown, gs?: number) => void;
     const ctx = makeCtxStub();
     const fakeImg = { src: 'x' } as unknown as HTMLImageElement;
-    drawNode({ id: 'scatter-basic', x: 50, y: 50, img: fakeImg }, ctx);
+    drawNode(
+      { id: 'scatter-basic', x: 50, y: 50, imgs: new Map([[400, fakeImg]]), pendingTiers: new Set() },
+      ctx,
+      1,
+    );
 
     expect(ctx.drawImage).toHaveBeenCalledWith(fakeImg, expect.any(Number), expect.any(Number), expect.any(Number), expect.any(Number));
     expect(ctx.strokeRect).toHaveBeenCalled();

app/src/pages/MapPage.tsx

@@ -14,11 +14,15 @@ import { colors, fontSize, typography } from '../theme';
 import {
   buildKNNLinks,
   computeIDF,
+  ensureNodeTier,
   flattenTags,
+  pickBestLoadedTier,
+  pickTier,
   preloadImages,
   selectMapThumbUrl,
   type MapLink,
   type MapNode,
+  type ResolutionTier,
   type SpecMapItem,
 } from './MapPage.helpers';
 
@@ -108,23 +112,25 @@ export function MapPage() {
       title: s.title,
       tags: flattenTags(s),
       thumbUrl: selectMapThumbUrl(s, isDark),
+      imgs: new Map(),
+      pendingTiers: new Set(),
     }));
     const links = buildKNNLinks(specs, idf, KNN_K, KNN_MIN_SIM);
     return { nodes, links };
   }, [specs, isDark]);
 
-  // Preload thumbnails as a side effect; attach to nodes by reference and
-  // ask force-graph to repaint without restarting the physics simulation.
+  // Eager-load the 400-tier thumbnails so something paints fast. Higher tiers
+  // are fetched lazily from nodeCanvasObject when the user zooms in.
   useEffect(() => {
     if (graphData.nodes.length === 0) return;
     const nodeById = new Map(graphData.nodes.map(n => [n.id, n]));
     let cancelled = false;
     preloadImages(
       graphData.nodes.map(n => ({ id: n.id, thumbUrl: n.thumbUrl })),
-      (id, img) => {
+      (id, tier, img) => {
         if (cancelled) return;
         const n = nodeById.get(id);
-        if (n) n.img = img;
+        if (n) n.imgs.set(tier, img);
         fgRef.current?.refresh?.();
       }
     );
@@ -220,7 +226,7 @@ export function MapPage() {
             width={size.w}
             height={size.h}
             backgroundColor={'transparent'}
-            nodeCanvasObject={(node, ctx) => {
+            nodeCanvasObject={(node, ctx, globalScale) => {
               const n = node as WithCoords;
               if (n.x == null || n.y == null) return;
               const isHover = hoverId === n.id;
@@ -230,10 +236,22 @@ export function MapPage() {
               const x = n.x - baseSize / 2;
               const y = n.y - baseSize / 2;
 
+              // Pick the smallest variant whose source resolution comfortably
+              // covers the on-screen size, then lazy-load it if not yet present.
+              // force-graph only invokes nodeCanvasObject for visible nodes, so
+              // off-screen specs never trigger a higher-tier fetch.
+              const screenPx = baseSize * (globalScale ?? 1);
+              const dpr = typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1;
+              const desired: ResolutionTier = pickTier(screenPx * dpr);
+              if (n.imgs && !n.imgs.has(desired) && !n.pendingTiers?.has(desired)) {
+                ensureNodeTier(n, desired, () => fgRef.current?.refresh?.());
+              }
+              const img = n.imgs ? pickBestLoadedTier(n.imgs, desired) : null;
+
               ctx.save();
               if (dim) ctx.globalAlpha = 0.18;
-              if (n.img) {
-                ctx.drawImage(n.img, x, y, baseSize, baseSize);
+              if (img) {
+                ctx.drawImage(img, x, y, baseSize, baseSize);
               } else {
                 ctx.fillStyle = isDark ? '#242420' : '#FFFDF6';
                 ctx.fillRect(x, y, baseSize, baseSize);