pretext-pdfjs 0.3.3 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pretext-pdfjs",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Pretext-native text layer for PDF.js — zero DOM reflows, per-block reflow with image preservation, pinch-to-zoom text",
   "type": "module",
   "main": "./src/index.js",

package/src/pinch.js

@@ -392,6 +392,37 @@ export function createPDFPinchReader(container, options = {}) {
     }
   }
 
+  /**
+   * Find adaptive paragraph threshold by analyzing gap distribution.
+   */
+  function findParagraphThreshold(gaps, fontSize) {
+    if (gaps.length < 3) return 1.8;
+
+    // Filter out extreme outliers (>5x font size - likely headers, titles, etc.)
+    const filtered = gaps.filter(g => g / fontSize < 5);
+    if (filtered.length < 3) return 1.8;
+
+    const ratios = filtered.map(g => g / fontSize).sort((a, b) => a - b);
+
+    let maxGap = 0;
+    let threshold = 1.8;
+
+    for (let i = 0; i < ratios.length - 1; i++) {
+      const gap = ratios[i + 1] - ratios[i];
+      if (gap > maxGap && gap > 0.25 && ratios[i] > 0.8) {
+        maxGap = gap;
+        threshold = (ratios[i] + ratios[i + 1]) / 2;
+      }
+    }
+
+    if (maxGap < 0.2) {
+      const idx = Math.floor(ratios.length * 0.75);
+      threshold = ratios[Math.min(idx, ratios.length - 1)];
+    }
+
+    return Math.max(1.25, Math.min(threshold, 2.2));
+  }
+
   /**
    * Extract plain text from a PDF page.
    * Joins text items with spaces, preserves paragraph breaks.
@@ -400,11 +431,32 @@ export function createPDFPinchReader(container, options = {}) {
     const page = await pdfDoc.getPage(pageNum);
     const content = await page.getTextContent();
 
-    // Build text with paragraph detection
-    let result = "";
+    // First pass: collect all gaps to compute adaptive threshold
+    const gaps = [];
     let lastY = null;
     let lastFontSize = 12;
 
+    for (const item of content.items) {
+      if (!item.str || !item.transform) continue;
+
+      const currentY = item.transform[5];
+      const fontHeight = Math.hypot(item.transform[2], item.transform[3]);
+      if (fontHeight > 0) lastFontSize = fontHeight;
+
+      if (lastY !== null) {
+        gaps.push(Math.abs(currentY - lastY));
+      }
+      lastY = currentY;
+    }
+
+    // Compute adaptive threshold
+    const paraThreshold = findParagraphThreshold(gaps, lastFontSize);
+    const lineThreshold = lastFontSize * 0.3;
+
+    // Second pass: build text with adaptive threshold
+    let result = "";
+    lastY = null;
+
     for (const item of content.items) {
       if (!item.str) continue;
 
@@ -415,10 +467,10 @@ export function createPDFPinchReader(container, options = {}) {
 
         if (lastY !== null) {
           const gap = Math.abs(currentY - lastY);
-          if (gap > lastFontSize * 1.8) {
+          if (gap > lastFontSize * paraThreshold) {
             // Paragraph break
             result += "\n\n";
-          } else if (gap > lastFontSize * 0.3) {
+          } else if (gap > lineThreshold) {
             // Line break within paragraph — add space
             if (!result.endsWith(" ") && !result.endsWith("\n")) {
               result += " ";

package/src/reflow.js

@@ -64,7 +64,7 @@ function drawColoredLine(ctx, text, charOffset, spans, defaultColor, x, y) {
     }
 
     const spanText = text.slice(overlapStart, overlapEnd);
-    ctx.fillStyle = span.color;
+    ctx.fillStyle = span.color === "transparent" ? defaultColor : span.color;
     ctx.fillText(spanText, xPos, y);
     xPos += ctx.measureText(spanText).width;
     pos = overlapEnd;
@@ -156,111 +156,195 @@ async function extractFontMetadata(page, opList, OPS) {
 // ─── Text color extraction ───────────────────────────────────────────────
 
 /**
- * Extract fill colors per beginText/endText block pair.
- * Returns an array of color strings, one per text block.
- *
- * The previous approach pushed one color per text-drawing operator (showText,
- * showSpacedText, etc.) and tried to index into text items 1:1. That mapping
- * is broken because a single showSpacedText operator can produce multiple text
- * items via buildTextContentItem(). Instead, we track color at text-block
- * boundaries — all text items within the same beginText/endText pair share
- * the same color context.
+ * Extract text with colors from the operator list.
+ * Returns an array of {text, color} objects that can be matched to getTextContent() items.
  */
