First specialized renderer landing under RFC #2991 — chat attachment
preview. Adds the dispatch infrastructure that PR-2 (video/audio) and
PR-3 (PDF/text) will extend.
Architecture (RFC #2991 Phase 2 design)
---------------------------------------
- preview-kind.ts: pure helper that maps mimeType (+ extension fallback
for missing/generic MIME) to one of: image | video | audio | pdf |
text | file. Single source of truth; the dispatch axis for every
attachment renderer.
- AttachmentPreview.tsx: SSOT dispatch component. ChatTab no longer
imports kind-specific components — it imports AttachmentPreview,
which switches on the kind and renders the right child.
- AttachmentImage.tsx: inline thumbnail (max 240×180) + click →
lightbox. Auth-aware: for platform URIs (workspace: /
platform-pending: / etc) the bytes are fetched via JS-injected
headers, wrapped in a Blob, served as ObjectURL — bare <img src>
would not include the cookie/token.
- AttachmentLightbox.tsx: shared fullscreen modal (image now; PDF will
use it in PR-3). Esc / backdrop click / X button to close, focus
trap on close button, focus restoration on close.
- AttachmentChip retained as the kind=file fallback. No breaking
change for existing renderable shapes.
External-workspace coverage
---------------------------
The wire shape (ChatAttachment.mimeType + uri) is identical for
internal + external workspaces — both go through AgentMessageWriter
(PR #2949). External claude-code agents that attach images via
send_message_to_user automatically get the new preview surface; no
runtime-side change needed.
Failure modes
-------------
- Fetch failure (404, 403, network) → AttachmentChip fallback so the
user still gets a working download. Pinned by tests.
- Decoded as non-image (corrupt bytes, wrong Content-Type) → onError
on the <img> swaps to AttachmentChip. Pinned by tests.
- Non-platform URIs (http/https external image hosts) → skip the
auth-fetch flow, use the raw URL via resolveAttachmentHref. Pinned
by extension-fallback tests.
Tests
-----
preview-kind.test.ts (49 cases):
- Strict MIME match across image/video/audio/pdf/text/unknown
- Extension fallback when MIME is missing or application/octet-stream
- URL with query string + fragment → strip before parsing
- MIME wins over extension (regression: don't render image-named zip)
- SVG is image (not text) despite being XML
- Non-canonical MIME like application/javascript → text
AttachmentPreview.test.tsx (9 component tests):
- Dispatch: kind=file → chip, kind=image → image path
- Loading state shows placeholder, NOT chip (proves dispatch routed)
- Extension fallback (no mimeType) routes to image path
- Fetch fail (404) and network error → fall back to chip
- Image success: <img> renders ObjectURL, click opens lightbox
- Lightbox: Esc closes, backdrop click closes, content click doesn't
- Universal fallback: unknown MIME → chip even when extension hints
at a renderable kind
Hostile self-review (3 weakest spots, addressed)
------------------------------------------------
1. <img> auth: bare <img src="/chat/download?..."> would NOT include
our auth headers. Resolved via fetch+Blob+ObjectURL pattern.
Pinned by the image-success test (asserts src === "blob:test-url").
2. Server-side allowed-roots mismatch: pre-fix tests used /tmp/ paths
which the server doesn't allow. Caught when the dispatch test
fell into the non-platform path. Updated tests to use /workspace/
subpaths matching templates.go's allowedRoots.
3. Bundle size creep: each kind component adds bytes. Lightbox is
currently always-bundled. Lazy-loading is plausible but defer
until measured-needed.
Verified
- tsc --noEmit clean
- 168 chat tests green (49 unit + 9 component + 110 pre-existing)
PR-2 (video + audio) and PR-3 (PDF + text) extend the dispatch in
AttachmentPreview.tsx with their own kind-specific components.
Refs RFC #2991.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
04f7a07add