Native PDF Engine & Annotations
Relevant source files
The following files were used as context for generating this wiki page:
The Native PDF Engine in ThinkEx provides a high-performance, interactive environment for viewing, searching, and annotating PDF documents. Built upon @embedpdf and powered by a shared PDFium engine, it integrates tightly with the workspace's AI capabilities, allowing users to extract text context for chat, navigate via citations, and persist reading states.
The engine supports advanced features such as Optical Character Recognition (OCR) for text extraction, spatial annotations (highlights/notes), and marquee capture for visual region selection. This system ensures that PDFs are not just static files but active, queryable knowledge sources within the ThinkEx canvas. Sources: src/components/pdf/AppPdfViewer.tsx, README.md:46-52
Core Architecture & Engine Integration
The PDF viewer is built using a plugin-based architecture centered around the EmbedPDF component. It utilizes a shared engine (Pdfium) provided via useEngineContext to ensure efficient resource usage across multiple PDF instances.
Plugin System
The system registers multiple plugins to handle specific PDF functionalities:
- Viewport & Scroll: Manages document rendering, page layout, and scrolling behavior.
- Zoom & Pan: Handles scaling (Fit Width, Zoom levels) and touch/mouse panning.
- Render & Tiling: Optimizes rendering for large documents by using tile-based loading.
- Interaction Manager: Coordinates pointer events across different layers (Selection vs. Annotation).
Sources: src/components/pdf/AppPdfViewer.tsx:490-530
Component Data Flow
The following diagram illustrates how the AppPdfViewer initializes the engine and manages document states.
The diagram shows the hierarchy of layers within the PDF viewer once a document is successfully loaded. Sources: src/components/pdf/AppPdfViewer.tsx:556-650
State Persistence & Navigation
ThinkEx implements robust state management to ensure a seamless reading experience, including persisting the user's position and handling AI-driven navigation.
PDF State Persister
The PdfStatePersister component tracks the currentPage, zoomLevel, and scrollOffset. It saves these values to localStorage using a key prefixed with pdf-state- and the encoded source URL. This allows users to return to their exact previous location when re-opening a document. Sources: src/components/pdf/AppPdfViewer.tsx:53-121
AI Context & Citation Sync
The engine synchronizes with the AI Assistant in two primary ways:
- Active Page Sync: The
PdfActivePageSynccomponent updates the global UI store with the current page number, allowing the AI to prioritize "what the user is currently looking at". - Citation Highlighting: When a user clicks an AI-generated citation (e.g.,
<citation>PDF Title | p. 5</citation>), thePdfCitationHighlightSynccomponent triggers a text search for the quoted excerpt and scrolls the viewer to the specific page and coordinates.
Sources: src/components/pdf/AppPdfViewer.tsx:432-488, src/lib/utils/format-workspace-context.ts:121-125
| Feature | Component | Logic |
|---|---|---|
| Persistence | PdfStatePersister | Stores currentPage and scrollOffset in localStorage. |
| AI Sync | PdfActivePageSync | Updates useUIStore.setActivePdfPage on scroll. |
| Citations | PdfCitationHighlightSync | Runs provides.searchAllPages and scroll.scrollToPage. |
| Initial Load | PdfInitialPageScroll | Handles 1-indexed page navigation for deep-linking. |
Text Extraction & OCR
PDF content is made accessible to the AI through a structured extraction process. If a PDF contains selectable text, the SelectionLayer handles it; otherwise, the system triggers an OCR workflow.
OCR Pipeline
When a PDF is added to a workspace, an OCR dispatch workflow is initiated. The extracted content is stored as ocrPages within the PdfData structure.
- Markdown Conversion: OCR results are converted into Markdown, including headers, footers, and table placeholders.
- Placeholder Replacement: The
replaceOcrPlaceholdersfunction identifies table tags like[id](https://github.com/ThinkEx-OSS/thinkex/blob/HEAD/id)and replaces them with actual structured table content.
Sources: src/app/api/workspaces/autogen/route.ts:500-550, src/lib/utils/format-workspace-context.ts:348-368
This sequence shows the asynchronous nature of PDF text extraction during workspace generation. Sources: src/app/api/workspaces/autogen/route.ts:560-600
Annotations & Marquee Capture
The viewer provides a dedicated AnnotationLayer and CapturePlugin for interactive work.
Annotation Layer
Users can create highlights and notes directly on the PDF. The AnnotationPluginPackage manages these objects, which include pageIndex and unique IDs. The AnnotationToolbar (when enabled via showAnnotations) provides the UI for selecting colors and annotation types. Sources: src/components/pdf/AppPdfViewer.tsx:210-220, src/components/pdf/AppPdfViewer.tsx:535-542
Marquee Capture
For content that cannot be easily extracted as text (like charts or complex diagrams), the CapturePluginPackage allows users to draw a "marquee" box over a region.
- Visual Understanding: Since the AI lacks direct visual perception of embedded charts, the viewer provides a "camera button" to take a screenshot of the selected area and add it to the chat context.
- Scale: Captures are typically rendered at a scale of
2.0inimage/pngformat to preserve legibility.
Sources: src/components/pdf/AppPdfViewer.tsx:543-547, src/lib/utils/format-workspace-context.ts:117-121
Search & Navigation Controls
The viewer includes a native search bar that intercepts standard keyboard shortcuts (Cmd/Ctrl + F).
Native Search Functionality
The PdfSearchBar component provides:
- Query Flags: Supports "Case sensitive" and "Whole word" matches via
MatchFlag. - Navigation: Prev/Next buttons navigate through results, automatically scrolling the viewport to the result's
pageCoordinates. - UI Integration: Displays current match index (e.g.,
3 / 10) and a loading spinner for large files.
Sources: src/components/pdf/AppPdfViewer.tsx:325-408
Page Controls
A floating overlay at the bottom of the viewer provides quick navigation. It includes:
- Direct Input: Users can click the page number to type a specific page to jump to.
- Visibility Logic: Controls fade in on mouse movement or scroll activity and fade out after 4 seconds of inactivity.
Sources: src/components/pdf/AppPdfViewer.tsx:243-306
Conclusion
The ThinkEx Native PDF Engine & Annotations system transforms standard PDFs into interactive, AI-aware components. By combining deep state persistence, automated OCR extraction, and a sophisticated plugin architecture, the engine ensures that document context is always available for reasoning and permanent knowledge capture. The integration of citation-based navigation and visual marquee capture bridges the gap between static documents and fluid AI conversations.