Ground-truth Expected/Actual labels + named source list, lightbox zoom/pan, and ground-truth P3 design (GB-965, GB-963, GB-962)

Ground-truth UX polish (GB-965): the side-by-side comparison panes now read "Expected (A)" / "Actual (B)" instead of the generic Old/New in ground-truth mode, and the sidebar renders a flat list of named comparisons (manifest label with a basename fallback, plus a Spec/Reference/Baseline expectedKind badge, most-different-first) rather than an actual/ file tree. New pure helper src/ground-truth/presentation.ts (groundTruthSideLabels, groundTruthMetaByFileId, EXPECTED_KIND_LABELS) shared by the diff page and the /files route; the response carries an optional per-file groundTruth map that the client stores on reviewStore. Threaded sideLabels through ImageDiff and DiffView. Documented as FR-26.7 / FR-26.8.

Lightbox zoom/pan (GB-963): the shared lightbox now zooms (wheel / pinch / on-screen +- controls, up to 8x) and pans (drag a zoomed image, or wheel), so a reviewer can mark a precise region on a large artifact; note-artifact and attachment image previews get this for free since they share the component. Zoom/pan math lives in the pure, unit-tested src/client/lightboxZoom.ts; region fractions stay correct under any transform because they are read from the overlay's live post-transform bounding rect. Restructured the lightbox DOM to a clipping viewport around the transformed frame. Documented as FR-25.7. Image-file-diff lightbox adoption is filed as GB-966.

Ground-truth P3 design (GB-962, design only): documented sets / multi-step flows in doc 26 - a version:2 additive manifest with ordered sets/steps and per-step navigation, per-step plus max-aggregate perceptual scoring, a consumer-only capture contract (Glassbox runs no capturer and takes no domotion dependency) with proof-export guidance for projects, and external baseline rotation. Implementation is tracked in phased follow-ups GB-967 (loader/model), GB-968 (UI), GB-969 (guidance doc/skill), and GB-970 (optional promote helper).

Tests: new unit suites tests/unit/ground-truth/presentation.test.ts and tests/unit/client/lightboxZoom.test.ts; e2e assertions added in tests/e2e/ground-truth.test.ts (label + expectedKind badge, Expected/Actual pane captions) and tests/e2e/diff-viewing.test.ts (lightbox zoom controls). Full unit suite and the ground-truth + lightbox e2e tests pass; typecheck and lint clean.

Author: Brian Westphal

docs/20-ai-review-notes.md

@@ -200,7 +200,9 @@ Authoring shall support a combined live-plus-coalesce flow (not either/or):
   served by `GET /api/review-notes/artifact` (path-contained, content-typed,
   size-capped). The reviewer can **mark a rectangle on an image artifact** two
   ways: **inline** — drag directly on the thumbnail (a plain click instead opens
-  the full-screen lightbox) — or in the **lightbox** itself. Either way the
+  the full-screen lightbox, which can be **zoomed/panned** to mark a precise spot
+  on a large artifact — doc 25 FR-25.7 / GB-963) — or in the **lightbox** itself.
+  Either way the
   rectangle is carried into the reply they then write, and a reply can carry
   **several** marks (GB-959): the reply renders each artifact with its
   rectangle(s) over it (a "see this spot" thumbnail). Each region reuses doc 23's

docs/25-attachments.md

@@ -31,6 +31,15 @@ for which UI surfaces are wired today.
   when clicked or activated with **Space**, shall open in a full-screen in-app
   overlay (lightbox) — instant, stays in the app, and works in any browser.
   Esc, Space, or a backdrop click dismisses it.
+- **FR-25.7 — Zoom/pan in the lightbox (shipped, GB-963).** An image in the
+  lightbox can be **zoomed** (wheel / pinch / the on-screen +/− controls, up to
+  8×) and **panned** (drag a zoomed image, or two-finger / wheel), so a reviewer
+  can inspect — and, on a markable artifact, precisely mark — a region on a large
+  image. The zoom/pan math is pure + unit-tested (`src/client/lightboxZoom.ts`);
+  region fractions stay correct under any transform because they're read from the
+  overlay's live post-transform bounding rect. PDFs are not zoomed (native
+  iframe). The lightbox (`src/client/lightbox.tsx`) is shared by attachment
+  previews and AI-note image artifacts (doc 20 §20.5).
 - **FR-25.5 — OS opener for other types.** A non-previewable attachment shall
   open in the OS default application: macOS **Quick Look** (`qlmanage -p`), the
   platform default opener on Windows (`start`) and Linux (`xdg-open`). Because