-function extractTextBlockColors(opList, OPS) {
-  const blockColors = []; // one entry per beginText/endText pair
-  let currentColor = "#000000";
-  let blockColor = "#000000";
-  let inTextBlock = false;
+function extractTextWithColors(opList, OPS) {
+  const textRuns = []; // {text, color}
+  let fillColor = "#000000";
+  let strokeColor = "#000000";
+  let textRenderingMode = 0;
+
+  // Helper to extract text from glyph array
+  function glyphsToText(glyphs) {
+    if (!Array.isArray(glyphs)) return "";
+    return glyphs
+      .filter(g => g && typeof g === "object" && g.unicode)
+      .map(g => g.unicode)
+      .join("");
+  }
 
   for (let i = 0; i < opList.fnArray.length; i++) {
     const fn = opList.fnArray[i];
+    const args = opList.argsArray[i];
 
-    // Track color changes
     if (fn === OPS.setFillRGBColor) {
-      currentColor = opList.argsArray[i][0];
-    } else if (fn === OPS.setFillTransparent) {
-      currentColor = "transparent";
-    } else if (
-      fn === OPS.setFillGray ||
-      fn === OPS.setFillColor ||
-      fn === OPS.setFillCMYKColor ||
-      fn === OPS.setFillColorN
-    ) {
-      const args = opList.argsArray[i];
-      if (args?.[0] && typeof args[0] === "string" && args[0].startsWith("#")) {
-        currentColor = args[0];
+      fillColor = argsToHex(args);
+    } else if (fn === OPS.setStrokeRGBColor) {
+      strokeColor = argsToHex(args);
+    } else if (fn === OPS.setTextRenderingMode) {
+      textRenderingMode = args[0];
+    } else if (fn === OPS.showText || fn === OPS.nextLineShowText || fn === OPS.nextLineSetSpacingShowText) {
+      const text = glyphsToText(args[0]);
+      if (text) {
+        textRuns.push({ text, color: visibleColor(fillColor, strokeColor, textRenderingMode) });
+      }
+    } else if (fn === OPS.showSpacedText) {
+      // showSpacedText has an array of [glyphs, spacing, glyphs, spacing, ...]
+      const arr = args[0];
+      if (Array.isArray(arr)) {
+        let combinedText = "";
+        for (let j = 0; j < arr.length; j += 2) {
+          const glyphs = arr[j];
+          if (glyphs) {
+            combinedText += glyphsToText(glyphs);
+          }
+        }
+        if (combinedText) {
+          textRuns.push({ text: combinedText, color: visibleColor(fillColor, strokeColor, textRenderingMode) });
+        }
       }
     }
+  }
 
-    if (fn === OPS.beginText) {
-      inTextBlock = true;
-      blockColor = currentColor; // color at start of block
+  return textRuns;
+}
+
+/**
+ * Match text items to colors by content.
+ * Returns an array of colors aligned with textItems.
+ */
+function matchColorsToTextItems(textItems, textRuns) {
+  const colors = [];
+  let runIdx = 0;
+
+  for (const item of textItems) {
+    if (item.str === undefined || !item.str.trim()) {
+      colors.push(null); // Skip non-text items
+      continue;
     }
 
-    // If color changes within a text block, update (last color wins)
-    if (inTextBlock && (
-      fn === OPS.setFillRGBColor ||
-      fn === OPS.setFillTransparent ||
-      fn === OPS.setFillGray ||
-      fn === OPS.setFillColor ||
-      fn === OPS.setFillCMYKColor ||
-      fn === OPS.setFillColorN
-    )) {
-      blockColor = currentColor;
+    const itemText = item.str.trim();
+    let matchedColor = "#000000"; // default
+
+    // Find a text run that matches this item
+    // Reset runIdx if we've gone too far (item may be earlier in the list)
+    if (runIdx >= textRuns.length) {
+      runIdx = 0;
     }
 
-    if (fn === OPS.endText) {
-      blockColors.push(blockColor);
-      inTextBlock = false;
+    // Search for matching run starting from current position
+    for (let i = runIdx; i < textRuns.length; i++) {
+      const run = textRuns[i];
+      const runText = run.text.trim();
+
+      // Skip empty runs
+      if (!runText) continue;
+
+      // Check for exact match or substring match
+      if (runText === itemText || 
+          itemText.startsWith(runText) || 
+          runText.startsWith(itemText)) {
+        matchedColor = run.color;
+        runIdx = i + 1; // Start from next run for next item
+        break;
+      }
+    }
+
+    colors.push(matchedColor);
+  }
+
+  return colors;
+}
+
+/**
+ * Extract one visible color per text-drawing operator in the operator list.
+ * Returns an array that maps ~1:1 to the text items from getTextContent().
+ * DEPRECATED: Use extractTextWithColors + matchColorsToTextItems instead.
+ */
+function extractTextItemColors(opList, OPS) {
+  const itemColors = []; // one entry per text-drawing operator
+  let fillColor = "#000000";
+  let strokeColor = "#000000";
+  let textRenderingMode = 0;
+
+  for (let i = 0; i < opList.fnArray.length; i++) {
+    const fn = opList.fnArray[i];
+
+    if (fn === OPS.setFillRGBColor) {
+      fillColor = argsToHex(opList.argsArray[i]);
+    } else if (fn === OPS.setStrokeRGBColor) {
+      strokeColor = argsToHex(opList.argsArray[i]);
+    } else if (fn === OPS.setTextRenderingMode) {
+      textRenderingMode = opList.argsArray[i][0];
+    } else if (
+      fn === OPS.showText ||
+      fn === OPS.nextLineShowText ||
+      fn === OPS.nextLineSetSpacingShowText
+    ) {
+      itemColors.push(visibleColor(fillColor, strokeColor, textRenderingMode));
+    } else if (fn === OPS.showSpacedText) {
+      itemColors.push(visibleColor(fillColor, strokeColor, textRenderingMode));
     }
   }
 
-  return blockColors;
+  return itemColors;
+}
+
+/** Convert color operator args to a hex string. Args may be a hex string or RGB byte array. */
+function argsToHex(args) {
+  if (typeof args[0] === "string" && args[0].startsWith("#")) return args[0];
+  const r = args[0] | 0, g = args[1] | 0, b = args[2] | 0;
+  return `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+}
+
+/** Pick the color that will actually be visible based on text rendering mode. */
+function visibleColor(fill, stroke, mode) {
+  const m = mode & 3; // lower 2 bits: 0=fill, 1=stroke, 2=fill+stroke, 3=invisible
+  if (m === 1) return stroke;
+  if (m === 0 || m === 2) return fill;
+  return "#000000"; // mode 3 (invisible) — show as black in reflow
 }
 
 // ─── Page analysis ────────────────────────────────────────────────────────
 
+/**
+ * Find adaptive threshold for grouping items into blocks.
+ * Similar to paragraph detection but tuned for block-level grouping.
+ */
+function findBlockThreshold(gaps, fontSize) {
+  if (gaps.length < 3) return 2.0;  // Default block threshold
+
+  // Filter extreme outliers
+  const filtered = gaps.filter(g => g / fontSize < 5);
+  if (filtered.length < 3) return 2.0;
+
+  const ratios = filtered.map(g => g / fontSize).sort((a, b) => a - b);
+
+  // For block grouping, we want to be more conservative than paragraph detection
+  // Use the 60th percentile as the threshold - this separates:
+  // - Line spacing (~1.0-1.3x) from paragraph gaps (~1.5x+)
+  const idx = Math.floor(ratios.length * 0.6);
+  const threshold = ratios[Math.min(idx, ratios.length - 1)];
+
+  // Clamp: block threshold should be between 1.5x and 2.2x
+  // Lower than paragraph threshold to ensure paragraphs split into separate blocks
+  return Math.max(1.5, Math.min(threshold, 2.2));
+}
+
 /**
  * Group adjacent text items into text blocks by proximity.
  * Also extracts font metadata: average size, italic, bold.
  */
-function groupTextBlocks(textItems, pageHeight, styles, fontMap, blockColors) {
-  // Map text items to beginText/endText blocks by detecting position
-  // discontinuities. Items within the same text block are contiguous and
-  // share the same color. When there's a large Y-position jump or font
-  // change, we advance to the next block's color.
-  if (blockColors && blockColors.length > 0) {
-    let blockIdx = 0;
-    let prevY = null;
-    let prevFontName = null;
-    let itemsInCurrentBlock = 0;
-
-    for (const item of textItems) {
-      if (item.str === undefined) continue; // skip marked content
-
-      const y = item.transform ? item.transform[5] : null;
-      const fontHeight = item.transform
-        ? Math.hypot(item.transform[2], item.transform[3])
-        : 12;
-
-      // Detect text block boundary by position discontinuity
-      if (prevY !== null && y !== null && itemsInCurrentBlock > 0) {
-        const yDiff = Math.abs(y - prevY);
-        const fontChanged = item.fontName !== prevFontName;
-
-        if (
-          (yDiff > fontHeight * 3) ||
-          (fontChanged && yDiff > fontHeight * 0.5)
-        ) {
-          blockIdx = Math.min(blockIdx + 1, blockColors.length - 1);
-          itemsInCurrentBlock = 0;
-        }
-      }
-
-      item._color = blockColors[blockIdx] || "#000000";
-      itemsInCurrentBlock++;
-      prevY = y;
-      prevFontName = item.fontName;
+function groupTextBlocks(textItems, pageHeight, styles, fontMap, textRuns) {
+  // Assign colors to text items by matching content from textRuns.
+  // textRuns is an array of {text, color} extracted from the operator list.
+  if (textRuns && textRuns.length > 0) {
+    const colors = matchColorsToTextItems(textItems, textRuns);
+    for (let i = 0; i < textItems.length; i++) {
+      const item = textItems[i];
+      if (item.str === undefined || !item.str.trim()) continue;
+      item._color = colors[i] || "#000000";
     }
   }
 
@@ -271,6 +355,23 @@ function groupTextBlocks(textItems, pageHeight, styles, fontMap, blockColors) {
     return a.transform[4] - b.transform[4];
   });
 
+  // First pass: collect all vertical gaps to compute adaptive block threshold
+  const gaps = [];
+  let lastY = null;
+  let lastFontSize = 12;
+  for (const item of sorted) {
+    const y = pageHeight - item.transform[5];
+    const fontHeight = Math.hypot(item.transform[2], item.transform[3]);
+    if (fontHeight > 0) lastFontSize = fontHeight;
+    if (lastY !== null) {
+      gaps.push(Math.abs(y - lastY));
+    }
+    lastY = y;
+  }
+
+  // Compute adaptive block grouping threshold
+  const blockThreshold = findBlockThreshold(gaps, lastFontSize);
+
   const blocks = [];
   let current = null;
 
@@ -315,9 +416,10 @@ function groupTextBlocks(textItems, pageHeight, styles, fontMap, blockColors) {
       continue;
     }
 
+    // Use adaptive block threshold instead of fixed 2.5x
     if (
       sizeOk &&
-      verticalGap < lastFH * 2.5 &&
+      verticalGap < lastFH * blockThreshold &&
       x < current.bbox.x + current.bbox.w + lastFH * 1.5
     ) {
       current.items.push(item);
@@ -408,9 +510,7 @@ function groupTextBlocks(textItems, pageHeight, styles, fontMap, blockColors) {
     const colorFreq = {};
     for (const item of block.items) {
       const c = item._color || "#000000";
-      if (c !== "transparent") {
-        colorFreq[c] = (colorFreq[c] || 0) + 1;
-      }
+      colorFreq[c] = (colorFreq[c] || 0) + 1;
     }
     let dominantColor = "#000000";
     let maxColorFreq = 0;
@@ -601,29 +701,91 @@ function detectGraphicRegionsFromRender(offCanvas, textBlocks, renderScale) {
   return regions;
 }
 
+/**
+ * Find adaptive paragraph threshold by analyzing gap distribution.
+ * Uses histogram approach to find natural breakpoint between line gaps and paragraph gaps.
+ */
+function findParagraphThreshold(gaps, fontSize) {
+  if (gaps.length < 3) return 1.8;  // Fallback for small blocks
+
+  // Filter out extreme outliers (>5x font size - likely headers, titles, etc.)
+  const filtered = gaps.filter(g => g / fontSize < 5);
+  if (filtered.length < 3) return 1.8;
+
+  // Convert to font size ratios and sort
+  const ratios = filtered.map(g => g / fontSize).sort((a, b) => a - b);
+
+  // Find the largest gap between consecutive ratios (the "elbow")
+  // Look for a significant jump (>0.3) between line spacing and paragraph spacing
+  let maxGap = 0;
+  let threshold = 1.8;  // Default fallback
+
+  for (let i = 0; i < ratios.length - 1; i++) {
+    const gap = ratios[i + 1] - ratios[i];
+    // Look for significant gaps above typical line spacing (0.8x+)
+    if (gap > maxGap && gap > 0.25 && ratios[i] > 0.8) {
+      maxGap = gap;
+      threshold = (ratios[i] + ratios[i + 1]) / 2;
+    }
+  }
+
+  // If no clear cluster boundary found, use percentile-based approach
+  // 75th percentile usually separates lines from paragraphs
+  if (maxGap < 0.2) {
+    const idx = Math.floor(ratios.length * 0.75);
+    threshold = ratios[Math.min(idx, ratios.length - 1)];
+  }
+
+  // Clamp to reasonable range for paragraph detection
+  // Line spacing is typically 1.0-1.3x, paragraphs 1.3-1.8x+
+  return Math.max(1.25, Math.min(threshold, 2.2));
+}
+
 /**
  * Build text content for a block, preserving paragraph breaks.
  */
 function blockToText(block, pageHeight) {
-  let result = "";
+  // First pass: collect all gaps and font sizes to compute adaptive threshold
+  const gaps = [];
   let lastY = null;
-  let lastX = null;
-  let lastW = 0;
   let lastFontSize = 12;
 
   for (const item of block.items) {
     if (!item.str) continue;
-    const currentX = item.transform[4];
     const currentY = pageHeight - item.transform[5];
     const fontHeight = Math.hypot(item.transform[2], item.transform[3]);
     if (fontHeight > 0) lastFontSize = fontHeight;
 
+    if (lastY !== null) {
+      const vGap = Math.abs(currentY - lastY);
+      gaps.push(vGap);
+    }
+    lastY = currentY;
+  }
+
+  // Compute adaptive paragraph threshold
+  const paraThreshold = findParagraphThreshold(gaps, lastFontSize);
+  const lineThreshold = lastFontSize * 0.3;  // Keep fixed line threshold
+
+  // Second pass: build text with adaptive threshold
+  let result = "";
+  lastY = null;
+  let lastX = null;
+  let lastW = 0;
+
+  for (const item of block.items) {
+    if (!item.str) continue;
+    const currentX = item.transform[4];
+    const currentY = pageHeight - item.transform[5];
+
     if (lastY !== null) {
       const vGap = Math.abs(currentY - lastY);
       const isShortItem = (item.str || "").trim().length <= 2;
-      if (vGap > lastFontSize * 1.8 && !isShortItem) {
+
+      // Use adaptive threshold for paragraph detection
+      if (vGap > lastFontSize * paraThreshold && !isShortItem) {
         result += "\n\n";
-      } else if (vGap > lastFontSize * 0.3) {
+      } else if (vGap > lineThreshold) {
         // Different line — insert space
         if (!result.endsWith(" ") && !result.endsWith("\n")) {
           result += " ";
@@ -916,11 +1078,11 @@ async function analyzePage(page, OPS) {
   // Extract real font metadata from commonObjs (bold, italic, weight, loadedName)
   const fontMap = await extractFontMetadata(page, opList, OPS);
 
-  // Extract text colors per beginText/endText block (not per operator)
-  const blockColors = extractTextBlockColors(opList, OPS);
+  // Extract text with colors from operator list
+  const textRuns = extractTextWithColors(opList, OPS);
 
-  // Now group text blocks with real font data and block colors
-  const textBlocks = groupTextBlocks(textContent.items, pageHeight, textContent.styles, fontMap, blockColors);
+  // Now group text blocks with real font data and matched colors
+  const textBlocks = groupTextBlocks(textContent.items, pageHeight, textContent.styles, fontMap, textRuns);
 
   // Compute body font size (most common size = body text)
   const allSizes = textBlocks.map(b => Math.round(b.avgFontSize * 10) / 10);