Repository navigation
feat(nextjs): sandboxed pdf.js preview on browsers without a PDF viewer - #61
Merged
Merged
Conversation
…a viewer Chrome on Android reports navigator.pdfViewerEnabled === false and can't show a PDF in a frame, so per ADR-0069 phones got only a Download button for the corpus's most common document type. Browsers with a built-in viewer keep the native, unsandboxed frame (ADR-0069, unchanged). Without one, the explorer now draws the PDF with pdf.js (pdfjs-dist 6.4.299, pinned) inside an allow-scripts-only sandboxed iframe with a no-network, no-eval CSP, so untrusted PDF bytes are parsed in an opaque origin, never the app's. The opaque frame can't load the app's module files, so the page fetches pdf.js as text and posts it in with the bytes; the frame imports it from its own blob URLs. Chromium refuses a Worker from a blob in an opaque origin, so pdf.js parses on the frame's main thread. Pages render lazily to canvases; no annotation/text layer, so no live links. pdf.js is only fetched when the fallback runs. webpack emits the two pdf.js files under a .txt name: the production minifier otherwise re-parses the .mjs assets as scripts and fails. ADR-0070 records the decision and amends ADR-0069's third guard; specs/overview.md updated. Verified in the built-in browser against Sepolia data with pdfViewerEnabled forced false: bitcoin.pdf renders inline, at phone width (Android UA), and fullscreen; later pages render on scroll; switching to uniswap-v3-core.pdf re-renders (images included). Blob URLs in the frame are blob:null, i.e. opaque origin. With a native viewer, the old unsandboxed blob frame is used and pdf.js is never fetched. Production static export builds; the emitted pdf.js files are byte-identical to the package's and render from the export. next lint, hardhat lint, check-types, docs:check and the nextjs unit tests pass. Not run on a physical Android device. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Permanence-tier: Ephemeral
Addresses the expert review of the sandboxed pdf.js fallback. - Page count and page size are attacker-chosen, and on Android the sandboxed frame shares the app's main thread. The frame now lays out at most 300 pages (then points to Download) and caps each canvas at 16 MP, so a tiny file claiming 100k pages or a 1x14400 MediaBox can't hang or OOM the tab. - Pages far out of view are cleared (bitmap freed, aspect-ratio keeps the layout) and redrawn when they come back; in-flight renders are cancelled. The observer uses root: document because rootMargin is ignored for the implicit root in a cross-origin frame. - A page-1 render failure now shows the "use Download" message instead of "Loading PDF..." forever; later failures leave that page blank. - The app posts pdf.js and the bytes to each frame once, so a frame that navigates itself can't make it re-post in a loop, and skips the copy if the frame was replaced while pdf.js was fetching. - ADR-0070 no longer overstates the CSP: pdf.js makes no requests, but script that escaped pdf.js could still navigate the frame or use WebRTC; the boundary is the opaque origin, as for the HTML preview. Documents the missing wasm decoders / standard fonts. Verified in the built-in browser with pdfViewerEnabled forced false: ethereum-whitepaper-2014.pdf renders, deep pages render on scroll and page 1 redraws after scrolling back. next lint, hardhat lint, check-types, docs:check, nextjs unit tests and the production build pass. Accepted, not changed: script-src 'unsafe-inline' (no HTML-injection path into the frame; a hash would need build-time sync), the optional @napi-rs/canvas dependency pdfjs-dist pulls in (no install hook, never loaded in the browser build), layout jumps on mixed page sizes, fullscreen re-parsing the PDF. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Reviewed-by: Claude Opus 5.5 <noreply@anthropic.com> Tested-by: Claude Opus 5.5 <noreply@anthropic.com> Permanence-tier: Ephemeral
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
navigator.pdfViewerEnabled === false, e.g. Chrome on Android) now get an inline PDF preview drawn by pdf.js inside a sandboxed iframe, instead of only a Download button.pdfjs-dist6.4.299, pinned exactly (released 2026-10-03; 6.5 was three days old).specs/overview.mdis updated.Why
Chrome for Android can open a PDF full-screen on a top-level navigation (Chrome 135+), but it still can't show one inside a page and reports
pdfViewerEnabled === false. So phones saw no preview for the most common document type in the corpus. James asked for pdf.js where it's needed, with native rendering everywhere else.How it stays isolated (ADR-0056):
sandbox="allow-scripts"with noallow-same-origin, so it has an opaque origin.default-src 'none', scripts inline orblob:only, no eval, no connect.blob:URLs. An opaque origin can't load the app's module files, and Chromium won't start a blob Worker there, so pdf.js parses on the frame's main thread.Build detail: webpack emits the two pdf.js files under a
.txtname. Otherwise the production minifier re-parses the.mjsassets as scripts and the build fails.Known limits (in ADR-0070):
Permanence tier
Ephemeral (client render path). It adds a dependency and amends an ADR, so it is recorded as ADR-0070.
Specs / ADRs touched or checked
specs/overview.md: render-isolation invariant updated.Test plan
Tested in the built-in browser against Sepolia data, with
pdfViewerEnabledforced tofalse:bitcoin.pdfrenders inline, at phone width with an Android UA, and fullscreen.uniswap-v3-core.pdfre-renders, images included.ethereum-whitepaper-2014.pdfrenders with substituted fonts.blob:null/…, which confirms the opaque origin.Other checks:
yarn buildsucceeds, the emitted pdf.js files are byte-identical to the package's, andbitcoin.pdfrenders from the exported site served with an/explorer/*fallback.yarn next:lint,yarn hardhat:lint,yarn next:check-types,yarn docs:checkand the nextjs unit tests (184 pass).Review: an adversarial security review and a correctness review found no P0 or P1 findings. Their P2s are fixed in the second commit:
Accepted P3s are listed in that commit message.
Agents involved
🤖 Generated with Claude Code