AGENTS.md

1## Overview
2 
3PDF.js is a Portable Document Format (PDF) viewer built with JavaScript, HTML5 Canvas, and CSS. It's a Mozilla project that provides a general-purpose, web standards-based platform for parsing and rendering PDFs without requiring native code or plugins.
4 
5## Common Commands
6 
7### Development Server
8```bash
9npx gulp server
10```
11Then open http://localhost:8888/web/viewer.html to view the PDF viewer. Test PDFs are available at http://localhost:8888/test/pdfs/?frame
12 
13### Building
14 
15Build for modern browsers:
16```bash
17npx gulp generic
18```
19 
20This generates `pdf.js` and `pdf.worker.js` in `build/generic/build/`.
21 
22Build for distribution (creates pdfjs-dist package):
23```bash
24npx gulp dist
25npx gulp dist-install    # Build and install locally
26```
27 
28### Testing
29 
30Run all tests:
31```bash
32npx gulp test
33```
34 
35Run unit tests only:
36```bash
37npx gulp unittest
38```
39 
40Run integration tests (browser-based tests using Puppeteer):
41```bash
42npx gulp integrationtest
43```
44 
45Run font tests:
46```bash
47npx gulp fonttest
48```
49 
50Run a single test file by modifying test/test_manifest.json or using test runner options.
51 
52### Linting and Formatting
53 
54Lint JavaScript:
55```bash
56npx gulp lint
57```
58 
59Format code (uses Prettier and ESLint):
60```bash
61npx eslint --fix <file>
62```
63 
64### Type Checking
65 
66Run TypeScript type checking:
67```bash
68npx gulp typestest
69```
70 
71## Architecture
72 
73### High-Level Structure
74 
75PDF.js has a multi-layer architecture that separates concerns between PDF parsing, rendering, and UI:
76 
77#### 1. Core Layer (`src/core/`)
78The core layer handles PDF parsing and interpretation. Key responsibilities:
79- **PDF parsing**: Parsing PDF structure, cross-reference tables, streams
80- **Font handling**: CFF, TrueType, Type1 font parsing and conversion (`font.js`, `fonts.js`, `cff_*.js`, `type1_*.js`)
81- **Image decoding**: JPEG, JBIG2, JPX/JPEG2000 decoders
82- **Operators**: Processing PDF drawing operators (`operator_list.js`, `evaluator.js`)
83- **XFA Forms**: XML Forms Architecture support (`src/core/xfa/`)
84- **Color spaces**: ICC profiles, device color spaces (`colorspace.js`, `icc_colorspace.js`)
85- Runs in a Web Worker for performance isolation
86 
87Entry point: `src/pdf.worker.js`
88 
89#### 2. Display Layer (`src/display/`)
90The display layer provides the API for rendering PDFs to canvas and managing documents. Key components:
91- **API**: Main public API (`api.js`) - `PDFDocumentProxy`, `PDFPageProxy`, `getDocument()`
92- **Canvas rendering**: Renders PDF operations to HTML5 canvas (`canvas.js`)
93- **Text layer**: Extracts and positions text for selection/search (`text_layer.js`)
94- **Annotation layer**: Renders and handles PDF annotations (`annotation_layer.js`)
95- **Editor layer**: Supports PDF editing (annotations, highlights, stamps) (`editor/`)
96- **Metadata**: Parses XMP metadata (`metadata.js`)
97- **Streams**: Handles PDF data fetching (fetch, network, node) (`fetch_stream.js`, `network.js`, `node_stream.js`)
98 
99Entry point: `src/pdf.js`
100 
101#### 3. Scripting Layer (`src/scripting_api/`)
102Implements JavaScript execution for interactive PDFs (form calculations, validations, button actions).
103- Sandboxed execution environment
104- Implements Acrobat JavaScript API objects (App, Doc, Field, etc.)
105 
106Entry points: `src/pdf.scripting.js`, `src/pdf.sandbox.js`
107 
108#### 4. Web Viewer (`web/`)
109The complete PDF viewer application with UI. Key components:
110- **Main app**: Application orchestration (`app.js`)
111- **Viewer**: Page rendering and layout (`pdf_viewer.js`, `pdf_page_view.js`)
112- **Toolbar**: Zoom, page navigation, print, download controls
113- **Sidebar**: Thumbnails, outlines, attachments (`pdf_sidebar.js`, `pdf_thumbnail_view.js`, `pdf_outline_viewer.js`)
114- **Find controller**: Text search functionality (`pdf_find_controller.js`)
115- **Annotation editors**: UI for creating/editing annotations (`annotation_editor_layer_builder.js`)
116- **Presentation mode**: Full-screen presentation (`pdf_presentation_mode.js`)
117 
118Entry point: `web/viewer.html` + `web/viewer.mjs`
119 
120#### 5. Shared Utilities (`src/shared/`)
121Common utilities used across layers:
122- **Message handling**: Worker communication (`message_handler.js`)
123- **Utilities**: Common functions and constants (`util.js`)
124- **Image utilities**: Image processing helpers (`image_utils.js`)
125 
126### Worker Communication
127 
128PDF.js uses a Web Worker architecture:
129- Main thread (`display` layer) communicates with worker thread (`core` layer) via `MessageHandler`
130- Keeps PDF parsing off the main thread for better performance
131- Messages include: page rendering requests, text content extraction, metadata queries
132 
133### Build System
134 
135- Uses **Gulp** for build orchestration (`gulpfile.mjs`)
136- **Webpack** bundles modules into browser-compatible formats
137- **Babel** transpiles for browser compatibility (configurable targets in gulpfile)
138- Preprocessor replaces build-time constants (e.g., `typeof PDFJSDev !== "undefined"` checks)
139- Multiple build targets: generic, components, minified, legacy (older browser support)
140 
141### External Dependencies
142 
143Located in `external/`:
144- **bcmaps**: Binary CMaps for CJK fonts
145- **standard_fonts**: Core 14 PDF fonts metrics
146- **cmapscompress**: Tools for compressing CMaps
147- **openjpeg**: JPEG2000 decoder (WASM)
148- **quickjs**: JavaScript engine for sandboxed execution
149 
150### Translations
151 
152Translations in `l10n/` are imported from Mozilla Firefox Nightly. Only the file l10n/en-US/viewer.ftl can be updated.
153 
154## Development Notes
155 
156### Adding New Features
157 
158When adding features that span multiple layers:
1591. Start with the `core` layer if parsing/interpretation changes are needed
1602. Update the `display` layer API if new capabilities need exposure
1613. Modify the `web` viewer if UI changes are required
1624. Ensure worker communication handles new message types
163 
164### Preprocessor Directives
165 
166Code uses preprocessor checks for build-time conditionals:
167```javascript
168if (typeof PDFJSDev !== "undefined" && PDFJSDev.test("GENERIC")) {
169  // Generic build-specific code
170}
171```
172 
173Common flags: `GENERIC`, `MOZCENTRAL`, `CHROME`, `MINIFIED`, `TESTING`, `LIB`, `SKIP_BABEL`, `IMAGE_DECODERS`
174 
175### Testing
176 
177- Unit tests use Jasmine framework (`test/unit/`)
178- Integration tests use Puppeteer for browser automation (`test/integration/`)
179- Test PDFs downloaded from manifest (`test/test_manifest.json`)
180- Reference images for visual regression testing (`test/ref/`)
181 
182### Code Style
183 
184- Uses ESLint with custom configuration (`eslint.config.mjs`)
185- Prettier for formatting
186- Stylelint for CSS
187- No semicolons required (ASI enabled)
188- Single quotes for strings
189 
190### Pull Request Process
191 
192- Keep PRs focused on a single issue
193- Provide a test PDF if the issue is PDF-specific
194- Ensure tests pass (`npx gulp test`)
195- Run linting (`npx gulp lint`)
196- Follow existing code patterns
197- Don't modify translations directly (they come from Firefox)
198 
199### Performance Considerations
200 
201- Core parsing runs in a Web Worker - keep main thread work minimal
202- Canvas rendering can be expensive - use appropriate scale factors
203- Text layer generation is separate from rendering - can be deferred
204- Annotation layer is optional - only enable when needed
205