Design a PDF viewer

Requirements: what to ask before drawing anything

Every browser can already show a PDF, so the first thing to find out is why that isn't enough here. Usually the answer is a mix of three things: the built-in viewer looks and behaves differently in Chrome, Firefox, and Safari; it can't be extended with our own toolbar, highlights, or signing fields; and on some phones it doesn't show inline at all. Once you know which of these matter, the rest of the questions decide how much of a PDF engine you must ship to the browser.

Ask from the outside in: who embeds the viewer, what kind of documents, how big, on which devices, and what users do with them besides reading. The table shows the answers this guide assumes and what would move if the answer changed.

Functional requirements

• Open a PDF from a URL (or bytes already in memory) and show page 1 fast, even for a large file.
• Scroll through all pages continuously, with a page counter and a page number input.
• Zoom: fit width, fit page, preset levels from 25% to 400%, Ctrl plus wheel, and pinch on touch. Rotate pages by 90 degrees.
• A sidebar with page thumbnails and the document outline (bookmarks).
• Select and copy text. Find text across the whole document with a match count and next and previous.
• Follow links inside the document and to the web.
• Add highlights and comments, stored per user, shown to collaborators.
• Fill AcroForm fields (text boxes, checkboxes) and submit or save the values.
• Print and download, if the host allows them.
• Deep links: a URL that opens page 47 of a manual, or a search term.

Non-functional requirements

• Page 1 visible in under 1.5 seconds on a good connection for a 50 MB linearized file, without downloading all 50 MB first.
• Scrolling stays at 60 frames per second: no main-thread task over 50 ms while scrolling, so parsing happens off the main thread and painting runs in small slices.
• Canvas memory stays under a budget, about 150 MB on phones, at any zoom level and any document length.
• The viewer's own code costs little on pages that never open a PDF: it loads lazily, on first use.
• Untrusted files are safe to open: a PDF must not be able to run code in our origin.
• Keyboard and screen reader users can open, navigate, search, and read the text the file provides.

Out of scope, and why

Editing page content (moving text, reordering pages), creating PDFs, and digital signature cryptography are separate products. Signing a contract by placing a drawn signature image is close to an annotation, so the design should leave room for it, but verifying certificate-based signatures is a server job. Real-time co-editing of annotations is a follow-up: we store them on the server and refresh, which covers most review workflows.

What makes a PDF viewer hard

A PDF is not a web page. A web page is a stream of text that the browser lays out to fit your screen. A PDF is a set of fixed pages, each one a little program of drawing instructions: move here, set this font, draw these glyphs at these exact coordinates, fill this path, paint this image. Nothing reflows, and five properties of that format drive every decision in this guide.

• Pages are drawings, not markup. To show a page you must run its drawing instructions with a PDF engine and paint the result into pixels, usually a canvas. The browser's layout engine can't help, and there is no DOM text to select or search unless you build one.
• Files are big and random-access. A PDF has a cross-reference table (the xref) that says at which byte each object starts. That table normally sits at the end of the file. A viewer that reads bytes in order can't draw page 1 until it has the end of the file, unless it can ask for specific byte ranges.
• Pixels are expensive. A canvas costs 4 bytes per pixel. One A4 page at 200% zoom on a phone with a device pixel ratio of 3 (3 screen pixels per CSS pixel in each direction) is about 32 million pixels, or 128 MB. Ten of those and the tab crashes. Memory, not CPU, is the limit you hit first.
• Coordinates are not screen coordinates. PDF positions are in points (1/72 inch) with the origin at the bottom-left of the page and y pointing up. The screen has its origin at the top-left, y pointing down, scaled by zoom and device pixel ratio, maybe rotated. Every highlight, link, form field, and search match has to cross between the two.
• Files are untrusted programs. A PDF can contain JavaScript, embedded fonts with their own instructions, forms that submit data, and links to anywhere. Parsing it is parsing attacker-controlled input with a large, complex parser.

The wireframe below names the parts of the viewer we are building, so the later chapters have words to point at: the toolbar, the sidebar with thumbnails and outline, the scrolling page column, and the find bar.

Who draws the pages: built-in viewer, PDF.js, an SDK, or the server

The naive design is one line: iframe src="/files/contract.pdf". The browser picks its own viewer and shows the file. It costs zero bytes of JavaScript and works on most desktops. Then the bug reports arrive.

Chrome shows its viewer (built on the PDFium engine), Firefox shows PDF.js, and Safari shows Apple's own viewer: three toolbars, three zoom behaviors, three keyboard maps. On phones it's uneven. An iframe may show only the first page, a download button, or nothing, depending on the browser and version. You can check with navigator.pdfViewerEnabled, which is false when the browser can't show PDFs inline.

