@hienlh/ppm 0.17.34 → 0.17.36

package/src/web/components/shared/image-overlay.tsx

@@ -1,45 +1,209 @@
-import { useEffect, useCallback } from "react";
-import { X } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import {
+  Check, ChevronLeft, ChevronRight, Copy, Download, FlipHorizontal, FlipVertical,
+  Maximize2, Minus, Plus, RotateCcw, RotateCw, Scan, X,
+} from "lucide-react";
 import { useImageOverlay } from "@/stores/image-overlay-store";
+import { useImageTransform } from "@/hooks/use-image-transform";
+import { canCopyImage, copyImageToClipboard } from "@/lib/clipboard";
+import { triggerDownload } from "@/lib/file-download";
+import { cn } from "@/lib/utils";
 
-/** Global image lightbox overlay — mount once in app root */
+/**
+ * Global image lightbox with zoom, pan, rotate and flip — mount once in app root.
+ *
+ * The viewer is a separate component so its gesture bindings attach on the same commit that
+ * puts the container in the DOM. Running them from here would bind against a ref that is
+ * still null while the overlay is closed, and they would never attach at all.
+ */
 export function ImageOverlay() {
-  const { src, alt, close } = useImageOverlay();
+  const src = useImageOverlay((s) => s.src);
+  if (!src) return null;
+  return <Viewer key={src} />;
+}
 
-  const handleKeyDown = useCallback(
-    (e: KeyboardEvent) => {
-      if (e.key === "Escape") close();
-    },
-    [close],
-  );
+function Viewer() {
+  const { src, alt, images, index, close, go } = useImageOverlay();
+  const {
+    containerRef, imageRef, zoomPercent, rotation,
+    zoomBy, reset, fit, actualSize, rotate, flip,
+  } = useImageTransform();
+
+  const [copied, setCopied] = useState(false);
+  const copyable = canCopyImage();
+
+  // Give the image an explicit identity transform up front, so the first gesture animates
+  // from a known state rather than from an empty style. Remounting per image (see the `key`
+  // above) is what keeps a 400% zoom from carrying over to the next one.
+  useEffect(() => { reset(); }, [reset]);
+
+  const actions = useRef({ close, go, zoomBy, reset, fit, actualSize, rotate, flip });
+  actions.current = { close, go, zoomBy, reset, fit, actualSize, rotate, flip };
 
   useEffect(() => {
     if (!src) return;
-    document.addEventListener("keydown", handleKeyDown);
-    return () => document.removeEventListener("keydown", handleKeyDown);
-  }, [src, handleKeyDown]);
+    const onKey = (e: KeyboardEvent) => {
+      const a = actions.current;
+      const key = e.key;
+      if (key === "Escape") return a.close();
+      if (key === "ArrowLeft") return a.go(-1);
+      if (key === "ArrowRight") return a.go(1);
+      if (key === "+" || key === "=") return a.zoomBy(1.25);
+      if (key === "-" || key === "_") return a.zoomBy(0.8);
+      if (key === "0") return a.fit();
+      if (key === "1") return a.actualSize();
+      if (key === "r") return a.rotate(90);
+      if (key === "R") return a.rotate(-90);
+      if (key === "h") return a.flip("x");
+      if (key === "v") return a.flip("y");
+    };
+    document.addEventListener("keydown", onKey);
+    return () => document.removeEventListener("keydown", onKey);
+  }, [src]);
 
   if (!src) return null;
 
