teamsync-pdf-viewer 2.2.1 → 2.2.3

package/CHANGELOG.md

@@ -2,7 +2,74 @@
 
 All notable changes to `teamsync-pdf-viewer` are documented here.
 
-## [2.2.1] — 2026-11-03
+## [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
+- **AcroForm In-Place Updates & Round-Trip Export (F1)**:
+  - Form fields already present in a PDF are updated in-place during export via `form.getFields()` rather than failing with `FieldAlreadyExistsError` or skipping value updates.
+- **Interactive Radio Group Export (F2)**:
+  - Radio options are exported into native interactive PDF radio groups using `form.createRadioGroup()` with calculated bounding boxes, Helvetica text labels, and selection state.
+- **Hierarchical Checklist Export (F3)**:
+  - Multi-select checklist fields export with standardized hierarchical naming (`fieldName.OptionName`) and drawn text labels.
+- **Clean Signature Page Stream & Flatten Option (F4, F5)**:
+  - Unsigned signature placeholders no longer burn permanent ink artifacts onto the PDF content stream unless `flatten: true` is explicitly configured in `getFileData()`.
+  - Added `field.readOnly` checkbox in `FormFieldEditorModal` locking fields against modification, and enforced `enableReadOnly()` on AcroForms.
+  - Added `{ flatten?: boolean }` export option to flatten interactive fields into static page content when desired.
+- **Duplicate Field Key Collision Prevention (F6)**:
+  - Added duplicate name detection banner in the field configuration modal and deterministic suffix naming (`name_1`, `name_2`) during export to prevent collisions.
+- **Electronic vs Digital Signature Clarification (F7, F10)**:
+  - Electronic signatures are explicitly labeled `"Signed electronically by ..."` without misrepresenting visual signatures as digital certificates.
+  - Removed misleading pseudo-random hex strings; digital certificate signatures now show genuine status indicators.
+  - Strict signature value validation rejecting raw strings (e.g. `[object Object]` or `hello`) while accepting structured signature objects and Base64 images.
+- **Manager-Level Role Locking & Security (F8)**:
+  - `FormManager` enforces role assignment and read-only checks on `setValue()` and `setValues()`, blocking unauthorized edits unless `{ force: true }` is passed.
+- **Proportional Option Font Scaling (F9)**:
+  - Replaced rigid 10px minimum clamp on radio and checklist options with proportional scaling down to 7px, eliminating overflow clipping and scrollbars on zoom-out.
+- **Aligned Validation & Unassigned Role Policies (F11)**:
+  - Configurable `unassignedFieldsRole` (`'all' | 'none' | roleId`) ensuring completion counters and `validate()` agree. Validation errors now include role names (e.g., `(Buyer)`).
+- **Native AcroForm & XFDF Form Ingestion (F12, F13)**:
+  - Introduced `extractAcroFormFields` to detect and parse existing PDF `Widget` annotations into interactive form field models.
+  - Introduced `parseXfdfFormFields` to parse XFDF `<widget>` and `<field>` tags directly into `FormManager` without creating dead grey outline annotations.
+- **Form Role Metadata (F14)**:
+  - Added `partyType` (`'signer' | 'viewer' | 'notary'`), `signingOrder`, and custom `metadata` to `FormRole`.
+- **Programmatic Tab Navigation & Granular Events (F15, F18)**:
+  - Added `instance.UI.setActiveTab(tab)` and `instance.UI.getActiveTab()` with `tabChanged` event emission.
+  - Added granular event hooks: `fieldValueChanged`, `signatureApplied`, `signatureCleared`, `fieldAdded`, `fieldRemoved`, `fieldUpdated`.
+- **Role Field Highlighting (F16)**:
+  - Added `instance.highlightRoleFields(roleId)` with accent glow across matching fields.
+- **Adopted Signature Caching & 1-Click Sign All (F17)**:
+  - Added session-level adopted signature persistence with 1-click application across all pending signature fields for the active role.
+- **Prop Synchronization & Undo Isolation (F19)**:
+  - Props passed to `<TeamSyncViewer>` (`formFields`, `formData`) synchronize cleanly without resetting state or polluting undo history stacks.
+- **Dynamic Schema Versioning (F20)**:
+  - Exported field templates now dynamically reflect library version `2.2.2`.
 
 ### Security
 - **Cryptographically Secure Identifier Generation**: Replaced pseudo-random number generator routines with cryptographically secure random values (`crypto.randomUUID()` and `crypto.getRandomValues()`) across fallback blob URLs, manual redactions, and form roles, resolving CodeQL alert CWE-338.