Worse, you can't add a highlight tool, a signing field, or analytics. The viewer is the browser's, not yours, and your page can't reach into it.

So the real question is which engine turns PDF bytes into pixels, and where it runs. There are four realistic answers.

The figure compares the four options on what matters for this product (PDF.js sizes measured for pdfjs-dist 6.4, minified and gzipped). No option wins every row: the decision is which costs you can live with.

How PDF.js turns bytes into a page you can read

Before designing around PDF.js, know what it does with a file, because every later decision (virtualization, zoom, search) works with these pieces. PDF.js splits the work across two threads and builds each page from three stacked layers.

Two threads: the worker parses, the main thread paints

Parsing a PDF is heavy: decompressing streams, decoding fonts and images, reading the cross-reference table, turning each page's content stream into drawing commands. PDF.js does all of that in a web worker, a background thread with no access to the DOM. The worker sends the main thread an operator list for each page: a compact list of drawing calls like setFont, showText, fill, paintImageXObject, with their arguments.

Fonts are converted to OpenType and loaded with the CSS Font Loading API; images arrive already decoded. The main thread then replays the operator list onto a canvas 2D context. Parsing never blocks scrolling. Painting does, but it's the cheaper part, and PDF.js runs it in short time slices so a complex page doesn't freeze the tab.

import { getDocument, GlobalWorkerOptions } from "pdfjs-dist";

GlobalWorkerOptions.workerSrc = "/static/pdf.worker.min.mjs";

const pdf = await getDocument({ url: "/files/manual.pdf" }).promise;
const page = await pdf.getPage(1);

const zoom = 1.5;
const viewport = page.getViewport({ scale: zoom * (96 / 72) });
const dpr = window.devicePixelRatio || 1;

const canvas = document.querySelector("canvas")!;
canvas.width = Math.floor(viewport.width * dpr);   // device pixels
canvas.height = Math.floor(viewport.height * dpr);
canvas.style.width = `${viewport.width}px`;        // CSS pixels
canvas.style.height = `${viewport.height}px`;

const task = page.render({
  canvas,
  viewport,
  transform: dpr === 1 ? undefined : [dpr, 0, 0, dpr, 0, 0],
});
await task.promise; // task.cancel() if the page scrolls away first

Three details in that code matter later. First, 96 / 72: a PDF point is 1/72 inch and a CSS pixel is 1/96 inch, so 100% zoom means 1.333 CSS pixels per point. An A4 page (595 by 842 points) is therefore 794 by 1123 CSS pixels at 100%.

Second, the canvas has two sizes: its backing store in device pixels (sharp on a Retina screen) and its CSS size, and memory follows the first. Third, render returns a task you can cancel, so a fast scroll past 40 pages can cancel 38 renders instead of queueing them.

Three layers per page

A canvas is just pixels: you can't select text in it, a screen reader sees nothing, and links don't click. So each page is a stack of three same-sized boxes, positioned exactly on top of each other.

• Canvas layer: the painted page. Everything you see comes from here.
• Text layer: one absolutely positioned span per run of text, from page.getTextContent(), which returns each string with its transform matrix and width. The text is transparent, sized with the same font metrics, and stretched with a CSS scaleX so each span covers exactly the glyphs painted underneath. You select and copy real DOM text; the browser's selection highlight shows through. PDF.js builds it with its TextLayer class.
• Annotation layer: real DOM elements for interactive parts of the page: a elements for links, input, select, and textarea elements for form fields, popups for comments already in the file. PDF.js builds it with its AnnotationLayer class from page.getAnnotations().

Why not draw the text into the canvas and also keep it hidden in the DOM, like an accessible alternative? Because the spans must sit exactly over the glyphs: that's what makes a drag-select follow your mouse across the painted words and what lets find draw highlights in the right place. The text layer is not a copy of the text, it's a transparent map of where the text is.

Loading big files: page 1 before the last byte

The naive loader fetches the whole file, then parses it. For a 2 MB invoice that's fine. For a 120 MB scanned manual on a 20 Mbps phone connection, that's 48 seconds of spinner before anything appears, and the user wanted page 3. We want page 1 on screen after a few hundred kilobytes, whatever the file size.

Where the bytes for page 1 live

A PDF is a pile of numbered objects (pages, fonts, images, content streams) plus a cross-reference table (xref) that gives the byte offset of every object. In a normal PDF the xref and a startxref pointer sit at the very end of the file, and page 1's objects can be anywhere. So the reader must look at the end first, then jump around. That's a perfect fit for HTTP range requests: ask the server for just the bytes you need.

