pdf-diff-viewer 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [1.1.0] - 2026-01-20
+
+### Added
+- **Smart Alignment**: Text-based page matching for handling content reflow
+- Support for comparing PDFs with different page counts
+- Jaccard similarity algorithm for intelligent page matching
+- `smartAlignment` option (default: true)
+- `alignmentTolerance` option to control search range
+- `similarityThreshold` option for minimum match quality
+- Page mapping information in comparison results
+- Similarity scores displayed in UI for matched pages
+
+### Changed
+- `compare()` method now handles different page counts gracefully
+- Page comparison results now include `pageNumA` and `pageNumB` fields
+- Enhanced error messages for page count mismatches
+
+### Features
+- Automatically finds best-matching pages based on text content
+- Handles scenarios where text additions push content to new pages
+- Displays page mappings (e.g., "Page 1 ↔ Page 2") in UI
+- Shows content similarity percentage for cross-page comparisons
+
 ## [1.0.0] - 2026-01-19
 
 ### Added

package/README.md

@@ -142,6 +142,9 @@ new PDFDiffViewer(container, options)
 - `showPageNumbers` (boolean) - Show page numbers, default: true
 - `cropRegions` (Array) - Regions to crop: `[{ page: 1, x, y, width, height }]`
 - `maskRegions` (Array) - Regions to mask/ignore: `[{ page: 1, x, y, width, height }]`
+- **`smartAlignment` (boolean)** - Enable text-based page alignment for content reflow, default: true
+- **`alignmentTolerance` (number)** - Search range for matching pages (+/- pages), default: 2
+- **`similarityThreshold` (number)** - Minimum text similarity (0-1) for page matching, default: 0.3
 
 ### Methods
 
@@ -157,6 +160,7 @@ Compare two PDFs and render results.
 - `totalPages` - Number of pages compared
 - `totalDiffPixels` - Total different pixels across all pages
 - `pageResults` - Array of per-page results
+- `pageMapping` - Page alignment mappings (when smartAlignment is enabled)
 
 #### `getResults()`
 