package/README.md

@@ -78,7 +78,7 @@ Explore detailed SDK guides, parameter options, code snippets, and architecture
 
 ---
 
-## ✨ Uncompromised Feature Set
+## ✨ Feature Set
 
 Everything you need to build collaborative, secure document workflows.
 

package/dist/src/annotations/AnnotationManager.d.ts

@@ -31,6 +31,8 @@ export declare class AnnotationManager {
     private readOnly;
     private canEditOthers;
     private resolver;
+    private formManager;
+    setFormManager(fm: any): void;
     setDocument(doc: PDFDocumentProxy | null): void;
     hasDocument(): boolean;
     setCurrentUser(name: string, id?: string): void;

package/dist/src/annotations/xfdf.d.ts

@@ -1,4 +1,5 @@
 import { Annotation } from './types';
+import { FormField, FormDataRecord } from '../forms/types';
 import { GeometryResolver } from './geometry';
 export declare const XFDF_NS = "http://ns.adobe.com/xfdf/";
 export interface XfdfExportOptions {
@@ -16,3 +17,10 @@ export declare function annotationToXfdfFragment(a: Annotation, resolve: Geometr
 /** Serialize annotations to a complete XFDF document. */
 export declare function annotationsToXfdf(annotations: Annotation[], resolve: GeometryResolver, opts?: XfdfExportOptions): Promise<string>;
 export declare function parseXfdf(xml: string, resolve: GeometryResolver): Promise<Annotation[]>;
+/**
+ * Extracts form field definitions (<widget>) and field values (<fields>) from an XFDF document (F13).
+ */
+export declare function parseXfdfFormFields(xml: string, resolve?: GeometryResolver, roleMapper?: (customData: Record<string, string>) => string | undefined): Promise<{
+    fields: FormField[];
+    values: FormDataRecord;
+}>;

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;
@@ -90,6 +94,7 @@ interface DocumentViewerProps {
     formManager?: FormManager;
     setActiveTab?: (tab: string) => void;
     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, }: 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/FormFieldEditorModal.d.ts

@@ -3,6 +3,7 @@ import { FormField, FormRole } from '../forms/types';
 interface FormFieldEditorModalProps {
     field: FormField;
     roles?: FormRole[];
+    existingFields?: FormField[];
     onAddRole?: (role: FormRole) => void;
     onSave: (updated: Partial<FormField>) => void;
     onClose: () => void;

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

@@ -14,6 +14,7 @@ interface FormFieldLayerProps {
     canFillForms?: boolean;
     showFlowOrder?: boolean;
     selectedRoleFilter?: string | null;
+    highlightedRoleId?: string | null;
 }
 export declare const FormFieldLayer: React.FC<FormFieldLayerProps>;
 export {};

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

@@ -6,6 +6,7 @@ interface FormSignatureModalProps {
     role?: FormRole;
     currentUser?: ViewerUser | null;
     currentValue?: FormSignatureValue | any;
+    adoptedSignature?: FormSignatureValue | null;
     defaultSignerName?: string;
     onSave: (value: FormSignatureValue) => void;
     onClear?: () => void;

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

@@ -49,7 +49,9 @@ interface PageRendererProps {
     canFillForms?: boolean;
     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 }: 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

@@ -1,7 +1,8 @@
 import { default as React } from 'react';
 import { DocumentLoadErrorInfo } from './DocumentViewer';
 import { WebViewerInstance } from '../core/ViewerInstance';
-import { WebViewerOptions, Redaction, TransientHighlight, LinkClickEvent } from '../core/types';
+import { FormField, FormDataRecord } from '../forms/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'> {
@@ -18,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;
@@ -97,6 +103,16 @@ export interface TeamSyncViewerProps extends Omit<WebViewerOptions, 'path'> {
         error: Error;
         url?: string;
     }) => void;
+    /** Initial active UI mode tab: 'View' | 'Annotate' | 'Forms' (default 'View') (F15). */
+    initialTab?: string;
+    /** Initial form fields definition (F19). */
+    initialFormFields?: FormField[];
+    /** Initial form data values (F19). */
+    initialFormData?: FormDataRecord;
+    /** Fires when active UI tab changes (F15). */
+    onTabChanged?: (info: {
+        tab: string;
+    }) => void;
     className?: string;
     style?: React.CSSProperties;
 }

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 {
@@ -65,6 +69,7 @@ export interface ViewerBinding {
     }): void;
     getTransientHighlights(): TransientHighlight[];
     setTransientHighlights(highlights: TransientHighlight[]): void;
+    getActiveTab?(): string;
 }
 export declare class WebViewerInstance {
     private static instances;
@@ -89,7 +94,15 @@ export declare class WebViewerInstance {
     private unmountRoot;
     private destroyed;
     private targetViewerTarget;
+    private currentActiveTab;
     constructor(bus: ViewerBus, annotationManager?: AnnotationManager, id?: string, formManager?: FormManager);
+    /**
+     * Visually highlights form fields belonging to a specific role with an accent glow (F16).
+     * Pass null to clear active highlights.
+     */
+    highlightRoleFields(roleId: string | null): void;
+    /** Returns current active tab in the viewer (F15). */
+    getActiveTab(): string;
     /** Sets the target viewer instance, ref, getter, or ID to receive cross-document links. */
     setTargetViewer(target: WebViewerInstance | React.RefObject<WebViewerInstance | null> | (() => WebViewerInstance | null) | string | null): void;
     /** Resolves the target viewer instance if configured. */
@@ -266,6 +279,10 @@ export declare class WebViewerInstance {
      */
     copySelectedText(): Promise<boolean>;
     readonly UI: {
+        /** Sets active UI mode tab: 'View' | 'Annotate' | 'Forms' (F15). */
+        setActiveTab: (tab: "View" | "Annotate" | "Forms" | string) => void;
+        /** Returns currently active tab (F15). */
+        getActiveTab: () => string;
         /** Theming is not implemented; kept for API compatibility. */
         setTheme: (_theme: string) => void;
         goToPage: (pageNumber: number) => void;

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

@@ -16,11 +16,15 @@ export interface ExportInput {
     signerName?: string;
     formFields?: FormField[];
     formData?: FormDataRecord;
+    /** Whether to lock and flatten form fields into static page content on export (F5). */
+    flatten?: boolean;
 }
 export interface ExportOptions {
     /** Bake exactly these annotations instead of the live list. */
     explicitAnnotations?: Annotation[];
     /** Accepted for API compatibility; annotations are always taken from the live list / explicitAnnotations. */
     xfdfString?: string;
+    /** Whether to lock and flatten form fields into static page content on export (F5). */
+    flatten?: boolean;
 }
 export declare function buildPdfBytes(input: ExportInput, options?: ExportOptions): Promise<Uint8Array>;

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

@@ -6,7 +6,8 @@ import { PdfAssetPaths } from './pdfAssets';
 import { WebViewerInstance } from './ViewerInstance';
 import { OfficeConverterConfig, OfficeFileType } from '../office/types';
 import { FormManager } from '../forms/FormManager';
-import { FormField, FormDataRecord, FormRole, FormFeatureOptions } from '../forms/types';
+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;
@@ -302,6 +319,30 @@ export interface ViewerEventMap {
         text: string;
     };
     linkClicked: LinkClickEvent;
+    /** Fires when active UI tab changes (View / Annotate / Forms). */
+    tabChanged: {
+        tab: string;
+    };
+    /** Granular form field value change event (F18). */
+    fieldValueChanged: FormFieldValueChangedEvent;
+    /** Granular signature applied event (F18). */
+    signatureApplied: FormSignatureAppliedEvent;
+    /** Granular signature cleared event (F18). */
+    signatureCleared: FormSignatureClearedEvent;
+    /** Form field schema added (F18). */
+    fieldAdded: FormFieldAddedEvent;
+    /** Form field schema removed (F18). */
+    fieldRemoved: FormFieldRemovedEvent;
+    /** Form field schema updated (F18). */
+    fieldUpdated: FormFieldUpdatedEvent;
+    /** Full form data changed event. */
+    formDataChanged: {
+        data: Record<string, any>;
+    };
+    /** Full form fields schema changed event. */
+    formFieldsChanged: {
+        fields: FormField[];
+    };
     /** Fires when an Office document begins conversion. */
     officeConverting: {
         fileType: OfficeFileType;

package/dist/src/forms/FormManager.d.ts

@@ -1,4 +1,4 @@
-import { FormField, FormDataRecord, FormValidationResult, FormRole, FormFeatureOptions } from './types';
+import { FormField, FormDataRecord, FormValidationResult, FormRole, FormFeatureOptions, FormSignatureValue, FormFieldValueChangedEvent, FormSignatureAppliedEvent, FormSignatureClearedEvent, FormFieldAddedEvent, FormFieldRemovedEvent, FormFieldUpdatedEvent } from './types';
 import { ViewerUser } from '../core/types';
 export declare const DEFAULT_FORM_OPTIONS: FormFeatureOptions;
 export declare const DEFAULT_ROLES: FormRole[];
@@ -25,10 +25,31 @@ export declare class FormManager {
     private activeFieldListeners;
     private optionsListeners;
     private userListeners;
+    private fieldValueListeners;
+    private signatureAppliedListeners;
+    private signatureClearedListeners;
+    private fieldAddedListeners;
+    private fieldRemovedListeners;
+    private fieldUpdatedListeners;
+    private adoptedSignature;
     private readOnly;
     constructor(initialFields?: FormField[], initialValues?: FormDataRecord, initialRoles?: FormRole[], initialOptions?: Partial<FormFeatureOptions>, initialUser?: ViewerUser | null);
     onFieldsChange(listener: FormFieldsChangeListener): () => void;
     onDataChange(listener: FormDataChangeListener): () => void;
+    onFieldValueChanged(listener: (event: FormFieldValueChangedEvent) => void): () => void;
+    onSignatureApplied(listener: (event: FormSignatureAppliedEvent) => void): () => void;
+    onSignatureCleared(listener: (event: FormSignatureClearedEvent) => void): () => void;
+    onFieldAdded(listener: (event: FormFieldAddedEvent) => void): () => void;
+    onFieldRemoved(listener: (event: FormFieldRemovedEvent) => void): () => void;
+    onFieldUpdated(listener: (event: FormFieldUpdatedEvent) => void): () => void;
+    private notifyFieldValueChanged;
+    private notifySignatureApplied;
+    private notifySignatureCleared;
+    private notifyFieldAdded;
+    private notifyFieldRemoved;
+    private notifyFieldUpdated;
+    getAdoptedSignature(): FormSignatureValue | null;
+    setAdoptedSignature(sig: FormSignatureValue | null): void;
     private notifyFieldsChange;
     private notifyDataChange;
     private pushHistory;
@@ -40,15 +61,28 @@ export declare class FormManager {
     getFieldsForPage(pageIndex: number): FormField[];
     getField(id: string): FormField | undefined;
     getFieldByName(name: string): FormField | undefined;
-    setFields(fields: FormField[]): void;
+    setFields(fields: FormField[], recordHistory?: boolean): void;
     addField(field: FormField): void;
     updateField(id: string, updates: Partial<Omit<FormField, 'id'>>, recordHistory?: boolean): boolean;
     deleteField(id: string): boolean;
+    /** Alias for deleteField (F18). */
+    removeField(id: string): boolean;
     clearFields(): void;
     getValues(): FormDataRecord;
     getValue(name: string): any;
-    setValue(name: string, value: any): void;
-    setValues(newValues: FormDataRecord): void;
+    /**
+     * Checks whether a form field can currently be modified based on form read-only state,
+     * field-level read-only setting, and the active role assignment (F8).
+     */
+    canEditField(fieldOrName: FormField | string): boolean;
+    setValue(name: string, value: any, options?: {
+        force?: boolean;
+        source?: 'user' | 'code';
+    }): boolean;
+    setValues(newValues: FormDataRecord, options?: {
+        force?: boolean;
+        source?: 'user' | 'code';
+    }): void;
     clearValues(): void;
     setReadOnly(readOnly: boolean): void;
     isReadOnly(): boolean;

package/dist/src/forms/acroFormIngestion.d.ts

@@ -0,0 +1,6 @@
+import { FormField, FormDataRecord } from './types';
+import { GeometryResolver } from '../annotations/geometry';
+export declare function extractAcroFormFields(pdfDoc: any, resolver?: GeometryResolver): Promise<{
+    fields: FormField[];
+    values: FormDataRecord;
+}>;

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

@@ -98,6 +98,37 @@ export interface FormRole {
     color: string;
     /** Optional human-readable description for the role */
     description?: string;
+    /** Optional party type classification (e.g. 'internal', 'external', 'signer', 'viewer') */
+    partyType?: 'internal' | 'external' | string;
+    /** Optional signing order or sequence index in a multi-party workflow */
+    signingOrder?: number;
+    /** Optional custom host-specific metadata attributes */
+    metadata?: Record<string, any>;
+}
+export interface FormFieldValueChangedEvent {
+    fieldName: string;
+    oldValue: any;
+    newValue: any;
+    source: 'user' | 'code';
+}
+export interface FormSignatureAppliedEvent {
+    fieldName: string;
+    signature: FormSignatureValue;
+    signerName?: string;
+}
+export interface FormSignatureClearedEvent {
+    fieldName: string;
+}
+export interface FormFieldAddedEvent {
+    field: FormField;
+}
+export interface FormFieldRemovedEvent {
+    fieldId: string;
+    fieldName: string;
+}
+export interface FormFieldUpdatedEvent {
+    field: FormField;
+    changes: Partial<FormField>;
 }
 export type FormDataRecord = Record<string, any>;
 export interface FormValidationResult {
@@ -176,4 +207,11 @@ export interface FormFeatureOptions {
      * Controls which fields and signature flags are active for the current user.
      */
     currentRole?: string | null;
+    /**
+     * Defines which role unassigned fields (fields with no roleId) belong to during validation:
+     * - 'all': unassigned fields are required for everyone (default)
+     * - 'none': unassigned fields are never treated as required for any specific role
+     * - string: role ID that unassigned fields belong to
+     */
+    unassignedFieldsRole?: 'all' | 'none' | string;
 }

package/dist/src/index.d.ts

@@ -51,4 +51,6 @@ export type { OfficeConverterConfig, OfficeConversionConfig, OfficeConversionSta
 export { VERSION } from './version';
 export { FormManager, DEFAULT_FORM_OPTIONS, DEFAULT_ROLES } from './forms/FormManager';
 export type { FormFieldsChangeEvent, FormFieldsChangeListener, FormDataChangeListener } from './forms/FormManager';
-export type { FormField, FormFieldType, DateTimeFormat, SignatureType, FormSignatureValue, FormRole, FormDataRecord, FormValidationResult, FormToolType, FormFeatureOptions, } from './forms/types';
+export { extractAcroFormFields } from './forms/acroFormIngestion';
+export { parseXfdfFormFields } from './annotations/xfdf';
+export type { FormField, FormFieldType, DateTimeFormat, SignatureType, FormSignatureValue, FormRole, FormDataRecord, FormValidationResult, FormToolType, FormFeatureOptions, FormFieldValueChangedEvent, FormSignatureAppliedEvent, FormSignatureClearedEvent, FormFieldAddedEvent, FormFieldRemovedEvent, FormFieldUpdatedEvent, } from './forms/types';

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.

package/dist/src/version.d.ts

@@ -1 +1,2 @@
 export declare const VERSION: string;
+export declare const LIB_VERSION: string;