GET /files/manual.pdf HTTP/1.1
Range: bytes=125763584-125829119

HTTP/1.1 206 Partial Content
Accept-Ranges: bytes
Content-Range: bytes 125763584-125829119/125829120
Content-Length: 65536
Content-Type: application/pdf
ETag: "a91f3c"

A linearized PDF (Acrobat calls it "Fast Web View") is rewritten so page 1 needs no jumping. The file starts with a small linearization dictionary (within the first 1,024 bytes) that says the file is linearized and how long it is. Next come a cross-reference section for page 1, the document catalog, hint tables that say where every other page's objects are, and then page 1's own objects. A viewer that reads the first chunks can draw page 1 right away.

You can linearize at upload time with a tool like qpdf --linearize, which is cheap insurance for big files.

What the server must send, or ranges silently turn off

PDF.js decides from the first response's headers whether to use ranges. In its source (validateRangeRequestCapabilities), ranges are used only when all of these hold. If any fails, it quietly falls back to streaming the whole file, and nobody notices until someone opens a 200 MB file on a phone.

• Content-Length is present. Without a total length there is no way to compute chunk positions.
• The file is bigger than two chunks (by default 2 x 64 KB = 128 KB). Smaller files are just downloaded.
• Accept-Ranges: bytes is present.
• No compression: Content-Encoding is absent or identity. A gzipped response has byte offsets that don't match the file, so ranges can't work. Don't let a CDN gzip PDFs; they're mostly compressed inside anyway.
• For a file on another origin, CORS allows it: Access-Control-Allow-Origin for our origin, Access-Control-Allow-Headers: Range so a preflighted Range request is allowed, and Access-Control-Expose-Headers: Accept-Ranges, Content-Range, Content-Encoding, because JavaScript can't read headers outside the CORS-safelisted set (which already includes Content-Length) unless they're exposed. The CORS lesson covers why.

Caching works with ranges too. The CDN stores the full object and answers range requests from it, and the browser's HTTP cache can store 206 responses. Version the URL (or rely on a strong ETag) so a replaced file never mixes chunks from two versions: PDF.js would read an xref from the old file and objects from the new one, which shows as corrupted pages. The http-caching and cdn-caching lessons cover the headers.

Rendering only what you see, within a memory budget

The naive viewer creates a canvas for every page and renders them all. A 30-page invoice survives. A 600-page manual at 100% on a laptop with a device pixel ratio of 2 needs 600 canvases of 14 MB each: 8.6 GB. The tab dies long before that, often with no error, just a blank page or a crash screen, because memory is the budget here and rendering is how you spend it.

The fix is the same idea as list virtualization (the virtualization lesson and the virtualized-list guide cover the windowing math): keep a lightweight placeholder for every page so the scrollbar is right, and paint real canvases only for pages near the viewport. Three things make pages different from list rows: each row is a heavy bitmap, not a few DOM nodes; rendering one takes 50 to 500 ms, not microseconds; and its cost grows with the square of the zoom.

Canvas memory math

A canvas backing store costs width x height x 4 bytes, in device pixels. An A4 page is 794 by 1123 CSS pixels at 100%. Multiply each side by zoom and by devicePixelRatio.

Browsers also cap a single canvas, and none of them document the limit; these are measured values that change between versions. Desktop Chrome and Firefox allow up to 32,767 pixels per side, with a total area limit in the hundreds of millions of pixels. iOS Safari limits a canvas to about 16.7 million pixels (4,096 x 4,096). Exceed the limit and the canvas silently draws nothing.

That's why PDF.js's viewer has a maxCanvasPixels option: 2 to the 25th (about 33.5 million pixels) on desktop and 5,242,880 (5 megapixels) on iOS and Android. Recent versions also cap each side (maxCanvasDim, 32,767) and cap the area relative to the screen (capCanvasAreaFactor). Above the cap the viewer renders at a lower resolution and stretches the canvas with CSS, which looks slightly soft. It then adds a second, small detail canvas on top that paints only the part of the page near the viewport at full sharpness.

Placeholders need sizes before pages load

The scrollbar must be right from the start, or the page number under the thumb is wrong and jumping to page 400 lands somewhere else. That needs every page's size before rendering any of them. Getting a page's size from PDF.js means loading that page's dictionary, which with range loading can mean a request per page.

There are two practical answers. One: assume every page is the size of page 1 (true for most documents) and correct each placeholder when its page loads, keeping the reading position anchored when a correction happens above the viewport. Two: have the upload pipeline write a small manifest of all page sizes and rotations, which the viewer fetches alongside the file. We do both: the manifest when it exists, page 1's size when it doesn't.

