teamsync-pdf-viewer 2.2.0 → 2.2.2

package/CHANGELOG.md

@@ -2,6 +2,65 @@
 
 All notable changes to `teamsync-pdf-viewer` are documented here.
 
+## [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.
+- **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

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.
 
 ---
 
@@ -76,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.
 
@@ -308,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/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/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/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

@@ -90,6 +90,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, 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 {};

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,8 @@ interface PageRendererProps {
     canFillForms?: boolean;
     showFlowOrder?: boolean;
     selectedRoleFilter?: string | null;
+    highlightedRoleId?: 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, 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 }: PageRendererProps): React.JSX.Element;
 declare const PageRenderer: React.MemoExoticComponent<typeof PageRendererComponent>;
 export default PageRenderer;

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

@@ -1,6 +1,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 { Annotation } from '../annotations/types';
 import { OfficeConverterConfig, OfficeFileType } from '../office';
@@ -97,6 +98,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

@@ -65,6 +65,7 @@ export interface ViewerBinding {
     }): void;
     getTransientHighlights(): TransientHighlight[];
     setTransientHighlights(highlights: TransientHighlight[]): void;
+    getActiveTab?(): string;
 }
 export declare class WebViewerInstance {
     private static instances;
@@ -89,7 +90,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 +275,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/types.d.ts

@@ -6,7 +6,7 @@ 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';
 export type { PdfAssetPaths, WebViewerInstance, OfficeConverterConfig, OfficeFileType, FormManager, FormField, FormDataRecord, FormRole, FormFeatureOptions, };
 export interface SearchBounds {
     x: number;
@@ -302,6 +302,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/version.d.ts

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