feat(attachments): inline PDF preview for application/pdf media blocks

Adds a `pdf` eager viewer contribution on the mime→viewer facet so an
`application/pdf` media block renders an inline, bounded-height preview
instead of the download-only file fallback.

- mediaBlock.ts: PDF_MIME + isPdfMime (case-insensitive exact match).
- mediaViewers.tsx: PdfViewer — a bounded-height <object type="application/pdf">
  of the verified object URL (useAssetObjectUrl, revoked on unmount), with an
  always-visible neutral octet-stream download and a can't-preview fallback
  (e.g. iOS Safari). Fail-closed resolve → the broken-asset placeholder, never
  an unverified source (§5.1/§7.3). Extracted a shared useLazyDownload hook so
  the file fallback and PDF download reuse one octet-stream save path.
- index.ts: register pdfMediaViewer on mediaViewersFacet.

Security: the inline <object> is safe because the Blob's type is pinned to
application/pdf — the mime that selected the viewer — so the browser hands a
known non-text/* type to its PDF viewer and never HTML-sniffs
hash-verified-but-non-PDF bytes into an executable navigation; the download
stays octet-stream (matching the file-fallback posture).

Docs: design.html §11 / §15 / scope / status banner move PDF from vNext to
shipped.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S2J741JwXMwT2wGYNM1j5u

Author: claude

docs/media-attachments/design.html

@@ -97,9 +97,13 @@ <h1>Media attachments</h1>
 (returns verified bytes). Phase 4 = the <code>media</code> block type + property schemas and the
 <code>MediaBlockRenderer</code> (§11, <code>src/attachments/</code>) — it dispatches a block's
 <code>media:mime</code> through a mime→viewer FACET (<code>mediaViewersFacet</code>) that plugins contribute a
-viewer to — one per mime family. An INLINE viewer (image today; PDF/audio later, <code>eager: true</code>)
-gets the bytes resolved once into a verified object URL (fetch → verify → Blob → object URL, revoked on
-unmount) and a fail-closed resolve shows a broken-asset placeholder, never an unverified source. The
+viewer to — one per mime family. An INLINE viewer (image + inline PDF today; audio/video later,
+<code>eager: true</code>) gets the bytes resolved once into a verified object URL (fetch → verify → Blob →
+object URL, revoked on unmount) and a fail-closed resolve shows a broken-asset placeholder, never an
+unverified source. The PDF viewer renders a bounded-height <code>&lt;object type="application/pdf"&gt;</code>
+of that object URL (the Blob's type is pinned to <code>application/pdf</code> by the mime that selected the
+viewer, so a known non-<code>text/*</code> type is handed to the browser's PDF viewer and never HTML-sniffed
+into an executable navigation) with an always-visible neutral octet-stream download. The
 non-image fallback is a LAZY download button: it resolves nothing on mount and, on click, fetches the
 verified bytes and saves them via a transient, immediately-revoked <em>octet-stream</em> anchor — never a
 persistent navigable <code>blob:</code> URL typed with the attacker-influenceable <code>media:mime</code> (a
@@ -121,7 +125,7 @@ <h1>Media attachments</h1>
 deferred</strong> — until it lands, a never-promoted <code>staged</code> orphan and its OPFS bytes are
 retained (never reaped), and a <code>failed</code> upload record is recoverable only by re-paste (no §9
 recovery actor yet).
-Last verified against code 2026-07-01. Treat as current intent. The least-settled part is the byte-lane
+Last verified against code 2026-07-02. Treat as current intent. The least-settled part is the byte-lane
 lifecycle / failure-recovery machinery (§8–§9, §16): the happy path and the crypto / threat model are
 solid; the recovery edges are where the spec is still hardening.
 </aside>
@@ -181,11 +185,12 @@ <h2 id="scope">1. What we're adding, and scope</h2>
   lightbox; offline-first local caching; cross-device sync; correctness under E2EE workspaces.</p>
 
 <p><strong>Built on the image foundation (§11 / §15):</strong> arbitrary non-image files render a
-  download affordance through the same content-addressed resolve + a mime→viewer facet — so a richer
-  inline viewer (PDF preview, <code>&lt;audio&gt;</code>) is a new facet contribution, not a schema change.</p>
+  download affordance through the same content-addressed resolve + a mime→viewer facet, and
+  <code>application/pdf</code> renders an inline bounded-height preview — each a facet contribution, not a
+  schema change, so a further inline viewer (<code>&lt;audio&gt;</code>, video) is the same one-viewer add.</p>
 
-<p><strong>Designed-for but not built (vNext):</strong> those richer inline viewers for non-image mimes
-  (PDF / audio / video); thumbnails / transforms; resumable uploads for large media; public sharing.</p>
+<p><strong>Designed-for but not built (vNext):</strong> inline viewers for the remaining non-image mimes
+  (audio / video); thumbnails / transforms; resumable uploads for large media; public sharing.</p>
 
 <p><strong>Explicitly out of scope:</strong> server-side media features for E2EE workspaces (OCR,
   thumbnails, transcode) — the server has no key; this is the existing E2EE tradeoff
@@ -1231,9 +1236,15 @@ <h2 id="renderer">11. The renderer &amp; capture surfaces</h2>
     type and a <code>priority</code> above the default. It dispatches the block's <code>media:mime</code>
     through a mime→viewer FACET (<code>mediaViewersFacet</code>) that plugins contribute a viewer to — one per
     mime family — so the renderer never special-cases a mime; byte access is <em>per-viewer</em>. An EAGER
-    inline viewer (image via the <code>MarkdownImage</code> lightbox today; PDF/audio later,
-    <code>eager: true</code>) gets the bytes resolved once into the verified object URL the in-thread resolver
-    produces (§7.3, revoked on unmount). The non-image fallback is <strong>LAZY</strong> — a metadata-only
+    inline viewer (<code>eager: true</code>) gets the bytes resolved once into the verified object URL the
+    in-thread resolver produces (§7.3, revoked on unmount): today the <code>image</code> viewer feeds it to the
+    <code>MarkdownImage</code> lightbox and the <code>pdf</code> viewer renders it in a bounded-height
+    <code>&lt;object type="application/pdf"&gt;</code> (audio/video later). The PDF <code>&lt;object&gt;</code>
+    is safe because the object URL's Blob type is pinned to <code>application/pdf</code> — the very mime that
+    selected the viewer — so the browser hands a known non-<code>text/*</code> type to its PDF viewer and never
+    HTML-sniffs hash-verified-but-non-PDF bytes into an executable navigation; its download affordance (and the
+    <code>&lt;object&gt;</code> can't-preview fallback, e.g. iOS Safari) reuses the same neutral octet-stream
+    path as the fallback below. The non-image fallback is <strong>LAZY</strong> — a metadata-only
     download button that resolves the verified bytes only on click and saves them through a transient,
     immediately-revoked <em>octet-stream</em> anchor, <em>not</em> a persistent navigable <code>blob:</code>
     URL typed with the attacker-controlled <code>media:mime</code> (that would be same-origin XSS on
@@ -1465,7 +1476,10 @@ <h2 id="plan">15. Phased plan</h2>
       <code>mediaViewersFacet</code> registry: an EAGER image viewer contribution resolves the verified
       object URL for the lightbox; the built-in fallback is a LAZY, metadata-only download button that
       resolves on click and saves via a transient octet-stream anchor (filename/size from metadata). External
-      <code>![](url)</code> images keep the existing <code>MarkdownImage</code>, §11.</td></tr>
+      <code>![](url)</code> images keep the existing <code>MarkdownImage</code>, §11. A second EAGER
+      contribution — the <code>pdf</code> viewer — landed on this foundation with no renderer change: a
+      bounded-height <code>&lt;object type="application/pdf"&gt;</code> of the object URL + a neutral
+      octet-stream download (and a can't-preview fallback), §11.</td></tr>
 <tr><td>5 — capture + up-lane</td>
     <td>paste / drop / file-pick arms (through <code>pasteDecisionVerb</code>); deterministic content-derived
       block id via <code>createOrRestoreTargetBlock</code> (dedup is automatic, §11); optimistic write to the durable byte
@@ -1477,7 +1491,7 @@ <h2 id="plan">15. Phased plan</h2>
       <em>budget</em> / active-workspace <em>scope</em> / <em>politeness</em> controls; and
       <code>navigator.storage.persist()</code> so the byte store isn't best-effort-evicted.</td></tr>
 <tr><td>vNext</td>
-    <td>richer inline viewers for non-image mimes (PDF preview, <code>&lt;audio&gt;</code>, video) atop the
+    <td>inline viewers for the remaining non-image mimes (<code>&lt;audio&gt;</code>, video) atop the
       §11 <code>mediaViewersFacet</code>; thumbnails / transforms; resumable upload; the
       <code>effective_share_ids</code> storage-RLS branch when subtree sharing ships; public-share
       (export / key-in-fragment).</td></tr>

src/plugins/attachments/MediaBlockRenderer.test.tsx

@@ -30,11 +30,12 @@ vi.mock('./useAssetObjectUrl.js', () => ({
 }))
 vi.mock('./assetResolver.js', () => ({ getAssetResolver: () => ({ resolve: h.resolve }) }))
 vi.mock('@/utils/downloadBlob.js', () => ({ downloadBlob: h.downloadBlob }))
-// The runtime resolves the media-viewer facet to just the (real) image viewer, so an
-// image mime dispatches to ImageViewer and everything else to the download fallback.
+// The runtime resolves the media-viewer facet to the (real) image + PDF viewers, so an
+// image mime dispatches to ImageViewer, application/pdf to PdfViewer, and everything
+// else to the download fallback.
 vi.mock('@/extensions/runtimeContext.js', async () => {
-  const { imageMediaViewer } = await import('./mediaViewers.js')
-  return { useAppRuntime: () => ({ read: () => [imageMediaViewer] }) }
+  const { imageMediaViewer, pdfMediaViewer } = await import('./mediaViewers.js')
+  return { useAppRuntime: () => ({ read: () => [imageMediaViewer, pdfMediaViewer] }) }
 })
 
 const { MediaBlockRenderer, MediaContentRenderer } = await import('./MediaBlockRenderer.js')
@@ -91,8 +92,10 @@ describe('MediaContentRenderer — image branch', () => {
 })
 
 describe('MediaContentRenderer — non-image (file) branch', () => {
+  // A mime claimed by NO registered viewer (not image/*, not application/pdf) so it hits
+  // the download fallback — PDF now has its own inline viewer, so it can't stand in here.
   const fileProps = (extra: Record<string, unknown> = {}) => {
-    h.props = { 'media:hash': 'sha256:ab', 'media:mime': 'application/pdf', 'media:filename': 'doc.pdf', ...extra }
+    h.props = { 'media:hash': 'sha256:ab', 'media:mime': 'application/zip', 'media:filename': 'doc.zip', ...extra }
   }
 
   it('renders a METADATA-ONLY download button — no eager resolve — for a non-image MIME', () => {
@@ -101,7 +104,7 @@ describe('MediaContentRenderer — non-image (file) branch', () => {
     renderContent()
     const btn = screen.getByTestId('media-file')
     expect(btn.tagName).toBe('BUTTON')
-    expect(btn).toHaveTextContent('doc.pdf')
+    expect(btn).toHaveTextContent('doc.zip')
     expect(btn).toHaveTextContent('2 MB')
     expect(screen.queryByRole('img')).toBeNull() // not the image lightbox
     // The download fallback is LAZY: the renderer must gate the eager resolve OFF for it,
@@ -116,7 +119,7 @@ describe('MediaContentRenderer — non-image (file) branch', () => {
     fireEvent.click(screen.getByTestId('media-file'))
     await waitFor(() => expect(h.downloadBlob).toHaveBeenCalledTimes(1))
     const [blob, name] = h.downloadBlob.mock.calls[0]
-    expect(name).toBe('doc.pdf')
+    expect(name).toBe('doc.zip')
     // NEVER the attacker-influenceable media:mime — a neutral type so a navigated blob URL
     // downloads instead of rendering (no same-origin XSS via media:mime = text/html).
     expect(blob.type).toBe('application/octet-stream')
@@ -146,6 +149,65 @@ describe('MediaContentRenderer — non-image (file) branch', () => {
   })
 })
 
+describe('MediaContentRenderer — PDF branch', () => {
+  const pdfProps = (extra: Record<string, unknown> = {}) => {
+    h.props = { 'media:hash': 'sha256:ab', 'media:mime': 'application/pdf', 'media:filename': 'doc.pdf', ...extra }
+  }
+
+  it('renders a bounded inline <object> of the VERIFIED object URL, typed application/pdf', () => {
+    pdfProps()
+    h.urlState = { status: 'ready', url: 'blob:pdf/1' }
+    const { container } = renderContent()
+    expect(screen.getByTestId('media-pdf')).toBeInTheDocument()
+    const object = container.querySelector('object')
+    expect(object).toHaveAttribute('data', 'blob:pdf/1')
+    // Pinned to application/pdf so the browser hands it to its PDF viewer, never HTML-sniffs it.
+    expect(object).toHaveAttribute('type', 'application/pdf')
+    // The PDF viewer is EAGER: the renderer resolves the object URL up front for the inline preview.
+    expect(h.useAssetObjectUrl).toHaveBeenCalledWith(expect.anything(), expect.anything(), { enabled: true })
+  })
+
+  it('shows the loading placeholder while resolving', () => {
+    pdfProps()
+    h.urlState = { status: 'loading' }
+    renderContent()
+    expect(screen.getByTestId('media-loading')).toBeInTheDocument()
+  })
+
+  it('shows the broken-asset placeholder (and NO object) on a fail-closed resolve', () => {
+    pdfProps()
+    h.urlState = { status: 'error', reason: 'hash-mismatch' }
+    const { container } = renderContent()
+    expect(screen.getByTestId('media-broken')).toBeInTheDocument()
+    // The load-bearing assertion: nothing is ever served for an unverified asset.
+    expect(container.querySelector('object')).toBeNull()
+  })
+
+  it('downloads the VERIFIED bytes as a NEUTRAL octet-stream blob on the download click', async () => {
+    pdfProps()
+    h.urlState = { status: 'ready', url: 'blob:pdf/1' }
+    renderContent()
+    fireEvent.click(screen.getByTestId('media-pdf-download'))
+    await waitFor(() => expect(h.downloadBlob).toHaveBeenCalledTimes(1))
+    const [blob, name] = h.downloadBlob.mock.calls[0]
+    expect(name).toBe('doc.pdf')
+    // NEVER a navigable blob typed with the attacker-influenceable media:mime.
+    expect(blob.type).toBe('application/octet-stream')
+  })
+
+  it('fails the download closed on a failed resolve — nothing downloaded, retryable', async () => {
+    pdfProps()
+    h.urlState = { status: 'ready', url: 'blob:pdf/1' }
+    h.resolve.mockResolvedValue({ ok: false, reason: 'fetch-failed' })
+    renderContent()
+    const btn = screen.getByTestId('media-pdf-download')
+    fireEvent.click(btn)
+    await waitFor(() => expect(btn).toHaveTextContent('Retry'))
+    expect(h.downloadBlob).not.toHaveBeenCalled()
+    expect(btn).toBeEnabled() // still clickable to retry a transient failure
+  })
+})
+
 describe('MediaBlockRenderer.canRender', () => {
   // canRender must gate on a LOADED snapshot via peek() — `block.hasType()` reads
   // block.data, which THROWS for a not-yet-loaded / missing row, and useRenderer

src/plugins/attachments/index.ts

@@ -17,7 +17,7 @@ import { systemToggle } from '@/facets/togglable.js'
 import { diagnosticsFacet } from '@/plugins/diagnostics/facet.js'
 import { mobileKeyboardToolbarItemsFacet } from '@/plugins/mobile-keyboard-toolbar/facet.js'
 import { MediaBlockRenderer } from './MediaBlockRenderer.js'
-import { imageMediaViewer } from './mediaViewers.js'
+import { imageMediaViewer, pdfMediaViewer } from './mediaViewers.js'
 import { mediaViewersFacet } from './mediaViewersFacet.js'
 import { MediaDownLaneReplicator } from './MediaDownLaneReplicator.js'
 import { MediaUploadReconciler } from './MediaUploadReconciler.js'
@@ -43,9 +43,11 @@ export const attachmentsPlugin: AppExtension = systemToggle({
   typesFacet.of(ASSETS_TYPE_CONTRIBUTION, { source: 'attachments' }),
   MEDIA_PROPERTY_SCHEMAS.map((schema) => propertySchemasFacet.of(schema, { source: 'attachments' })),
   blockRenderersFacet.of({ id: 'media', renderer: MediaBlockRenderer }, { source: 'attachments' }),
-  // The image mime-family viewer. A PDF / audio / video plugin registers its own viewer
-  // on this facet (eager: true) and the renderer dispatches to it — no renderer change.
+  // The mime-family viewers. Each is an eager inline viewer; the renderer dispatches by
+  // mime over the facet (no renderer change per mime). An audio / video plugin registers
+  // its own viewer here the same way.
   mediaViewersFacet.of(imageMediaViewer, { source: 'attachments' }),
+  mediaViewersFacet.of(pdfMediaViewer, { source: 'attachments' }),
   // The capture path: DECIDE a file paste is media (decorator) + ACT on it (the
   // captureMediaVerb impl). Both gated here, so disabling the plugin disables capture
   // (a file paste falls through to a text paste, and the verb is a no-op).

src/plugins/attachments/mediaBlock.test.ts

@@ -4,6 +4,7 @@ import {
   MEDIA_TYPE,
   MEDIA_TYPE_CONTRIBUTION,
   isImageMime,
+  isPdfMime,
   mediaHashProp,
   resolveCaptureMime,
   sniffImageMime,
@@ -33,6 +34,17 @@ describe('isImageMime', () => {
   })
 })
 
+describe('isPdfMime', () => {
+  it('is true only for application/pdf, case-insensitively', () => {
+    expect(isPdfMime('application/pdf')).toBe(true)
+    expect(isPdfMime('APPLICATION/PDF')).toBe(true)
+    expect(isPdfMime('image/png')).toBe(false)
+    expect(isPdfMime('application/x-pdf')).toBe(false) // not the registered type
+    expect(isPdfMime('')).toBe(false)
+    expect(isPdfMime(undefined)).toBe(false)
+  })
+})
+
 describe('sniffImageMime', () => {
   it('recognizes common raster image magic, null otherwise', () => {
     expect(sniffImageMime(png())).toBe('image/png')

src/plugins/attachments/mediaBlock.ts

@@ -69,6 +69,14 @@ export const MEDIA_TYPE_CONTRIBUTION: TypeContribution = defineBlockType({
 export const isImageMime = (mime: string | undefined): boolean =>
   typeof mime === 'string' && mime.toLowerCase().startsWith('image/')
 
+/** The PDF MIME — its inline-preview viewer (§11 PDF branch). */
+export const PDF_MIME = 'application/pdf'
+
+/** Does a MIME type render as an inline PDF (§11 PDF branch)? Case-insensitive per
+ *  RFC 2045; an exact match — `application/pdf` has no sub-family the way `image/*` does. */
+export const isPdfMime = (mime: string | undefined): boolean =>
+  typeof mime === 'string' && mime.toLowerCase() === PDF_MIME
+
 /** The fallback MIME for a file with no declared type. */
 export const GENERIC_MIME = 'application/octet-stream'
 

