teamsync-pdf-viewer 2.2.2 → 2.2.3

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to `teamsync-pdf-viewer` are documented here.
 
+## [2.2.3] — 2026-11-08
+
+### Performance & Loading Optimizations
+- **Lazy Page-Dimension Scanning**:
+  - Deferred scanning page dimensions for pages 2 through $N$ until after Page 1 has completed its first canvas paint (`onFirstPageRendered`).
+  - Replaced eager 25-page parallel Promise batches with background idle slices (6 pages per slice via `requestIdleCallback`) to eliminate network contention on document open.
+  - Applied slice-level scroll offset compensation (`delta = newTop - oldTop`) in continuous mode to prevent layout jumps when non-uniform pages are measured.
+- **Viewport-Gated Text & Link Extraction**:
+  - `fetchText()` and `fetchNativeLinks()` now run only for pages currently in view (`isInViewport`) or that have previously rendered.
+  - Off-screen virtualization buffer rows no longer issue concurrent network requests for text content, fonts, and annotation dictionaries on mount.
+  - Extracted text and links are cached in component state, eliminating redundant network reads when scrolling back into view.
+- **Shared PDF.js Worker Lifecycle & Pre-Warming**:
+  - Added support for passing an explicit `worker?: pdfjsLib.PDFWorker` instance to `<TeamSyncViewer>`, `<DocumentViewer>`, and `createWebViewer()`.
+  - Added `createPdfWorker()`, `getSharedPdfWorker()`, and `destroySharedPdfWorker()` helpers in `src/core/pdfAssets.ts` for host idle warm-up.
+  - Reused a persistent shared worker singleton when none is passed, eliminating the 1.2 MB worker script re-evaluation overhead on every document load, retry, or split pane.
+  - Added self-healing recovery that automatically instantiates a fresh worker if `worker.destroyed` is detected.
+- **Single-Pass Initial Fit Scale**:
+  - Pre-calculates target `fit-width` and `fit-page` scale as soon as Page 1 dimensions and container width are retrieved in `loadPdf`.
+  - Page 1 paints directly at the fitted scale on its initial canvas render, eliminating double-rendering and scale flicker.
+- **Optimized HTTP/2 Network Defaults**:
+  - Defaulted `disableStream: true` in `resolveNetworkParams()`, aborting full-file HTTP 200 download streams after headers to prioritize HTTP 206 range reads for Page 1.
+  - Defaulted `rangeChunkSize: 524288` (512 KiB) to minimize round-trip overhead on high-latency links. Explicit host props continue to override defaults.
+- **Load Telemetry Reporting**:
+  - Added `LoadProgressInfo` interface reporting `{ bytesLoaded, totalBytes, rangeRequests }`.
+  - Hooked `loadingTask.onProgress` to emit progress telemetry through `onLoadProgress` and the event bus (`loadProgress`).
+  - Included telemetry payload in `onFirstPageRendered` and `firstPageRendered` event to measure first-page render performance.
+
 ## [2.2.2] — 2026-11-05
 
 ### Added & Enhanced

package/dist/src/components/DocumentViewer.d.ts

@@ -1,7 +1,7 @@
 import { default as React } from 'react';
 import { Annotation } from '../annotations/types';
 import { AnnotationManager } from '../annotations/AnnotationManager';
