DEV Community: StreamPDF

The AI Era: What Should We Do to Survive? (Reflections on Founding StreamPDF)

StreamPDF — Mon, 09 Nov 2026 13:00:00 +0000

Introduction

AI is called the fourth industrial revolution. Whose life did it take?

Revolutions kill people.

The first industrial revolution began around the 1760s and lasted until about the 1840s. It carried humanity from an agrarian society into industrial civilization and opened the age of steam. Who got hurt this time? The proletariat — farm laborers and artisans. For the first time, humanity held efficient means of production independent of any individual.

The second industrial revolution began around the 1870s and lasted until the early 20th century (roughly 1870-1914). It carried humanity from the age of steam into the age of electricity. Who got hurt this time? The proletariat, and small business owners. Electricity further increased the efficiency of the means of production.

The third industrial revolution began around the 1940s and lasted until the early 21st century (roughly 1940-2010). It carried humanity from the age of electricity into the information age. Who got hurt this time? The proletariat, industrial blue-collar workers, and companies running on outdated, inefficient technology. Information exchange dramatically increased the efficiency of the means of production.

The Fourth Industrial Revolution: Whose Life Did It Take?

AI, the fourth industrial revolution, was born on the internet and is developing at extreme speed. Within the internet industry, programmers, designers, and data analysts were among the first to get hurt.

Since ChatGPT launched on November 30, 2022, the tech layoff wave has not stopped. According to Layoffs.fyi, in just a few years more than 650,000 tech workers have been laid off across more than 2,600 recorded events:

2023: 263,000 layoffs, the highest annual total on record. Google cut 12,000, Microsoft 10,000, Amazon 27,000 in total, Meta 21,000 across 2022-2023, and Salesforce 8,000. The same year, IBM announced a hiring freeze on roughly 7,800 back-office roles that AI could handle.
2024: 152,000 layoffs — about 780 people losing their jobs every day. Intel cut 15,000, Tesla 14,000, and Cisco more than 10,000. The same year, Duolingo replaced 10% of its contract translators with AI.
2025: the first year AI was openly cited as the reason for layoffs. Intel cut another 22,000, Microsoft cut 9,000 in July, and Amazon cut 14,000 in October, writing in an internal memo that "AI is the most transformative technology since the invention of the Internet." The same year, Salesforce's AI agents replaced about 4,000 human support agents, and Chegg, whose students were flocking to ChatGPT, was forced to cut 22% of its staff.
2026: the cuts accelerate. In March, Oracle announced a one-time layoff of up to 30,000 people — the largest in its history. Dell cut 11,000. In April, Meta cut 8,000, explicitly attributing it to "AI efficiency." Block's founder Jack Dorsey cut nearly 40% of his workforce, saying AI can now take on more tasks. As of October, nearly 200,000 tech workers have been laid off in 2026 — more than 1,000 per day, the fastest pace of any year on record.

What is more intriguing: the companies cutting their own people are precisely the ones posting record revenue and record stock prices. After its layoffs, Meta's stock rose more than 150% in 2023. Wall Street told every CEO, with real money: layoffs + an AI narrative = a rising stock. Layoffs are no longer a signal of crisis; they are a medal for embracing AI.

This is not just a layoff wave. It is a revolution, and the cut positions are not coming back.

The difference from the previous three revolutions: each of those had the human brain as the backstop. Human intelligence was irreplaceable in the first three industrial revolutions. This fourth one wants to replace human intelligence itself.

Fortunately, machines can only replace intelligence — they cannot take responsibility. You cannot ask a machine to be accountable. And, more ironic still, even though this machine cannot take responsibility, every time you ask it to work, you still pay for every answer, in tokens.

What Does the Future of AI Look Like?

Nobody knows. I believe even OpenAI, Anthropic, and Google cannot predict where AI will end up. But one thing is certain: the workers — the proletariat — will get hurt again in this wave.

If AI truly replaces human intelligence and society moves toward communism, UBI will become the new social foundation. But then where do citizens' rights come from? Cut off from social labor, how do we account for a person's rights? Should a human being enslaved by AI have social rights at all?

And a question about the present: do people brainwashed by tittytainment like TikTok deserve social rights?

EU announces plan to restrict social media access for under-15s

Hidden inside this grim topic is one lucky fact: AI can replace human intelligence, but it cannot consume society's productive output.

The end point of all production is consumption, and the economy is a closed loop: people work, earn wages, and spend those wages buying back what they produce. In the first three industrial revolutions, machines replaced muscle; the displaced moved to new jobs, kept earning, kept spending — the loop never broke. This time, if AI replaces intelligence itself, the displaced will struggle to find the next job. With no wages, who consumes what AI produces? AI does not eat, does not travel, does not buy a house.

This is why UBI is being discussed so seriously: not as a utopian welfare fantasy, but as a life-support option for the loop itself. But UBI has to be paid out of the wealth AI creates — so who holds the power to distribute it?

I believe AI will inevitably enter the physical world and replace a huge number of workers. When UBI really arrives, are we the ones being enslaved by AI?

What Should We Actually Do to Survive?

Is AI's thinking the same thing as human thinking? In my perception, yes. The human brain relies on hundreds of millions of neuronal synapses to decide the next action and the next sentence. At its core, it is an inference engine. The biggest difference between humans and AI today is memory: a human brain can retain and distill decades — even a century — of experience and knowledge; AI cannot yet.

But AI is overwhelmingly strong: even with its memory mechanism limited, it was born already holding a vast amount of knowledge — something no human can do. A human needs over a decade of training after birth to become a functioning adult.

I believe that one day, AI's memory will improve dramatically too.

But can we trust what AI produces? Ask yourself: when you write code today, do you review every line AI generates? Most people don't. Not because you trust AI, but because the sheer volume of AI output has exceeded the boundary of human review capacity. Fair enough. On the internet this is acceptable — the web produces countless pages every day, some useful, some not. But the physical world's tolerance for error is far lower than the internet's. That is exactly why the internet became the field where AI exploded.

So in the physical world, what is left for humans?

