# pdf-tools / PDF Workbench `pdf-tools` is a self-hostable, browser-only PDF workbench for fast page-level PDF operations. It is built for situations where uploading PDFs to a third-party service is undesirable, but users still need simple, visual tools to split, merge, reorder, rotate, duplicate, delete, extract, and export pages. Current hosted version: Current development release: **v0.4.0 — shared Toolbox header and themes**. See [`CHANGELOG.md`](CHANGELOG.md) for milestone history. Active work is tracked in Gitea issues. Durable project context is mirrored into the Gitea wiki from repository docs, including [`ROADMAP.md`](ROADMAP.md). The app is a static React/Vite single-page application. There is no backend service, no server-side queue, and no server-side document storage. When hosted correctly, the server only delivers HTML, JavaScript, CSS, and static assets; PDF processing happens in the user's browser. ## Purpose Many everyday PDF tasks are not full document-authoring tasks. They are page-workbench tasks: - remove pages before sending a document; - rotate scanned pages; - split a PDF into single-page files and download them individually or as one ZIP archive; - merge another PDF into the current document; - extract a subset of pages; - reorder pages visually; - keep a local working state while experimenting; - undo and redo page operations before exporting. `pdf-tools` focuses on this page-level workflow. It is intentionally not a full PDF editor, OCR solution, digital-signature workflow, DMS, or Adobe Acrobat replacement. ## Where the project comes from The project started as a pragmatic, browser-only PDF helper for quick administrative and document-preparation tasks. The guiding idea is simple: many users need small PDF operations, but sensitive or internal documents should not have to leave the browser just to remove, rotate, split, or rearrange pages. This makes the project especially useful for self-hosted environments, public-sector settings, universities, small organizations, and internal tools where operational simplicity and document locality matter. ## Distinguishing features - **Browser-only processing**: PDF files are processed locally in the browser. The hosting server does not receive the selected PDFs. - **Static self-hosting**: The production build can be served by any static web server or reverse proxy. - **Visual page workspace**: Users work with page thumbnails, drag-and-drop ordering, selection, page preview, and page-level actions. - **Named local workspaces**: Workspaces can be saved in the browser with the PDF binary and editing state stored in IndexedDB. - **Undo/redo command history**: Workspace operations are recorded as commands with label, timestamp, and payload. The history view shows undo and redo states. - **Progressive thumbnails**: Thumbnails are generated progressively so the UI becomes useful before all pages have finished rendering. - **Thumbnail cache by page and rotation**: Rotated thumbnails are cached and only changed thumbnails need to be regenerated. - **Stable page references**: Duplicated pages and reordered pages are tracked as workspace page references rather than only by original page number. - **Merge choices**: Loading another PDF can replace the current document, append pages, or insert pages at a chosen position. - **PDF.js compatibility setup**: PDF.js is configured through one shared module and a local worker wrapper so the app can polyfill `Uint8Array.prototype.toHex` before PDF.js runs in older browsers. - **Toolbox appearance controls**: The shared header provides light, dark, and system-following themes and keeps the app switcher, help, and source controls in the same place as the Toolbox portal. - **In-app help**: The app includes a Help/Tutorial dialog with keyboard shortcuts and workflow explanations. ## Current features ### File and workspace handling - Load a local PDF file. - Save a named workspace in the browser. - Restore saved workspaces from IndexedDB. - Reset the active workspace, with a save prompt for unsaved changes. - Delete saved workspaces after confirmation. - Store workspace history and redo history. ### Page operations - Generate page thumbnails in the browser. - Reorder pages with drag and drop. - Select individual pages. - Select page ranges with Shift-click. - Drag a selected page to move the whole selection. - Duplicate/copy selected pages into a chosen position. - Rotate pages clockwise and counter-clockwise. - Delete one page or all selected pages after confirmation. - Preview pages in a modal overlay. - Flip through preview pages with buttons or arrow keys. ### Export tools - Export the current reordered/rotated/duplicated/deleted workspace as a new PDF. - Extract selected pages into a new PDF. - Open selected pages as a new active workspace for continued editing. - Split the source PDF into single-page PDFs. - Download all split results as one ZIP archive. - Merge another PDF by replacing, appending, or inserting it into the current workspace. ### Keyboard shortcuts | Shortcut | Action | | -------------------------- | --------------------------------------------------- | | `F1` / `?` | Open in-app help and tutorial | | `Ctrl`/`⌘` + `A` | Select all pages | | `Delete` / `Backspace` | Delete selected pages after confirmation | | `Esc` | Clear the current selection or close an open dialog | | `Ctrl`/`⌘` + `Z` | Undo | | `Ctrl`/`⌘` + `Shift` + `Z` | Redo | | `Ctrl`/`⌘` + `Y` | Redo | | `←` / `→` in preview | Move to previous / next page | | `Esc` in preview | Close preview | Keyboard shortcuts are ignored while typing in form fields. ## In-app documentation concept The app includes a Help/Tutorial dialog reachable from the header's **?** control, `F1`, or `?`. Recommended structure for in-app documentation: 1. **Quick tutorial**: short task-oriented steps from loading a PDF to exporting. 2. **Keyboard shortcuts**: a compact reference for power users. 3. **Concepts**: explain the difference between a PDF file, a workspace, command history, and exported output. 4. **Privacy model**: state clearly that processing is browser-local and workspaces are saved in local browser storage. 5. **Roadmap hints**: link users to the README or project repository for planned features, instead of overloading the app UI. This keeps the app useful for first-time users without turning the main interface into a manual. ## Administrator notes ### Deployment model `pdf-tools` is deployed as a static web application: ```text browser <-- HTTPS --> static web server / reverse proxy --> built app assets ``` There is no application server to operate. Administrators only need to host the built files from `dist/`. The production build is relocatable and can also be assembled into an [Add Ideas Toolbox](https://git.add-ideas.de/zemion/toolbox-portal) deployment. `toolbox-app.json` describes this app through the framework-independent [Toolbox App Contract](https://git.add-ideas.de/zemion/toolbox-sdk). The same artifact remains fully usable on its own. The shared first-party shell always provides help, source, and appearance controls. When launched with a same-origin catalogue URL, for example `?toolbox=/toolbox.catalog.json`, it also connects the application switcher to the current Toolbox catalogue. Missing, invalid, and cross-origin catalogues are ignored so the app falls back to standalone mode. ### Build and test from source ```bash npm ci npm run check ``` `npm run check` runs the main project quality gate: ```bash npm run typecheck npm run lint npm run test npm run build ``` The production build is written to `dist/`. Create a versioned, checksummed release artifact with: ```bash npm run release:artifact ``` This writes `release/pdf-tools-.zip` and its `.sha256` file. The ZIP contains the static app, its toolbox manifest and changelog, plus the application source-code location, license, and the full license/notice texts found for bundled runtime dependencies under `LICENSES/`. Existing artifacts for the same version are never replaced implicitly; after intentionally reviewing a rebuild, use `npm run release:artifact -- --force`. Useful individual development commands: ```bash npm run dev # start the Vite development server npm run preview # preview the production build locally npm run test # run tests once npm run test:watch # run tests in watch mode npm run typecheck # run TypeScript without emitting files npm run lint # run ESLint npm run format # format the project with Prettier npm run format:check # verify Prettier formatting ``` ### Static hosting Any static hosting setup should work, for example: - nginx; - Apache httpd; - Caddy; - Traefik in front of a static file container; - GitLab Pages or another static publishing target; - a minimal container serving `dist/`. A typical nginx location for a single-page app looks like this: ```nginx location / { try_files $uri $uri/ /index.html; } ``` ### Reverse proxy considerations For production, serve the built app via HTTPS. The reverse proxy only sees requests for static app assets. It should not receive the user's PDF files, because the files are opened through browser APIs and processed locally. For the Vite development server, `vite.config.ts` can restrict allowed hosts. The current development configuration includes `pdftools.add-ideas.de` as an allowed host for the dev server. This is not required for a normal production static build. ### Content Security Policy A strict CSP is possible, but it must account for browser-local rendering details. Thumbnails use data URLs, downloads use blob URLs, and pdf.js uses a worker. A starting point for testing could be: ```http Content-Security-Policy: default-src 'self'; script-src 'self'; worker-src 'self' blob:; img-src 'self' data: blob:; style-src 'self' 'unsafe-inline'; object-src 'none'; base-uri 'self'; form-action 'none' ``` Adjust this to your hosting environment and test PDF loading, thumbnail rendering, preview, and downloads before enforcing it broadly. ### Storage and persistence Saved workspaces are stored in the user's browser using IndexedDB. A workspace may include: - the source PDF binary; - workspace name and metadata; - page order and duplicated page references; - rotations; - selected pages; - undo and redo command history. This has several operational consequences: - Workspaces are local to the browser profile and device. - Clearing browser data can delete saved workspaces. - Server backups do not include user workspaces. - Different users on different devices do not share workspaces through the server. - Browser storage quotas apply. ### Privacy and logging The server should only log asset requests for the app itself. It should not log PDF filenames or contents unless the hosting environment adds custom client-side telemetry or upload logic. Avoid adding analytics that could weaken the project's privacy model. ### Browser support The app expects modern browser APIs, including: - File API; - Blob and object URLs; - IndexedDB; - Web Workers; - Canvas; - modern JavaScript modules. The app includes a small `Uint8Array.prototype.toHex` compatibility shim for PDF.js fingerprint handling in browsers that do not provide that typed-array helper natively. Use current versions of Chromium, Firefox, Safari, or Edge where possible. ## Versioning and release baseline The application version shown in the header is defined in `src/version.ts`. The package version in `package.json` and the displayed app version should be kept in sync for releases. The current development baseline is: ```text v0.4.0 — shared Toolbox header and light/dark/system themes ``` This branch preserves the browser-only workspace baseline and PDF.js compatibility setup while moving the app to Toolbox SDK `0.2.0`. The displayed app/package version is `0.4.0`; the shared header and saved appearance preference now work in standalone and portal-launched sessions. Workspace state, thumbnail handling, generated download URLs, page-grid components, tests, type-checking, linting, and formatting remain separated enough to support additional feature work without turning `App.tsx` back into a monolith. ## Project structure ```text src/ App.tsx Main application orchestration and UI wiring components/ ActionDialog.tsx Reusable confirmation/action dialog ActionsPanel.tsx Export, extract, split, and ZIP download actions FileLoader.tsx PDF file loading HelpDialog.tsx In-app tutorial and shortcut reference Layout.tsx Application shell/header PagePreviewModal.tsx Large page preview with navigation ReorderPanel.tsx Page grid, selection, drag/drop, copy/delete/rotate WorkspacePanel.tsx Workspace save/load/reset and undo/redo history pdf/ pdfJs.ts Shared pdf.js setup and worker configuration pdfjsWorker.ts Local pdf.js worker wrapper with compatibility shim uint8ArrayToHexPolyfill.ts Compatibility shim for PDF.js fingerprint handling pdfService.ts pdf-lib operations: load, merge, split, export pdfThumbnailService.ts pdf.js thumbnail rendering pdfZipService.ts Browser-side ZIP packaging for split results pdfTypes.ts PDF-related types workspace/ workspaceCommands.ts Command model for undo/redo workspaceDb.ts IndexedDB persistence workspaceTypes.ts Workspace data model styles.css Global styles version.ts App version displayed in the header ``` ## Roadmap and backlog The roadmap and non-goals now live in [`ROADMAP.md`](ROADMAP.md). Open roadmap items are imported into Gitea issues so priorities, status, and implementation notes stay out of the README. ## License AGPL-3.0-only. See `LICENSE`.