@plannotator/ui 0.52.1 → 0.53.1

package/components/ImageLightbox.tsx

@@ -1,4 +1,57 @@
-import React, { useEffect, useRef } from 'react';
+import React, { useEffect, useMemo, useRef, useState } from 'react';
+import { ImagePeek, type ImagePeekHandle, type ImagePeekRow } from './ImagePeek';
+
+/** One image of a document, for the lightbox's stepping (`images`). */
+export interface LightboxImage {
+  src: string;
+  alt: string;
+  /** The heading the image sits under ("Options"), for "2 of 4 · in “Options”" and the peek's rows. */
+  section?: string | null;
+}
+
+/**
+ * The file name an image's src names: the `path` a host route carries
+ * (`/api/image?path=…`), else the URL's last segment, else the alt text.
+ */
+export function lightboxImageName(image: Pick<LightboxImage, 'src' | 'alt'>): string {
+  try {
+    const base = typeof window !== 'undefined' && /^https?:/.test(window.location.href) ? window.location.href : 'http://localhost/';
+    const url = new URL(image.src, base);
+    const named = url.searchParams.get('path') ?? (url.protocol === 'data:' || url.protocol === 'blob:' ? '' : url.pathname);
+    const last = named.split(/[\\/]/).filter(Boolean).pop();
+    if (last) return decodeURIComponent(last);
+  } catch {
+    // Not a URL: fall back to the alt text.
+  }
+  return image.alt || 'Image';
+}
+
+/**
+ * Every image a rendered document shows, in document order, each with the
+ * heading it sits under: what the lightbox steps through (plan review and
+ * annotate's light version of the Inbox's one viewer, approval
+ * "inbox-image-viewer"). Only images that open the lightbox count
+ * (`.cursor-zoom-in`).
+ */
+export function collectDocumentImages(container: ParentNode | null): LightboxImage[] {
+  if (!container) return [];
+  const out: LightboxImage[] = [];
+  let section: string | null = null;
+  for (const el of container.querySelectorAll<HTMLElement>('h1, h2, h3, h4, h5, h6, img')) {
+    if (el.tagName !== 'IMG') {
+      section = (el.textContent ?? '').trim() || section;
+      continue;
+    }
+    const img = el as HTMLImageElement;
+    if (!img.classList.contains('cursor-zoom-in')) continue;
+    const src = img.getAttribute('src');
+    if (!src || out.some((i) => i.src === src)) continue;
+    out.push({ src, alt: img.getAttribute('alt') ?? '', section });
+  }
+  return out;
+}
+
+const ICON = { width: 16, height: 16, viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 1.8, strokeLinecap: 'round' as const, strokeLinejoin: 'round' as const, 'aria-hidden': true };
 
 /**
  * Overlay for viewing one image enlarged. Shared by the markdown Viewer
@@ -15,24 +68,96 @@ import React, { useEffect, useRef } from 'react';
  * overlay when it opens, which also pulls focus out of an HTML page's iframe
  * (whose keys the parent would otherwise never see), and goes back to where
  * it was when it closes.
+ *
+ * With `images` (two or more) it is the light version of the Inbox's one
+ * viewer: full screen, `2 of 4 · in “Options”`, ← → (and `]` `[`) through the
+ * document's images, stopping at the ends, Actual size, and the same peek
+ * from the pill under the image. No pen, no comments: there the person
+ * annotates the document itself. Without `images` it is exactly the single
+ * image overlay it always was.
  */