docs/26-ground-truth-comparison.md

@@ -140,6 +140,7 @@ See §6 for the schema itself.
 | `types.ts` | `ReviewMode` (incl. the doc-18 `diff` + doc-26 `ground-truth` variants), `GroundTruthEntry`, `FileDiff`, `DiffHunk`, `DiffLine`. |
 | `../ground-truth/manifest.ts` | doc 26 — `loadGroundTruthManifest(path)`: read/validate (`version:1` + `comparisons[]`), resolve actual/expected paths relative to the manifest dir, image-only check, dedup keys. |
 | `../ground-truth/perceptual-diff.ts` | doc 26 P2 — `comparePerceptual(actual, expected)`: decode PNG/JPEG to RGBA (`pngjs`/`jpeg-js`) + `pixelmatch` (YIQ, threshold 0.1, AA-tolerant) → difference score (fraction of changed pixels); `dimension-mismatch`→1, SVG/WebP/corrupt→`undecodable`. Score computed at launch + stored on `review_files.difference_score`. Format helpers in `src/utils/diffScore.ts`. |
+| `../ground-truth/presentation.ts` | doc 26 §26.1 polish — pure helpers shared by the diff page + `/files` route. `groundTruthSideLabels(mode)` → "Expected (A)" / "Actual (B)" pane captions (via `ImageDiff.sideLabels` / `DiffView.imageSideLabels`); `groundTruthMetaByFileId(mode, files)` → `fileId → {label, expectedKind}` map the `/files` response carries for ground-truth reviews (drives the flat named-comparison sidebar list, `groundTruthListJsx`); `EXPECTED_KIND_LABELS` (Spec / Reference / Baseline). |
 | `image.ts` | Image side retrieval from git (old/new), binary detection, format identification. |
 | `image-metadata.ts` | Parse image headers (PNG IHDR, JPEG SOF/JFIF, GIF, WebP VP8/VP8L/VP8X) — no native deps. |
 | `svg-meta.ts` | Pure SVG metadata helpers for the "Rendered" view: `parseSvgDimensions` (base size from width/height/viewBox) and `svgUsesExternalFonts` (font-caveat banner trigger). No rendering. SVGs are rendered live in the browser (GB-932): the image route serves them as raw `image/svg+xml` and the diff shows them in a native `<img>`, so animated SVGs animate. The old `@resvg/resvg-wasm` rasterizer + worker thread were removed. |
@@ -703,7 +704,7 @@ two documents intentionally overlap.
 | Change the DB schema | `src/db/schema.ts` (tables/indexes) + a migration in `src/db/connection.ts` (`addColumnIfMissing` pattern). Query code in `src/db/queries.ts` or `ai-queries.ts`. |
 | Add an annotation category | `src/client/state.ts` (CATEGORIES), `src/client/annotations/categories.tsx` (UI), `src/routes/api/annotations.ts` (`VALID_CATEGORIES`), `src/export/generate.ts` (export semantics). Update `docs/5-annotations.md` + `docs/6-export.md`. |
 | Work on feedback attachments | `src/client/annotations/attachments.tsx` (chips/upload/drag-drop/paste/preview), `src/routes/api/attachments.ts` + `src/api/attachments.ts` (API), `src/db/attachment-queries.ts` + `src/attachments/store.ts` (storage), `src/utils/openOS.ts` (`'quicklook'`), `src/export/generate.ts` (export paths). Doc 25. |
