PDF.js Source Walkthrough: api

Introduction

This is the installment of the PDF.js source walkthrough series covering the "display-layer entry point": src/display/api.js (about 3560 lines). Nearly every name a user gets from import * as pdfjsLib from "pdf.mjs" — getDocument, PDFDocumentProxy, PDFPageProxy, PDFWorker, RenderTask — is defined in this single file.

The "demo deep-dive" series has already walked the instantiation paths of these methods along the call chain: article 2 followed getDocument's parameter expansion and handshake, article 3 followed getPage, and article 5 followed render. This article takes a different angle: instead of tracing a single call, we take the entire file apart structurally, answering "what parts make up this file, what is each part responsible for, and how do they interlock."

api.js's job in one sentence: it is the main thread's facade layer — upward it offers users a clean set of proxy classes and task handles; downward it translates every method call into MessageHandler messages sent to the worker, and deposits the data the worker pushes back into the right caches and callbacks.

The export table at the end of the file is the table of contents for this article:

export {
  build,
  getDocument,
  PDFDataRangeTransport,
  PDFDocumentLoadingTask,
  PDFDocumentProxy,
  PDFPageProxy,
  PDFWorker,
  RenderTask,
  version,
};

Of the nine names, build and version are constant strings injected at build time; the remaining seven are the runtime API.

Module Overview

api.js can be cut into eight blocks:

Ownership relations among the eight blocks:

getDocument: The One-Shot Expansion Entry Point

All of getDocument's work falls into five stages: create the task, expand the parameters, start the worker, assemble the parameter bundles, and attach the handshake callback. Article 2 of the demo series already walked through this with concrete values; here we keep only structural observations.

Parameter Expansion: Read src Exactly Once

At the top of the function, src is expanded in one shot into 35+ local variables, and src is never read again afterwards:

function getDocument(src = {}) {
  const task = new PDFDocumentLoadingTask();
  const { docId } = task;
 
  const url = src.url ? getUrlProp(src.url) : null;
  const data = src.data ? getDataProp(src.data) : null;
  // ... 35+ local variables
  const useWorkerFetch =
    typeof src.useWorkerFetch === "boolean"
      ? src.useWorkerFetch
      : (typeof PDFJSDev !== "undefined" && PDFJSDev.test("MOZCENTRAL")) ||
        !!(
          BinaryDataFactory === DOMBinaryDataFactory &&
          cMapUrl && cMapPacked && standardFontDataUrl && wasmUrl &&
          isValidFetchUrl(cMapUrl, document.baseURI) &&
          // ...
        );

Each parameter resolves within three lines, but the patterns vary: some normalize the type (getUrlProp turns a string into a URL), some flip the semantics (ignoreErrors = src.stopAtErrors !== true), some cascade off variables just computed (useSystemFonts depends on disableFontFace), and some are compound conditions (useWorkerFetch). The full rule set for this segment is covered in article 2 of the demo series and is not repeated here.

Design note: the entry function concentrates the conversion from "user input" to "internal state" in a single code block. The following 4000 lines see only clean local variables and parameter bundles, and never again have to ask "did the user actually pass this?" This is the universal practice across the whole PDF.js library — validation converges at the boundary.

Two Parameter Bundles: Cross-Thread and Main-Thread-Only

Once parsed, the parameters are packed into two bundles:

const docParams = {
  docId,
  apiVersion: /* BUNDLE_VERSION */,
  data,
  password,
  disableAutoFetch,
  rangeChunkSize,
  docBaseUrl,
  enableXfa,
  evaluatorOptions: {
    maxImageSize, disableFontFace, ignoreErrors,
    isOffscreenCanvasSupported, isImageDecoderSupported,
    canvasMaxAreaInBytes, fontExtraProperties, useSystemFonts,
    useWasm, useWorkerFetch, cMapUrl, cMapPacked, iccUrl,
    standardFontDataUrl, wasmUrl,
    hasGPU: false, // placeholder, backfilled once the worker is ready
  },
};
const transportParams = {
  ownerDocument,
  pdfBug,
  styleElement,
  enableHWA,
  loadingParams: { disableAutoFetch, enableXfa },
};

docParams is sent to the worker via postMessage, so every value in it must be serializable; transportParams stays on the main thread, so it can hold DOM objects like ownerDocument. evaluatorOptions.hasGPU starts as a false placeholder and is backfilled with the real value once both gpuPromise and the worker handshake complete — GPU probing and worker startup run in parallel, neither waiting for the other.

Three Branches of Network Streams

The three parameters data, range, and url are mutually exclusive, with priority matching the code order:

let networkStream;
if (data) {
  // the whole PDF is already in memory; no network stream needed
} else if (rangeTransport) {
  networkStream = new PDFDataTransportStream({
    pdfDataRangeTransport: rangeTransport, disableRange, disableStream,
  });
} else if (url) {
  const NetworkStream = getNetworkStream(url); // prefer fetch, fall back to XHR
  networkStream = new NetworkStream({
    url, httpHeaders, withCredentials, rangeChunkSize, disableRange, disableStream,
  });
} else {
  throw new Error("getDocument - expected either `data`, `range`, or `url` parameter.");
}

getNetworkStream picks an implementation per environment: http(s) goes through PDFFetchStream, and older environments without support fall back to PDFNetworkStream (XHR). The data branch doesn't even build a stream — the bytes are already complete, and the worker takes ownership of data.buffer via the GetDocRequest transfer; the main thread's copy becomes invalid immediately.

Handshake Timing and the Race

Promise.all([worker.promise, gpuPromise])
  .then(function ([, hasGPU]) {
    if (worker.destroyed) throw new Error("Worker was destroyed");
    docParams.evaluatorOptions.hasGPU = hasGPU;
 
    const workerIdPromise = worker.messageHandler.sendWithPromise(
      "GetDocRequest", docParams, data ? [data.buffer] : null
    );
    // ... build networkStream
    return workerIdPromise.then(workerId => {
      const messageHandler = new MessageHandler(docId, workerId, worker.port);
      const transport = new WorkerTransport(
        messageHandler, task, networkStream, transportParams, transportFactory, pagesMapper
      );
      task._transport = transport;
      if (task.destroyed) throw new Error("Loading aborted");
      messageHandler.send("Ready", null);
    });
  })
  .catch(task._capability.reject)
  .finally(task._setupCapability.resolve);
 
return task;

Three things to note:

1. task is returned synchronously; the whole .then chain advances in the background. Any error at any step of the chain rejects task._capability — the very promise the user awaits via await loadingTask.promise.
2. _setupCapability resolves whether the chain succeeds or fails. It does not report a result to the user; it only tells destroy() that "_transport is either ready now or never will be" — this is the synchronization point for the race between destroy and the handshake, detailed below.
3. After assigning task._transport, task.destroyed is checked once more: the user may have called destroy() during the handshake, in which case throwing routes the chain into .catch, and orderly shutdown is left to the transport.

PDFDocumentLoadingTask: The User Handle for Loading

class PDFDocumentLoadingTask {
  static #docId = 0;
 
  _capability = Promise.withResolvers();
  _setupCapability = Promise.withResolvers();
  _transport = null;
  _worker = null;
 
  docId = `d${PDFDocumentLoadingTask.#docId++}`;
  destroyed = false;
  onPassword = null;
  onProgress = null;
 
  get promise() {
    return this._capability.promise;
  }
}

docId comes from a static counter; the first document is d1. This id appears in the MessageHandler source/target names (new MessageHandler(docId, workerId, ...)), and when multiple documents coexist it distinguishes which document a message belongs to.

The two capabilities have a clear division of labor:

destroy's Race Handling

destroy() is the most deliberate method in this small class; the four steps must stay in order:

async destroy() {
  this.destroyed = true;
  // the startup chain will later reject _capability with "Loading aborted"; claim
  // that rejection up front so it isn't treated as an unhandled promise rejection
  this._capability.promise.catch(() => {});
 
  try {
    // must be set synchronously: a later PDFWorker.create() on the shared
    // workerPort must see it immediately and throw
    if (this._worker?.port) this._worker._pendingDestroy = true;
    // wait for the startup chain to finish, guaranteeing _transport is set so
    // the "Terminate" message can actually be sent
    await this._setupCapability.promise;
    await this._transport?.destroy();
  } catch (ex) {
    if (this._worker?.port) delete this._worker._pendingDestroy;
    throw ex;
  }
  this._transport = null;
  this._worker?.destroy();
  this._worker = null;
}

The synchronous setting of _pendingDestroy corresponds to issue 16777: if the flag were set after the await, another getDocument in the event-loop gap could reuse the same workerPort and get a worker that is being destroyed. On failure the flag is rolled back before rethrowing — if the worker wasn't destroyed, the "being destroyed" seal must not be left behind.

PDFDataRangeTransport: A Push-Mode Range Abstraction

When users want to control range requests themselves (e.g. a custom protocol, or adding authentication), they subclass this abstract class:

class PDFDataRangeTransport {
  #capability = Promise.withResolvers();
  #listener = null;
 
  constructor(length, initialData, progressiveDone = false, contentDispositionFilename = null) { ... }
 
  onDataRange(begin, chunk) {
    this.#listener({ type: "range", begin, chunk });
  }
 
  onDataProgressiveRead(chunk) {
    this.#capability.promise.then(() => {
      this.#listener({ type: "progressiveRead", chunk });
    });
  }
 
  transportReady(listener) {
    this.#listener = listener;
    this.#capability.resolve();
  }
 
  requestDataRange(begin, end) {
    unreachable("Abstract method PDFDataRangeTransport.requestDataRange");
  }
  abort() {}
}

Note the asymmetry between the two kinds of entry points:

• onDataRange forwards directly to the listener. Range data is actively pulled by the transport via requestDataRange; if data can be pulled, the listener was registered long ago;
• onDataProgressiveRead / onDataProgressiveDone must first wait on #capability. Progressive data is pushed as soon as the user's network is ready, which can be earlier than the transportReady call; without queueing, that data would land on #listener === null.

Design note: for the same "data has arrived" event, pull mode is naturally ordered, while push mode must queue via a promise. Keeping the queueing logic in the base class lets subclasses just call when they have data, without caring about timing.

PDFDocumentProxy: Thirty Forwarding Methods

PDFDocumentProxy is the proxy for the worker-side PDFDocument; its constructor stores only two fields:

class PDFDocumentProxy {
  constructor(pdfInfo, transport) {
    this._pdfInfo = pdfInfo;
    this._transport = transport;
    // TESTING / INTERNAL_VIEWER builds additionally attach getRawData etc. dynamically
  }
}

Then come about 30 methods, the vast majority one-line forwarders: getPage, getOutline, getMetadata, getAttachments, getJSActions... all delegate to the same-named method on this._transport. Only four categories deserve individual treatment.

Synchronous Getters: Laying Out Already-Ready Data

Getters like numPages, fingerprints, annotationStorage, and canvasFactory send no messages — the data already arrived on the main thread with pdfInfo during the GetDoc handshake. isPureXfa uses the shadow utility:

get isPureXfa() {
  return shadow(this, "isPureXfa", !!this._transport._htmlForXfa);
}

shadow computes the value on first read, then replaces it with a plain data property via Object.defineProperty, so every subsequent access is a plain field read, never going through the getter again.

Test-Only Dynamic Methods

if (typeof PDFJSDev === "undefined" || PDFJSDev.test("TESTING")) {
  Object.defineProperty(this, "getNetworkStreamName", {
    value: () => this._transport.getNetworkStreamName(),
  });
  // getXFADatasets / getStartXRefPos / getAnnotArray work the same way
}

The preprocessor of production builds deletes the entire if block — PDFJSDev.test("TESTING") is the constant false in release packages, so these methods never appear on instances. All of pdf.js's diagnostic capabilities go through this switch, keeping the production API surface unpolluted.

getOptionalContentConfig's Intent Conversion

getOptionalContentConfig({ intent = "display" } = {}) {
  const { renderingIntent } = this._transport.getRenderingIntent(intent);
  return this._transport.getOptionalContentConfig(renderingIntent);
}

The string intent is first converted into bit flags by getRenderingIntent, then sent to the worker with the request. This renderingIntent is later bitwise-AND-verified against the one in render() — when the two intents disagree, render throws, preventing "a config fetched for display being used for print rendering."

cleanup's XFA Special Case

cleanup(keepLoadedFonts = false) {
  return this._transport.startCleanup(keepLoadedFonts || this.isPureXfa);
}

Pure XFA documents forcibly keep loaded fonts. XFA forms go down the HTML rendering path, with fonts attached to the document via the DOM's @font-face; clearing the fonts and re-rendering would fall the whole page back to system fonts, so when isPureXfa holds, keepLoadedFonts = true no matter what.

PDFPageProxy: A Rendering State Machine Bucketed by intentState

PDFPageProxy is the state-heaviest class in the whole file. Besides the page number and page info, its constructor sets up two levels of object caches:

constructor(pageIndex, pageInfo, transport, pagesMapper, pdfBug = false) {
  this._pageIndex = pageIndex;
  this._pageInfo = pageInfo;
  this._transport = transport;
  /** @type {PDFObjects} */
  this.commonObjs = transport.commonObjs; // document-level shared: fonts, cross-page images
  this.objs = new PDFObjects();           // page-level private: this page's images and patterns
 
  this._intentStates = new Map();
  // ...
}

The division between commonObjs and objs corresponds to the two messages by which the worker pushes data: commonobj (document level) and obj (page level), which we'll see in the WorkerTransport section below.

_intentStates: Bucketed by cacheKey

The same page may be rendered concurrently multiple times: one for display, one for print, one for editing mode. Each has its own operatorList, renderTasks set, and ready capability, and PDF.js buckets them by cacheKey:

const intentState = this._intentStates.getOrInsertComputed(cacheKey, makeObj);

cacheKey is composed by WorkerTransport.getRenderingIntent (intent bit flags + annotation storage hash), detailed below. Both render() and getOperatorList() compute the cacheKey first, and calls with the same key share the same operatorList — rendering the same page twice with the same intent means the worker parses it only once.

render(): Pump the Stream Immediately, Start Painting Once Ready

render() executes in two stages. The first stage completes synchronously:

render({ canvasContext, canvas = canvasContext.canvas, viewport, intent = "display", ... }) {
  const intentArgs = this._transport.getRenderingIntent(intent, annotationMode, ...);
  const { renderingIntent, cacheKey } = intentArgs;
  this.#pendingCleanup = false; // a render is running; cancel the pending cleanup
 
  optionalContentConfigPromise ||=
    this._transport.getOptionalContentConfig(renderingIntent);
 
  const intentState = this._intentStates.getOrInsertComputed(cacheKey, makeObj);
  if (intentState.streamReaderCancelTimeout) {
    clearTimeout(intentState.streamReaderCancelTimeout); // cancel the delayed abort
    intentState.streamReaderCancelTimeout = null;
  }
 
  if (!intentState.displayReadyCapability) {
    // first render: build the operatorList container and start pumping from the worker immediately
    intentState.displayReadyCapability = Promise.withResolvers();
    intentState.operatorList = { fnArray: [], argsArray: [], lastChunk: false, separateAnnots: null };
    this._pumpOperatorList(intentArgs);
  }
  // ... build InternalRenderTask and register it into intentState.renderTasks

The second stage happens asynchronously: once both "operatorList first chunk ready" and "optional content config" are in place, the canvas is actually initialized:

  Promise.all([
    intentState.displayReadyCapability.promise,
    optionalContentConfigPromise,
  ]).then(([transparency, optionalContentConfig]) => {
    if (this.destroyed) { complete(); return; }
    if (!(optionalContentConfig.renderingIntent & renderingIntent)) {
      throw new Error("Must use the same `intent`-argument ...");
    }
    internalRenderTask.initializeGraphics({ transparency, optionalContentConfig });
    internalRenderTask.operatorListChanged();
  }).catch(complete);
 
  return renderTask; // returned synchronously, waits on no promise
}

Two design decisions here are worth remembering:

1. Stream fetching waits for no one. _pumpOperatorList starts synchronously inside render(), without waiting for the canvas to be ready. Worker-side parsing and main-thread canvas preparation run in parallel; when the first operatorList chunk arrives, the StartRenderPage message resolves displayReadyCapability, and by then the canvas has usually long been initialized.
2. Intent is verified bitwise. If optionalContentConfig.renderingIntent & renderingIntent is zero, the intents of the two calls don't match (e.g. the config was fetched with print while rendering uses display), and it throws outright rather than rendering a page with missing layers.

_pumpOperatorList: Pumping a Streaming Interface into an Array

The operatorList crosses threads via sendWithStream — the worker pushes each chunk as soon as it parses it:

_pumpOperatorList({ renderingIntent, cacheKey, annotationStorageSerializable, modifiedIds }) {
  const { map, transfer } = annotationStorageSerializable;
  const readableStream = this._transport.messageHandler.sendWithStream(
    "GetOperatorList",
    {
      pageId: this.#pagesMapper.getPageId(this._pageIndex + 1) - 1,
      pageIndex: this._pageIndex,
      intent: renderingIntent,
      cacheKey,
      annotationStorage: map,
      modifiedIds,
    },
    /* queueingStrategy = */ undefined,
    transfer
  );
  const reader = readableStream.getReader();
  const intentState = this._intentStates.get(cacheKey);
  intentState.streamReader = reader;
 
  const pump = () => {
    reader.read().then(({ value, done }) => {
      if (done) { intentState.streamReader = null; return; }
      if (this._transport.destroyed) return;
      this._renderPageChunk(value, intentState); // append into fnArray/argsArray and wake the render tasks
      pump();
    }, reason => { /* on error: mark lastChunk, then wake and reject each capability */ });
  };
  pump();
}

The line pageId: this.#pagesMapper.getPageId(this._pageIndex + 1) - 1 deserves expansion: _pageIndex + 1 is the page number in the user's eyes, getPageId maps it to the source document page number, and - 1 converts back to a zero-based index. When pages have been reordered/deleted/duplicated (pagesMapper's job), user page numbers and worker page numbers diverge, and every cross-thread message must go through this translation layer.

_abortOperatorList: The 100ms Delayed Cancellation

When rendering is cancelled (e.g. the user zooms rapidly), the main thread does not immediately tell the worker to stop parsing:

if (reason instanceof RenderingCancelledException) {
  let delay = RENDERING_CANCELLED_TIMEOUT; // 100ms
  if (reason.extraDelay > 0 && reason.extraDelay < 1000) {
    delay += reason.extraDelay;
  }
  intentState.streamReaderCancelTimeout = setTimeout(() => {
    intentState.streamReaderCancelTimeout = null;
    this._abortOperatorList({ intentState, reason, force: true });
  }, delay);
  return;
}

The comment explains why: in the viewer, after zooming/rotating, the same page is re-render()ed immediately with new parameters, and cacheKey contains intent but not scale — the new render reuses the same stream. If a cancellation cut off the worker's parsing at once, the re-render would have to parse again from scratch. Leaving a 100ms window lets a new render() come in and clearTimeout the delayed task, saving the stream. Only if nobody reuses it within the window does force: true really cancel.

Another layer of protection comes before that:

if (intentState.renderTasks.size > 0) return;