Back to the earlier conclusion: AI can generate everything, but it cannot take responsibility. And the concrete form of taking responsibility is review. The real world is not the internet; its fault tolerance is extremely low. Behind every bridge drawing, drug formula, financial statement, and legal document, there must stand a person who can be held accountable (because chopping off an AI's head accomplishes nothing). When AI monopolizes generation, what humans can and must do is verify it and sign off on its results. I believe reviewing AI's behavior and output is the only work left for the working class: we shift from producers to reviewers.

But review is far harder than generation. AI's mistakes tend to look perfectly correct; only someone who knows more than it does can catch its errors. That means review demands professional skill and long training — something not everyone can achieve.

The other path is to go deep into a field, so deep that AI needs you. AI's knowledge is average: broad but shallow. It shines where data is dense; in the sparse depths of a specialized field, it fails confidently. Take the field I know, PDF: the spec runs nearly a thousand pages, real-world malformed documents are endlessly weird, and AI-written parsing code that looks flawless collapses on edge cases — while someone who has read the PDF.js source spots the problem at a glance.

This path runs in two directions: inward, use AI as a research assistant, exploring the depths of a field through long conversations; outward, package what you learn into tools and hand them to other AIs. At that point you are no longer AI's competitor — you are its eyes and hands. Or you become the reviewer for AI in that field, returning to the path above.

Conclusion

Frankly, AI is terrifying for ordinary people: a human needs over a decade of schooling to become a functioning adult, while AI is born with all of it. In the first three industrial revolutions, humanity held everything together with its intelligence; this time, intelligence itself is what the revolution has come for.

Revolutions kill people. But after every revolution settles, the survivors stand on new means of production. This time, I hope the ones standing on top are us who learned to enslave AI — not us who were enslaved by it.

About me: founder of StreamPDF, working deep in the PDF domain and the AI domain. This article was created with AI assistance, reviewed by me, and I remain responsible for its content.

Original article: The AI Era: What Should We Do to Survive? (Reflections on Founding StreamPDF)

PDF.js Deep Dive from Demo 4: getViewport

StreamPDF — Thu, 05 Nov 2026 13:00:00 +0000

Introduction

In the previous article, we obtained the page variable via await pdf.getPage(1). It is a PDFPageProxy instance whose _pageInfo holds the page metadata: rotate: 0, userUnit: 1, view: [0, 0, 595, 842].

Back to the demo from the first article, lines 10-11:

const viewport = page.getViewport({ scale: 0.5 });

An object parameter is passed in:

Parameter	Value	Meaning
`scale`	`0.5`	The zoom factor

Unlike getPage, getViewport is a synchronous call: it does not touch the worker and performs no IO — it is purely a math computation. Starting from this call, this article walks through the complete execution of getViewport.

The getViewport call

Based on its definition in api.js, the execution flow is as follows.

Lines 1423-1439: Destructure the parameters

view source

getViewport({
  scale,                  // 0.5, the only parameter passed in
  rotation = this.rotate, // this._pageInfo.rotate = 0
  offsetX = 0,
  offsetY = 0,
  dontFlip = false,
} = {}) {
  return new PageViewport({
    viewBox: this.view,   // [0, 0, 595, 842]
    userUnit: this.userUnit, // 1
    scale,
    rotation,
    offsetX,
    offsetY,
    dontFlip,
  });
}

Note that the default value of rotation comes from the page itself: the PDF page's own /Rotate attribute is applied automatically, so the caller does not need to care about it. this.view and this.userUnit come from the pageInfo returned by the GetPage message in the previous article.

Once the parameters are collected, they are all handed to the PageViewport constructor (display/page_viewport.js): view source. All subsequent computation takes place there.

Q: What are offsetX / offsetY for?

A: They translate the rendered result on the canvas — for example, to tile multiple pages onto one large canvas, or to leave padding around a page. The demo does not pass them, so they default to 0.

Line 70: scale absorbs userUnit (`page_viewport.js`)

scale *= userUnit; // 0.5 * 1 = 0.5

Q: What is userUnit?

A: A unit conversion factor introduced in PDF 1.6: 1 unit in PDF user space = userUnit / 72 inches, with a default value of 1. By folding it into scale, subsequent computations no longer need to distinguish between "user space units" and "actual size".

Lines 74-75: Compute the page center point (`page_viewport.js`)

const centerX = (viewBox[2] + viewBox[0]) / 2; // (595 + 0) / 2 = 297.5
const centerY = (viewBox[3] + viewBox[1]) / 2; // (842 + 0) / 2 = 421

Rotation happens around the page center, so the center point is computed first for later use.

Lines 78-116: Normalize the rotation and compute the rotation vector (`page_viewport.js`)

rotation %= 360; // 0
if (rotation < 0) {
  rotation += 360;
}
switch (rotation) {
  case 0:
    rotateA = 1;
    rotateB = 0;
    rotateC = 0;
    rotateD = -1;
    break;
  // case 90 / 180 / 270 omitted
  default:
    throw new Error('PageViewport: Invalid rotation, must be a multiple of 90 degrees.');
}

The rotation is normalized into the [0, 360) range, and only multiples of 90 are allowed; any other value throws an error directly — this is a restriction of the PDF specification.

The demo's rotation is 0, which hits case 0: rotateA = 1, rotateB = 0, rotateC = 0, rotateD = -1.

Q: Why is rotateD -1 when rotation is 0?
A: This is the y-axis flip. In the PDF coordinate system the y-axis points up (a mathematical coordinate system with the origin at the bottom-left), while in the canvas coordinate system the y-axis points down (a screen coordinate system with the origin at the top-left). Even without any rotation, a flip is needed to align the two, and rotateD = -1 is exactly that flip.

Correspondingly, dontFlip = true negates rotateC and rotateD, canceling this flip — useful when the target coordinate system also has an upward y-axis.

Lines 120-130: Compute width, height, and canvas offsets (`page_viewport.js`)

if (rotateA === 0) {
  // The branch for rotation 90/270: width and height are swapped
  offsetCanvasX = Math.abs(centerY - viewBox[1]) * scale + offsetX;
  offsetCanvasY = Math.abs(centerX - viewBox[0]) * scale + offsetY;
  width = (viewBox[3] - viewBox[1]) * scale;
  height = (viewBox[2] - viewBox[0]) * scale;
} else {
  offsetCanvasX = Math.abs(centerX - viewBox[0]) * scale + offsetX; // 297.5 * 0.5 + 0 = 148.75
  offsetCanvasY = Math.abs(centerY - viewBox[1]) * scale + offsetY; // 421 * 0.5 + 0 = 210.5
  width = (viewBox[2] - viewBox[0]) * scale; // 595 * 0.5 = 297.5
  height = (viewBox[3] - viewBox[1]) * scale; // 842 * 0.5 = 421
}

The rotateA === 0 branch corresponds to a 90/270 degree rotation: the page lies on its side, and the computations of width and height are swapped. The demo's rotation is 0, so it takes the else branch.

Lines 134-141: Assemble the transform matrix (`page_viewport.js`)

this.transform = [
  rotateA * scale, // 0.5
  rotateB * scale, // 0
  rotateC * scale, // 0
  rotateD * scale, // -0.5
  offsetCanvasX - rotateA * scale * centerX - rotateC * scale * centerY, // 148.75 - 148.75 - 0 = 0
  offsetCanvasY - rotateB * scale * centerX - rotateD * scale * centerY, // 210.5 - 0 + 210.5 = 421
];
// transform = [0.5, 0, 0, -0.5, 0, 421]

The source code comment explains the composite transformation these 6 components correspond to:

translate(-centerX, -centerY), rotate and flip vertically, scale, and translate(offsetCanvasX, offsetCanvasY)

That is: move the page center to the origin → rotate and flip vertically → scale → translate to the target position on the canvas. These are exactly the 6 arguments that canvas setTransform(a, b, c, d, e, f) needs, and they will be applied directly during rendering (covered in the next article).

Let's verify the correctness of the matrix: take the top-left corner of the page in the PDF coordinate system, (0, 842) (with the y-axis pointing up, "top" is the larger value), and apply the matrix:

x' = 0.5 * 0 + 0 * 842 + 0 = 0
y' = 0 * 0 + (-0.5) * 842 + 421 = 0

It maps exactly to the canvas coordinate (0, 0), i.e., the top-left corner of the canvas. ✓

The 6th component, 421, happens to equal height: after the y-axis flip, the whole page ends up above the canvas (negative y), so it needs to be translated down by one page height to land back inside the canvas.

Lines 143-144: Store width and height (`page_viewport.js`)

this.width = width; // 297.5
this.height = height; // 421

These two values are the source of canvas.width = Math.floor(viewport.width) in the first article's demo: Math.floor(297.5) is 297, so the actual canvas size is 297 x 421.

At this point, all of getViewport's computation is complete, and the returned PageViewport instance is assigned to the demo's viewport variable.

Summary

This article followed the demo through the complete computation of getViewport({ scale: 0.5 }):

Parameter destructuring: scale = 0.5, rotation defaults to the page's /Rotate value 0, and the rest are 0/false;
scale absorbs userUnit, remaining 0.5;
Compute the page center point (297.5, 421);
After rotation normalization, take the rotation vector (1, 0, 0, -1), where rotateD = -1 performs the y-axis flip;
Compute the width and height 297.5 x 421 and the canvas offsets (148.75, 210.5);
Assemble transform = [0.5, 0, 0, -0.5, 0, 421], completing the "PDF coordinates → canvas coordinates" mapping.

viewport also carries methods like convertToViewportPoint / convertToPdfPoint (bidirectional coordinate conversion, used for text selection and annotation positioning: view source) and clone (deriving a new viewport: view source), which the demo does not use, so we will not expand on them here.

With the viewport in hand, the demo packages it together with canvasContext and passes them to page.render(renderContext) — the transform matrix will be applied to the canvas context there. That will be covered in the next article.

About me: Creator of StreamPDF, focused on research and development in AI and PDF.

Original article: PDF.js Deep Dive from Demo 4: getViewport

PDF.js Deep Dive from Demo 3: getPage

StreamPDF — Wed, 04 Nov 2026 15:10:31 +0000

Introduction

In the demo of the first article, we obtained the pdf variable via await loadingTask.promise — that promise is resolved by the main thread's GetDoc handler after the worker sends back the GetDoc message; see article 13 for details — and it is an instance of PDFDocumentProxy.

Back to the demo in the first article, lines 8-9:

const page = await pdf.getPage(1);

The getPage call

This call passes a single numeric argument:

Parameter	Value	Meaning
`pageNumber`	`1`	Page number; the first page is 1 (1-based)

getPage returns a Promise that resolves to a PDFPageProxy object. This article follows that single call through the full execution chain of getPage.

According to the definition in api.js, the execution flow is as follows.

Lines 773-775: PDFDocumentProxy.getPage: a one-line delegation

getPage(pageNumber) {
  return this._transport.getPage(pageNumber);
}

The pdf object itself is just a facade; the real logic lives entirely on this._transport — the WorkerTransport instance created in article 2 (task._transport).

Everything below happens inside WorkerTransport.getPage.

Lines 3031-3037: Validate the arguments

if (!Number.isInteger(pageNumber) || pageNumber <= 0 || pageNumber > this.pagesMapper.pagesNumber) {
  return Promise.reject(new Error('Invalid page request.'));
}

Plugging the demo values into each condition:

Condition	With `pageNumber = 1`	Result
`!Number.isInteger(pageNumber)`	`Number.isInteger(1)` is `true`, so the negation is `false`	Not hit
`pageNumber <= 0`	`1 <= 0` is `false`	Not hit
`pageNumber > this.pagesMapper.pagesNumber`	`pagesNumber` is `756`, `1 > 756` is `false`	Not hit

pagesNumber is 756, written from pdfInfo.numPages when the document becomes ready: view source. The demo PDF in this article has 756 pages, so validation passes. If you pass 0, a negative number, a decimal, or a number beyond the page count, this returns a rejected promise immediately.

Q: Why use Promise.reject instead of throw?
A: To keep the asynchronous semantics consistent. Callers of getPage always await a promise, so argument errors go through the same error channel. Callers don't have to handle both a synchronous throw and an asynchronous rejection.

Lines 3038-3039: Convert the page number

const pageIndex = pageNumber - 1; // 1 - 1 = 0
const newPageIndex = this.pagesMapper.getPageId(pageNumber) - 1; // 1 - 1 = 0

These two lines produce three page numbering schemes, each serving a different consumer:

Variable	Perspective	Base	Value here	Purpose
`pageNumber`	User	1-based	`1`	The public `getPage` argument
`pageIndex`	Main thread	0-based	`0`	Key of `#pageCache` / `#pagePromises`
`newPageIndex`	Worker (original document)	0-based	`0`	Payload of the `GetPage` message

pagesMapper.getPageId(1) returns 1. The demo never moves, deletes, or copies pages, so the mapping is an identity mapping (#pageNumberToId is null), and therefore newPageIndex === pageIndex === 0. The three only diverge once the document has been edited.

PagesMapper: translating between user page numbers and original page order

PagesMapper was created with new PagesMapper() during argument parsing in article 2: view source. It exposes just two things:

pagesNumber: the current total page count. Once assigned, the internal #pageNumberToId / #prevPageNumbers are reset to null, falling back to the identity mapping;
getPageId(pageNumber) / getPageNumber(pageId): two-way translation (L462-L464, L443-L454). Under the identity mapping they return their input unchanged; only an actual page reorder builds a real table.

Q: Why go through PagesMapper at all?
A: To support page reordering. In an editor scenario, users can move, delete, and copy pages, after which "page 3" may no longer be the original document's page 3. The worker side only understands the original document's page order, so what gets sent to the worker is newPageIndex, while the two main-thread caches are keyed by the user-facing pageIndex. Under an identity mapping the two are identical and can be ignored. Note: PagesMapper has nothing to do with the PDF file itself — the PDF contains no such data; it exists purely to hold state while editing.

One sentence to distinguish them: pageIndex is the cache key on the main thread, while newPageIndex is the key sent to the worker.

Lines 3041-3044: Check the cache

const cachedPromise = this.#pagePromises.get(0); // pageIndex = 0
if (cachedPromise) {
  return cachedPromise;
}

#pagePromises is a Map<pageIndex, Promise<PDFPageProxy>>. On the first call there is no cache hit, so we continue.

Q: What does the cache actually do?
A: In practice, calling await pdf.getPage(1) twice in a row returns the same PDFPageProxy object (page === page2 is true). The second call hits the cached promise directly and no message is sent to the worker.

Three layers of cache: separate stores, separate jobs

WorkerTransport declares all three Maps as class fields in one place: view source

#pageCache = new Map();
#pagePromises = new Map();
#pageRefCache = new Map();

Field	Key → Value	Responsibility	Typical use
`#pageCache`	`pageIndex → PDFPageProxy`	Index of created page objects	`StartRenderPage` looks up a page by index (api.js#L2805); `startCleanup` iterates it (api.js#L3227)
`#pagePromises`	`pageIndex → Promise<PDFPageProxy>`	Deduplicates in-flight requests and repeat calls	Read at the top of `getPage` (line 3041 here), written at the end (line 3067)
`#pageRefCache`	`refStr → pageIndex`	Reverse lookup from object reference to page index	Written by `getPage` (line 3054), read by `cachedPageNumber` (api.js#L3245-L3255)

All three share the same lifetime and are cleared when the transport is destroyed: destroy() clears them in turn (api.js#L2611-L2616).

Q: Why keep #pagePromises when #pageCache already holds the page object?
A: They solve different problems. #pagePromises is written before the message even leaves, so that "several getPage calls arriving at the same time only send one GetPage message". #pageCache is only written after the reply arrives, so that transport-internal events can look up objects by page index. Caching the promise rather than the page is precisely what covers the window before the reply arrives.

Lines 3045-3048: Send the GetPage message to the worker

const promise = this.messageHandler
  .sendWithPromise('GetPage', {
    pageIndex: newPageIndex, // 0
  })
  .then(pageInfo => {
    // The reply handling is covered in the next section
  });

messageHandler is the MessageHandler created in article 2. The communication mechanism of sendWithPromise is covered in article 6. All you need to know here is that it sends the message to the worker thread and returns a promise that waits for the worker's reply.

When the worker receives GetPage: view source

handler.on('GetPage', async function ({ pageIndex }) {
  const page = await pdfManager.getPage(pageIndex);
  const [rotate, ref, userUnit, view] = await Promise.all([
    pdfManager.ensure(page, 'rotate'),
    pdfManager.ensure(page, 'ref'),
    pdfManager.ensure(page, 'userUnit'),
    pdfManager.ensure(page, 'view'),
  ]);
  return {
    rotate,
    ref,
    refStr: ref?.toString() ?? null,
    userUnit,
    view,
  };
});

How the worker parses the page object internally is covered in article 14. The reply for the demo's first page is:

pageInfo = {
  rotate: 0,
  ref: { num: 4, gen: 0 }, // after structured cloning across threads, the Ref instance degrades to a plain object
  refStr: '4R', // the result of ref.toString() on the worker side
  userUnit: 1,
  view: [0, 0, 595, 842],
};

Field	Value here	Meaning	Matching `PDFPageProxy` getter
`rotate`	`0`	Clockwise rotation in degrees	`rotate`
`ref`	`{ num: 4, gen: 0 }`	Object reference (the entry Ref of this page in the PDF file)	`ref`
`refStr`	`"4R"`	String form of the reference, used as a cache key	None (internal only)
`userUnit`	`1`	User unit conversion factor	`userUnit`
`view`	`[0, 0, 595, 842]`	Visible area (PDF user space)	`view`

The 595 × 842 of view is exactly A4 paper size in 1/72-inch units, matching the demo's PDF specification.

Q: What is ref: { num: 4, gen: 0 }? Why isn't it a Ref instance?

A: It is PDF's Indirect Reference — every object in a PDF file has a unique (num, gen) number, and the page object is no exception. num = 4 means "object #4", gen = 0 is the generation number (almost always 0 in new PDFs; it only bumps up after incremental updates).

On the worker side this was a real Ref instance: view source created via Ref.get(4, 0), with a cached private #str = '4R'. But it cannot cross threads: Web Worker postMessage uses Structured Clone, which only copies enumerable own properties. Ref's #str is a private field — it doesn't clone — and class instances degrade to plain objects, leaving only the two public fields num and gen. That's why the main thread receives { num: 4, gen: 0 }.

The main-thread PDFPageProxy.ref getter (api.js#L1399) simply returns this plain object — it never reconstructs a Ref, because the main thread only ever needs to read num / gen and never sends them back as-is. Later messages like GetPageIndex or the editor's SaveDocument rebuild a Ref on the worker side from these two fields.

Why pre-compute refStr on the worker side? Precisely because Ref#toString() is lost after crossing threads — the main thread holds only a plain object and can't call toString. So the worker pre-computes refStr: ref?.toString() ?? null in its return value. Two fields, two roles: ref for callers that need to split num / gen, refStr for cache lookups that need a string key.

Q: Why is refStr "4R" rather than "4 0 R"?

A: Ref#toString returns the compact string cached inside the object: numR when gen is zero, numRgen otherwise: view source. The reverse-lookup side, cachedPageNumber, builds its key as ${ref.num}R as well, so both sides use the same format.

Q: Why only these 4 properties?

A: They are all metadata of the page: rotation angle, object reference, unit conversion factor, and visible area. Reading them only requires parsing the page object dictionary, without touching the page content stream. The real content parsing (drawing commands) is deferred to the GetOperatorList message at render time. This is why getPage can return quickly.

These 4 properties map one-to-one to getters on PDFPageProxy: rotate, ref, userUnit, and view. The next article's getViewport will use two of them.

Lines 3049-3068: Handle the reply and create the PDFPageProxy

Once the reply arrives, we enter the .then callback:

.then(pageInfo => {
  if (this.destroyed) {
    throw new Error("Transport destroyed");
  }
  if (pageInfo.refStr) {
    this.#pageRefCache.set(pageInfo.refStr, newPageIndex); // "4R" -> 0
  }

  const page = new PDFPageProxy(
    pageIndex,          // 0
    pageInfo,
    this,
    this.pagesMapper,
    this._params.pdfBug // false
  );
  this.#pageCache.set(pageIndex, page);
  return page;
});
this.#pagePromises.set(pageIndex, promise); // line 3067
return promise;                             // line 3068

Four things happen in sequence:

destroyed check: while waiting for the reply, the document may already have been destroyed (loadingTask.destroy()); if so, throw an error;
#pageRefCache reverse-lookup cache: "4R" → 0. Used by cachedPageNumber(ref) for reverse lookups — for example, when an outline link jumps to a page, the PDF internally locates pages by object reference (4 0 R), which must be translated back to a page number;
Create the PDFPageProxy and store it in #pageCache;
Store the promise itself in #pagePromises.

Q: Why does #pageRefCache store newPageIndex rather than pageIndex?

A: Because it records "which page of the original document this object reference points to", which has nothing to do with the user's perspective. During reverse lookup, cachedPageNumber first obtains the original page index, then translates it back to the user page number via pagesMapper.getPageNumber(pageIndex + 1) (api.js#L3245-L3255). Under an identity mapping the two happen to be equal, but semantically they are not interchangeable.

The PDFPageProxy constructor: assignment only, no parsing

View source

constructor(pageIndex, pageInfo, transport, pagesMapper, pdfBug = false) {
  this._pageIndex = pageIndex;                  // 0
  this._pageInfo = pageInfo;                    // the pageInfo received above
  this._transport = transport;
  this._stats = pdfBug ? new StatTimer() : null; // false, so performance stats are not enabled
  this._pdfBug = pdfBug;
  this.commonObjs = transport.commonObjs;       // resource container shared across the whole document (fonts, etc.)
  this.objs = new PDFObjects();                 // resource container private to this page
  this._intentStates = new Map();               // rendering intent state cache, used by render in article 5
  this.destroyed = false;
  this.recordedBBoxes = null;                   // recorded regions for the editor scenario
  this.#pagesMapper = pagesMapper;
  this.imageCoordinates = null;                 // image coordinate mapping, only populated after rendering
}

The whole constructor contains not a single await and does no parsing at all; it only moves references around and seeds placeholders:

_pageIndex is exposed to the outside as pageNumber via a getter returning _pageIndex + 1;
_pageInfo is the pageInfo above; all four getters read from it;
commonObjs and objs are resource containers used later during rendering; PDFObjects will be covered in a separate article;
recordedBBoxes / imageCoordinates stay null until the first render.

This is also why the main-thread cost of getPage is so small: the heavy lifting happens entirely on the worker thread, and the main thread only assembles the object.

At this point, the promise returned by getPage(1) resolves to page, and the demo's await receives it.

Summary

In this section we followed the demo through the complete getPage(1) call:

PDFDocumentProxy.getPage delegates in one line to WorkerTransport.getPage;
Argument validation: 1 is a valid page number (756 pages in total);
Page number conversion: pageNumber(1) → pageIndex(0) → newPageIndex(0); under the identity mapping all three agree;
The #pagePromises cache is checked and missed on the first call;
A GetPage message is sent to the worker, and rotate / ref / refStr / userUnit / view come back;
#pageRefCache is written, the PDFPageProxy is created, and #pageCache is populated;
The promise is stored in #pagePromises and returned; the demo's await yields page.

With page in hand, the demo's next step is page.getViewport({ scale: 0.5 }) — which will use the view and userUnit from this article's pageInfo. That will be covered in the next article.

About me: Creator of StreamPDF, focused on research and development in AI and PDF.
Original article: https://streampdf.com/blog/pdfjs-deep-dive-from-demo-3-get-page

PDF.js Deep Dive from Demo 2: getDocument

StreamPDF — Tue, 03 Nov 2026 13:00:00 +0000

Introduction

The demo in the previous article called getDocument with only { url: '...' }. This article follows that single call through the full execution chain of getDocument.

The getDocument call

The source parameter is named src. The demo passes only one key:

Key in `src`	Value
`url`	`'https://assets-blog.streampdf.com/PDF32000_2008.pdf'`

Based on the definition of getDocument in display/api.js, the execution flow is as follows.

Lines 235-236: Initialize the loading task

Instantiate the PDFDocumentLoadingTask class: view source, and assign the return value to the task variable.

Extract docId from task; at this point docId is d0.

Lines 238-335: Validate and process parameters

This block of code expands the user-provided src object into 35+ local variables: provided values are validated and type-converted, while missing ones fall back to defaults. The demo only passes url, so the vast majority of parameters take the default branch.

The only provided url is converted into a URL object by getUrlProp:

const url = URL.parse('https://assets-blog.streampdf.com/PDF32000_2008.pdf', window.location);
// const url = src.url ? getUrlProp(src.url) : null;

All other parameters are absent. In source order, the computed results are:

Variable	Result	Logic
`data`	`null`	If provided, normalized to `Uint8Array` by `getDataProp`
`httpHeaders`	`null`	Passed through as-is; `null` when absent
`withCredentials`	`false`	Only accepts `=== true`
`password`	`null`	`?? null`
`rangeTransport`	`null`	Only accepts a `PDFDataRangeTransport` instance
`rangeChunkSize`	`2 ** 16` (64KB)	Only accepts the provided value if it is a positive integer
`worker`	`null`	Only accepts a `PDFWorker` instance
`verbosity`	`undefined`	Taken verbatim from `src.verbosity`
`docBaseUrl`	`null`	Only accepts a string that is not a `data:` URL
`cMapUrl`	`null`	`getFactoryUrlProp`: non-string becomes `null`, and it must end with `/`
`cMapPacked`	`true`	`!== false`
`iccUrl`	`null`	Same as `cMapUrl`
`standardFontDataUrl`	`null`	Same as `cMapUrl`
`wasmUrl`	`null`	Same as `cMapUrl`
`ignoreErrors`	`true`	`src.stopAtErrors !== true`, see below
`maxImageSize`	`-1` (unlimited)	Only accepted if an integer and > -1
`isOffscreenCanvasSupported`	`true`	Defaults to `!isNodeJS` when absent
`isImageDecoderSupported`	`true`	Defaults to `!isNodeJS` when absent
`canvasMaxAreaInBytes`	`-1` (unlimited)	Only accepted if an integer
`disableFontFace`	`false`	Defaults to `isNodeJS` when absent
`fontExtraProperties`	`false`	Only accepts `=== true`
`enableXfa`	`false`	Only accepts `=== true`
`ownerDocument`	`globalThis.document`	Defaults to the global `document` when absent
`disableRange`	`false`	Only accepts `=== true`
`disableStream`	`false`	Only accepts `=== true`
`disableAutoFetch`	`false`	Only accepts `=== true`
`pdfBug`	`false`	Only accepts `=== true`
`CanvasFactory`	`DOMCanvasFactory`	Environment branch, see below
`FilterFactory`	`DOMFilterFactory`	Same as above
`BinaryDataFactory`	`DOMBinaryDataFactory`	Same as above
`enableHWA`	`false`	Only accepts `=== true`
`enableWebGPU`	`false`	Only accepts `=== true`
`gpuPromise`	`Promise.resolve(false)`	WebGPU is off, so GPU initialization does not start
`useWasm`	`true`	`!== false`
`pagesMapper`	`new PagesMapper()`	Created fresh when absent
`useSystemFonts`	`true`	Cascading default, see below
`useWorkerFetch`	`false`	Compound check, see the Q&A below
`styleElement`	`null`	Only preserved in TESTING builds; always `null` in production

These are all the local variables produced by this block of code. Most of the checks are trivial "fall back to default when absent" cases, but a few deserve a closer look.

ignoreErrors: a semantically inverted internal variable

The user-facing parameter is called stopAtErrors, yet the internal variable is called ignoreErrors, computed as src.stopAtErrors !== true. In other words, the default behavior is to ignore errors: when parsing fails, try to recover rather than rejecting promises such as getOperatorList / getTextContent / RenderTask. When reading the source, it is very easy to copy the name and value the wrong way around here.

rangeChunkSize: the 64KB setup for later

rangeChunkSize defaults to 64KB. Since disableRange = false, when the transport is created later, range requests will be issued against the PDF, and each fetched chunk will be exactly this size. Keep it in mind for now.

docBaseUrl: why data: URLs are excluded

The source comment explains the reason: a data: URL cannot be used to resolve absolute paths, and it contains the entire PDF document with no upper bound on length, so it is not sent to the worker thread.

gpuPromise: designed to run in parallel with worker startup

const gpuPromise = Promise.resolve(false); // enableWebGPU ? initGPU() : Promise.resolve(false);

Even when WebGPU is disabled, this immediately returns a resolved promise instead of deferring the check until it is used. The comment explains the intent: let GPU initialization run in parallel with worker startup, with the resolved boolean forwarded to the worker afterwards.

The three Factories: environment branches

const CanvasFactory = DOMCanvasFactory;
// src.CanvasFactory || (GENERIC build && isNodeJS ? NodeCanvasFactory : DOMCanvasFactory);

The same applies to FilterFactory and BinaryDataFactory. The check has three tiers: user-provided custom > Node environment implementation > DOM implementation. The demo runs in a browser without customization, so all three factories are the DOM versions. Their responsibilities:

CanvasFactory: creates canvases for rendering
FilterFactory: creates image filters (such as SVG filters)
BinaryDataFactory: downloads built-in static assets; works together with useWorkerFetch below

useSystemFonts: the default depends on other parameters

const useSystemFonts = true;
// typeof src.useSystemFonts === "boolean" ? src.useSystemFonts : !isNodeJS && !disableFontFace;

Its default depends on disableFontFace, which was just parsed above. Why? Fonts not embedded in the PDF are loaded as FontFaces; if disableFontFace is true, that loading path is disabled, and falling back to system fonts at that point would produce completely garbled glyphs. So in that scenario the default is simply false as well, avoiding rendering utterly broken fonts.

useWorkerFetch: a compound check

const useWorkerFetch = false;
// typeof src.useWorkerFetch === "boolean"
//   ? src.useWorkerFetch
//   : MOZCENTRAL ||
//     !!(
//       BinaryDataFactory === DOMBinaryDataFactory &&
//       cMapUrl && cMapPacked && standardFontDataUrl && wasmUrl &&
//       isValidFetchUrl(cMapUrl, document.baseURI) &&
//       isValidFetchUrl(standardFontDataUrl, document.baseURI) &&
//       isValidFetchUrl(wasmUrl, document.baseURI)
//     );

Q: What is this check doing?
A: It decides who downloads the built-in static assets (CMap files, standard font files, wasm files): the worker thread downloads them itself via the Fetch API (true), or the main thread downloads them and forwards them to the worker (false).

If the user explicitly passes a boolean, the user's value is used directly. Otherwise the default is computed: MOZCENTRAL (the Firefox built-in viewer) is always true; for a regular build, all three of the following conditions must hold at the same time for it to be true:

No custom BinaryDataFactory — because when useWorkerFetch is true, that parameter is simply ignored (inside transportFactory, binaryDataFactory is set to null). A user-provided factory must be respected, so the default cannot be true;

cMapUrl / standardFontDataUrl / wasmUrl are all provided, and cMapPacked is true — without URLs there is nothing to fetch;

These three URLs resolve to http/https relative to document.baseURI — the Fetch API only supports http/https, not file/ftp.

The demo in this article only passes url, so cMapUrl is null, condition 2 is not met, and therefore useWorkerFetch = false: the main-thread path is taken, with DOMBinaryDataFactory downloading on the main thread, and the worker requesting data from the main thread via FetchBinaryData messages when needed.

Lines 338: Set the main-thread log level

setVerbosityLevel(verbosity); // verbosity is undefined

verbosity is undefined, so the main-thread log level stays at its default. Note that this only affects the main thread; the worker thread's log level is passed separately when the worker is created.

Lines 342-350: Instantiate the three factories

const transportFactory = {
  canvasFactory: new DOMCanvasFactory({ ownerDocument: document, enableHWA: false }),
  filterFactory: new DOMFilterFactory({ docId: 'd0', ownerDocument: document }),
  binaryDataFactory: new DOMBinaryDataFactory({
    cMapUrl: null,
    standardFontDataUrl: null,
    wasmUrl: null,
  }),
};
// binaryDataFactory: null when MOZCENTRAL or useWorkerFetch is true

The three Factory classes selected earlier are instantiated and packaged as transportFactory, which is then handed to the transport. Since useWorkerFetch = false, binaryDataFactory is not null — echoing the Q&A in the previous section: built-in static assets are downloaded on the main thread.

Instantiate DOMCanvasFactory: view source

Instantiate DOMFilterFactory: view source

Instantiate DOMBinaryDataFactory: view source

Lines 352-360: Create the worker

worker = PDFWorker.create({ verbosity: undefined, port: undefined });
// port comes from GlobalWorkerOptions.workerPort, which the demo does not set
task._worker = worker;

The demo does not pass a worker, so PDF.js creates and owns one itself. PDFWorker.create synchronously returns a PDFWorker instance; its constructor reads GlobalWorkerOptions.workerSrc (the worker file URL configured in the first article), creates a Worker, and completes the startup handshake through ready / test messages — covered in detail in Article 8. For now, just remember: worker.promise is a Promise<void> that resolves (to undefined) once the test reply succeeds, and rejects if startup fails or the worker is destroyed.

Lines 362-402: Assemble the two parameter packages

The first is docParams, which will later be sent across threads to the worker:

const docParams = {
  docId: 'd0',
  apiVersion: '6.3.289', // build version number
  data: null,
  password: null,
  disableAutoFetch: false,
  rangeChunkSize: 65536,
  docBaseUrl: null,
  enableXfa: false,
  evaluatorOptions: {
    maxImageSize: -1,
    disableFontFace: false,
    ignoreErrors: true,
    isOffscreenCanvasSupported: true,
    isImageDecoderSupported: true,
    canvasMaxAreaInBytes: -1,
    fontExtraProperties: false,
    useSystemFonts: true,
    useWasm: true,
    useWorkerFetch: false,
    cMapUrl: null,
    cMapPacked: true,
    iccUrl: null,
    standardFontDataUrl: null,
    wasmUrl: null,
    hasGPU: false, // placeholder, backfilled later
  },
};

The second is transportParams, which stays on the main thread:

const transportParams = {
  ownerDocument: document,
  pdfBug: false,
  styleElement: null,
  enableHWA: false,
  loadingParams: { disableAutoFetch: false, enableXfa: false },
};

One sentence to distinguish them: docParams is the "work order" sent to the worker, while transportParams is the "local configuration" kept on the main thread.

Lines 404-473: The handshake after the worker is ready

Promise.all([worker.promise, gpuPromise]).then(...)

Once both worker readiness and GPU probing (resolving to false) complete, the following happens in sequence:

hasGPU = false is backfilled into evaluatorOptions;
A GetDocRequest message is sent to the worker with docParams as the payload. Since data is null, there is no buffer whose ownership needs to be transferred;
Choose the network stream: with data being null and rangeTransport being null, the url branch is taken and a network stream is instantiated (the fetch implementation is preferred, with a fallback to XHR when unsupported; see Article 9 for how range requests are issued internally):

networkStream = new NetworkStream({
  url,
  httpHeaders: null,
  withCredentials: false,
  rangeChunkSize: 65536,
  disableRange: false,
  disableStream: false,
});

NetworkStream here is not a fixed imported class; it is picked at runtime inside this branch:

const NetworkStream = getNetworkStream(url); // api.js#L431

getNetworkStream makes a three-way choice:

function getNetworkStream(url) {
  // eslint-disable-next-line no-nested-ternary
  return isValidFetchUrl(url)
    ? PDFFetchStream
    : typeof PDFJSDev !== 'undefined' && PDFJSDev.test('GENERIC') && isNodeJS
      ? PDFNodeStream
      : PDFNetworkStream;
}

Condition	Stream implementation
`isValidFetchUrl(url)`: protocol is `http` / `https`	`PDFFetchStream`
Otherwise, GENERIC build running in Node	`PDFNodeStream`
Everything else	`PDFNetworkStream` (XHR)

The demo's url is https://..., so it actually instantiates PDFFetchStream. The other inputs have their own streams too: rangeTransport uses PDFDataTransportStream, while data means the whole PDF is already in memory and no stream is created at all.

In summary: const NetworkStream = PDFFetchStream.

Execution continues:

Receive the worker's acknowledgment of GetDocRequest (workerId): click to view the event. The value returned here is d0_worker, assigned to the workerId variable
Create a MessageHandler with { docId: 'd0', workerId: 'd0_worker', port: Worker }: click to view the call, assigned to the messageHandler variable
Create a WorkerTransport with { messageHandler, task, networkStream, transportParams, transportFactory, pagesMapper }: click to view the call, attached to task._transport
Send a Ready message to the worker, declaring the main-thread side ready: click to view the event

At the end of the chain, task._setupCapability.resolve is called to settle the task's asynchronous setup.

Lines 474-475: Return value

All of the above .then chain proceeds asynchronously in the background, while getDocument itself returns task synchronously. If any step in the chain fails, the capability inside task is rejected — the very promise that the demo waits on with await loadingTask.promise.

At this point, getDocument has finished executing.

Summary

In this section we followed the demo through the complete getDocument call:

Create PDFDocumentLoadingTask and extract docId = 'd0';
Expand src into 35+ local variables; the demo only passes url, and everything else falls back to defaults;
Instantiate the three DOM factories and package them as transportFactory;
PDFWorker.create creates the worker and starts the handshake;
Assemble docParams (sent to the worker) and transportParams (kept on the main thread);
Once the worker is ready, send GetDocRequest, set up the network stream, create MessageHandler and WorkerTransport, and finally send Ready;
Return task synchronously; the demo waits for the document to be ready via await loadingTask.promise.

Back to the demo in the first article: lines 4-7 call exactly the getDocument dissected here.

Following the caller chain upward, the next call site is: getPage

About me: Creator of StreamPDF, focused on research and development in AI and PDF.

Original article: https://streampdf.com/blog/pdfjs-deep-dive-from-demo-1-custom-viewer

PDF.js Deep Dive from Demo 1: Rendering a PDF with a Custom Viewer

StreamPDF — Mon, 02 Nov 2026 13:00:00 +0000

Introduction

In our previous series of articles, we explored the architecture of PDF.js, as well as technical topics such as the rendering layer and message communication. However, while writing those articles, we identified a few problems:

The articles could not be connected to one another and failed to form a complete knowledge system.
They could not be mapped back to the PDF.js source code, so following along carried a heavy mental burden.

Therefore, we decided to start a new series that begins with demo code and gradually follows the call chain deep into the internals of PDF.js. We will explain the principles behind the code from two perspectives:

Demo interpretation: case-by-case interpretation, linked from shallow to deep, exploring in depth.
Repository interpretation: generalized interpretation that can be read in chunks, each standing on its own as an article.

Come on, let's start from the beginning.

Rendering a PDF with a Custom Viewer

Let's try building a minimal custom viewer to render a PDF, then follow each line of code into the internals of PDF.js. As we follow along, we will substitute variable values into the code to make the execution flow easier to understand.

import * as pdfjsLib from 'https://cdn.jsdelivr.net/npm/pdfjs-dist@6.3.289/build/pdf.mjs';
pdfjsLib.GlobalWorkerOptions.workerSrc =
  'https://cdn.jsdelivr.net/npm/pdfjs-dist@6.3.289/build/pdf.worker.mjs';
const loadingTask = pdfjsLib.getDocument({
  url: 'https://assets-blog.streampdf.com/PDF32000_2008.pdf',
});
const pdf = await loadingTask.promise;
// Get the rendering data of the first page
const page = await pdf.getPage(1);
// Get the viewport data of the first page
const viewport = page.getViewport({ scale: 0.5 });
// Get the canvas onto which we will render
const canvas = document.getElementById('canvas-id');
const context = canvas.getContext('2d');
// Match the canvas dimensions to the PDF viewport size
canvas.width = Math.floor(viewport.width);
canvas.height = Math.floor(viewport.height);
canvas.style.width = Math.floor(viewport.width) + 'px';
canvas.style.height = Math.floor(viewport.height) + 'px';
// Prepare the rendering parameters
const renderContext = {
  canvasContext: context,
  viewport,
};
// Call the render method to perform the actual rendering and return a renderTask
const renderTask = page.render(renderContext);
// Awaiting renderTask.promise is what actually waits for completion
await renderTask.promise;

demo: https://streampdf.com/blog/demos/a-simple-pdf-render-demo.html

Lines 1-3: Configure the Worker file path

Import the entry file of the PDF.js library and set the path of the Worker file.

This means that when using PDF.js, we can even completely replace the Worker with our own, as long as it follows the interface specification.

Here we set it to the default Worker file path:

GlobalWorkerOptions.workerSrc = https://cdn.jsdelivr.net/npm/pdfjs-dist@6.3.289/build/pdf.worker.mjs

Lines 4-7: Load the PDF document

Call the getDocument method to load the PDF document, passing in an object parameter:

url: the URL of the PDF document. The value is https://assets-blog.streampdf.com/PDF32000_2008.pdf.

The getDocument method returns a Promise that resolves to a PDF document object once the document has finished loading.

const loadingTask = pdfjsLib.getDocument(...) is a synchronous call: click to view the call.

loadingTask.promise is a getter that returns a Promise created by the Promise.withResolvers() method.

Here we await loadingTask.promise to wait for the PDF document to finish loading and assign it to the pdf variable.

Lines 8-9: Get the first page of the PDF document

Once the document has been initialized, we can call the getPage method to get the rendering data of the first page.

The getPage method returns a Promise that resolves to a page object once the page data has finished loading.

const page = await pdf.getPage(1); is an asynchronous call: click to view the call.

After the first page's data has finished loading, it is assigned to the page variable.

Lines 10-11: Get the viewport data of the first page

Once the page data has loaded, we can call the getViewport method to get the viewport data of the first page.

const viewport = page.getViewport({ scale: 0.5 }); is a synchronous call: click to view the call.

Get the viewport data of the first page, passing in an object parameter:

scale: the scale factor. The value is 0.5.

The returned viewport is an object containing the width and height of the viewport. Its value is:

{
  width: 297.5,
  height: 421,
  // others, not used here, omitted for now...
}

It is assigned to the viewport variable.

Lines 12-19: Get the canvas onto which we will render

After obtaining the viewport variable, match the canvas's width and height to the PDF viewport size.

canvas.width = 297; // Math.floor(viewport.width);
canvas.height = 421; // Math.floor(viewport.height);

Also set the canvas's CSS width and height to the PDF viewport size.

canvas.style.width = 297 + 'px'; // Math.floor(viewport.width) + 'px';
canvas.style.height = 421 + 'px'; // Math.floor(viewport.height) + 'px';

Why do we need to set the canvas's CSS width and height?
The canvas's width and height attributes control the pixel dimensions of the canvas, while the CSS width and height are the dimensions at which the canvas is displayed on the page. In general, these two are the same. But on high-resolution screens, they differ. For example, when window.devicePixelRatio is 2, the canvas's pixel dimensions should be set to 594 by 842, while the CSS width and height remain 297 by 421, to prevent blurry rendering.

Lines 20-28: Render the first page

Once the canvas is ready, we can call the render method to render the first page.

Prepare the canvas context, viewport data, and rendering parameters so that we can call the render method.

const renderTask = page.render(renderContext); is a synchronous call that returns a RenderTask object; await renderTask.promise is what actually waits for rendering to complete: click to view the call.

At this point, the code execution is complete.

Summary

In this chapter, we followed a custom viewer to render the first page of a PDF file.

The biggest difference from other articles is that we substituted variable values into the chain of code being analyzed, so that different execution paths can be determined. Different files and analysis articles lead into different branch paths, making reading the article feel like debugging the code.

We hope this brings you a different kind of source code reading experience.

happy coding!

About me: Creator of StreamPDF, focused on research and development in AI and PDF.

Original article: https://streampdf.com/blog/pdfjs-deep-dive-from-demo-1-custom-viewer

PDF.js Deep Dive 3: getViewport & render

StreamPDF — Mon, 26 Oct 2026 13:00:00 +0000

Introduction

This is the third article in the PDF.js Deep Dive series. In the previous article, we explored the Display layer's getDocument and getPage methods.

In this article, we dive into the getViewport and render methods exposed by the Display layer.

All code snippets in this article are based on PDF.js v6.3.289.

getViewport

For page.getViewport, the call lands on the PDFPageProxy.getViewport method.

/**
 * @param {GetViewportParameters} params - Viewport parameters.
 * @returns {PageViewport} Contains 'width' and 'height' properties
 *   along with transforms required for rendering.
 */
getViewport({
  scale,
  rotation = this.rotate,
  offsetX = 0,
  offsetY = 0,
  dontFlip = false,
} = {}) {
  return new PageViewport({
    viewBox: this.view,
    userUnit: this.userUnit,
    scale,
    rotation,
    offsetX,
    offsetY,
    dontFlip,
  });
}

which instantiates the PageViewport class.

Entering PageViewport

// Source: src/display/page_viewport.js
/**
 * @param {PageViewportParameters}
 */
constructor({
  viewBox,
  userUnit,
  scale,
  rotation,
  offsetX = 0,
  offsetY = 0,
  dontFlip = false,
}) {
  this.viewBox = viewBox;
  this.userUnit = userUnit;
  this.scale = scale;
  this.rotation = rotation;
  this.offsetX = offsetX;
  this.offsetY = offsetY;

  scale *= userUnit; // Take the userUnit into account.

  // creating transform to convert pdf coordinate system to the normal
  // canvas like coordinates taking in account scale and rotation
  const centerX = (viewBox[2] + viewBox[0]) / 2;
  const centerY = (viewBox[3] + viewBox[1]) / 2;
  let rotateA, rotateB, rotateC, rotateD;
  // Normalize the rotation, by clamping it to the [0, 360) range.
  rotation %= 360;
  if (rotation < 0) {
    rotation += 360;
  }
  switch (rotation) {
    case 180:
      rotateA = -1;
      rotateB = 0;
      rotateC = 0;
      rotateD = 1;
      break;
    case 90:
      rotateA = 0;
      rotateB = 1;
      rotateC = 1;
      rotateD = 0;
      break;
    case 270:
      rotateA = 0;
      rotateB = -1;
      rotateC = -1;
      rotateD = 0;
      break;
    case 0:
      rotateA = 1;
      rotateB = 0;
      rotateC = 0;
      rotateD = -1;
      break;
    default:
      throw new Error(
        "PageViewport: Invalid rotation, must be a multiple of 90 degrees."
      );
  }

  if (dontFlip) {
    rotateC = -rotateC;
    rotateD = -rotateD;
  }

  let offsetCanvasX, offsetCanvasY;
  let width, height;
  if (rotateA === 0) {
    offsetCanvasX = Math.abs(centerY - viewBox[1]) * scale + offsetX;
    offsetCanvasY = Math.abs(centerX - viewBox[0]) * scale + offsetY;
    width = (viewBox[3] - viewBox[1]) * scale;
    height = (viewBox[2] - viewBox[0]) * scale;
  } else {
    offsetCanvasX = Math.abs(centerX - viewBox[0]) * scale + offsetX;
    offsetCanvasY = Math.abs(centerY - viewBox[1]) * scale + offsetY;
    width = (viewBox[2] - viewBox[0]) * scale;
    height = (viewBox[3] - viewBox[1]) * scale;
  }
  // creating transform for the following operations:
  // translate(-centerX, -centerY), rotate and flip vertically,
  // scale, and translate(offsetCanvasX, offsetCanvasY)
  this.transform = [
    rotateA * scale,
    rotateB * scale,
    rotateC * scale,
    rotateD * scale,
    offsetCanvasX - rotateA * scale * centerX - rotateC * scale * centerY,
    offsetCanvasY - rotateB * scale * centerX - rotateD * scale * centerY,
  ];

  this.width = width;
  this.height = height;
}

It computes the rotation, the scale, the offsets, and the viewport dimensions after flipping — the page's width and height.

Let's zoom in on the PDF point and the CSS px units. In PDF, 72 points equal one inch; in CSS, 96 px equal one inch. That means rendering at 100% size on the web requires scaling PDF points up by 96/72.

PDF's coordinate system has its origin at the bottom-left corner, with the X axis pointing right and the Y axis pointing up. CSS's coordinate system has its origin at the top-left corner, with the X axis pointing right and the Y axis pointing down. So for an unrotated PDF, we need to flip the PDF's Y axis to match the web canvas coordinate system. That's why you see

case 0:
  rotateA = 1;
  rotateB = 0;
  rotateC = 0;
  rotateD = -1;

the rotateD of -1 in there — it exists precisely to flip the Y axis.

Flip demo: get-viewport-demo

MDN canvas transform

render

For page.render, the call lands on the PDFPageProxy.render method.

/**
 * Begins the process of rendering a page to the desired context.
 *
 * @param {RenderParameters} params - Page render parameters.
 * @returns {RenderTask} An object that contains a promise that is
 *   resolved when the page finishes rendering.
 */
render({
  canvasContext,
  canvas = canvasContext.canvas,
  viewport,
  intent = "display",
  annotationMode = AnnotationMode.ENABLE,
  transform = null,
  background = null,
  optionalContentConfigPromise = null,
  annotationCanvasMap = null,
  pageColors = null,
  printAnnotationStorage = null,
  isEditing = false,
  recordImages = false,
  recordOperations = false,
  operationsFilter = null,
}) {
  this._stats?.time("Overall");

  const intentArgs = this._transport.getRenderingIntent(
    intent,
    annotationMode,
    printAnnotationStorage,
    isEditing
  );
  const { renderingIntent, cacheKey } = intentArgs;
  // If there was a pending destroy, cancel it so no cleanup happens during
  // this call to render.
  this.#pendingCleanup = false;

  optionalContentConfigPromise ||=
    this._transport.getOptionalContentConfig(renderingIntent);

  const intentState = this._intentStates.getOrInsertComputed(
    cacheKey,
    makeObj
  );
  // Ensure that a pending `streamReader` cancel timeout is always aborted.
  if (intentState.streamReaderCancelTimeout) {
    clearTimeout(intentState.streamReaderCancelTimeout);
    intentState.streamReaderCancelTimeout = null;
  }

  const intentPrint = !!(renderingIntent & RenderingIntentFlag.PRINT);

  // If there's no displayReadyCapability yet, then the operatorList
  // was never requested before. Make the request and create the promise.
  if (!intentState.displayReadyCapability) {
    intentState.displayReadyCapability = Promise.withResolvers();
    intentState.operatorList = {
      fnArray: [],
      argsArray: [],
      lastChunk: false,
      separateAnnots: null,
    };

    this._stats?.time("Page Request");
    this._pumpOperatorList(intentArgs);
  }

  const recordForDebugger = !!(
    this._pdfBug && globalThis.StepperManager?.enabled
  );
  const shouldRecordOperations =
    !!canvas &&
    !this.recordedBBoxes &&
    (recordOperations || recordForDebugger);
  const shouldRecordImages =
    !!canvas && !this.imageCoordinates && recordImages;

  const complete = error => {
    intentState.renderTasks.delete(internalRenderTask);

    if (shouldRecordOperations) {
      const recordedBBoxes = internalRenderTask.gfx?.dependencyTracker.take();
      if (recordedBBoxes) {
        internalRenderTask.stepper?.setOperatorBBoxes(
          recordedBBoxes,
          internalRenderTask.gfx.dependencyTracker.takeDebugMetadata()
        );

        if (recordOperations) {
          this.recordedBBoxes = recordedBBoxes;
        }
      }
    }

    if (shouldRecordImages && !error) {
      this.imageCoordinates = internalRenderTask.gfx?.imagesTracker.take();
    }

    // Attempt to reduce memory usage during *printing*, by always running
    // cleanup immediately once rendering has finished.
    if (intentPrint) {
      this.#pendingCleanup = true;
    }
    this.#tryCleanup();

    if (error) {
      internalRenderTask.capability.reject(error);

      this._abortOperatorList({
        intentState,
        reason: error instanceof Error ? error : new Error(error),
      });
    } else {
      internalRenderTask.capability.resolve();
    }

    if (this._stats) {
      this._stats.timeEnd("Rendering");
      this._stats.timeEnd("Overall");

      if (globalThis.Stats?.enabled) {
        globalThis.Stats.add(this.pageNumber, this._stats);
      }
    }
  };

  let dependencyTracker = null;
  let bboxTracker = null;
  if (shouldRecordOperations || shouldRecordImages) {
    bboxTracker = new CanvasBBoxTracker(
      canvas,
      intentState.operatorList.length
    );
  }
  if (shouldRecordOperations) {
    dependencyTracker = new CanvasDependencyTracker(
      bboxTracker,
      recordForDebugger
    );
  }

  const internalRenderTask = new InternalRenderTask({
    callback: complete,
    // Only include the required properties, and *not* the entire object.
    params: {
      canvas,
      canvasContext,
      dependencyTracker: dependencyTracker ?? bboxTracker,
      imagesTracker: shouldRecordImages
        ? new CanvasImagesTracker(canvas)
        : null,
      viewport,
      transform,
      background,
    },
    objs: this.objs,
    commonObjs: this.commonObjs,
    annotationCanvasMap,
    operatorList: intentState.operatorList,
    pageIndex: this._pageIndex,
    canvasFactory: this._transport.canvasFactory,
    filterFactory: this._transport.filterFactory,
    useRequestAnimationFrame: !intentPrint,
    pdfBug: this._pdfBug,
    pageColors,
    enableHWA: this._transport.enableHWA,
    operationsFilter,
  });

  (intentState.renderTasks ||= new Set()).add(internalRenderTask);
  const renderTask = internalRenderTask.task;

  Promise.all([
    intentState.displayReadyCapability.promise,
    optionalContentConfigPromise,
  ])
    .then(([transparency, optionalContentConfig]) => {
      if (this.destroyed) {
        complete();
        return;
      }
      this._stats?.time("Rendering");

      if (!(optionalContentConfig.renderingIntent & renderingIntent)) {
        throw new Error(
          "Must use the same `intent`-argument when calling the `PDFPageProxy.render` " +
            "and `PDFDocumentProxy.getOptionalContentConfig` methods."
        );
      }
      internalRenderTask.initializeGraphics({
        transparency,
        optionalContentConfig,
      });
      internalRenderTask.operatorListChanged();
    })
    .catch(complete);

  return renderTask;
}

This is a very complex method — let's break it down into chunks.

Step 1: call getRenderingIntent to compute the rendering intent. There are three intents: any, display, and print.

Step 2: call this._intentStates.getOrInsertComputed to get or insert the computed intent state, keyed by the rendering intent from step 1.

Step 3: fetch the page's operator list.

// If there's no displayReadyCapability yet, then the operatorList
// was never requested before. Make the request and create the promise.
if (!intentState.displayReadyCapability) {
  intentState.displayReadyCapability = Promise.withResolvers();
  intentState.operatorList = {
    fnArray: [],
    argsArray: [],
    lastChunk: false,
    separateAnnots: null,
  };

  this._stats?.time('Page Request');
  this._pumpOperatorList(intentArgs);
}

There is a cache layer here: it checks whether intentState.displayReadyCapability exists. If it doesn't, a promise is created and the page's operator list is requested.

Q: What is intentState.displayReadyCapability? And why must we wait for this promise to resolve before we can actually render anything to the canvas?

A: It is the { promise, resolve, reject } returned by Promise.withResolvers(). Its promise resolves with the boolean transparency (whether the page contains blend modes, which decides whether rendering needs an alpha canvas).

We must wait for it to resolve for two core reasons. First, transparency is a required parameter of initializeGraphics — CanvasGraphics needs to know whether to enable the alpha channel to correctly handle blend modes, and this value can only be determined after the worker has parsed the page's content stream and resources. Second, it is essentially the "page ready" startup signal from the worker: the worker sends the StartRenderPage message before running getOperatorList, and the Display layer resolves it in _startRenderPage. Until this point the operatorList is still empty; chunks are only streamed in afterwards via _renderPageChunk, so the render pipeline must wait for this signal before it can start consuming them.

Note that it means "page resources are ready, ready to start receiving operator chunks", not "the operator list has been fully delivered" — whether everything has arrived is marked by intentState.operatorList.lastChunk.

Additionally, its existence doubles as a cache marker: as long as it already exists, the operator list for this rendering intent (cacheKey) has been requested before, so _pumpOperatorList doesn't need to be called again.

Step 4: instantiate the InternalRenderTask class and add it to the render task queue.

Step 5: wait for intentState.displayReadyCapability to resolve. Then initialize the graphics context with initializeGraphics, and notify that the operator list has changed with operatorListChanged — kicking off the actual rendering logic.

With the overall flow in place, let's analyze the execution logic of each step in detail.

Step 1: `getRenderingIntent`, computing the rendering intent

Entering PDFPageProxy.render → WorkerTransport.getRenderingIntent

// Source: src/display/api.js
getRenderingIntent(
  intent,
  annotationMode = AnnotationMode.ENABLE,
  printAnnotationStorage = null,
  isEditing = false,
  isOpList = false
) {
  let renderingIntent = RenderingIntentFlag.DISPLAY; // Default value.
  let annotationStorageSerializable = SerializableEmpty;

  switch (intent) {
    case "any":
      renderingIntent = RenderingIntentFlag.ANY;
      break;
    case "display":
      break;
    case "print":
      renderingIntent = RenderingIntentFlag.PRINT;
      break;
    default:
      warn(`getRenderingIntent - invalid intent: ${intent}`);
  }

  const annotationStorage =
    renderingIntent & RenderingIntentFlag.PRINT &&
    printAnnotationStorage instanceof PrintAnnotationStorage
      ? printAnnotationStorage
      : this.annotationStorage;

  switch (annotationMode) {
    case AnnotationMode.DISABLE:
      renderingIntent += RenderingIntentFlag.ANNOTATIONS_DISABLE;
      break;
    case AnnotationMode.ENABLE:
      break;
    case AnnotationMode.ENABLE_FORMS:
      renderingIntent += RenderingIntentFlag.ANNOTATIONS_FORMS;
      break;
    case AnnotationMode.ENABLE_STORAGE:
      renderingIntent += RenderingIntentFlag.ANNOTATIONS_STORAGE;

      annotationStorageSerializable = annotationStorage.serializable;
      break;
    default:
      warn(`getRenderingIntent - invalid annotationMode: ${annotationMode}`);
  }

  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("_"),
    annotationStorageSerializable,
    modifiedIds,
  };
}

There are three modes: any, display, and print.

any is for getOperatorList / getTextContent and other "any" scenarios.
display renders the page.
print prints the page.

Plus the annotationMode option, which controls whether annotations are rendered. And the isEditing editing mode.

Step 2: `this._intentStates.getOrInsertComputed`

this._intentStates is a Map that caches data keyed by the rendering intent.

makeObj is a utility function: const makeObj = () => Object.create(null);

getOrInsertComputed is a fairly new function in the JS spec: if the key exists, it returns the corresponding value; if it doesn't, it creates a value via the second-argument callback and returns it. See MDN.

Step 3: fetching the page's operator list

Here we check whether intentState.displayReadyCapability exists. If it does, the data was requested before and there's no need to call _pumpOperatorList again.

Otherwise we call _pumpOperatorList to request the page's operator list.

Entering PDFPageProxy.render → PDFPageProxy._pumpOperatorList

// Source: src/display/api.js
_pumpOperatorList({
  renderingIntent,
  cacheKey,
  annotationStorageSerializable,
  modifiedIds,
}) {
  if (typeof PDFJSDev === "undefined" || PDFJSDev.test("TESTING")) {
    assert(
      Number.isInteger(renderingIntent) && renderingIntent > 0,
      '_pumpOperatorList: Expected valid "renderingIntent" argument.'
    );
  }
  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; // Ignore any pending requests if the worker was terminated.
        }
        this._renderPageChunk(value, intentState);
        pump();
      },
      reason => {
        intentState.streamReader = null;

        if (this._transport.destroyed) {
          return; // Ignore any pending requests if the worker was terminated.
        }
        if (intentState.operatorList) {
          // Mark operator list as complete.
          intentState.operatorList.lastChunk = true;

          for (const internalRenderTask of intentState.renderTasks) {
            internalRenderTask.operatorListChanged();
          }
          this.#tryCleanup();
        }

        if (intentState.displayReadyCapability) {
          intentState.displayReadyCapability.reject(reason);
        } else if (intentState.opListReadCapability) {
          intentState.opListReadCapability.reject(reason);
        } else {
          throw reason;
        }
      }
    );
  };
  pump();
}

Here, through the transport, we send an important streaming event to the worker: GetOperatorList.

Entering PDFPageProxy.render → PDFPageProxy._pumpOperatorList → Worker: on GetOperatorList

handler.on(
  'GetOperatorList',
  function ({ pageId, pageIndex, intent, cacheKey, annotationStorage, modifiedIds }, sink) {
    pdfManager.getPage(pageId).then(function (page) {
      const task = new WorkerTask(`GetOperatorList: page ${pageIndex}`);
      startWorkerTask(task);

      // NOTE: Keep this condition in sync with the `info` helper function.
      const start = verbosity >= VerbosityLevel.INFOS ? Date.now() : 0;

      // Pre compile the pdf page and fetch the fonts/images.
      page
        .getOperatorList({
          handler,
          sink,
          task,
          intent,
          cacheKey,
          annotationStorage,
          modifiedIds,
          pageIndex,
        })
        .then(
          opListInfo => {
            if (start) {
              info(`${task.name}; time=${Date.now() - start}ms, len=${opListInfo.length}`);
            }
            sink.close();
          },
          reason => {
            if (task.terminated) {
              return; // ignoring errors from the terminated thread
            }
            sink.error(reason);
          },
        )
        .finally(() => {
          finishWorkerTask(task);
        });
    });
  },
);

It calls pdfManager.getPage to get the Page instance. This call points to NetworkPDFManager.getPage, which in turn points to BasePdfManager.getPage.

Entering PDFPageProxy.render → PDFPageProxy._pumpOperatorList → Worker: on GetOperatorList → NetworkPDFManager.getPage (parent BasePdfManager.getPage)

getPage(pageIndex) {
  return this.pdfDocument.getPage(pageIndex);
}

which calls this.pdfDocument.getPage.

Let's first see where this.pdfDocument comes from.

Entering PDFPageProxy.render → PDFPageProxy._pumpOperatorList → Worker: on GetOperatorList → NetworkPDFManager.constructor

this.pdfDocument = new PDFDocument(this, this.streamManager.getStream());

instantiating PDFDocument.

Entering PDFPageProxy.render → PDFPageProxy._pumpOperatorList → Worker: on GetOperatorList → NetworkPDFManager.constructor → PDFDocument.constructor

constructor(pdfManager, stream) {
  if (typeof PDFJSDev === "undefined" || PDFJSDev.test("TESTING")) {
    assert(
      stream instanceof BaseStream,
      'PDFDocument: Invalid "stream" argument.'
    );
  }
  if (stream.length <= 0) {
    throw new InvalidPDFException(
      "The PDF file is empty, i.e. its size is zero bytes."
    );
  }

  this.pdfManager = pdfManager;
  this.stream = stream;
  this.xref = new XRef(stream, pdfManager);

  const idCounters = {
    font: 0,
  };
  this._globalIdFactory = class {
    static getDocId() {
      return `g_${pdfManager.docId}`;
    }

    static createFontId() {
      return `f${++idCounters.font}`;
    }

    static createObjId() {
      unreachable("Abstract method `createObjId` called.");
    }

    static getPageObjId() {
      unreachable("Abstract method `getPageObjId` called.");
    }
  };
}

Here, an XRef instance is created to parse the PDF file's XRef table.

Q: What is the XRef table?

A: The XRef (Cross-Reference) table is the PDF file's "object directory". Every entity inside a PDF — pages, fonts, images, content streams, etc. — is a numbered object (e.g. 3 0 obj). The XRef table records the byte offset of each object within the file.

For example:
xref
0 5
0000000000 65535 f
0000000010 00000 n
0000000053 00000 n
0000000102 00000 n
0000000173 00000 n
The first line, 0 5, means the next 5 entries list the objects starting from object 0. Each entry is exactly 20 bytes: the first 10 digits are the byte offset, the middle 5 digits are the generation number, and the last one is n (in-use) or f (free/deleted).

When the parser gets an object reference (say 2 0 R, meaning "reference object 2"), it looks up the XRef table and computes the object's location in the file directly, instead of scanning the file from the start like XML/JSON. This is also the key to PDF's incremental updates (append-only): after each append-only modification, you only need to append a new XRef section and point the startxref pointer at the end of the file to the latest one.

In pdf.js, the XRef class parses this table, maintains the {object number → offset} mapping, and resolves the actual content of objects (when it hits an indirect reference like 2 0 R, it recursively parses until it gets the real value).

This is one of the optimization points in StreamPDF: the XRef table is pre-parsed on the server side. We won't expand on it here — a dedicated article will introduce it in detail later.

We won't go deeper for now — back to rendering. A later article will explore PDF.js's lexical and syntactic parsing of PDF documents.

Now that PDFDocument is initialized, let's return to the getPage method.

Entering PDFPageProxy.render → PDFPageProxy._pumpOperatorList → Worker: on GetOperatorList → NetworkPDFManager.getPage → PDFDocument.getPage

getPage(pageIndex) {
  const cachedPromise = this.#pagePromises.get(pageIndex);
  if (cachedPromise) {
    return cachedPromise;
  }
  const { catalog, linearization, xfaFactory } = this;

  let promise;
  if (xfaFactory) {
    promise = Promise.resolve([Dict.empty, null]);
  } else if (linearization?.pageFirst === pageIndex) {
    promise = this.#getLinearizationPage(pageIndex);
  } else {
    promise = catalog.getPageDict(pageIndex);
  }
  promise = promise.then(
    ([pageDict, ref]) =>
      new Page({
        pdfManager: this.pdfManager,
        xref: this.xref,
        pageIndex,
        pageDict,
        ref,
        globalIdFactory: this._globalIdFactory,
        fontCache: catalog.fontCache,
        builtInCMapCache: catalog.builtInCMapCache,
        standardFontDataCache: catalog.standardFontDataCache,
        globalColorSpaceCache: catalog.globalColorSpaceCache,
        globalImageCache: catalog.globalImageCache,
        systemFontCache: catalog.systemFontCache,
        nonBlendModesSet: catalog.nonBlendModesSet,
        xfaFactory,
      })
  );

  this.#pagePromises.set(pageIndex, promise);
  return promise;
}

It reads the catalog, checks linearization, and creates the page.

Q: What is the catalog?
A: The Catalog is the PDF file's "root dictionary", sitting at the top of the object graph. The /Root entry in the trailer at the end of the file points to it — it's the entry point of the entire PDF. It holds references to all other top-level structures: most importantly /Pages (the root of the page tree), plus /Names (named objects), /Outlines (bookmarks), /AcroForm (forms), /Metadata (XMP metadata), and more.

In pdf.js, the Catalog class wraps this root dictionary and provides caches shared across pages — the font cache (fontCache), the global color space cache (globalColorSpaceCache), the image cache (globalImageCache), the built-in CMap cache (builtInCMapCache), etc. These caches are reused across pages to avoid re-parsing the same font definitions or color spaces — which is why the Page constructor above takes that long list of catalog.fontCache, catalog.globalColorSpaceCache, and so on.

Q: What is linearization?
A: Linearization is a "fast web view" optimization provided by the PDF specification.

A normal PDF is parsed like this: jump to the end of the file and read startxref → read the trailer → find the main XRef section from the trailer → only then can objects be located. That means you need the tail of the file before you can start working.

A linearized PDF additionally places a Linearized dictionary at the beginning of the file (at object 1), which records:

N — total page count

P — the index of the first page (default 0)

O — the object number of the first page

T — the offset of the main XRef section in the file

H — the hint arrays, telling the reader which pages live where in the file

With just a few hundred bytes from the start of the file, the parser can use this dictionary to skip the main XRef and jump straight to the first page's data to start rendering, without waiting for the whole file to download. The effect is dramatic on large files (tens-of-MB scanned documents).

In pdf.js, the PDFDocument.linearization getter tries to parse the beginning of the file; if it finds this Linearized dictionary, it returns an object with fields like numPages, pageFirst, and objectNumberFirst. The getPage logic above is: if the PDF is linearized and the requested page is the first page, take the #getLinearizationPage fast path and use linearization.objectNumberFirst to get the first page's dictionary directly; otherwise fall back to the standard catalog lookup.
But linearization depends heavily on the tool that produced the file — most PDFs have never been linearized.

We've now touched some real PDF format specifications.

This returns the Page instance — let's stay restrained and not dig deeper.

Back to PDFPageProxy.render → PDFPageProxy._pumpOperatorList → Worker: on GetOperatorList

Continuing:

// Pre compile the pdf page and fetch the fonts/images.
page
  .getOperatorList({
    handler,
    sink,
    task,
    intent,
    cacheKey,
    annotationStorage,
    modifiedIds,
    pageIndex,
  })
  .then(
    opListInfo => {
      if (start) {
        info(`${task.name}; time=${Date.now() - start}ms, len=${opListInfo.length}`);
      }
      sink.close();
    },
    reason => {
      if (task.terminated) {
        return; // ignoring errors from the terminated thread
      }
      sink.error(reason);
    },
  )
  .finally(() => {
    finishWorkerTask(task);
  });

It calls the Page.getOperatorList method to get the page's rendering operators.

Let's take a quick look at the implementation of Page.getOperatorList.

Entering PDFPageProxy.render → PDFPageProxy._pumpOperatorList → Worker: on GetOperatorList → Page.getOperatorList

// Source: src/core/document.js
async getOperatorList({
  handler,
  sink,
  task,
  intent,
  cacheKey,
  pageIndex = this.pageIndex,
  annotationStorage = null,
  modifiedIds = null,
}) {
  const contentStreamPromise = this.getContentStream();
  const resourcesPromise = this.loadResources(RESOURCES_KEYS_OPERATOR_LIST);
  // ...

  const pageListPromise = Promise.all([
    contentStreamPromise,
    resourcesPromise,
  ]).then(async ([contentStream]) => {
    const resources = await this.#getMergedResources(
      contentStream.dict,
      RESOURCES_KEYS_OPERATOR_LIST
    );
    const opList = new OperatorList(intent, sink);
    handler.send("StartRenderPage", {
      transparency: partialEvaluator.hasBlendModes(
        resources,
        this.nonBlendModesSet
      ),
      pageIndex,
      cacheKey,
    });

    await partialEvaluator.getOperatorList({
      stream: contentStream,
      task,
      resources,
      operatorList: opList,
    });
    return opList;
  });
  // ...

A lot of logic is omitted — but did you spot the key handler.send("StartRenderPage")? This event corresponds to the intentState.displayReadyCapability we saw earlier.

The main thread's StartRenderPage event listener:

Entering PDFPageProxy.render → PDFPageProxy._pumpOperatorList → Worker: on GetOperatorList → Page.getOperatorList → Main: on StartRenderPage

messageHandler.on('StartRenderPage', data => {
  if (this.destroyed) {
    return; // Ignore any pending requests if the worker was terminated.
  }

  const page = this.#pageCache.get(data.pageIndex);
  page._startRenderPage(data.transparency, data.cacheKey);
});

which calls page._startRenderPage.

/**
 * @private
 */
_startRenderPage(transparency, cacheKey) {
  const intentState = this._intentStates.get(cacheKey);
  if (!intentState) {
    return; // Rendering was cancelled.
  }
  this._stats?.timeEnd("Page Request");

  // TODO Refactor RenderPageRequest to separate rendering
  // and operator list logic
  intentState.displayReadyCapability?.resolve(transparency);
}

This method resolves the intentState.displayReadyCapability promise.

OK, let's return to the _pumpOperatorList method.

Back to PDFPageProxy.render → PDFPageProxy._pumpOperatorList

Continuing with the streaming data: through the sink, data keeps flowing back to the reader on the main thread.

intentState.streamReader = reader;

const pump = () => {
  reader.read().then(
    ({ value, done }) => {
      if (done) {
        intentState.streamReader = null;
        return;
      }
      if (this._transport.destroyed) {
        return; // Ignore any pending requests if the worker was terminated.
      }
      this._renderPageChunk(value, intentState);
      pump();
    },
    reason => {
      intentState.streamReader = null;

      if (this._transport.destroyed) {
        return; // Ignore any pending requests if the worker was terminated.
      }
      if (intentState.operatorList) {
        // Mark operator list as complete.
        intentState.operatorList.lastChunk = true;

        for (const internalRenderTask of intentState.renderTasks) {
          internalRenderTask.operatorListChanged();
        }
        this.#tryCleanup();
      }

      if (intentState.displayReadyCapability) {
        intentState.displayReadyCapability.reject(reason);
      } else if (intentState.opListReadCapability) {
        intentState.opListReadCapability.reject(reason);
      } else {
        throw reason;
      }
    },
  );
};
pump();

Every time the worker pushes a chunk into the stream, it's consumed here, which calls this._renderPageChunk(value, intentState);

Entering PDFPageProxy.render → PDFPageProxy._pumpOperatorList → PDFPageProxy._renderPageChunk

_renderPageChunk(operatorListChunk, intentState) {
  // Add the new chunk to the current operator list.
  for (let i = 0, ii = operatorListChunk.length; i < ii; i++) {
    intentState.operatorList.fnArray.push(operatorListChunk.fnArray[i]);
    intentState.operatorList.argsArray.push(operatorListChunk.argsArray[i]);
  }
  intentState.operatorList.lastChunk = operatorListChunk.lastChunk;
  intentState.operatorList.separateAnnots = operatorListChunk.separateAnnots;

  // Notify all the rendering tasks there are more operators to be consumed.
  for (const internalRenderTask of intentState.renderTasks) {
    internalRenderTask.operatorListChanged();
  }

  if (operatorListChunk.lastChunk) {
    this.#tryCleanup();
  }
}

After pre-processing the data, it calls internalRenderTask.operatorListChanged() to notify the render tasks that new operators have arrived.

Step 4: the render tasks have new operators

Entering PDFPageProxy.render → PDFPageProxy._pumpOperatorList → PDFPageProxy._renderPageChunk → internalRenderTask.operatorListChanged

operatorListChanged() {
  if (!this.graphicsReady) {
    this.graphicsReadyCallback ||= this._continueBound;
    return;
  }
  this.gfx.dependencyTracker?.growOperationsCount(
    this.operatorList.fnArray.length
  );
  this.stepper?.updateOperatorList(this.operatorList);

  if (this.running) {
    return;
  }
  this._continue();
}

which goes to _continue.

Entering PDFPageProxy.render → PDFPageProxy._pumpOperatorList → PDFPageProxy._renderPageChunk → internalRenderTask.operatorListChanged → internalRenderTask._continue

_continue() {
  this.running = true;
  if (this.cancelled) {
    return;
  }
  if (this.task.onContinue) {
    this.task.onContinue(this._scheduleNextBound);
  } else {
    this._scheduleNext();
  }
}

which goes to _scheduleNext.

Entering PDFPageProxy.render → PDFPageProxy._pumpOperatorList → PDFPageProxy._renderPageChunk → internalRenderTask.operatorListChanged → internalRenderTask._continue → internalRenderTask._scheduleNext

_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);
  }
}

