teamsync-pdf-viewer 1.8.1 → 2.2.1

package/CHANGELOG.md

@@ -2,6 +2,100 @@
 
 All notable changes to `teamsync-pdf-viewer` are documented here.
 
+## [2.2.1] — 2026-11-03
+
+### 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.
+- **Vulnerability Patches & Dependency Updates**:
+  - Upgraded `vite` to `^8.3.5` resolving launch-editor command execution and filesystem bypass advisories.
+  - Upgraded `vitest` to `^5.0.5` (resolving to `5.1.0`) fixing `@vitest/mocker` code injection and path traversal advisories.
+  - Upgraded `vite-plugin-dts` to `^5.1.2` resolving `minimatch` glob amplification denial-of-service advisory.
+  - Upgraded `undici` to `^8.12.3` resolving cache poisoning, TLS options dropping, and DoS advisories.
+  - Upgraded `fast-uri` to `^3.1.9` and `source-map-js` to `^1.2.2`.
+  - Achieved clean `npm audit` with 0 reported vulnerabilities.
+
+## [2.2.0] — 2026-10-20
+
+### Added
+- **Network Authentication Headers**: Added `httpHeaders` and `customHeaders` options to `WebViewerOptions` and `loadDocument(url, options)` allowing authenticated document requests with session tokens and custom HTTP headers.
+- **Progressive Streaming Controls**: Added `rangeChunkSize`, `disableStream`, `disableAutoFetch`, and `disableRange` options to control document downloading behavior and prevent background bandwidth consumption.
+- **Cross-Environment Compatibility**: Enhanced `createBlobUrl` fallback for environments lacking native `URL.createObjectURL(blob)` support (e.g. Node 22 / jsdom).
+
+## [2.0.0] — 2026-09-26
+
+### Added
+- **Multi-Role Form Templates & Host Application User Context**:
+  - **Decoupled Form Roles from User Identity**: Form templates assign fields to abstract roles (`FormRole`) such as `applicant`, `tenant`, `landlord`, or `reviewer`.
+  - **Host Application Current User Integration**: Applications pass the logged-in user profile (`ViewerUser`) containing `id`, `name`, `email`, and `role`. Setting a user automatically activates their role in the form session without hardcoding user IDs into templates.
+  - **Audit-Grade Signature Capture**: Electronic and digital signatures adopted in the viewer automatically bind the active signer's name, email, role, and cryptographic SHA-256 seal.
+- **Signature Sticky / Index Flags**:
+  - **Side-Docked Visual Flags**: Sticky index flags positioned along the right edge of the viewport indicate pending signatures assigned to the current user's role.
+  - **Cross-Page Accessibility**: Flags are visible even when viewing page 1 while signature fields reside on page 2 or later, giving users immediate visibility into required actions.
+  - **1-Click Jump & Sign**: Clicking a sticky flag smoothly scrolls the document directly to the target signature field and activates signature capture.
+  - **Filtered by Active Role**: Only flags relevant to the current user's role are displayed, preventing clutter and cross-user confusion.
+- **Form SDK & Programmatic Feature Control**:
+  - **SDK Methods on `WebViewerInstance`**:
+    - `getFormRoles()`, `setFormRoles()`, `addFormRole()`, `updateFormRole()`, `removeFormRole()`
+    - `getCurrentRole()`, `setCurrentRole()`
+    - `getCurrentUser()`, `setCurrentUser()`
+    - `getFormFields()`, `setFormFields()`, `getFormData()`, `setFormData()`, `clearFormData()`
+    - `validateForm(roleId?)`, `nextFormField(roleId?)`, `previousFormField(roleId?)`
+    - `getFormOptions()`, `setFormOptions()`
+  - **Granular Feature Visibility Controls (`FormFeatureOptions`)**:
+    - `allowRoleSwitching`: Lock users to their assigned role or allow role switching in filler mode.
+    - `showRoleSelector`: Toggle visibility of the role selector dropdown in the toolbar.
+    - `otherRoleFieldsMode`: Configure how fields assigned to other roles are rendered (`'interactive'`, `'view-only'`, or `'hidden'`).
+    - `showSignatureFlags`: Toggle sticky index flags on or off.
+    - `showFlowNavigation`, `showValidation`, `showReset`, `showExport`, `hideToolbar`: Fine-grained visibility toggles for the filler toolbar.
+
+### Breaking Changes
+- **Standardized on Roles**: Removed legacy assignee terminology and aliases (`FormAssignee`, `assigneeId`, `setUser`, `setAssignees`, `actualUser`, etc.) across all models, types, and components in favor of `FormRole`, `FormField.roleId`, and `currentUser`.
+
+## [1.9.0] — 2026-09-25
+
+### Added
+- **Interactive PDF Forms Builder ("Forms" Tab)**:
+  - Added a dedicated 3rd navigation tab ("Forms") alongside "View" and "Annotate" for designing interactive forms directly over loaded PDF documents.
+  - **Comprehensive Form Field Controls**:
+    - **Textbox**: Single-line text input for short answers, names, codes, emails.
+    - **Text Area**: Multi-line expandable text area for comments, descriptions, notes.
+    - **Date and Time Picker**: Calendar and clock selector supporting `date`, `time`, or `datetime` format modes.
+    - **Check List**: Multi-item checklist allowing authors to configure selectable items and respondents to check/uncheck choices independently (plus single-checkbox mode).
+    - **Dropdown**: Single-select dropdown list with customizable choices.
+    - **Radio Group**: Mutually exclusive single-choice options.
+  - **Visual Form Field Canvas Layer**:
+    - Drag-to-create bounding box with live visual preview.
+    - Click-to-select with 8 interactive resize handles (`nw`, `n`, `ne`, `e`, `se`, `s`, `sw`, `w`) and drag-to-move repositioning.
+    - Floating field action bar with quick properties edit, duplicate, and delete actions.
+    - Keyboard delete support (`Delete` / `Backspace`).
+  - **Field Properties Editor**:
+    - Modal dialog to configure field key name, display label, placeholder text, mandatory/required toggle (`*`), date format, default value, and item options management (add, edit, remove, reorder).
+  - **Forms Toolbar**:
+    - Undo and Redo buttons for form layout modifications.
+    - One-click tool selection for Textbox, Text Area, Date & Time, Check List, Dropdown, and Radio Group.
+    - Form schema management: Export Schema (JSON), Import Schema (JSON), Clear All Fields, and quick toggle to test in View mode.
+
+- **Interactive Form Filler (View Tab)**:
+  - Form fields render directly on top of the PDF pages at their exact unscaled PDF coordinates, zooming and rotating with the canvas.
+  - Live interactive HTML inputs embedded directly over pages for single-line text, multi-line textareas, date-time pickers, checklist checkboxes, dropdowns, and radio groups.
+  - Real-time two-way data binding to central `FormManager` state.
+  - **Form Filler Actions Bar**: Utility header displayed in View mode showing completion progress, required field count, form validation with feedback, JSON data export, and form reset.
+
+- **Role & Permissions Architecture**:
+  - Added `canCreateForms?: boolean` (default: `true`) to `SDKPermissions` controlling access to the Forms builder tab. When set to `false`, the Forms tab is omitted and users are restricted to View/Annotate.
+  - Added `canFillForms?: boolean` (default: `true`) to `SDKPermissions` controlling whether fields in View mode can be edited or remain read-only.
+  - Automatic normalization to View tab if a restricted user attempts to switch to Forms tab.
+
+- **Native PDF AcroForm Baking & Export**:
+  - Integrated with `pdf-lib` to bake interactive form fields into native PDF AcroForms upon export (`createTextField`, `createCheckBox`, `createDropdown`, multiline text areas, and checklist items) preserving user-filled values.
+  - Exported public SDK methods on `WebViewerInstance`: `getFormFields()`, `setFormFields()`, `getFormData()`, `setFormData()`, `clearFormData()`, `validateForm()`, and `exportFormData()`.
+  - Exported `FormManager` and all related form types from the top-level package.
+
+### Security
+- **SSRF Prevention & Edge Converter Hardening**: Added strict content-type validation and upstream error sanitization to the edge conversion function.
+- **Protocol Sanitization for PDF Links**: Enforced URI sanitization rejecting `javascript:`, `vbscript:`, and `data:` schemes.
+- **Diff Engine Memory Bounds**: Added bounded edit distance to Myers diff to prevent memory exhaustion on divergent pages.
+
 ## [1.8.1] — 2026-09-19
 
 ### Added