When other render tasks are still attached to the same intentState, a single task's error does not cut the stream — one failed render() must not break other renders of the same page.

cleanup: Four Conditions, All Required

Page-level cleanup is not "clean on demand":

#tryCleanup() {
  if (!this.#pendingCleanup || this.destroyed) return false;
  for (const { renderTasks, operatorList } of this._intentStates.values()) {
    if (renderTasks.size > 0 || !operatorList.lastChunk) return false;
  }
  this._intentStates.clear();
  this.objs.clear();
  this.#pendingCleanup = false;
  return true;
}

All must hold simultaneously: someone has requested cleanup (#pendingCleanup), the page is not destroyed, all intentStates have no running render tasks, and all operatorLists have received their final chunk. In render()'s completion callback, print intent actively sets #pendingCleanup = true and attempts cleanup — printing easily spans dozens of pages, and releasing glyph/image data right after printing is the only way to keep memory down.

PDFWorker: Creation, Handshake, and Fallback

PDFWorker encapsulates the "parsing thread" resource. Its static block settles two things at class-load time (GENERIC build):

static {
  if (isNodeJS) {
    // Node.js doesn't support the Worker usage here; disable it outright
    this.#isWorkerDisabled = true;
    GlobalWorkerOptions.workerSrc ||= PDFJSDev.test("LIB")
      ? "../pdf.worker.js"
      : "./pdf.worker.mjs";
  }
  this._isSameOrigin = (baseUrl, otherUrl) => { /* returns false for non-same-origin or non-http */ };
  this._createCDNWrapper = url => {
    const wrapper = `await import("${url}");`;
    return URL.createObjectURL(new Blob([wrapper], { type: "text/javascript" }));
  };
}

_createCDNWrapper solves a frequent problem in real deployments: when workerSrc points at a CDN (cross-origin), new Worker(url) is rejected by the browser. Wrapping it in a same-origin blob lets the import() inside the blob fetch the CDN code — import is not subject to the worker script's same-origin restriction.

The test Handshake: Verifying transfer Really Works

After #initialize builds the Worker and MessageHandler, it doesn't declare readiness right away; it first sends a probe message:

const sendTest = () => {
  const testObj = new Uint8Array();
  // verify postMessage's transfer capability: the Uint8Array must still be a Uint8Array on the worker side
  messageHandler.send("test", testObj, [testObj.buffer]);
};
sendTest(); // sent immediately once
// sent once more when the worker's "ready" message arrives; the worker only handles whichever arrives first

Only when the worker replies with truthy data are #messageHandler / #port / #webWorker attached to the instance and the promise resolved. A falsy reply or an error routes into terminateEarly to clean up and fall back to a fake worker. The double send covers timing: when the worker loads fast, the immediate test arrives first; when slow, the one triggered by ready acts as a backstop.

The Fake-Worker Fallback Chain

When a real worker is unavailable (Node environment, constructor throws, test fails), the fallback is a "fake worker" — loading the worker code into the main thread:

#setupFakeWorker() {
  if (!PDFWorker.#isWorkerDisabled) {
    warn("Setting up fake worker.");
    PDFWorker.#isWorkerDisabled = true; // later documents won't even try a real worker
  }
  PDFWorker._setupFakeWorkerGlobal.then(WorkerMessageHandler => {
    if (this.destroyed) { /* reject */ return; }
    const port = new LoopbackPort();
    const id = `fake${PDFWorker.#fakeWorkerId++}`;
    const workerHandler = new MessageHandler(id + "_worker", id, port);
    WorkerMessageHandler.setup(workerHandler, port);
    this.#messageHandler = new MessageHandler(id, id + "_worker", port);
    this.#resolve();
  });
}

LoopbackPort is a pair of interconnected local ports whose messages are dispatched synchronously rather than via postMessage. To the upper-layer WorkerTransport, the interface is identical — it cannot tell whether the other end is a thread or a loopback. _setupFakeWorkerGlobal caches the loading promise with shadow, so the worker code is dynamically imported only once per library.

create: Port Reuse and the Destruction Seal

static create(params) {
  const cachedPort = this.#workerPorts.get(params?.port);
  if (cachedPort) {
    if (cachedPort._pendingDestroy) {
      throw new Error(
        "PDFWorker.create - the worker is being destroyed.\n" +
        "Please remember to await `PDFDocumentLoadingTask.destroy()`-calls."
      );
    }
    return cachedPort;
  }
  return new PDFWorker(params);
}

#workerPorts is a WeakMap caching PDFWorkers keyed by workerPort: multiple create calls passing the same port share the same worker. Hitting the _pendingDestroy seal (the one set synchronously by destroy() above) throws directly, and the error message tells you exactly to await the destruction — this is the fix for issue 16777.

WorkerTransport: The Message Routing Hub

WorkerTransport is not exported, yet it is the real main-thread hub: document-level caches, page caches, and the message routing table all live on it.

Three Sets of Page Caches

