PDF Page Summaries

Relevant source files

The following files were used as context for generating this wiki page:

• backend/routes/pdf-page-summaries.ts
• extension/src/content/pdf-page-summaries.ts
• backend/config/prompts.json
• extension/src/content/tests/pdf-page-summaries.test.ts
• backend/api/tests/pdf-page-summaries.test.ts
• backend/lib/pdf-page-summary-validator.ts
• extension/src/background/index.ts

PDF Page Summaries generate concise, 1-2 sentence overviews for individual pages of a converted PDF document. This feature helps readers quickly understand the main idea, key evidence, or structural role of each page within the document. The system uses a combination of DOM normalization, text extraction, and Large Language Model (LLM) generation to provide these summaries.

The system is primarily used when a PDF has been converted to HTML. It identifies page boundaries, extracts text while ignoring noise (like headers or UI fragments), and presents summaries in a dedicated modal interface within the browser extension.

Sources: backend/config/prompts.json:441-443, extension/src/content/pdf-page-summaries.ts:358-362

System Architecture and Data Flow

The PDF Page Summary feature operates across the browser extension's content script, background worker, and the backend API.

1. Content Script: Discovers pages in the DOM, computes hashes, and manages the UI (Floating Action Button and Modal).
2. Background Worker: Routes requests between the content script and the Backend API.
3. Backend API: Validates requests, checks user usage limits, queries existing summaries from the database, or generates new ones via OpenRouter.

Summary Generation Flow

The following diagram illustrates the sequence of events when a user requests a summary for a specific PDF page.

DOM Normalization and Page Discovery

Because different PDF-to-HTML converters produce varying DOM structures, the system performs normalization to ensure a consistent #page-container [data-page-no] hierarchy.

Normalization Strategies

The normalizePdfDom function applies cascading checks:

• Existing Structure: If #page-container [data-page-no] exists, it does nothing.
• Missing Attributes: If #page-container exists but children lack data-page-no, it injects the attributes.
• ID Pattern: If elements with IDs like page1, page2 are found, it wraps them in a container and adds attributes.
• Synthetic Fallback: If no structure is found, it wraps all body children into a single synthetic page.

Sources: extension/src/content/pdf-page-summaries.ts:358-385, extension/src/content/tests/pdf-page-summaries.test.ts:115-156

Text Extraction

The extractPdfPageText function clones the page element and removes injected UI artifacts (like Oddity's own summary hosts or margin notes) before normalizing whitespace. This ensures the LLM receives only the original document text.

Sources: extension/src/content/pdf-page-summaries.ts:41-45, extension/src/content/pdf-page-summaries.ts:394-399

Backend API and Validation

The backend handles the persistence and generation logic. It uses Zod for schema validation and a custom validator to ensure the generated summary meets length requirements.

API Endpoints

Method	Endpoint	Description
GET	/	Retrieves all existing summaries for a specific document_hash.
POST	/generate	Generates a new summary for a page if not already cached.

Sources: backend/routes/pdf-page-summaries.ts:48, backend/routes/pdf-page-summaries.ts:76

Data Model

The pdf_page_summaries table stores the generated content.

Field	Type	Description
url	String	The source URL of the PDF.
document_hash	String	SHA-256 hash of the entire document text.
page_no	String	The page number identifier.
page_text_hash	String	SHA-256 hash of the specific page's text.
summary	String	The 1-2 sentence generated summary.

Sources: backend/routes/pdf-page-summaries.ts:37-45, backend/api/tests/pdf-page-summaries.test.ts:103-114

Prompt Engineering

The system uses a specific system prompt (pdf_page_summary_prompt) to guide the LLM.

Generation Constraints

• Length: Exactly 1 or 2 sentences, under 320 characters.
• Content: Focus on the main idea or role of the page; ignore extraction noise.
• Formatting: No titles, bullets, or markdown.
• Sparse Pages: If a page contains only figures or tables, the LLM is instructed to state the dominant content plainly.

Sources: backend/config/prompts.json:441-468

{
  "summary": "<1-2 concise sentences>"
}

Sources: backend/config/prompts.json:470-472

User Interface Components

The UI is managed by the PdfPageSummaryController, which handles the mounting of the launcher and the modal.

Components

• Launcher FAB: A fixed button at the top-left of the viewport that opens the summary modal.
• Modal Backdrop: A full-screen overlay containing the summary grid.
• Summary Cards: Each card represents a page. It can show a "Thumbnail" (a scaled, sanitized clone of the actual page) or the generated "Summary" text.
• Intersection Observer: Tracks which page is currently visible in the document and automatically scrolls the modal to the corresponding card when opened.

Sources: extension/src/content/pdf-page-summaries.ts:413-468, extension/src/content/pdf-page-summaries.ts:635-645

UI State Management

Conclusion

The PDF Page Summaries module provides an automated way to navigate and comprehend long PDF documents. By normalizing diverse HTML structures and utilizing constrained LLM prompts, it ensures that users receive high-quality, concise overviews of document content regardless of the original PDF's formatting.