-| Work on the image lightbox / note-artifact regions | `src/client/lightbox.tsx` (shared full-screen lightbox + region draw), `src/client/diff/noteArtifactRegions.tsx` (inline drag-to-draw on the thumbnail **or** click → lightbox; accumulates pending regions per note), `src/utils/artifactRegions.ts` (pure decode/group of `region_data` arrays), `src/components/reviewNoteRegionThumb.tsx` (the marked-region thumbnail(s) on a reply). Regions carried into the reply via `createAnnotation`'s `regions` array (→ `region_data` JSON array with `artifact` uris; single object still read for back-compat). Doc 25 / GB-953, GB-959. |
+| Work on the image lightbox / note-artifact regions | `src/client/lightbox.tsx` (shared full-screen lightbox + zoom/pan + region draw; zoom/pan math in the pure `src/client/lightboxZoom.ts`, GB-963), `src/client/diff/noteArtifactRegions.tsx` (inline drag-to-draw on the thumbnail **or** click → lightbox; accumulates pending regions per note), `src/utils/artifactRegions.ts` (pure decode/group of `region_data` arrays), `src/components/reviewNoteRegionThumb.tsx` (the marked-region thumbnail(s) on a reply). Regions carried into the reply via `createAnnotation`'s `regions` array (→ `region_data` JSON array with `artifact` uris; single object still read for back-compat). Doc 25 / GB-953, GB-959. |
 | Add a CLI option | `src/cli.ts` `parseArgs()` switch; document in `docs/2-cli-and-server.md`. |
 | Add an AI platform | `src/ai/models.ts` (platform enum + fallback models + env key; `KEYLESS_PLATFORMS` if no key needed), `src/ai/list-models.ts` (live-discovery fetch+map), `src/ai/client.ts` (HTTP/spawn dispatch), `src/ai/config.ts` (any per-platform config like a base URL), `src/ai/api-keys.ts` (key source mapping), `src/routes/ai-config.ts` + `src/api/ai.ts` (config/discovery/key-status wiring), `src/client/settings/experimentalTab.tsx` + `dialog.tsx` (picker + any platform-specific inputs). The `local` platform (doc 22) is the worked example of a keyless, base-URL-configured provider. Update `docs/7-ai-analysis.md`. |
 | Update / discover AI models | Models are discovered live per provider in `src/ai/list-models.ts` (used by `GET /api/ai/models`); `src/ai/models.ts` holds the static fallback + `resolveModelId` old→new mapping. |

docs/ai/code-summary.md

@@ -163,8 +163,20 @@ pair is (fraction of changed pixels, anti-aliasing-tolerant); identical pairs ar
 hidden by default (toggle to show), the score shows per source-list entry + in
 the diff header, and the list sorts most-different-first. Score stored on
 `review_files.difference_score`. PNG/JPEG only; other formats show with no score.
-**P3** (sets/flows + capture pipeline incl. domotion animated SVGs; baseline
-rotation) remains design-only — phased follow-up ticket.
+**UX polish** (shipped, FR-26.7/26.8): in ground-truth mode the side-by-side panes
+read **Expected (A)** / **Actual (B)**, and the sidebar is a **flat list of named
+comparisons** — each row captioned by the manifest `label` (basename fallback)
+with a **Spec / Reference / Baseline** `expectedKind` badge, most-different-first
+(`src/ground-truth/presentation.ts`). **P3** (sets/multi-step flows +
+capture-pipeline guidance + baseline rotation) is now **fully designed** (doc 26
+§26.2/§26.3/§26.5): a `version: 2` additive manifest with ordered `sets`/`steps`,
+source-list **set groups** with per-step rows + max-aggregate perceptual score +
+a per-step Prev/Next navigator, a **consumer-only** capture contract (Glassbox
+runs no capturer / takes no domotion dependency) plus **proof-export guidance**
+for projects (screenshots, logs-as-note-artifacts, animated-SVG flows), and
+**external** baseline rotation. Implementation is **design-only** — tracked in
+phased follow-up tickets (P3a loader/model, P3b UI, P3c guidance doc/skill, P3d
+optional `promote` helper).
 
 **Image feedback** (doc 23): a panel below the image canvas lets the
 reviewer add general comments about an image and draw rectangle regions

docs/ai/requirements-summary.md

@@ -9,10 +9,25 @@ import { apiCall, OkResponseSchema } from './_runner.js';
 export const FileStatusSchema = z.enum(['pending', 'reviewed']);
 export type FileStatus = z.infer<typeof FileStatusSchema>;
 