-import { Redaction, WatermarkOptions, SDKPermissions, PdfAssetPaths, TransientHighlight, InitialScale, LinkClickEvent, WebViewerInstance } from '../core/types';
+import { Redaction, WatermarkOptions, SDKPermissions, PdfAssetPaths, TransientHighlight, InitialScale, LinkClickEvent, WebViewerInstance, LoadProgressInfo } from '../core/types';
 import { FormManager } from '../forms/FormManager';
 import * as pdfjsLib from 'pdfjs-dist';
 export interface DocumentLoadErrorInfo {
@@ -23,14 +23,16 @@ interface DocumentViewerProps {
     httpHeaders?: Record<string, string>;
     /** Alias for `httpHeaders` providing an alternative headers option. */
     customHeaders?: Record<string, string>;
-    /** Maximum number of bytes fetched per HTTP 206 range request. Default is 65536. */
+    /** Maximum number of bytes fetched per HTTP 206 range request. Default is 524288 (512 KB). */
     rangeChunkSize?: number;
-    /** Disable chunked streaming of PDF file data. Default false. */
+    /** Disable chunked streaming of PDF file data. Default true. */
     disableStream?: boolean;
     /** Disable automatic background pre-fetching of remaining PDF file chunks. Default false. */
     disableAutoFetch?: boolean;
     /** Disable HTTP 206 range requests entirely, forcing full PDF download. Default false. */
     disableRange?: boolean;
+    /** Optional dedicated or pre-warmed pdf.js worker instance. Defaults to shared worker singleton. */
+    worker?: pdfjsLib.PDFWorker;
     /** Password for password-protected PDFs. */
     password?: string;
     /** pdf.js asset locations, applied right before the document is opened. */
@@ -51,7 +53,9 @@ interface DocumentViewerProps {
     onDocumentLoaded?: (doc: pdfjsLib.PDFDocumentProxy, url: string) => void;
     onLoadError?: (error: Error, info: DocumentLoadErrorInfo) => void;
     /** Fires once per loaded document, after the first page canvas has been painted. */
-    onFirstPageRendered?: (pageNumber: number) => void;
+    onFirstPageRendered?: (pageNumber: number, telemetry?: LoadProgressInfo) => void;
+    /** Telemetry callback reporting download progress and range requests. */
+    onLoadProgress?: (info: LoadProgressInfo) => void;
     /** Fires whenever any page canvas has finished rendering. */
     onPageRendered?: (pageNumber: number) => void;
     onPageChange?: (pageNumber: number, numPages: number) => void;
@@ -92,5 +96,5 @@ interface DocumentViewerProps {
     onDownloadFilledPdf?: () => void;
     highlightedRoleId?: string | null;
 }
-export default function DocumentViewer({ leftSidebarOpen, rightSidebarOpen, activeTab, annotationManager, initialDoc, loadNonce, withCredentials, httpHeaders, customHeaders, rangeChunkSize, disableStream, disableAutoFetch, disableRange, password, assets, sidebars, redactions, regexRedactions, scale, setScale, sidebarTab, setSidebarTab, onAnnotationsChange, onRedactionsChange, onRedactionsApplied, onDocumentLoaded, onLoadError, onFirstPageRendered, onPageRendered, onPageChange, pageTransition, pageLayout, rotation, setRotation, watermark, watermarkText, enableAnnotations: _enableAnnotations, initialPage, page, transientHighlights, permissions, hideAnnotationsUntilPageRendered, enableTextSelection, defaultTool, showSelectionTooltip, initialScale, initialWidthRatio, responsive, instance, targetViewer, resolveLinkUrl, onLinkClick, formManager, setActiveTab, onDownloadFilledPdf, highlightedRoleId, }: DocumentViewerProps): React.JSX.Element;
+export default function DocumentViewer({ leftSidebarOpen, rightSidebarOpen, activeTab, annotationManager, initialDoc, loadNonce, withCredentials, httpHeaders, customHeaders, rangeChunkSize, disableStream, disableAutoFetch, disableRange, password, assets, sidebars, redactions, regexRedactions, scale, setScale, sidebarTab, setSidebarTab, onAnnotationsChange, onRedactionsChange, onRedactionsApplied, onDocumentLoaded, onLoadError, onFirstPageRendered, onLoadProgress, onPageRendered, onPageChange, pageTransition, pageLayout, rotation, setRotation, watermark, watermarkText, enableAnnotations: _enableAnnotations, initialPage, page, transientHighlights, permissions, hideAnnotationsUntilPageRendered, enableTextSelection, defaultTool, showSelectionTooltip, initialScale, initialWidthRatio, responsive, instance, targetViewer, resolveLinkUrl, onLinkClick, formManager, setActiveTab, onDownloadFilledPdf, highlightedRoleId, worker, }: DocumentViewerProps): React.JSX.Element;
 export {};

package/dist/src/components/PageRenderer.d.ts

@@ -50,7 +50,8 @@ interface PageRendererProps {
     showFlowOrder?: boolean;
     selectedRoleFilter?: string | null;
     highlightedRoleId?: string | null;
+    isInViewport?: boolean;
 }
-declare function PageRendererComponent({ pageNum, pdfDoc, scale, rotation, containerWidth: _containerWidth, containerHeight: _containerHeight, scrollTop: _scrollTop, scrollLeft: _scrollLeft, pageTop, pageLeft, basePageWidth, basePageHeight, activeTab, activeTool, annotations, selectedAnnotationId, activeSearchResult, transientHighlights, onMouseDown, onMouseMove, onMouseUp, onAnnotationClick, onAnnotationDoubleClick, onStartResize, onStartMove, onAnnotationMouseEnter, onClearSelection, watermark, watermarkText, redactions, onDiscardRedaction, onRendered, hideAnnotationsUntilPageRendered, onLinkClick, formManager, activeFormTool, setActiveFormTool, canFillForms, showFlowOrder, selectedRoleFilter, highlightedRoleId }: PageRendererProps): React.JSX.Element;
+declare function PageRendererComponent({ pageNum, pdfDoc, scale, rotation, containerWidth: _containerWidth, containerHeight: _containerHeight, scrollTop: _scrollTop, scrollLeft: _scrollLeft, pageTop, pageLeft, basePageWidth, basePageHeight, activeTab, activeTool, annotations, selectedAnnotationId, activeSearchResult, transientHighlights, onMouseDown, onMouseMove, onMouseUp, onAnnotationClick, onAnnotationDoubleClick, onStartResize, onStartMove, onAnnotationMouseEnter, onClearSelection, watermark, watermarkText, redactions, onDiscardRedaction, onRendered, hideAnnotationsUntilPageRendered, onLinkClick, formManager, activeFormTool, setActiveFormTool, canFillForms, showFlowOrder, selectedRoleFilter, highlightedRoleId, isInViewport: propIsInViewport }: PageRendererProps): React.JSX.Element;
 declare const PageRenderer: React.MemoExoticComponent<typeof PageRendererComponent>;
 export default PageRenderer;

package/dist/src/components/TeamSyncViewer.d.ts

@@ -2,7 +2,7 @@ import { default as React } from 'react';
 import { DocumentLoadErrorInfo } from './DocumentViewer';
 import { WebViewerInstance } from '../core/ViewerInstance';
 import { FormField, FormDataRecord } from '../forms/types';
-import { WebViewerOptions, Redaction, TransientHighlight, LinkClickEvent } from '../core/types';
+import { WebViewerOptions, Redaction, TransientHighlight, LinkClickEvent, LoadProgressInfo } from '../core/types';
 import { Annotation } from '../annotations/types';
 import { OfficeConverterConfig, OfficeFileType } from '../office';
 export interface TeamSyncViewerProps extends Omit<WebViewerOptions, 'path'> {
@@ -19,11 +19,16 @@ export interface TeamSyncViewerProps extends Omit<WebViewerOptions, 'path'> {
      * the previous one was a presigned link that expired.
      */
     onDocumentLoadError?: (error: Error, retry: (newUrl?: string) => void, info: DocumentLoadErrorInfo) => void;
-    /** Fires once per document, after the first page canvas has been painted. */
+    /** Fires once per document, after the first page canvas has been painted. Includes load telemetry. */
     onFirstPageRendered?: (info: {
         url: string;
         pageNumber: number;
+        bytesLoaded?: number;
+        totalBytes?: number;
+        rangeRequests?: number;
     }) => void;
+    /** Telemetry callback reporting download progress and range requests. */
+    onLoadProgress?: (info: LoadProgressInfo) => void;
     /** Fires whenever any page canvas has finished rendering. */
     onPageRendered?: (info: {
         url: string;

package/dist/src/core/ViewerInstance.d.ts

@@ -47,6 +47,10 @@ export interface LoadDocumentOptions {
     withCredentials?: boolean;
     /** Password for password-protected PDFs. */
     password?: string;
+    /**
+     * Optional dedicated or pre-warmed pdf.js PDFWorker instance.
+     */
+    worker?: pdfjsLib.PDFWorker;
 }
 /** Callbacks the React component installs so the instance can reach live state. */
 export interface ViewerBinding {

package/dist/src/core/pdfAssets.d.ts

@@ -1,4 +1,25 @@
 import { DocumentInitParameters } from 'pdfjs-dist/types/src/display/api';
+/**
+ * © 2026 AngelBot Ai Pvt Ltd. All rights reserved.
+ * pdf.js asset configuration.
+ *
+ * The library never bundles or inlines the pdf.js worker (that produced a 5 MB bundle with a
+ * `data:` URL worker, which strict Content-Security-Policies reject). Hosts serve the worker,
+ * CMaps, standard fonts and wasm decoders from their own origin and tell us where they live.
+ *
+ * Next.js example (copy from node_modules/pdfjs-dist into public/pdfjs/):
+ *   configurePdfAssets({
+ *     workerSrc: '/pdfjs/pdf.worker.min.mjs',
+ *     cMapUrl: '/pdfjs/cmaps/',
+ *     standardFontDataUrl: '/pdfjs/standard_fonts/',
+ *     wasmUrl: '/pdfjs/wasm/',
+ *   });
+ *
+ * Vite example:
+ *   import workerSrc from 'pdfjs-dist/build/pdf.worker.min.mjs?url';
+ *   configurePdfAssets({ workerSrc });
+ */
+import * as pdfjsLib from 'pdfjs-dist';
 export interface PdfAssetPaths {
     /** URL of `pdf.worker.min.mjs` matching the installed pdfjs-dist version. REQUIRED. */
     workerSrc?: string;
@@ -25,3 +46,22 @@ export declare function assertWorkerConfigured(): void;
 export declare function getDocumentParams(): Partial<DocumentInitParameters>;
 /** pdfjs-dist version this build was compiled against (useful for worker-version mismatch checks). */
 export declare const pdfjsVersion: string;
+export type PDFWorker = pdfjsLib.PDFWorker;
+/**
+ * Creates a new dedicated pdf.js worker instance.
+ * Useful for host applications that pre-warm the worker thread during idle periods.
+ */
+export declare function createPdfWorker(params?: {
+    name?: string;
+    port?: any;
+    verbosity?: number;
+}): pdfjsLib.PDFWorker;
+/**
+ * Returns a shared library-level pdf.js worker singleton.
+ * Self-healing: if the worker was destroyed or terminated, instantiates a fresh worker instance.
+ */
+export declare function getSharedPdfWorker(): pdfjsLib.PDFWorker | undefined;
+/**
+ * Destroys the shared library-level pdf.js worker singleton, releasing its worker thread.
+ */
+export declare function destroySharedPdfWorker(): void;

package/dist/src/core/types.d.ts

@@ -7,6 +7,7 @@ import { WebViewerInstance } from './ViewerInstance';
 import { OfficeConverterConfig, OfficeFileType } from '../office/types';
 import { FormManager } from '../forms/FormManager';
 import { FormField, FormDataRecord, FormRole, FormFeatureOptions, FormFieldValueChangedEvent, FormSignatureAppliedEvent, FormSignatureClearedEvent, FormFieldAddedEvent, FormFieldRemovedEvent, FormFieldUpdatedEvent } from '../forms/types';
+import type * as pdfjsLib from 'pdfjs-dist';
 export type { PdfAssetPaths, WebViewerInstance, OfficeConverterConfig, OfficeFileType, FormManager, FormField, FormDataRecord, FormRole, FormFeatureOptions, };
 export interface SearchBounds {
     x: number;
@@ -79,6 +80,12 @@ export type ToolMode = 'select' | 'pan' | 'rectangle' | 'ellipse' | 'line' | 'ar
  * Options accepted by `createWebViewer()` (and the deprecated `WebViewer()` alias).
  * Every option is also available as a prop on `<TeamSyncViewer>`.
  */
+/** Loading telemetry reported during PDF document retrieval. */
+export interface LoadProgressInfo {
+    bytesLoaded: number;
+    totalBytes: number;
+    rangeRequests?: number;
+}
 export interface WebViewerOptions {
     /** @deprecated Only meaningful for the iframe package (`public/webviewer.js`). */
     path?: string;
@@ -157,12 +164,12 @@ export interface WebViewerOptions {
     customHeaders?: Record<string, string>;
     /**
      * Maximum number of bytes fetched per HTTP 206 range request.
-     * Default is 65536 (= 64 KB).
+     * Default is 524288 (= 512 KB), optimizing round-trip latency over HTTP/2.
      */
     rangeChunkSize?: number;
     /**
      * Disable chunked streaming of PDF file data.
-     * Default is false.
+     * Default is true, prioritizing initial page range requests over full-file download streams.
      */
     disableStream?: boolean;
     /**
@@ -177,6 +184,12 @@ export interface WebViewerOptions {
      * Default is false.
      */
     disableRange?: boolean;
+    /**
+     * Optional dedicated or pre-warmed pdf.js PDFWorker instance.
+     * If omitted, a persistent shared library-level worker singleton is used to avoid
+     * recreating a 1.2 MB worker thread on every document open or retry.
+     */
+    worker?: pdfjsLib.PDFWorker;
     /** Render the top toolbar. Default true. */
     toolbar?: boolean;
     /** Render the left (thumbnails) and right (comments/search) panels. Default true. */
@@ -269,7 +282,11 @@ export interface ViewerEventMap {
     firstPageRendered: {
         url: string;
         pageNumber: number;
+        bytesLoaded?: number;
+        totalBytes?: number;
+        rangeRequests?: number;
     };
+    loadProgress: LoadProgressInfo;
     pageRendered: {
         url: string;
         pageNumber: number;

package/dist/src/utils/zoomUtils.d.ts

@@ -32,6 +32,10 @@ export declare function clampScale(scale: number, minScale?: number, maxScale?:
  * optionally scaled by a width ratio (e.g. 0.7 for 70% of available width).
  */
 export declare function calculateFitWidthScale(availableWidth: number, pageWidth: number, ratio?: number, minScale?: number, maxScale?: number): number;
+/**
+ * Calculates the target scale to fit a given page (both width and height) inside an available container viewport.
+ */
+export declare function calculateFitPageScale(availableWidth: number, availableHeight: number, pageWidth: number, pageHeight: number, minScale?: number, maxScale?: number): number;
 /**
  * Calculates the safe rasterization scale for PDF.js viewport rendering so that
  * canvas dimensions and texture memory stay strictly within hardware limits.