#pageCache = new Map();      // pageIndex -> PDFPageProxy
#pagePromises = new Map();   // pageIndex -> Promise<PDFPageProxy>
#pageRefCache = new Map();   // "12R0" -> pageIndex

getPage checks #pagePromises first; concurrent calls for the same page share one promise, and the worker receives only one GetPage message. Note the two index directions: pageIndex = pageNumber - 1 is the user-view zero-based index (the cache key), while newPageIndex = pagesMapper.getPageId(pageNumber) - 1 is the source-document index sent to the worker. Once pages are reordered the two diverge: caches are keyed by user view, messages are sent by source view.

#pageRefCache serves reverse lookups: cachedPageNumber(ref) maps a reference string like "12R0" (the suffix omitted when gen is 0) back to a page number, a pure local hit that sends no message.

#cacheSimpleMethod: Local Caching for Idempotent Requests

#cacheSimpleMethod(name, data = null) {
  return this.#methodPromises.getOrInsertComputed(name, () =>
    this.messageHandler.sendWithPromise(name, data)
  );
}

Requests whose results don't change between calls — GetFieldObjects, GetDocJSActions, GetOptionalContentConfig, GetMetadata — go through it: the first call sends a message, later calls return the cached promise. The counter-example is getSignatureData — signature bytes are sizable, and caching them in a Map would keep them alive as long as the document; the comment explicitly says "not cached, consumed once."

getRenderingIntent: Bit Flags and cacheKey

render, getOperatorList, getAnnotations, and getOptionalContentConfig all compile their string parameters into bit flags through it first:

let renderingIntent = RenderingIntentFlag.DISPLAY;
switch (intent) {
  case "any":   renderingIntent = RenderingIntentFlag.ANY; break;
  case "print": renderingIntent = RenderingIntentFlag.PRINT; break;
}
switch (annotationMode) {
  case AnnotationMode.DISABLE:         renderingIntent += RenderingIntentFlag.ANNOTATIONS_DISABLE; break;
  case AnnotationMode.ENABLE_FORMS:    renderingIntent += RenderingIntentFlag.ANNOTATIONS_FORMS; break;
  case AnnotationMode.ENABLE_STORAGE:
    renderingIntent += RenderingIntentFlag.ANNOTATIONS_STORAGE;
    annotationStorageSerializable = annotationStorage.serializable; // serialized form data travels with the message
    break;
}
if (isEditing) renderingIntent += RenderingIntentFlag.IS_EDITING;
if (isOpList)  renderingIntent += RenderingIntentFlag.OPLIST;
 
const { ids: modifiedIds, hash: modifiedIdsHash } = annotationStorage.modifiedIds;
const cacheKeyBuf = [renderingIntent, annotationStorageSerializable.hash, modifiedIdsHash];
return { renderingIntent, cacheKey: cacheKeyBuf.join("_"), ... };

cacheKey compresses "rendering intent + form snapshot + modification set" into one string — when form content changes, the key changes, and _intentStates naturally starts a new bucket and re-parses; when forms are unchanged, renders with the same intent share the stream. When printing with a PrintAnnotationStorage passed in, the print-specific storage is used instead, so print and display edits don't interfere with each other.

setupMessageHandler: Thirteen Message Routes

At the end of the constructor, setupMessageHandler() registers all handlers for the worker→main-thread direction. Grouped by function:

Three data-channel routes

The "close if unavailable" branch in GetRangeReader is fully commented: during streaming loads, data may already have been pulled down by the fullReader but not yet postMessaged to the worker, so issuing another range request would be waste; the worker just waits for the full stream.

Four document-lifecycle routes

PasswordRequest translates "the worker blocks waiting for a password" into "the main thread waits for a user callback": if updatePassword receives an Error it rejects (give up opening); a string resolves {password} and lets the worker retry decryption.

Two object-delivery routes

commonobj (document level) dispatches into five paths by type:

messageHandler.on("commonobj", ([id, type, exportedData]) => {
  if (this.commonObjs.has(id)) return null; // dedup
  switch (type) {
    case "Font": {
      const font = new FontFaceObject(new FontInfo(exportedData), inspectFont, ...);
      this.fontLoader.bind(font)
        .catch(() => messageHandler.sendWithPromise("FontFallback", { id }))
        .finally(() => {
          if (!font.fontExtraProperties) font.clearData(); // release font bytes as soon as it's attached to the DOM
          this.commonObjs.resolve(id, font);
        });
      break;
    }
    case "CopyLocalImage": /* cross-page image reuse: find the data with the same ref in the page cache and structuredClone a copy */ break;
    case "FontPath": this.commonObjs.resolve(id, new FontPathInfo(exportedData)); break;
    case "Image":    this.commonObjs.resolve(id, exportedData); break;
    case "Pattern":  this.commonObjs.resolve(id, new PatternInfo(exportedData).getIR()); break;
  }
  return null;
});