-export const ImageLightbox: React.FC<{ src: string; alt: string; onClose: () => void }> = ({ src, alt, onClose }) => {
+export const ImageLightbox: React.FC<{
+  src: string;
+  alt: string;
+  onClose: () => void;
+  /** The document's images in order; with two or more the lightbox steps through them. Additive: absent keeps the single image overlay. */
+  images?: readonly LightboxImage[];
+}> = ({ src, alt, onClose, images }) => {
   const overlayRef = useRef<HTMLDivElement>(null);
   const onCloseRef = useRef(onClose);
   onCloseRef.current = onClose;
+  const stepping = !!images && images.length > 1;
+  const [index, setIndex] = useState(() => Math.max(0, images?.findIndex((i) => i.src === src) ?? 0));
+  const [fit, setFit] = useState<'fit' | 'actual'>('fit');
+  const [peekOpen, setPeekOpen] = useState(false);
+  const [endNote, setEndNote] = useState<string | null>(null);
+  const [announced, setAnnounced] = useState('');
+  const peekRef = useRef<ImagePeekHandle>(null);
+  const pillRef = useRef<HTMLButtonElement>(null);
+  const endTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const current = stepping ? images![index]! : { src, alt, section: null };
+  const name = lightboxImageName(current);
+
+  const step = (dir: 1 | -1) => {
+    if (!stepping) return;
+    const next = index + dir;
+    if (next < 0 || next >= images!.length) {
+      const note = dir > 0 ? 'Last image in this document' : 'First image in this document';
+      setEndNote(note);
+      setAnnounced(note);
+      if (endTimer.current) clearTimeout(endTimer.current);
+      endTimer.current = setTimeout(() => setEndNote(null), 1800);
+      return;
+    }
+    go(next);
+  };
+  const go = (next: number) => {
+    setIndex(next);
+    setFit('fit');
+    const image = images![next]!;
+    setAnnounced(`${next + 1} of ${images!.length}, ${lightboxImageName(image)}${image.section ? `, in “${image.section}”` : ''}`);
+  };
+  const stepRef = useRef(step);
+  stepRef.current = step;
+  const peekOpenRef = useRef(peekOpen);
+  peekOpenRef.current = peekOpen;
+
+  useEffect(() => () => {
+    if (endTimer.current) clearTimeout(endTimer.current);
+  }, []);
 
   useEffect(() => {
     const previous = document.activeElement instanceof HTMLElement ? document.activeElement : null;
     overlayRef.current?.focus({ preventScroll: true });
     const handleKeyDown = (e: KeyboardEvent) => {
-      // Tab stays native: the overlay is the only focusable thing that matters
-      // here, and trapping it buys nothing for a click-to-close surface.
+      // The peek owns the keys while it is open (it is inside this modal, so they reach it from here).
+      if (peekOpenRef.current) {
+        e.stopImmediatePropagation();
+        if (peekRef.current?.handleKey({ key: e.key, isComposing: e.isComposing })) e.preventDefault();
+        else if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) e.preventDefault();
+        return;
+      }
+      // Tab stays native: the overlay's own controls take it.
       if (e.key === 'Tab') return;
       e.stopImmediatePropagation();
       if (e.key === 'Escape' || (e.key === 'Enter' && (e.metaKey || e.ctrlKey))) {
         e.preventDefault();
       }
-      if (e.key === 'Escape') onCloseRef.current();
+      if (e.key === 'Escape') {
+        onCloseRef.current();
+        return;
+      }
+      if (e.metaKey || e.ctrlKey || e.altKey || e.isComposing) return;
+      if (e.key === 'ArrowRight' || e.key === ']') {
+        e.preventDefault();
+        stepRef.current(1);
+      } else if (e.key === 'ArrowLeft' || e.key === '[') {
+        e.preventDefault();
+        stepRef.current(-1);
+      } else if (e.key === 'ArrowDown' && e.target === pillRef.current) {
+        e.preventDefault();
+        setPeekOpen(true);
+      }
     };
     window.addEventListener('keydown', handleKeyDown, true);
     return () => {
@@ -41,26 +166,172 @@ export const ImageLightbox: React.FC<{ src: string; alt: string; onClose: () =>
     };
   }, []);
 
+  const rows = useMemo<ImagePeekRow[]>(() => {
+    if (!stepping) return [];
+    const out: ImagePeekRow[] = [];
+    images!.forEach((image, i) => {
+      const label = image.section ?? 'Document';
+      let row = out.at(-1);
+      if (!row || row.label !== label) {
+        row = { key: `row-${i}`, label, items: [] };
+        out.push(row);
+      }
+      row.items.push({ key: String(i), name: lightboxImageName(image), thumb: image.src });
+    });
+    return out;
+  }, [stepping, images]);
+
+  if (!stepping) {
+    return (
+      <div
+        ref={overlayRef}
+        tabIndex={-1}
+        role="dialog"
+        aria-modal="true"
+        aria-label={alt || 'Image'}
+        data-image-lightbox=""
+        className="fixed inset-0 z-[200] flex flex-col items-center justify-center bg-black/80 backdrop-blur-sm cursor-zoom-out outline-none"
+        onClick={onClose}
+      >
+        <img
+          src={src}
+          alt={alt}
+          className="max-w-[90vw] max-h-[85vh] object-contain rounded-lg shadow-2xl"
+          onClick={(e) => e.stopPropagation()}
+        />
+        {alt && (
+          <div className="mt-3 text-sm text-white/70 max-w-[90vw] text-center truncate">{alt}</div>
+        )}
+      </div>
+    );
+  }
+
+  const total = images!.length;
+  const first = index === 0;
+  const last = index === total - 1;
+  const circle = 'flex h-11 w-11 items-center justify-center rounded-full border border-border bg-card text-foreground shadow-sm hover:bg-muted disabled:opacity-40 aria-disabled:opacity-35';
   return (
     <div
       ref={overlayRef}
       tabIndex={-1}
       role="dialog"
       aria-modal="true"
-      aria-label={alt || 'Image'}
+      aria-label={`${name}, image ${index + 1} of ${total}`}
       data-image-lightbox=""
-      className="fixed inset-0 z-[200] flex flex-col items-center justify-center bg-black/80 backdrop-blur-sm cursor-zoom-out outline-none"
-      onClick={onClose}
+      data-image-lightbox-stepping=""
+      className="fixed inset-0 z-[200] flex flex-col bg-background text-foreground outline-none"
     >
-      <img
-        src={src}
-        alt={alt}
-        className="max-w-[90vw] max-h-[85vh] object-contain rounded-lg shadow-2xl"
-        onClick={(e) => e.stopPropagation()}
-      />
-      {alt && (
-        <div className="mt-3 text-sm text-white/70 max-w-[90vw] text-center truncate">{alt}</div>
-      )}
+      <div className="flex h-14 flex-none items-center gap-3 px-5">
+        <span className="text-[15px] font-semibold tabular-nums" data-lightbox-count="">
+          {index + 1} of {total}
+        </span>
+        {current.section && (
+          <span className="min-w-0 truncate text-[14px] text-muted-foreground" data-lightbox-section="">
+            in “{current.section}”
+          </span>
+        )}
+        <span className="flex-1" />
+        <button
+          type="button"
+          className="h-9 rounded-md border border-border bg-card px-3 text-[13.5px] hover:bg-muted"
+          onClick={() => setFit((f) => (f === 'fit' ? 'actual' : 'fit'))}
+          aria-pressed={fit === 'actual'}
+          data-lightbox-fit=""
+        >
+          {fit === 'fit' ? 'Actual size' : 'Fit'}
+        </button>
+        <button type="button" className="flex h-9 w-9 items-center justify-center rounded-md border border-border bg-card hover:bg-muted" onClick={onClose} aria-label="Close" data-lightbox-close="">
+          <svg {...ICON}>
+            <path d="M6 18 18 6M6 6l12 12" />
+          </svg>
+        </button>
+      </div>
+      <div className="relative flex min-h-0 flex-1 items-center gap-3 px-4">
+        <button type="button" className={circle} onClick={() => step(-1)} aria-label="Previous image" aria-disabled={first || undefined} data-lightbox-prev="">
+          <svg {...ICON}>
+            <path d="m15.75 19.5-7.5-7.5 7.5-7.5" />
+          </svg>
+        </button>
+        <div className={`flex min-h-0 min-w-0 flex-1 self-stretch ${fit === 'fit' ? 'items-center justify-center' : 'overflow-auto'}`} data-lightbox-stage={fit}>
+          <img
+            key={current.src}
+            src={current.src}
+            alt={current.alt}
+            draggable={false}
+            className={fit === 'fit' ? 'max-h-full max-w-full rounded-md object-contain shadow-xl' : 'max-w-none rounded-md'}
+            data-lightbox-image=""
+          />
+        </div>
+        <button type="button" className={circle} onClick={() => step(1)} aria-label="Next image" aria-disabled={last || undefined} data-lightbox-next="">
+          <svg {...ICON}>
+            <path d="m8.25 4.5 7.5 7.5-7.5 7.5" />
+          </svg>
+        </button>
+      </div>
+      <div className="flex flex-none flex-col items-center gap-2 px-4 pb-4 pt-3">
+        {current.alt && <div className="max-w-[90vw] truncate text-[14px] font-medium">{current.alt}</div>}
+        <div className="relative flex items-center gap-3">
+          <span className="inline-flex items-center gap-px rounded-lg border border-border/70 bg-muted/40 p-0.5">
+            <button type="button" className="flex h-7 w-7 items-center justify-center rounded-md hover:bg-muted" onClick={() => step(-1)} aria-label="Previous image" tabIndex={-1}>
+              <svg {...ICON} width={14} height={14}>
+                <path d="m15.75 19.5-7.5-7.5 7.5-7.5" />
+              </svg>
+            </button>
+            <button
+              ref={pillRef}
+              type="button"
+              className="flex h-7 max-w-[60vw] items-center gap-1.5 rounded-md px-2 text-[13.5px] hover:bg-muted"
+              aria-haspopup="grid"
+              aria-expanded={peekOpen}
+              aria-label={`${index + 1} of ${total}, ${name}. Show every image in this document`}
+              onClick={() => setPeekOpen((v) => !v)}
+              data-peek-opener=""
+              data-lightbox-pill=""
+            >
+              <span className="tabular-nums text-muted-foreground">
+                {index + 1} of {total}
+              </span>
+              <span className="text-muted-foreground" aria-hidden="true">
+                ·
+              </span>
+              <span className="truncate font-semibold">{name}</span>
+              <svg {...ICON} width={13} height={13} className={peekOpen ? 'rotate-180' : ''}>
+                <path d="m19.5 8.25-7.5 7.5-7.5-7.5" />
+              </svg>
+            </button>
+            <button type="button" className="flex h-7 w-7 items-center justify-center rounded-md hover:bg-muted" onClick={() => step(1)} aria-label="Next image" tabIndex={-1}>
+              <svg {...ICON} width={14} height={14}>
+                <path d="m8.25 4.5 7.5 7.5-7.5 7.5" />
+              </svg>
+            </button>
+          </span>
+          <span className={`whitespace-nowrap rounded-md bg-muted px-2 py-1 text-[12px] text-muted-foreground transition-opacity ${endNote ? 'opacity-100' : 'opacity-0'}`} aria-hidden="true" data-lightbox-end-note="">
+            {endNote}
+          </span>
+          {peekOpen && (
+            <div className="absolute bottom-[calc(100%+8px)] left-1/2 z-10 -translate-x-1/2">
+              <ImagePeek
+                ref={peekRef}
+                rows={rows}
+                current={String(index)}
+                label="Images in this document"
+                onPick={(key) => {
+                  setPeekOpen(false);
+                  go(Number(key));
+                  pillRef.current?.focus({ preventScroll: true });
+                }}
+                onClose={(reason) => {
+                  setPeekOpen(false);
+                  if (reason === 'key') pillRef.current?.focus({ preventScroll: true });
+                }}
+              />
+            </div>
+          )}
+        </div>
+      </div>
+      <div className="sr-only" aria-live="polite" data-lightbox-live="">
+        {announced}
+      </div>
     </div>
   );
 };

package/components/ImagePeek.tsx

@@ -0,0 +1,255 @@
+import React, { forwardRef, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState } from 'react';
+
+/**
+ * The picture list a stepper opens ("A · Peek", approval "inbox-image-viewer",
+ * 2026-10-15): one row per group (a message, a section of a document) with
+ * its label, each item a thumbnail with its name under it, the open one
+ * ringed. It floats over what is open and moves nothing under it; on a phone
+ * it is a bottom sheet, three across.
+ *
+ * Keys only while it is open: ← → along the items, ↑ ↓ between rows (the
+ * nearest column), Home / End, Enter or Space opens the item (`onPick`), Esc or
+ * Tab closes it (`onClose`). The host puts focus back on the control that
+ * opened it. Focus starts on the open item.
+ *
+ * Images are only ever drawn through `<img src>`.
+ */
+export interface ImagePeekItem {
+  /** Unique across the peek. */
+  key: string;
+  name: string;
+  /** An image URL for the thumbnail; absent for a file drawn as a type tile. */
+  thumb?: string | null;
+  /** The type tile's short label ("MD", "PDF") when there is no thumbnail. */
+  tile?: string;
+  /** Comments on it, shown as a count badge when more than 0. */
+  count?: number;
+  /** A paperclip badge (an attached file, as opposed to an image in the text). */
+  attached?: boolean;
+  /** Extra words for a screen reader ("changed since it was sent"). */
+  detail?: string;
+}
+
+export interface ImagePeekRow {
+  key: string;
+  /** "11:22 AM", or a section heading. */
+  label: string;
+  items: ImagePeekItem[];
+}
+
+export interface ImagePeekProps {
+  rows: readonly ImagePeekRow[];
+  /** The open item's key: ringed, and where focus starts. */
+  current: string | null;
+  onPick: (key: string) => void;
+  /** Esc or Tab (`key`: the host puts focus back on its opener), or a press outside / the sheet's backdrop (`outside`). */
+  onClose: (reason: 'key' | 'outside') => void;
+  /** `popover`: a panel the host positions above its bar. `sheet`: a phone's bottom sheet, three across. */
+  variant?: 'popover' | 'sheet';
+  /** The grid's accessible name. */
+  label: string;
+  /** An id for the panel, for the opener's `aria-controls`. */
+  id?: string;
+  className?: string;
+}
+
+const PaperclipIcon = () => (
+  <svg width="11" height="11" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+    <path d="m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l8.57-8.57A4 4 0 1 1 18 8.84l-8.59 8.57a2 2 0 0 1-2.83-2.83l8.49-8.48" />
+  </svg>
+);
+
+/** Where focus may move from `at` (row, column) for a key, or null when the key is not the grid's. */
+export function peekMove(rows: readonly { items: readonly unknown[] }[], at: { row: number; col: number }, key: string): { row: number; col: number } | null {
+  const flat: { row: number; col: number }[] = [];
+  rows.forEach((row, r) => row.items.forEach((_, c) => flat.push({ row: r, col: c })));
+  if (flat.length === 0) return null;
+  const index = flat.findIndex((p) => p.row === at.row && p.col === at.col);
+  switch (key) {
+    case 'ArrowRight':
+      return flat[Math.min(flat.length - 1, index + 1)]!;
+    case 'ArrowLeft':
+      return flat[Math.max(0, index - 1)]!;
+    case 'Home':
+      return flat[0]!;
+    case 'End':
+      return flat[flat.length - 1]!;
+    case 'ArrowDown':
+    case 'ArrowUp': {
+      const step = key === 'ArrowDown' ? 1 : -1;
+      for (let r = at.row + step; r >= 0 && r < rows.length; r += step) {
+        const count = rows[r]!.items.length;
+        if (count > 0) return { row: r, col: Math.min(at.col, count - 1) };
+      }
+      return at;
+    }
+    default:
+      return null;
+  }
+}
+
+/** A host that intercepts keys before they reach the peek (a modal's capture listener) hands them over here. */
+export interface ImagePeekHandle {
+  /** Handle one key as the peek would; true when it was the peek's (the caller prevents its default). */
+  handleKey: (event: { key: string; isComposing?: boolean }) => boolean;
+}
+
+export const ImagePeek = forwardRef<ImagePeekHandle, ImagePeekProps>(function ImagePeek({ rows, current, onPick, onClose, variant = 'popover', label, id, className = '' }, ref) {
+  const sheet = variant === 'sheet';
+  const gridRef = useRef<HTMLDivElement>(null);
+  const autoId = useId();
+  const labelId = `${(id ?? `pn-peek-${autoId}`).replace(/:/g, '')}-label`;
+  const start = useMemo(() => {
+    for (let r = 0; r < rows.length; r++) {
+      const c = rows[r]!.items.findIndex((item) => item.key === current);
+      if (c >= 0) return { row: r, col: c };
+    }
+    const r = rows.findIndex((row) => row.items.length > 0);
+    return { row: Math.max(0, r), col: 0 };
+  }, [rows, current]);
+  const [focus, setFocus] = useState(start);
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
+
+  const cellOf = (at: { row: number; col: number }) => gridRef.current?.querySelector<HTMLElement>(`[data-peek-cell="${at.row}:${at.col}"]`) ?? null;
+
+  // Focus starts on the open item, and the open item is in view.
+  useLayoutEffect(() => {
+    const cell = cellOf(start);
+    cell?.focus({ preventScroll: true });
+    cell?.scrollIntoView?.({ block: 'nearest' });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  // A press outside closes it (the opener toggles it itself).
+  useEffect(() => {
+    if (sheet) return;
+    const onDown = (event: PointerEvent) => {
+      const target = event.target instanceof Node ? event.target : null;
+      if (!target || gridRef.current?.contains(target)) return;
+      if (target instanceof Element && target.closest('[data-peek-opener]')) return;
+      onCloseRef.current('outside');
+    };
+    document.addEventListener('pointerdown', onDown, true);
+    return () => document.removeEventListener('pointerdown', onDown, true);
+  }, [sheet]);
+
+  const focusRef = useRef(focus);
+  focusRef.current = focus;
+  const handleKey = (event: { key: string; isComposing?: boolean }): boolean => {
+    if (event.isComposing) return false;
+    if (event.key === 'Escape' || event.key === 'Tab') {
+      onClose('key');
+      return true;
+    }
+    const at = focusRef.current;
+    if (event.key === 'Enter' || event.key === ' ') {
+      const item = rows[at.row]?.items[at.col];
+      if (item) onPick(item.key);
+      return true;
+    }
+    const next = peekMove(rows, at, event.key);
+    if (!next) return false;
+    focusRef.current = next;
+    setFocus(next);
+    const cell = cellOf(next);
+    cell?.focus({ preventScroll: true });
+    cell?.scrollIntoView?.({ block: 'nearest' });
+    return true;
+  };
+  const handleKeyRef = useRef(handleKey);
+  handleKeyRef.current = handleKey;
+  useImperativeHandle(ref, () => ({ handleKey: (event) => handleKeyRef.current(event) }), []);
+
+  const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    if (!handleKey({ key: event.key, isComposing: event.nativeEvent.isComposing })) return;
+    event.preventDefault();
+    event.stopPropagation();
+  };
+
+  const panel = (
+    <div
+      ref={gridRef}
+      id={id}
+      role="grid"
+      aria-labelledby={labelId}
+      onKeyDown={onKeyDown}
+      data-image-peek={variant}
+      className={
+        sheet
+          ? `pointer-events-auto max-h-[78vh] w-full overflow-y-auto rounded-t-2xl border-t border-border bg-popover px-3 pb-[calc(16px+env(safe-area-inset-bottom))] pt-2 text-popover-foreground shadow-2xl ${className}`
+          : `max-h-[min(460px,62vh)] w-[min(600px,calc(100vw-24px))] overflow-y-auto rounded-xl border border-border bg-popover p-2 text-popover-foreground shadow-[0_14px_36px_rgba(0,0,0,0.28)] ${className}`
+      }
+    >
+      <span id={labelId} className="sr-only">
+        {label}
+      </span>
+      {sheet && <div className="mx-auto mb-2 h-1.5 w-10 rounded-full bg-muted-foreground/30" aria-hidden="true" />}
+      {rows.map((row, r) => (
+        <div
+          key={row.key}
+          role="row"
+          className={`${sheet ? 'flex flex-col gap-2 py-2' : 'grid grid-cols-[84px_1fr] gap-2 px-1 py-2'} ${r > 0 ? 'border-t border-border/60' : ''}`}
+          data-peek-row={row.key}
+        >
+          <span role="rowheader" className={`text-[12.5px] text-muted-foreground ${sheet ? 'px-1 text-[14px]' : 'pt-1 tabular-nums'}`}>
+            {row.label}
+          </span>
+          <div role="presentation" className={sheet ? 'grid grid-cols-3 gap-2' : 'grid grid-cols-[repeat(auto-fill,minmax(132px,1fr))] gap-2'}>
+            {row.items.map((item, c) => {
+              const open = item.key === current;
+              const focused = focus.row === r && focus.col === c;
+              const words = [item.name, item.attached ? 'attached' : null, item.count ? `${item.count} comment${item.count === 1 ? '' : 's'}` : null, item.detail ?? null, open ? 'open now' : null]
+                .filter(Boolean)
+                .join(', ');
+              return (
+                <div
+                  key={item.key}
+                  role="gridcell"
+                  tabIndex={focused ? 0 : -1}
+                  aria-selected={open}
+                  aria-label={words}
+                  data-peek-cell={`${r}:${c}`}
+                  data-peek-item={item.key}
+                  data-peek-open={open ? '' : undefined}
+                  onClick={() => onPick(item.key)}
+                  onFocus={() => setFocus({ row: r, col: c })}
+                  className="group flex min-w-0 cursor-pointer flex-col gap-1 rounded-lg p-1 outline-none hover:bg-muted/70 focus-visible:bg-muted focus-visible:outline-2 focus-visible:outline-offset-1 focus-visible:outline-dashed focus-visible:outline-foreground/45"
+                >
+                  <span
+                    className={`relative block w-full overflow-hidden rounded-md border bg-muted ${sheet ? 'h-[99px]' : 'aspect-[16/10]'} ${open ? 'border-primary ring-2 ring-primary' : 'border-border/70'}`}
+                  >
+                    {item.thumb ? (
+                      <img src={item.thumb} alt="" loading="lazy" decoding="async" draggable={false} className="h-full w-full object-cover object-top" />
+                    ) : (
+                      <span className="flex h-full w-full items-center justify-center font-mono text-[12px] font-semibold tracking-wide text-muted-foreground">{item.tile ?? 'FILE'}</span>
+                    )}
+                    {item.attached && (
+                      <span className="absolute bottom-1 left-1 flex h-[18px] w-[18px] items-center justify-center rounded-full bg-card text-foreground shadow-sm" aria-hidden="true" data-peek-attached="">
+                        <PaperclipIcon />
+                      </span>
+                    )}
+                    {item.count ? (
+                      <span className="absolute right-1 top-1 flex h-[18px] min-w-[18px] items-center justify-center rounded-full bg-primary px-1 text-[11px] font-semibold text-primary-foreground" aria-hidden="true" data-peek-count="">
+                        {item.count}
+                      </span>
+                    ) : null}
+                  </span>
+                  <span className={`line-clamp-2 [overflow-wrap:anywhere] text-[12.5px] leading-tight ${open ? 'font-semibold text-foreground' : 'text-foreground/85'}`}>{item.name}</span>
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+
+  if (!sheet) return panel;
+  return (
+    <div className="fixed inset-0 z-[220] flex flex-col justify-end" data-image-peek-sheet="">
+      <div className="absolute inset-0 bg-black/40" aria-hidden="true" onClick={() => onClose('outside')} data-peek-backdrop="" />
+      <div className="relative">{panel}</div>
+    </div>
+  );
+});

package/components/ImageResolverContext.tsx

@@ -0,0 +1,31 @@
+import { createContext, useContext } from "react";
+
+/**
+ * What a host makes of an image a document references (`![shot](img/a.png)`,
+ * or an `<img src>` in a raw HTML block):
+ *
+ * - `src`: load the image from this URL instead of the default resolution.
+ * - `unavailable`: draw a small inert placeholder (the alt text, `title` as
+ *   its tooltip) instead of an `<img>`, so nothing is fetched.
+ * - `null` from the resolver: the renderer's default for that image.
+ */
+export type ImageResolution =
+  | { kind: "src"; src: string }
+  | { kind: "unavailable"; title: string };
+
+/** Called with the image source exactly as the document wrote it. */
+export type ImageResolver = (src: string) => ImageResolution | null;
+
+/**
+ * Provided by `RenderedMarkdown` from its optional `resolveImage` prop.
+ * Absent (null), every image renders exactly as it always has.
+ */
+export const ImageResolverContext = createContext<ImageResolver | null>(null);
+
+export function useImageResolver(): ImageResolver | null {
+  return useContext(ImageResolverContext);
+}
+
+/** Classes for the inert placeholder an `unavailable` image renders as. */
+export const UNAVAILABLE_IMAGE_CLASS =
+  "inline-flex items-center gap-1 my-1 rounded border border-dashed border-border px-2 py-0.5 text-xs text-muted-foreground";