Via window.requestAnimationFrame, it schedules the _nextBound method.

In the constructor, this._nextBound = this._next.bind(this);

which goes to the _next method.

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();
    }
  }
}

It calls this.gfx.executeOperatorList — the operator list is now actually executed.

Step 5: initializeGraphics & operatorListChanged

Once intentState.displayReadyCapability.promise is ready, the graphics context is initialized.

Entering initializeGraphics

// Source: src/display/api.js (InternalRenderTask)
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. " +
          "Use different canvas or ensure previous operations were " +
          "cancelled or completed."
      );
    }
    InternalRenderTask.#canvasInUse.add(this._canvas);
  }

  if (this._pdfBug && globalThis.StepperManager?.enabled) {
    this.stepper = globalThis.StepperManager.create(this._pageIndex);
    this.stepper.init(this.operatorList);
    this.stepper.nextBreakPoint = this.stepper.getNextBreakPoint();
  }
  const {
    viewport,
    transform,
    background,
    dependencyTracker,
    imagesTracker,
  } = this.params;

  // When printing in Firefox, we get a specific context in mozPrintCallback
  // which cannot be created from the canvas itself.
  const canvasContext =
    this._canvasContext ||
    this._canvas.getContext("2d", {
      alpha: false,
      willReadFrequently: !this._enableHWA,
    });

  this.gfx = new CanvasGraphics(
    canvasContext,
    this.commonObjs,
    this.objs,
    this.canvasFactory,
    this.filterFactory,
    { optionalContentConfig },
    this.annotationCanvasMap,
    this.pageColors,
    dependencyTracker,
    imagesTracker
  );
  this.gfx.beginDrawing({
    transform,
    viewport,
    transparency,
    background,
  });
  this.operatorListIdx = 0;
  this.graphicsReady = true;
  this.graphicsReadyCallback?.();
}

