PDF previews crashed on iPhone: the Safari bug we just fixed

A user reported it plainly: tapping a file to preview it did nothing on iPhone, or worse, the page gave up. On desktop everything worked. This is the story of what was actually broken, and how we fixed it for every iPhone still in real use.

The symptom versus the cause

Our preview engine is pdf.js, which does all parsing inside a Web Worker so the page never freezes. The crash had nothing to do with our code paths: pdfjs-dist 4.x calls Promise.withResolvers, a JavaScript API that Safari only shipped in version 17.4. On iOS 17.3.1 and older, the moment a PDF tried to parse, the worker hit a function that does not exist and the preview silently failed.

Why a normal polyfill was not enough

The standard fix is to polyfill the missing function before the library loads. But a Web Worker is a separate JavaScript realm: the main page and the worker do not share globals, so a polyfill installed on the page never reaches the worker where the crash happened. We had to ship our own worker entry file that installs the polyfill first and only then loads the real pdf.js worker.

Two smaller iPhone gremlins we fixed along the way

• Ghost clicks: iOS sometimes fires a delayed second tap after opening a fullscreen overlay, which could instantly close a preview that just opened. The overlay now ignores close-taps for the first 400 milliseconds.
• Memory pressure: large documents used to rasterize every page thumbnail immediately. Phones are quicker to kill tabs than laptops, so thumbnails now render the first 12 pages eagerly and show a +N chip for the rest.

How we verified it

We tested on a real iPhone running iOS 17.3.1 in Safari, Chrome and Telegram's in-app browser, on emulated iPad mini, iPad Pro, Android tablet, and desktop Safari and Chrome. We also built a public diagnostics page that runs the whole PDF pipeline on any device and reports each layer, so if some future browser update breaks something, any user can send us a 30-second report.

What this means for you

Local, no-upload PDF processing is not a marketing line; it is an engineering commitment. That includes the unglamorous work of supporting phones that stopped getting updates years ago. If you ever hit a blank preview on any device, open our diagnostics page and tell us what it says.