+  const name = alt?.trim() || "image";
+  const many = images.length > 1;
+
+  const copy = async () => {
+    if (await copyImageToClipboard(src)) {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    }
+  };
+
   return (
-    <div
-      className="fixed inset-0 z-[100] flex items-center justify-center bg-black/80 backdrop-blur-sm animate-in fade-in duration-150"
-      onClick={close}
-    >
+    <div className="fixed inset-0 z-[100] flex flex-col bg-black/90 backdrop-blur-sm animate-in fade-in duration-150">
       <button
         onClick={close}
-        className="absolute top-4 right-4 z-10 flex items-center justify-center size-8 rounded-full bg-white/10 hover:bg-white/20 text-white transition-colors"
+        className="absolute top-3 right-3 z-20 flex size-11 items-center justify-center rounded-full bg-white/10 text-white transition-colors hover:bg-white/20 active:bg-white/30"
         aria-label="Close"
       >
         <X className="size-5" />
       </button>
 
-      <img
-        src={src}
-        alt={alt}
-        className="max-w-[90vw] max-h-[90vh] object-contain rounded-lg shadow-2xl"
-        onClick={(e) => e.stopPropagation()}
-      />
+      {many && (
+        <div className="absolute top-3 left-3 z-20 rounded-full bg-white/10 px-3 py-1.5 font-mono text-xs text-white/80">
+          {index + 1} / {images.length}
+        </div>
+      )}
+
+      {/*
+        touch-none hands every finger to the gesture handler; without it the browser claims
+        the drag for its own scroll and pinch, and neither pan nor zoom ever fires.
+      */}
+      <div
+        ref={containerRef}
+        className="relative flex flex-1 touch-none select-none items-center justify-center overflow-hidden"
+        onPointerDown={(e) => { if (e.target === e.currentTarget) e.currentTarget.dataset.bg = "1"; }}
+        onPointerUp={(e) => {
+          // Close only on a click that started and ended on the backdrop, so releasing a
+          // pan outside the image does not dismiss the viewer.
+          if (e.target === e.currentTarget && e.currentTarget.dataset.bg === "1") close();
+          delete e.currentTarget.dataset.bg;
+        }}
+      >
+        <img
+          ref={imageRef}
+          src={src}
+          alt={alt}
+          draggable={false}
+          style={{ willChange: "transform" }}
+          className="max-h-full max-w-full object-contain rounded-lg shadow-2xl"
+        />
+      </div>
+
+      <Toolbar>
+        {many && (
+          <>
+            <ToolButton onClick={() => go(-1)} disabled={index === 0} label="Previous image (←)">
+              <ChevronLeft className="size-5" />
+            </ToolButton>
+            <ToolButton onClick={() => go(1)} disabled={index === images.length - 1} label="Next image (→)">
+              <ChevronRight className="size-5" />
+            </ToolButton>
+            <Divider />
+          </>
+        )}
+
+        <ToolButton onClick={() => zoomBy(0.8)} label="Zoom out (-)"><Minus className="size-5" /></ToolButton>
+        <button
+          onClick={reset}
+          className="h-11 min-w-[4.5rem] rounded-lg px-2 font-mono text-xs text-white/80 transition-colors hover:bg-white/10 active:bg-white/20"
+          title="Reset view"
+        >
+          {zoomPercent}%
+        </button>
+        <ToolButton onClick={() => zoomBy(1.25)} label="Zoom in (+)"><Plus className="size-5" /></ToolButton>
+        <ToolButton onClick={fit} label="Fit to screen (0)"><Maximize2 className="size-5" /></ToolButton>
+        <ToolButton onClick={actualSize} label="Actual size (1)"><Scan className="size-5" /></ToolButton>
+
+        <Divider />
+
+        <ToolButton onClick={() => rotate(-90)} label="Rotate left (Shift+R)" active={rotation !== 0}>
+          <RotateCcw className="size-5" />
+        </ToolButton>
+        <ToolButton onClick={() => rotate(90)} label="Rotate right (R)" active={rotation !== 0}>
+          <RotateCw className="size-5" />
+        </ToolButton>
+        <ToolButton onClick={() => flip("x")} label="Flip horizontally (H)"><FlipHorizontal className="size-5" /></ToolButton>
+        <ToolButton onClick={() => flip("y")} label="Flip vertically (V)"><FlipVertical className="size-5" /></ToolButton>
+
+        <Divider />
+
+        <ToolButton onClick={() => triggerDownload(src, name)} label="Download"><Download className="size-5" /></ToolButton>
+        <ToolButton
+          onClick={copy}
+          disabled={!copyable}
+          label={copyable ? "Copy image" : "Copying images needs an HTTPS or localhost address"}
+        >
+          {copied ? <Check className="size-5 text-green-400" /> : <Copy className="size-5" />}
+        </ToolButton>
+      </Toolbar>
+    </div>
+  );
+}
+
+/** Bottom placement keeps the controls in thumb reach on a phone (design-guidelines §9). */
+function Toolbar({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="flex shrink-0 justify-center px-2 pb-[max(0.75rem,env(safe-area-inset-bottom))] pt-2">
+      <div className="flex flex-wrap items-center justify-center gap-0.5 rounded-2xl bg-white/10 p-1 backdrop-blur">
+        {children}
+      </div>
     </div>
   );
 }