+/**
+ * Per-file ground-truth presentation metadata (doc 26 §26.1). Present only for
+ * ground-truth reviews; lets the sidebar read like a list of named comparisons
+ * (label + what the expected image represents) rather than a raw `actual/` file
+ * tree. An entry exists for every ground-truth file even when both fields are
+ * absent, so the map's keys also signal "this is a ground-truth review".
+ */
+export const GroundTruthMetaSchema = z.object({
+  label: z.string().optional(),
+  expectedKind: z.enum(['spec', 'reference', 'previous-actual']).optional(),
+});
+export type GroundTruthMeta = z.infer<typeof GroundTruthMetaSchema>;
+
 export const ListFilesRespSchema = z.object({
   files: z.array(ReviewFileSchema),
   annotationCounts: z.record(z.string(), z.number()),
   staleCounts: z.record(z.string(), z.number()),
+  /** Keyed by review-file id; omitted/empty for non-ground-truth reviews. */
+  groundTruth: z.record(z.string(), GroundTruthMetaSchema).optional(),
 });
 export type ListFilesResp = z.infer<typeof ListFilesRespSchema>;
 

src/api/files.ts

@@ -2,15 +2,25 @@ import type { ImageRegion } from '../api/index.js';
 import { IconX } from '../icons.js';
 import { clientToFraction, isDrawnRegion, rectFromPoints, regionStyle } from './diff/imageDiff/regionGeometry.js';
 import { toElement } from './dom.js';
