fix(reader): PDF.js for large hybrid books, prioritized image fallback, stable page geometry, hybrid outline

- Range-transport PDFs up to 1 GiB (complete bodies keep 512 MiB) on client and proxy
- A failed primary leaves hybrid mode; image pages use a priority-ordered pool with preemption
- Visible-page image fallback waits for this book's measured PDF draw time
- Image and canvas geometry changes preserve the reading anchor; first geometry seeds shells
- PDF outline fills a missing manifest TOC after the first page

backend/app.py

@@ -1907,6 +1907,9 @@ READER_ISOLATION_HEADERS = {
     "X-Content-Type-Options": "nosniff",
 }
 READER_DOCUMENT_MAX_BYTES = 512 * 1024 * 1024
+# Total size accepted for a PDF whose bounded Range reads are proxied. Each
+# response body still obeys READER_DOCUMENT_MAX_BYTES; complete bodies keep it.
+READER_PDF_RANGE_MAX_BYTES = 1024 * 1024 * 1024
 READER_RESOURCE_MAX_ARCHIVE_BYTES = 512 * 1024 * 1024
 READER_RESOURCE_MAX_BYTES = 64 * 1024 * 1024
 READER_BUCKET_CACHE_TTL_SECONDS = 3600
@@ -2810,6 +2813,11 @@ async def _stream_reader_document(
         if name in request.headers
     }
     range_header = forwarded_headers.get("Range")