The font path is the most elaborate: when bind fails (the system refuses to load the font), it isn't condemned outright — a FontFallback message lets the worker fall back to built-in rendering; on success, clearData immediately releases the possibly multi-MB font bytes instead of waiting for document cleanup.

obj (page level) only accepts Image / Pattern, with one extra line of defense:

if (pageProxy._intentStates.size === 0) {
  imageData?.bitmap?.close(); // page already cleaned up; release the ImageBitmap directly
  return;
}

This is the fix for bug 1854145: data the worker pushes after a successful page cleanup must not enter the store (PDFObjects has been cleared, so nothing would release it); closing the bitmap directly prevents the leak.

The rest: StartRenderPage wakes the page object's displayReadyCapability; DocProgress forwards loading progress; FetchBinaryData (non-MOZCENTRAL) has binaryDataFactory download CMaps/fonts/wasm on the main thread — exactly the main-thread download path when useWorkerFetch = false in getDocument.

saveDocument and extractPages: Serialization and Remapping

Saving a document brings the main thread's form edits back to the worker:

saveDocument() {
  const { map, transfer } = this.annotationStorage.serializable;
  return this.messageHandler.sendWithPromise("SaveDocument", {
    isPureXfa: !!this._htmlForXfa,
    numPages: this._numPages,
    annotationStorage: map,
    filename: this.#fullReader?.filename ?? null,
  }, transfer).finally(() => {
    this.annotationStorage.resetModified(); // clear the "modified" flag whether it succeeds or fails
  });
}

extractPages is more complex: after pages have been reordered, the pageIndex recorded in annotations is user-view, while the worker looks up by source view, so it must be translated via pagesMapper.getMapping(); when the same source page is extracted into multiple copies, copyLevels further marks which copy each editor annotation belongs to:

const copyLevel = copyLevels?.[v.pageIndex] ?? 0;
const sourceIdx = mapping[v.pageIndex] - 1;
if (sourceIdx !== v.pageIndex || copyLevel !== 0) {
  remapped.set(k, { ...v, pageIndex: sourceIdx, copyLevel });
  continue;
}

A -1 in copyLevels means the page was not extracted — the corresponding entries are still kept, because extracted stamp annotations may reference their bitmapId; seeing a negative value, the worker skips the annotation itself but keeps the bitmap association.

destroy: Stop the Pages First, Then the Worker

destroy() {
  if (this.destroyCapability) return this.destroyCapability.promise; // idempotent
  this.destroyed = true;
  this.destroyCapability = Promise.withResolvers();
  this.#passwordCapability?.reject(new Error("Worker was destroyed during onPassword callback"));
 
  const waitOn = [];
  for (const page of this.#pageCache.values()) waitOn.push(page._destroy()); // wait for all rendering to settle
  // ... clear caches, resetModified
  const terminated = this.messageHandler.sendWithPromise("Terminate", null); // wait for the worker's long task to finish
  waitOn.push(terminated);
 
  Promise.all(waitOn).then(() => {
    this.commonObjs.clear();
    this.fontLoader.clear();
    this.#methodPromises.clear();
    this.filterFactory.destroy();
    TextLayer.cleanup();
    this.#networkStream?.cancelAllRequests(new AbortException("Worker was terminated."));
    this.messageHandler?.destroy();
    this.messageHandler = null;
    this.destroyCapability.resolve();
  }, this.destroyCapability.reject);
  return this.destroyCapability.promise;
}

The order is "pages → worker → local resources": first let all RenderTasks settle (rAF callbacks may still be queued), then send Terminate and wait for the worker to wrap up, and finally clear the main thread's fonts, filters, text layer, and network requests. A document blocked on onPassword gets rejected immediately instead of hanging forever.

RenderTask and InternalRenderTask: Handle and Scheduler

The RenderTask returned synchronously by render() is just a shell; the real scheduling lives in InternalRenderTask:

class RenderTask {
  onContinue = null; // called each time rendering pauses, with the "continue" function as argument
  onError = null;    // called synchronously when rendering errors / is cancelled
 
  get promise() {
    return this._internalRenderTask.capability.promise;
  }
 
  cancel(extraDelay = 0) {
    this._internalRenderTask.cancel(null, extraDelay);
  }
}

Note that RenderTask itself is not a thenable — await page.render(...) does not wait for rendering to finish; you must await renderTask.promise. Article 5 of the demo series specifically stepped on this pit.

initializeGraphics: A Canvas Serves Only One Task at a Time

initializeGraphics({ transparency = false, optionalContentConfig }) {
  if (this.cancelled) return;
  if (this._canvas) {
    if (InternalRenderTask.#canvasInUse.has(this._canvas)) {
      throw new Error("Cannot use the same canvas during multiple render() operations. ...");
    }
    InternalRenderTask.#canvasInUse.add(this._canvas);
  }
  const canvasContext = this._canvasContext || this._canvas.getContext("2d", {
    alpha: false,
    willReadFrequently: !this._enableHWA,
  });
  this.gfx = new CanvasGraphics(canvasContext, this.commonObjs, this.objs, ...);
  this.gfx.beginDrawing({ transform, viewport, transparency, background });
  this.operatorListIdx = 0;
  this.graphicsReady = true;
  this.graphicsReadyCallback?.();
}

#canvasInUse is a static WeakSet: a second render() on the same canvas throws outright, and the error message spells out the remedy (use another canvas, or cancel/wait for completion first). The two 2D-context switches each have their own backstory: alpha: false tells the browser the canvas is opaque, saving one blend during compositing; willReadFrequently: !enableHWA declares "rarely read back" when hardware acceleration is on, letting the browser safely keep the canvas on the GPU side.

The Scheduling Loop: rAF and Microtasks

_scheduleNext() {
  if (this._useRequestAnimationFrame) {
    this.#rAF = window.requestAnimationFrame(() => {
      this.#rAF = null;
      this._nextBound().catch(this._cancelBound);
    });
  } else {
    Promise.resolve().then(this._nextBound).catch(this._cancelBound);
  }
}
 