+
+function Divider() {
+  return <span className="mx-1 h-6 w-px bg-white/20" aria-hidden />;
+}
+
+function ToolButton({
+  onClick, label, children, disabled, active,
+}: {
+  onClick: () => void;
+  label: string;
+  children: React.ReactNode;
+  disabled?: boolean;
+  active?: boolean;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      title={label}
+      aria-label={label}
+      className={cn(
+        "flex size-11 items-center justify-center rounded-lg text-white transition-colors",
+        "hover:bg-white/15 active:bg-white/25",
+        active && "text-primary",
+        disabled && "pointer-events-none opacity-30",
+      )}
+    >
+      {children}
+    </button>
+  );
+}

package/src/web/components/shared/markdown-context.ts

@@ -14,7 +14,7 @@ export interface MdContextValue {
   /** True while the message is still streaming — defer async Shiki highlight until done. */
   isStreaming: boolean;
   openFileOrSearch: (path: string, line?: { start: number; end?: number }) => void;
-  openImageOverlay: (url: string, alt: string) => void;
+  openImageOverlay: (url: string, alt: string, gallery?: { src: string; alt: string }[]) => void;
   openDiagramOverlay: (svg: string) => void;
 }
 

package/src/web/components/shared/markdown-renderer.tsx

@@ -8,6 +8,7 @@ import rehypeKatex from "rehype-katex";
 import { useTabStore } from "@/stores/tab-store";
 import { useFileStore, type FileNode } from "@/stores/file-store";
 import { useImageOverlay } from "@/stores/image-overlay-store";
+import { collectGallery, GALLERY_ITEM_ATTR } from "@/lib/image-gallery";
 import { useDiagramOverlay } from "@/stores/diagram-overlay-store";
 import { openCommandPalette } from "@/hooks/use-global-keybindings";
 import { useBackgroundOutputStore } from "@/stores/background-output-store";
