@hienlh/ppm 0.17.34 → 0.17.37

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-draft.ts

@@ -11,6 +11,13 @@ interface DraftState {
   attachments: DraftAttachment[];
 }
 
+/**
+ * How long the chat composer may stay hidden waiting for a draft. The composer
+ * is gated on `draftLoading`, so a slow or stalled load must not leave the user
+ * with no way to type.
+ */
+const GATE_RELEASE_MS = 3_000;
+
 interface DraftResult {
   content: string;
   attachments: string; // JSON string
@@ -34,6 +41,11 @@ export function useDraft(projectName: string, sessionId: string | null) {
     }
     let cancelled = false;
     setLoading(true);
+    // Releasing the gate only reveals the composer; a draft arriving afterwards
+    // is still applied, and MessageInput refuses to overwrite typed text.
+    const releaseTimer = setTimeout(() => {
+      if (!cancelled) setLoading(false);
+    }, GATE_RELEASE_MS);
     api
       .get<DraftResult | null>(
         `${projectUrl(projectName)}/chat/drafts/${encodeURIComponent(effectiveId)}`,
@@ -49,8 +61,11 @@ export function useDraft(projectName: string, sessionId: string | null) {
         }
       })
       .catch(() => { if (!cancelled) setDraft(null); })
-      .finally(() => { if (!cancelled) setLoading(false); });
-    return () => { cancelled = true; };
+      .finally(() => {
+        clearTimeout(releaseTimer);
+        if (!cancelled) setLoading(false);
+      });
+    return () => { cancelled = true; clearTimeout(releaseTimer); };
   }, [projectName, effectiveId]);
 
   // Debounced save (1s)

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/api-client.ts

@@ -16,11 +16,30 @@ function warnOnAuditFailure(res: Response): void {
 /** GETs currently awaiting a response, keyed by absolute URL. See ApiClient.get. */
 const pendingGets = new Map<string, Promise<unknown>>();
 
-class ApiClient {
+/**
+ * How long a GET may wait for response headers. Browsers do not time a stalled
+ * fetch out on their own, and a request that never settles keeps its
+ * `pendingGets` slot forever — every later caller of that URL then inherits the
+ * stall, and UI gated on the response stays hidden until a page reload.
+ *
+ * The clock stops once headers arrive, so transcripts, file reads and other
+ * large bodies may still take as long as the connection needs. Generous enough
+ * for endpoints that spawn a CLI or hit a registry before answering.
+ */
+const RESPONSE_TIMEOUT_MS = 30_000;
+
+/** `reason` is only guaranteed on newer engines; never propagate `undefined`. */
+function abortReason(signal: AbortSignal): unknown {
+  return signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+
+export class ApiClient {
   private baseUrl: string;
+  private responseTimeoutMs: number;
 
-  constructor(baseUrl = "") {
+  constructor(baseUrl = "", responseTimeoutMs = RESPONSE_TIMEOUT_MS) {
     this.baseUrl = baseUrl;
+    this.responseTimeoutMs = responseTimeoutMs;
   }
 
   private getToken(): string | null {
@@ -61,11 +80,35 @@ class ApiClient {
   }
 
   private async rawGet<T>(path: string, signal?: AbortSignal): Promise<T> {
-    const res = await fetch(`${this.baseUrl}${path}`, {
-      headers: this.headers(),
-      signal,
-    });
-    return this.handleResponse<T>(res);
+    if (signal?.aborted) throw abortReason(signal);
+
+    const controller = new AbortController();
+    const timer = setTimeout(
+      () =>
+        controller.abort(
+          new DOMException(
+            `No response after ${this.responseTimeoutMs}ms: ${path}`,
+            "TimeoutError",
+          ),
+        ),
+      this.responseTimeoutMs,
+    );
+    const forwardAbort = () => controller.abort(abortReason(signal!));
+    signal?.addEventListener("abort", forwardAbort, { once: true });
+
+    try {
+      const res = await fetch(`${this.baseUrl}${path}`, {
+        headers: this.headers(),
+        signal: controller.signal,
+      });
+      // Headers are in, so the connection answered — stop the clock before
+      // reading the body, which may legitimately be large and slow.
+      clearTimeout(timer);
+      return await this.handleResponse<T>(res);
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", forwardAbort);
+    }
   }
 
   async post<T>(path: string, body?: unknown): Promise<T> {