+import {
+  clampPan,
+  LIGHTBOX_MIN_ZOOM,
+  type LightboxZoomState,
+  resetZoom,
+  zoomTowardCursor,
+} from './lightboxZoom.js';
 
 /**
  * Shared full-screen lightbox (doc 25 / GB-953). Used to preview note image
- * artifacts and, optionally, to drag a rectangle on the image to mark a region
- * (normalized `{x,y,w,h}`, doc 23's model). One instance at a time; Esc, the
- * close button, or a backdrop click dismisses it.
+ * artifacts and attachment images and, optionally, to drag a rectangle on the
+ * image to mark a region (normalized `{x,y,w,h}`, doc 23's model). One instance
+ * at a time; Esc, the close button, or a backdrop click dismisses it.
  *
- * Built to be reusable: attachment image previews and image-file diffs can adopt
- * it later. The region-draw layer is opt-in via `onRegion`.
+ * Images support zoom (wheel / pinch / the +/− controls) and pan (drag when not
+ * drawing a region, or wheel/two-finger) so a reviewer can mark a precise region
+ * on a large artifact (GB-963). Region fractions stay correct under any transform
+ * because they're read from the overlay's live (post-transform) bounding rect.
+ * The region-draw layer is opt-in via `onRegion`.
  */
 
 interface LightboxOptions {
@@ -25,6 +35,7 @@ interface LightboxOptions {
 
 let openEl: HTMLElement | null = null;
 let escHandler: ((e: KeyboardEvent) => void) | null = null;
+const ZOOM_STEP = 1.25;
 
 export function closeLightbox(): void {
   if (openEl === null) return;
@@ -42,7 +53,8 @@ export function isLightboxOpen(): boolean {
 
 export function openLightbox(opts: LightboxOptions): void {
   closeLightbox();
-  const drawable = opts.kind !== 'pdf' && opts.onRegion !== undefined;
+  const isImage = opts.kind !== 'pdf';
+  const drawable = isImage && opts.onRegion !== undefined;
 
   const media = opts.kind === 'pdf'
     ? <iframe className="lightbox-pdf" src={opts.src} title={opts.alt ?? 'attachment'}></iframe>
@@ -51,10 +63,19 @@ export function openLightbox(opts: LightboxOptions): void {
   const overlay = toElement(
     <div className="lightbox-overlay" role="dialog" aria-label={opts.alt ?? 'Preview'}>
       <button className="lightbox-close" aria-label="Close"><IconX /></button>
-      <div className={`lightbox-frame${drawable ? ' lightbox-drawable' : ''}`}>
-        {media}
-        <div className="lightbox-region-overlay"></div>
+      <div className="lightbox-viewport">
+        <div className={`lightbox-frame${drawable ? ' lightbox-drawable' : ''}`}>
+          {media}
+          <div className="lightbox-region-overlay"></div>
+        </div>
       </div>
+      {isImage ? (
+        <div className="lightbox-controls" role="group" aria-label="Zoom">
+          <button className="lightbox-zoom-btn" data-zoom="out" aria-label="Zoom out">&minus;</button>
+          <button className="lightbox-zoom-btn lightbox-zoom-level" data-zoom="reset" aria-label="Reset zoom">100%</button>
+          <button className="lightbox-zoom-btn" data-zoom="in" aria-label="Zoom in">+</button>
+        </div>
+      ) : null}
       {drawable ? <div className="lightbox-hint">Drag a rectangle to mark a region for your reply</div> : null}
     </div>,
   );
@@ -65,6 +86,9 @@ export function openLightbox(opts: LightboxOptions): void {
   });
   overlay.querySelector('.lightbox-close')?.addEventListener('click', () => { closeLightbox(); });
 
+  if (isImage) {
+    wireZoomPan(overlay, drawable);
+  }
   if (drawable && opts.onRegion !== undefined) {
     wireRegionDraw(overlay, opts.onRegion);
   }
@@ -78,6 +102,80 @@ export function openLightbox(opts: LightboxOptions): void {
   openEl = overlay;
 }
 
+/** Zoom (wheel / pinch / +−) and pan (drag when not drawing, or wheel) on the
+ *  image frame, clipped to the viewport. Region fractions stay accurate because
+ *  `wireRegionDraw` reads the overlay's live post-transform rect. */
+function wireZoomPan(overlay: HTMLElement, drawable: boolean): void {
+  const viewport = overlay.querySelector<HTMLElement>('.lightbox-viewport');
+  const frame = overlay.querySelector<HTMLElement>('.lightbox-frame');
+  const level = overlay.querySelector<HTMLElement>('.lightbox-zoom-level');
+  if (viewport === null || frame === null) return;
+
+  let state: LightboxZoomState = resetZoom();
+
+  const apply = (): void => {
+    state = clampPan(state, frame.offsetWidth, frame.offsetHeight, viewport.clientWidth, viewport.clientHeight);
+    frame.style.transform = state.zoom <= LIGHTBOX_MIN_ZOOM
+      ? ''
+      : `translate(${String(state.panX)}px, ${String(state.panY)}px) scale(${String(state.zoom)})`;
+    overlay.classList.toggle('lightbox-zoomed', state.zoom > LIGHTBOX_MIN_ZOOM);
+    if (level !== null) level.textContent = `${String(Math.round(state.zoom * 100))}%`;
+  };
+
+  const zoomBy = (factor: number, clientX: number, clientY: number): void => {
+    state = zoomTowardCursor(state, viewport.getBoundingClientRect(), clientX, clientY, factor);
+    apply();
+  };
+
+  viewport.addEventListener('wheel', (e: WheelEvent) => {
+    e.preventDefault();
+    // ctrlKey is a pinch gesture (or Ctrl+wheel) → zoom; a plain wheel pans when
+    // zoomed in. Mirrors the image-diff canvas split (GB-942).
+    if (e.ctrlKey) {
+      zoomBy(e.deltaY < 0 ? ZOOM_STEP : 1 / ZOOM_STEP, e.clientX, e.clientY);
+    } else if (state.zoom > LIGHTBOX_MIN_ZOOM) {
+      state = { zoom: state.zoom, panX: state.panX - e.deltaX, panY: state.panY - e.deltaY };
+      apply();
+    }
+  }, { passive: false });
+
+  viewport.addEventListener('mousedown', (e: MouseEvent) => {
+    if (e.button !== 0) return;
+    // A click on the empty margin around the image closes (the viewport fills
+    // most of the screen now, so the backdrop is mostly this element).
+    if (e.target === viewport && state.zoom <= LIGHTBOX_MIN_ZOOM) { closeLightbox(); return; }
+    // Region-draw mode owns frame drags; otherwise a drag pans a zoomed image.
+    if (drawable || state.zoom <= LIGHTBOX_MIN_ZOOM) return;
+    e.preventDefault();
+    overlay.classList.add('lightbox-panning');
+    const startX = e.clientX - state.panX;
+    const startY = e.clientY - state.panY;
+    const onMove = (ev: MouseEvent): void => {
+      state = { zoom: state.zoom, panX: ev.clientX - startX, panY: ev.clientY - startY };
+      apply();
+    };
+    const onUp = (): void => {
+      document.removeEventListener('mousemove', onMove);
+      document.removeEventListener('mouseup', onUp);
+      overlay.classList.remove('lightbox-panning');
+    };
+    document.addEventListener('mousemove', onMove);
+    document.addEventListener('mouseup', onUp);
+  });
+
+  overlay.querySelectorAll<HTMLElement>('.lightbox-zoom-btn').forEach((btn) => {
+    btn.addEventListener('click', () => {
+      const rect = viewport.getBoundingClientRect();
+      const cx = rect.left + rect.width / 2;
+      const cy = rect.top + rect.height / 2;
+      const kind = btn.dataset.zoom;
+      if (kind === 'in') zoomBy(ZOOM_STEP, cx, cy);
+      else if (kind === 'out') zoomBy(1 / ZOOM_STEP, cx, cy);
+      else { state = resetZoom(); apply(); }
+    });
+  });
+}
+
 /** Drag-to-draw a single rectangle over the lightbox image; on a valid release,
  *  hand the normalized region to `onRegion` and close. */
 function wireRegionDraw(overlay: HTMLElement, onRegion: (region: ImageRegion) => void): void {

src/client/lightbox.tsx

@@ -0,0 +1,80 @@
+/**
+ * Pure zoom/pan geometry for the shared lightbox (GB-963). Kept DOM-free so the
+ * math is unit-tested; `lightbox.tsx` does the imperative wiring.
+ *
+ * The model: an image-sized frame is centered in a fixed viewport and carries a
+ * `translate(panX,panY) scale(zoom)` transform (transform-origin: center). Zoom
+ * is anchored at the cursor; pan is clamped so a zoomed image can't be dragged
+ * fully out of the viewport (and a not-larger-than-viewport image stays centered).
+ */
+
+export interface LightboxZoomState {
+  zoom: number;
+  panX: number;
+  panY: number;
+}
+
+export const LIGHTBOX_MIN_ZOOM = 1;
+export const LIGHTBOX_MAX_ZOOM = 8;
+
+export function clampZoom(z: number): number {
+  return Math.max(LIGHTBOX_MIN_ZOOM, Math.min(LIGHTBOX_MAX_ZOOM, z));
+}
+
+interface Rect { left: number; top: number; width: number; height: number }
+
+/**
+ * Multiply the zoom by `factor`, keeping the content point under the cursor
+ * fixed on screen. Pan is *not* clamped here — call `clampPan` afterwards with
+ * the resolved content/viewport sizes.
+ */
+export function zoomTowardCursor(
+  state: LightboxZoomState,
+  viewport: Rect,
+  clientX: number,
+  clientY: number,
+  factor: number,
+): LightboxZoomState {
+  const z0 = state.zoom;
+  const z1 = clampZoom(z0 * factor);
+  if (z1 === z0) return { ...state };
+  const cx = viewport.left + viewport.width / 2;
+  const cy = viewport.top + viewport.height / 2;
+  // Vector from the (panned) frame center to the cursor, in screen px.
+  const dx = clientX - cx - state.panX;
+  const dy = clientY - cy - state.panY;
+  const ratio = z1 / z0;
+  return {
+    zoom: z1,
+    panX: state.panX + dx * (1 - ratio),
+    panY: state.panY + dy * (1 - ratio),
+  };
+}
+
+/**
+ * Clamp pan so the scaled content keeps covering the viewport when it's larger,
+ * and snaps to centered (pan 0) on an axis where it isn't. `contentW/H` are the
+ * frame's base (zoom-1) size; the function applies the zoom itself.
+ */
+export function clampPan(
+  state: LightboxZoomState,
+  contentW: number,
+  contentH: number,
+  viewW: number,
+  viewH: number,
+): LightboxZoomState {
+  const scaledW = contentW * state.zoom;
+  const scaledH = contentH * state.zoom;
+  const allowedX = Math.max(0, (scaledW - viewW) / 2);
+  const allowedY = Math.max(0, (scaledH - viewH) / 2);
+  return {
+    zoom: state.zoom,
+    panX: Math.max(-allowedX, Math.min(allowedX, state.panX)),
+    panY: Math.max(-allowedY, Math.min(allowedY, state.panY)),
+  };
+}
+
+/** The reset / fit state. */
+export function resetZoom(): LightboxZoomState {
+  return { zoom: 1, panX: 0, panY: 0 };
+}