@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/graphClipboard.ts

@@ -0,0 +1,414 @@
+// The material graph's clipboard codec: a selection out, a selection back in.
+//
+// ── WHY A CODEC AND NOT A STRUCTURED CLONE ──────────────────────────────
+//
+// A copied region is not a graph. It has wires whose far end was left behind,
+// it names exposed controls that the graph it lands in may not have, it may
+// reference an image asset that document does not carry, and it may sit inside
+// a function body that only exists in the graph it came from. Handing those
+// nodes to another graph verbatim writes a document `validateMaterialGraph`
+// refuses — and the refusal would arrive at the SAVE, one gesture too late to
+// say what went wrong.
+//
+// So paste is a REWRITE with a report. `remapClip` mints every id fresh,
+// resolves the exposed controls by type, drops what cannot survive the trip,
+// and says what it dropped in sentences the store puts on screen. Nothing here
+// touches the document: the store takes the pieces and builds the one graph it
+// passes through `updateProjectMaterial`'s validated door.
+//
+// ── AND WHY THE TRANSPORT IS TEXT ───────────────────────────────────────
+//
+// `navigator.clipboard` carries strings, which is what lets a copy in one
+// browser tab paste into a graph in another. `decodeClip` is therefore TOTAL
+// over garbage: the string it is handed is whatever the operating system's
+// clipboard happened to hold, and half of the time that is a filename.
+import {
+  MATERIAL_GRAPH_EDGE_ID_PREFIX,
+  MATERIAL_GRAPH_FUNCTION_ID_PREFIX,
+  MATERIAL_GRAPH_NODE_ID_PREFIX,
+  MATERIAL_GRAPH_PARAMETER_ID_PREFIX,
+  materialGraphNodeSpec,
+} from "@dailies-studio/shot/doc";
+import type {
+  MaterialGraph3D,
+  MaterialGraphEdge,
+  MaterialGraphFunction,
+  MaterialGraphNode,
+  MaterialGraphParameter,
+  ShotAsset,
+} from "@dailies-studio/shot/doc";
+
+/** The wrapper string, so a paste can tell one of ours from a filename. */
+export const MATERIAL_CLIP_FORMAT = "dailies.material-graph-clip";
+
+/**
+ * A copied region, as it crosses the clipboard.
+ *
+ * `nodes` holds BOTH the copied selection and the bodies of any functions it
+ * calls; a body node is the one whose `scope` names a function in `functions`.
+ * They share one list because that is how a graph stores them, and keeping the
+ * shape the same is what lets `remapClip` walk one array rather than reconcile
+ * two.
+ */
+export interface MaterialGraphClip {
+  format: typeof MATERIAL_CLIP_FORMAT;
+  version: 1;
+  nodes: MaterialGraphNode[];
+  edges: MaterialGraphEdge[];
+  parameters: Record<string, MaterialGraphParameter>;
+  functions: Record<string, MaterialGraphFunction>;
+}
+
+/** What a paste produces: pieces to merge, plus what did not survive. */
+export interface MaterialClipPaste {
+  nodes: MaterialGraphNode[];
+  edges: MaterialGraphEdge[];
+  /** Only the controls the target graph did not already have under a usable
+   *  id. An empty record is the common case: most pastes reuse. */
+  parameters: Record<string, MaterialGraphParameter>;
+  /** Only the functions the target graph did not already have. */
+  functions: Record<string, MaterialGraphFunction>;
+  /** One sentence per thing that was left behind, ready for the error strip. */
+  dropped: string[];
+}
+
+/**
+ * A selection, packed.
+ *
+ * THREE KINDS OF NODE NEVER TRAVEL. The material output is one per graph, and a
+ * second one pasted in is a document the validator refuses; `fn-input` and
+ * `fn-output` describe a function's BOUNDARY, and a boundary pasted outside the
+ * function it bounds names a socket that is not there. They are skipped rather
+ * than refused, because a rubber band that happened to cross the output is a
+ * copy of everything else, not a failed copy.
+ */
+export function encodeClip(graph: MaterialGraph3D, nodeIds: readonly string[]): MaterialGraphClip {
+  const picked = new Map<string, MaterialGraphNode>();
+  for (const id of [...new Set(nodeIds)].sort()) {
+    const node = graph.nodesById[id];
+    if (node === undefined || !copyable(node)) continue;
+    picked.set(id, node);
+  }
+
+  // The functions the picked nodes CALL, transitively: a body may itself hold a
+  // Subgraph node, and a clip that carried the outer function but not the inner
+  // one would paste a call to a function nobody shipped.
+  const functions: Record<string, MaterialGraphFunction> = {};
+  const bodies = new Map<string, MaterialGraphNode>();
+  const pending = [...picked.values()];
+  while (pending.length > 0) {
+    const node = pending.pop()!;
+    if (node.kind !== "subgraph") continue;
+    const id = node.functionId;
+    if (id === undefined || functions[id] !== undefined) continue;
+    const fn = graph.functions?.[id];
+    if (fn === undefined) continue;
+    functions[id] = fn;
+    for (const key of Object.keys(graph.nodesById).sort()) {
+      const body = graph.nodesById[key]!;
+      if (body.scope !== id || bodies.has(key)) continue;
+      bodies.set(key, body);
+      pending.push(body);
+    }
+  }
+
+  const all = new Map<string, MaterialGraphNode>([...picked, ...bodies]);
+  const parameters: Record<string, MaterialGraphParameter> = {};
+  for (const node of all.values()) {
+    if (node.kind !== "parameter" || node.parameterId === undefined) continue;
+    const parameter = graph.parameters[node.parameterId];
+    if (parameter !== undefined) parameters[node.parameterId] = parameter;
+  }
+
+  return {
+    format: MATERIAL_CLIP_FORMAT,
+    version: 1,
+    nodes: [...all.values()],
+    edges: graph.edges.filter((edge) => all.has(edge.source.nodeId) && all.has(edge.target.nodeId)),
+    parameters,
+    functions,
+  };
+}
+
+/** The output node and the two function boundaries never leave their graph. */
+function copyable(node: MaterialGraphNode): boolean {
+  if (node.kind === "fn-input" || node.kind === "fn-output") return false;
+  return materialGraphNodeSpec(node.kind)?.category !== "output";
+}
+
+/**
+ * Whatever the clipboard held, as a clip or as null.
+ *
+ * TOTAL over garbage by construction: it parses inside a try, then checks the
+ * wrapper before believing one field of the payload. Everything past the
+ * wrapper is coerced to the right SHAPE (an array, a record) rather than
+ * validated in detail, because `remapClip` already drops what it cannot use and
+ * the store puts the result through `validateMaterialGraph` after that. Two
+ * validators for one string would be two places to disagree.
+ */
+export function decodeClip(text: string): MaterialGraphClip | null {
+  if (typeof text !== "string" || text.length === 0) return null;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const clip = asRecord(parsed);
+  if (clip === null || clip["format"] !== MATERIAL_CLIP_FORMAT || clip["version"] !== 1) return null;
+  const nodes = Array.isArray(clip["nodes"]) ? clip["nodes"] : [];
+  const kept: MaterialGraphNode[] = [];
+  for (const raw of nodes) {
+    const node = asRecord(raw);
+    if (node === null) continue;
+    if (typeof node["id"] !== "string" || typeof node["kind"] !== "string") continue;
+    if (!finitePair(node["position"])) continue;
+    if (materialGraphNodeSpec(node["kind"]) === null) continue;
+    kept.push(node as unknown as MaterialGraphNode);
+  }
+  const edges = (Array.isArray(clip["edges"]) ? clip["edges"] : []).filter(isEdge);
+  return {
+    format: MATERIAL_CLIP_FORMAT,
+    version: 1,
+    nodes: kept,
+    edges,
+    parameters: recordOfShape(clip["parameters"], isParameter),
+    functions: recordOfShape(clip["functions"], isFunction),
+  };
+}
+
+/** How a paste's node ids and control ids are minted. The store owns the
+ *  source, so a replayed undo mints the same ids the first run did. */
+export interface MaterialClipRemapOptions {
+  /** The function body the paste lands in, or undefined for the main scope. */
+  scope?: string | undefined;
+  /** The document's assets, so a texture node with nowhere to read from is
+   *  dropped here rather than refused at the save. Absent skips the check. */
+  assets?: Readonly<Record<string, ShotAsset>> | undefined;
+  /** Added to every top-level node's position, so a paste lands where the
+   *  author asked rather than exactly on top of what they copied. */
+  offset?: readonly [number, number] | undefined;
+}
+
+/**
+ * A clip, rewritten to fit the graph it is landing in.
+ *
+ * FOUR RESOLUTIONS, and each is the one that keeps the paste honest:
+ *
+ *   IDS are all fresh, so pasting into the graph a clip came from is a copy
+ *     rather than a no-op that silently overwrote the original.
+ *   A CONTROL the target already has under the same id is REUSED when the type
+ *     agrees and re-keyed when it does not. Reuse is what an author means by
+ *     pasting a Roughness node back into the material it came from; re-keying
+ *     is what stops a float control from being silently redefined as a colour.
+ *   A FUNCTION the target already has is reused whole, body and all, and the
+ *     clip's copy of it is thrown away — otherwise every paste of one call site
+ *     would fork the function it calls.
+ *   ANYTHING THAT CANNOT LAND is dropped and NAMED. A texture with no asset, a
+ *     Subgraph whose function travelled in neither the clip nor the target, a
+ *     group box that was outside the rubber band.
+ */
+export function remapClip(
+  clip: MaterialGraphClip,
+  graph: MaterialGraph3D,
+  mint: (prefix: string) => string,
+  options: MaterialClipRemapOptions = {},
+): MaterialClipPaste {
+  const dropped: string[] = [];
+
+  // 1. A function the target already has is REUSED; only the ones it does not
+  //    have are minted, and only those carry their bodies across.
+  const fnId = new Map<string, string>();
+  const reusedFn = new Set<string>();
+  for (const id of Object.keys(clip.functions).sort()) {
+    if (graph.functions?.[id] !== undefined) {
+      fnId.set(id, id);
+      reusedFn.add(id);
+    } else fnId.set(id, mint(MATERIAL_GRAPH_FUNCTION_ID_PREFIX));
+  }
+
+  // 2. Which nodes survive. A body node of a reused function is dropped in
+  //    silence — the target already holds an identical one — while everything
+  //    else that cannot land says so.
+  const survives = new Map<string, MaterialGraphNode>();
+  for (const node of clip.nodes) {
+    if (node.scope !== undefined && reusedFn.has(node.scope)) continue;
+    const spec = materialGraphNodeSpec(node.kind);
+    if (spec === null) continue;
+    if (spec.fields.includes("assetId") && options.assets !== undefined) {
+      const asset = node.assetId === undefined ? undefined : options.assets[node.assetId];
+      if (asset === undefined || asset.kind !== "image") {
+        dropped.push(`${spec.label} was left out: this document has no image asset "${node.assetId ?? ""}".`);
+        continue;
+      }
+    }
+    if (node.kind === "subgraph") {
+      const target = node.functionId;
+      const known = target !== undefined && (fnId.has(target) || graph.functions?.[target] !== undefined);
+      if (!known) {
+        dropped.push(`A Subgraph node was left out: the function it calls did not come with it.`);
+        continue;
+      }
+    }
+    survives.set(node.id, node);
+  }
+
+  // 3. Mint the new ids, now that the surviving set is known.
+  const nodeId = new Map<string, string>();
+  for (const id of [...survives.keys()].sort()) nodeId.set(id, mint(MATERIAL_GRAPH_NODE_ID_PREFIX));
+
+  // 4. Exposed controls, resolved by type against the graph the paste lands in.
+  const paramId = new Map<string, string>();
+  const parameters: Record<string, MaterialGraphParameter> = {};
+  for (const id of Object.keys(clip.parameters).sort()) {
+    const parameter = clip.parameters[id]!;
+    const existing = graph.parameters[id];
+    if (existing === undefined) {
+      paramId.set(id, id);
+      parameters[id] = parameter;
+      continue;
+    }
+    if (existing.type === parameter.type) {
+      paramId.set(id, id);
+      continue;
+    }
+    const fresh = mint(MATERIAL_GRAPH_PARAMETER_ID_PREFIX);
+    paramId.set(id, fresh);
+    parameters[fresh] = { ...parameter, id: fresh };
+    dropped.push(
+      `"${parameter.label}" was pasted as a second control: this material already has a ${existing.type} control under that name.`,
+    );
+  }
+
+  const offset = options.offset ?? [0, 0];
+  const nodes: MaterialGraphNode[] = [];
+  for (const id of [...survives.keys()].sort()) {
+    const node = survives.get(id)!;
+    const body = node.scope !== undefined && fnId.has(node.scope);
+    const scope = body ? fnId.get(node.scope!) : options.scope;
+    // A GROUP THAT DID NOT TRAVEL leaves its members loose rather than pointing
+    // at a box the paste never created — which the validator would refuse.
+    const group = node.groupId === undefined ? undefined : nodeId.get(node.groupId);
+    if (node.groupId !== undefined && group === undefined) {
+      dropped.push(`One node was pasted outside its group: the group box was not part of the copy.`);
+    }
+    const position: [number, number] = body
+      ? [node.position[0], node.position[1]]
+      : [node.position[0] + offset[0], node.position[1] + offset[1]];
+    const next: MaterialGraphNode = {
+      ...node,
+      id: nodeId.get(id)!,
+      position,
+      ...(scope === undefined ? {} : { scope }),
+      ...(group === undefined ? {} : { groupId: group }),
+      ...(node.parameterId === undefined ? {} : { parameterId: paramId.get(node.parameterId) ?? node.parameterId }),
+      ...(node.functionId === undefined ? {} : { functionId: fnId.get(node.functionId) ?? node.functionId }),
+    };
+    if (scope === undefined) delete next.scope;
+    if (group === undefined) delete next.groupId;
+    nodes.push(next);
+  }
+
+  const edges: MaterialGraphEdge[] = [];
+  for (const edge of clip.edges) {
+    const source = nodeId.get(edge.source.nodeId);
+    const target = nodeId.get(edge.target.nodeId);
+    if (source === undefined || target === undefined) continue;
+    edges.push({
+      id: mint(MATERIAL_GRAPH_EDGE_ID_PREFIX),
+      source: { nodeId: source, socket: edge.source.socket },
+      target: { nodeId: target, socket: edge.target.socket },
+    });
+  }
+
+  const functions: Record<string, MaterialGraphFunction> = {};
+  for (const [id, fn] of Object.entries(clip.functions)) {
+    if (reusedFn.has(id)) continue;
+    const fresh = fnId.get(id)!;
+    const outputNodeId = nodeId.get(fn.outputNodeId);
+    if (outputNodeId === undefined) {
+      dropped.push(`Function "${fn.name}" was left out: its Function Output node did not come with it.`);
+      continue;
+    }
+    functions[fresh] = { ...fn, id: fresh, outputNodeId, inputs: fn.inputs.map((input) => ({ ...input })) };
+  }
+  // A function that lost its output takes its call sites with it, or the paste
+  // would land a call to a function the graph does not have.
+  const orphan = new Set(
+    [...fnId.entries()]
+      .filter(([id, fresh]) => !reusedFn.has(id) && functions[fresh] === undefined)
+      .map(([, fresh]) => fresh),
+  );
+  if (orphan.size > 0) {
+    const dead = new Set(
+      nodes.filter((node) => node.functionId !== undefined && orphan.has(node.functionId)).map((n) => n.id),
+    );
+    return {
+      nodes: nodes.filter((node) => !dead.has(node.id) && !(node.scope !== undefined && orphan.has(node.scope))),
+      edges: edges.filter((edge) => !dead.has(edge.source.nodeId) && !dead.has(edge.target.nodeId)),
+      parameters,
+      functions,
+      // DEDUPED, because a group box left behind is one fact however many of
+      // its members noticed. Twelve copies of one sentence in the error strip
+      // reads as twelve problems.
+      dropped: [...new Set(dropped)],
+    };
+  }
+
+  return { nodes, edges, parameters, functions, dropped: [...new Set(dropped)] };
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+function finitePair(value: unknown): boolean {
+  return (
+    Array.isArray(value) && value.length === 2 && value.every((n) => typeof n === "number" && Number.isFinite(n))
+  );
+}
+
+function isEdge(value: unknown): value is MaterialGraphEdge {
+  const edge = asRecord(value);
+  if (edge === null || typeof edge["id"] !== "string") return false;
+  return isEndpoint(edge["source"]) && isEndpoint(edge["target"]);
+}
+
+function isEndpoint(value: unknown): boolean {
+  const end = asRecord(value);
+  return end !== null && typeof end["nodeId"] === "string" && typeof end["socket"] === "string";
+}
+
+function isParameter(value: unknown): value is MaterialGraphParameter {
+  const parameter = asRecord(value);
+  return (
+    parameter !== null &&
+    typeof parameter["id"] === "string" &&
+    typeof parameter["label"] === "string" &&
+    (["float", "color", "vec2", "vec3"] as unknown[]).includes(parameter["type"])
+  );
+}
+
+function isFunction(value: unknown): value is MaterialGraphFunction {
+  const fn = asRecord(value);
+  return (
+    fn !== null &&
+    typeof fn["id"] === "string" &&
+    typeof fn["name"] === "string" &&
+    typeof fn["outputNodeId"] === "string" &&
+    Array.isArray(fn["inputs"]) &&
+    asRecord(fn["output"]) !== null
+  );
+}
+
+function recordOfShape<T>(value: unknown, is: (candidate: unknown) => candidate is T): Record<string, T> {
+  const record = asRecord(value);
+  if (record === null) return {};
+  const out: Record<string, T> = {};
+  for (const [key, candidate] of Object.entries(record)) {
+    if (is(candidate)) out[key] = candidate;
+  }
+  return out;
+}

package/src/state/imageThumbs.ts

@@ -0,0 +1,216 @@
+// SMALL PICTURES OF PROJECT IMAGES: a tile that shows an image at 100px
+// should not decode and hold the 4000px original. Each image is fetched once,
+// decoded with `createImageBitmap`, resized, drawn to a canvas and kept as a
+// webp object URL in this page. Never stored as files.
+//
+// KEYED ON THE ASSET'S CONTENT HASH AND A SIZE BUCKET (a power of two from
+// `IMAGE_THUMB_MIN_PX`), so the board, the shot board and the Assets tab share
+// one picture per image and size, and a re-upload under the same name (a new
+// hash) asks for a new one.
+//
+// THE ORIGINAL WHEN THERE IS NO GAIN OR NO WAY: no `createImageBitmap` (a
+// suite, an old browser), an image already within the bucket, a bucket past
+// `IMAGE_THUMB_MAX_PX`, or a decode that fails (some browsers refuse an SVG
+// blob). A thumbnail is decoration: a failure is never a thrown error.
+//
+// ONE DECODE AT A TIME, so a board of fifty pictures never holds fifty
+// full-size bitmaps at once.
+// ponytail: a fixed LRU of 128 pictures; size it from the views if a board
+// shows more than that at once.
+import { useState, useSyncExternalStore } from "react";
+
+/** The smallest bucket: a 20px pinned-row thumb still asks for 64. */
+export const IMAGE_THUMB_MIN_PX = 64;
+/** Past this the original is shown: a thumbnail this large saves little. */
+export const IMAGE_THUMB_MAX_PX = 2048;
+export const IMAGE_THUMB_ENTRIES = 128;
+
+/** The bucket a longest side of `px` asks for: the next power of two, at
+ *  least `IMAGE_THUMB_MIN_PX`. Null past `IMAGE_THUMB_MAX_PX`. */
+export function thumbBucket(px: number): number | null {
+  const want = Math.max(IMAGE_THUMB_MIN_PX, Math.ceil(Number.isFinite(px) ? px : IMAGE_THUMB_MAX_PX + 1));
+  const bucket = 2 ** Math.ceil(Math.log2(want));
+  return bucket > IMAGE_THUMB_MAX_PX ? null : bucket;
+}
+
+/** What a thumbnail answers: a picture to show, or null while it is drawn. */
+export type ImageThumb = string | null;
+
+export interface ImageThumbsDeps {
+  /** False skips every draw and answers the original. Default: whether
+   *  `createImageBitmap` and a canvas exist. */
+  supported?: boolean;
+  /** The image's bytes. Default `fetch`. */
+  load?: (url: string) => Promise<Blob>;
+  /** The resized picture whose longest side is at most `bucket`, or null when
+   *  the image is already that small. Default `resizeToWebp`. */
+  resize?: (blob: Blob, bucket: number) => Promise<Blob | null>;
+  createObjectURL?: (blob: Blob) => string;
+  revokeObjectURL?: (url: string) => void;
+  maxEntries?: number;
+}
+
+export interface ImageThumbs {
+  /** The picture of `url` (content `hash`) for a longest side of `maxPx`:
+   *  the thumbnail, the original when there is no gain or no way, or null
+   *  while it is drawn. Queues a draw when it has none. */
+  thumb(url: string, hash: string, maxPx: number): ImageThumb;
+  /** Called after each change to what `thumb` answers. Returns the
+   *  unsubscribe. */
+  subscribe(listener: () => void): () => void;
+  dispose(): void;
+}
+
+interface Entry {
+  readonly url: string;
+  /** The thumbnail's object URL, or the original's URL; absent while drawn. */
+  shown?: string;
+  /** True when `shown` is an object URL this cache made and must revoke. */
+  owned?: boolean;
+}
+
+export function createImageThumbs(deps: ImageThumbsDeps = {}): ImageThumbs {
+  const supported =
+    deps.supported ?? (typeof createImageBitmap === "function" && (typeof OffscreenCanvas === "function" || typeof document !== "undefined"));
+  const load = deps.load ?? ((url: string) => fetch(url).then((r) => (r.ok ? r.blob() : Promise.reject(new Error(`${r.status}`)))));
+  const resize = deps.resize ?? resizeToWebp;
+  const createUrl = deps.createObjectURL ?? ((blob: Blob) => URL.createObjectURL(blob));
+  const revokeUrl = deps.revokeObjectURL ?? ((url: string) => URL.revokeObjectURL(url));
+  const maxEntries = deps.maxEntries ?? IMAGE_THUMB_ENTRIES;
+
+  /** Insertion order is recency: `thumb` moves an entry to the end. */
+  const entries = new Map<string, Entry>();
+  const listeners = new Set<() => void>();
+  /** The one decode chain. */
+  let chain: Promise<void> = Promise.resolve();
+  let disposed = false;
+
+  const notify = (): void => {
+    for (const listener of [...listeners]) listener();
+  };
+  const drop = (entry: Entry): void => {
+    if (entry.owned === true && entry.shown !== undefined) revokeUrl(entry.shown);
+  };
+  const evict = (): void => {
+    for (const [key, entry] of entries) {
+      if (entries.size <= maxEntries) return;
+      entries.delete(key);
+      drop(entry);
+    }
+  };
+
+  const draw = (key: string, entry: Entry, bucket: number): void => {
+    chain = chain.then(async () => {
+      if (disposed || entries.get(key) !== entry) return;
+      let shown = entry.url;
+      let owned = false;
+      try {
+        const small = await resize(await load(entry.url), bucket);
+        if (small !== null) {
+          shown = createUrl(small);
+          owned = true;
+        }
+      } catch {
+        // The original stands in.
+      }
+      if (disposed || entries.get(key) !== entry) {
+        if (owned) revokeUrl(shown);
+        return;
+      }
+      entry.shown = shown;
+      if (owned) entry.owned = true;
+      notify();
+    })
+      // A link that threw (a listener, say) must not stop every later draw:
+      // `then` on a rejected chain runs nothing.
+      .catch(() => {});
+  };
+
+  return {
+    thumb(url, hash, maxPx) {
+      const bucket = thumbBucket(maxPx);
+      if (!supported || bucket === null || hash === "") return url;
+      const key = `${hash}@${bucket}`;
+      // The same bytes under a new URL (a rename) keep their picture.
+      let entry = entries.get(key);
+      if (entry === undefined) {
+        entry = { url };
+        entries.set(key, entry);
+        evict();
+        draw(key, entry, bucket);
+      } else {
+        entries.delete(key);
+        entries.set(key, entry);
+      }
+      return entry.shown ?? null;
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    dispose() {
+      disposed = true;
+      for (const entry of entries.values()) drop(entry);
+      entries.clear();
+      listeners.clear();
+    },
+  };
+}
+
+/**
+ * The browser's resize: decode, scale the longest side to `bucket` with a
+ * high-quality resample, draw to a canvas and encode webp. Null when the image
+ * is already within the bucket, so the original shows.
+ */
+export async function resizeToWebp(blob: Blob, bucket: number): Promise<Blob | null> {
+  const full = await createImageBitmap(blob);
+  try {
+    const longest = Math.max(full.width, full.height);
+    if (longest <= bucket) return null;
+    const width = Math.max(1, Math.round((full.width * bucket) / longest));
+    const height = Math.max(1, Math.round((full.height * bucket) / longest));
+    const small = await createImageBitmap(full, { resizeWidth: width, resizeHeight: height, resizeQuality: "high" });
+    try {
+      if (typeof OffscreenCanvas === "function") {
+        const canvas = new OffscreenCanvas(width, height);
+        canvas.getContext("2d")?.drawImage(small, 0, 0);
+        return await canvas.convertToBlob({ type: "image/webp", quality: 0.85 });
+      }
+      const canvas = document.createElement("canvas");
+      canvas.width = width;
+      canvas.height = height;
+      canvas.getContext("2d")?.drawImage(small, 0, 0);
+      return await new Promise<Blob | null>((resolve) => canvas.toBlob(resolve, "image/webp", 0.85));
+    } finally {
+      small.close();
+    }
+  } finally {
+    full.close();
+  }
+}
+
+let shared: ImageThumbs | null = null;
+function sharedThumbs(): ImageThumbs {
+  shared ??= createImageThumbs();
+  return shared;
+}
+
+/** For the suite: forget every picture and start a fresh cache. */
+export function resetImageThumbs(next?: ImageThumbs): void {
+  shared?.dispose();
+  shared = next ?? null;
+}
+
+/**
+ * The picture to show for an image of content `hash` at `url`, in a box whose
+ * longest side is `maxPx` CSS px (scaled by the device pixel ratio here). The
+ * original where there is no thumbnail to make, null while one is drawn.
+ */
+export function useImageThumb(url: string, hash: string, maxPx: number): ImageThumb {
+  const [dpr] = useState(() => (typeof window === "undefined" ? 1 : window.devicePixelRatio || 1));
+  const thumbs = sharedThumbs();
+  const px = Math.ceil(maxPx * dpr);
+  // `thumb` queues the draw on its first ask and answers the same value until
+  // the draw lands and notifies, which is what a snapshot must do.
+  return useSyncExternalStore(thumbs.subscribe, () => thumbs.thumb(url, hash, px));
+}