A native, high-performance PDF viewing engine and GPUI workspace item engineered for the Zed Editor.
Important: This is a native workspace crate, not an installable WASM extension.
As of current Zed versions, Zed's WebAssembly extension API (zed_extension_api) contains no custom UI or file preview surfaces.kkpdf-zedis designed as a native crate to be registered within the Zed workspace (crates/kkpdf_vieweror integrated upstream intozed-industries/zed).
extension.toml in this repository is a documentation stub preserving metadata identi
A40E
ty for a potential future extension surface or upstream contribution.
┌──────────────────────────────────────────────────────────────────────────────────┐
│ KKPDF-ZED CORE PIPELINE │
└──────────────────────────────────────────────────────────────────────────────────┘
│
[PDF Document on Disk / Memory Buffer]
│
▼
[Thread-Safe Document Handle (`document.rs`)]
│
▼
[Serialized Native Pdfium Engine (`pdfium/`)]
│
▼
[Memory-Budgeted LRU Cache (`cache.rs`)]
│
(Visible Viewport + 1-Page Margin)
│
▼
[Luminosity Tone-Mapping Engine (`rasterizer.rs`)]
│
(Inverts White/Black; Preserves Images)
│
▼
[Viewport State & Geometry Engine (`view.rs`)]
- Thread-Safe Serialization: PDF parsing and rasterization are synchronized behind thread-safe handles, ready to be dispatched to background executor tasks in GPUI.
- Viewport Virtualization & LRU Caching: Pages are rasterized on-demand with memory-budgeted caching (
PageLruCache) to prevent unbounded RAM usage. - Luminosity-Threshold Dark Mode: Unlike simple blanket RGB inversion (which turns photos and charts into negative ghosts),
kkpdf-zedimplements selective tone mapping, remapping near-white canvas backgrounds to editor background tones and near-black text to theme light text, while preserving saturated color images. - Scroll & Zoom Preserving Live Reload: Watches the underlying PDF on disk (via file system notifications) and reloads seamlessly without resetting the user's scroll percentage or zoom level.
- Bitmap-Rendered Continuous Scroll: Version 1 is engineered strictly as a high-fidelity, high-frame-rate read-only document viewer.
- Excluded from v1:
- Text selection and copying.
- In-document text search (
Ctrl+F). - Interactive PDF form field editing.
- Rationale: Delivering an ultra-fast, stutter-free viewing experience with zero UI locks takes precedence. Text extraction and selection layer synchronization will be introduced in subsequent milestones.
- In-Process Parsing: PDF rasterization is performed via Google's native C++ Pdfium engine linked in-process with the editor.
- Accepted Risk in v1: Because Pdfium runs in-process without sandboxing (e.g., without separate process IPC or WebAssembly memory isolation), malformed or malicious PDFs could theoretically trigger memory vulnerabilities in the underlying C++ library.
- Mitigation & Future Hardening: Memory budgets are strictly capped, document handles are isolated behind thread boundaries, and a future sandboxed worker process model is planned for untrusted file browsing.
kkpdf-zed/
├── Cargo.toml # Native crate manifest
├── extension.toml # Documentation stub
├── README.md # Architecture & operational guide
└── src/
├── lib.rs # Crate entrypoint & exports
├── document.rs # Thread-safe PdfDocument handle
├── rasterizer.rs # Async background rendering & luminosity tone mapping
├── cache.rs # Memory-budgeted LRU cache with O(1) eviction
├── watcher.rs # Live-reload file watcher & scroll state
├── view.rs # Viewport state machine, navigation & pan/zoom geometry
└── ui/
└── toolbar.rs # Zoom, fit-width & page jump controls
Run unit and integration tests across the caching and rasterization engines:
# Run all unit and integration tests (mock fallback enabled when native library is absent)
cargo test
# To run tests against native Google Pdfium dynamic libraries:
bash scripts/download_pdfium.sh "${PWD}/lib"
PDFIUM_LIB_DIR="${PWD}/lib" cargo testThe wider Zed community has packaged and extended kkpdf-zed for end-user workflows:
- TendonT52/zed-with-pdf-viewer: Provides prebuilt, ready-to-run macOS application bundles (
.dmgfor Apple Siliconaarch64and Intelx86_64) that track upstream Zed stable releases with native PDF rendering built in. - HomoY/zed-with-pdf-viewer-synctex: Extends downstream Zed PDF integration with bidirectional SyncTeX support for LaTeX and Typst workflows (Cmd-click PDF to jump to TeX source; Cmd+Option+J to jump from editor to PDF viewport).
kkpdf-zed is a clean-room, native Rust implementation designed specifically for Zed's GPUI framework. We gratefully acknowledge the open source projects that inspired our workflow and interface concepts:
- Zed (zed-industries/zed): The high-performance code editor and GPUI framework powering this experience (GPL-3.0 / Apache-2.0).
- pdfium-render: Idiomatic Rust FFI bindings to Google Chrome's native Pdfium engine (Apache-2.0 / MIT).
- LaTeX-Workshop by James Yu (MIT License): Inspired the live-reload debounce strategy and scroll-preserving document refresh workflows for TeX/Typst compilation.
- vscode-pdfviewer by tomoki1207 (MIT License): Inspired ergonomic zoom-level scaling increments and toolbar layout patterns.
- typst-preview by mgt (MIT License): Informed smooth previewer synchronization concepts.
Note: No third-party source code was copied into this project; all GPUI painters, rasterizer pipelines, and caching layers are original native Rust implementations.
This project is dual-licensed under either:
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- GNU General Public License, Version 3.0 or later (LICENSE-GPL or https://www.gnu.org/licenses/gpl-3.0.html)
at your option.