perf(reader): prioritize hybrid PDF over speculative streams

static/reader.js

@@ -71,6 +71,7 @@ const readerContext = {
   get PDF_MANIFEST_PREFETCH_CONCURRENCY() { return PDF_MANIFEST_PREFETCH_CONCURRENCY; },
   get PDF_MANIFEST_PREFETCH_LIMIT() { return PDF_MANIFEST_PREFETCH_LIMIT; },
   get PDF_MANIFEST_PREFETCH_MAX_PAGES() { return PDF_MANIFEST_PREFETCH_MAX_PAGES; },
+  get PDF_HYBRID_DOCUMENT_GRACE_MS() { return PDF_HYBRID_DOCUMENT_GRACE_MS; },
   get PDF_OCR_PAGE_CACHE_BYTES() { return PDF_OCR_PAGE_CACHE_BYTES; },
   get PDF_PREFETCH_MARGIN() { return PDF_PREFETCH_MARGIN; },
   get PDF_SEARCH_TEXT_CACHE_BYTES() { return PDF_SEARCH_TEXT_CACHE_BYTES; },
@@ -845,6 +846,9 @@ const PDF_MANIFEST_PREFETCH_LIMIT = 12;
 const PDF_MANIFEST_PREFETCH_CONCURRENCY = 3;
 // Keep the 12-page render cache; background prefetch stays a nearby window.
 const PDF_MANIFEST_PREFETCH_MAX_PAGES = 48;
+// Let a primary PDF win speculative pages before starting image-stream I/O.
+// The visible page keeps its immediate image fallback.
+const PDF_HYBRID_DOCUMENT_GRACE_MS = 750;
 let pdfManifestPrefetchTimer = 0;
 let pdfManifestPrefetchNext = 0;
 let pdfManifestPrefetchOrigin = 0;

static/reader/pdf/reader-pdf-page-window.mjs

@@ -1,6 +1,8 @@
 export function createReaderPdfPageWindow(readerContext) {
   async function preloadPdfFirstPage(total) {
-    if (readerContext.pdfV3Manifest) return;
+    // Hybrid PDFs use the primary-document race below. A standalone preload
+    // would guarantee preview traffic before a warm PDF can win.
+    if (readerContext.pdfV3Manifest || readerContext.pdfHybridUrl) return;
     await readerContext.getInitialReaderRestoration();
     try {
       const source = readerContext.pdfManifestSource();
@@ -43,6 +45,24 @@ export function createReaderPdfPageWindow(readerContext) {
     return ocrEntry ? { ...pageEntry, ...ocrEntry, page } : pageEntry;
   }
 
+  function startPdfHybridDocument(totalPages = readerContext.documentState.pageCount) {
+    readerContext.pdfHybridUrl = readerContext.pdfPrimarySource();
+    if (!readerContext.pdfHybridUrl || readerContext.pdfHybridDocumentPromise) return;
+    readerContext.pdfHybridDocumentPromise = readerContext.loadPdfDocument(readerContext.pdfHybridUrl).then((pdf) => {
+      readerContext.assertReaderActive();
+      if (pdf.numPages !== totalPages) throw new Error("PDF_PRIMARY_PAGE_COUNT_MISMATCH");
+      readerContext.pdfDocument = pdf;
+      readerContext.clearPdfManifestPrefetches();
+      readerContext.cancelSpeculativePdfRenders(readerContext.pageAtMarker?.());
+      readerContext.syncCapabilityControls();
+      return pdf;
+    });
+    readerContext.pdfHybridDocumentPromise.catch((error) => {
+      if (error?.name !== "AbortError" && !readerContext.readerLifecycle.disposed)
+        console.warn("Primary PDF unavailable; page stream retained", error);
+    });
+  }
+
   async function appendShellsBatched(createShell, total, batchSize) {
     for (let start = 2; start <= total; start += batchSize) {
       readerContext.assertReaderActive();
@@ -258,6 +278,11 @@ export function createReaderPdfPageWindow(readerContext) {
         throw new Error("PDF_V3_SOURCE_MISMATCH");
       const repository = readerContext.pdfV3Repository =
         readerContext.createPdfV3Repository(manifest.source_sha256, manifest.page_count);
+      readerContext.pdfV3Manifest = manifest;
+      readerContext.pdfOcrManifest = manifest.text_layer ? manifest : null;
+      readerContext.ocrManifestUrl = manifest.text_layer ? readerContext.sourceUrl : "";
+      // Start the primary PDF while the independent page map is being read.
+      startPdfHybridDocument(manifest.page_count);
       const pageMap = repository.read(manifest.page_map);
       // The opening preview partition depends only on the validated reading
       // manifest, so fetch it alongside the page map; preview() still
@@ -269,9 +294,6 @@ export function createReaderPdfPageWindow(readerContext) {
         if (part) return repository.read(part.resource);
       }).catch(() => {});
       readerContext.pdfV3Map = readerContext.validatePageMap(await pageMap, manifest);
-      readerContext.pdfV3Manifest = manifest;
-      readerContext.pdfOcrManifest = manifest.text_layer ? manifest : null;
-      readerContext.ocrManifestUrl = manifest.text_layer ? readerContext.sourceUrl : "";
     }
     readerContext.assertReaderActive();
     const source = readerContext.pdfManifestSource();
@@ -279,21 +301,7 @@ export function createReaderPdfPageWindow(readerContext) {
     if (!source) throw new Error("PDF_MANIFEST_INVALID");
     readerContext.pdfPageManifest = { ...source, pageCount: totalPages };
     if (readerContext.pdfV3Manifest) readerContext.pdfPageManifest.pageUrl = () => "";
-    readerContext.pdfHybridUrl = readerContext.pdfPrimarySource();
-    if (readerContext.pdfHybridUrl) {
-      readerContext.pdfHybridDocumentPromise = readerContext.loadPdfDocument(readerContext.pdfHybridUrl).then((pdf) => {
-        readerContext.assertReaderActive();
-        if (pdf.numPages !== totalPages) throw new Error("PDF_PRIMARY_PAGE_COUNT_MISMATCH");
-        readerContext.pdfDocument = pdf;
-        readerContext.clearPdfManifestPrefetches();
-        readerContext.syncCapabilityControls();
-        return pdf;
-      });
-      readerContext.pdfHybridDocumentPromise.catch((error) => {
-        if (error?.name !== "AbortError" && !readerContext.readerLifecycle.disposed)
-          console.warn("Primary PDF unavailable; page stream retained", error);
-      });
-    }
+    startPdfHybridDocument(totalPages);
     readerContext.updateDocumentState({ pageCount: totalPages });
     readerContext.pageInput.max = String(totalPages);
     document.querySelector("#page-total").textContent = `/ ${totalPages}`;

static/reader/pdf/reader-pdf-renderer.mjs

@@ -136,7 +136,22 @@ export function createReaderPdfRenderer(readerContext) {
     shell._hybridCancel = () => { controller.abort(); shell._renderCancel?.(); };
     const pdfTask = readerContext.renderHybridPdfCanvas(shell, controller.signal, priority);
     const previewTask = (async () => {
-      if (readerContext.pdfDocument || shell.dataset.pdfPresented === "1") await readerContext.waitForReader(250);
+      // Keep the visible page's fallback immediate; only speculative pages
+      // should wait for the primary-PDF grace period.
+      if (readerContext.isPdfPageVisible(shell) && !readerContext.pdfDocument)
+        return readerContext.renderPdfImageShell(shell, false, priority);
+      // Give a warm primary PDF a short chance to win before starting preview
+      // I/O. If drawing is slower, the image stream remains the fallback.
+      const documentReady = await Promise.race([
+        readerContext.pdfHybridDocumentPromise?.then(() => true, () => false) || Promise.resolve(false),
+        readerContext.waitForReader(readerContext.PDF_HYBRID_DOCUMENT_GRACE_MS).then(() => false)
+      ]);
+      if (!documentReady) return readerContext.renderPdfImageShell(shell, false, priority);
+      const winner = await Promise.race([
+        pdfTask.then(() => "pdf", () => "preview"),
+        readerContext.waitForReader(150).then(() => "preview")
+      ]);
+      if (winner === "pdf") return pdfTask;
       if (controller.signal.aborted || !shell.isConnected) throw readerContext.readerAbortError();
       if (shell.querySelector("canvas.ready") || shell.dataset.pdfPresented === "1") return pdfTask;
       if (!readerContext.normalizePdfPriority(priority) && readerContext.pdfDocument) return pdfTask;
@@ -274,7 +289,7 @@ export function createReaderPdfRenderer(readerContext) {
          if (!entry) throw new Error("PDF page entry missing");
          let target = readerContext.pdfPageManifest.pageUrl(entry.page);
          if (readerContext.pdfV3Manifest) {
-           const preview = await readerContext.pdfV3Repository.preview(readerContext.pdfV3Manifest, readerContext.pdfV3Map, entry.page);
+            const preview = await readerContext.pdfV3Repository.preview(readerContext.pdfV3Manifest, readerContext.pdfV3Map, entry.page, renderController.signal);
            shell._v3PreviewEntry = preview.entry;
            readerContext.assertReaderActive();
            if (renderController.signal.aborted) throw readerContext.readerAbortError();

static/reader/pdf/reader-pdf-text-runtime.mjs

@@ -11,9 +11,10 @@ export function createReaderPdfTextRuntime(readerContext) {
   function createPdfV3Repository(sourceSha, pageCount) {
     return readerContext.createV3Repository({ sourceSha, pageCount, signal: readerContext.readerAbortController.signal,
       resourceUrl: readerContext.v3ResourceUrl,
-      readJson: (url, ref) => readerContext.readPdfOcrJson(url, VoiceOfMLReaderSecurity.LIMITS.chapterBytes, ref.sha256, ref.bytes),
-      readBytes: async (url, ref) => {
-        const response = await readerContext.fetchReaderUrl(url);
+       readJson: (url, ref, signal) => readerContext.readPdfOcrJson(
+         url, VoiceOfMLReaderSecurity.LIMITS.chapterBytes, ref.sha256, ref.bytes, "auto", signal),
+       readBytes: async (url, ref, signal) => {
+         const response = await readerContext.fetchReaderUrl(url, signal ? { signal } : {});
         if (!response.ok) throw new Error(`HTTP ${response.status}`);
         const packed = await VoiceOfMLReaderSecurity.readBytes(response, VoiceOfMLReaderSecurity.LIMITS.chapterBytes);
         const actual = [...new Uint8Array(await crypto.subtle.digest("SHA-256", packed))]
@@ -24,8 +25,8 @@ export function createReaderPdfTextRuntime(readerContext) {
     });
   }
 
-  async function readPdfOcrJson(url, limit = VoiceOfMLReaderSecurity.LIMITS.chapterBytes, digest = "", size = 0, priority = "auto") {
-    const response = await readerContext.fetchReaderUrl(url, { priority });
+  async function readPdfOcrJson(url, limit = VoiceOfMLReaderSecurity.LIMITS.chapterBytes, digest = "", size = 0, priority = "auto", signal = null) {
+    const response = await readerContext.fetchReaderUrl(url, { priority, ...(signal ? { signal } : {}) });
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
     let bytes = await VoiceOfMLReaderSecurity.readBytes(response, limit);
     if (size && bytes.byteLength !== size) throw new Error("PDF_OCR_SIZE_MISMATCH");
@@ -70,7 +71,7 @@ export function createReaderPdfTextRuntime(readerContext) {
       return readerContext.loadPdfOcrManifest().then((manifest) => {
         if (manifest?.text_layer) {
           readerContext.pdfTextLayerRepository ||= readerContext.createPdfV3Repository(manifest.source_sha256, manifest.page_count);
-          return readerContext.pdfTextLayerRepository.textPage(manifest.text_layer, page).then(payload => {
+           return readerContext.pdfTextLayerRepository.textPage(manifest.text_layer, page, readerContext.readerAbortController.signal).then(payload => {
             if (readerContext.pdfV3Map) {
               const geometry = readerContext.pdfV3Map.pages[page - 1];
               if (Math.abs((payload.geometry.width / payload.geometry.height) / (geometry.width / geometry.height) - 1) > .01)

static/reader/pdf/reader-v3.mjs

@@ -78,15 +78,16 @@ export function createV3Repository({ readJson, readBytes, resourceUrl, signal, p
   const cache = new Map(), pending = new Map();
   let bytes = 0, disposed = false, index = null, textPending = null, indexKey = "";
   const active = () => { if (disposed || signal?.aborted) throw new DOMException("Reader closed", "AbortError"); };
-  async function read(ref, source = sourceSha) {
+  async function read(ref, source = sourceSha, signal = null) {
     active();
+    signal?.throwIfAborted?.();
     validateResource(ref, source);
     const key = ref.bucket + ":" + ref.path + ":" + ref.sha256;
     const cached = cache.get(key);
     if (cached) { cache.delete(key); cache.set(key, cached); return cached.value; }
     if (pending.has(key)) return pending.get(key);
     if (pending.size >= 8) throw new Error("PDF_V3_BUSY");
-    const task = Promise.resolve().then(() => readJson(resourceUrl(ref), ref)).then(value => {
+    const task = Promise.resolve().then(() => readJson(resourceUrl(ref), ref, signal)).then(value => {
       active();
       const size = JSON.stringify(value).length * 2;
       if (size <= 2 * 1024 * 1024) {
@@ -101,13 +102,14 @@ export function createV3Repository({ readJson, readBytes, resourceUrl, signal, p
     pending.set(key, task);
     return task;
   }
-  async function textIndex(ref) {
-    active(); validateResource(ref, sourceSha);
+    async function textIndex(ref, signal = null) {
+      active(); validateResource(ref, sourceSha);
+      signal?.throwIfAborted?.();
     const key = ref.bucket + ":" + ref.path + ":" + ref.sha256;
     if (indexKey && indexKey !== key) throw new Error("PDF_V3_GENERATION_CHANGED");
     indexKey = key;
     if (index) return index;
-    if (!textPending) textPending = read(ref).then(value => {
+    if (!textPending) textPending = read(ref, sourceSha, signal).then(value => {
       if (value.version !== 1 || value.kind !== "pdf-text-layer-index" || value.complete !== true ||
           value.source_sha256 !== sourceSha || value.page_count !== pageCount || !sha(value.generation) ||
           !["raw", "effective"].includes(value.revision) || value.offset_unit !== "unicode-codepoint") invalid();
@@ -128,10 +130,10 @@ export function createV3Repository({ readJson, readBytes, resourceUrl, signal, p
   return {
     read,
     textIndex,
-    async textPage(ref, page) {
-      if (!integer(page) || page > pageCount) invalid();
-      const root = await textIndex(ref), part = partitionFor(root.partitions, page);
-      const value = await read(part.resource);
+      async textPage(ref, page, signal = null) {
+        if (!integer(page) || page > pageCount) invalid();
+        const root = await textIndex(ref, signal), part = partitionFor(root.partitions, page);
+        const value = await read(part.resource, sourceSha, signal);
       if (value.version !== 1 || value.kind !== "pdf-text-partition" || value.source_sha256 !== sourceSha ||
           value.generation !== root.generation || value.start !== part.start || value.end !== part.end ||
           !Array.isArray(value.pages) || value.pages.length !== part.end - part.start + 1 ||
@@ -141,11 +143,12 @@ export function createV3Repository({ readJson, readBytes, resourceUrl, signal, p
       if (!entry.resource.path.endsWith(`/text/page-${String(page).padStart(6, "0")}.json.gz`)) invalid();
       return validateTextLayer(await read(entry.resource), entry, sourceSha);
     },
-    async preview(manifest, map, page) {
+    async preview(manifest, map, page, signal = null) {
       active();
+      signal?.throwIfAborted?.();
       const part = partitionFor(manifest.preview.partitions, page);
       if (!part) throw new Error("PDF_V3_PREVIEW_PENDING");
-      const data = await read(part.resource);
+      const data = await read(part.resource, sourceSha, signal);
       if (data.version !== 3 || data.kind !== "pdf-preview-partition" || data.source_sha256 !== sourceSha ||
           data.page_map_sha256 !== manifest.page_map.sha256 || data.start !== part.start || data.end !== part.end ||
           !Array.isArray(data.pages) || data.pages.length > part.end - part.start + 1) invalid();
@@ -164,8 +167,9 @@ export function createV3Repository({ readJson, readBytes, resourceUrl, signal, p
       if (part.complete && data.pages.length !== part.end - part.start + 1) invalid();
       const entry = data.pages.find(p => p.page === page);
       if (!entry) throw new Error("PDF_V3_PREVIEW_PENDING");
-      const packed = await readBytes(resourceUrl(entry.resource), entry.resource);
+      const packed = await readBytes(resourceUrl(entry.resource), entry.resource, signal);
       active();
+      signal?.throwIfAborted?.();
       return { entry, blob: new Blob([packed], { type: entry.codec === "svg" ? "image/svg+xml" : `image/${entry.codec}` }) };
     },
     dispose() { disposed = true; cache.clear(); bytes = 0; index = null; }

tests/test_reader_pdf_hybrid.py

@@ -173,6 +173,22 @@ class HybridPdfTests(unittest.TestCase):
         self.assertNotIn(60, self.images)
         self.assertEqual(self.errors, [])
 
+    def test_fast_pdf_handoff_does_not_start_preview_stream(self):
+        self.page.add_init_script("""(() => {
+          const timer = setInterval(() => {
+            if (typeof window.__releaseDocument !== 'function') return;
+            clearInterval(timer);
+            setTimeout(() => window.__releaseDocument(), 50);
+          }, 0);
+        })();""")
+        source = ("https://voiceofml-search.hf.space" if PAGES else self.origin) + "/api/reader-bucket-resource?" + urlencode({"path": PATH})
+        self.page.goto(self.origin + BASE_PATH + "/static/reader.html?" + urlencode(
+            {"url": source, "ext": "pdf-pages", "pdf_document": PDF}), wait_until="domcontentloaded")
+        shell = self.page.locator('.reader-page[data-page="1"]')
+        shell.locator("canvas.ready").wait_for()
+        self.assertEqual(self.images, [1])
+        self.assertEqual(self.errors, [])
+
     def test_late_page_stream_backfills_slow_pdf_then_handoffs_on_mobile(self):
         self.page.set_viewport_size({"width": 390, "height": 844})
         self.open()