feat(pdf-server): lazy range-based loading + eager background preloading (#480)

* lazy PDF loading w/ PDFDataRangeTransport

* lint

* feat: lazy PDF loading via range transport + eager background preloading

Replace full-file download with PDFDataRangeTransport so PDF.js fetches
byte ranges on demand. First page renders immediately; remaining pages
load in background for search.

**Range transport (server + client)**
- server.ts: add read_pdf_bytes tool returning base64 chunks with offset
- mcp-app.ts: AppRangeTransport feeds PDF.js via fetchRange/fetchChunk
  with parallel sub-requests for large ranges, Promise-based dedup of
  concurrent requests, and a persistent range cache

**Background preloader**
- Sequential page 1→N text extraction, pauses during interactive
  navigation (preloadPaused flag set in goToPage, cleared in renderPage)
- Debounced live search refresh (500ms) as pages load
- Search UI shows '(loading…)' suffix until all pages processed

**Loading indicators**
- SVG pie in toolbar: fills as pages load, fades on completion,
  turns red on errors with tooltip listing failed pages
- Debounced page-loading overlay (150ms) for uncached page navigation

**Cleanup**
- Remove old full-file chunked download and progress bar
- Remove extractAllPageText (replaced by preloader)
- Remove verbose debug logs (Coverage, RangeReq, cache hit)

Author: ochafik

examples/pdf-server/mcp-app.html

@@ -11,14 +11,6 @@
       <div id="loading" class="loading">
         <div class="spinner"></div>
         <p id="loading-text">Loading PDF...</p>
-        <div
-          id="progress-container"
-          class="progress-container"
-          style="display: none"
-        >
-          <div id="progress-bar" class="progress-bar"></div>
-        </div>
-        <p id="progress-text" class="progress-text"></p>
       </div>
 
       <!-- Error State -->
@@ -33,6 +25,13 @@
         <div class="toolbar">
           <div class="toolbar-left">
             <span id="pdf-title" class="pdf-title">Document</span>
+            <div id="loading-indicator" class="loading-indicator" style="display: none"
+                 title="Loading pages...">
+              <svg viewBox="0 0 20 20" width="14" height="14">
+                <circle class="loading-indicator-bg" cx="10" cy="10" r="8"/>
+                <circle class="loading-indicator-arc" cx="10" cy="10" r="8"/>
+              </svg>
+            </div>
           </div>
           <div class="toolbar-center">
             <button id="prev-btn" class="nav-btn" title="Previous page (←)">

examples/pdf-server/server.test.ts

@@ -131,6 +131,33 @@ describe("PDF Cache with Timeouts", () => {
       }
     });
 