src/plugins/attachments/mediaViewers.test.tsx

@@ -1,24 +1,17 @@
 import { describe, expect, it } from 'vitest'
-import { FILE_VIEWER_FALLBACK, formatByteSize, imageMediaViewer, pickMediaViewer } from './mediaViewers.js'
-import type { MediaViewerContribution } from './mediaViewersFacet.js'
-
-const fakePdf: MediaViewerContribution = {
-  id: 'pdf',
-  match: (m) => m === 'application/pdf',
-  Component: () => null,
-  eager: true,
-}
+import { FILE_VIEWER_FALLBACK, formatByteSize, imageMediaViewer, pdfMediaViewer, pickMediaViewer } from './mediaViewers.js'
 
 describe('pickMediaViewer', () => {
   it('returns the first viewer whose match() accepts the mime (list is precedence-ordered)', () => {
-    const viewers = [imageMediaViewer, fakePdf]
+    const viewers = [imageMediaViewer, pdfMediaViewer]
     expect(pickMediaViewer(viewers, 'image/png')).toBe(imageMediaViewer)
     expect(pickMediaViewer(viewers, 'IMAGE/PNG')).toBe(imageMediaViewer) // MIME is case-insensitive (RFC 2045)
-    expect(pickMediaViewer(viewers, 'application/pdf')).toBe(fakePdf)
+    expect(pickMediaViewer(viewers, 'application/pdf')).toBe(pdfMediaViewer)
+    expect(pickMediaViewer(viewers, 'APPLICATION/PDF')).toBe(pdfMediaViewer) // case-insensitive too
   })
 
   it('falls back to the download viewer when no registered viewer claims the mime', () => {
-    expect(pickMediaViewer([imageMediaViewer], 'audio/mpeg')).toBe(FILE_VIEWER_FALLBACK)
+    expect(pickMediaViewer([imageMediaViewer, pdfMediaViewer], 'audio/mpeg')).toBe(FILE_VIEWER_FALLBACK)
     // Empty facet → still downloadable (the fallback is a hardcoded floor, not a contribution).
     expect(pickMediaViewer([], 'application/pdf')).toBe(FILE_VIEWER_FALLBACK)
   })