Freeing a canvas has a trick. Removing it from the DOM doesn't free its memory until garbage collection runs, which may be seconds later; on iOS Safari, which also limits total canvas memory per page, slow collection is how you hit that limit. Set canvas.width = 0 and canvas.height = 0 before dropping it: that releases the backing store right away.

Text layers need virtualizing too: a dense page can have 3,000 spans. Drop the text and annotation layers of far-away pages and rebuild them from cached text content, which is cheap.

Zoom and rotate without losing your place

Zoom looks like one number, but it touches everything: every page's size, every canvas's resolution, the scroll position, the text and annotation layers, and the memory budget. The naive version sets scale and re-renders every visible page on each change.

A trackpad pinch fires 60 or more wheel events per second. Each one starts a 200 ms render that the next event cancels, so the user sees blank or flickering pages until they stop. And the page they were reading has drifted off screen, because the scroll offset stayed the same while everything above it got taller.

Keeping the reading position anchored

When zoom changes, the point under the user's fingers (or under the mouse for Ctrl plus wheel, or the center of the viewport for the toolbar buttons) must stay under them. Everything above that point grows, so the scroll offset must grow with it. Record the anchor in document coordinates before the change, then set the scroll so the same document point lands at the same screen point after.

function zoomAround(scroller: HTMLElement, oldZoom: number, newZoom: number,
                    anchorX: number, anchorY: number) {
  // anchorX/Y: the anchor in viewport pixels, relative to the scroller
  const docX = (scroller.scrollLeft + anchorX) / oldZoom;
  const docY = (scroller.scrollTop + anchorY) / oldZoom;

  setZoom(newZoom); // resizes page boxes synchronously (CSS sizes only)

  scroller.scrollLeft = docX * newZoom - anchorX;
  scroller.scrollTop = docY * newZoom - anchorY;
}

scroller.addEventListener("wheel", (e) => {
  if (!e.ctrlKey) return;          // trackpad pinch also arrives as ctrl+wheel
  e.preventDefault();              // stop the browser zooming the whole page
  const r = scroller.getBoundingClientRect();
  const next = clamp(zoom * Math.exp(-e.deltaY / 300), 0.25, 4);
  zoomAround(scroller, zoom, next, e.clientX - r.left, e.clientY - r.top);
  scheduleSharpRender();           // debounced: runs about 200 ms after the last event
}, { passive: false });

Pass passive: false explicitly. Wheel listeners on window, document, or body are passive by default for scroll performance, and a passive listener can't call preventDefault, so if the listener ever moves up to the document the browser would zoom the whole page instead. On touch screens, set CSS touch-action: pan-x pan-y on the scroller so the browser handles one-finger panning but leaves two-finger pinch to our pointer event handler.

Fit modes and rotation

• Fit width: zoom = (container width minus padding) divided by the page's CSS width at 100%. It's the default on phones, where a 390-pixel screen shows an A4 page at about 47%.
• Fit page: the smaller of the width ratio and the height ratio, so a whole page is visible. Good for slides.
• Fit modes are modes, not numbers: store fit-width in state and recompute the zoom when the container resizes (a ResizeObserver), the sidebar opens, or the phone rotates.
• Rotation is a view setting in steps of 90 degrees, passed to page.getViewport({ scale, rotation }). At 90 or 270 degrees width and height swap. It doesn't change the file; if users want rotation saved, store it with their view settings, or have the server rewrite the page's /Rotate entry.

Getting around: thumbnails, outline, page numbers, deep links

A 600-page manual is read by jumping, not scrolling. Four tools do the jumping, and each has a cheap version and a version that breaks.

Thumbnails: the sidebar is a second virtualized list

The naive sidebar renders 600 small canvases when it opens. Even at 100 by 140 pixels that's 600 page renders competing with the main view, and every one needs that page's bytes fetched. Treat the sidebar as its own virtualized list with its own render queue, at a lower priority than the main view: main view pages first, thumbnails only when the main queue is empty. Three tricks make thumbnails cheap.

• If the main view has already rendered a page, draw the thumbnail by shrinking that canvas with drawImage into a small one. No second render of the page.
• Otherwise render at a tiny scale: a 120-pixel-wide thumbnail at devicePixelRatio 2 is 240 by 340 device pixels, about 0.3 MB.
• Better still for big files: the upload pipeline already makes thumbnail images (WebP, a few KB each). Show those as plain img elements with loading="lazy". They appear before PDF.js even loads, and the client renders nothing.

Outline and named destinations