+    it("should fall back to GET when server returns 501 for Range request", async () => {
+      const fullData = new Uint8Array([0x25, 0x50, 0x44, 0x46, 0x2d]); // %PDF-
+
+      const mockFetch = spyOn(globalThis, "fetch")
+        // First call: Range request returns 501
+        .mockResolvedValueOnce(
+          new Response("Unsupported client Range", { status: 501 }),
+        )
+        // Second call: plain GET returns full body
+        .mockResolvedValueOnce(
+          new Response(fullData, {
+            status: 200,
+            headers: { "Content-Type": "application/pdf" },
+          }),
+        );
+
+      try {
+        const result = await pdfCache.readPdfRange(testUrl, 0, 1024);
+        expect(result.data).toEqual(fullData);
+        expect(result.totalBytes).toBe(fullData.length);
+        expect(pdfCache.getCacheSize()).toBe(1);
+        expect(mockFetch).toHaveBeenCalledTimes(2);
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
     it("should reject PDFs larger than max size limit", async () => {
       const hugeUrl = "https://arxiv.org/pdf/huge-pdf";
       // Create data larger than the limit

examples/pdf-server/server.ts

@@ -292,17 +292,21 @@ export function createPdfCache(): PdfCache {
       return sliceToChunk(cached, offset, clampedByteCount);
     }
 
-    // Remote URL - Range request
-    const response = await fetch(normalized, {
+    // Remote URL - try Range request, fall back to full GET if not supported
+    let response = await fetch(normalized, {
       headers: {
         Range: `bytes=${offset}-${offset + clampedByteCount - 1}`,
       },
     });
 
+    // If server doesn't support Range (501, 416, etc.), fall back to plain GET
     if (!response.ok && response.status !== 206) {
-      throw new Error(
-        `Range request failed: ${response.status} ${response.statusText}`,
-      );
+      response = await fetch(normalized);
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch PDF: ${response.status} ${response.statusText}`,
+        );
+      }
     }
 
     // HTTP 200 means the server ignored our Range header and sent the full body.
@@ -551,6 +555,7 @@ Accepts:
       outputSchema: z.object({
         url: z.string(),
         initialPage: z.number(),
+        totalBytes: z.number(),
       }),
       _meta: { ui: { resourceUri: RESOURCE_URI } },
     },
@@ -565,11 +570,15 @@ Accepts:
         };
       }
 
+      // Probe file size so the client can set up range transport without an extra fetch
+      const { totalBytes } = await readPdfRange(normalized, 0, 1);
+
       return {
         content: [{ type: "text", text: `Displaying PDF: ${normalized}` }],
         structuredContent: {
           url: normalized,
           initialPage: page,
+          totalBytes,
         },
         _meta: {
           viewUUID: randomUUID(),

examples/pdf-server/src/mcp-app.css

@@ -68,28 +68,6 @@ body {
   color: var(--text100);
 }
 
-/* Progress Bar */
-.progress-container {
-  width: 100%;
-  max-width: 200px;
-  height: 3px;
-  background: var(--bg200);
-  border-radius: 2px;
-  overflow: hidden;
-}
-
-.progress-bar {
-  height: 100%;
-  background: var(--text100);
-  width: 0%;
-  transition: width 0.15s ease-out;
-}
-
-.progress-text {
-  font-size: 0.7rem;
-  color: var(--text200);
-}
-
 /* Error State */
 .error {
   display: flex;
@@ -138,6 +116,8 @@ body {
   flex: 1;
   min-width: 0;
   overflow: hidden;
+  display: flex;
+  align-items: center;
 }
 
 .pdf-title {
@@ -281,6 +261,47 @@ body {
   --min-font-size-inv: calc(1 / var(--min-font-size, 1));
 }
 
+/* Page Loading Overlay - shown while page data is being fetched */
+.page-loading-overlay {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(255, 255, 255, 0.9);
+  border-radius: 4px;
+  z-index: 10;
+}
+
+.page-loading-content {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.75rem;
+  padding: 1.5rem 2rem;
+  background: var(--bg000);
+  border: 1px solid var(--bg200);
+  border-radius: 8px;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
+}
+
+.page-loading-spinner {
+  width: 32px;
+  height: 32px;
+  border: 3px solid var(--bg200);
+  border-top-color: var(--text100);
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+
+.page-loading-text {
+  font-size: 0.85rem;
+  color: var(--text100);
+}
+
 .text-layer :is(span, br) {
   color: transparent;
   position: absolute;
@@ -460,3 +481,30 @@ body {
     mix-blend-mode: screen;
   }
 }
+
+/* Loading Indicator (pie) */
+.loading-indicator {
+  display: inline-flex;
+  align-items: center;
+  margin-left: 0.5rem;
+  flex-shrink: 0;
+  transition: opacity 0.3s;
+}
+.loading-indicator-bg {
+  fill: none;
+  stroke: var(--bg200);
+  stroke-width: 3;
+}
+.loading-indicator-arc {
+  fill: none;
+  stroke: var(--text100);
+  stroke-width: 3;
+  stroke-dasharray: 50.27; /* 2*pi*8 */
+  stroke-dashoffset: 50.27;
+  transform: rotate(-90deg);
+  transform-origin: center;
+  transition: stroke-dashoffset 0.3s;
+}
+.loading-indicator.error .loading-indicator-arc {
+  stroke: #e74c3c;
+}