@@ -162,7 +163,8 @@ function MdImage({ src, alt, node, ...props }: any) {
     <img
       src={displaySrc}
       alt={name}
-      onClick={() => displaySrc && openImageOverlay(displaySrc, name)}
+      {...{ [GALLERY_ITEM_ATTR]: "" }}
+      onClick={(e) => displaySrc && openImageOverlay(displaySrc, name, collectGallery(e.currentTarget))}
       className="max-h-[400px] max-w-full object-contain rounded-md border border-border cursor-pointer"
       style={{ opacity: loading ? 0.3 : 1, minHeight: loading ? 48 : undefined, minWidth: loading ? 48 : undefined }}
       {...props}

package/src/web/hooks/use-image-transform.ts

@@ -0,0 +1,276 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useGesture } from "@use-gesture/react";
+
+/**
+ * Pan / zoom / rotate / flip state for a single image inside a fixed container.
+ *
+ * The transform is written straight to the element's style on every gesture frame and only
+ * mirrored into React state for the zoom readout. Re-rendering a component tree per
+ * pointermove is what makes a viewer feel heavy, and none of the surrounding UI depends on
+ * the intermediate values.
+ *
+ * `scale` is relative to the image's laid-out size, not its pixels: the `<img>` is already
+ * CSS-fitted to the container, so scale 1 means "fits" and the fit never has to be measured
+ * for the unrotated case.
+ */
+
+export interface ImageTransform {
+  scale: number;
+  x: number;
+  y: number;
+  /** Multiples of 90 degrees, always normalised to 0/90/180/270. */
+  rotation: number;
+  flipX: boolean;
+  flipY: boolean;
+}
+
+const IDENTITY: ImageTransform = { scale: 1, x: 0, y: 0, rotation: 0, flipX: false, flipY: false };
+
+const MIN_SCALE = 0.1;
+const MAX_SCALE = 20;
+/** Scale applied when double-clicking an image that is currently at fit. */
+const DOUBLE_CLICK_SCALE = 2.5;
+
+const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));
+
+/**
+ * Whether a wheel event looks like a real mouse wheel rather than a trackpad.
+ *
+ * Trackpads emit a dense stream of small, often fractional deltas and frequently move on both
+ * axes; a wheel emits sparse whole-number notches on one axis. The guess only decides whether
+ * a bare wheel zooms or pans — Ctrl/Cmd+wheel, the toolbar and the keyboard always zoom, so a
+ * wrong guess is an annoyance rather than a dead end.
+ */
+function looksLikeMouseWheel(e: WheelEvent): boolean {
+  if (e.deltaMode !== 0) return true; // line/page deltas only ever come from a wheel
+  if (e.deltaX !== 0) return false;
+  return Number.isInteger(e.deltaY) && Math.abs(e.deltaY) >= 40;
+}
+
+export interface UseImageTransformResult {
+  containerRef: React.RefObject<HTMLDivElement | null>;
+  imageRef: React.RefObject<HTMLImageElement | null>;
+  /** Current zoom as a percentage of the fitted size, for display only. */
+  zoomPercent: number;
+  rotation: number;
+  zoomBy: (factor: number) => void;
+  reset: () => void;
+  fit: () => void;
+  actualSize: () => void;
+  rotate: (deltaDegrees: number) => void;
+  flip: (axis: "x" | "y") => void;
+}
+
+export function useImageTransform(): UseImageTransformResult {
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const imageRef = useRef<HTMLImageElement | null>(null);
+  const t = useRef<ImageTransform>({ ...IDENTITY });
+  const frame = useRef<number | null>(null);
+
+  const [zoomPercent, setZoomPercent] = useState(100);
+  const [rotation, setRotation] = useState(0);
+
+  /** Laid-out size of the image — unaffected by transforms, so it is the stable reference. */
+  const layout = useCallback(() => {
+    const img = imageRef.current;
+    const box = containerRef.current;
+    return {
+      dw: img?.clientWidth ?? 0,
+      dh: img?.clientHeight ?? 0,
+      cw: box?.clientWidth ?? 0,
+      ch: box?.clientHeight ?? 0,
+      natural: img?.naturalWidth ?? 0,
+    };
+  }, []);
+
+  /** How far the image may travel before its edge crosses the container's. */
+  const panLimits = useCallback(() => {
+    const { dw, dh, cw, ch } = layout();
+    const quarterTurned = Math.abs(t.current.rotation % 180) === 90;
+    const w = (quarterTurned ? dh : dw) * t.current.scale;
+    const h = (quarterTurned ? dw : dh) * t.current.scale;
+    return { maxX: Math.max(0, (w - cw) / 2), maxY: Math.max(0, (h - ch) / 2) };
+  }, [layout]);
+
+  const commit = useCallback(() => {
+    setZoomPercent(Math.round(t.current.scale * 100));
+    setRotation(t.current.rotation);
+  }, []);
+
+  /**
+   * Write the transform, and publish the readout.
+   *
+   * Mid-gesture the readout is throttled to one frame, since it is cosmetic and re-rendering
+   * per pointermove is what makes a viewer feel heavy. At rest it must be published outright:
+   * a frame callback only runs if the browser goes on to paint, so a gesture that ends the
+   * moment the finger lifts would otherwise leave the number showing the previous value.
+   */
+  const apply = useCallback((immediate = false) => {
+    const el = imageRef.current;
+    if (!el) return;
+    const { scale, x, y, rotation: r, flipX, flipY } = t.current;
+    el.style.transform =
+      `translate3d(${x}px, ${y}px, 0) rotate(${r}deg) ` +
+      `scale(${scale * (flipX ? -1 : 1)}, ${scale * (flipY ? -1 : 1)})`;
+
+    if (immediate) {
+      if (frame.current != null) {
+        cancelAnimationFrame(frame.current);
+        frame.current = null;
+      }
+      commit();
+      return;
+    }
+    if (frame.current == null) {
+      frame.current = requestAnimationFrame(() => {
+        frame.current = null;
+        commit();
+      });
+    }
+  }, [commit]);
+
+  /** Clamp the pan back inside the limits — used after any scale or rotation change. */
+  const settle = useCallback((immediate = false) => {
+    const { maxX, maxY } = panLimits();
+    t.current.x = clamp(t.current.x, -maxX, maxX);
+    t.current.y = clamp(t.current.y, -maxY, maxY);
+    apply(immediate);
+  }, [apply, panLimits]);
+
+  /**
+   * Zoom while holding one point of the image still.
+   *
+   * `originX/Y` are client coordinates; without this correction the image slides away from
+   * whatever the user was pointing at, which is the single most noticeable flaw in a viewer.
+   */
+  const zoomAt = useCallback((nextScale: number, originX?: number, originY?: number, immediate = false) => {
+    const box = containerRef.current;
+    if (!box) return;
+    const rect = box.getBoundingClientRect();
+    const cx = (originX ?? rect.left + rect.width / 2) - (rect.left + rect.width / 2);
+    const cy = (originY ?? rect.top + rect.height / 2) - (rect.top + rect.height / 2);
+
+    const prev = t.current.scale;
+    const scale = clamp(nextScale, MIN_SCALE, MAX_SCALE);
+    const ratio = scale / prev;
+    t.current.scale = scale;
+    t.current.x = cx - (cx - t.current.x) * ratio;
+    t.current.y = cy - (cy - t.current.y) * ratio;
+    settle(immediate);
+  }, [settle]);
+
+  const reset = useCallback(() => {
+    t.current = { ...IDENTITY };
+    apply(true);
+  }, [apply]);
+
+  /**
+   * Scale the image so its rotated bounding box fits the container.
+   *
+   * At 0 and 180 degrees CSS has already fitted it, so the answer is 1. At a quarter turn the
+   * width and height swap and the fitted box no longer fits.
+   */
+  const fit = useCallback(() => {
+    const { dw, dh, cw, ch } = layout();
+    const quarterTurned = Math.abs(t.current.rotation % 180) === 90;
+    t.current.scale = quarterTurned && dw > 0 && dh > 0 ? Math.min(cw / dh, ch / dw) : 1;
+    t.current.x = 0;
+    t.current.y = 0;
+    settle(true);
+  }, [layout, settle]);
+
+  /** One image pixel per CSS pixel. */
+  const actualSize = useCallback(() => {
+    const { dw, natural } = layout();
+    if (dw > 0 && natural > 0) zoomAt(natural / dw, undefined, undefined, true);
+  }, [layout, zoomAt]);
+
+  const rotate = useCallback((delta: number) => {
+    t.current.rotation = ((t.current.rotation + delta) % 360 + 360) % 360;
+    // A quarter turn changes which dimension is constrained, so an untouched view would
+    // otherwise overflow. Re-fitting keeps the whole image visible, which is the reason
+    // someone rotates in the first place.
+    fit();
+  }, [fit]);
+
+  const flip = useCallback((axis: "x" | "y") => {
+    if (axis === "x") t.current.flipX = !t.current.flipX;
+    else t.current.flipY = !t.current.flipY;
+    apply(true);
+  }, [apply]);
+
+  const zoomBy = useCallback(
+    (factor: number) => zoomAt(t.current.scale * factor, undefined, undefined, true),
+    [zoomAt],
+  );
+
+  // Bound to the container element itself rather than returning props to spread: only a
+  // natively attached, non-passive listener may call preventDefault on wheel, and React's
+  // synthetic wheel handler is always passive.
+  useGesture(
+    {
+      onDrag: ({ delta: [dx, dy], pinching, cancel, last }) => {
+        if (pinching) return cancel();
+        t.current.x += dx;
+        t.current.y += dy;
+        settle(last);
+      },
+      onPinch: ({ offset: [s], origin: [ox, oy], first, last, memo }) => {
+        // `offset` is cumulative from the gesture's start, so anchor it to the scale we had.
+        const base = first ? t.current.scale / (s || 1) : memo ?? 1;
+        zoomAt(base * s, ox, oy, last);
+        return base;
+      },
+      onWheel: ({ event, last }) => {
+        // A wheel gesture closes with a trailing frame that carries the previous event
+        // object, deltas and all. Acting on it would apply every notch twice — but it is the
+        // right moment to publish the readout, since no further frame is guaranteed.
+        if (last) {
+          apply(true);
+          return;
+        }
+        // Read the deltas off the event rather than the gesture state, which accumulates.
+        const { deltaX, deltaY } = event;
+        if (deltaX === 0 && deltaY === 0) return;
+        event.preventDefault();
+
+        // A trackpad pinch reaches the page as Ctrl+wheel — the browser exposes no separate
+        // pinch event outside of Safari, and @use-gesture's pinch recogniser does not claim
+        // it here, so this is the only place it can be handled.
+        if (event.ctrlKey || event.metaKey || looksLikeMouseWheel(event)) {
+          // Exponential so every notch scales by the same proportion, and so a trackpad's
+          // stream of small fractional deltas reads as one continuous zoom.
+          zoomAt(t.current.scale * Math.exp(-deltaY / 300), event.clientX, event.clientY);
+          return;
+        }
+
+        t.current.x -= deltaX;
+        t.current.y -= deltaY;
+        settle();
+      },
+      onDoubleClick: ({ event }) => {
+        if (t.current.scale > 1.05) fit();
+        else zoomAt(DOUBLE_CLICK_SCALE, event.clientX, event.clientY, true);
+      },
+    },
+    {
+      target: containerRef,
+      drag: { from: () => [t.current.x, t.current.y], filterTaps: true, pointer: { touch: true } },
+      pinch: { scaleBounds: { min: MIN_SCALE, max: MAX_SCALE }, rubberband: true },
+      eventOptions: { passive: false },
+    },
+  );
+
+  // A resized window changes what "fits", and a stale pan clamp would leave the image
+  // stranded off-centre.
+  useEffect(() => {
+    const onResize = () => settle();
+    window.addEventListener("resize", onResize);
+    return () => {
+      window.removeEventListener("resize", onResize);
+      if (frame.current != null) cancelAnimationFrame(frame.current);
+    };
+  }, [settle]);
+
+  return { containerRef, imageRef, zoomPercent, rotation, zoomBy, reset, fit, actualSize, rotate, flip };
+}