Many PDFs carry an outline (bookmarks): a tree of titles that point to destinations. pdf.getOutline() returns it as nested items with a title, a dest, or a url. A dest is either an explicit array (a page reference plus a position, like "page 12, top at y = 700") or a name you look up with pdf.getDestination(name). Turn the page reference into a page number with pdf.getPageIndex(ref), and scroll so the target y is at the top.

Render the outline as a tree view with proper keyboard support (arrow keys expand and move, Enter jumps). If the file has no outline, hide the tab rather than showing an empty panel.

Page number input and page labels

The toolbar shows "47 of 612" and lets you type a page. The first detail is which page counts as "current" while two pages share the screen. Pick the page that covers the most of the viewport, or the one crossing a line a third of the way down; both feel right, and an IntersectionObserver with several thresholds tells you visible ratios without scroll math.

The second detail is that books number pages their own way: the cover, then i to xii, then 1. PDFs can store page labels, available from pdf.getPageLabels(). Show the label ("vii") and the position ("9 of 612"), and accept either in the input.

Deep links

Deep links are in our requirements: a help article that says "see page 47" should open page 47. There is a standard fragment syntax for PDFs, first published by Adobe (as its "PDF open parameters" and in RFC 3778) and now part of the PDF 2.0 standard. RFC 8118, which registers the application/pdf media type, summarizes it: #page=47, #nameddest=Chapter3, #zoom=150, #search=warranty, and a few more.

Support varies by viewer. PDF.js's viewer reads page, nameddest, zoom, and search; other built-in viewers support fewer, with page the most widely honored. Use the same syntax in our viewer's URL so links work both in our app and, where supported, when the file opens in a browser's built-in viewer.

Text selection and find across the whole document

With a text layer in place, the browser's own Ctrl+F finds text in it. That's the naive version, and virtualization breaks it: the browser can only find text that's in the DOM, and only the 3 to 10 pages near the viewport have text layers. Searching a 600-page manual for "warranty" finds the 2 matches on screen and misses the 40 elsewhere. Find in a PDF viewer has to search the document, not the DOM.

Matching text that was never written for searching

PDF text is positioned glyph runs, not sentences. A word can be split into several items ("war" and "ranty" set with different spacing), a line-end hyphen can break it ("war-" then "ranty"), ligatures replace letter pairs (the single glyph "fi" for "fi"), and accents may be stored as separate combining marks. So each page's items are joined into one string, normalized, and a map is kept from each position in that string back to an item index and a character offset in it.

type PageText = { text: string; map: { item: number; char: number }[] };

function buildPageText(items: { str: string; hasEOL?: boolean }[]): PageText {
  let text = "";
  const map: PageText["map"] = [];
  items.forEach((it, item) => {
    const hyphenEOL = it.hasEOL && it.str.endsWith("-");
    const s = hyphenEOL ? it.str.slice(0, -1) : it.str;  // "war-" + EOL joins "ranty"
    const norm = s.normalize("NFKD")                    // "fi" -> "fi", "é" -> "e" + mark
      .replace(/\p{M}/gu, "").toLowerCase();             // drop accents, ignore case
    for (let c = 0; c < norm.length; c++) {
      text += norm[c];
      map.push({ item, char: Math.min(c, s.length - 1) });
    }
    if (it.hasEOL && !hyphenEOL) { text += " "; map.push({ item, char: s.length }); }
  });
  return { text, map };
}

The mapping is approximate when normalization changes length (one ligature glyph becomes two letters). The hyphen rule also joins compounds like "well-known" that break at a line end, so real viewers track offsets and hyphens more carefully. The shape is right, though: search a clean string, then translate each match back to spans on the page.

Highlighting wraps the matched characters of the right spans in a mark-like element with a background, or draws boxes over them in a separate layer. Either way it happens only when the page's text layer exists, so highlights for page 300 are applied when page 300 renders.

• Search progressively: pages near the current page first, then outward, updating "3 of 41" as results arrive. Debounce typing by about 250 ms.
• "Next" from the last match on page 12 goes to the first match on page 13 or later, which may need a scroll, a render, and then the highlight. Mark the current match differently from the others.
• Announce the count in a polite live region ("41 matches"), not on every keystroke. The screen-readers lesson covers live regions.
• Cache extracted text per document (in memory, or IndexedDB for files reopened often). The second search is instant.
• Scanned PDFs have no text to find, as the text layer warning in the PDF.js chapter explains. Detect it (a page with a big image and no text items), tell the user "This document has no searchable text", and run OCR on the server. A tool like OCRmyPDF adds an invisible text layer to the PDF, which PDF.js then reads like any other text.

Annotations and forms: anchoring to the page, not the screen