By setting this.graphicsReady = true, the internalRenderTask.operatorListChanged method is allowed to proceed.

It then immediately triggers operatorListChanged once more, starting execution of the operator list.

operatorListChanged() {
  if (!this.graphicsReady) {
    this.graphicsReadyCallback ||= this._continueBound;
    return;
  }
  this.gfx.dependencyTracker?.growOperationsCount(
    this.operatorList.fnArray.length
  );
  this.stepper?.updateOperatorList(this.operatorList);

  if (this.running) {
    return;
  }
  this._continue();
}

Summary

In this article, we explored the Display layer's getViewport and render methods.

The core of getViewport is building an affine transform matrix: converting PDF's coordinate system (origin at the bottom-left, unit = point) into canvas's coordinate system (origin at the top-left, unit = px), while handling rotation, scale, and dontFlip.

render is a rendering pipeline spanning the main thread and the worker:

Text version:

Main thread (PDFPageProxy.render)
  |-- getRenderingIntent            compute the intent, build the cache key
  |-- _intentStates.getOrInsert...  get or create the intent state by cache key
  |-- _pumpOperatorList             send the streaming GetOperatorList request to the worker
  |     `-- reader.read() loop consumes chunks, hands each to _renderPageChunk
  |-- new InternalRenderTask        create the render task, add it to renderTasks
  `-- await displayReadyCapability
        `-- initializeGraphics      create CanvasGraphics, beginDrawing
              `-- operatorListChanged -> _next -> gfx.executeOperatorList