async _next() {
  if (this.cancelled) return;
  this.operatorListIdx = this.gfx.executeOperatorList(
    this.operatorList, this.operatorListIdx, this._continueBound, this.stepper, this._operationsFilter
  );
  if (this.operatorListIdx === this.operatorList.argsArray.length) {
    this.running = false;
    if (this.operatorList.lastChunk) {
      this.gfx.endDrawing();
      InternalRenderTask.#canvasInUse.delete(this._canvas);
      this.callback(); // back to the `complete` in PDFPageProxy.render
    }
  }
}

Each round of executeOperatorList runs at most about 15ms (the time-slice constant in canvas.js), then returns here via continueCallback to schedule the next round. Display rendering uses requestAnimationFrame to align with frames; print rendering goes through microtasks (useRequestAnimationFrame: !intentPrint) — printing has no notion of frames, and draining microtasks is faster. If the user sets RenderTask.onContinue, scheduling power is handed to the user: at the end of each time slice, onContinue(continueFn) is called, and the user decides when to call continueFn — enabling strategies like "render when idle."

At the end of each round, it checks "executed to the end of the array and this is the final chunk"; only then does it endDrawing and invoke the completion callback. Otherwise the stream hasn't finished pushing, so it hangs with running = false, to be restarted by operatorListChanged() when the next chunk arrives.

Version Constants and Exports

Two constants at the end of the file are injected at build time:

const version = typeof PDFJSDev !== "undefined" ? PDFJSDev.eval("BUNDLE_VERSION") : null;
const build = typeof PDFJSDev !== "undefined" ? PDFJSDev.eval("BUNDLE_BUILD") : null;

PDFJSDev.eval is replaced with a literal (e.g. "6.3.289") during bundling, and is null when run directly from the source tree. When getDocument assembles docParams, it sends apiVersion to the worker, which uses it to verify the two ends run matching versions — main-thread API and worker coming from different versions is a common deployment accident, and this check blows it up right at the handshake.

Summary

api.js is the main-thread facade of PDF.js: it hides worker communication, streaming transport, font loading, and canvas scheduling behind seven exported names, so the user faces only three verbs — "load document → get page → render."

Where Each Stage of a Full Render Lands in This Article

Six Design Principles

1. Validation converges at the boundary. src is read only once at the top of getDocument, expanded into 35+ clean local variables; the inner 4000 lines never again face "did the user pass it?"
2. Cross-thread data must be serializable; main-thread-only data can be anything. The docParams / transportParams split is drawn exactly along the "does it cross postMessage?" line.
3. Return handles synchronously, advance chains asynchronously. getDocument returns task and render() returns renderTask, both synchronously; errors arrive asynchronously via capabilities, and the race between destroy() and the startup chain is resolved by the two synchronization points _setupCapability and _pendingDestroy.
4. Streaming beats whole-package delivery. The operatorList is pumped in chunks, text is segmented by highWaterMark, range data is fetched on demand — first paint never waits for the full parse.
5. Cancellation should be lazy, cleanup strict. Render cancellation leaves a 100ms reuse window; cleanup executes only when "no tasks, stream exhausted" holds, and a late obj message would rather have its bitmap discarded than enter the store.
6. Capability fallbacks don't disturb upper layers. If a real worker fails, use a fake one; if a font fails, go through FontFallback; LoopbackPort is isomorphic to a real port — code at and above WorkerTransport is unaware of the degradation.

After understanding api.js, the remaining display-layer files can each be positioned by "which stage here does it serve": message_handler.js implements message semantics, canvas.js is the operator set behind executeOperatorList, and fetch_stream.js / network.js are two legs of the three-branch network stream. Their own source walkthroughs are left to separate articles.

StreamPDF design principle: anything that can be handled ahead of time is absolutely not deferred to parse time; the server solves all performance problems once. The browser only fetches and renders the data it must.