+    bounded_range = re.fullmatch(r"bytes=([0-9]{1,20})-([0-9]{1,20})", range_header or "")
+    total_limit = max_bytes
+    if (max_bytes is not None and bounded_range and not is_media_stream
+            and (urlparse(target_url).path.lower().endswith(".pdf") or media_type == "application/pdf")):
+        total_limit = max(max_bytes, READER_PDF_RANGE_MAX_BYTES)
     # Conditional requests must reach the origin: a cached partial body cannot
     # represent a 200/304 decision made against a different validator.
     has_conditionals = any(
@@ -2907,11 +2915,11 @@ async def _stream_reader_document(
             if (range_start > range_end or range_end >= total_length
                     or (length is not None and length != range_end - range_start + 1)):
                 return JSONResponse({"error": "上游阅读文件范围无效"}, status_code=502)
-            if max_bytes is not None and total_length > max_bytes:
+            if total_limit is not None and total_length > total_limit:
                 return JSONResponse({"error": "阅读文件过大"}, status_code=413)
         elif status == 416:
             match = re.fullmatch(r"bytes\s+\*/([0-9]{1,20})", str(content_range or ""))
-            if match and max_bytes is not None and int(match.group(1)) > max_bytes:
+            if match and total_limit is not None and int(match.group(1)) > total_limit:
                 return JSONResponse({"error": "阅读文件过大"}, status_code=413)
         if request.method == "HEAD" or status == 304:
             return Response(status_code=status, headers=headers)

static/reader.js

@@ -83,6 +83,17 @@ const readerContext = {
   get THEME_SUN_ICON() { return THEME_SUN_ICON; },
   get TOC_VIRTUALIZATION_THRESHOLD() { return TOC_VIRTUALIZATION_THRESHOLD; },
   get TOC_VIRTUAL_ROW_HEIGHT() { return TOC_VIRTUAL_ROW_HEIGHT; },
+  get acquirePdfPreviewSlot() { return acquirePdfPreviewSlot; }, set acquirePdfPreviewSlot(value) { acquirePdfPreviewSlot = value; },
+  get releasePdfPreviewSlot() { return releasePdfPreviewSlot; }, set releasePdfPreviewSlot(value) { releasePdfPreviewSlot = value; },
+  get pdfPreviewLoads() { return pdfPreviewLoads; }, set pdfPreviewLoads(value) { pdfPreviewLoads = value; },
+  get resetPdfLatencySamples() { return resetPdfLatencySamples; }, set resetPdfLatencySamples(value) { resetPdfLatencySamples = value; },
+  get notePdfLatency() { return notePdfLatency; }, set notePdfLatency(value) { notePdfLatency = value; },
+  get pdfHybridPreviewGrace() { return pdfHybridPreviewGrace; }, set pdfHybridPreviewGrace(value) { pdfHybridPreviewGrace = value; },
+  get applyPdfShellGeometry() { return applyPdfShellGeometry; }, set applyPdfShellGeometry(value) { applyPdfShellGeometry = value; },
+  get startPdfHybridDocument() { return startPdfHybridDocument; }, set startPdfHybridDocument(value) { startPdfHybridDocument = value; },
+  get leavePdfHybridMode() { return leavePdfHybridMode; }, set leavePdfHybridMode(value) { leavePdfHybridMode = value; },
+  get loadPdfOutline() { return loadPdfOutline; }, set loadPdfOutline(value) { loadPdfOutline = value; },
+  get seedPdfPageGeometry() { return seedPdfPageGeometry; }, set seedPdfPageGeometry(value) { seedPdfPageGeometry = value; },
   get acquirePdfRenderSlot() { return acquirePdfRenderSlot; }, set acquirePdfRenderSlot(value) { acquirePdfRenderSlot = value; },
   get acquirePdfTextSlot() { return acquirePdfTextSlot; }, set acquirePdfTextSlot(value) { acquirePdfTextSlot = value; },
   get activateFoliateTocEntry() { return activateFoliateTocEntry; }, set activateFoliateTocEntry(value) { activateFoliateTocEntry = value; },
@@ -243,7 +254,6 @@ const readerContext = {
   get pdfFirstPagePreloadPage() { return pdfFirstPagePreloadPage; }, set pdfFirstPagePreloadPage(value) { pdfFirstPagePreloadPage = value; },
   get pdfHybridDocumentPromise() { return pdfHybridDocumentPromise; }, set pdfHybridDocumentPromise(value) { pdfHybridDocumentPromise = value; },
   get pdfHybridSearchUnavailable() { return pdfHybridSearchUnavailable; }, set pdfHybridSearchUnavailable(value) { pdfHybridSearchUnavailable = value; },
-  get pdfHybridPreviewLoads() { return pdfHybridPreviewLoads; }, set pdfHybridPreviewLoads(value) { pdfHybridPreviewLoads = value; },
   get pdfHybridUrl() { return pdfHybridUrl; }, set pdfHybridUrl(value) { pdfHybridUrl = value; },
   get pdfLastScrollTop() { return pdfLastScrollTop; }, set pdfLastScrollTop(value) { pdfLastScrollTop = value; },
   get pdfManifestPrefetchActive() { return pdfManifestPrefetchActive; },
@@ -587,7 +597,7 @@ let {
   stopPdfManifestPrefetch, trimPdfManifestPrefetches, pdfPixelBudget, pdfSurfacePixels,
   pdfRetainedPixels, trimPdfSurfaces, clearPdfManifestPrefetches, takePdfManifestPrefetch,
   queuePdfManifestPrefetch, prioritizePdfManifestPrefetch, schedulePdfManifestPrefetch, trimPdfManifestImages,
-  cancelSpeculativePdfRenders, promotePdfRenderWaiter, acquirePdfRenderSlot, releasePdfRenderSlot,
+  cancelSpeculativePdfRenders, promotePdfRenderWaiter, acquirePdfPreviewSlot, releasePdfPreviewSlot, pdfPreviewLoads, acquirePdfRenderSlot, releasePdfRenderSlot,
   acquirePdfTextSlot, drainPdfTextWaiters, releasePdfTextSlot, trimPdfCanvases,
   rerenderVisiblePdfPages, refreshNearbyPdfPages, scheduleVisiblePdfRenderReconciliation,
   notePdfViewportMotion, pdfScrollActivity
@@ -636,8 +646,8 @@ let {
 
 let {
   preloadPdfFirstPage, pdfManifestSource, pdfPageEntry, appendShellsBatched,
-  pdfSelectionIntersects, correctPdfCrossPageSelection, createPdfShellWindow, renderPdfPages,
-  renderImagePages, renderPdf
+  pdfSelectionIntersects, correctPdfCrossPageSelection, createPdfShellWindow, startPdfHybridDocument,
+  leavePdfHybridMode, loadPdfOutline, seedPdfPageGeometry, renderPdfPages, renderImagePages, renderPdf
 } = createReaderPdfPageWindow(readerContext);
 
 let {
@@ -657,7 +667,8 @@ let {
 let {
   setPdfPageLoadingState, isPdfPageVisible, pdfPagePriority, normalizePdfPriority,
   renderPdfInBackground, pdfPrimarySource, renderPdfManifestShell, renderHybridPdfCanvas,
-  renderPdfImageShell, renderPdfShell
+  renderPdfImageShell, renderPdfShell, resetPdfLatencySamples, notePdfLatency, pdfHybridPreviewGrace,
+  applyPdfShellGeometry
 } = createReaderPdfRenderer(readerContext);
 
 let {
@@ -740,7 +751,6 @@ let pdfEnginePreload = null;
 let pdfHybridUrl = "";
 let pdfHybridDocumentPromise = null;
 let pdfHybridSearchUnavailable = false;
-let pdfHybridPreviewLoads = 0;
 let pdfWorker = null;
 let releasePdfWorker = null;
 readerBindings.applySourceSessionAndCachedMetadata();

static/reader/core/reader-security.js

@@ -2,6 +2,8 @@
   "use strict";
   const LIMITS = Object.freeze({
     documentBytes: 512 * 1024 * 1024,
+    // PDF.js range transport only: demanded chunks are read, not the body.
+    pdfRangeDocumentBytes: 1024 * 1024 * 1024,
     archiveCompressedBytes: 512 * 1024 * 1024,
     archiveExpandedBytes: 1536 * 1024 * 1024,
     archiveEntries: 20000,

static/reader/pdf/reader-pdf-engine.mjs

@@ -25,13 +25,20 @@ export function createReaderPdfEngine(readerContext) {
       readerContext.openPdfRangeTask(pdfjs, options(url), {
         signal:owner.signal, readBytes:VoiceOfMLReaderSecurity.readBytes, initial,
         limit:VoiceOfMLReaderSecurity.LIMITS.documentBytes,
+        rangeLimit:VoiceOfMLReaderSecurity.LIMITS.pdfRangeDocumentBytes,
         canPrefetchOpening: () => !!readerContext.pdfV3Manifest && readerContext.readerRestorationLoaded &&
           (!readerContext.readerRestorationEntry || Number(readerContext.readerRestorationEntry.page) <= 1),
         canPrefetchFirstPage: () => readerContext.capability?.mode === "pdf" &&
           readerContext.readerRestorationLoaded && !readerContext.restorationFailed &&
           (!readerContext.readerRestorationEntry || Number(readerContext.readerRestorationEntry.page) === 1),
-        onError() {
-          if (!documentReady || readerContext.readerAbortController.signal.aborted || readerContext.capability.mode !== "pdf") return;
+        onError(error) {
+          if (!documentReady || readerContext.readerAbortController.signal.aborted) return;
+          // A hybrid PDF-pages book keeps its image stream as the only surface.
+          if (readerContext.capability.mode === "pdf-pages" && readerContext.pdfHybridUrl) {
+            readerContext.leavePdfHybridMode(undefined, error);
+            return;
+          }
+          if (readerContext.capability.mode !== "pdf") return;
           // Page retries cannot revive a destroyed PDF.js document. Capture an
           // eligible position before failure stops work; reload owns recovery.
           readerContext.saveProgress();
@@ -191,6 +198,7 @@ export function createReaderPdfEngine(readerContext) {
     let initial = readerContext.preparePdfInitialRange({url:proxyUrl, rangeChunkSize:262144}, {
       signal:AbortSignal.any([owner.signal, readerContext.readerAbortController.signal]),
       readBytes:VoiceOfMLReaderSecurity.readBytes, limit:VoiceOfMLReaderSecurity.LIMITS.documentBytes,
+      rangeLimit:VoiceOfMLReaderSecurity.LIMITS.pdfRangeDocumentBytes,
       canPrefetchFirstPage: () => pageOneKnown && !owner.signal.aborted &&
         navigation === readerContext.readerRuntime?.currentGeneration("navigation")
     });

static/reader/pdf/reader-pdf-network.mjs

@@ -80,7 +80,10 @@ function abortable(promise, signal) {
   });
 }
 
-async function readPdfRange(options, begin, end, {signal, readBytes, limit, rangeCache}, expected = null, onHeaders = null, partialOnly = false) {
+// Complete bodies retain `limit`. A validated range-transport document may be
+// larger (`rangeLimit`): PDF.js reserves one length-sized buffer, but only
+// demanded chunks are fetched or written. See the dated large-PDF report.
+async function readPdfRange(options, begin, end, {signal, readBytes, limit, rangeLimit = limit, rangeCache}, expected = null, onHeaders = null, partialOnly = false) {
   signal.throwIfAborted();
   const key = new URL(options.url, globalThis.location?.href).href;
   let cached = null;
@@ -102,7 +105,8 @@ async function readPdfRange(options, begin, end, {signal, readBytes, limit, rang
     if (response.status !== 206 || !match || match.slice(1).some(value=>!Number.isSafeInteger(Number(value))))
       throw invalid();
     const [start, last, total] = match.slice(1).map(Number);
-    if (total > limit) throw Object.assign(new Error("READER_RESOURCE_LIMIT"), {code:"READER_RESOURCE_LIMIT"});
+    if (total > (total === last + 1 - start ? limit : rangeLimit))
+      throw Object.assign(new Error("READER_RESOURCE_LIMIT"), {code:"READER_RESOURCE_LIMIT"});
     if (start !== begin || last !== Math.min(end,total)-1 || total <= start) throw invalid();
     const etag = response.headers.get("ETag"), encoding = response.headers.get("Content-Encoding");
     if (encoding && encoding !== "identity") throw invalid();
@@ -269,7 +273,7 @@ export async function preparePdfInitialRange(options, hooks) {
   }
 }
 
-export async function openPdfRangeTask(pdfjs, options, {signal, readBytes, limit, onError, initial = null,
+export async function openPdfRangeTask(pdfjs, options, {signal, readBytes, limit, rangeLimit = limit, onError, initial = null,
   rangeCache = sharedPdfRangeCache(), canPrefetchFirstPage = () => false, canPrefetchOpening = () => false}) {
   if (typeof pdfjs.PDFDataRangeTransport !== "function") return pdfjs.getDocument(options);
   const chunkSize = options.rangeChunkSize;
@@ -288,10 +292,10 @@ export async function openPdfRangeTask(pdfjs, options, {signal, readBytes, limit
   const cancelled = () => stop(signal.reason);
   signal.addEventListener("abort", cancelled, {once:true});
   const read = (begin, end, expected = null) => readPdfRange(options, begin, end,
-    {signal:active, readBytes, limit, rangeCache}, expected);
+    {signal:active, readBytes, limit, rangeLimit, rangeCache}, expected);
   try {
     const first = prepared = await (initial || preparePdfInitialRange(options,
-      {signal:active, readBytes, limit, rangeCache, canPrefetchFirstPage}));
+      {signal:active, readBytes, limit, rangeLimit, rangeCache, canPrefetchFirstPage}));
     active.throwIfAborted();
     if (!first) {
       stop();
@@ -310,7 +314,7 @@ export async function openPdfRangeTask(pdfjs, options, {signal, readBytes, limit
     let tail = first.tail || null;
     if (!tail && first.total > chunkSize * 4) {
       const begin = Math.floor((first.total - 1) / chunkSize) * chunkSize - chunkSize;
-      tail = preparePdfRangeHint(options, begin, first.total, {signal:active, readBytes, limit, rangeCache}, first);
+      tail = preparePdfRangeHint(options, begin, first.total, {signal:active, readBytes, limit, rangeLimit, rangeCache}, first);
     }
     // A conservative read-ahead hint, not a PDF parser: only a direct Length
     // before the first stream, in the bounded opening header, can qualify.

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

@@ -45,16 +45,27 @@ export function createReaderPdfPageWindow(readerContext) {
     return ocrEntry ? { ...pageEntry, ...ocrEntry, page } : pageEntry;
   }
 
+  // Per-book PDF-pages state; renderPdfPages resets it.
+  let pdfPagesBook = { hybridFailed: false, manifestToc: false, initialShown: false, outlineStarted: false, seedRatio: 0 };
+
   function startPdfHybridDocument(totalPages = readerContext.documentState.pageCount) {
+    // A failed primary leaves hybrid mode for the rest of this book.
+    if (pdfPagesBook.hybridFailed || readerContext.pdfHybridDocumentPromise) return;
     readerContext.pdfHybridUrl = readerContext.pdfPrimarySource();
-    if (!readerContext.pdfHybridUrl || readerContext.pdfHybridDocumentPromise) return;
+    if (!readerContext.pdfHybridUrl) return;
+    const book = pdfPagesBook;
     const documentPromise = readerContext.loadPdfDocument(readerContext.pdfHybridUrl).then((pdf) => {
       readerContext.assertReaderActive();
-      if (pdf.numPages !== totalPages) throw new Error("PDF_PRIMARY_PAGE_COUNT_MISMATCH");
+      if (book.hybridFailed) throw new Error("PDF_PRIMARY_TRANSPORT");
+      if (pdf.numPages !== totalPages) {
+        pdf.destroy?.()?.catch?.(() => {});
+        throw new Error("PDF_PRIMARY_PAGE_COUNT_MISMATCH");
+      }
       readerContext.pdfDocument = pdf;
       readerContext.clearPdfManifestPrefetches();
       readerContext.cancelSpeculativePdfRenders(readerContext.pageAtMarker?.());
       readerContext.syncCapabilityControls();
+      maybeLoadHybridOutline(book);
       return pdf;
     });
     readerContext.pdfHybridDocumentPromise = documentPromise;
@@ -62,12 +73,95 @@ export function createReaderPdfPageWindow(readerContext) {
       if (error?.name === "AbortError" || readerContext.readerLifecycle.disposed ||
           readerContext.pdfHybridDocumentPromise !== documentPromise) return;
       console.warn("Primary PDF unavailable; page stream retained", error);
-      // The page stream stays readable, but without OCR it has no text layer.
-      readerContext.pdfHybridSearchUnavailable = true;
-      readerContext.syncCapabilityControls();
+      leavePdfHybridMode(book);
     });
   }
 
+  // The image stream becomes the only surface: ordinary prioritized image
+  // admission and manifest prefetch replace the PDF-preview race.
+  function leavePdfHybridMode(book = pdfPagesBook, error = null) {
+    if (book !== pdfPagesBook || book.hybridFailed || readerContext.readerLifecycle.disposed) return;
+    if (error) console.warn("Primary PDF failed after opening; page stream retained", error);
+    book.hybridFailed = true;
+    const pdf = readerContext.pdfDocument;
+    readerContext.pdfDocument = null;
+    readerContext.pdfHybridUrl = "";
+    // The page stream stays readable, but without OCR it has no text layer.
+    readerContext.pdfHybridSearchUnavailable = true;
+    if (pdf && error) pdf.destroy?.()?.catch?.(() => {});
+    for (const shell of readerContext.content.querySelectorAll(".reader-page[data-pdf-hybrid]")) {
+      delete shell.dataset.pdfHybrid;
+      if (shell.dataset.renderState !== "rendered") shell._pdfRenderNeedsRequeue = true;
+    }
+    readerContext.syncCapabilityControls();
+    readerContext.scheduleVisiblePdfRenderReconciliation(true);
+    const page = readerContext.documentState.page;
+    if (page) readerContext.schedulePdfManifestPrefetch(page);
+  }
+
+  async function loadPdfOutline(pdf) {
+    if (typeof pdf?.getOutline !== "function") return;
+    try {
+      const outline = await readerContext.awaitReader(pdf.getOutline()),
+        entries = [];
+      const cleanLabel = (value) =>
+        String(value || "未命名章节")
+          .replace(/[\u2610-\u2612\u25a1]\s*[xX×]?\s*$/u, "")
+          .trim() || "未命名章节";
+      const append = async (items, depth = 0) => {
+        for (const item of items || []) {
+          readerContext.assertReaderActive();
+          let destination = item.dest,
+            page = 0;
+          if (typeof destination === "string") destination = await pdf.getDestination(destination);
+          if (destination && destination[0]) {
+            try {
+              page = (await pdf.getPageIndex(destination[0])) + 1;
+            } catch (_) {}
+          }
+          entries.push({
+            label: page ? `${cleanLabel(item.title)} · 第 ${page} 页` : cleanLabel(item.title),
+            depth,
+            activate: (generation) => (page ? readerContext.goToPage(page, generation) : false)
+          });
+          await append(item.items, depth + 1);
+        }
+      };
+      await append(outline);
+      readerContext.assertReaderActive();
+      return entries;
+    } catch (error) {
+      if (!readerContext.readerAbortController.signal.aborted)
+        console.warn("PDF outline could not be loaded", error);
+    }
+  }
+
+  // A page manifest without its own TOC takes the primary PDF outline, after
+  // the opening page is shown so outline reads never delay the first screen.
+  function maybeLoadHybridOutline(book = pdfPagesBook) {
+    if (book !== pdfPagesBook || book.manifestToc || book.outlineStarted || !book.initialShown) return;
+    const pdf = readerContext.pdfDocument;
+    if (!pdf || !readerContext.pdfHybridUrl) return;
+    book.outlineStarted = true;
+    loadPdfOutline(pdf).then((entries) => {
+      if (book !== pdfPagesBook || book.manifestToc || !entries?.length || readerContext.readerLifecycle.disposed) return;
+      readerContext.setToc(entries);
+    }).catch(() => {});
+  }
+
+  // The first measured page geometry replaces the A4 estimate for unrendered
+  // shells and virtual chunk heights. Callers run inside applyPdfShellGeometry,
+  // which keeps the reading anchor in place.
+  function seedPdfPageGeometry(width, height) {
+    if (pdfPagesBook.seedRatio || readerContext.pdfV3Map || !(width > 0 && height > 0)) return;
+    const ratio = height / width;
+    pdfPagesBook.seedRatio = ratio;
+    if (Math.abs(ratio / 1.414 - 1) < .001) return;
+    for (const shell of readerContext.content.querySelectorAll(".reader-page:not([data-page-geometry])"))
+      shell.style.aspectRatio = `1 / ${ratio}`;
+    readerContext.pdfShellWindow?.setDefaultRatio(ratio);
+  }
+
   async function appendShellsBatched(createShell, total, batchSize) {
     for (let start = 2; start <= total; start += batchSize) {
       readerContext.assertReaderActive();
@@ -142,6 +236,7 @@ export function createReaderPdfPageWindow(readerContext) {
   }
 
   function createPdfShellWindow(total, firstShell, createShell, unobserve, defaultRatio) {
+    // `defaultRatio` may be replaced once a real page geometry is known.
     if (total <= 256) return null;
     const chunkSize = 32, chunks = [], ratios = new Map();
     let frame = 0, disposed = false;
@@ -255,6 +350,13 @@ export function createReaderPdfPageWindow(readerContext) {
         const bounds = shell.getBoundingClientRect();
         if (bounds.width && bounds.height) ratios.set(Number(shell.dataset.page), bounds.height / bounds.width);
       },
+      // The caller owns anchor compensation (see seedPdfPageGeometry).
+      setDefaultRatio(ratio) {
+        if (disposed || !(ratio > 0)) return;
+        defaultRatio = ratio;
+        const width = readWidth();
+        for (const chunk of chunks) if (!chunk.mounted) chunk.element.style.height = `${chunkHeight(chunk, width)}px`;
+      },
       schedule,
       resize,
       dispose() {
@@ -271,6 +373,9 @@ export function createReaderPdfPageWindow(readerContext) {
   }
 
   async function renderPdfPages(prepared) {
+    pdfPagesBook = { hybridFailed: false, manifestToc: false, initialShown: false, outlineStarted: false, seedRatio: 0 };
+    const book = pdfPagesBook;
+    readerContext.resetPdfLatencySamples();
     const response = await prepared;
     if (!response.ok) throw new Error(`HTTP ${response.status}`);
     const decoded = JSON.parse(await VoiceOfMLReaderSecurity.readText(response, VoiceOfMLReaderSecurity.LIMITS.manifestBytes));
@@ -304,6 +409,7 @@ export function createReaderPdfPageWindow(readerContext) {
     const source = readerContext.pdfManifestSource();
     const totalPages = manifest.page_count;
     if (!source) throw new Error("PDF_MANIFEST_INVALID");
+    book.manifestToc = Array.isArray(manifest.toc) && manifest.toc.length > 0;
     readerContext.pdfPageManifest = { ...source, pageCount: totalPages };
     if (readerContext.pdfV3Manifest) readerContext.pdfPageManifest.pageUrl = () => "";
     startPdfHybridDocument(totalPages);
@@ -375,7 +481,7 @@ export function createReaderPdfPageWindow(readerContext) {
       shell.className = "reader-page";
       shell.dataset.page = String(page);
       if (readerContext.pdfHybridUrl) shell.dataset.pdfHybrid = "1";
-      shell.style.aspectRatio = "1 / 1.414";
+      shell.style.aspectRatio = `1 / ${book.seedRatio || 1.414}`;
       if (readerContext.pdfV3Map) {
         const geometry = readerContext.pdfV3Map.pages[page - 1];
         shell.style.aspectRatio = `${geometry.width} / ${geometry.height}`;
@@ -409,7 +515,7 @@ export function createReaderPdfPageWindow(readerContext) {
     readerContext.pdfShellWindow = readerContext.createPdfShellWindow(totalPages, firstShell, createShell, (shell) => {
       observer.unobserve(shell);
       visibleObserver.unobserve(shell);
-    }, 1.414);
+    }, book.seedRatio || 1.414);
     readerContext.pdfShellsReady = readerContext.pdfShellWindow ? Promise.resolve() : readerContext.appendShellsBatched(createShell, totalPages, 250);
     readerContext.pdfShellsReady.catch(() => {});
     try {
@@ -424,6 +530,8 @@ export function createReaderPdfPageWindow(readerContext) {
     } finally {
       releaseInitialRenderGate();
     }
+    book.initialShown = true;
+    maybeLoadHybridOutline(book);
   }
 
   async function renderImagePages(prepared) {
@@ -558,42 +666,9 @@ export function createReaderPdfPageWindow(readerContext) {
     } finally {
       releaseInitialRenderGate();
     }
-    const outlineReady = (async () => {
-      if (typeof pdf.getOutline !== "function") return;
-      try {
-        const outline = await readerContext.awaitReader(pdf.getOutline()),
-          entries = [];
-        const cleanLabel = (value) =>
-          String(value || "未命名章节")
-            .replace(/[\u2610-\u2612\u25a1]\s*[xX×]?\s*$/u, "")
-            .trim() || "未命名章节";
-        const append = async (items, depth = 0) => {
-          for (const item of items || []) {
-            readerContext.assertReaderActive();
-            let destination = item.dest,
-              page = 0;
-            if (typeof destination === "string") destination = await pdf.getDestination(destination);
-            if (destination && destination[0]) {
-              try {
-                page = (await pdf.getPageIndex(destination[0])) + 1;
-              } catch (_) {}
-            }
-            entries.push({
-              label: page ? `${cleanLabel(item.title)} · 第 ${page} 页` : cleanLabel(item.title),
-              depth,
-              activate: (generation) => (page ? readerContext.goToPage(page, generation) : false)
-            });
-            await append(item.items, depth + 1);
-          }
-        };
-        await append(outline);
-        readerContext.assertReaderActive();
-        if (entries.length) readerContext.setToc(entries);
-      } catch (error) {
-        if (!readerContext.readerAbortController.signal.aborted)
-          console.warn("PDF outline could not be loaded", error);
-      }
-    })();
+    const outlineReady = loadPdfOutline(pdf).then((entries) => {
+      if (entries?.length) readerContext.setToc(entries);
+    });
     outlineReady.catch(() => {});
     await readerContext.pdfShellsReady;
     readerContext.assertReaderActive();
@@ -607,6 +682,10 @@ export function createReaderPdfPageWindow(readerContext) {
     pdfSelectionIntersects,
     correctPdfCrossPageSelection,
     createPdfShellWindow,
+    startPdfHybridDocument,
+    leavePdfHybridMode,
+    loadPdfOutline,
+    seedPdfPageGeometry,
     renderPdfPages,
     renderImagePages,
     renderPdf

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

@@ -127,6 +127,51 @@ export function createReaderPdfRenderer(readerContext) {
     } catch (_) { return ""; }
   }
 
+  // Recent per-page latencies for this book: PDF.js admission-to-draw and
+  // page-image admission-to-decode. They choose the visible-page image grace.
+  const pdfLatencySamples = { pdf: [], preview: [] };
+
+  function resetPdfLatencySamples() {
+    pdfLatencySamples.pdf.length = pdfLatencySamples.preview.length = 0;
+  }
+
+  function notePdfLatency(kind, milliseconds) {
+    const samples = pdfLatencySamples[kind];
+    if (!samples || !Number.isFinite(milliseconds) || milliseconds < 0) return;
+    samples.push(milliseconds);
+    if (samples.length > 12) samples.shift();
+  }
+
+  function pdfHybridPreviewGrace() {
+    // The image stream is a fallback once PDF.js is ready. Start it only when a
+    // draw is slower than this book's typical draw, not on every short wait:
+    // a duplicate image download competes with the PDF and swaps surfaces.
+    const median = (values, fallback) => {
+      if (!values.length) return fallback;
+      const sorted = [...values].sort((a, b) => a - b);
+      return sorted[sorted.length >> 1];
+    };
+    const pdf = median(pdfLatencySamples.pdf, 800), preview = median(pdfLatencySamples.preview, 2400);
+    // When this book's images are measurably faster than its PDF draws (small
+    // v3 previews, very heavy pages), keep the short fallback grace.
+    if (pdfLatencySamples.pdf.length >= 2 && pdfLatencySamples.preview.length >= 2 && preview < pdf * .8) return 150;
+    return Math.round(Math.max(400, Math.min(3000, pdf * 2)));
+  }
+
+  // Applies a page-geometry change (aspect ratio, surface swap) while keeping
+  // the reading anchor at the same visual position.
+  function applyPdfShellGeometry(change) {
+    const anchor = readerContext.content.querySelector(`.reader-page[data-page="${readerContext.documentState.page}"]`);
+    const viewportTop = readerContext.viewport.getBoundingClientRect().top;
+    const before = anchor?.getBoundingClientRect();
+    const fraction = before ? Math.max(0, (viewportTop - before.top) / Math.max(1, before.height)) : 0;
+    change();
+    if (!before || !anchor.isConnected) return;
+    const after = anchor.getBoundingClientRect();
+    const delta = after.top - before.top + fraction * (after.height - before.height);
+    if (Math.abs(delta) >= .5) readerContext.viewport.scrollTop += delta;
+  }
+
   function renderPdfManifestShell(shell, force = false, priority = false) {
     if (!readerContext.pdfHybridUrl) return readerContext.renderPdfImageShell(shell, force, priority);
     if (!force && shell.querySelector("canvas.ready")) return Promise.resolve();
@@ -170,18 +215,24 @@ export function createReaderPdfRenderer(readerContext) {
       // fallback: scrolling may promote it while its getPage/draw is still slow.
       let pdfSettled = false;
       pdfTask.then(() => { pdfSettled = true; }, () => { pdfSettled = true; });
-      while (!readerContext.isPdfPageVisible(shell) && !pdfSettled) {
+      const pdfOutcome = pdfTask.then(() => "pdf", () => "preview");
+      while (true) {
+        while (!readerContext.isPdfPageVisible(shell) && !pdfSettled) {
+          if (controller.signal.aborted || !shell.isConnected) throw readerContext.readerAbortError();
+          await readerContext.waitForReader(100);
+        }
+        if (controller.signal.aborted || !shell.isConnected) throw readerContext.readerAbortError();
+        // The grace counts from visibility. A page flown past during fast
+        // scrolling therefore starts no image download of its own.
+        const winner = await Promise.race([
+          pdfOutcome,
+          readerContext.waitForReader(readerContext.pdfHybridPreviewGrace()).then(() => "preview")
+        ]);
+        if (winner === "pdf") return pdfTask;
         if (controller.signal.aborted || !shell.isConnected) throw readerContext.readerAbortError();
-        await readerContext.waitForReader(100);
+        if (shell.querySelector("canvas.ready") || shell.dataset.pdfPresented === "1") return pdfTask;
+        if (pdfSettled || readerContext.isPdfPageVisible(shell)) break;
       }
-      if (controller.signal.aborted || !shell.isConnected) throw readerContext.readerAbortError();
-      const winner = await Promise.race([
-        pdfTask.then(() => "pdf", () => "preview"),
-        readerContext.waitForReader(readerContext.pdfScrollActivity?.(true) ? 0 : 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;
       const preview = await readerContext.renderPdfImageShell(shell, false, priority);
       if (controller.signal.aborted) throw readerContext.readerAbortError();
       return preview;
@@ -213,6 +264,7 @@ export function createReaderPdfRenderer(readerContext) {
     signal.addEventListener("abort", cancel, { once: true });
     try {
       const pdf = await readerContext.awaitReader(readerContext.pdfHybridDocumentPromise, signal);
+      let admittedAt = 0;
       do {
         const generation = readerContext.readerRuntime.currentGeneration("pdf");
         if (signal.aborted || !shell.isConnected) throw readerContext.readerAbortError();
@@ -220,6 +272,7 @@ export function createReaderPdfRenderer(readerContext) {
           // Admit page reads too: getPage can demand ranges before canvas rendering.
           await readerContext.measurePdf(readerContext.acquirePdfRenderSlot(priority, shell, signal), "queue", Number(shell.dataset.page));
           acquired = true;
+          admittedAt = performance.now();
           shell._pdfRenderOwnsSlot = true;
         }
         if (signal.aborted || !shell.isConnected) throw readerContext.readerAbortError();
@@ -247,18 +300,20 @@ export function createReaderPdfRenderer(readerContext) {
           canvas.width = canvas.height = 0;
           continue;
         }
-        const anchor = readerContext.content.querySelector(`.reader-page[data-page="${readerContext.documentState.page}"]`);
-        const oldTop = anchor?.getBoundingClientRect().top;
-        const oldHeight = anchor?.getBoundingClientRect().height || 1;
-        const fraction = anchor ? Math.max(0, (readerContext.viewport.getBoundingClientRect().top - oldTop) / oldHeight) : 0;
-        const previous = shell.querySelector("canvas");
-        canvas.classList.add("ready");
-        if (previous) { previous.replaceWith(canvas); previous.width = previous.height = 0; }
-        else shell.prepend(canvas);
-        shell.style.aspectRatio = `${base.width} / ${base.height}`;
-        shell._renderCancel?.();
-        shell.querySelector("img")?.remove();
-        shell._v3PreviewRelease?.();
+        const ready = canvas;
+        readerContext.applyPdfShellGeometry(() => {
+          const previous = shell.querySelector("canvas");
+          ready.classList.add("ready");
+          if (previous) { previous.replaceWith(ready); previous.width = previous.height = 0; }
+          else shell.prepend(ready);
+          shell.style.aspectRatio = `${base.width} / ${base.height}`;
+          shell.dataset.pageGeometry = "1";
+          shell._renderCancel?.();
+          shell.querySelector("img")?.remove();
+          shell._v3PreviewRelease?.();
+          readerContext.seedPdfPageGeometry?.(base.width, base.height);
+        });
+        if (admittedAt) readerContext.notePdfLatency("pdf", performance.now() - admittedAt);
         const pageState = shell.querySelector(".reader-page-state");
         if (pageState) pageState.hidden = true;
         shell.dataset.pdfPresented = "1";
@@ -267,10 +322,6 @@ export function createReaderPdfRenderer(readerContext) {
         delete shell.dataset.renderRetries;
         delete shell.dataset.renderFailed;
         shell.dataset.renderUsedAt = String(Date.now());
-        if (anchor) {
-          const current = anchor.getBoundingClientRect();
-          readerContext.viewport.scrollTop += current.top - oldTop + fraction * (current.height - oldHeight);
-        }
         readerContext.pdfShellWindow?.remember(shell);
         readerContext.trimPdfCanvases(shell);
         (readerContext.ocrManifestUrl ? readerContext.renderPdfOcrText(shell) : readerContext.renderPdfText(page, shell, signal)).catch(() => {});
@@ -293,7 +344,6 @@ export function createReaderPdfRenderer(readerContext) {
     if (!force && shell.dataset.renderState === "rendered") return Promise.resolve();
     shell.dataset.renderState = "rendering";
     const renderController = new AbortController();
-    const hybridPreview = !!readerContext.pdfHybridUrl;
     shell._renderCancel = () => renderController.abort();
     shell._renderStarted = false;
     priority = readerContext.normalizePdfPriority(priority || readerContext.pdfPagePriority(shell));
@@ -301,15 +351,11 @@ export function createReaderPdfRenderer(readerContext) {
     const task = (async () => {
       let acquired = false;
       try {
-        if (hybridPreview) {
-          while (readerContext.pdfHybridPreviewLoads >= 2) {
-            await readerContext.waitForReader(25);
-            if (renderController.signal.aborted) throw readerContext.readerAbortError();
-          }
-          if (renderController.signal.aborted) throw readerContext.readerAbortError();
-          readerContext.pdfHybridPreviewLoads++;
-        } else await readerContext.acquirePdfRenderSlot(priority, shell, renderController.signal);
+        // Page images are network-bound, not canvas work: they use their own
+        // priority-ordered pool, where visible demand preempts speculation.
+        await readerContext.measurePdf(readerContext.acquirePdfPreviewSlot(priority, shell, renderController.signal), "queue", Number(shell.dataset.page));
         acquired = true;
+        const admittedAt = performance.now();
         shell._renderStarted = true;
         readerContext.assertReaderActive();
          const entry = readerContext.pdfPageEntry(Number(shell.dataset.page));
@@ -352,13 +398,20 @@ export function createReaderPdfRenderer(readerContext) {
                Math.abs((image.naturalWidth / image.naturalHeight) / (geometry.width / geometry.height) - 1) > .01)
              throw new Error("PDF_V3_PREVIEW_GEOMETRY_MISMATCH");
          }
-         shell.style.aspectRatio = `${image.naturalWidth || 1} / ${image.naturalHeight || 1}`;
-         if (priority >= 2 && readerContext.ocrManifestUrl && !navigator.connection?.saveData)
-           loadText ||= readerContext.renderPdfOcrText(shell);
+        readerContext.notePdfLatency("preview", performance.now() - admittedAt);
+        readerContext.applyPdfShellGeometry(() => {
+          shell.style.aspectRatio = `${image.naturalWidth || 1} / ${image.naturalHeight || 1}`;
+          shell.dataset.pageGeometry = "1";
+          image.classList.add("ready");
+          readerContext.seedPdfPageGeometry?.(image.naturalWidth, image.naturalHeight);
+        });
+        if (priority >= 2 && readerContext.ocrManifestUrl && !navigator.connection?.saveData)
+          loadText ||= readerContext.renderPdfOcrText(shell);
         loadText?.catch(() => {});
-         image.classList.add("ready");
-         if (pageState) pageState.hidden = true;
-         shell.dataset.renderState = "rendered";
+        if (pageState) pageState.hidden = true;
+        shell.dataset.renderState = "rendered";
+        delete shell.dataset.renderRetries;
+        delete shell.dataset.renderFailed;
         shell.dataset.renderUsedAt = String(Date.now());
         readerContext.pdfShellWindow?.remember(shell);
         if (readerContext.isPdfPageVisible(shell) || !readerContext.pdfManifestPrefetchOrigin) readerContext.schedulePdfManifestPrefetch(entry.page);
@@ -376,10 +429,7 @@ export function createReaderPdfRenderer(readerContext) {
         shell.dataset.renderState = "idle";
         throw error;
       } finally {
-        if (acquired) {
-          if (hybridPreview) readerContext.pdfHybridPreviewLoads--;
-          else readerContext.releasePdfRenderSlot();
-        }
+        if (acquired) readerContext.releasePdfPreviewSlot(shell);
       }
     })().finally(() => {
       if (shell._renderPromise === task) delete shell._renderPromise;
@@ -489,6 +539,10 @@ export function createReaderPdfRenderer(readerContext) {
     renderPdfManifestShell,
     renderHybridPdfCanvas,
     renderPdfImageShell,
-    renderPdfShell
+    renderPdfShell,
+    resetPdfLatencySamples,
+    notePdfLatency,
+    pdfHybridPreviewGrace,
+    applyPdfShellGeometry
   };
 }

static/reader/pdf/reader-pdf-scheduler.mjs

@@ -1,5 +1,9 @@
 export function createReaderPdfScheduler(readerContext) {
   let pdfVisibleReconcileFrame = 0;
+  // Page-image admission (PDF-pages previews and image streams). Separate from
+  // canvas render slots so an image download never delays a PDF.js draw.
+  const PDF_PREVIEW_SLOTS = 2;
+  const pdfPreviewActive = new Map(), pdfPreviewWaiters = [];
   let pdfMotionAt = 0, pdfFastUntil = 0;
 
   function notePdfViewportMotion() {
@@ -153,7 +157,8 @@ export function createReaderPdfScheduler(readerContext) {
       if (readerContext.readerAbortController.signal.aborted || document.hidden || !navigator.onLine ||
           readerContext.pdfManifestPrefetchActive.size >= readerContext.pdfManifestPrefetchConcurrency() ||
           readerContext.pdfManifestPrefetchCount >= readerContext.pdfManifestPrefetchMaxPages() ||
-          (readerContext.pdfActiveRenders && readerContext.content.querySelector('.reader-page[data-render-visible="1"][data-render-state="rendering"]'))) return;
+          ((readerContext.pdfActiveRenders || pdfPreviewActive.size) &&
+            readerContext.content.querySelector('.reader-page[data-render-visible="1"][data-render-state="rendering"]'))) return;
       while (readerContext.pdfManifestPrefetchActive.size < readerContext.pdfManifestPrefetchConcurrency()) {
         if (readerContext.pdfManifestPrefetchCount >= readerContext.pdfManifestPrefetchMaxPages()) return;
         if (readerContext.pdfManifestPrefetchWrapped && readerContext.pdfManifestPrefetchNext >= readerContext.pdfManifestPrefetchOrigin) return;
@@ -240,6 +245,93 @@ export function createReaderPdfScheduler(readerContext) {
     for (const waiter of readerContext.pdfRenderWaiters) {
       if (waiter.shell === shell) waiter.priority = Math.max(waiter.priority, readerContext.pdfPagePriority(shell));
     }
+    for (const waiter of pdfPreviewWaiters) {
+      if (waiter.shell !== shell) continue;
+      waiter.priority = Math.max(waiter.priority, readerContext.pdfPagePriority(shell));
+      preemptPdfPreview(waiter.priority, shell);
+    }
+  }
+
+  // Index of the waiter to admit next: live priority first, then the nearest
+  // page, with pages behind the scroll direction counted at twice the distance.
+  function nextPdfWaiterIndex(waiters) {
+    let index = -1, best = -1, nearest = Infinity;
+    const bounds = readerContext.viewport.getBoundingClientRect();
+    for (let i = 0; i < waiters.length; i++) {
+      const waiter = waiters[i], value = waiter.shell ? readerContext.pdfPagePriority(waiter.shell) : waiter.priority;
+      const rect = waiter.shell?.getBoundingClientRect();
+      const gap = rect ? Math.max(bounds.top - rect.bottom, rect.top - bounds.bottom, 0) : Infinity;
+      const behind = rect && (readerContext.pdfScrollDirection < 0 ? rect.top >= bounds.bottom : rect.bottom <= bounds.top);
+      const distance = gap * (behind ? 2 : 1);
+      if (value > best || (value === best && distance < nearest)) {
+        best = value; nearest = distance; index = i;
+      }
+    }
+    return index < 0 ? 0 : index;
+  }
+
+  // Visible demand must not wait behind speculative image downloads: cancel
+  // the least useful offscreen holder; its page is requeued if it is needed.
+  function preemptPdfPreview(priority, shell) {
+    if (priority < 2 || pdfPreviewActive.size < PDF_PREVIEW_SLOTS) return false;
+    let victim = null, lowest = Infinity;
+    for (const [holder, entry] of pdfPreviewActive) {
+      if (holder === shell || readerContext.isPdfPageVisible(holder) || readerContext.pdfSelectionIntersects?.(holder)) continue;
+      const value = readerContext.pdfPagePriority(holder);
+      if (value < lowest) { lowest = value; victim = entry; }
+    }
+    if (!victim || lowest >= 2) return false;
+    victim.shell._pdfRenderCancelled = true;
+    victim.shell._pdfRenderNeedsRequeue = true;
+    victim.cancel();
+    return true;
+  }
+
+  function acquirePdfPreviewSlot(priority = false, shell = null, signal = null) {
+    if (readerContext.readerAbortController.signal.aborted || signal?.aborted)
+      return Promise.reject(readerContext.readerAbortError());
+    priority = readerContext.normalizePdfPriority(priority);
+    const admit = () => {
+      pdfPreviewActive.set(shell, { shell, cancel: () => shell?._renderCancel?.() });
+    };
+    if (pdfPreviewActive.size < PDF_PREVIEW_SLOTS && !pdfPreviewWaiters.length) {
+      admit();
+      return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      const lifetime = signal ? AbortSignal.any([signal, readerContext.readerAbortController.signal])
+        : readerContext.readerAbortController.signal;
+      const waiter = {
+        shell, priority,
+        resolve: () => { lifetime.removeEventListener("abort", abort); admit(); resolve(); }
+      };
+      function abort() {
+        const index = pdfPreviewWaiters.indexOf(waiter);
+        if (index >= 0) pdfPreviewWaiters.splice(index, 1);
+        reject(readerContext.readerAbortError());
+        drainPdfPreviewWaiters();
+      }
+      lifetime.addEventListener("abort", abort, { once: true });
+      pdfPreviewWaiters.push(waiter);
+      if (!preemptPdfPreview(priority, shell)) drainPdfPreviewWaiters();
+    });
+  }
+
+  function drainPdfPreviewWaiters() {
+    // Disposal rejects each waiter through its own abort listener.
+    if (readerContext.readerAbortController.signal.aborted) return;
+    while (pdfPreviewActive.size < PDF_PREVIEW_SLOTS && pdfPreviewWaiters.length)
+      pdfPreviewWaiters.splice(nextPdfWaiterIndex(pdfPreviewWaiters), 1)[0].resolve();
+  }
+
+  function releasePdfPreviewSlot(shell) {
+    pdfPreviewActive.delete(shell);
+    drainPdfPreviewWaiters();
+    scheduleVisiblePdfRenderReconciliation();
+  }
+
+  function pdfPreviewLoads() {
+    return pdfPreviewActive.size;
   }
 
   function acquirePdfRenderSlot(priority = false, shell = null, signal = null) {
@@ -291,19 +383,7 @@ export function createReaderPdfScheduler(readerContext) {
   function releasePdfRenderSlot() {
     readerContext.pdfActiveRenders = Math.max(0, readerContext.pdfActiveRenders - 1);
     if (readerContext.readerAbortController.signal.aborted) return;
-    let index = -1, best = -1, nearest = Infinity;
-    for (let i = 0; i < readerContext.pdfRenderWaiters.length; i++) {
-      const waiter = readerContext.pdfRenderWaiters[i], value = waiter.shell ? readerContext.pdfPagePriority(waiter.shell) : waiter.priority;
-      const rect = waiter.shell?.getBoundingClientRect(), bounds = readerContext.viewport.getBoundingClientRect();
-      const gap = rect ? Math.max(bounds.top - rect.bottom, rect.top - bounds.bottom, 0) : Infinity;
-      const behind = rect && (readerContext.pdfScrollDirection < 0 ? rect.top >= bounds.bottom : rect.bottom <= bounds.top);
-      const distance = gap * (behind ? 2 : 1);
-      if (value > best || (value === best && distance < nearest)) {
-        best = value; nearest = distance; index = i;
-      }
-    }
-    if (index < 0) index = 0;
-    const waiter = readerContext.pdfRenderWaiters.splice(index, 1)[0];
+    const waiter = readerContext.pdfRenderWaiters.splice(nextPdfWaiterIndex(readerContext.pdfRenderWaiters), 1)[0];
     if (waiter) waiter.resolve();
     scheduleVisiblePdfRenderReconciliation();
   }
@@ -413,6 +493,9 @@ export function createReaderPdfScheduler(readerContext) {
     promotePdfRenderWaiter,
     acquirePdfRenderSlot,
     releasePdfRenderSlot,
+    acquirePdfPreviewSlot,
+    releasePdfPreviewSlot,
+    pdfPreviewLoads,
     acquirePdfTextSlot,
     drainPdfTextWaiters,
     releasePdfTextSlot,

tests/test_async_proxy.py

@@ -643,6 +643,46 @@ class AsyncProxyTests(unittest.IsolatedAsyncioTestCase):
                 await app.api_reader_bucket_resource(path, SimpleNamespace(method="GET", headers={}))
         self.assertEqual(semaphore._value, 1)
 
+    async def test_large_pdf_admits_bounded_ranges_but_not_complete_bodies(self):
+        # PDF.js range transport reads demanded chunks of a large original PDF;
+        # complete or open-ended bodies keep the document bound.
+        large = app.READER_DOCUMENT_MAX_BYTES + 100
+        over = app.READER_PDF_RANGE_MAX_BYTES + 1
+        url = "https://huggingface.co/datasets/VoiceOfML/Test/resolve/main/large.pdf"
+        for forwarded, status, headers, expected in (
+            ({"Range": "bytes=0-1"}, 206, {"Content-Length": "2", "Content-Range": f"bytes 0-1/{large}"}, 206),
+            ({"Range": f"bytes={large - 2}-{large - 1}"}, 206,
+             {"Content-Length": "2", "Content-Range": f"bytes {large - 2}-{large - 1}/{large}"}, 206),
+            ({"Range": "bytes=0-1"}, 206, {"Content-Length": "2", "Content-Range": f"bytes 0-1/{over}"}, 413),
+            ({"Range": "bytes=0-"}, 206, {"Content-Length": "2", "Content-Range": f"bytes 0-1/{large}"}, 413),
+            ({}, 200, {"Content-Length": str(large)}, 413),
+        ):
+            for source in ("bucket", "original"):
+                with self.subTest(range=forwarded, total=headers.get("Content-Range"), source=source):
+                    upstream = FakeResponse(status, headers, chunks=(b"ab",))
+                    app.app.state.http_session = FakeSession([upstream])
+                    semaphore = app.app.state.upstream_semaphore = asyncio.Semaphore(1)
+                    app.app.state.reader_range_cache = OrderedDict()
+                    app.app.state.reader_range_cache_bytes = 0
+                    request = SimpleNamespace(method="GET", headers=forwarded)
+                    if source == "bucket":
+                        response = await app.api_reader_bucket_resource("derived/test/" + "a" * 32 + "/document.pdf", request)
+                    else:
+                        response = await app.api_reader_content(request, url=url, id=None)
+                    self.assertEqual(response.status_code, expected)
+                    if expected == 206:
+                        self.assertEqual(b"".join([chunk async for chunk in response.body_iterator]), b"ab")
+                        self.assertEqual(response.headers["Cache-Control"], "no-store")
+                    self.assertTrue(upstream.released)
+                    self.assertEqual(semaphore._value, 1)
+        # Non-PDF documents retain the ordinary total bound for ranges too.
+        upstream = FakeResponse(206, {"Content-Length": "2", "Content-Range": f"bytes 0-1/{large}"}, chunks=(b"ab",))
+        app.app.state.http_session = FakeSession([upstream])
+        app.app.state.upstream_semaphore = asyncio.Semaphore(1)
+        response = await app.api_reader_content(SimpleNamespace(method="GET", headers={"Range": "bytes=0-1"}),
+                                                url="https://huggingface.co/datasets/VoiceOfML/Test/resolve/main/large.txt", id=None)
+        self.assertEqual(response.status_code, 413)
+
     async def test_bucket_pdf_redirect_cannot_switch_to_another_hf_source(self):
         path = "derived/test/" + "a" * 32 + "/document.pdf"
         redirect = FakeResponse(302, {"Location": "https://huggingface.co/datasets/Other/Private/resolve/main/book.pdf"})

tests/test_reader_pdf_hybrid.py

@@ -27,7 +27,10 @@ export function getDocument(options) {
     stream: options.disableStream, auto: options.disableAutoFetch};
   let finish;
   const promise = new Promise(resolve => { finish = resolve; });
-  const pdf = { numPages: window.__wrongCount ? 79 : 80, getOutline: async () => null,
+  const pdf = { numPages: window.__wrongCount ? 79 : 80,
+    getOutline: async () => { window.__outlineReads = (window.__outlineReads || 0) + 1; return window.__outline || null; },
+    getDestination: async name => [{num: Number(name.slice(1))}],
+    getPageIndex: async ref => ref.num - 1,
     getPage: async number => ({
       getViewport: ({scale}) => ({width: 600*scale, height: 800*scale}),
       getTextContent: async () => ({items: [{str:'hybrid searchable page '+number,
@@ -90,8 +93,10 @@ class HybridPdfTests(unittest.TestCase):
     def asset(self, route):
         path = parse_qs(urlparse(route.request.url).query)["path"][0]
         if path.endswith("page-manifest.json"):
-            route.fulfill(content_type="application/json", body=json.dumps(
-                {"version": 2, "kind": "pdf-pages", "page_count": self.page_count}))
+            manifest = {"version": 2, "kind": "pdf-pages", "page_count": self.page_count}
+            if getattr(self, "manifest_toc", None):
+                manifest["toc"] = self.manifest_toc
+            route.fulfill(content_type="application/json", body=json.dumps(manifest))
         else:
             self.images.append(int(path.split("page-")[-1].split(".")[0]))
             if self.svg_preview:
@@ -251,6 +256,47 @@ class HybridPdfTests(unittest.TestCase):
         self.assertEqual(self.page.locator(".reader-error").count(), 0)
         self.assertEqual(self.errors, [])
 
+    def test_failed_primary_leaves_hybrid_mode_for_prioritized_image_pages(self):
+        self.page.add_init_script("window.__wrongCount=true")
+        self.open()
+        self.page.evaluate("window.__releaseDocument()")
+        self.page.wait_for_function("() => !document.querySelector('.reader-page[data-pdf-hybrid]')")
+        self.images.clear()
+        self.jump(60)
+        shell = self.page.locator('.reader-page[data-page="60"]')
+        # The visible page is an ordinary image page: no hybrid grace/limiter.
+        shell.locator("img.ready").wait_for(timeout=3000)
+        self.assertIn(60, self.images)
+        # Ordinary manifest prefetch resumes once hybrid mode is left.
+        self.page.wait_for_function("() => document.querySelectorAll('.reader-page img').length > 1")
+        self.assertEqual(self.page.locator(".reader-page canvas.ready").count(), 0)
+        self.assertEqual(self.page.evaluate("window.__renders.length"), 0)
+        self.assertEqual(self.page.locator(".reader-error").count(), 0)
+        self.assertEqual(self.errors, [])
+
+    def test_hybrid_outline_fills_missing_manifest_toc_after_first_page(self):
+        self.page.add_init_script("window.__outline=[{title:'第一章', dest:'p3', items:[{title:'第一节', dest:[{num:4}], items:[]}]},{title:'第二章', dest:'p40', items:[]}]")
+        self.open()
+        self.assertEqual(self.page.evaluate("window.__outlineReads || 0"), 0)
+        self.page.evaluate("window.__releaseDocument()")
+        self.page.wait_for_function("() => document.querySelectorAll('#toc-list .toc-item').length === 3")
+        labels = self.page.locator("#toc-list .toc-item .panel-item-main").all_inner_texts()
+        self.assertEqual([label.strip() for label in labels], ["第一章 · 第 3 页", "第一节 · 第 4 页", "第二章 · 第 40 页"])
+        self.page.locator("#toc-list .toc-item").nth(2).locator(".panel-item-main").click()
+        self.page.wait_for_function("() => document.querySelector('#page-number').value === '40'")
+        self.assertEqual(self.errors, [])
+
+    def test_manifest_toc_is_not_replaced_by_pdf_outline(self):
+        self.manifest_toc = [{"title": "清单目录", "page": 2, "depth": 0}]
+        self.page.add_init_script("window.__outline=[{title:'PDF 书签', dest:'p3', items:[]}]")
+        self.open()
+        self.page.evaluate("window.__releaseDocument()")
+        self.page.locator('.reader-page[data-page="1"] canvas.ready').wait_for()
+        self.page.wait_for_timeout(200)
+        self.assertEqual(self.page.evaluate("window.__outlineReads || 0"), 0)
+        self.assertEqual([t.strip() for t in self.page.locator("#toc-list .toc-item .panel-item-main").all_inner_texts()], ["清单目录 · 第 2 页"])
+        self.assertEqual(self.errors, [])
+
     def test_disposal_cancels_pending_pdf_without_late_canvas(self):
         shell = self.open()
         self.page.evaluate("window.dispatchEvent(new Event('pagehide'))")

tests/test_reader_pdf_range_transport.mjs

@@ -219,6 +219,24 @@ try {
   }
   await assert.rejects(open(async()=>response([1,2,3,4],[0,3,128])),/READER_RESOURCE_LIMIT/);
   await assert.rejects(open(async()=>new Response(new Uint8Array(65))),/READER_RESOURCE_LIMIT/);
+  {
+    // Range transport may admit a larger validated total (demanded chunks
+    // only); complete bodies, totals beyond rangeLimit and the default stay bounded.
+    const ranged=async(total)=>{
+      calls.length=0;globalThis.fetch=async()=>response([1,2,3,4],[0,3,total]);
+      const task=await openPdfRangeTask(pdfjs,options,{signal:new AbortController().signal,readBytes,limit:64,rangeLimit:128,rangeCache:null});
+      return task.promise;
+    };
+    const large=await ranged(100);
+    assert.equal(large.range.length,100,'a range-read total above the body limit opens');
+    await assert.rejects(ranged(129),/READER_RESOURCE_LIMIT/);
+    await assert.rejects(open(async()=>response([1,2,3,4],[0,3,100])),/READER_RESOURCE_LIMIT/,'without rangeLimit the body limit applies');
+    globalThis.fetch=async()=>new Response(new Uint8Array(65));
+    await assert.rejects(openPdfRangeTask(pdfjs,options,{signal:new AbortController().signal,readBytes,limit:64,rangeLimit:128,rangeCache:null}),
+      /READER_RESOURCE_LIMIT/,'a complete body keeps the body limit');
+    assert.equal(globalThis.VoiceOfMLReaderSecurity.LIMITS.documentBytes,512*1024*1024);
+    assert.equal(globalThis.VoiceOfMLReaderSecurity.LIMITS.pdfRangeDocumentBytes,1024*1024*1024);
+  }
   await assert.rejects(open(async()=>new Response('missing',{status:404})),error=>error.status===404);
 
   const failures=[];

tests/test_reader_pdf_scroll_scheduling.mjs

@@ -9,6 +9,7 @@ const load = name => import(pathToFileURL(path.join(root, "static/reader", name)
 const { createReaderPdfScheduler } = await load("pdf/reader-pdf-scheduler.mjs");
 const { createReaderPdfRenderer } = await load("pdf/reader-pdf-renderer.mjs");
 const { createReaderLifecycle } = await load("core/reader-lifecycle.mjs");
+const { createReaderPdfPageWindow } = await load("pdf/reader-pdf-page-window.mjs");
 const tick = () => new Promise(resolve => setImmediate(resolve));
 const deferred = () => { let resolve; const promise = new Promise(done => { resolve = done; }); return { promise, resolve }; };
 globalThis.window = { devicePixelRatio: 1 };
@@ -88,6 +89,7 @@ for (const outcome of ["promoted", "pdf", "cancelled"]) {
   reader.pdfDocument = {};
   reader.pdfHybridDocumentPromise = Promise.resolve(reader.pdfDocument);
   reader.PDF_HYBRID_DOCUMENT_GRACE_MS = 5000;
+  reader.pdfHybridPreviewGrace = () => 150;
   reader.renderHybridPdfCanvas = () => pdf.promise;
   let previews = 0;
   reader.renderPdfImageShell = async () => { previews++; };
@@ -114,33 +116,125 @@ for (const outcome of ["promoted", "pdf", "cancelled"]) {
   assert.equal(reader.readerResources.size, 0);
 }
 {
-  const nativePerformance=globalThis.performance;
-  let clock=1000;
-  Object.defineProperty(globalThis,'performance',{configurable:true,value:{now:()=>clock}});
+  // After document readiness the visible-page image is a fallback for a
+  // genuinely slow draw: the grace follows this book's measured latencies and
+  // starts only once the page is visible (fast fly-past starts no image).
+  const reader=context(true);
+  assert.equal(reader.pdfHybridPreviewGrace(),1600,'unmeasured books wait twice the default PDF draw');
+  for (const ms of [500,700,600]) reader.notePdfLatency('pdf',ms);
+  assert.equal(reader.pdfHybridPreviewGrace(),1200);
+  for (const ms of [2400,2300]) reader.notePdfLatency('preview',ms);
+  assert.equal(reader.pdfHybridPreviewGrace(),1200,'slower images keep the PDF-first grace');
+  reader.resetPdfLatencySamples();
+  for (const ms of [2600,2400]) reader.notePdfLatency('pdf',ms);
+  for (const ms of [300,250]) reader.notePdfLatency('preview',ms);
+  assert.equal(reader.pdfHybridPreviewGrace(),150,'measurably faster images keep the short fallback');
+  reader.resetPdfLatencySamples();
+  for (const ms of [9000,9000,9000]) reader.notePdfLatency('pdf',ms);
+  assert.equal(reader.pdfHybridPreviewGrace(),3000,'the grace is bounded');
+  const target=shell(2,5000),hold=deferred(),waits=[];let previews=0;
+  reader.pdfHybridUrl='https://fixture.test/document.pdf';reader.pdfDocument={};
+  reader.pdfHybridDocumentPromise=Promise.resolve(reader.pdfDocument);
+  reader.renderHybridPdfCanvas=()=>hold.promise;
+  reader.renderPdfImageShell=async()=>{previews++;};
+  reader.waitForReader=ms=>{waits.push(ms);return new Promise(resolve=>setTimeout(resolve,1));};
+  reader.pdfHybridPreviewGrace=()=>777;
+  const task=reader.renderPdfManifestShell(target,false,1);
+  await new Promise(resolve=>setTimeout(resolve,30));
+  assert.equal(waits.includes(777),false,'the grace does not run while the page is offscreen');
+  target.getBoundingClientRect=()=>({top:0,bottom:200});
+  await task;
+  assert.equal(waits.includes(777),true);
+  assert.equal(previews,1);
+  hold.resolve();await target._hybridRenderPromise;
+}
+{
+  // Page images use a priority-ordered pool: visible demand is admitted first
+  // and preempts speculative holders instead of polling behind them.
+  const reader=context(false),admitted=[],cancelled=[];
+  const make=(page,top)=>{const s=shell(page,top);s._renderCancel=()=>{cancelled.push(page);};return s;};
+  const far1=make(40,6000),far2=make(41,6200),near=make(3,900),visible=make(2,100);
+  await reader.acquirePdfPreviewSlot(1,far1);await reader.acquirePdfPreviewSlot(1,far2);
+  assert.equal(reader.pdfPreviewLoads(),2);
+  const queuedNear=reader.acquirePdfPreviewSlot(1,near).then(()=>admitted.push(3));
+  const queuedVisible=reader.acquirePdfPreviewSlot(3,visible).then(()=>admitted.push(2));
+  await tick();
+  assert.deepEqual(cancelled,[40],'visible demand cancels one speculative image download');
+  assert.equal(far1._pdfRenderNeedsRequeue,true,'a preempted page is requeued when needed');
+  reader.releasePdfPreviewSlot(far1);await tick();
+  assert.deepEqual(admitted,[2],'the visible page is admitted before an earlier speculative waiter');
+  reader.releasePdfPreviewSlot(far2);await tick();
+  assert.deepEqual(admitted,[2,3]);
+  const abort=new AbortController();
+  const dropped=reader.acquirePdfPreviewSlot(1,make(50,9000),abort.signal);
+  abort.abort();await assert.rejects(dropped,{name:'AbortError'});
+  reader.releasePdfPreviewSlot(visible);reader.releasePdfPreviewSlot(near);
+  assert.equal(reader.pdfPreviewLoads(),0);
+  // Disposal rejects waiters.
+  await reader.acquirePdfPreviewSlot(1,far1);await reader.acquirePdfPreviewSlot(1,far2);
+  const pending=reader.acquirePdfPreviewSlot(1,make(60,9000));
+  reader.readerAbortController.abort();
+  await assert.rejects(pending,{name:'AbortError'});
+}
+{
+  // Geometry changes (image natural size, canvas swap) keep the reading anchor.
+  const reader=context(false);
+  let height=566,top=-200;
+  const anchor={isConnected:true,getBoundingClientRect:()=>({top,height,bottom:top+height})};
+  reader.documentState.page=7;
+  reader.content={querySelector:selector=>selector.includes('"7"')?anchor:null};
+  reader.viewport.scrollTop=5000;
+  reader.applyPdfShellGeometry(()=>{top+=12;height=569;});
+  assert.ok(Math.abs(reader.viewport.scrollTop-(5000+12+(200/566)*3))<1e-9,'shift above and growth of the anchor are compensated');
+  reader.viewport.scrollTop=5000;
+  reader.applyPdfShellGeometry(()=>{});
+  assert.equal(reader.viewport.scrollTop,5000,'no geometry change means no scroll write');
+}
+for (const late of [false, true]) {
+  // A failed primary PDF leaves hybrid mode cleanly: no PDF-preview race or
+  // hybrid limiter remains, shells requeue as ordinary prioritized image pages,
+  // manifest prefetch resumes and the failed document is never reopened.
+  const reader=context(false),loads=[],reconciled=[],prefetched=[],destroyed=[];
+  const shells=[1,2].map(n=>({...shell(n,0),dataset:{page:String(n),pdfHybrid:'1',renderState:n===1?'rendered':'idle'}}));
+  Object.assign(reader,createReaderPdfPageWindow(reader),{
+    capability:{mode:'pdf-pages'},readerLifecycle:{disposed:false},pdfV3Manifest:null,pdfV3Map:null,
+    content:{querySelector:()=>null,querySelectorAll:()=>shells},
+    pdfPrimarySource:()=> 'https://fixture.test/primary.pdf',
+    syncCapabilityControls(){},clearPdfManifestPrefetches(){},cancelSpeculativePdfRenders(){},
+    scheduleVisiblePdfRenderReconciliation:force=>reconciled.push(force),
+    schedulePdfManifestPrefetch:page=>prefetched.push(page),
+    documentState:{page:2},
+    loadPdfDocument:url=>{loads.push(url);return late
+      ? Promise.resolve({numPages:2,destroy:()=>{destroyed.push(1);return Promise.resolve();}})
+      : Promise.reject(new Error('READER_RESOURCE_LIMIT'));}
+  });
+  const warn=console.warn;console.warn=()=>{};
   try {
-    const reader=context(true);
-    reader.capability={mode:'pdf-pages'};reader.documentState.restorationReady=true;
-    reader.viewport.clientHeight=800;reader.pdfLastScrollTop=0;reader.viewport.scrollTop=260;
-    reader.notePdfViewportMotion();
-    assert.equal(reader.pdfScrollActivity(),true);
-    assert.equal(reader.pdfScrollActivity(true),false,'ordinary movement must keep normal draw grace');
-    clock+=35;reader.pdfLastScrollTop=260;reader.viewport.scrollTop=2060;
-    reader.notePdfViewportMotion();
-    assert.equal(reader.pdfScrollActivity(true),true,'a genuine fast viewport movement enables immediate visible fallback');
-    for (const [delta,expected] of [[0,0],[161,150]]) {
-      clock+=delta;
-      const hold=deferred(),target=shell(2,0),waits=[];
-      reader.pdfHybridUrl='https://fixture.test/document.pdf';reader.pdfDocument={};
-      reader.pdfHybridDocumentPromise=Promise.resolve(reader.pdfDocument);
-      reader.renderHybridPdfCanvas=()=>hold.promise;
-      reader.renderPdfImageShell=async()=>{};
-      reader.waitForReader=async ms=>{waits.push(ms);};
-      const task=reader.renderPdfManifestShell(target,false,3);
-      await task;
-      assert.equal(waits.at(-1),expected,'only recent fast motion may shorten the visible-page grace');
-      hold.resolve();await target._hybridRenderPromise;
+    reader.startPdfHybridDocument(2);
+    assert.equal(reader.pdfHybridUrl,'https://fixture.test/primary.pdf');
+    await reader.pdfHybridDocumentPromise.catch(()=>{});await tick();
+    if (late) {
+      assert.ok(reader.pdfDocument,'a ready primary is used');
+      reader.leavePdfHybridMode(undefined,new Error('PDF_RANGE_INVALID'));
+      assert.deepEqual(destroyed,[1],'a late transport failure releases the document');
     }
-  } finally {Object.defineProperty(globalThis,'performance',{configurable:true,value:nativePerformance});}
+    assert.equal(reader.pdfHybridUrl,'','failure leaves hybrid mode');
+    assert.equal(reader.pdfDocument,null);
+    assert.equal(reader.pdfHybridSearchUnavailable,true);
+    assert.equal(shells.some(s=>s.dataset.pdfHybrid),false);
+    assert.equal(shells[1]._pdfRenderNeedsRequeue,true,'unrendered pages requeue through the image pool');
+    assert.equal(shells[0]._pdfRenderNeedsRequeue,undefined);
+    assert.deepEqual(reconciled,[true]);
+    assert.deepEqual(prefetched,[2],'ordinary manifest prefetch resumes');
+    reader.pdfHybridDocumentPromise=null;
+    reader.startPdfHybridDocument(2);
+    assert.deepEqual(loads,['https://fixture.test/primary.pdf'],'a failed primary is not reopened for this book');
+    assert.equal(reader.pdfHybridUrl,'');
+    // The image path no longer enters the PDF race.
+    let images=0;reader.renderPdfImageShell=async()=>{images++;};
+    await reader.renderPdfManifestShell(shells[1],false,3);
+    assert.equal(images,1);
+  } finally {console.warn=warn;}
 }
 {
   // DjVu primary: the manifest validates, its primary is never handed to PDF.js,
@@ -191,4 +285,4 @@ for (const outcome of ["promoted", "pdf", "cancelled"]) {
   assert.match(reader.pdfPrimarySource(), /document\.pdf$/);
   delete globalThis.VoiceOfMLReader;
 }
-console.log("PDF scroll scheduling: bounded reads, live demand/fallback promotion, motion grace, cancellation and directional neighbors passed", root);
+console.log("PDF scroll scheduling: bounded reads, live demand/fallback promotion, adaptive grace, visible-priority image admission, anchor-preserving geometry, hybrid fallback, cancellation and directional neighbors passed", root);