Worker thread (on:GetOperatorList)
  |-- pdfManager.getPage            locate the Page
  `-- Page.getOperatorList
        |-- handler.send("StartRenderPage")    resolves displayReadyCapability
        `-- partialEvaluator.getOperatorList   parses operators, streams them back via sink

Understanding this pipeline means understanding the skeleton of PDF.js rendering: the main thread only schedules and consumes operators; the real parsing work all happens in the worker.

At this point, after these three articles, the rendering architecture of PDF.js is clear. Starting from the next article, we'll dive into some of the details to round out the depth.

Happy reading!

Next up: MessageHandler — a deep dive into the core mechanism of message communication.

PDF.js Deep Dive 2: getDocument & getPage

StreamPDF — Thu, 22 Oct 2026 13:00:00 +0000

Introduction

This is the second article in the PDF.js Deep Dive series, continuing from the architecture overview in article 1. We'll dive into the Display layer and trace the execution paths of getDocument and getPage. All code snippets in this article are based on PDF.js v6.3.289.

PDF.js Deep Dive 1: The Architecture of PDF.js

The `getDocument` Method

Step 1: Create the loading task and global ID generator

// Source: src/display/api.js
const task = new PDFDocumentLoadingTask();
const { docId } = task;

PDFDocumentLoadingTask also doubles as PDF.js's global ID generator — the docId it produces is used to identify this document throughout the worker.

