PDFMathTranslate/PDFMathReader

• Tooling: Bun manages dependencies and scripts; Vue/Vite build the UI, while Electron and Express run on Node.js. Commit bun.lock when changing dependencies.
• Tests: run bun run build, then bun run test; CI scripts use node --test .github/scripts/*.test.*. Add focused regression coverage for behavior changes; see test priorities.
• CI: Code style checks formatting and lint; Packaging builds and launches apps on macOS, Windows and Linux. Release publishes successful default-branch packages when the version increases.
• Style: run bun run style:fix before committing. Husky automatically formats and checks staged files, blocking unresolved errors. Prettier/ESLint cover JS and Vue, Ruff covers Python, and swift-format covers Swift; see setup and rules.

Install Bun 1.3.14 and Node.js 22.22.1 or newer. To run the desktop app from source:

bun install --frozen-lockfile
bun run desktop

Build on the matching platform:

# macOS (requires a signing identity; add --unsigned to skip signing)
bun run package:mac
# Windows
bun run package:win

Frontend libraries (Vue, MacVue, and Fluent UI) are build dependencies: Vite includes them in dist. Node dependencies used by the server or Electron main process remain runtime dependencies. Install with bun install --frozen-lockfile before building; a production-only install cannot build or package the app.

The About page includes GitHub Release update status, a manual check button, and an automatic check switch (enabled by default). Packaged apps check lazily after startup and every six hours; no published release is shown as a normal empty state. Stable version tags must use vX.Y.Z or X.Y.Z. Matching release assets use PDFMathReader-<platform>-<arch>.zip (macOS), .exe (Windows), or .tar.gz (Linux). Available updates open the matching download, or the release page when that asset is absent; installation remains manual.

The About page shows the application, installed kernels and UV versions. Each Vite build embeds dist/build-info.json with the package version and the latest ten conventional feat commits (including scoped and breaking features); release CI checks out the full Git history. The installed app reads this snapshot without Git or network access. Builds from a source archive without Git show an empty update list.

The default Electron package bundles Express and PDF utilities into the backend/main scripts, retaining their licenses. It copies only external runtime modules into the staged node_modules; native PDF Inspector bindings and the PDF.js/DOMMatrix fallback for unsupported native targets remain available. Electron itself and packaging tools are supplied by the build toolchain.

For browser development, set OPENAI_API_KEY, run bun run dev, and open 127.0.0.1:5173. Use OPENAI_MODEL to override the default model. Desktop environment variables can be loaded with Launch PDFMathReader.command.

bun run test
bun run build

The application suite contains 29 risk-focused tests. See test priorities for retained coverage and the policy for adding cases.

PDFMathReader uses Vue 3 and PDF.js for the reader, Electron for the desktop app, and Express for the local backend. Vite supports frontend development and builds; pdf-lib handles PDF manipulation.

Each desktop window has its own renderer and backend running in an Electron utility process. The main process manages windows, menus, credentials, recent documents, and preferences. A sandboxed preload provides desktop IPC; backend requests use authenticated HTTP on 127.0.0.1.

Rendering, layout analysis, and translation run independently. Pages and thumbnails are virtualized, PDF.js and layout analysis load on demand, and rendering caches have bounded memory use. Each document is uploaded to its local backend once; subsequent requests use its document ID. Outdated translation work is cancelled when the document, language, or kernel changes.

Translation text is cached across documents and app restarts. Identical requests to the same service and model reuse the saved result, including requests from the math translation kernels. Languages, prompts, and other translation options remain part of the cache key. Concurrent identical requests share one service call; failed or empty responses are not cached.

Experimental Jev paragraph continuation detection is available with Ultra fast and Fast. Fast combines confirmed adjoining fragments within the same column before translation and typesetting, keeping formulas in place. Uncertain or failed checks preserve separate fragments. Enabling it uses separate page caches so earlier unmerged output is regenerated.

Experimental: Settings → Experimental → Generate table of contents adds Edit → Generate Table of Contents, which builds a contents list locally for documents without bookmarks, with progress shown in the Contents sidebar. It parses a printed contents page (including dot leaders and right-aligned page numbers) and maps its page numbers to physical pages; if there is none, it infers headings from font sizes, numbering, and spacing. Nothing is sent anywhere. Scanned pages without a text layer are not supported, and generated contents are not saved with the document.

Experimental: Precise can instead translate through a remote zotero-pdf2zh server over HTTP (Settings → Experimental). PDFMathReader implements that server's HTTP protocol as a client; the server is not bundled and is optional. The remote kernel is used only when the server's /health check passes, otherwise the local Precise kernel runs. No API key is sent; the server uses its own translation service. Remote pages have no reading text layer, and the selected translation service and glossaries are not used for remotely translated pages.

PDF rendering and layout analysis stay local. Translation sends document text to OpenAI and may incur API charges. Fast and Precise run in separate app-managed Python environments installed with uv, and access OpenAI through the backend proxy. API keys remain outside the renderer.

Saved desktop keys are encrypted with Electron safeStorage and macOS Keychain protection. A saved key overrides OPENAI_API_KEY; clearing it restores the environment fallback. Saving is disabled when secure storage is unavailable.

Desktop data is stored in the app directory under ~/Library/Application Support/: credentials, recent documents, translation/layout caches, and kernel environments. Browser-development caches use .cache/translations/. Caches and temporary PDFs can contain document content; Clear on the start page removes recent-document history only.

In browser development, Express and Vite run in a standalone Node.js process. Native menus, desktop IPC, and secure desktop key storage are available only in the desktop app.

• Platform support: macOS is the tested platform. Windows and Linux have platform-specific styles, but native runtime validation is pending. Packaging commands target macOS arm64 and Windows x64.
• Layout fidelity: Ultra fast uses geometric paragraph grouping and text overlays. Complex tables, rotated text, unusual backgrounds, and long translations may not retain the original typography. Math-kernel output depends on upstream layout handling.
• Scanned documents: scanned PDFs require OCR, which this app does not implement.
• Translation requirements: translation needs an OpenAI API key and network access. Fast and Precise require separately installed math kernels through uv.
• Scope: this is a local reader and translation app, not a complete PDF editing or export tool.
• Validation: the 30 core regression tests cover backend and reader support logic. Mock-provider checks do not establish live OpenAI translation quality or API-key validity.