package/README.md

@@ -4,30 +4,32 @@
 
 ![TeamSync PDF Viewer UI](https://raw.githubusercontent.com/angelbot-ai/TeamSync-PDF-Viewer/main/docs/images/viewer_ui.png)
 
-### **100% Open Source. 100% Client-Side. Enterprise SDK.**
+###  Advanced Web PDF Viewer, Annotation and PDF Forms with PDF Enterprise SDK.
 
-[![License: CPAL-1.0](https://img.shields.io/badge/License-CPAL--1.0-blue.svg)](LICENSE)
 [![Live Demo](https://img.shields.io/badge/Live%20Demo-pdfviewer.teamsync.com-000000.svg)](https://pdfviewer.teamsync.com/)
 [![NPM Version](https://img.shields.io/badge/npm-teamsync--pdf--viewer-blue.svg)](https://www.npmjs.com/package/teamsync-pdf-viewer)
 [![React 19](https://img.shields.io/badge/React-19-61dafb.svg)](https://reactjs.org/)
 [![Vite 8](https://img.shields.io/badge/Vite-8.2-646cff.svg)](https://vitejs.dev/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue.svg)](https://www.typescriptlang.org/)
 
-*No paywalls. No vendor lock-in. No server dependencies.*  
 Try the **[Interactive Live Demo](https://pdfviewer.teamsync.com/)** or integrate the high-performance PDF Viewer SDK directly into your React applications.
 
 </div>
 
 ---
 
-## 🚀 Why TeamSync PDF Viewer?
+**TeamSync PDF Viewer** allows developers to embed advanced viewing, annotation, and forms capabilities directly into any web application.
+
+⚡ **Universal Document Viewing**: It accurately renders PDFs, Microsoft Office files (Word, Excel, PowerPoint), CAD drawings, and images directly in the browser. It handles massive, complex files smoothly with vector-based zooming and lightning-fast rendering.
+
+• **True Client-Side Processing**: Because it processes everything locally using the browser's resources, sensitive files never leave the user's device. This makes it ideal for highly secure environments (like finance, healthcare, or legal apps) and significantly reduces server infrastructure costs.
+
+• **Rich Annotation & Collaboration**: It provides built-in UI tools for highlighting text, adding sticky notes, drawing shapes, stamping, and text callouts. It supports real-time collaboration so multiple users can comment and mark up the same document simultaneously.
 
-Traditional commercial PDF viewers force developers into expensive per-domain licenses, opaque sales calls, and heavy server-side processing dependencies. **TeamSync PDF Viewer** is built from the ground up to solve these pain points.
+• **Interactive Forms & Digital Signatures**: Users can fill out existing PDF forms, build new forms from scratch, and apply secure e-signatures or digital signatures.
+
+• **Advanced Text Editing & Redaction**: It allows users to edit underlying text directly within a PDF as if they were in a word processor. It also features programmatic and manual redaction, permanently wiping sensitive data from the document's code.
 
-- 💰 **Zero-Cost, Transparent Licensing**: Uncapped usage, no per-server fees, and no commercial paywalls. 100% free and open-source under CPAL 1.0.
-- ⚡ **100% Client-Side PDF Processing**: Documents never leave the browser sandbox. Process, redact, and render PDFs entirely on the client. 
-- 🔌 **Universal WebViewer API**: Clean, intuitive `WebViewer({...})` API interface that makes integrating into your web applications effortless.
-- 🎨 **Headless & Customizable**: Built for modern React 19 SPA lifecycles. No bloated iFrames to fight—customize toolbars, sidebars, context menus, and controls natively.
 
 ---
 
@@ -65,14 +67,14 @@ If installing from GitHub Packages registry:
 
 Explore detailed SDK guides, parameter options, code snippets, and architecture deep dives:
 
-- 🏠 **[Wiki Home](docs/wiki/Home.md)**: Main documentation index & overview.
-- 🚀 **[Getting Started Guide](docs/wiki/Getting-Started.md)**: Installation, CDN, and framework setups.
-- ⚙️ **[API Reference & Options](docs/wiki/API-Reference-&-Options.md)**: Complete parameter list for `WebViewerOptions` & `SDKPermissions`.
-- 🎨 **[Annotations & Markup Guide](docs/wiki/Annotations-&-Markup-Guide.md)**: Freehand drawing, vector shapes, callouts & links.
-- 🛡️ **[Redactions & PII Sanitization Guide](docs/wiki/Redactions-&-PII-Sanitization.md)**: Binary redactions, regex PII scanning & discard options.
-- 💧 **[Forensic Watermarking Guide](docs/wiki/Forensic-Watermarking.md)**: Dynamic single and tiled watermark setup.
-- 📄 **[Viewing Office Documents Guide](docs/wiki/Viewing-Office-Documents.md)**: Word (.docx), PowerPoint (.pptx), Excel (.xlsx) high-fidelity viewing & conversion.
-- 🔌 **[Plugin Architecture Guide](docs/wiki/Plugin-Architecture.md)**: Writing custom extension plugins.
+- 🏠 **[Wiki Home](https://github.com/angelbot-ai/TeamSync-PDF-Viewer/wiki/Home)**: Main documentation index & overview.
+- 🚀 **[Getting Started Guide](https://github.com/angelbot-ai/TeamSync-PDF-Viewer/wiki/Getting-Started)**: Installation, CDN, and framework setups.
+- ⚙️ **[API Reference & Options](https://github.com/angelbot-ai/TeamSync-PDF-Viewer/wiki/API-Reference-&-Options)**: Complete parameter list for `WebViewerOptions` & `SDKPermissions`.
+- 📝 **[Interactive Forms & Multi-Role Signatures](https://github.com/angelbot-ai/TeamSync-PDF-Viewer/wiki/Interactive-Forms-&-Multi-Role-Signatures)**: PDF form designer, multi-role template assignment, signature sticky index flags & SDK.
+- 🎨 **[Annotations & Markup Guide](https://github.com/angelbot-ai/TeamSync-PDF-Viewer/wiki/Annotations-&-Markup-Guide)**: Freehand drawing, vector shapes, callouts & links.
+- 🛡️ **[Redactions & PII Sanitization Guide](https://github.com/angelbot-ai/TeamSync-PDF-Viewer/wiki/Redactions-&-PII-Sanitization)**: Binary redactions, regex PII scanning & discard options.
+- 💧 **[Forensic Watermarking Guide](https://github.com/angelbot-ai/TeamSync-PDF-Viewer/wiki/Forensic-Watermarking)**: Dynamic single and tiled watermark setup.
+- 🔌 **[Plugin Architecture Guide](https://github.com/angelbot-ai/TeamSync-PDF-Viewer/wiki/Plugin-Architecture)**: Writing custom extension plugins.
 
 ---
 
@@ -80,12 +82,30 @@ Explore detailed SDK guides, parameter options, code snippets, and architecture
 
 Everything you need to build collaborative, secure document workflows.
 
+### 📝 Interactive PDF Forms & Multi-Role Signatures (v2.0 & v2.1)
+- **Visual Forms Designer ("Forms" Tab)**: Dedicated builder tab to design interactive forms with drag-to-create bounding boxes, 8 interactive resize handles, drag-to-move, and keyboard shortcuts.
+- **Comprehensive Form Field Controls**: Textbox, Text Area, Date & Time Picker (calendar/clock modes), Multi-Choice Checklist, Single-Select Dropdown, and Radio Groups.
+- **Multi-Role Form Templates**: Decoupled template roles (`FormRole`) such as `applicant`, `tenant`, `landlord`, or `reviewer`. Design reusable form templates without hardcoding user IDs.
+- **Host Application User Integration**: Pass the logged-in user profile (`ViewerUser`) containing `id`, `name`, `email`, and `role`. Setting the user automatically activates their role in the form session.
+- **Signature Sticky / Index Flags & Cross-Page Navigation**: Visual sticky index flags docked along the viewport edge indicate pending signatures for the current user's role. Clicking a flag navigates across pages, smoothly scrolls the field into view (`scrollIntoView`), and triggers a glowing pulse highlight.
+- **Audit-Grade Signatures**: Electronic signatures (canvas drawing, typed handwriting, image upload) and digital certificate signatures (cryptographic SHA-256 seal) automatically recording signer name, email, role, and timestamp.
+- **Interactive Form Filler ("View" Tab)**: Embedded live inputs positioned over PDF pages at exact coordinates, with sequential filling flow, per-page re-render isolation, per-role validation, JSON export, and native PDF AcroForm baking.
+
 ### 🎨 Smart Markup & Annotations
 - **Full Drawing Toolkit**: Freehand ink (`brush`), highlighters, geometric shapes (rectangles, ellipses), arrows, and lines.
 - **Notes & Callouts**: Sticky notes, callout text boxes with directional arrows, and text annotations.
 - **Interactive Hyperlinks**: Create internal page-jump links (`#page=N`) or external web URL links directly on document selections.
 
-### 🛡️ Secure Redaction
+### ⚡ Viewport Virtualization & High-DPI Scaling (v2.1)
+- **Continuous Scroll Canvas Virtualization**: Built-in `IntersectionObserver` with an 800px lookahead buffer. Off-screen canvases unmount and release high-DPI GPU backbuffers immediately (`canvas.width = 0; canvas.height = 0`) while preserving exact wrapper layout geometry. Supports 1,000+ page documents without crashing mobile Safari or bloating tab memory.
+- **Isolated Form Re-renders**: Typing keystrokes only re-evaluate fields on the active page, producing 0 re-renders across all other mounted pages in large documents.
+- **Retina 60 FPS Zoom & Pan**: High-DPI `devicePixelRatio` scaling eliminates blurred text. Micro-debounced rendering enables buttery-smooth 60 FPS trackpad pinching and 360° mouse drag panning.
+- **Contextual Document Search**: Instant client-side text search with real-time match highlighting, result jumping, and match counting.
+
+### 🛡️ Enterprise Security & Redaction (v2.1)
+- **SVG XSS & Stored Injection Protection**: Typed signatures strictly escape XML entities before rendering SVG templates, and fallback signatures are Base64 encoded.
+- **Strict Image Upload MIME Validation**: Enforces whitelist checks (`image/png`, `image/jpeg`, `image/webp`) to prevent executable SVG/HTML payloads.
+- **In-Memory Data URL Decoding**: AcroForm export decodes Base64 data URLs in-memory without external network `fetch()`, blocking SSRF and network errors.
 - **Binary-Level Data Obliteration**: We don't just place black boxes over text—redactions are permanently rasterized and burned into the underlying PDF vector structure.
 - **Text Layer Sanitization**: Redacted text is automatically stripped from the DOM `textLayer` and PDF content streams, preventing copy/paste extraction and search indexing.
 - **Automatic Regex Redactions**: Programmatically locate and redact sensitive PII in a single click.
@@ -95,10 +115,6 @@ Everything you need to build collaborative, secure document workflows.
 - **Fit to Width & Fit to Page**: Container-aware dynamic scaling calculations for responsive reading on any screen size.
 - **Synchronized Page Rotation**: 360° page rotation with real-time vector coordinate transforms so annotations rotate seamlessly with document content.
 
-### 🔍 High-DPI Canvas Rendering & Search
-- **Retina 60 FPS Zoom & Pan**: High-DPI `devicePixelRatio` scaling eliminates blurred text. Micro-debounced rendering enables buttery-smooth 60 FPS trackpad pinching and 360° mouse drag panning.
-- **Contextual Document Search**: Instant client-side text search with real-time match highlighting, result jumping, and match counting.
-
 ### 💧 Dynamic Forensic Watermarking
 - Programmatic, non-destructive watermarks rendered on the fly (single centered or full-page tiled) with customizable text, color, opacity, font size, and rotation.
 
@@ -165,6 +181,53 @@ function App() {
 }
 ```
 
+### Multi-Role Forms & Electronic Signatures (v2.0)
+
+For multi-party form workflows, role assignment, and signature collection:
+
+```tsx
+import { TeamSyncViewer, WebViewerInstance } from 'teamsync-pdf-viewer';
+import 'teamsync-pdf-viewer/style.css';
+
+function ContractSigningPortal() {
+  const currentUser = {
+    id: 'usr_98124',
+    name: 'Robert Davis',
+    email: 'robert@domain.com',
+    role: 'tenant', // Automatically activates 'tenant' role & signature flags
+  };
+
+  const formRoles = [
+    { id: 'tenant', name: 'Tenant', color: '#2563eb' },
+    { id: 'landlord', name: 'Landlord', color: '#10b981' },
+  ];
+
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <TeamSyncViewer
+        initialDoc="/lease-agreement.pdf"
+        currentUser={currentUser}
+        formRoles={formRoles}
+        formOptions={{
+          allowRoleSwitching: false,       // Locked to respondent's assigned role
+          otherRoleFieldsMode: 'view-only', // Read-only for landlord fields
+          showSignatureFlags: true,         // Display side sticky index flags
+        }}
+        onViewerReady={(instance: WebViewerInstance) => {
+          // Programmatic Form SDK
+          console.log('Active Role:', instance.getCurrentRole());
+          console.log('Form Fields:', instance.getFormFields());
+          
+          // Validate current role's required fields
+          const result = instance.validateForm();
+          if (!result.valid) console.warn('Incomplete:', result.errors);
+        }}
+      />
+    </div>
+  );
+}
+```
+
 ---
 
 ## 🛠️ Local Development Quick Start
@@ -226,7 +289,10 @@ WebViewer({
 ```
 TeamSync-PDF-Viewer/
 ├── src/
-│   ├── components/       # Native React UI (Header, DocumentViewer, Sidebars, Modals)
+│   ├── components/       # Native React UI (Header, DocumentViewer, Forms, Modals)
+│   ├── forms/            # Interactive Forms Engine (FormManager, Roles, AcroForm, Signatures)
+│   ├── office/           # Native Microsoft Office document viewing and conversion
+│   ├── annotations/      # Annotation manager, vector rendering, and XFDF engine
 │   ├── hooks/            # Search & Keyboard shortcut hooks
 │   ├── utils/            # Redaction algorithms, rotation transforms & vector helpers
 │   ├── plugins/          # Plugin API interfaces & registry
@@ -244,6 +310,8 @@ TeamSync-PDF-Viewer/
 Distributed under the **CPAL 1.0 (Common Public Attribution License)**.  
 100% Free and Open Source for personal and commercial usage.
 
+[![License: CPAL-1.0](https://img.shields.io/badge/License-CPAL--1.0-blue.svg)](LICENSE)
+
 ---
 
 <div align="center">

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

@@ -3,4 +3,5 @@
  * Stable, collision-free annotation ids. They double as the XFDF `name` attribute, which hosts use
  * to match persisted rows to live annotations, so they must never be timestamps.
  */
+export declare function generateSecureId(prefix?: string): string;
 export declare function newAnnotationId(): string;

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

@@ -2,6 +2,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 { FormManager } from '../forms/FormManager';
 import * as pdfjsLib from 'pdfjs-dist';
 export interface DocumentLoadErrorInfo {
     url: string;
@@ -18,6 +19,20 @@ interface DocumentViewerProps {
     loadNonce?: number;
     /** Send cookies with the document request. */
     withCredentials?: boolean;
+    /** Custom HTTP headers sent with every document request (e.g. Authorization: Bearer <token>). */
+    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. */
+    rangeChunkSize?: number;
+    /** Disable chunked streaming of PDF file data. Default false. */
+    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;
+    /** Password for password-protected PDFs. */
+    password?: string;
     /** pdf.js asset locations, applied right before the document is opened. */
     assets?: PdfAssetPaths;
     /** Render the thumbnails (left) and comments/search (right) panels. Default true. */
@@ -72,6 +87,9 @@ interface DocumentViewerProps {
         page?: number;
     } | null> | null;
     onLinkClick?: (event: LinkClickEvent) => boolean | void | Promise<void>;
+    formManager?: FormManager;
+    setActiveTab?: (tab: string) => void;
+    onDownloadFilledPdf?: () => void;
 }
-export default function DocumentViewer({ leftSidebarOpen, rightSidebarOpen, activeTab, annotationManager, initialDoc, loadNonce, withCredentials, 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, }: 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, 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 {};

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

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+import { FormField, FormRole } from '../forms/types';
+interface FormFieldEditorModalProps {
+    field: FormField;
+    roles?: FormRole[];
+    onAddRole?: (role: FormRole) => void;
+    onSave: (updated: Partial<FormField>) => void;
+    onClose: () => void;
+}
+export declare const FormFieldEditorModal: React.FC<FormFieldEditorModalProps>;
+export {};

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

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+import { FormToolType } from '../forms/types';
+import { FormManager } from '../forms/FormManager';
+interface FormFieldLayerProps {
+    pageNum: number;
+    scale: number;
+    rotation: number;
+    basePageWidth: number;
+    basePageHeight: number;
+    activeTab: string;
+    activeTool: FormToolType;
+    setActiveTool: (tool: FormToolType) => void;
+    formManager: FormManager;
+    canFillForms?: boolean;
+    showFlowOrder?: boolean;
+    selectedRoleFilter?: string | null;
+}
+export declare const FormFieldLayer: React.FC<FormFieldLayerProps>;
+export {};

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

@@ -0,0 +1,8 @@
+import { default as React } from 'react';
+import { FormManager } from '../forms/FormManager';
+interface FormFillerActionsProps {
+    formManager: FormManager;
+    onDownloadFilledPdf?: () => void;
+}
+export declare const FormFillerActions: React.FC<FormFillerActionsProps>;
+export {};

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

@@ -0,0 +1,15 @@
+import { default as React } from 'react';
+import { FormField, FormSignatureValue, FormRole } from '../forms/types';
+import { ViewerUser } from '../core/types';
+interface FormSignatureModalProps {
+    field: FormField;
+    role?: FormRole;
+    currentUser?: ViewerUser | null;
+    currentValue?: FormSignatureValue | any;
+    defaultSignerName?: string;
+    onSave: (value: FormSignatureValue) => void;
+    onClear?: () => void;
+    onClose: () => void;
+}
+export declare const FormSignatureModal: React.FC<FormSignatureModalProps>;
+export {};

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

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+import { FormManager } from '../forms/FormManager';
+import { FormRole } from '../forms/types';
+interface FormUsersModalProps {
+    formManager: FormManager;
+    onClose: () => void;
+    onRoleAdded?: (role: FormRole) => void;
+    onUserAdded?: (role: FormRole) => void;
+}
+export declare const FormUsersModal: React.FC<FormUsersModalProps>;
+export {};

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

@@ -0,0 +1,15 @@
+import { default as React } from 'react';
+import { FormToolType } from '../forms/types';
+import { FormManager } from '../forms/FormManager';
+interface FormsToolbarProps {
+    activeTool: FormToolType;
+    setActiveTool: (tool: FormToolType) => void;
+    formManager: FormManager;
+    onSwitchToView?: () => void;
+    showFlowOrder?: boolean;
+    setShowFlowOrder?: (show: boolean) => void;
+    selectedRoleFilter?: string | null;
+    setSelectedRoleFilter?: (id: string | null) => void;
+}
+export declare const FormsToolbar: React.FC<FormsToolbarProps>;
+export {};

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

@@ -2,6 +2,8 @@ import { default as React } from 'react';
 import { SearchResult } from '../hooks/usePdfSearch';
 import { Redaction, WatermarkOptions, TransientHighlight } from '../core/types';
 import { Annotation } from '../annotations/types';
+import { FormManager } from '../forms/FormManager';
+import { FormToolType } from '../forms/types';
 import * as pdfjsLib from 'pdfjs-dist';
 export type { Annotation };
 interface PageRendererProps {
@@ -41,7 +43,13 @@ interface PageRendererProps {
     /** Whether to hide annotations and transient highlights until the page canvas has finished rendering. Default: true. */
     hideAnnotationsUntilPageRendered?: boolean;
     onLinkClick?: (url: string, annotation?: Annotation, e?: React.MouseEvent) => void;
+    formManager?: FormManager;
+    activeFormTool?: FormToolType;
+    setActiveFormTool?: (tool: FormToolType) => void;
+    canFillForms?: boolean;
+    showFlowOrder?: boolean;
+    selectedRoleFilter?: string | null;
 }
-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 }: 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 }: PageRendererProps): React.JSX.Element;
 declare const PageRenderer: React.MemoExoticComponent<typeof PageRendererComponent>;
 export default PageRenderer;

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

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { FormManager } from '../forms/FormManager';
+interface SignatureIndexFlagsProps {
+    formManager: FormManager;
+    activeTab: string;
+    onJumpToPage?: (page: number) => void;
+}
+export declare const SignatureIndexFlags: React.FC<SignatureIndexFlagsProps>;
+export {};

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

@@ -3,9 +3,51 @@ import { ViewerBus } from './eventBus';
 import { ExportOptions } from './export';
 import { Annotation } from '../annotations/types';
 import { AnnotationManager } from '../annotations/AnnotationManager';
-import { Redaction, WatermarkOptions, ViewerEventMap, ViewerEventType, TransientHighlight } from './types';
+import { Redaction, WatermarkOptions, ViewerEventMap, ViewerEventType, TransientHighlight, ViewerUser } from './types';
 import { SearchResult } from '../hooks/usePdfSearch';
+import { FormManager } from '../forms/FormManager';
+import { FormField, FormDataRecord, FormValidationResult, FormRole, FormFeatureOptions } from '../forms/types';
 import type * as pdfjsLib from 'pdfjs-dist';
+/** Options passed to `instance.loadDocument(url, options)`. */
+export interface LoadDocumentOptions {
+    page?: number;
+    initialPage?: number;
+    /**
+     * Custom HTTP headers sent with every document request (e.g. Authorization: Bearer <token>).
+     * Passed directly to the underlying PDF.js engine.
+     */
+    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 (= 64 KB).
+     */
+    rangeChunkSize?: number;
+    /**
+     * Disable chunked streaming of PDF file data.
+     * Default is false.
+     */
+    disableStream?: boolean;
+    /**
+     * Disable automatic background pre-fetching of remaining PDF file chunks when range requests are enabled.
+     * When true, only pages explicitly navigated to are fetched.
+     * Automatically disables streaming as required by the underlying PDF.js engine.
+     * Default is false.
+     */
+    disableAutoFetch?: boolean;
+    /**
+     * Disable HTTP 206 range requests entirely, forcing the full PDF to download.
+     * Default is false.
+     */
+    disableRange?: boolean;
+    /** Send cookies with the document request (same-origin session-bound URLs). Default false. */
+    withCredentials?: boolean;
+    /** Password for password-protected PDFs. */
+    password?: string;
+}
 /** Callbacks the React component installs so the instance can reach live state. */
 export interface ViewerBinding {
     getAnnotations(): Annotation[];
@@ -17,7 +59,7 @@ export interface ViewerBinding {
     getCurrentUserName(): string | undefined;
     getCurrentPage(): number;
     getPageCount(): number;
-    loadDocument(url: string): void;
+    loadDocument(url: string, options?: LoadDocumentOptions): void;
     goToPage(pageNumber: number, options?: {
         smooth?: boolean;
     }): void;
@@ -37,6 +79,8 @@ export declare class WebViewerInstance {
     readonly bus: ViewerBus;
     /** Annotation list, history, permissions and XFDF import/export. */
     readonly annotationManager: AnnotationManager;
+    /** Form fields schema, values, validation, and history. */
+    readonly formManager: FormManager;
     /** Root element of the viewer once mounted. */
     element: HTMLElement | null;
     /** Unique identifier for this instance. */
@@ -45,7 +89,7 @@ export declare class WebViewerInstance {
     private unmountRoot;
     private destroyed;
     private targetViewerTarget;
-    constructor(bus: ViewerBus, annotationManager?: AnnotationManager, id?: string);
+    constructor(bus: ViewerBus, annotationManager?: AnnotationManager, id?: string, formManager?: FormManager);
     /** 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. */
@@ -66,10 +110,7 @@ export declare class WebViewerInstance {
     on<K extends ViewerEventType>(type: K, listener: (detail: ViewerEventMap[K]) => void): () => void;
     off<K extends ViewerEventType>(type: K, listener: (detail: ViewerEventMap[K]) => void): void;
     /** Load (or reload) a document by URL. Resolves when loaded, rejects on load error. */
-    loadDocument(url: string, options?: {
-        page?: number;
-        initialPage?: number;
-    }): Promise<{
+    loadDocument(url: string, options?: LoadDocumentOptions): Promise<{
         url: string;
         numPages: number;
     }>;
@@ -77,10 +118,7 @@ export declare class WebViewerInstance {
      * Loads a document or navigates to a page within it. If the document is already loaded,
      * directly navigates to the requested page without reloading.
      */
-    loadOrNavigate(url: string, options?: {
-        page?: number;
-        initialPage?: number;
-    }): Promise<{
+    loadOrNavigate(url: string, options?: LoadDocumentOptions): Promise<{
         url: string;
         numPages: number;
     } | void>;
@@ -162,6 +200,57 @@ export declare class WebViewerInstance {
     getRedactions(): Redaction[];
     /** Print the exported document (annotations, redactions and watermark baked in). */
     print(): void;
+    /** Returns all defined form fields across all pages. */
+    getFormFields(): FormField[];
+    /** Sets the form fields schema. */
+    setFormFields(fields: FormField[]): void;
+    /** Returns current filled form data values. */
+    getFormData(): FormDataRecord;
+    /** Sets current filled form data values. */
+    setFormData(data: FormDataRecord): void;
+    /** Clears all filled form data values. */
+    clearFormData(): void;
+    /** Validates all required form fields (or only those assigned to the specified role). */
+    validateForm(roleId?: string | null): FormValidationResult;
+    /** Exports filled form data as a JSON string. */
+    exportFormData(_format?: 'json'): Promise<string>;
+    /** Imports form data from a record object or JSON string. */
+    importFormData(data: FormDataRecord | string): void;
+    /** Returns all configured form template roles. */
+    getFormRoles(): FormRole[];
+    /** Sets the list of form template roles. */
+    setFormRoles(roles: FormRole[]): void;
+    /** Adds a new form template role. */
+    addFormRole(role: FormRole): void;
+    /** Updates an existing form template role. */
+    updateFormRole(id: string, updates: Partial<Omit<FormRole, 'id'>>): void;
+    /** Removes a form template role and unbinds any fields associated with it. */
+    removeFormRole(id: string): void;
+    /** Returns the active form role ID (or null for all). */
+    getCurrentRole(): string | null;
+    /** Sets the active form role ID (or null for all). */
+    setCurrentRole(roleId: string | null): void;
+    /** Returns the current logged-in user details passed by the host application. */
+    getCurrentUser(): ViewerUser | null;
+    /**
+     * Sets the current logged-in user details passed by the host application.
+     * If the user specifies a role, that role is automatically activated in the viewer.
+     */
+    setCurrentUser(user: ViewerUser | null): void;
+    /** Returns current form feature options and visibility rules. */
+    getFormOptions(): FormFeatureOptions;
+    /**
+     * Programmatically sets form feature options.
+     * Controls what form features are visible and interactive for the user
+     * (e.g. allowUserSwitching, showSignatureFlags, showFlowNavigation, otherUserFieldsMode, etc.).
+     */
+    setFormOptions(options: Partial<FormFeatureOptions>): void;
+    /** Advances focus to the next form field in the sequence. */
+    nextFormField(roleId?: string | null): FormField | null;
+    /** Moves focus to the previous form field in the sequence. */
+    previousFormField(roleId?: string | null): FormField | null;
+    /** Focuses a specific form field by ID. */
+    focusFormField(fieldId: string): void;
     /**
      * Build the exported PDF (annotations + watermark baked, redacted pages rasterized).
      * Uses the bytes of the loaded document; never re-fetches the URL.
@@ -201,6 +290,8 @@ export declare class WebViewerInstance {
     readonly Core: {
         /** The real AnnotationManager (XFDF import/export, granular events, permissions). */
         readonly annotationManager: AnnotationManager;
+        /** The FormManager (form schema, values, validation). */
+        readonly formManager: FormManager;
         documentViewer: {
             addEventListener: (event: string, callback: (detail: unknown) => void) => (() => void);
             removeEventListener: (event: string, callback: (detail: unknown) => void) => void;