Step 2: Process user parameters

const url = src.url ? getUrlProp(src.url) : null;
const data = src.data ? getDataProp(src.data) : null;
const httpHeaders = src.httpHeaders || null;
const withCredentials = src.withCredentials === true;
const password = src.password ?? null;
// ...
const transportFactory = {
  canvasFactory: new CanvasFactory({ ownerDocument, enableHWA }),
  filterFactory: new FilterFactory({ docId, ownerDocument }),
  binaryDataFactory:
    (typeof PDFJSDev !== 'undefined' && PDFJSDev.test('MOZCENTRAL')) || useWorkerFetch
      ? null
      : new BinaryDataFactory({ cMapUrl, standardFontDataUrl, wasmUrl }),
};

Step 3: Create the Worker

if (!worker) {
  // Worker was not provided -- creating and owning our own. If message port
  // is specified in global worker options, using it.
  worker = PDFWorker.create({
    verbosity,
    port: GlobalWorkerOptions.workerPort,
  });
  task._worker = worker;
}

Callers can pass in their own Worker instance, but in the common case PDF.js handles Worker creation internally.

PDFWorker is a class; we invoke its static create method.

Entering getDocument → PDFWorker.create

// Source: src/display/api.js
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);
}

PDFWorker maintains a static #workerPorts Map keyed by port, which caches previously created Worker instances so the same port isn't instantiated twice. If a cached entry exists, it returns it directly; otherwise it constructs a fresh PDFWorker.

Entering getDocument → PDFWorker.create → PDFWorker

// Source: src/display/api.js
constructor({
  name = null,
  port = null,
  verbosity = getVerbosityLevel(),
} = {}) {
  this.name = name;
  this.destroyed = false;
  this.verbosity = verbosity;

  if (port) {
    if (PDFWorker.#workerPorts.has(port)) {
      throw new Error("Cannot use more than one PDFWorker per port.");
    }
    PDFWorker.#workerPorts.set(port, this);
    this.#initializeFromPort(port);
  } else {
    this.#initialize();
  }

  if (typeof PDFJSDev === "undefined" || PDFJSDev.test("TESTING")) {
    // For testing purposes.
    Object.defineProperty(this, "_webWorker", {
      get() {
        return this.#webWorker;
      },
    });
  }
}

Since we don't pass a port, the constructor calls #initialize.

Entering getDocument → PDFWorker.create → PDFWorker → #initialize

if (PDFWorker.#isWorkerDisabled || PDFWorker.#mainThreadWorkerMessageHandler) {
  this.#setupFakeWorker();
  return;
}
let { workerSrc } = PDFWorker;
// ...
if (
  typeof PDFJSDev !== 'undefined' &&
  PDFJSDev.test('GENERIC') &&
  !PDFWorker._isSameOrigin(window.location, workerSrc)
) {
  workerSrc = PDFWorker._createCDNWrapper(new URL(workerSrc, window.location).href);
}
const worker = new Worker(workerSrc, { type: 'module' });
const messageHandler = new MessageHandler('main', 'worker', worker);
// ...

First it checks whether to fall back to a "fake worker" (run PDF parsing on the main thread). In our case we take the normal path, skip the fake-worker branch, and read workerSrc from a static getter.

Entering getDocument → PDFWorker.create → PDFWorker → #initialize → workerSrc

static get workerSrc() {
  if (GlobalWorkerOptions.workerSrc) {
    return GlobalWorkerOptions.workerSrc;
  }
  throw new Error('No "GlobalWorkerOptions.workerSrc" specified.');
}

This is the option we set at startup:

pdfjsLib.GlobalWorkerOptions.workerSrc =
  'https://cdn.jsdelivr.net/npm/pdfjs-dist@6.3.289/build/pdf.worker.min.mjs';

Back to getDocument → PDFWorker.create → PDFWorker → #initialize

Next, PDF.js handles a potential cross-origin issue: if workerSrc and the current page are on different origins, it wraps the URL in a Blob to bypass the Worker origin check. In our demo the worker is same-origin, so we skip this branch.

What is the Worker cross-origin issue?

The browser's native new Worker(url) only accepts same-origin script URLs. If workerSrc points to a CDN (e.g. https://cdn.jsdelivr.net/...) that differs from your page's origin, the browser rejects Worker creation outright with Failed to construct 'Worker'.

PDF.js's fix is _createCDNWrapper: it generates a tiny snippet of JS — await import("${url}"); — wraps it in a Blob, then calls URL.createObjectURL to produce a blob URL. A blob URL inherits the origin of the page that created it, so new Worker(blobUrl) looks same-origin to the browser. The wrapper's import call itself can load ES modules cross-origin, which gives PDF.js an indirect way around the restriction.

In our demo the worker script is same-origin, so _isSameOrigin returns true and this wrapper path is never triggered.

A few lines later the Worker is instantiated as an ES Module:

const worker = new Worker(workerSrc, { type: 'module' });

and the main-to-worker communication channel is created:

const messageHandler = new MessageHandler('main', 'worker', worker);

MessageHandler is an abstraction that wraps the underlying postMessage-based communication between the main thread and the Worker.

Worker ↔ main handshake

PDF.js then performs a short handshake between the two threads:

const terminateEarly = () => {
  ac.abort();
  messageHandler.destroy();
  worker.terminate();
  if (this.destroyed) {
    this.#capability.reject(new Error('Worker was destroyed'));
  } else {
    // Fall back to fake worker if the termination is caused by an
    // error (e.g. NetworkError / SecurityError).
    this.#setupFakeWorker();
  }
};

const ac = new AbortController();
worker.addEventListener(
  'error',
  () => {
    if (!this.#webWorker) {
      // Worker failed to initialize due to an error. Clean up and fall
      // back to the fake worker.
      terminateEarly();
    }
  },
  { signal: ac.signal },
);

messageHandler.on('test', data => {
  ac.abort();
  if (this.destroyed || !data) {
    terminateEarly();
    return;
  }
  this.#messageHandler = messageHandler;
  this.#port = worker;
  this.#webWorker = worker;

  this.#resolve();
});

messageHandler.on('ready', data => {
  ac.abort();
  if (this.destroyed) {
    terminateEarly();
    return;
  }
  try {
    sendTest();
  } catch {
    // We need fallback to a faked worker.
    this.#setupFakeWorker();
  }
});

const sendTest = () => {
  const testObj = new Uint8Array();
  // Ensure that we can use `postMessage` transfers.
  messageHandler.send('test', testObj, [testObj.buffer]);
};

// It might take time for the worker to initialize. We will try to send
// the "test" message immediately, and once the "ready" message arrives.
// The worker shall process only the first received "test" message.
sendTest();

It listens for error, ready, and test, then calls sendTest immediately to probe the channel.

Let's look at what happens on the Worker side when new Worker(...) is called.

Entering main → new Worker

// Source: src/core/worker.js
static {
  // Worker thread (and not Node.js)?
  if (
    typeof window === "undefined" &&
    !isNodeJS &&
    typeof self !== "undefined" &&
    /* isMessagePort = */
    typeof self.postMessage === "function" &&
    "onmessage" in self
  ) {
    this.initializeFromPort(self);
  }
}

The Worker's entry point is a static block inside WorkerMessageHandler. It detects that it's running in a Worker environment and calls initializeFromPort.

Entering main → new Worker → initializeFromPort