A reviewer highlights a clause at 150% zoom on a laptop. The naive version stores the highlight as screen pixels: { page: 12, x: 310, y: 482, w: 220, h: 18 }. A colleague opens it on a phone at 47% with the page rotated, and the highlight lands on the wrong line or off the page. Screen pixels depend on zoom, device pixel ratio, rotation, and layout, but the page itself doesn't change, so store positions in the page's own coordinates.

PDF user space and the viewport transform

PDF user space measures in points (1/72 inch) from the page's bottom-left corner, with y pointing up. An A4 page runs from (0, 0) to (595, 842). The screen measures in CSS pixels from the top-left, with y pointing down. PDF.js's PageViewport holds the transform between the two for a given scale and rotation.

The viewport has helpers both ways: viewport.convertToPdfPoint(x, y) when the user drags, and viewport.convertToViewportPoint(x, y) on two opposite corners when drawing a stored highlight. (Version 6.1 removed the old convertToViewportRectangle helper, which did the same for a whole rectangle.) At 100% and no rotation, a point at y = 700 in PDF space is 142 points from the top, which is 189 CSS pixels down.

A text highlight isn't one rectangle: a selection across three lines is three rectangles (in PDF's own format, a list of quadrilaterals). Store the list, plus the selected text itself so the comment list can show "liability is limited to" without rendering the page. Build the rectangles from the selection's Range.getClientRects() on the text layer, converting each to PDF space.

Filling forms

AcroForm fields (the standard PDF form type) come from page.getAnnotations() as widget annotations with a field name, type, rectangle, and current value. The annotation layer renders them as real input, select, and textarea elements, positioned and sized from their PDF rectangles, so typing, tab order, autofill, and screen readers all work natively. PDF.js keeps the values in pdf.annotationStorage.

To submit, read the values by field name and post them as JSON; to produce a filled PDF, call pdf.saveDocument() for the bytes, or fill the original on the server. The older XFA form format is mostly unsupported outside Adobe's own readers. PDF.js renders some of it with its enableXfa option, but plan to tell users when a form can't be filled.

Architecture and data: who owns what

With the hard parts decided, put names on the pieces. The main rule: PDF.js is wrapped by one service and nothing else talks to it. That keeps its async, cancellable, memory-heavy objects in one place, lets us upgrade it (which security requires, as the security chapter shows), and gives the UI plain data to render.

The data flow for opening and reading a document goes in one direction: the host passes src; the document service asks the CDN for byte ranges and hands them to the worker; the worker answers with page sizes, operator lists, and text; the scheduler paints canvases for the pages the virtualizer says are visible; user actions change the store, which changes the visible set or zoom, which schedules new renders. Annotation writes go the other way, from a page's highlight layer to the store to the API.

The client-side data model

type DocInfo = {                  // document service, in memory
  id: string; version: string;     // the version keys caches and annotations
  numPages: number;
  pageSizes: { w: number; h: number; rotate: 0 | 90 | 180 | 270 }[];
  outline: OutlineNode[] | null;
  pageLabels: string[] | null;
};

type ViewState = {                 // viewer store, mirrored in the URL hash
  page: number;
  zoom: number | "fit-width" | "fit-page";
  rotation: 0 | 90 | 180 | 270;
  sidebar: "thumbnails" | "outline" | null;
  query: string;
};

type RenderedPage = {              // render scheduler, LRU by lastSeen
  page: number; scale: number; bytes: number; lastSeen: number;
  canvas: HTMLCanvasElement;
};

type Annotation = {                // server data, cached and optimistic
  id: string; docVersion: string; page: number;
  kind: "highlight" | "comment";
  rects: [number, number, number, number][]; // PDF user space
  quote?: string; body?: string; authorId: string; createdAt: string;
};

Notice what isn't in global state: canvases and PDF.js page proxies. They are big, mutable, and tied to the worker, so they live inside the scheduler and the service, keyed by page number, and the UI only sees "page 12 is rendered at scale 2". Extracted text lives in the service's cache, optionally saved to IndexedDB by document version so reopening a big manual skips extraction. Annotations are server state with the usual cache, optimistic insert, and rollback on error.

The component API teams will use

Many teams embed this viewer: a file preview wants a toolbar and nothing else, contract signing wants form fields and a "Sign" button, the help center wants deep links and search. The API should make the simple case one line and the complex cases possible without forking. The component-api-design lesson covers the general rules; here's how they land for a PDF viewer, in the same style as our video player.

