Serve demo SVG bytes so the live-rendered view stops 404ing the E2E suite (GB-947)

GB-932 renders SVGs as live `<img src="/api/image/:fileId/:side">`, but the synthetic demo file `src/assets/icons.min.svg` exists nowhere on disk or in git, so both sides returned 404. `svg_view_mode` is a server-persisted preference and the E2E suite shares one demo server, so once a spec toggled an SVG to the Rendered view, every later load of the giant SVG (navigation, stability, themes, large-file-perf) emitted a console 404 — which the new failOnPageError fixture then correctly failed on. The fixture didn't cause the breakage; it exposed a real 404.

The difftool blob store already solves the same shape of problem — image bytes for a DB-seeded review with no git refs or working tree to re-read. Generalize it from difftool-only to that whole class:

- Rename `src/difftool/blob-store.ts` to `src/git/image-blobs.ts` with neutral names (`writeImageBlob` / `readImageBlob` / `clearImageBlobs`), since it now backs demo reviews too, not just difftool sessions.
- Add `resolveImageSide()` in the image route: read git / disk first, then fall back to the blob store (used outright for difftool, as a fallback for demo). Both the `:side` and `metadata` routes go through it.
- Seed each demo SVG's old/new bytes into the blob store at setup time, reconstructed from the diff hunks (old drops adds, new drops removes).

Then fix a second failure the 404 had been masking: the large-file-perf specs assert the SVG *code* view (giant-line truncation), but relied on the 'code' default that no longer holds once an earlier spec persists 'rendered' on the shared server. Add `ensureCodeView()` to pin the text view regardless of prior state.

Verified with the CI-parity Docker E2E suite: 149 passed, 0 failed (was 16 failed). Unit tests and the difftool integration suite still pass after the rename.

Author: Brian Westphal

docs/ai/code-summary.md

@@ -99,7 +99,7 @@ How the layer is used:
 | `api/outline.ts` | `/outline/:fileId` and `/symbol-definition` go-to-definition repo scan. |
 | `api/context.ts` | `/context/:fileId` line-range fetch for hunk expansion. |
 | `api/project-settings.ts` | `.glassbox/settings.json` read/write (per-repo `appName`). |
-| `api/image.ts` | Image diff: `/image/:fileId/metadata` and `/image/:fileId/:side` with SVG rasterization. For a difftool review (doc 19) the bytes come from the persisted blob store (`src/difftool/blob-store.ts`) instead of git refs / disk — a difftool session has neither (GB-863). |
+| `api/image.ts` | Image diff: `/image/:fileId/metadata` and `/image/:fileId/:side`; SVGs served as raw `image/svg+xml` for live `<img>` render. `resolveImageSide()` reads from git refs / disk, then falls back to the persisted blob store (`src/git/image-blobs.ts`) — used outright for a difftool review (doc 19, no git/working tree, GB-863) and as a fallback for demo SVGs seeded into the DB with no on-disk file (GB-947). |
 | `api/share-prompt.ts` | Share prompt state / dismiss / tick (uses `global-config.ts`). |
 | `api/system.ts` | `POST /open-external` — opens a validated http(s) URL via `openOS` (same OS-open path as file reveal). |
 | `ai-api.ts` | Router that mounts ai-config + ai-analysis handlers under `/api/ai/*`. |
@@ -332,10 +332,11 @@ path), `GET /poll` (live file list + `active` flag for the client sidebar),
 attached; resolves on session end), `POST /end` ("Done" / tab-close
 `sendBeacon`). Session state + lifecycle live in `src/difftool/session.ts`;
 the detached server is started by `glassbox --difftool-serve`. On append, an