static initializeFromPort(port) {
  const handler = new MessageHandler("worker", "main", port);
  this.setup(handler, port);
  handler.send("ready", null);
}

It creates a MessageHandler for the worker→main direction, calls setup, and then signals ready back to main.

Entering main → new Worker → initializeFromPort → setup

// Source: src/core/worker.js (WorkerMessageHandler.setup)
static setup(handler, port) {
  let testMessageProcessed = false;
  handler.on("test", data => {
    if (testMessageProcessed) {
      return; // we already processed 'test' message once
    }
    testMessageProcessed = true;

    // Ensure that `TypedArray`s can be sent to the worker.
    handler.send("test", data instanceof Uint8Array);
  });

  handler.on("configure", data => {
    setVerbosityLevel(data.verbosity);
  });

  handler.on("GetDocRequest", data => this.createDocumentHandler(data, port));

  if (typeof PDFJSDev === "undefined" || PDFJSDev.test("TESTING")) {
    handler.on("GetWorkerCoverage", function () {
      return globalThis.__coverage__ ?? {};
    });
  }
}

The worker registers handlers for three messages: test, configure, and GetDocRequest. The test handler is one-shot — it sets testMessageProcessed to true and echoes back.

Now back to the main thread: when the Worker's ready arrives, main resends test. But the Worker's testMessageProcessed flag is already true, so the retry is silently discarded. Only the very first test message gets a response. Once main receives that acknowledgement, it calls #resolve(), marking worker.promise as complete.

Here's the full handshake visualized:

The two vertical lanes represent main (left) and worker (right), with time flowing downward.

① Right after new Worker, main sends a test probe that validates postMessage transfer semantics;

② After finishing initializeFromPort, the worker replies with ready, telling main it is now ready;

③ Main resends test after receiving ready, but the worker only processes the first one — testMessageProcessed is a one-shot switch. This retry (dashed in the diagram) is dropped at if (testMessageProcessed) { return; };

④ The worker responds only to the first test. Main then removes its error listener and calls #resolve(), completing worker.promise.

Q: Which test message is actually consumed, and why is the retry sent?
A: The first one is always consumed — the ① probe fired right after new Worker. On the worker side, testMessageProcessed is a one-shot switch: when the first message arrives, the flag is false, so it flips to true and echoes back a test ack. Every subsequent test (the ③ retry in the diagram) hits if (testMessageProcessed) { return; } and is silently dropped.

Why can we be sure it's the first? Main and worker share a single ordered MessagePort. The first sendTest() (right after Worker creation) is guaranteed to be enqueued before the retry triggered by ready. The worker only starts dispatching the message queue after its initial script runs and setup() registers the test handler, so that first message is never "missed" — it always hits the one-shot switch.

Then why retry at all? The source code comment spells it out: "It might take time for the worker to initialize." The worker starts slower than the caller, and main doesn't know whether it's ready. PDF.js uses a "probe optimistically first + retry after ready" strategy. In the rare case where the first test isn't dispatched before the switch flips, the retry acts as a fallback. The testMessageProcessed flag ensures the retry can't produce a duplicate ack — keeping the whole process idempotent.

On top of that, try { sendTest(); } catch { this.#setupFakeWorker(); } in the ready callback also acts as a channel health check: if the message can't even be sent, the Worker channel is dead and PDF.js falls back to the fake worker. So the retry is fundamentally about handshake robustness, not about "the second try being the one that works."

Milestone ✅ Worker handshake complete: main creates the Worker thread, confirms the channel works through the test / ready / test exchange, and the Worker instance is ready.

main → Worker: `GetDocRequest`

Once the handshake is done, main waits for both the Worker and GPU to be ready — the GPU check (gpuPromise) determines whether certain rendering paths can use hardware acceleration later.

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
    );

Main sends a GetDocRequest message through the Worker-level messageHandler.

The Worker's handler is registered in setup:

Worker: on GetDocRequest

handler.on('GetDocRequest', data => this.createDocumentHandler(data, port));

This triggers createDocumentHandler:

Worker: on GetDocRequest → createDocumentHandler

const workerHandlerName = docId + '_worker';
let handler = new MessageHandler(workerHandlerName, docId, port);

After validating the parameters, it creates a document-specific MessageHandler between main and this document on the worker, registers a long list of message handlers (GetPage, GetDestinations, GetMetadata, GetOutline, Terminate, etc.), and returns workerHandlerName back to main.

