DOM Rendering Engine

Relevant source files

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

• extension/src/content/index.ts
• extension/src/content/pdf-page-summaries.ts
• extension/src/content/manual.ts
• extension/src/content/export-pdf.ts
• Oddity1Dashboard/src/utils/exportPdf.js

The DOM Rendering Engine manages the visual transformation of web pages and PDF documents into an interactive annotation layer. It resolves text-based selectors to physical coordinates, injects structural anchors for state persistence, and renders multi-modal decorations including highlights, margin notes, and floating action buttons (FAB).

Core Architecture and Rendering Pipeline

The rendering engine operates as a multi-stage pipeline that synchronizes remote annotation data with the host DOM. It distinguishes between standard DOM-based websites and canvas-based environments like Google Docs.

Rendering Flow

1. Resolution: Converts TextQuoteSelector data (exact, prefix, suffix) into DOM Range objects.
2. Overlap Detection: Checks new ranges against existing anchor spans to prevent duplicate or conflicting decorations.
3. Anchor Injection: Inserts hidden <span> elements into the DOM to provide stable reference points for visual layers.
4. Decoration: Renders visual highlights in the Overlay layer and creates MarginNote components.

PDF Document Normalization

The engine includes a specific module to handle varied PDF-to-HTML conversion outputs. It ensures a consistent DOM structure for the summarization logic by enforcing a standard hierarchy.

Normalization Levels

• Existing Containers: Detects #page-container with data-page-no attributes and treats it as a standard source.
• Implicit Pages: Identifies elements matching id="pageN" (common in FreeConvert) and wraps them in a synthetic container.
• Fallbacks: Wraps all body children in a single synthetic page if no recognizable structure is found.

Key Components

Component	Function
normalizePdfDom	Standardizes DOM hierarchy across different PDF converters.
PdfPageSummaryController	Manages the lifecycle of page-level summaries and preview thumbnails.
sanitizePreviewClone	Clones PDF pages and removes interactive elements for safe preview rendering.

Sources: extension/src/content/pdf-page-summaries.ts:333-366, extension/src/content/pdf-page-summaries.ts:74-93

Manual Annotation Interface

The manual rendering system allows users to create custom highlights by interacting with native browser selections.

Selection and Highlighting Logic

1. Tracking: The system listens for selectionchange and mouseup events.
2. Temporary Highlighting: Draws transient visual rectangles over the user's selection while the editor is active.
3. Editor Injection: Mounts a Shadow DOM-hosted editor near the selection coordinates.
4. Permanent Rendering: Replaces the selection with stable anchors and persistent highlights upon saving.

PDF Export Rendering

The export system generates a standalone HTML document by sanitizing the host page and injecting Tufte-style sidenotes.

Export Pipeline

• Sanitization: Strips script tags, styles, and UI fragments while preserving content-essential attributes like src and href.
• Mark Injection: Processes annotations sorted by length to avoid sub-match conflicts and wraps anchor text in <mark> tags.
• Sidenote Injection: Injects sidenote cards immediately after their anchors. It uses Tufte-style floats to push notes into the margins while maintaining document flow.

Visual Style and Configurations

Rendering behavior is controlled by user preferences stored in chrome.storage.local. The engine dynamically updates the DOM when these settings change.

Configuration Parameters

Parameter	Values	Effect
annotation_font	fraunces, kalam, helvetica, etc.	Sets font-family for margin notes and exports.
annotation_font_size	small, default, large	Adjusts pixel sizes (12px, 14px, 16px).
annotation_mode	overview, depth, all	Toggles visible annotation type sets.
theme	light, dark	Determines accent colors and background opacities.

Sources: extension/src/content/export-pdf.ts:29-45, extension/src/content/index.ts:1095-1172

The DOM Rendering Engine serves as the bridge between abstract data and the user's visual experience, ensuring that annotations remain stable, interactive, and stylistically consistent across different web environments.