PDFs & Annotations
Relevant source files
The following files were used as context for generating this wiki page:
The PDF viewer and annotation system manages the display, navigation, and markup of PDF documents within the PRKS research library. It enables you to highlight text, underline passages, and attach comments directly to document coordinates, while ensuring these markups persist across sessions and synchronize with the backend database.
The system integrates a vendored PDF viewer runtime with a local-first persistence layer that handles concurrent edits, offline states, and data reconciliation. This ensures that user-created markup remains semantically consistent even when the underlying PDF bytes are updated or viewed across different devices.
Sources: README.md, frontend/js/components/works-pdf.js:1-10, tools/pdf-viewer/README.md
Viewer Architecture and Integration
The PDF viewer is implemented as a specialized component loaded on demand when you open a work containing a PDF file path. It utilizes a vendored distribution of @embedpdf/core to handle document rendering and low-level annotation primitives.
Component Lifecycle
The frontend runtime initializes the viewer by creating a PRKS PDF viewer instance and mounting it to a specific DOM element. The initialization process restores your last viewed page and zoom settings.
Supported Interaction Modes
The viewer operates in two primary modes depending on the current capability of the runtime:
| Mode | Description |
|---|---|
| Work | Allows full interaction, including creating, editing, and deleting annotations. Active when the file is local and storage is durable. |
| Preview | Read-only mode where you can navigate and view existing annotations but cannot perform mutations. |
Sources: frontend/js/components/works-pdf.js:1483-1490, tests/test_pdf_viewer_integration.py:270-280
Annotation Management
Annotations in PRKS are categorized into user markup (highlights, underlines) and embedded PDF artifacts (links, widgets). The system focuses on persisting user markup as canonical metadata.
User Markup Types
The following table describes the primary user-created annotation types:
| Type | Backend ID | Description |
|---|---|---|
| Highlight | 9 | Rectangular or multiline text background color overlays. |
| Underline | 10 | Line segments rendered beneath selected text. |
| Comment | N/A | Textual notes attached to a highlight or underline via the custom.prksComment field. |
Sources: backend/pdf_annotations.py:15-30, frontend/js/components/works-pdf.js:200-220
Logic for Filtering Markup
The frontend distinguishes between PRKS-managed markup and native PDF elements to prevent external links or watermarks from being saved into the PRKS database.
Synchronization and Persistence
PRKS uses a local-first synchronization strategy for PDF annotations. Mutations are first committed to a local IndexedDB store before being sent to the backend.
Materialization and Reconciliation
The system ensures that the PDF document (the "bytes") and the database metadata (the "canonical state") remain in sync through a process called materialization.
- Durable Intent: When you create an annotation, the viewer emits a "committed" event.
- Local Save: The runtime enqueues a durable write to IndexedDB.
- Materialization Gate: The system blocks further mutations while it reconciles the viewer state with the server's acknowledged revision.
- PDF Update: A new copy of the PDF containing the embedded markups is exported and uploaded to the server.
Conflict Handling
Conflicts occur if multiple devices edit the same annotation. The system provides a UI to resolve these by choosing to "Keep server" or "Apply mine".
| Conflict Code | Resolution Logic |
|---|---|
| REVISION_CONFLICT | Server revision is newer than the client's base. Requires manual decision. |
| ACKNOWLEDGED | Successful sync; client updates local cache to match server value. |
Sources: frontend/js/components/works-pdf.js:630-680, backend/pdf_annotations.py:100-110
Annotation Sidebar and Navigation
The Annotation Drawer (Sidebar) provides a list of all user markups within the document, sorted by page and vertical position.
- Jump: Clicking an item in the sidebar scrolls the viewer to the specific coordinates of that annotation.
- Wiki Links: You can copy a link in the format
[[pdf:id|label]]. These links can be pasted into Research Notes to create cross-references that navigate back to the exact spot in the PDF. - Comment Editor: Clicking a highlight in the viewer or an "Edit" button in the sidebar opens an anchored popup for updating the attached comment.
Sources: frontend/js/components/works-pdf.js:315-350, tests/PDF_VIEWER_MANUAL.md:38-45
Conclusion
The PDFs & Annotations system provides a robust environment for active reading and research. By decoupling the document rendering from the metadata persistence, PRKS ensures that your annotations are not just visual overlays but structured data points integrated into your broader research network through wiki links and coordinated synchronization.
Sources: tools/pdf-viewer/README.md, frontend/js/components/works-pdf.js