Back in getDocument:

} else if (url) {
  if (typeof PDFJSDev !== "undefined" && PDFJSDev.test("MOZCENTRAL")) {
    throw new Error("Not implemented: NetworkStream");
  }
  const NetworkStream = getNetworkStream(url);

  networkStream = new NetworkStream({
    url,
    httpHeaders,
    withCredentials,
    rangeChunkSize,
    disableRange,
    disableStream,
  });
} else {

Since we provided a url, PDF.js instantiates a NetworkStream. It then waits for workerIdPromise to resolve:

return workerIdPromise.then(workerId => {
  if (worker.destroyed) {
    throw new Error('Worker was destroyed');
  }

  const messageHandler = new MessageHandler(docId, workerId, worker.port);
  const transport = new WorkerTransport(
    messageHandler,
    task,
    networkStream,
    transportParams,
    transportFactory,
    pagesMapper,
  );
  task._transport = transport;

  if (task.destroyed) {
    // `destroy()` was called during the worker handshake; the orderly
    // shutdown (including the "Terminate" message) will be issued
    // through the transport once destroy resumes.
    throw new Error('Loading aborted');
  }
  messageHandler.send('Ready', null);
});

Main creates the document-level MessageHandler and a WorkerTransport — the central object that manages this document's lifecycle. Finally it sends the Ready message to kick off actual loading.

Milestone ✅ GetDocRequest complete: Worker registers an independent message-processing chain for this document and returns workerHandlerName; main creates WorkerTransport and sends Ready to begin loading.

main → Worker: `Ready`

Entering Worker: on Ready → setupDoc

// Source: src/core/worker.js
handler.on('Ready', function () {
  setupDoc(docParams);
  docParams = null; // we don't need docParams anymore -- saving memory.
});

setupDoc is the core setup function. It defines three helpers — onSuccess, onFailure, and pdfManagerReady — then calls getPdfManager:

Entering Worker: on Ready → setupDoc → getPdfManager

const pdfManagerArgs = {
  source: null,
  disableAutoFetch,
  docBaseUrl,
  docId,
  enableXfa,
  evaluatorOptions,
  handler,
  length: 0,
  password,
  rangeChunkSize,
};

if (data) {
  pdfManagerArgs.source = data;

  return new LocalPdfManager(pdfManagerArgs);
}
const pdfStream = new PDFWorkerStream({ msgHandler: handler }),
  fullReader = pdfStream.getFullReader();

When raw data bytes are provided, PDF.js uses LocalPdfManager. For URL-based loading it creates a PDFWorkerStream to read data incrementally.

Entering Worker: on Ready → setupDoc → getPdfManager → PDFWorkerStream

class PDFWorkerStream extends BasePDFStream {
  constructor(source) {
    super(source, PDFWorkerStreamReader, PDFWorkerStreamRangeReader);
  }
}

PDFWorkerStream subclasses BasePDFStream and wires in two reader implementations.

Back to Worker: on Ready → setupDoc → getPdfManager

fullReader = pdfStream.getFullReader();

getFullReader is inherited from BasePDFStream:

getFullReader() {
  assert(
    !this._fullReader,
    "BasePDFStream.getFullReader can only be called once."
  );
  return (this._fullReader = new this.#PDFStreamReader(this));
}

It instantiates PDFWorkerStreamReader, which — crucially — sends a GetReader message back to main over the msgHandler:

class PDFWorkerStreamReader extends BasePDFStreamReader {
  _reader = null;

  constructor(stream) {
    super(stream);
    const { msgHandler } = stream._source;

    const readableStream = msgHandler.sendWithStream('GetReader');
    this._reader = readableStream.getReader();

    msgHandler.sendWithPromise('ReaderHeadersReady').then(data => {
      this._contentLength = data.contentLength;
      this._isStreamingSupported = data.isStreamingSupported;
      this._isRangeSupported = data.isRangeSupported;

      this._headersCapability.resolve();
    }, this._headersCapability.reject);
  }
  // ...
}

On the main side, WorkerTransport handles the GetReader message by calling networkStream.getFullReader(), which eventually issues the first actual HTTP request — the fetch call for the PDF itself:

constructor(stream) {
  super(stream);
  const {
    disableRange,
    disableStream,
    rangeChunkSize,
    url,
    withCredentials,
  } = stream._source;

  this._isStreamingSupported = !disableStream;
  const headers = new Headers(stream.headers);

  fetchUrl(url, headers, withCredentials, this._abortController)
    .then(response => {
      stream._responseOrigin = getResponseOrigin(response.url);
      ensureResponseStatus(response.status, url);
      this._reader = response.body.getReader();

      const responseHeaders = response.headers;
      const { contentLength, isRangeSupported } =
        validateRangeRequestCapabilities({
          responseHeaders,
          isHttp: true,
          rangeChunkSize,
          disableRange,
        });
      this._contentLength = contentLength;
      this._isRangeSupported = isRangeSupported;
      this._filename = extractFilenameFromHeader(responseHeaders);

      // We need to stop reading when range is supported and streaming is
      // disabled.
      if (!this._isStreamingSupported && this._isRangeSupported) {
        this.cancel(new AbortException("Streaming is disabled."));
      }

      this._headersCapability.resolve();
    })
    .catch(this._headersCapability.reject);
}

This is where the first network request happens. PDF.js fetches the URL and inspects response headers — content-length, Accept-Ranges, Content-Disposition, etc.

One important detail:

// We need to stop reading when range is supported and streaming is
// disabled.
if (!this._isStreamingSupported && this._isRangeSupported) {
  this.cancel(new AbortException('Streaming is disabled.'));
}

If range requests are available but streaming is off, PDF.js deliberately aborts this initial fetch. You may see the request fire and then immediately cancel — that's not a bug, it's intentional: the probe request only exists to determine whether range is supported. Once that decision is made, PDF.js either switches to NetworkPdfManager (range-capable, reads on-demand) or LocalPdfManager (downloads everything).

This is one of the optimizations built into StreamPDF: our backend guarantees that OSS always supports range requests, eliminating the need for this probe request and moving straight to the next phase.

Back in getPdfManager, once headers are known:

fullReader.headersReady.then(() => {
  if (!fullReader.isRangeSupported) {
    return;
  }
  pdfManagerArgs.source = pdfStream;
  pdfManagerArgs.length = fullReader.contentLength;
  pdfManagerArgs.disableAutoFetch ||= fullReader.isStreamingSupported;

  newPdfManager = new NetworkPdfManager(pdfManagerArgs);
  // ...
  resolve(newPdfManager);
});

If range is supported → NetworkPdfManager (reads data incrementally over the network). If not → the probe request finishes normally, all bytes are buffered, and LocalPdfManager is used instead.

async function readData() {
  let loaded = 0;
  while (true) {
    const { value, done } = await fullReader.read();
    ensureNotTerminated();
    if (done) break;
    // ...
    if (!fullReader.isStreamingSupported) {
      handler.send('DocProgress', { loaded, total: fullReader.contentLength });
    }
    if (newPdfManager) {
      newPdfManager.sendProgressiveData(value);
    } else {
      cachedChunks.push(value);
    }
  }
  if (!newPdfManager) {
    pdfManagerArgs.source = arrayBuffersToBytes(cachedChunks);
    newPdfManager = new LocalPdfManager(pdfManagerArgs);
    resolve(newPdfManager);
  }
}
readData();

Q: Why "LocalPdfManager"? Because once all bytes are in memory, the code path is identical to handling a locally-provided PDF — "local" means the data is fully available, not that it came from disk.

Once getPdfManager resolves, setupDoc continues:

getPdfManager(data)
  .then(function (newPdfManager) {
    // ...
    pdfManager = newPdfManager;

    pdfManager.requestLoadedStream(/* noFetch = */ true).then(
      stream => {
        handler.send('DataLoaded', { length: stream.bytes.byteLength });
      },
      () => {
        /* avoid errors if terminated */
      },
    );
  })
  .then(pdfManagerReady, onFailure);

Then pdfManagerReady → loadDocument:

Entering Worker: on Ready → pdfManagerReady → loadDocument

// Source: src/core/worker.js (closure inside createDocumentHandler)
async function loadDocument(recoveryMode) {
  await pdfManager.initDocument(recoveryMode);

  const isPureXfa = await pdfManager.ensureDoc('isPureXfa');
  if (isPureXfa) {
    const task = new WorkerTask('loadXfaResources');
    startWorkerTask(task);
    await pdfManager.ensureDoc('loadXfaResources', [handler, task]);
    finishWorkerTask(task);
  }

  const [numPages, fingerprints] = await Promise.all([
    pdfManager.ensureDoc('numPages'),
    pdfManager.ensureDoc('fingerprints'),
  ]);

  const htmlForXfa = isPureXfa ? await pdfManager.ensureDoc('htmlForXfa') : null;

  return { numPages, fingerprints, htmlForXfa };
}

Inside initDocument (inherited from BasePdfManager), PDF.js performs a series of integrity checks — parse the header, parse the cross-reference table, parse the document, verify the first and last page load correctly. We won't go into the details here; that will be the topic of a future article.

Once all checks pass, onSuccess is called, which sends the document metadata back to main:

function onSuccess(doc) {
  ensureNotTerminated();
  handler.send('GetDoc', { pdfInfo: doc });
}

Milestone ✅ Ready complete: Worker initializes the PdfManager, probes network capabilities (range / streaming) via fetch, creates either NetworkPdfManager or LocalPdfManager, runs document integrity checks, and sends document metadata back to main with the GetDoc message.

Worker → main: `GetDoc`

Entering main: on GetDoc

messageHandler.on('GetDoc', ({ pdfInfo }) => {
  this.pagesMapper.pagesNumber = pdfInfo.numPages;
  this._numPages = pdfInfo.numPages;
  this._htmlForXfa = pdfInfo.htmlForXfa;
  delete pdfInfo.htmlForXfa;
  loadingTask._capability.resolve(new PDFDocumentProxy(pdfInfo, this));
});

Main stores the document metadata, creates a PDFDocumentProxy — the Display-layer facade for the document — and resolves loadingTask.promise.

Milestone ✅ GetDoc complete: main receives document metadata, creates PDFDocumentProxy and resolves loadingTask.promise. The getDocument call chain is fully resolved.

At this point getDocument returns, and the caller receives a PDFDocumentProxy.

The `getPage` Method

From our demo code:

const loadingTask = pdfjsLib.getDocument({ url: '...' });
const pdf = await loadingTask.promise;
const page = await pdf.getPage(1);

pdf is a PDFDocumentProxy instance, so pdf.getPage(1) calls PDFDocumentProxy.getPage.

Entering main: PDFDocumentProxy.getPage

// Source: src/display/api.js
getPage(pageNumber) {
  return this._transport.getPage(pageNumber);
}

It delegates to WorkerTransport.getPage:

Entering main: PDFDocumentProxy.getPage → WorkerTransport.getPage

// Source: src/display/api.js
getPage(pageNumber) {
  if (
    !Number.isInteger(pageNumber) ||
    pageNumber <= 0 ||
    pageNumber > this.pagesMapper.pagesNumber
  ) {
    return Promise.reject(new Error("Invalid page request."));
  }
  const pageIndex = pageNumber - 1;
  const newPageIndex = this.pagesMapper.getPageId(pageNumber) - 1;

  const cachedPromise = this.#pagePromises.get(pageIndex);
  if (cachedPromise) {
    return cachedPromise;
  }
  const promise = this.messageHandler
    .sendWithPromise("GetPage", { pageIndex: newPageIndex })
    .then(pageInfo => {
      if (this.destroyed) { throw new Error("Transport destroyed"); }
      if (pageInfo.refStr) {
        this.#pageRefCache.set(pageInfo.refStr, newPageIndex);
      }

      const page = new PDFPageProxy(
        pageIndex, pageInfo, this, this.pagesMapper, this._params.pdfBug
      );
      this.#pageCache.set(pageIndex, page);
      return page;
    });
  this.#pagePromises.set(pageIndex, promise);
  return promise;
}

After validating the page number and checking an in-flight promise cache, main sends the GetPage message to the worker.

main → Worker: `GetPage`

Entering Worker: on GetPage

handler.on('GetPage', async function ({ pageIndex }) {
  const page = await pdfManager.getPage(pageIndex);

  const [rotate, ref, userUnit, view] = await Promise.all([
    pdfManager.ensure(page, 'rotate'),
    pdfManager.ensure(page, 'ref'),
    pdfManager.ensure(page, 'userUnit'),
    pdfManager.ensure(page, 'view'),
  ]);
  return { rotate, ref, refStr: ref?.toString() ?? null, userUnit, view };
});

This calls pdfManager.getPage, which goes through BasePdfManager.getPage:

getPage(pageIndex) {
  return this.pdfDocument.getPage(pageIndex);
}

Which lands in PDFDocument.getPage:

Entering Worker: on GetPage → pdfManager.getPage → PDFDocument.getPage

// Source: src/core/document.js
getPage(pageIndex) {
  const cachedPromise = this.#pagePromises.get(pageIndex);
  if (cachedPromise) {
    return cachedPromise;
  }
  const { catalog, linearization, xfaFactory } = this;

  let promise;
  if (xfaFactory) {
    promise = Promise.resolve([Dict.empty, null]);
  } else if (linearization?.pageFirst === pageIndex) {
    promise = this.#getLinearizationPage(pageIndex);
  } else {
    promise = catalog.getPageDict(pageIndex);
  }
  promise = promise.then(
    ([pageDict, ref]) =>
      new Page({
        pdfManager: this.pdfManager,
        xref: this.xref,
        pageIndex,
        pageDict,
        ref,
        globalIdFactory: this._globalIdFactory,
        fontCache: catalog.fontCache,
        builtInCMapCache: catalog.builtInCMapCache,
        standardFontDataCache: catalog.standardFontDataCache,
        globalColorSpaceCache: catalog.globalColorSpaceCache,
        globalImageCache: catalog.globalImageCache,
        systemFontCache: catalog.systemFontCache,
        nonBlendModesSet: catalog.nonBlendModesSet,
        xfaFactory,
      })
  );

  this.#pagePromises.set(pageIndex, promise);
  return promise;
}

This is where PDF.js actually fetches and parses the PDF data for a given page, and constructs a Page instance. We won't go into the deep PDF parsing logic here — that will get its own article.

Back on the main side, WorkerTransport.getPage (code shown above) receives the pageInfo payload and wraps it in a PDFPageProxy, storing it in the page cache and returning it to the caller.

Milestone ✅ GetPage complete: main sends GetPage → Worker retrieves the Page instance from PDFDocument and extracts rotate / view / ref / userUnit → main receives pageInfo, wraps it in PDFPageProxy, and returns it.

Summary

In this article we traced the complete execution paths of getDocument and getPage:

getDocument → creates a PDFDocumentLoadingTask, spins up a Worker and completes the test / ready / test handshake, sends GetDocRequest to obtain a document-scoped message channel, sends Ready to kick off loading. The Worker probes network capability via fetch, creates NetworkPdfManager or LocalPdfManager, validates the document, and replies with GetDoc. Main receives metadata and resolves with a PDFDocumentProxy.
getPage → validates the page number, sends GetPage to the Worker. The Worker resolves the page's PDF dictionary and constructs a Page instance, extracting rotate / view / ref / userUnit. Main wraps the response in a PDFPageProxy and returns it.

At the end of both calls, our demo code has everything it needs:

const loadingTask = pdfjsLib.getDocument({
  url: 'https://assets.streampdf.com/PDF32000_2008.pdf',
});
const pdf = await loadingTask.promise;
const page = await pdf.getPage(1);

We end up holding a PDFPageProxy, which is the foundation for everything that comes next — viewport calculation, rendering to canvas, text extraction, annotations, and more.

Notice we've deliberately stayed at the top of the architecture. Before diving into PDF-level parsing (lexer, XRef table, page dictionary, operators), you need this high-level mental model of how data flows between main and Worker. If you stick with this series, you'll gain both a deep understanding of PDF.js internals and, by extension, a solid grasp of the PDF specification itself.

In the next article we'll move into viewport computation and rendering.

PDF.js Deep Dive 1: The Architecture of PDF.js

StreamPDF — Wed, 21 Oct 2026 13:00:00 +0000

Introduction

This is the first article in the PDF.js Deep Dive series, covering the architecture design of PDF.js.

The analysis in this series is based on the PDF.js v6.3.289 source code.

What is a PDF

Portable Document Format (PDF), standardized as ISO 32000, is a file format developed by Adobe in 1993 used to present documents, including text formatting and images, in a manner independent of application software, hardware, and operating systems. Based on the PostScript language, a PDF file encapsulates a complete description of a fixed-layout document, including the text, fonts, vector graphics, raster images and other information needed to display it.

PDF has its roots in "The Camelot Project" initiated by Adobe co-founder John Warnock in 1991. PDF was standardized as ISO 32000 in 2008. It is maintained by ISO TC 171 SC 2 WG8, of which the PDF Association is the committee manager. The last edition as ISO 32000-2:2020 was published in December 2020.

From Wikipedia: https://en.wikipedia.org/wiki/PDF

It is a file format that does not depend on any particular runtime implementation: a document can be displayed consistently in every environment. In practice, of course, it is the parser and renderer that absorb the differences between environments. It is similar to a high-level language such as Java — the same code runs anywhere, and the runtime translates it for each platform.

This is also the biggest difference from formats such as Word and HTML, which display differently in different environments. HTML in particular is designed to provide different experiences in different environments.

What is PDF.js

A general-purpose PDF parsing and rendering platform built on web standards.

It parses and executes the instructions inside a PDF file, then renders the result on the web.

This series goes deep inside PDF.js, and just as deep inside the PDF specification, ISO 32000. By the time you finish it, you will have both breadth and depth of understanding of the PDF file format.

The layered design of PDF.js

PDF.js divides the whole framework into three layers:

Core layer — parses and interprets the binary PDF file. This layer is the foundation of everything above it. Its APIs are not covered by the versioning policy and may change at any time.
Display layer (API) — sits on top of the core layer and provides easier-to-use APIs for rendering PDF pages and reading other information from the document. Version numbers are based on this layer.
Viewer layer — built on top of the display layer: the default PDF viewer UI shipped with Firefox.

Let's look at a demo and trace how the code executes. Our demo is, in effect, a custom viewer layer.

First, import the PDF.js resources:

import * as pdfjsLib from 'https://cdn.jsdelivr.net/npm/pdfjs-dist@6.3.289/build/pdf.min.mjs';
pdfjsLib.GlobalWorkerOptions.workerSrc =
  'https://cdn.jsdelivr.net/npm/pdfjs-dist@6.3.289/build/pdf.worker.min.mjs';

Then call the exposed entry method with the URL of a file:

const loadingTask = pdfjsLib.getDocument({
  url: 'https://assets.streampdf.com/PDF32000_2008.pdf',
});

Stop — let's not render yet. First, look at the call chain of getDocument, which is a display-layer API:

Validate the arguments
Create a Worker
Set up the communication channel between the Worker thread and the main thread
Start fetching the file data, then send a Ready event over the main↔Worker communication channel
After the Ready event, the Worker creates a pdfManager object. This object belongs to the core layer and provides access to core PDF data such as startxref and the cross-reference (xref) table.
Return the task's Promise

Because this is an asynchronous method driven by a Promise, we generally wait for it to finish before continuing:

const pdf = await loadingTask.promise;

When the promise resolves, the data is ready and the document can be rendered.

// Get the render data for the first page
const page = await pdf.getPage(1);
// Get the viewport for the first page
const viewport = page.getViewport({ scale: 0.5 });
// Grab the canvas we will render onto
const canvas = document.getElementById('canvas-id');
const context = canvas.getContext('2d');

// Size the canvas to match the PDF viewport
canvas.width = Math.floor(viewport.width);
canvas.height = Math.floor(viewport.height);
canvas.style.width = Math.floor(viewport.width) + 'px';
canvas.style.height = Math.floor(viewport.height) + 'px';

// Prepare the render parameters
const renderContext = {
  canvasContext: context,
  viewport,
};

// render returns a RenderTask (Promise); await it so the drawing completes
await page.render(renderContext);

getPage, getViewport, and render above are all methods exposed by the display layer; underneath, they call into the core layer.

Note that we are not diving into these methods here — that is the subject of the next article in this series.

Live demo: https://streampdf.com/blog/demos/a-simple-pdf-render-demo.html

Q: Why is the design layered?

A: In one sentence: confine change to a single place. The PDF specification is enormous and the parsing implementation is bound to keep evolving, while the API exposed to users has to stay stable over the long term; layering puts a "stable contract" between the two — the upper layers depend only on the handful of methods the display layer exposes, so no matter how the code below is refactored, optimized, or even rewritten, nothing outside is affected.

Concretely in PDF.js, layering buys four things.

First, contract and versioning: the core layer's APIs are not covered by the versioning policy and may change at any time, and version numbers are defined by the display layer — the unstable implementation is confined to the bottom layer, while the getDocument / getPage / render that users depend on live in the display layer, where the interface stays stable for the long term.

Second, replaceability: each layer can be replaced on its own — the viewer layer can go from Firefox's built-in viewer to the hand-written calling code in our demo, and the core layer can move from a Worker to the fake worker (falling back to the main thread) or even Node, with the display layer's calling code completely unchanged.

Third, performance and isolation: the core layer runs in a Worker thread, so CPU-heavy parsing never blocks the main-thread UI; layering makes that thread boundary explicit — layers talk only by passing messages through MessageHandler, which keeps the interface clean and the boundary clear.

Fourth, testability: the core layer can be tested on its own, with no DOM and no canvas.

As the Java analogy earlier in this article suggests: Java uses a runtime to smooth over platform differences, and PDF.js uses layering to smooth over "the complexity of the specification" — you do not need to know the details of ISO 32000 to parse and render a PDF.

Architecture diagram

Each row in the diagram is one public API call from the demo: the viewer column is the code we write, the display column holds display-layer objects such as PDFDocumentProxy and PDFPageProxy, and the core column runs inside the Worker thread. The horizontal arrows are message round-trips between layers (via MessageHandler), and the vertical arrows show the call order. getViewport is a pure display-layer size calculation that never touches the Worker, so it has no core counterpart; render, on the other hand, needs the core layer to produce an operator list (GetOperatorList), which is why all three columns are present.

Summary

PDF.js opened up the possibility of rendering PDF files on the web, and it has since become the general-purpose tool for doing so. A deep study of PDF.js gives you a deeper understanding of the PDF specification — you get to read the spec through a working implementation, instead of grinding through the dry specification document directly.

PDF.js's distinctive three-layer design lets developers replace each layer independently. It also supports unique performance techniques such as streaming requests and range requests. I learned a great deal from PDF.js when founding the StreamPDF project — thanks to everyone who has participated in the project.

Next in the series: we will go deep into getDocument and getPage to see exactly what happens in the core layer. It will be a genuinely fascinating logical challenge. See you in the next article.

DEV Community: StreamPDF

The AI Era: What Should We Do to Survive? (Reflections on Founding StreamPDF)

Introduction

The Fourth Industrial Revolution: Whose Life Did It Take?

What Does the Future of AI Look Like?

What Should We Actually Do to Survive?

Conclusion

PDF.js Deep Dive from Demo 4: getViewport

Introduction

The getViewport call

Lines 1423-1439: Destructure the parameters

Line 70: scale absorbs userUnit (page_viewport.js)

Lines 74-75: Compute the page center point (page_viewport.js)

Lines 78-116: Normalize the rotation and compute the rotation vector (page_viewport.js)

Lines 120-130: Compute width, height, and canvas offsets (page_viewport.js)

Lines 134-141: Assemble the transform matrix (page_viewport.js)

Lines 143-144: Store width and height (page_viewport.js)

Summary

PDF.js Deep Dive from Demo 3: getPage

Introduction

The getPage call

Lines 773-775: PDFDocumentProxy.getPage: a one-line delegation

Lines 3031-3037: Validate the arguments

Lines 3038-3039: Convert the page number

PagesMapper: translating between user page numbers and original page order

Lines 3041-3044: Check the cache

Three layers of cache: separate stores, separate jobs

Lines 3045-3048: Send the GetPage message to the worker

Lines 3049-3068: Handle the reply and create the PDFPageProxy

The PDFPageProxy constructor: assignment only, no parsing

Summary

PDF.js Deep Dive from Demo 2: getDocument

Introduction

The getDocument call

Lines 235-236: Initialize the loading task

Lines 238-335: Validate and process parameters

ignoreErrors: a semantically inverted internal variable

rangeChunkSize: the 64KB setup for later

docBaseUrl: why data: URLs are excluded

gpuPromise: designed to run in parallel with worker startup

The three Factories: environment branches

useSystemFonts: the default depends on other parameters

useWorkerFetch: a compound check

Lines 338: Set the main-thread log level

Lines 342-350: Instantiate the three factories

Lines 352-360: Create the worker

Lines 362-402: Assemble the two parameter packages

Lines 404-473: The handshake after the worker is ready

Lines 474-475: Return value

Summary

PDF.js Deep Dive from Demo 1: Rendering a PDF with a Custom Viewer

Introduction

Rendering a PDF with a Custom Viewer

Lines 1-3: Configure the Worker file path

Lines 4-7: Load the PDF document

Lines 8-9: Get the first page of the PDF document

Lines 10-11: Get the viewport data of the first page

Lines 12-19: Get the canvas onto which we will render

Lines 20-28: Render the first page

Summary

PDF.js Deep Dive 3: getViewport & render

Introduction

getViewport

render

Step 1: getRenderingIntent, computing the rendering intent

Step 2: this._intentStates.getOrInsertComputed

Step 3: fetching the page's operator list

Step 4: the render tasks have new operators

Step 5: initializeGraphics & operatorListChanged

Summary

PDF.js Deep Dive 2: getDocument & getPage

Introduction

The getDocument Method

Step 1: Create the loading task and global ID generator

Step 2: Process user parameters

Step 3: Create the Worker

Worker ↔ main handshake

main → Worker: GetDocRequest

main → Worker: Ready

Worker → main: GetDoc

Line 70: scale absorbs userUnit (`page_viewport.js`)

Lines 74-75: Compute the page center point (`page_viewport.js`)

Lines 78-116: Normalize the rotation and compute the rotation vector (`page_viewport.js`)

Lines 120-130: Compute width, height, and canvas offsets (`page_viewport.js`)

Lines 134-141: Assemble the transform matrix (`page_viewport.js`)

Lines 143-144: Store width and height (`page_viewport.js`)

Step 1: `getRenderingIntent`, computing the rendering intent

Step 2: `this._intentStates.getOrInsertComputed`

The `getDocument` Method

main → Worker: `GetDocRequest`

main → Worker: `Ready`

Worker → main: `GetDoc`

The `getPage` Method

main → Worker: `GetPage`