type PdfViewerProps = {
  src: string | Uint8Array;                 // URL (range-loaded) or bytes
  onRequestUrl?: () => Promise<string>;     // fresh signed URL after a 403
  password?: () => Promise<string>;         // asked only if the file is encrypted

  page?: number; defaultPage?: number;      // controlled or uncontrolled
  zoom?: Zoom; defaultZoom?: Zoom;          // number or "fit-width" | "fit-page"
  rotation?: 0 | 90 | 180 | 270;

  onPageChange?: (page: number) => void;
  onZoomChange?: (zoom: Zoom) => void;
  onLoad?: (info: { numPages: number; title?: string }) => void;
  onError?: (e: ViewerError) => void;       // "network" | "password" | "invalid" | "unsupported"
  onTextSelect?: (s: { page: number; text: string; rects: Rect[] }) => void;

  allowDownload?: boolean; allowPrint?: boolean;
  plugins?: ViewerPlugin[];                 // annotations, signing, analytics
  toolbar?: (slots: ToolbarSlots) => React.ReactNode;
};

• Controlled or uncontrolled: pass defaultPage and let the viewer own it, or pass page and onPageChange when the host must drive it (a contract checklist that jumps to each field). Never require the controlled form for simple use.
• An imperative handle through a ref for actions that aren't state: scrollToPage(n), find(query), print(), getSelection(), scrollToRect(page, rect).
• Plugins get a small, stable context instead of PDF.js objects: the viewer store, coordinate helpers (toPdfRect, toCssRect), a layer they can draw into for each page, and toolbar slots. The annotation tools and the signing fields are plugins, which proves the plugin API is good enough.
• Errors are typed, so hosts can show a password prompt, a "file is damaged" state, or a retry. A failure to load must never be a blank box.
• Lazy by default: the package entry is a tiny shell that import()s the viewer and PDF.js on mount, so a page that might show a PDF doesn't pay 500 KB until it does. Preload the worker on hover of a file link.

Note what's not in the API: PDF.js's own objects. If onLoad handed out the PDFDocumentProxy, every team would depend on PDF.js's API version, and the next PDF.js upgrade would break them. The plugin context is our contract; PDF.js is our implementation detail.

Printing, downloading, and opening untrusted files safely

Printing a canvas-rendered document is less obvious than it sounds. window.print() prints the page's DOM, and our DOM holds a dozen canvases sized for the screen plus a thousand empty placeholders. Two approaches work.

The first is what PDF.js's viewer does. It renders every page into a canvas at a print resolution (150 DPI by default), turns each into an image in a hidden print container, then calls print(). An A4 page at 150 DPI is 1240 by 1754 pixels, about 8.7 MB as a bitmap, so a 300-page print job must render page by page into compressed images and show progress, or it runs out of memory.

The second hands the browser the original file in a hidden iframe and calls print on it. That keeps vector text sharp where the browser has a built-in viewer, but behaves differently per browser. Use the first as the default, and raise the resolution to 300 DPI for documents where print quality matters, like forms and contracts.

Hosts will ask for allowDownload: false. Hide the button, but be honest in the design review: it's a convenience setting, not protection. To show the document, the browser already received the bytes (they're visible in the network panel), and anyone can screenshot or print to PDF.

If a document must not leave, don't send the PDF at all. Serve server-rendered page images with a visible watermark naming the viewer, and accept the loss of selection and sharpness. That's a product decision, so name it as one.

A PDF is untrusted input to a big parser

PDFs can carry JavaScript (for form calculations and validation), launch actions, links with any URL scheme, form submit actions, and embedded fonts with their own programs. The PDF.js display library that we call (getDocument, render) never runs a document's JavaScript.

PDF.js's viewer components can run a limited, Acrobat-like scripting API when their enableScripting option is on (it is on by default in the full viewer app). In pdfjs-dist that code runs in a separate sandbox: the QuickJS engine compiled to WebAssembly. For our viewer, leave scripting off unless a specific form needs calculated fields.

The real risk is bugs in the parser itself. In May 2024, CVE-2024-4367 showed that a crafted font in a PDF could run arbitrary JavaScript in the page hosting PDF.js. PDF.js compiled glyph outlines into JavaScript functions for speed, and a missing type check on the font matrix let the file inject code into that function body. It was fixed in PDF.js 4.2.67 (Firefox 126), which stopped compiling glyphs into code.

The fix was easy; finding every copy was not, because many apps bundled an old pdfjs-dist through wrapper libraries and never upgraded. The workaround for old versions was setting isEvalSupported: false. PDF.js 5.7 (April 2026) removed the last code that used eval and the option with it, so current versions have neither.

