fix(images): deterministic host image paths to stop screenshot churn (#43)

Agent output references the same artifact through volatile `src` forms — a
relative `artifacts/…` path, a container absolute path
(`/opt/cursor/artifacts/…`), a repo/directory-named path
(`/home/user/<repo>/artifacts/…`), or a per-session download URL
(`…/v1/agents/<id>/artifacts/download?path=artifacts/…`). The host-injectable
image refactor dropped the normalization the old `artifact-images.ts` did, so
the host renderer now echoes `src` verbatim into `data-host-image-path`. Those
volatile segments (container dir, repo name, directory layout, session id) then
leak into the rendered DOM and churn the downstream e2e screenshots every time
the environment differs.

Restore determinism as a generic, app-agnostic primitive:

- Add `normalizeHostImagePath(src, { rootMarker })` — strips any leading
  absolute/dir prefix down to the marker segment (default `artifacts`), prefers a
  URL's `?path=` param, returns volatile query params separately, and rejects
  path traversal. No host path is hardcoded, keeping the core decoupled.
- Route the host-image test policy through it and render only the stable path.
- Regression test proving five volatile forms of one artifact collapse to a
  single identical placeholder and no session id leaks.

Hosts should call `normalizeHostImagePath(src).path` and keep volatile query
params out of any snapshot-visible attribute.


Claude-Session: https://claude.ai/code/session_01U5XyfYm8fojvk9USphcx4E

Co-authored-by: Claude <noreply@anthropic.com>

Author: jonathanKingston

docs/ARCHITECTURE.md

@@ -60,6 +60,18 @@ When extending the renderer or its CSS, preserve these rules:
     `<img>` becomes (e.g. an app's artifact placeholder). The core escapes every
     `<img>` by default; the renderer's output bypasses escaping via a placeholder and
     is restored afterward.
+  - `normalizeHostImagePath` (`raw-images.ts`) — determinism primitive for that renderer.
+    Agent output references the same artifact through volatile `src` forms — a relative
+    `artifacts/…` path, a container absolute path (`/opt/cursor/artifacts/…`), a
+    repo/directory-named path (`/home/user/<repo>/artifacts/…`), or a per-session download
+    URL (`…/v1/agents/<id>/artifacts/download?path=artifacts/…`). Left verbatim in the
+    rendered attribute, those volatile segments (container dir, repo name, directory layout,
+    session id) change per run and churn the host's e2e **screenshots**. This collapses each
+    to the same stable `artifacts/…` path (marker segment configurable; no host path is
+    hardcoded) and keeps URL query params out of the path, so a host that renders
+    `normalizeHostImagePath(src).path` gets identical output across machines. Hosts should
+    route their artifact `<img>` through it and never fold volatile query params into a
+    snapshot-visible attribute.
   - `setSanitizeExtension` (`sanitize.ts`) — widens the sanitizer allowlist and adds a
     per-element gate so a host's injected markup (e.g. its artifact `<img>`) survives
     sanitization. The core allowlist stays the security gate; keep additions narrow.

src/host-image-path.test.ts

@@ -0,0 +1,85 @@
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+import { normalizeHostImagePath } from './raw-images.ts'
+import { withHostImagePolicy } from '../tests/host-image-test-policy.ts'
+import { renderMarkdown } from './renderer.ts'
+
+describe('normalizeHostImagePath — screenshot determinism (#churn)', () => {
+  it('leaves an already-relative artifacts path unchanged', () => {
+    assert.deepEqual(normalizeHostImagePath('artifacts/screenshots/x.png'), {
+      path: 'artifacts/screenshots/x.png',
+    })
+  })
+
+  it('strips a container absolute prefix down to the root marker', () => {
+    assert.deepEqual(normalizeHostImagePath('/opt/cursor/artifacts/screenshots/x.png'), {
+      path: 'artifacts/screenshots/x.png',
+    })
+  })
+
+  it('strips a repo/directory-named prefix so repo names never leak', () => {
+    assert.deepEqual(normalizeHostImagePath('/home/user/some-repo/artifacts/screenshots/x.png'), {
+      path: 'artifacts/screenshots/x.png',
+    })
+  })
+
+  it('collapses every volatile form of the same artifact to one identical path', () => {
+    const forms = [
+      'artifacts/screenshots/x.png',
+      '/opt/cursor/artifacts/screenshots/x.png',
+      '/home/user/some-repo/artifacts/screenshots/x.png',
+      '/tmp/build-9f3a/checkout/artifacts/screenshots/x.png',
+      'https://host.example/v1/agents/session-abc123/artifacts/download?path=artifacts/screenshots/x.png',
+    ]
+    const paths = new Set(forms.map((src) => normalizeHostImagePath(src)?.path))
+    assert.deepEqual([...paths], ['artifacts/screenshots/x.png'])
+  })
+
+  it('keeps a URL session id out of the stable path (in params, not the rendered attribute)', () => {
+    const normalized = normalizeHostImagePath(
+      'https://host.example/v1/agents/session-abc123/artifacts/download?path=artifacts/screenshots/x.png&token=xyz',
+    )
+    assert.equal(normalized?.path, 'artifacts/screenshots/x.png')
+    // Volatile bits are surfaced separately, never folded into `path`.
+    assert.deepEqual(normalized?.params, { token: 'xyz' })
+    assert.doesNotMatch(normalized?.path ?? '', /session-abc123/)
+  })
+
+  it('accepts a caller-supplied root marker (no host path is hardcoded in core)', () => {
+    assert.deepEqual(normalizeHostImagePath('/srv/data/uploads/a/b.png', { rootMarker: 'uploads' }), {
+      path: 'uploads/a/b.png',
+    })
+  })
+
+  it('returns null when the marker is absent (host falls through to escaping)', () => {
+    assert.equal(normalizeHostImagePath('/etc/passwd'), null)
+    assert.equal(normalizeHostImagePath('https://host.example/logo.png'), null)
+    assert.equal(normalizeHostImagePath(''), null)
+  })
+
+  it('rejects path traversal that would escape the root', () => {
+    assert.equal(normalizeHostImagePath('artifacts/../../etc/passwd'), null)
+  })
+})
+
+describe('host image policy renders volatile srcs to one stable placeholder', () => {
+  it('renders the container-absolute and relative forms identically', () => {
+    withHostImagePolicy(() => {
+      const abs = renderMarkdown('<img alt="shot" src="/opt/cursor/artifacts/screenshots/x.png" />')
+      const rel = renderMarkdown('<img alt="shot" src="artifacts/screenshots/x.png" />')
+      assert.equal(abs, rel)
+      assert.match(abs, /data-host-image-path="artifacts\/screenshots\/x\.png"/)
+    })
+  })
+
+  it('renders the download-URL form identically and never leaks the session id', () => {
+    withHostImagePolicy(() => {
+      const url = renderMarkdown(
+        '<img alt="shot" src="https://host.example/v1/agents/session-abc123/artifacts/download?path=artifacts/screenshots/x.png" />',
+      )
+      const rel = renderMarkdown('<img alt="shot" src="artifacts/screenshots/x.png" />')
+      assert.equal(url, rel)
+      assert.doesNotMatch(url, /session-abc123/)
+    })
+  })
+})

src/index.ts

@@ -24,7 +24,14 @@ export {
 // `@copse/streaming-markdown/sanitizers/dompurify` entry so it is only bundled
 // when a host explicitly opts in.
 export { browserSanitizerBackend, isBrowserSanitizerSupported } from './sanitize-browser.ts'
-export { setRawImageRenderer, type RawImageRenderer, type RawImageTag } from './raw-images.ts'
+export {
+  setRawImageRenderer,
+  normalizeHostImagePath,
+  type RawImageRenderer,
+  type RawImageTag,
+  type NormalizedImagePath,
+  type NormalizeImagePathOptions,
+} from './raw-images.ts'
 export { escapeHtml, escapeHtmlTextNodes, decodeSafeMarkdownEntities } from './escape.ts'
 // Syntax highlighting is a pluggable backend. The core (`highlight.ts`) carries
 // no highlight.js code and renders escaped plain text until a backend is

src/raw-images.ts

@@ -80,3 +80,104 @@ export function restoreRawImages(text: string, images: readonly string[]): strin
   if (images.length === 0) return text
   return text.replace(PLACEHOLDER_RE, (_match, index: string) => images[Number(index)] ?? '')
 }
+
+/** A host image `src` reduced to a stable, machine-independent form. */
+export interface NormalizedImagePath {
+  /**
+   * The image path relative to (and including) the root marker segment, e.g.
+   * `artifacts/screenshots/x.png`. Deterministic across machines: any leading
+   * absolute/container/repo directory prefix is stripped.
+   */
+  path: string
+  /**
+   * Query params carried by a URL `src` (e.g. a per-session agent id). These are
+   * volatile and MUST be kept out of any attribute that ends up in a rendered
+   * snapshot/screenshot — surface them separately (or use them only at fetch
+   * time) so they can't churn the committed image. Omitted when the `src` was a
+   * plain path with no query string.
+   */
+  params?: Record<string, string>
+}
+
+export interface NormalizeImagePathOptions {
+  /**
+   * The path segment that anchors the stable relative path. Everything before the
+   * first occurrence of this segment is discarded; the segment and everything
+   * after it are kept. Defaults to `'artifacts'`.
+   */
+  rootMarker?: string
+}
+
+/**
+ * Reduce a raw image `src` to a stable, machine-independent {@link NormalizedImagePath},
+ * or `null` when it does not contain the root marker (host should then fall through
+ * to escaping). This is the determinism primitive behind screenshot churn: agent
+ * output references the same artifact through volatile forms —
+ *
+ *   - `artifacts/screenshots/x.png`                              (already relative)
+ *   - `/opt/cursor/artifacts/screenshots/x.png`                 (container abs path)
+ *   - `/home/user/some-repo/artifacts/screenshots/x.png`        (repo/dir names leak)
+ *   - `https://host/v1/agents/<session>/artifacts/download?path=artifacts/screenshots/x.png`
+ *
+ * — all of which must render identically. This collapses each to the same
+ * `artifacts/screenshots/x.png` so the rendered DOM (and any screenshot of it) stops
+ * changing when the container dir, repo name, directory layout, or session id changes.
+ *
+ * The core stays app-agnostic: no host path is hardcoded — the anchor segment is the
+ * caller-supplied {@link NormalizeImagePathOptions.rootMarker}. Path traversal
+ * (`..`) is rejected as a safety measure.
+ */
+export function normalizeHostImagePath(
+  rawSrc: string,
+  options: NormalizeImagePathOptions = {},
+): NormalizedImagePath | null {
+  const rootMarker = options.rootMarker ?? 'artifacts'
+  const src = rawSrc.trim()
+  if (!src) return null
+
+  let candidate = src
+  let params: Record<string, string> | undefined
+
+  // A URL src carries the stable path in its `?path=` query param (the URL's own
+  // pathname holds a volatile per-session id); prefer it. Other query params are
+  // returned separately so the host keeps them out of snapshot-visible attributes.
+  const url = tryParseUrl(src)
+  if (url) {
+    const pathParam = url.searchParams.get('path')
+    candidate = pathParam ?? url.pathname
+    const rest: Record<string, string> = {}
+    for (const [key, value] of url.searchParams) {
+      if (key === 'path') continue
+      rest[key] = value
+    }
+    if (Object.keys(rest).length > 0) params = rest
+  }
+
+  const path = stableRelativePath(candidate, rootMarker)
+  if (path == null) return null
+  return params ? { path, params } : { path }
+}
+
+function tryParseUrl(src: string): URL | null {
+  // Only absolute URLs (with a scheme) are URLs here; bare paths must not be
+  // coerced (no base is supplied), so `new URL(src)` naturally rejects them.
+  try {
+    return new URL(src)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Keep the `rootMarker` segment and everything after it, discarding any leading
+ * directory prefix. Returns `null` if the marker is absent or a `..` segment would
+ * escape the root.
+ */
+function stableRelativePath(rawPath: string, rootMarker: string): string | null {
+  const segments = rawPath.split('/').filter((segment) => segment !== '' && segment !== '.')
+  const start = segments.indexOf(rootMarker)
+  if (start === -1) return null
+  const kept = segments.slice(start)
+  if (kept.includes('..')) return null
+  return kept.join('/')
+}

tests/host-image-test-policy.ts

@@ -2,19 +2,30 @@
 // core renderer escapes raw `<img>` and allows none through the sanitizer. This
 // fixture simulates a host (the real policy lives in the consuming app) so the
 // injection surface — `setRawImageRenderer` + `setSanitizeExtension` — can be
-// exercised. Only an `<img>` whose `src` starts with `artifacts/` becomes a
-// locked-down, src-less placeholder; everything else falls through to escaping.
-import { setRawImageRenderer, type RawImageTag } from '../src/raw-images.ts'
+// exercised. An `<img>` whose `src` resolves (via `normalizeHostImagePath`) to a
+// stable `artifacts/…` path becomes a locked-down, src-less placeholder; every
+// other tag falls through to escaping.
+//
+// The renderer normalizes the path so volatile prefixes — a container abs path
+// (`/opt/cursor/artifacts/…`), a repo/dir name (`/home/user/<repo>/artifacts/…`),
+// or a per-session download URL — all collapse to the same
+// `data-host-image-path`. That determinism is what stops the rendered DOM (and
+// any screenshot of it) from churning when those environment details change.
+import { setRawImageRenderer, normalizeHostImagePath, type RawImageTag } from '../src/raw-images.ts'
 import { setSanitizeExtension } from '../src/sanitize.ts'
 import { escapeHtml } from '../src/escape.ts'
 
 const HOST_IMAGE_CLASS = 'host-image'
 
 function hostImageRenderer({ attrs }: RawImageTag): string | null {
   const src = attrs['src']
-  if (!src || !src.startsWith('artifacts/')) return null
+  if (!src) return null
+  const normalized = normalizeHostImagePath(src)
+  if (!normalized) return null
   const alt = escapeHtml(attrs['alt'] ?? '')
-  return `<img class="${HOST_IMAGE_CLASS}" data-host-image-path="${escapeHtml(src)}" alt="${alt}" loading="lazy">`
+  // Only the stable relative path reaches the rendered attribute; the volatile
+  // query params (e.g. a session id) stay out of anything a screenshot captures.
+  return `<img class="${HOST_IMAGE_CLASS}" data-host-image-path="${escapeHtml(normalized.path)}" alt="${alt}" loading="lazy">`
 }
 
 const hostImageSanitize = {