PDF Export & Conversion
Relevant source files
The following files were used as context for generating this wiki page:
The PDF Export & Conversion module manages the transformation of documents between PDF and HTML formats. This system enables users to annotate PDF content by converting it to a web-readable format and allows for the generation of annotated PDF reports from existing web content or dashboard data.
PDF to HTML Conversion
The conversion system transforms raw PDF data into structured HTML to support the annotation engine. This process uses an external API and a backend orchestration layer to handle large file processing and polling.
Conversion Architecture
The backend utilizes the FreeConvert API to perform the conversion. The system enforces a 3MB limit on raw PDF files and requires a "Standard" user tier to access this feature.
This diagram illustrates the asynchronous polling mechanism used to manage long-running conversion tasks within Vercel's timeout limits.
Sources: backend/routes/convert-pdf.ts:1-125
Conversion Steps and Validation
- Tier Gate: The router checks the
UserTiervia thecanUseFeatureutility. - Payload Validation: The system validates the presence of
pdfBase64and ensures the buffer does not exceedMAX_PDF_SIZE(3MB). - Task Orchestration: The backend creates an import upload task, a conversion task (HTML output), and an export task.
- Polling Strategy: The system polls every 2 seconds with a 55-second timeout.
Sources: backend/routes/convert-pdf.ts:36-96
PDF Export Engine
The export engine generates a print-ready HTML document that includes original page content alongside Tufte-style sidenotes for annotations.
HTML Sanitization
Before exporting, the system strips host-page artifacts to ensure clean rendering. It removes non-content elements like scripts, styles, navigation, and forms. It retains essential attributes such as src, href, and alt.
Sources: extension/src/content/export-pdf.ts:88-120
Annotation Injection Logic
The engine uses a recursive text marker to locate annotation anchors within the sanitized DOM.
- Phase 1: Marking: The system sorts annotations by anchor length (longest first) to prevent sub-match conflicts. It wraps matched text in
<mark>tags. - Phase 2: Sidenotes: It iterates through marks in DOM order and injects
sn(sidenote) spans. These sidenotes alternate between left and right margins.
Sources: extension/src/content/export-pdf.ts:133-162, Oddity1Dashboard/src/utils/exportPdf.js:29-52
Sidenote Components
| Component | Description |
|---|---|
sn-label | The type of annotation (e.g., Core Claim, Insight). |
sn-body | The primary note text provided by the user or AI. |
sn-section | Extra context like "Why it matters" or follow-up questions. |
extra-section | A list of annotations that could not be matched to the text. |
| Sources: extension/src/content/export-pdf.ts:197-217, Oddity1Dashboard/src/utils/exportPdf.js:84-118 |
PDF Page Summaries
For converted PDF documents, the system provides a specialized controller to generate and display summaries for individual pages.
Controller Logic
The PdfPageSummaryController manages a launcher Floating Action Button (FAB), a modal grid of summary cards, and an IntersectionObserver to track the currently visible page in the viewport.
The normalizePdfDom function standardizes different PDF converter outputs (e.g., pdf2htmlEX, FreeConvert) by ensuring #page-container [data-page-no] exists.
Sources: extension/src/content/pdf-page-summaries.ts:153-205, extension/src/content/pdf-page-summaries.ts:251-310
Summary Card States
- Preview State: Displays a sanitized clone of the PDF page at a scaled width (220px).
- Loading State: Shows a "Summarizing..." indicator while the AI generates content.
- Summary State: Displays the 1-2 sentence page overview with a copy-to-clipboard action.
Sources: extension/src/content/pdf-page-summaries.ts:468-525
Visual Styling and Fonts
The export system maps internal annotation types to specific CSS styles and fonts to maintain visual consistency with the live extension.
| Property | Value Options |
|---|---|
| Fonts | Fraunces, Kalam, Helvetica, Arial, Georgia, System |
| Sizes | Small (12px), Medium (14px), Large (16px) |
| Colors | Derived from ANNOTATION_COLORS |
The buildDocument function dynamically loads Google Fonts (e.g., Lora, Fraunces) via link tags in the generated HTML header.
Sources: extension/src/content/export-pdf.ts:31-60, extension/src/content/export-pdf.ts:241-260
Conclusion
The PDF Export & Conversion system provides a robust pipeline for document transformation. By combining backend conversion services with client-side DOM manipulation and Tufte-style layout logic, it ensures that annotations remain contextually relevant and visually accessible in exported formats. The inclusion of page-level summaries further enhances the navigability of converted PDF documents within the project.