PaperDesk

macOS SwiftUI app: import academic PDFs into a local library, rebuild them as translation-friendly HTML, and open them via http://127.0.0.1 so Chrome's built-in translate works.

Third-party translation extensions are optional and not required for P0 success. See docs/PRD.md.

Requirements

• macOS 13+
• Xcode / Swift 5.9+ (DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer recommended)

Install (double-clickable app)

export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
cd /path/to/translate
./scripts/install-app.sh

This builds PaperDesk and installs ~/Applications/PaperDesk.app. After that, launch it like any other app — Finder → Applications, or Spotlight (⌘Space → "PaperDesk"). Re-run the script after pulling code changes to refresh the installed app.

Keep the app open while you read — it serves the reading pages and receives papers sent from Chrome.

Run from Terminal (dev)

./scripts/run-paperdesk.sh   # builds, then runs the binary in the foreground
# or
swift run PaperDesk

Test

export DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer
swift test

Reading quality on a real paper (not just plumbing):

swift run PaperDeskHarness path/to/paper.pdf

Extension tests:

node chrome-extension/tests/resolve-pdf.test.js
node chrome-extension/tests/paperdesk-client.test.js

Library layout

Default: ~/Documents/PaperDesk/

library.json
inbox/                 # drop PDFs here for automatic import
items/{uuid}/
  original.pdf
  reading.html
  thumbnail.png        # first-page preview shown on the library card
  meta.json
  notes.md             # optional literature notes

What it does

Area	Behaviour
Import	Drag in, pick files or a folder, drop into inbox/, or send from Chrome. The PDF is copied into the library; re-importing the same paper resolves to the copy you already have.
Convert	Layout-aware extraction rebuilds paragraphs and section headings, rejoins hyphenated line breaks, and repairs ligatures that publisher PDFs collapse (ofine → offline). Output is one continuous document, not page fragments.
Read	Opens in Chrome on 127.0.0.1 at a port that stays the same for your library, so bookmarks keep working.
Organise	Tags, notes, search across title / filename / tags / DOI / notes; grid with page previews or dense list.

Chrome companion

One click from a publisher page to the translatable reading copy — the extension hands the PDF straight to the app, with nothing written to Downloads. See docs/COMPANION_EXTENSION.md; load unpacked from chrome-extension/.

Docs

• docs/PRD.md — product scope and phase decisions
• docs/ROADMAP.md — milestones ahead (M3+), implementation approaches, decision gates
• docs/TECH_DESIGN.md — implemented modules, extraction design, server routes
• docs/TEST_REPORT.md — latest verification results
• docs/samples/ — sample PDFs

Translation path (frozen)

Success = Chrome (or system browser) built-in translate works on the reading HTML. Third-party translation side panels on localhost are not guaranteed.

Privacy and security

The app makes no outbound network requests — no telemetry, no update check, no metadata lookups. The only socket it opens is a listener bound to 127.0.0.1, because Chrome's built-in translation will not run on a file:// URL. Your papers, notes and tags stay in ~/Documents/PaperDesk/ as ordinary files.

The reading server is closed to web pages: it serves only reading.html and rendered figures under items/{uuid}/, and PDF hand-off requires a browser-extension origin plus a custom header, which a page cannot produce. The extension asks for <all_urls> — it has to inject the fetch into the publisher's page so your institutional session is attached, which is the only way paywalled PDFs come through.

SECURITY.md covers the routes, the trust boundaries, the two known limitations that are deliberate rather than overlooked, and how to report a vulnerability.

License

MIT.