package/src/web/lib/clipboard.ts

@@ -20,6 +20,47 @@ export async function copyToClipboard(text: string): Promise<boolean> {
   return legacyCopy(text);
 }
 
+/**
+ * Whether an image can be placed on the clipboard at all on this origin.
+ *
+ * Unlike text there is no `execCommand` fallback for binary data, so on the plain-HTTP
+ * origins PPM is often reached from there is nothing to try — callers should disable the
+ * action and say why rather than offer a button that always fails.
+ */
+export function canCopyImage(): boolean {
+  return typeof ClipboardItem !== "undefined" && !!navigator.clipboard?.write;
+}
+
+/**
+ * Copy an image to the clipboard, converting to PNG first.
+ *
+ * Browsers accept a very short list of image types on the clipboard — PNG is the only one
+ * supported everywhere — so a JPEG or WebP has to be repainted through a canvas.
+ */
+export async function copyImageToClipboard(src: string): Promise<boolean> {
+  if (!canCopyImage()) return false;
+  try {
+    const blob = await fetch(src).then((r) => r.blob());
+    const png = blob.type === "image/png" ? blob : await toPng(blob);
+    await navigator.clipboard.write([new ClipboardItem({ "image/png": png })]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function toPng(blob: Blob): Promise<Blob> {
+  const bitmap = await createImageBitmap(blob);
+  const canvas = document.createElement("canvas");
+  canvas.width = bitmap.width;
+  canvas.height = bitmap.height;
+  canvas.getContext("2d")?.drawImage(bitmap, 0, 0);
+  bitmap.close();
+  return new Promise((resolve, reject) => {
+    canvas.toBlob((b) => (b ? resolve(b) : reject(new Error("canvas produced no blob"))), "image/png");
+  });
+}
+
 function legacyCopy(text: string): boolean {
   const textarea = document.createElement("textarea");
   textarea.value = text;

package/src/web/lib/file-download.ts

@@ -24,7 +24,7 @@ export async function downloadFolder(projectName: string, folderPath: string): P
 }
 
 /** Hidden <a> tag download trigger — avoids popup blockers */
-function triggerDownload(url: string, filename: string): void {
+export function triggerDownload(url: string, filename: string): void {
   const a = document.createElement("a");
   a.href = url;
   a.download = filename;

package/src/web/lib/image-gallery.ts

@@ -0,0 +1,25 @@
+import type { GalleryImage } from "@/stores/image-overlay-store";
+
+/** Marks a container whose tagged images form one navigable set. */
+export const GALLERY_ROOT_ATTR = "data-image-gallery";
+/** Marks an `<img>` that belongs to the enclosing gallery. */
+export const GALLERY_ITEM_ATTR = "data-gallery-item";
+
+/**
+ * Collect the images a viewer may move between, in the order they appear on screen.
+ *
+ * Read from the DOM rather than a registry because every image already owns a blob URL that
+ * is revoked when its component unmounts — so the mounted elements are exactly the set whose
+ * sources are still valid, and the DOM already holds them in the order the user sees.
+ *
+ * The reach is therefore whatever is mounted. The chat transcript is deliberately not
+ * virtualised (`message-list.tsx`), so that is the whole conversation today; if it ever gains
+ * data windowing, navigation narrows to the loaded window along with everything else.
+ */
+export function collectGallery(from: Element | null): GalleryImage[] {
+  const root = from?.closest(`[${GALLERY_ROOT_ATTR}]`);
+  if (!root) return [];
+  return [...root.querySelectorAll<HTMLImageElement>(`img[${GALLERY_ITEM_ATTR}]`)]
+    .filter((img) => !!img.src)
+    .map((img) => ({ src: img.src, alt: img.alt }));
+}

package/src/web/stores/image-overlay-store.ts

@@ -1,18 +1,46 @@
 import { create } from "zustand";
 
+export interface GalleryImage {
+  /** Blob URL or data URL of the image. */
+  src: string;
+  alt: string;
+}
+
 interface ImageOverlayState {
-  /** Blob URL or data URL of the image to display */
+  /** Images the overlay can move between; a single entry when opened without a gallery. */
+  images: GalleryImage[];
+  index: number;
+  /** Convenience mirrors of the current entry — every existing consumer reads these. */
   src: string | null;
   alt: string;
-  /** Open the overlay with a given image source */
-  open: (src: string, alt?: string) => void;
-  /** Close the overlay */
+  /**
+   * Open the overlay. Passing a gallery lets the arrows walk its siblings; the clicked
+   * source decides where in that list the viewer starts.
+   */
+  open: (src: string, alt?: string, gallery?: GalleryImage[]) => void;
   close: () => void;
+  /** Move by a signed offset, stopping at the ends rather than wrapping. */
+  go: (delta: number) => void;
 }
 
-export const useImageOverlay = create<ImageOverlayState>((set) => ({
+export const useImageOverlay = create<ImageOverlayState>((set, get) => ({
+  images: [],
+  index: 0,
   src: null,
   alt: "",
-  open: (src, alt = "") => set({ src, alt }),
-  close: () => set({ src: null, alt: "" }),
+  open: (src, alt = "", gallery) => {
+    const images = gallery?.length ? gallery : [{ src, alt }];
+    const found = images.findIndex((i) => i.src === src);
+    const index = found >= 0 ? found : 0;
+    const current = images[index]!;
+    set({ images, index, src: current.src, alt: current.alt || alt });
+  },
+  close: () => set({ images: [], index: 0, src: null, alt: "" }),
+  go: (delta) => {
+    const { images, index } = get();
+    const next = index + delta;
+    if (next < 0 || next >= images.length) return;
+    const current = images[next]!;
+    set({ index: next, src: current.src, alt: current.alt });
+  },
 }));