AeroPDF

A browser-local PDF review extension for VS Code Web. Chat tools and the editor operate on the same PDF session. PDF.js handles rendering; the viewer adapts the official MCP Apps PDF example. There is no external MCP server, Node process, CDN dependency, or backend PDF upload in the extension.

First release

• Open workspace PDFs in an AeroPDF editor tab.
• Select text, navigate, search, zoom, review annotations, and fill existing forms.
• Let chat read pages, inspect the current selection, navigate, add highlights and notes, fill fields, render a page, and save an annotated PDF.
• Save to the original or a new workspace file; refuse conflicting source writes.
• Use VS Code's custom-editor save, revert, Save As, unsaved-document, and backup lifecycle. The viewer also has its own annotation undo/redo controls.
• Run in the browser extension host, including virtual workspaces. Writes require a writable workspace provider. No desktop-only APIs are imported.

Status: initial implementation. Browser tests exercise both standard MCP App postMessage and the VS Code message transport. The filesystem/editor adapter is tested against a mocked VS Code API. A full installation test inside AeroCode / VS Code Web is still needed before publishing. This extension has not been published to the Marketplace.

Try it

Build or use the supplied aeropdf.vsix, then run Extensions: Install from VSIX... in a VS Code host that supports web-extension sideloading. In a trusted workspace, right-click a PDF, choose Reopen Editor With... → AeroPDF, or run AeroPDF: Open PDF. Native Save / Save As work; AeroPDF: Save Copy saves a review copy without replacing the open session.

Enable the aeropdf_* tools in the host's chat tool picker. Example:

Open reports/quarterly.pdf, show me the revenue section, highlight the key sentence, and save the review to reports/quarterly-reviewed.pdf.

The extension contributes skills/aeropdf/SKILL.md for hosts that support extension-provided chat skills. The tools are usable without skill discovery. The agent's/model provider's normal handling of tool results still applies: PDF processing is local, while requested text or page images can enter chat.

Tools

All page numbers are 1-based. Paths are workspace-relative; prefix the folder name in multi-root workspaces. Notes use PDF points from the page's top-left. Mutating chat tools provide VS Code confirmation messages. Hosts that invoke language-model tools must honor the VS Code tool invocation/approval lifecycle.

Local MCP App architecture

src/extension.ts owns workspace access and registers vscode.lm tools. src/session.ts hosts the MCP App bridge and services only local byte reads and saves for its own session. src/transport.ts carries JSON-RPC over the webview channel. The adapted upstream viewer uses the MCP Apps SDK and registers its review operations. Every session has one editor view.

dist/app.html is a self-contained MCP App UI resource. It uses VS Code messaging when acquireVsCodeApi is available and standard MCP App postMessage otherwise. The extension exposes its resource URI through its activation API. Inline chat rendering, moving the same live session between a chat widget and editor, and an in-memory MCP server adapter for general MCP clients are not implemented yet. Those require an AeroCode host integration; the editor-driven workflow works through the native tool catalog.

The CSP blocks external assets and inline script injection. PDF.js worker code, fonts, CMaps, WASM decoders, and CSS images ship with the extension. Only opened workspace PDFs are accessible; paths, byte ranges, file sizes, trust, symlink entries, and overwrite choices are checked by the host adapter.

Limits

• Four simultaneous PDF sessions, up to 64 MiB per PDF. The initial host read is in memory; this release does not provide multi-gigabyte streaming.
• No OCR, secure redaction, arbitrary PDF text/layout editing, digital signing, or creation of form fields. Encrypted and unusual PDFs may fail to load/export.
• Annotation/form export follows upstream capabilities. Image-heavy, rotated, complex, and non-Latin PDFs need broader compatibility testing.
• Saving through a chat tool or viewer toolbar writes the file immediately. VS Code may retain its dirty indicator until a native Save completes.
• Source-conflict checks happen immediately before writes; the workspace API does not expose an atomic compare-and-swap operation.
• The editor maintains its own undo/redo, rather than native VS Code edit events.

Develop

Requires Node 22 or newer.

npm ci
npx playwright install chromium
npm run verify
npm run package:vsix

verify type-checks, builds, runs policy/filesystem tests, then launches Chromium for end-to-end viewer tests. Browser tests generate their own two-page PDF with text and checkbox fields, drive both transports, assert zero external requests, and reopen the exported PDF to check real annotations and field values. Generated test artifacts are written under test-results/.

The optional AEROPDF_CHROMIUM environment variable selects a preinstalled Chromium executable. AEROPDF_LOCAL_CHROMIUM=1 uses a separately installed @sparticuz/chromium runtime for constrained CI environments.

Dependency versions are pinned. See NOTICE.md and the preserved upstream license before redistributing the viewer. vendor/pdf-app/ retains the upstream layout to make future updates reviewable.

Release and publish

Publishing follows the shared AeroKit workflow:

1. After Verify succeeds for a push to main, code changes without an explicit version change use bpcarson/actions to create and merge a patch version bump. Viewer, extension, skill, dependency, and build changes count.
2. Release on version bump creates or resumes the matching vX.Y.Z GitHub release and calls Publish VSIX directly.
3. Publish VSIX checks the tag and Marketplace identity, runs verification, builds the VSIX, attaches it to the release, and publishes bpcarson.aeropdf using the repository's VSCE_TOKEN secret. Existing Marketplace versions are skipped on retries.

For the first release, manually run Release on version bump on main. To retry an existing release, run Publish VSIX with its tag. Publishing a GitHub release manually also triggers that workflow. The token is required only by the Marketplace publish step; it is not passed to builds or tests.

Automatic version bumps require Actions to be allowed to create pull requests, and repository policies must allow the shared workflow's merge. Workflow-only and documentation-only changes do not trigger patch bumps.