iPhone で PDF プレビューが白画面に：修正した Safari のバグ

ユーザーからの報告は素直なものでした。iPhone でファイルをタップしてプレビューしても何も起きない、時にはページが真っ白になる。デスクトップでは全部正常動作するのに。この記事は、本当に壊れていたものが何で、現役のすべての iPhone で動くようにどう直したかの記録です。

症状と原因

プレビューエンジンは pdf.js で、ページを固めないためパース処理はすべて Web Worker 内で走ります。今回のクラッシュは当方のコード経路ではなく、pdfjs-dist 4.x が内部で呼ぶ Promise.withResolvers が原因でした。この API は Safari 17.4 でようやく搭載されたもので、iOS 17.3.1 以前では PDF をパースした瞬間、ワーカー内に存在しない関数に当たり、プレビューが黙って死にました。

普通の polyfill では救えない理由

定番の修し方は、ライブラリ読み込み前に足りない関数を polyfill することです。しかし Web Worker は独立した JavaScript 空間で、ページとワーカーはグローバルを共有しません。ページに仕込んだ polyfill は、クラッシュ現場のワーカーには永遠に届きません。そこで、まず polyfill をインストールしてから本物の pdf.js ワーカーを読み込む、独自のワーカー入口ファイルを出すことにしました。

ついでに直した 2 匹の小悪魔

• ゴーストタップ：iOS は全画面オーバーレイを開いた後、遅れた 2 回目のタップを発火することがあり、開いたばかりのプレビューが即座に閉じることがありました。現在はオーバーレイを開いてから 400 ミリ秒以内の閉じるタップを無視します。
• メモリ圧迫：以前は全ページのサムネイルを即座にラスタライズしていました。スマホはノート PC よりタブを殺しやすいため、先頭 12 ページだけ積極的に描画し、残りは +N ラベルで示すようにしました。

検証方法

iOS 17.3.1 の実機で Safari、Chrome、Telegram 内蔵ブラウザを検証し、iPad mini、iPad Pro、Android タブレット、デスクトップの Safari と Chrome もエミュレーションで確認しました。さらに公開診断ページも用意し、どの端末でも PDF パイプライン全体を層ごとに実行して結果を報告します。将来のブラウザ更新で何か壊れても、どのユーザーも 30 秒で報告を送れます。

あなたにとっての意味

ローカル処理・アップロードなしは宣伝文句ではなく、エンジニアリングの約束です。何年も更新されていない電話を支える地味な作業も含めて。もし何らかの端末で白いプレビューに当たったら、診断ページを開いて結果を教えてください。