Draftable-style interactive visual diffs for PDFs, fully offline, integrated into VS Code's Git diff workflow.
Features
Side-by-side PDF comparison — shows the original (left) and modified (right) PDF pages next to each other
Red/green diff overlays — highlights changed regions directly on the PDF pages (Draftable-style)
Synced scrolling — both panels scroll together (toggleable)
Git-aware — compares the same versions VS Code uses for its diffs:
Working tree vs HEAD
Staged vs HEAD
Change navigation — jump between changed pages with Prev/Next buttons
Change list panel — sidebar listing all pages with differences
Zoom controls — zoom in/out/fit for detailed inspection
Keyboard shortcuts — arrow keys for pages, Ctrl+arrows for changes, Ctrl+/-/0 for zoom
Fully offline — no cloud services, no uploads, everything runs locally
How to Use
From Source Control (Primary workflow)
Open the Source Control view (Ctrl+Shift+G / Cmd+Shift+G)
Find a changed .pdf file in Changes or Staged Changes
Right-click the PDF file
Select "Open Visual PDF Diff"
This compares the PDF against HEAD using the same context as VS Code's built-in diff.
From Explorer
Right-click any .pdf file in the Explorer
Select "Compare PDF with HEAD"
This compares the current file on disk with the last committed version.
From Command Palette
Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
Search for "PDF Diff: Open Visual PDF Diff" or "PDF Diff: Compare PDF with HEAD"
Controls
Control
Action
← / PageUp
Previous page
→ / PageDown
Next page
Ctrl+↑
Previous changed page
Ctrl+↓
Next changed page
Ctrl++
Zoom in
Ctrl+-
Zoom out
Ctrl+0
Reset zoom to 100%
Overlay checkbox
Toggle diff highlighting
Sync Scroll checkbox
Toggle synchronized scrolling
Configuration
Setting
Default
Description
pdfVisualDiff.renderScale
1.5
PDF rendering scale (0.5–4.0). Higher = better quality, more memory
pdfVisualDiff.diffThreshold
0.1
Pixel color difference threshold (0 = exact, 1 = lenient). Increase to ignore minor rendering differences
pdfVisualDiff.maxFileSizeMB
50
Warning threshold for large PDFs (MB)
pdfVisualDiff.syncScroll
true
Enable synchronized scrolling by default
pdfVisualDiff.overlayOpacity
0.35
Diff overlay opacity (0.05–1.0)
Setup / Development
Prerequisites
VS Code 1.85.0 or later
Git installed and accessible
Node.js 18+ (for building from source)
Building from Source
# Clone the repository
git clone <repo-url>
cd pdf-visual-diff
# Install dependencies
npm install
# Build the extension
npm run compile
# Or watch for changes during development
npm run watch
Running in Development
Open this folder in VS Code
Press F5 to launch the Extension Development Host
In the new VS Code window, open a Git repository with PDF files
Make changes to a PDF, then use the Source Control view to diff
Packaging
npm run package
# This creates a .vsix file you can install with:
# code --install-extension pdf-visual-diff-0.1.0.vsix
How It Works
Technical Architecture
Git Integration — Uses VS Code's built-in Git extension API to find repositories and the git show command (via child_process) to extract binary-safe PDF content at specific refs (HEAD, staged index, etc.)
PDF Rendering — Mozilla's PDF.js renders each page to <canvas> elements inside a VS Code webview. PDF.js is bundled with the extension for fully offline operation.
Diff Computation — pixelmatch performs fast pixel-level image comparison between rendered page pairs. Changed pixels are identified using perceptual color metrics with anti-aliasing detection.
Overlay Rendering — Diff results are drawn as semi-transparent colored overlays on the right-side pages:
Red — pixels that changed
Green — pixels present only in the modified version (added pages)
Pages with no differences show no overlay
Why Pixel Diff?
There is no widely-available offline library that provides structured "change regions" for PDF documents. The pixel-diff approach:
✅ Works for any PDF content — text, images, diagrams, scanned documents
✅ Catches all visual changes — font changes, color tweaks, layout shifts
✅ Is fast — pixelmatch processes millions of pixels in milliseconds
⚠️ May flag anti-aliasing artifacts — mitigated by the configurable diffThreshold
⚠️ Does not provide semantic information (e.g., "this paragraph was reworded")
Known Limitations
Cannot override VS Code's diff editor — VS Code's API does not allow extensions to replace the built-in diff editor for specific file types. You must use the context menu command instead of clicking the PDF directly in Source Control.
Page matching is by index — Pages are compared 1-to-1 by page number. If a page was inserted in the middle, all subsequent pages will show as changed. A future enhancement could add page-content-based matching.
Large PDFs may be slow — All pages are rendered at once. For PDFs with 100+ pages, the initial load may take several seconds. Memory usage scales with page count × render resolution.
Anti-aliasing noise — Small pixel differences from font rendering may show as changes. Increase pdfVisualDiff.diffThreshold (e.g., to 0.2 or 0.3) to reduce false positives.
No text-layer diff — The extension compares rendered pixels, not extracted text. Semantic text diffing could be added as a future enhancement.
Commit-to-commit diffs — Currently supports Working Tree vs HEAD and Staged vs HEAD. Direct commit A vs commit B comparison is not yet wired up (would require parsing Git URIs from the commit history view).
PDF.js rendering fidelity — Some complex PDFs with unusual fonts or embedded objects may render slightly differently than in native PDF viewers. This is a PDF.js limitation.