@@ -244,6 +248,29 @@ const viewer = new PDFDiffViewer('#container', {
 });
 ```
 
+### With Smart Alignment (Content Reflow Handling)
+
+```javascript
+// Handles cases where content shifts across pages
+// (e.g., adding text pushes content to next page)
+const viewer = new PDFDiffViewer('#container', {
+  smartAlignment: true,         // Enable intelligent page matching
+  alignmentTolerance: 2,        // Search +/- 2 pages for matches
+  similarityThreshold: 0.3      // Require 30% content similarity
+});
+
+const results = await viewer.compare(pdfA, pdfB);
+console.log('Page mappings:', results.pageMapping);
+// Output: [{ pageA: 1, pageB: 1, similarity: 0.95 }, 
+//          { pageA: 2, pageB: 3, similarity: 0.87 }, ...]
+```
+
+**How it works:**
+- Extracts text from all pages in both documents
+- Uses Jaccard similarity to find best-matching pages
+- Handles different page counts gracefully
+- Shows similarity scores in the UI
+
 ### With Mask Regions (Ignore Dynamic Content)
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdf-diff-viewer",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Browser-based PDF comparison tool with visual diff highlighting. Zero system dependencies, pure JavaScript, client-side processing.",
   "main": "src/PDFDiffViewer.js",
   "type": "module",

package/public/app.js

@@ -431,7 +431,64 @@ angular.module("pdfDiffApp", [])
             return overlay;
         }
 
+        // Store PDFs for cleanup
+        let currentPdfA = null;
+        let currentPdfB = null;
+
+        // Cleanup function to clear all resources
+        function cleanup() {
+            // Clear canvases
+            const canvasA = document.getElementById("canvasA");
+            const canvasB = document.getElementById("canvasB");
+            const canvasDiff = document.getElementById("canvasDiff");
+            
+            if (canvasA) {
+                const ctxA = canvasA.getContext("2d");
+                ctxA.clearRect(0, 0, canvasA.width, canvasA.height);
+                canvasA.width = 0;
+                canvasA.height = 0;
+            }
+            
+            if (canvasB) {
+                const ctxB = canvasB.getContext("2d");
+                ctxB.clearRect(0, 0, canvasB.width, canvasB.height);
+                canvasB.width = 0;
+                canvasB.height = 0;
+            }
+            
+            if (canvasDiff) {
+                const ctxDiff = canvasDiff.getContext("2d");
+                ctxDiff.clearRect(0, 0, canvasDiff.width, canvasDiff.height);
+                canvasDiff.width = 0;
+                canvasDiff.height = 0;
+            }
+            
+            // Clear results div
+            const resultsDiv = document.getElementById("results");
+            if (resultsDiv) {
+                resultsDiv.innerHTML = "";
+            }
+            
+            // Destroy PDF documents to free memory
+            if (currentPdfA) {
+                currentPdfA.destroy();
+                currentPdfA = null;
+            }
+            if (currentPdfB) {
+                currentPdfB.destroy();
+                currentPdfB = null;
+            }
+            
+            // Force garbage collection hint
+            if (window.gc) {
+                window.gc();
+            }
+        }
+
         $scope.compare = async function () {
+            // Clear previous results and free memory
+            cleanup();
+            
             const LABEL_A = "Document A";
             const LABEL_B = "Document B";
             const fileA = document.getElementById("fileA").files[0];
@@ -457,12 +514,17 @@ angular.module("pdfDiffApp", [])
             const arrayBufferA = await fileA.arrayBuffer();
             const arrayBufferB = await fileB.arrayBuffer();
 
-            const pdfA = await pdfjsLib.getDocument({ data: arrayBufferA }).promise;
-            const pdfB = await pdfjsLib.getDocument({ data: arrayBufferB }).promise;
+            currentPdfA = await pdfjsLib.getDocument({ data: arrayBufferA }).promise;
+            currentPdfB = await pdfjsLib.getDocument({ data: arrayBufferB }).promise;
+            const pdfA = currentPdfA;
+            const pdfB = currentPdfB;
 
+            const maxPages = Math.max(pdfA.numPages, pdfB.numPages);
+            
             if (pdfA.numPages !== pdfB.numPages) {
-                alert(`Page mismatch: ${pdfA.numPages} vs ${pdfB.numPages}`);
-                return;
+                const message = `Page count differs: ${LABEL_A} has ${pdfA.numPages} page(s), ${LABEL_B} has ${pdfB.numPages} page(s). Showing all ${maxPages} page(s).`;
+                console.warn(message);
+                // alert(message);
             }
 
             const canvasA = document.getElementById("canvasA");
@@ -470,14 +532,86 @@ angular.module("pdfDiffApp", [])
             const canvasDiff = document.getElementById("canvasDiff");
 
             const resultsDiv = document.getElementById("results");
-            resultsDiv.innerHTML = "";
-            // resultsDiv.innerHTML = "<h3>Diff on A vs Diff on B</h3>";
+            // resultsDiv already cleared in cleanup()
 
             // const zip = new JSZip();
             let totalDiffPixels = 0;
 
-            for (let i = 1; i <= pdfA.numPages; i++) {
+            for (let i = 1; i <= maxPages; i++) {
+
+                const hasPageA = i <= pdfA.numPages;
+                const hasPageB = i <= pdfB.numPages;
+
+                // Handle pages that only exist in one document
+                if (!hasPageA || !hasPageB) {
+                    const title = document.createElement("h4");
+                    title.innerText = `Page ${i}`;
+
+                    const row = document.createElement("div");
+                    row.style.display = "grid";
+                    row.style.gridTemplateColumns = "1fr 1fr";
+                    row.style.gap = "15px";
+                    row.style.marginBottom = "25px";
+                    row.style.borderTop = "2px solid #ddd";
+                    row.style.paddingTop = "15px";
+
+                    function makeEmptyCol(labelText) {
+                        const col = document.createElement("div");
+                        const label = document.createElement("div");
+                        label.innerHTML = `<b>${labelText}</b>`;
+
+                        const placeholder = document.createElement("div");
+                        placeholder.style.padding = "40px";
+                        placeholder.style.textAlign = "center";
+                        placeholder.style.backgroundColor = "#f5f5f5";
+                        placeholder.style.border = "1px solid #ccc";
+                        placeholder.style.color = "#999";
+                        placeholder.innerText = "No corresponding page";
+
+                        col.appendChild(label);
+                        col.appendChild(placeholder);
+                        return col;
+                    }
+
+                    function makePageCol(labelText, canvas) {
+                        const col = document.createElement("div");
+                        const label = document.createElement("div");
+                        label.innerHTML = `<b>${labelText}</b>`;
+
+                        const img = document.createElement("img");
+                        img.src = canvas.toDataURL("image/png");
+                        img.style.width = "100%";
+                        img.style.border = "1px solid #ccc";
+                        img.style.imageRendering = "crisp-edges";
+                        img.style.backgroundColor = "#fff";
+
+                        col.appendChild(label);
+                        col.appendChild(img);
+                        return col;
+                    }
+
+                    if (hasPageA && !hasPageB) {
+                        // Only in Document A
+                        await renderPageToCanvas(pdfA, i, canvasA);
+                        const colA = makePageCol(`${LABEL_A} (only)`, canvasA);
+                        const colB = makeEmptyCol(`${LABEL_B} (no page ${i})`);
+                        row.appendChild(colA);
+                        row.appendChild(colB);
+                    } else if (!hasPageA && hasPageB) {
+                        // Only in Document B
+                        await renderPageToCanvas(pdfB, i, canvasB);
+                        const colA = makeEmptyCol(`${LABEL_A} (no page ${i})`);
+                        const colB = makePageCol(`${LABEL_B} (only)`, canvasB);
+                        row.appendChild(colA);
+                        row.appendChild(colB);
+                    }
+
+                    resultsDiv.appendChild(title);
+                    resultsDiv.appendChild(row);
+                    continue;
+                }
 
+                // Both pages exist - do normal comparison
                 const { words: wordsA } = await renderPageToCanvas(pdfA, i, canvasA);
                 const { words: wordsB } = await renderPageToCanvas(pdfB, i, canvasB);
 
@@ -569,6 +703,24 @@ angular.module("pdfDiffApp", [])
                     return col;
                 }
 
+                function makeEmptyCol(labelText) {
+                    const col = document.createElement("div");
+                    const label = document.createElement("div");
+                    label.innerHTML = `<b>${labelText}</b>`;
+
+                    const placeholder = document.createElement("div");
+                    placeholder.style.padding = "40px";
+                    placeholder.style.textAlign = "center";
+                    placeholder.style.backgroundColor = "#f5f5f5";
+                    placeholder.style.border = "1px solid #ccc";
+                    placeholder.style.color = "#999";
+                    placeholder.innerText = "No corresponding page";
+
+                    col.appendChild(label);
+                    col.appendChild(placeholder);
+                    return col;
+                }
+
                 resultsDiv.appendChild(title);
                 row.appendChild(makeCol(LABEL_A, overlayOnA));
                 row.appendChild(makeCol(LABEL_B, overlayOnB));

package/public/index.html

@@ -29,7 +29,7 @@
 
   <canvas id="canvasA" style="display:none"></canvas>
   <canvas id="canvasB" style="display:none"></canvas>
-  <canvas id="canvasDiff"></canvas>
+  <canvas id="canvasDiff" style="display:none"></canvas>
 
 </body>
 </html>

package/src/PDFDiffViewer.js

@@ -20,7 +20,7 @@ class PDFDiffViewer {
             scale: options.scale || 3.0,
             maxShift: options.maxShift || 3,
             dilationRadius: options.dilationRadius || 0,
-            colorTolerance: options.colorTolerance || 120,
+            colorTolerance: options.colorTolerance || 200,
             minHighlightArea: options.minHighlightArea || 60,
             minWordSize: options.minWordSize || 8,
             highlightAlpha: options.highlightAlpha || 0.32,
@@ -29,7 +29,10 @@ class PDFDiffViewer {
             workerSrc: options.workerSrc || 'https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js',
             showPageNumbers: options.showPageNumbers !== false,
             cropRegions: options.cropRegions || [],
-            maskRegions: options.maskRegions || []
+            maskRegions: options.maskRegions || [],
+            smartAlignment: options.smartAlignment !== false, // Enable text-based alignment
+            alignmentTolerance: options.alignmentTolerance || 2, // Search +/- 2 pages for matches
+            similarityThreshold: options.similarityThreshold || 0.3 // Minimum similarity score (0-1)
         };
 
         // Check if PDF.js is loaded
@@ -57,39 +60,56 @@ class PDFDiffViewer {
         const docA = await pdfjsLib.getDocument({ data: bufferA }).promise;
         const docB = await pdfjsLib.getDocument({ data: bufferB }).promise;
 
-        if (docA.numPages !== docB.numPages) {
-            throw new Error(`Page count mismatch: ${docA.numPages} vs ${docB.numPages}`);
-        }
-
         // Clear previous results
         this.container.innerHTML = '';
 
         let totalDiffPixels = 0;
         const pageResults = [];
+        let pageMapping = [];
 
         // Create summary element
         const summaryDiv = document.createElement('div');
         summaryDiv.className = 'pdf-diff-summary';
         this.container.appendChild(summaryDiv);
 
-        // Process each page
-        for (let i = 1; i <= docA.numPages; i++) {
-            const pageResult = await this._comparePage(docA, docB, i);
+        // Use smart alignment if enabled and page counts differ
+        if (this.options.smartAlignment && docA.numPages !== docB.numPages) {
+            summaryDiv.innerHTML = '<p>Analyzing document structure for smart alignment...</p>';
+            pageMapping = await this._findPageMappings(docA, docB);
+            summaryDiv.innerHTML = `<h3>Smart Alignment Active: Comparing ${pageMapping.length} matched page(s)</h3>`;
+        } else if (docA.numPages !== docB.numPages) {
+            throw new Error(`Page count mismatch: ${docA.numPages} vs ${docB.numPages}. Enable 'smartAlignment' option to handle different page counts.`);
+        } else {
+            // Direct 1-to-1 mapping
+            for (let i = 1; i <= docA.numPages; i++) {
+                pageMapping.push({ pageA: i, pageB: i, similarity: 1.0 });
+            }
+        }
+
+        // Process each mapped page pair
+        for (const mapping of pageMapping) {
+            const pageResult = await this._comparePagePair(docA, docB, mapping.pageA, mapping.pageB);
+            pageResult.similarity = mapping.similarity;
             pageResults.push(pageResult);
             totalDiffPixels += pageResult.diffPixels;
 
-            this._renderPageComparison(pageResult, i);
+            this._renderPageComparison(pageResult, mapping.pageA, mapping.pageB);
         }
 
         this.results = {
-            totalPages: docA.numPages,
+            totalPages: pageMapping.length,
             totalDiffPixels,
-            pageResults
+            pageResults,
+            pageMapping
         };
 
         // Update summary
         if (this.options.showPageNumbers) {
-            summaryDiv.innerHTML = `<h3>Comparison Results: ${docA.numPages} page(s)</h3>`;
+            if (docA.numPages === docB.numPages) {
+                summaryDiv.innerHTML = `<h3>Comparison Results: ${docA.numPages} page(s)</h3>`;
+            } else {
+                summaryDiv.innerHTML += `<p>Doc A: ${docA.numPages} pages | Doc B: ${docB.numPages} pages</p>`;
+            }
         }
 
         return this.results;
@@ -134,13 +154,17 @@ class PDFDiffViewer {
     }
 
     async _comparePage(docA, docB, pageNum) {
+        return await this._comparePagePair(docA, docB, pageNum, pageNum);
+    }
+
+    async _comparePagePair(docA, docB, pageNumA, pageNumB) {
         const canvasA = document.createElement('canvas');
         const canvasB = document.createElement('canvas');
 
-        const { words: wordsA } = await this._renderPageToCanvas(docA, pageNum, canvasA);
-        const { words: wordsB } = await this._renderPageToCanvas(docB, pageNum, canvasB);
+        const { words: wordsA } = await this._renderPageToCanvas(docA, pageNumA, canvasA);
+        const { words: wordsB } = await this._renderPageToCanvas(docB, pageNumB, canvasB);
 
-        const pageCrop = this.options.cropRegions.find(r => r.page === pageNum);
+        const pageCrop = this.options.cropRegions.find(r => r.page === pageNumA);
         const croppedWordsA = this._offsetWordBoxes(wordsA, pageCrop);
         const croppedWordsB = this._offsetWordBoxes(wordsB, pageCrop);
 
@@ -173,7 +197,7 @@ class PDFDiffViewer {
         const diffPixels = this._buildDiffImage(imgA, shiftedB, diffImage, this.options.colorTolerance);
 
         // Apply masks
-        const pageMasks = this.options.maskRegions.filter(r => r.page === pageNum);
+        const pageMasks = this.options.maskRegions.filter(r => r.page === pageNumA);
         this._applyMasks(diffImage, pageMasks);
 
         // Dilate diff mask
@@ -194,21 +218,33 @@ class PDFDiffViewer {
         const overlayOnB = this._overlayDiff(paddedB, highlightCanvasB);
 
         return {
-            pageNum,
+            pageNumA,
+            pageNumB,
             diffPixels,
             overlayA: overlayOnA.toDataURL('image/png'),
             overlayB: overlayOnB.toDataURL('image/png'),
             alignment: { dx: best.dx, dy: best.dy }
         };
     }
+            alignment: { dx: best.dx, dy: best.dy }
+        };
+    }
 
-    _renderPageComparison(pageResult, pageNum) {
+    _renderPageComparison(pageResult, pageNumA, pageNumB = null) {
         const pageDiv = document.createElement('div');
         pageDiv.className = 'pdf-diff-page';
 
         if (this.options.showPageNumbers) {
             const title = document.createElement('h4');
-            title.innerText = `Page ${pageNum}`;
+            if (pageNumB !== null && pageNumA !== pageNumB) {
+                title.innerText = `Page ${pageNumA} ↔ Page ${pageNumB}`;
+                if (pageResult.similarity !== undefined) {
+                    const simPercent = (pageResult.similarity * 100).toFixed(1);
+                    title.innerText += ` (${simPercent}% content match)`;
+                }
+            } else {
+                title.innerText = `Page ${pageNumA}`;
+            }
             title.style.marginTop = '20px';
             pageDiv.appendChild(title);
         }
@@ -627,6 +663,130 @@ class PDFDiffViewer {
 
         return overlay;
     }
+
+    // ===== SMART ALIGNMENT METHODS =====
+
+    /**
+     * Find optimal page mappings between two PDFs based on text content similarity
+     */
+    async _findPageMappings(docA, docB) {
+        const mappings = [];
+        const usedPagesB = new Set();
+        const tolerance = this.options.alignmentTolerance;
+
+        // Extract text from all pages of both documents
+        const textsA = await this._extractAllPageTexts(docA);
+        const textsB = await this._extractAllPageTexts(docB);
+
+        // For each page in document A, find best matching page in document B
+        for (let pageA = 1; pageA <= docA.numPages; pageA++) {
+            const textA = textsA[pageA - 1];
+            
+            let bestMatch = null;
+            let bestSimilarity = 0;
+
+            // Search within tolerance range
+            const startPage = Math.max(1, pageA - tolerance);
+            const endPage = Math.min(docB.numPages, pageA + tolerance);
+
+            for (let pageB = startPage; pageB <= endPage; pageB++) {
+                if (usedPagesB.has(pageB)) continue;
+
+                const textB = textsB[pageB - 1];
+                const similarity = this._calculateTextSimilarity(textA, textB);
+
+                if (similarity > bestSimilarity && similarity >= this.options.similarityThreshold) {
+                    bestSimilarity = similarity;
+                    bestMatch = pageB;
+                }
+            }
+
+            // If no good match found, try 1:1 mapping if that page exists and isn't used
+            if (!bestMatch && pageA <= docB.numPages && !usedPagesB.has(pageA)) {
+                bestMatch = pageA;
+                bestSimilarity = this._calculateTextSimilarity(textA, textsB[pageA - 1]);
+            }
+
+            if (bestMatch) {
+                usedPagesB.add(bestMatch);
+                mappings.push({
+                    pageA,
+                    pageB: bestMatch,
+                    similarity: bestSimilarity
+                });
+            }
+        }
+
+        return mappings;
+    }
+
+    /**
+     * Extract text from all pages of a PDF document
+     */
+    async _extractAllPageTexts(doc) {
+        const texts = [];
+        for (let i = 1; i <= doc.numPages; i++) {
+            const page = await doc.getPage(i);
+            const textContent = await page.getTextContent();
+            const pageText = textContent.items
+                .map(item => item.str || '')
+                .join(' ')
+                .toLowerCase()
+                .replace(/\s+/g, ' ')
+                .trim();
+            texts.push(pageText);
+        }
+        return texts;
+    }
+
+    /**
+     * Calculate text similarity using Jaccard similarity coefficient
+     * Returns a value between 0 (no similarity) and 1 (identical)
+     */
+    _calculateTextSimilarity(text1, text2) {
+        if (!text1 && !text2) return 1.0;
+        if (!text1 || !text2) return 0.0;
+
+        // Tokenize into words
+        const words1 = this._tokenize(text1);
+        const words2 = this._tokenize(text2);
+
+        // Create sets of words
+        const set1 = new Set(words1);
+        const set2 = new Set(words2);
+
+        // Calculate Jaccard similarity: |intersection| / |union|
+        const intersection = new Set([...set1].filter(x => set2.has(x)));
+        const union = new Set([...set1, ...set2]);
+
+        if (union.size === 0) return 0.0;
+
+        const jaccardSimilarity = intersection.size / union.size;
+
+        // Also consider length ratio for better accuracy
+        const lengthRatio = Math.min(text1.length, text2.length) / Math.max(text1.length, text2.length);
+
+        // Weighted combination
+        return jaccardSimilarity * 0.7 + lengthRatio * 0.3;
+    }
+
+    /**
+     * Tokenize text into words, removing common stopwords
+     */
+    _tokenize(text) {
+        const stopwords = new Set([
+            'the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for',
+            'of', 'with', 'by', 'from', 'as', 'is', 'was', 'are', 'were', 'be',
+            'been', 'being', 'have', 'has', 'had', 'do', 'does', 'did', 'will',
+            'would', 'should', 'could', 'may', 'might', 'can', 'shall'
+        ]);
+
+        return text
+            .toLowerCase()
+            .replace(/[^\w\s]/g, ' ') // Remove punctuation
+            .split(/\s+/)
+            .filter(word => word.length > 2 && !stopwords.has(word));
+    }
 }
 
 // Export for different module systems