• Keep PDF.js current: pin it, watch its releases and security advisories, and treat an upgrade as routine maintenance. The document service wrapper keeps upgrades cheap.
• Isolate the viewer: for user-uploaded files, run the viewer in an iframe on a separate origin (like a usercontent domain), talking to the host page with postMessage. A parser bug then runs in an origin with no cookies or user data.
• Content Security Policy: no unsafe-eval in script-src, and worker-src limited to our static origin. That blocks the code-from-strings class of bug entirely. PDF.js uses WebAssembly for some image decoders (and for the scripting sandbox), which needs wasm-unsafe-eval: that allows compiling WebAssembly but not JavaScript eval. Without it, PDF.js falls back to slower JavaScript decoders.
• Links: allow only http, https, and mailto targets (PDF.js already drops javascript: URLs), open external links with rel="noopener noreferrer", and consider a "You're leaving" prompt for links in untrusted files.
• Forms: ignore a file's own submit actions. Collect field values and send them through our API.

Accessibility and performance, honestly

Start with the honest limit: PDFs don't reflow. A web page at 200% zoom rewraps its text to fit the screen; a PDF page at 200% is just a bigger page, and a reader with low vision scrolls sideways on every line. WCAG's reflow criterion (1.4.10) asks content to fit a 320-CSS-pixel-wide viewport (400% zoom on a 1280-pixel window) without sideways scrolling, except where two-dimensional layout is essential. A fixed page of running text can't do that.

What we can do is make our own UI fully accessible, expose all the structure the file provides, and offer a way out. That way out is a "Reading view" that shows the extracted text as plain, reflowing HTML, page by page, with headings where the file is tagged.

• Tagged PDFs contain a structure tree (headings, paragraphs, lists, tables, figure alt text) and a logical reading order. PDF.js reads it with page.getStructTree() and its viewer maps it onto the text layer, so screen readers can hear headings and alt text, as far as the file's tags are correct. Untagged PDFs give only text runs in content-stream order, which for two-column layouts can interleave columns. Tell users when a file is untagged; fixing it is the author's job.
• The text layer is the accessible content. Each page region gets role="region" with a label like "Page 4 of 612", so screen reader users can jump by landmark. Pages without a rendered text layer must still announce their existence, and get their text layer built when a screen reader moves into them, not only when they scroll into view.
• Keyboard: Page Down and Page Up move by a page, Home and End to first and last, Ctrl plus + and - zoom (intercepted only while focus is in the viewer), Ctrl+F opens our find bar. Toolbar buttons are real button elements with labels; the thumbnail list and outline use arrow keys with a roving tabindex, as the keyboard-navigation lesson describes. Focus moves to the page heading after a jump, so screen reader users hear where they landed.
• Reduced motion: smooth scrolling to search results is nice, but use instant jumps when prefers-reduced-motion: reduce is set.

Performance budget and what to measure

The viewer's main metrics are product metrics, not just Core Web Vitals: time to first page painted, time to first text layer, and scroll smoothness. Record performance.mark at file request, first byte, document ready, and page 1 painted. Send them with the file size, page count, whether ranges were used, and device memory (navigator.deviceMemory, where supported). The "ranges used" field is what catches a CDN that quietly started compressing PDFs.

Watch long tasks during scroll with the Long Animation Frames API where available; a page render that paints a huge image in one chunk shows up there. Keep the PDF.js chunks out of the host page's critical path so its Largest Contentful Paint isn't hurt by a viewer that hasn't opened yet. The runtime-performance lesson covers the profiling side.

Running it in the interview

Forty-five minutes is not enough for every chapter, so plan the time around the decisions that show judgment. Draw the wireframe and the layered page early: they give you vocabulary for everything else.

Expect follow-ups that test whether you understand the mechanisms, not the names. Short, strong answers:

• "The PDF has 10,000 pages." Placeholder sizes from a server manifest; page-size lookups only for visible pages; thumbnails from the server; find via the server index; the virtualizer is unchanged because it never had per-page DOM cost.
• "Users zoom to 800% on a map PDF." Per-canvas cap plus a viewport-sized detail canvas; tile the detail canvas if needed, like a map; the memory budget stays the same.
• "Two people annotate at once." Annotations are server rows, so concurrent inserts don't conflict; push new ones over a socket or poll; edits to the same comment use last-write-wins with a version check.
• "Can you render in the worker too?" Yes, with OffscreenCanvas transferred to the worker, which keeps painting off the main thread. Name the costs: transfer and compositing, browser support details, and more complex cancellation.
• "How would you test it?" A corpus of tricky real files (scans, huge, encrypted, broken xref, rotated, forms) rendered in CI and compared to reference images, plus unit tests for coordinate math and the virtualizer.