-image/SVG file's raw old/new bytes are persisted by `src/difftool/blob-store.ts`
-(content under `<dataDir>/difftool-blobs/`, keyed by `fileId`+side, cleared on
+image/SVG file's raw old/new bytes are persisted by `src/git/image-blobs.ts`
+(content under `<dataDir>/image-blobs/`, keyed by `fileId`+side, cleared on
 session start + teardown) so the `/image` route can serve them — a difftool
-review has no git refs / working tree to re-read (GB-863).
+review has no git refs / working tree to re-read (GB-863). The same store also
+backs demo SVGs, which are seeded into the DB with no on-disk file (GB-947).
 
 ## 6. Database schema
 

docs/ai/requirements-summary.md

@@ -568,7 +568,7 @@ launcher shim in `--difftool-serve` mode and later invocations append to the
 running session; closing the window kills the sidecar and ends the session
 (`src-tauri/src/lib.rs`). Image/SVG visual comparison works too: the append
 endpoint persists each binary/SVG file's raw bytes to an on-disk blob store
-(`src/difftool/blob-store.ts`, under the session data dir, cleared on teardown)
+(`src/git/image-blobs.ts`, under the session data dir, cleared on teardown)
 and the `/image` route reads from there for a difftool review (GB-863). Internal
 git subprocesses run with `git difftool`'s leaked `GIT_EXTERNAL_DIFF` /
 `GIT_DIFF_PATH_*` scrubbed (`scrubbedGitEnv()` in `src/git/repo.ts`) so Glassbox's

src/cli.ts

@@ -291,15 +291,15 @@ async function main() {
   if (difftoolServe) {
     const { initDifftoolSession } = await import("./difftool/session.js");
     const { writeDiscovery, clearDiscovery, releaseStartingLock } = await import("./git/difftool-discovery.js");
-    const { clearDifftoolBlobs } = await import("./difftool/blob-store.js");
+    const { clearImageBlobs } = await import("./git/image-blobs.js");
     mkdirSync(dataDir, { recursive: true });
     setDataDir(dataDir);
     // Capture as a const so the shutdown closure below sees a non-null string
     // (TS won't narrow the captured `let dataDir`).
     const sessionDataDir = dataDir;
     // Clear any image blobs left by a previous session that was hard-killed
     // (e.g. desktop window force-close) before it could run teardown (GB-863).
-    clearDifftoolBlobs(sessionDataDir);
+    clearImageBlobs(sessionDataDir);
     const repoRoot = process.cwd();
     const review = await createReview(repoRoot, "git difftool", "difftool");
     const { port: actualPort, server } = await startServer(port, review.id, repoRoot, { noOpen, strictPort });
@@ -308,7 +308,7 @@ async function main() {
       repoRoot,
       shutdown: () => {
         try { server.close(); } catch { /* already closing */ }
-        clearDifftoolBlobs(sessionDataDir);
+        clearImageBlobs(sessionDataDir);
         clearDiscovery();
         releaseStartingLock();
         process.exit(0);

src/demo.ts

@@ -1,9 +1,31 @@
 import { saveGuidedReviewConfig } from './ai/config.js';
 import { appendFileScores, createAnalysis, saveUserPreferences, updateAnalysisStatus } from './db/ai-queries.js';
+import { getDataDir } from './db/connection.js';
 import { addAnnotation, addReviewFile, createReview } from './db/queries.js';
 import type { FileDiff } from './git/diff.js';
+import { writeImageBlob } from './git/image-blobs.js';
 import type { ReviewNoteView } from './review-notes/view.js';
 
+/**
+ * The SVG demo files are seeded into the DB, not committed to disk, so the
+ * live-rendered `<img>` view (GB-932) — which fetches `/api/image/:fileId/:side`
+ * — would 404 on the synthetic giant `src/assets/icons.min.svg` (GB-947). The
+ * full bytes of each side live in the diff hunks, so we persist them to the
+ * image-blob store, which the image route serves as a fallback. SVGs are
+ * single-hunk full-file diffs here, so each side is the join of the lines it
+ * keeps (old drops adds; new drops removes).
+ */
+function seedSvgBlobs(fileId: string, diff: FileDiff): void {
+  if (!diff.filePath.toLowerCase().endsWith('.svg')) return;
+  const dataDir = getDataDir();
+  if (dataDir === null) return;
+  const lines = diff.hunks.flatMap(h => h.lines);
+  const sideBytes = (keep: (type: string) => boolean): Buffer =>
+    Buffer.from(lines.filter(l => keep(l.type)).map(l => l.content).join('\n'), 'utf8');
+  writeImageBlob(dataDir, fileId, 'old', sideBytes(t => t !== 'add'));
+  writeImageBlob(dataDir, fileId, 'new', sideBytes(t => t !== 'remove'));
+}
+
 /**
  * Illustrative AI-authored review notes for the demo (docs/20 P2). Demo runs
  * against synthetic, DB-seeded diffs with no on-disk `.pr-notes/`, so the diff
@@ -495,6 +517,7 @@ export async function setupDemoReview(scenario: number): Promise<{ reviewId: str
     };
     const rf = await addReviewFile(review.id, file.path, JSON.stringify(diff));
     fileIdMap.set(file.path, rf.id);
+    seedSvgBlobs(rf.id, diff);
   }
 
   // Common: mark some files as reviewed

src/difftool/blob-store.ts

@@ -0,0 +1,67 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * On-disk storage for the raw image/SVG bytes of a review whose files have no
+ * git refs and no working tree to re-read from.
+ *
+ * The image-comparison routes (`src/routes/api/image.ts`) normally re-fetch a
+ * file's bytes from git or the working tree (`getOldImage`/`getNewImage`). Two
+ * review kinds have neither:
+ *
+ *   - an accumulating `git difftool` session (doc 19 / GB-863), whose files are
+ *     appended with their raw content and no backing refs, and
+ *   - demo mode (GB-947), whose synthetic SVGs (e.g. the giant
+ *     `src/assets/icons.min.svg`) are seeded into the DB with no real file on
+ *     disk — so once an SVG is shown in the live-rendered `<img>` view (GB-932),
+ *     `/api/image/:fileId/:side` would 404.
+ *
+ * For both, we persist the raw old/new bytes here when the file is created, then
+ * read them back to serve the `/image` route. Files live under the review's data
+ * dir and are cleared on difftool-session start + teardown; demo runs use a
+ * fresh per-run tmpdir, so they need no explicit clear.
+ *
+ * Keyed by `fileId`+side rather than content hash: the filename is itself the
+ * lookup key, which avoids a separate fileId→hash mapping. A re-created file
+ * reuses its fileId, so its blobs are overwritten in place.
+ */
+
+function blobDir(dataDir: string): string {
+  return join(dataDir, 'image-blobs');
+}
+
+/** fileIds are base36 (`[a-z0-9]`); strip anything else as belt-and-suspenders
+ *  so the key can never escape the blob directory. */
+function blobName(fileId: string, side: 'old' | 'new'): string {
+  return `${fileId.replace(/[^a-z0-9]/gi, '')}-${side}`;
+}
+
+/** Persist one side's raw bytes for a file. No-op for empty content (the absent
+ *  side of an add/delete). */
+export function writeImageBlob(dataDir: string, fileId: string, side: 'old' | 'new', bytes: Buffer): void {
+  if (bytes.length === 0) return;
+  const dir = blobDir(dataDir);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, blobName(fileId, side)), bytes);
+}
+
+/** Read back a side's bytes, or null if none were stored. */
+export function readImageBlob(dataDir: string, fileId: string, side: 'old' | 'new'): Buffer | null {
+  const path = join(blobDir(dataDir), blobName(fileId, side));
+  if (!existsSync(path)) return null;
+  try {
+    return readFileSync(path);
+  } catch {
+    return null;
+  }
+}
+
+/** Remove every stored blob. Called when a difftool session starts (clear a
+ *  previous session's leftovers, e.g. after a hard kill) and when it ends. */
+export function clearImageBlobs(dataDir: string): void {
+  try {
+    rmSync(blobDir(dataDir), { recursive: true, force: true });
+  } catch {
+    /* best-effort */
+  }
+}

src/git/image-blobs.ts

@@ -2,27 +2,57 @@ import { Hono } from 'hono';
 
 import { getDataDir } from '../../db/connection.js';
 import { getReview, getReviewFile } from '../../db/queries.js';
-import { readDifftoolBlob } from '../../difftool/blob-store.js';
+import type { ReviewMode } from '../../git/diff.js';
 import { parseDiffData, parseModeString } from '../../git/diff.js';
 import type { ImageSide } from '../../git/image.js';
 import { extractMetadata, formatMetadataLines, getContentType, getNewImage, getOldImage } from '../../git/image.js';
+import { readImageBlob } from '../../git/image-blobs.js';
 import type { AppEnv } from '../../types.js';
 import { requirePathParam } from '../../utils/parseBody.js';
 
 export const imageRoutes = new Hono<AppEnv>();
 
 /**
- * A difftool review (doc 19) has no git refs or working tree, so its image bytes
- * come from the blobs persisted at append time (GB-863) rather than
- * `getOldImage`/`getNewImage`. Returns null if nothing was stored for this side.
+ * Read a side's bytes from the on-disk blob store (`src/git/image-blobs.ts`).
+ * Returns null if nothing was stored for this side / there's no data dir.
  */
-function difftoolImageSide(fileId: string, side: 'old' | 'new'): ImageSide | null {
+function blobImageSide(fileId: string, side: 'old' | 'new'): ImageSide | null {
   const dataDir = getDataDir();
   if (dataDir === null) return null;
-  const bytes = readDifftoolBlob(dataDir, fileId, side);
+  const bytes = readImageBlob(dataDir, fileId, side);
   return bytes !== null ? { data: bytes, size: bytes.length } : null;
 }
 
+/**
+ * Resolve one side's image bytes for any review mode, honoring add/delete (the
+ * absent side has no bytes).
+ *
+ * - A difftool review (doc 19) has no git refs or working tree, so its bytes
+ *   come only from the blobs persisted at append time (GB-863).
+ * - Every other mode reads from git / the working tree, but falls back to the
+ *   blob store when that yields nothing — demo mode (GB-947) seeds synthetic
+ *   SVGs that exist nowhere on disk, so the live-rendered `<img>` view (GB-932)
+ *   would otherwise 404.
+ */
+function resolveImageSide(
+  fileId: string,
+  side: 'old' | 'new',
+  status: string,
+  mode: ReviewMode,
+  filePath: string,
+  oldPath: string | null,
+  repoRoot: string,
+  isDifftool: boolean,
+): ImageSide | null {
+  if (side === 'old' && status === 'added') return null;
+  if (side === 'new' && status === 'deleted') return null;
+  if (isDifftool) return blobImageSide(fileId, side);
+  const fromGit = side === 'old'
+    ? getOldImage(mode, filePath, oldPath, repoRoot)
+    : getNewImage(mode, filePath, repoRoot);
+  return fromGit ?? blobImageSide(fileId, side);
+}
+
 // Metadata route must come before the :side wildcard route
 imageRoutes.get('/image/:fileId/metadata', async (c) => {
   const fileIdParam = requirePathParam(c, 'fileId');
@@ -40,12 +70,8 @@ imageRoutes.get('/image/:fileId/metadata', async (c) => {
   const status = diff?.status ?? 'modified';
   const isDifftool = review.mode === 'difftool';
 
-  const oldImage = status === 'added' ? null
-    : isDifftool ? difftoolImageSide(fileIdParam.data, 'old')
-    : getOldImage(mode, file.file_path, oldPath, repoRoot);
-  const newImage = status === 'deleted' ? null
-    : isDifftool ? difftoolImageSide(fileIdParam.data, 'new')
-    : getNewImage(mode, file.file_path, repoRoot);
+  const oldImage = resolveImageSide(fileIdParam.data, 'old', status, mode, file.file_path, oldPath, repoRoot, isDifftool);
+  const newImage = resolveImageSide(fileIdParam.data, 'new', status, mode, file.file_path, oldPath, repoRoot, isDifftool);
 
   const oldMeta = oldImage !== null ? extractMetadata(oldImage.data, oldPath ?? file.file_path) : null;
   const newMeta = newImage !== null ? extractMetadata(newImage.data, file.file_path) : null;
@@ -72,12 +98,12 @@ imageRoutes.get('/image/:fileId/:side', async (c) => {
   const mode = parseModeString(review.mode);
   const diff = parseDiffData(file.diff_data);
   const oldPath: string | null = diff?.oldPath ?? null;
+  const status = diff?.status ?? 'modified';
 
-  const image = review.mode === 'difftool'
-    ? difftoolImageSide(fileIdParam.data, side)
-    : side === 'old'
-      ? getOldImage(mode, file.file_path, oldPath, repoRoot)
-      : getNewImage(mode, file.file_path, repoRoot);
+  const image = resolveImageSide(
+    fileIdParam.data, side, status, mode, file.file_path, oldPath, repoRoot,
+    review.mode === 'difftool',
+  );
 
   if (!image) return c.text('Image not available', 404);
 

src/routes/api/image.ts

@@ -3,7 +3,6 @@ import { Hono } from 'hono';
 import { AppendDifftoolFileReqSchema, RegisterDifftoolReqSchema } from '../api/index.js';
 import { getDataDir } from '../db/connection.js';
 import { addReviewFile, getAnnotationCountsForReview, getReviewFiles, updateFileDiff } from '../db/queries.js';
-import { writeDifftoolBlob } from '../difftool/blob-store.js';
 import {
   addDifftoolHold,
   endDifftoolSession,
@@ -13,6 +12,7 @@ import {
 import { diffRawContent } from '../git/diff.js';
 import { getDifftoolStatus, registerDifftool, unregisterDifftool } from '../git/difftool.js';
 import { isSvgFile } from '../git/image.js';
+import { writeImageBlob } from '../git/image-blobs.js';
 import type { AppEnv } from '../types.js';
 import { errorResponse, parseBody } from '../utils/parseBody.js';
 
@@ -86,8 +86,8 @@ difftoolApiRoutes.post('/append', async (c) => {
   if (diff.isBinary || isSvgFile(diff.filePath)) {
     const dataDir = getDataDir();
     if (dataDir !== null) {
-      writeDifftoolBlob(dataDir, fileId, 'old', oldContent);
-      writeDifftoolBlob(dataDir, fileId, 'new', newContent);
+      writeImageBlob(dataDir, fileId, 'old', oldContent);
+      writeImageBlob(dataDir, fileId, 'new', newContent);
     }
   }
 

src/routes/difftool-api.ts

@@ -30,6 +30,21 @@ async function openFileList(page: import('@playwright/test').Page) {
   await expect(page.locator('#progress-summary')).toHaveText(/files reviewed/, { timeout: 5000 });
 }
 
+/**
+ * Force the SVG *code* (text) view, the subject of these tests. `svg_view_mode`
+ * is a server-persisted preference (see `app.tsx`), and the suite shares one
+ * demo server — so an earlier spec that toggled an SVG to the Rendered view
+ * (e.g. `image-diff.test.ts`) leaves the giant SVG opening as a live `<img>`
+ * with no `.diff-line` rows. Click Code to pin the text view regardless of what
+ * ran before, then wait for the diff rows to (re)render.
+ */
+async function ensureCodeView(page: import('@playwright/test').Page) {
+  const codeToggle = page.locator('[data-svg-mode="code"]');
+  await expect(codeToggle).toBeVisible({ timeout: 5000 });
+  await codeToggle.click();
+  await expect(page.locator('.diff-line').first()).toBeVisible({ timeout: 5000 });
+}
+
 /**
  * Install a Long Tasks observer that accumulates total main-thread blocking
  * time (the sum of every task longer than 50 ms — the browser only reports
@@ -57,7 +72,7 @@ test.describe('Large file performance (GB-821)', () => {
     await page.locator('.file-item .file-name', { hasText: SVG_FILE }).click();
     await expect(page.locator('.diff-view')).toHaveAttribute(
       'data-file-path', new RegExp(SVG_FILE), { timeout: 5000 });
-    await expect(page.locator('.diff-line').first()).toBeVisible({ timeout: 5000 });
+    await ensureCodeView(page);
 
     // Every `.code` cell's rendered text must be bounded — the giant line is
     // never put into the DOM in full. (The fixture builds ~850 KB lines; after
@@ -78,6 +93,12 @@ test.describe('Large file performance (GB-821)', () => {
   test('selecting a large minified SVG does not freeze the main thread', async ({ page }) => {
     await openFileList(page);
 
+    // Pin the SVG code view (server-persisted; a prior spec may have left it on
+    // Rendered) so the timed selection below opens the text diff directly and
+    // the recorder measures code-view layout, not a live-rendered `<img>`.
+    await page.locator('.file-item .file-name', { hasText: SVG_FILE }).click();
+    await ensureCodeView(page);
+
     // Land on a normal file first, so the recorder measures *only* the work of
     // selecting the large SVG — independent of which file the app auto-selects
     // on load.