pdfdancer-client-typescript 1.0.12 → 1.0.13

package/src/pdfdancer_v1.ts

@@ -12,6 +12,7 @@ import {
     ValidationException
 } from './exceptions';
 import {
+    AddPageRequest,
     AddRequest,
     BoundingRect,
     ChangeFormFieldRequest,
@@ -19,6 +20,7 @@ import {
     CommandResult,
     CreatePdfRequest,
     DeleteRequest,
+    DocumentSnapshot,
     FindRequest,
     Font,
     FontRecommendation,
@@ -35,6 +37,7 @@ import {
     PageRef,
     PageSize,
     PageSizeInput,
+    PageSnapshot,
     Paragraph,
     Position,
     PositionMode,
@@ -43,11 +46,111 @@ import {
     TextStatus
 } from './models';
 import {ParagraphBuilder} from './paragraph-builder';
+import {PageBuilder} from './page-builder';
 import {FormFieldObject, FormXObject, ImageObject, ParagraphObject, PathObject, TextLineObject} from "./types";
 import {ImageBuilder} from "./image-builder";
+import {generateFingerprint} from "./fingerprint";
 import fs from "fs";
 import path from "node:path";
 
+const DEFAULT_TOLERANCE = 0.01;
+
+// Debug flag - set to true to enable timing logs
+const DEBUG =
+    (process.env.PDFDANCER_CLIENT_DEBUG ?? '').toLowerCase() === 'true' ||
+    (process.env.PDFDANCER_CLIENT_DEBUG ?? '') === '1' ||
+    (process.env.PDFDANCER_CLIENT_DEBUG ?? '').toLowerCase() === 'yes';
+
+/**
+ * Generate a timestamp string in the format expected by the API.
+ * Format: YYYY-MM-DDTHH:MM:SS.ffffffZ (with microseconds)
+ */
+function generateTimestamp(): string {
+    const now = new Date();
+    const year = now.getUTCFullYear();
+    const month = String(now.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(now.getUTCDate()).padStart(2, '0');
+    const hours = String(now.getUTCHours()).padStart(2, '0');
+    const minutes = String(now.getUTCMinutes()).padStart(2, '0');
+    const seconds = String(now.getUTCSeconds()).padStart(2, '0');
+    const milliseconds = String(now.getUTCMilliseconds()).padStart(3, '0');
+    // Add 3 more zeros for microseconds (JavaScript doesn't have microsecond precision)
+    const microseconds = milliseconds + '000';
+    return `${year}-${month}-${day}T${hours}:${minutes}:${seconds}.${microseconds}Z`;
+}
+
+/**
+ * Parse timestamp string, handling both microseconds and nanoseconds precision.
+ * @param timestampStr Timestamp string in format YYYY-MM-DDTHH:MM:SS.fffffffZ (with 6 or 9 fractional digits)
+ */
+function parseTimestamp(timestampStr: string): Date {
+    // Remove the 'Z' suffix
+    let ts = timestampStr.replace(/Z$/, '');
+
+    // Handle nanoseconds (9 digits) by truncating to milliseconds (3 digits)
+    // JavaScript's Date only supports millisecond precision
+    if (ts.includes('.')) {
+        const [datePart, fracPart] = ts.split('.');
+        // Truncate to 3 digits (milliseconds)
+        const truncatedFrac = fracPart.substring(0, 3);
+        ts = `${datePart}.${truncatedFrac}`;
+    }
+
+    return new Date(ts + 'Z');
+}
+
+/**
+ * Check for X-Generated-At and X-Received-At headers and log timing information if DEBUG=true.
+ *
+ * Expected timestamp formats:
+ * - 2025-10-24T08:49:39.161945Z (microseconds - 6 digits)
+ * - 2025-10-24T08:58:45.468131265Z (nanoseconds - 9 digits)
+ */
+function logGeneratedAtHeader(response: Response, method: string, path: string): void {
+    if (!DEBUG) {
+        return;
+    }
+
+    const generatedAt = response.headers.get('X-Generated-At');
+    const receivedAt = response.headers.get('X-Received-At');
+
+    if (generatedAt || receivedAt) {
+        try {
+            const logParts: string[] = [];
+            const currentTime = new Date();
+
+            // Parse and log X-Received-At
+            let receivedTime: Date | null = null;
+            if (receivedAt) {
+                receivedTime = parseTimestamp(receivedAt);
+                const timeSinceReceived = (currentTime.getTime() - receivedTime.getTime()) / 1000;
+                logParts.push(`X-Received-At: ${receivedAt}, time since received on backend: ${timeSinceReceived.toFixed(3)}s`);
+            }
+
+            // Parse and log X-Generated-At
+            let generatedTime: Date | null = null;
+            if (generatedAt) {
+                generatedTime = parseTimestamp(generatedAt);
+                const timeSinceGenerated = (currentTime.getTime() - generatedTime.getTime()) / 1000;
+                logParts.push(`X-Generated-At: ${generatedAt}, time since generated on backend: ${timeSinceGenerated.toFixed(3)}s`);
+            }
+
+            // Calculate processing time (X-Generated-At - X-Received-At)
+            if (receivedTime && generatedTime) {
+                const processingTime = (generatedTime.getTime() - receivedTime.getTime()) / 1000;
+                logParts.push(`processing time on backend: ${processingTime.toFixed(3)}s`);
+            }
+
+            if (logParts.length > 0) {
+                console.log(`${Date.now() / 1000}|${method} ${path} - ${logParts.join(', ')}`);
+            }
+        } catch (e) {
+            const errorMessage = e instanceof Error ? e.message : String(e);
+            console.log(`${Date.now() / 1000}|${method} ${path} - Header parse error: ${errorMessage}`);
+        }
+    }
+}
+
 // 👇 Internal view of PDFDancer methods, not exported
 interface PDFDancerInternals {
 
@@ -98,8 +201,8 @@ class PageClient {
         this._internals = this._client as unknown as PDFDancerInternals;
     }
 
-    async selectPathsAt(x: number, y: number) {
-        return this._internals.toPathObjects(await this._internals.findPaths(Position.atPageCoordinates(this._pageIndex, x, y)));
+    async selectPathsAt(x: number, y: number, tolerance: number = 0) {
+        return this._internals.toPathObjects(await this._internals.findPaths(Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
     }
 
     async selectPaths() {
@@ -110,8 +213,8 @@ class PageClient {
         return this._internals.toImageObjects(await this._internals._findImages(Position.atPage(this._pageIndex)));
     }
 
-    async selectImagesAt(x: number, y: number) {
-        return this._internals.toImageObjects(await this._internals._findImages(Position.atPageCoordinates(this._pageIndex, x, y)));
+    async selectImagesAt(x: number, y: number, tolerance: number = 0) {
+        return this._internals.toImageObjects(await this._internals._findImages(Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
     }
 
     async delete(): Promise<boolean> {
@@ -133,16 +236,16 @@ class PageClient {
         return this._internals.toFormXObjects(await this._internals.findFormXObjects(Position.atPage(this._pageIndex)));
     }
 
-    async selectFormsAt(x: number, y: number) {
-        return this._internals.toFormXObjects(await this._internals.findFormXObjects(Position.atPageCoordinates(this._pageIndex, x, y)));
+    async selectFormsAt(x: number, y: number, tolerance: number = 0) {
+        return this._internals.toFormXObjects(await this._internals.findFormXObjects(Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
     }
 
     async selectFormFields() {
         return this._internals.toFormFields(await this._internals.findFormFields(Position.atPage(this._pageIndex)));
     }
 
-    async selectFormFieldsAt(x: number, y: number) {
-        return this._internals.toFormFields(await this._internals.findFormFields(Position.atPageCoordinates(this._pageIndex, x, y)));
+    async selectFormFieldsAt(x: number, y: number, tolerance: number = 0) {
+        return this._internals.toFormFields(await this._internals.findFormFields(Position.atPageCoordinates(this._pageIndex, x, y, tolerance)));
     }
 
     // noinspection JSUnusedGlobalSymbols
@@ -156,6 +259,11 @@ class PageClient {
         return this._internals.toParagraphObjects(await this._internals.findParagraphs(Position.atPage(this._pageIndex)));
     }
 
+    async selectElements(types?: ObjectType[]) {
+        const snapshot = await this._client.getPageSnapshot(this._pageIndex, types);
+        return snapshot.elements;
+    }
+
     async selectParagraphsStartingWith(text: string) {
         let pos = Position.atPage(this._pageIndex);
         pos.textStartsWith = text;
@@ -168,8 +276,10 @@ class PageClient {
         return this._internals.toParagraphObjects(await this._internals.findParagraphs(pos));
     }
 
-    async selectParagraphsAt(x: number, y: number) {
-        return this._internals.toParagraphObjects(await this._internals.findParagraphs(Position.atPageCoordinates(this._pageIndex, x, y)));
+    async selectParagraphsAt(x: number, y: number, tolerance: number = DEFAULT_TOLERANCE) {
+        return this._internals.toParagraphObjects(
+            await this._internals.findParagraphs(Position.atPageCoordinates(this._pageIndex, x, y, tolerance))
+        );
     }
 
     async selectTextLinesStartingWith(text: string) {
@@ -181,8 +291,14 @@ class PageClient {
     /**
      * Creates a new ParagraphBuilder for fluent paragraph construction.
      */
-    newParagraph(): ParagraphBuilder {
-        return new ParagraphBuilder(this._client, this.position.pageIndex);
+    newParagraph(pageIndex?: number): ParagraphBuilder {
+        const targetIndex = pageIndex ?? this.position.pageIndex;
+        return new ParagraphBuilder(this._client, targetIndex);
+    }
+
+    newImage(pageIndex?: number) {
+        const targetIndex = pageIndex ?? this.position.pageIndex;
+        return new ImageBuilder(this._client, targetIndex);
     }
 
     async selectTextLines() {
@@ -197,8 +313,18 @@ class PageClient {
     }
 
     // noinspection JSUnusedGlobalSymbols
-    async selectTextLinesAt(x: number, y: number) {
-        return this._internals.toTextLineObjects(await this._internals.findTextLines(Position.atPageCoordinates(this._pageIndex, x, y)));
+    async selectTextLinesAt(x: number, y: number, tolerance: number = DEFAULT_TOLERANCE) {
+        return this._internals.toTextLineObjects(
+            await this._internals.findTextLines(Position.atPageCoordinates(this._pageIndex, x, y, tolerance))
+        );
+    }
+
+    /**
+     * Gets a snapshot of this page, including all elements.
+     * Optionally filter by object types.
+     */
+    async getSnapshot(types?: ObjectType[]): Promise<PageSnapshot> {
+        return this._client.getPageSnapshot(this._pageIndex, types);
     }
 }
 
@@ -216,6 +342,13 @@ export class PDFDancer {
     private _readTimeout: number;
     private _pdfBytes: Uint8Array;
     private _sessionId!: string;
+    private _userId?: string;
+    private _fingerprintCache?: string;
+
+    // Snapshot caches for optimizing find operations
+    private _documentSnapshotCache: DocumentSnapshot | null = null;
+    private _pageSnapshotCache: Map<number, PageSnapshot> = new Map();
+    private _pagesCache: PageRef[] | null = null;
 
     /**
      * Creates a new client with PDF data.
@@ -253,6 +386,11 @@ export class PDFDancer {
 
         // Process PDF data with validation
         this._pdfBytes = this._processPdfData(pdfData);
+
+        // Initialize caches
+        this._documentSnapshotCache = null;
+        this._pageSnapshotCache = new Map();
+        this._pagesCache = null;
     }
 
     /**
@@ -330,17 +468,24 @@ export class PDFDancer {
             const endpoint = '/session/new'.replace(/^\/+/, '');
             const url = `${base}/${endpoint}`;
 
+            // Generate fingerprint for this request
+            const fingerprint = await generateFingerprint();
+
             // Make request to create endpoint
             const response = await fetch(url, {
                 method: 'POST',
                 headers: {
                     'Authorization': `Bearer ${resolvedToken}`,
-                    'Content-Type': 'application/json'
+                    'Content-Type': 'application/json',
+                    'X-Generated-At': generateTimestamp(),
+                    'X-Fingerprint': fingerprint
                 },
                 body: JSON.stringify(createRequest.toDict()),
                 signal: resolvedTimeout > 0 ? AbortSignal.timeout(resolvedTimeout) : undefined
             });
 
+            logGeneratedAtHeader(response, 'POST', '/session/new');
+
             if (!response.ok) {
                 const errorText = await response.text();
                 throw new HttpClientException(`Failed to create new PDF: ${errorText}`, response);
@@ -358,6 +503,10 @@ export class PDFDancer {
             client._readTimeout = resolvedTimeout;
             client._pdfBytes = new Uint8Array();
             client._sessionId = sessionId;
+            // Initialize caches
+            client._documentSnapshotCache = null;
+            client._pageSnapshotCache = new Map();
+            client._pagesCache = null;
             return client;
         } catch (error) {
             if (error instanceof HttpClientException || error instanceof SessionException || error instanceof ValidationException) {
@@ -470,15 +619,21 @@ export class PDFDancer {
                 formData.append('pdf', blob, 'document.pdf');
             }
 
+            const fingerprint = await this._getFingerprint();
+
             const response = await fetch(this._buildUrl('/session/create'), {
                 method: 'POST',
                 headers: {
-                    'Authorization': `Bearer ${this._token}`
+                    'Authorization': `Bearer ${this._token}`,
+                    'X-Generated-At': generateTimestamp(),
+                    'X-Fingerprint': fingerprint
                 },
                 body: formData,
                 signal: this._readTimeout > 0 ? AbortSignal.timeout(this._readTimeout) : undefined
             });
 
+            logGeneratedAtHeader(response, 'POST', '/session/create');
+
             if (!response.ok) {
                 const errorMessage = await this._extractErrorMessage(response);
 
@@ -510,6 +665,16 @@ export class PDFDancer {
         }
     }
 
+    /**
+     * Get or generate the fingerprint for this client
+     */
+    private async _getFingerprint(): Promise<string> {
+        if (!this._fingerprintCache) {
+            this._fingerprintCache = await generateFingerprint(this._userId);
+        }
+        return this._fingerprintCache;
+    }
+
     /**
      * Make HTTP request with session headers and error handling.
      */
@@ -526,10 +691,14 @@ export class PDFDancer {
             });
         }
 
+        const fingerprint = await this._getFingerprint();
+
         const headers: Record<string, string> = {
             'Authorization': `Bearer ${this._token}`,
             'X-Session-Id': this._sessionId,
-            'Content-Type': 'application/json'
+            'Content-Type': 'application/json',
+            'X-Generated-At': generateTimestamp(),
+            'X-Fingerprint': fingerprint
         };
 
         try {
@@ -540,6 +709,8 @@ export class PDFDancer {
                 signal: this._readTimeout > 0 ? AbortSignal.timeout(this._readTimeout) : undefined
             });
 
+            logGeneratedAtHeader(response, method, path);
+
             // Handle FontNotFoundException
             if (response.status === 404) {
                 try {
@@ -576,13 +747,43 @@ export class PDFDancer {
      * Searches for PDF objects matching the specified criteria.
      * This method provides flexible search capabilities across all PDF content,
      * allowing filtering by object type and position constraints.
+     *
+     * Now uses snapshot caching for better performance.
      */
     private async find(objectType?: ObjectType, position?: Position): Promise<ObjectRef[]> {
-        const requestData = new FindRequest(objectType, position).toDict();
-        const response = await this._makeRequest('POST', '/pdf/find', requestData);
+        // Determine if we should use snapshot or fall back to HTTP
+        // For paths with coordinates, we need to use HTTP (backend requirement)
+        const isPathWithCoordinates = objectType === ObjectType.PATH &&
+            position?.shape === ShapeType.POINT;
+
+        if (isPathWithCoordinates) {
+            // Fall back to HTTP for path coordinate queries
+            const requestData = new FindRequest(objectType, position).toDict();
+            const response = await this._makeRequest('POST', '/pdf/find', requestData);
+            const objectsData = await response.json() as any[];
+            return objectsData.map((objData: any) => this._parseObjectRef(objData));
+        }
+
+        // Use snapshot-based search
+        let elements: ObjectRef[];
+
+        if (position?.pageIndex !== undefined) {
+            // Page-specific query - use page snapshot
+            const pageSnapshot = await this._getOrFetchPageSnapshot(position.pageIndex);
+            elements = pageSnapshot.elements;
+        } else {
+            // Document-wide query - use document snapshot
+            const docSnapshot = await this._getOrFetchDocumentSnapshot();
+            elements = docSnapshot.getAllElements();
+        }
 
-        const objectsData = await response.json() as any[];
-        return objectsData.map((objData: any) => this._parseObjectRef(objData));
+        // Filter by object type
+        if (objectType) {
+            elements = elements.filter(el => el.type === objectType);
+        }
+
+        // Apply position-based filtering
+        return this._filterByPosition(elements, position);
     }
 
     /**
@@ -643,43 +844,86 @@ export class PDFDancer {
     /**
      * Searches for form fields at the specified position.
      * Returns FormFieldRef objects with name and value properties.
+     *
+     * Now uses snapshot caching for better performance.
      */
     private async findFormFields(position?: Position): Promise<FormFieldRef[]> {
-        const requestData = new FindRequest(ObjectType.FORM_FIELD, position).toDict();
-        const response = await this._makeRequest('POST', '/pdf/find', requestData);
+        // Use snapshot-based search
+        let elements: ObjectRef[];
+
+        if (position?.pageIndex !== undefined) {
+            // Page-specific query - use page snapshot
+            const pageSnapshot = await this._getOrFetchPageSnapshot(position.pageIndex);
+            elements = pageSnapshot.elements;
+        } else {
+            // Document-wide query - use document snapshot
+            const docSnapshot = await this._getOrFetchDocumentSnapshot();
+            elements = docSnapshot.getAllElements();
+        }
+
+        // Filter by form field types (FORM_FIELD, TEXT_FIELD, CHECKBOX, RADIO_BUTTON)
+        const formFieldTypes = [
+            ObjectType.FORM_FIELD,
+            ObjectType.TEXT_FIELD,
+            ObjectType.CHECKBOX,
+            ObjectType.RADIO_BUTTON
+        ];
+        const formFields = elements.filter(el => formFieldTypes.includes(el.type)) as FormFieldRef[];
 
-        const objectsData = await response.json() as any[];
-        return objectsData.map((objData: any) => this._parseFormFieldRef(objData));
+        // Apply position-based filtering
+        return this._filterFormFieldsByPosition(formFields, position);
     }
 
     // Page Operations
 
     /**
      * Retrieves references to all pages in the PDF document.
+     * Now uses snapshot caching to avoid HTTP requests.
      */
     private async getPages(): Promise<PageRef[]> {
-        const response = await this._makeRequest('POST', '/pdf/page/find');
-        const pagesData = await response.json() as any[];
-        return pagesData.map((pageData: any) => this._parsePageRef(pageData));
+        // Check if we have cached pages
+        if (this._pagesCache) {
+            return this._pagesCache;
+        }
+
+        // Try to get from document snapshot cache first
+        if (this._documentSnapshotCache) {
+            this._pagesCache = this._documentSnapshotCache.pages.map(p => p.pageRef);
+            return this._pagesCache;
+        }
+
+        // Fetch document snapshot to get pages (this will cache it)
+        const docSnapshot = await this._getOrFetchDocumentSnapshot();
+        this._pagesCache = docSnapshot.pages.map(p => p.pageRef);
+        return this._pagesCache;
     }
 
     /**
      * Retrieves a reference to a specific page by its page index.
+     * Now uses snapshot caching to avoid HTTP requests.
      */
     private async _getPage(pageIndex: number): Promise<PageRef | null> {
         if (pageIndex < 0) {
             throw new ValidationException(`Page index must be >= 0, got ${pageIndex}`);
         }
 
-        const params = {pageIndex: pageIndex.toString()};
-        const response = await this._makeRequest('POST', '/pdf/page/find', undefined, params);
+        // Try page snapshot cache first
+        if (this._pageSnapshotCache.has(pageIndex)) {
+            return this._pageSnapshotCache.get(pageIndex)!.pageRef;
+        }
 
-        const pagesData = await response.json() as any[];
-        if (!pagesData || pagesData.length === 0) {
-            return null;
+        // Try document snapshot cache
+        if (this._documentSnapshotCache) {
+            const pageSnapshot = this._documentSnapshotCache.getPageSnapshot(pageIndex);
+            if (pageSnapshot) {
+                return pageSnapshot.pageRef;
+            }
         }
 
-        return this._parsePageRef(pagesData[0]);
+        // Fetch document snapshot to get page (this will cache it)
+        const docSnapshot = await this._getOrFetchDocumentSnapshot();
+        const pageSnapshot = docSnapshot.getPageSnapshot(pageIndex);
+        return pageSnapshot?.pageRef ?? null;
     }
 
     /**
@@ -700,6 +944,9 @@ export class PDFDancer {
             throw new HttpClientException(`Failed to move page from ${pageIndex} to ${targetPageIndex}`, response);
         }
 
+        // Invalidate cache after mutation
+        this._invalidateCache();
+
         // Fetch the page again at its new position for up-to-date metadata
         return await this._requirePageRef(targetPageIndex);
     }
@@ -711,7 +958,12 @@ export class PDFDancer {
         this._validatePageIndex(pageIndex, 'pageIndex');
 
         const pageRef = await this._requirePageRef(pageIndex);
-        return this._deletePage(pageRef);
+        const result = await this._deletePage(pageRef);
+
+        // Invalidate cache after mutation
+        this._invalidateCache();
+
+        return result;
     }
 
     private _validatePageIndex(pageIndex: number, fieldName: string): void {
@@ -744,6 +996,186 @@ export class PDFDancer {
         return await response.json() as boolean;
     }
 
+    // Snapshot Operations
+
+    /**
+     * Gets a snapshot of the entire PDF document.
+     * Returns page count, fonts, and snapshots of all pages with their elements.
+     *
+     * @param types Optional array of ObjectType to filter elements by type
+     * @returns DocumentSnapshot containing all document information
+     */
+    async getDocumentSnapshot(types?: ObjectType[]): Promise<DocumentSnapshot> {
+        const params: Record<string, string> = {};
+        if (types && types.length > 0) {
+            params.types = types.join(',');
+        }
+
+        const response = await this._makeRequest('GET', '/pdf/document/snapshot', undefined, params);
+        const data = await response.json() as any;
+
+        return this._parseDocumentSnapshot(data);
+    }
+
+    /**
+     * Gets a snapshot of a specific page.
+     * Returns the page reference and all elements on that page.
+     *
+     * @param pageIndex Zero-based page index
+     * @param types Optional array of ObjectType to filter elements by type
+     * @returns PageSnapshot containing page information and elements
+     */
+    async getPageSnapshot(pageIndex: number, types?: ObjectType[]): Promise<PageSnapshot> {
+        this._validatePageIndex(pageIndex, 'pageIndex');
+
+        const params: Record<string, string> = {};
+        if (types && types.length > 0) {
+            params.types = types.join(',');
+        }
+
+        const response = await this._makeRequest('GET', `/pdf/page/${pageIndex}/snapshot`, undefined, params);
+        const data = await response.json() as any;
+
+        return this._parsePageSnapshot(data);
+    }
+
+    // Cache Management
+
+    /**
+     * Gets a page snapshot from cache or fetches it.
+     * First checks page cache, then document cache, then fetches from server.
+     */
+    private async _getOrFetchPageSnapshot(pageIndex: number): Promise<PageSnapshot> {
+        // Check page cache first
+        if (this._pageSnapshotCache.has(pageIndex)) {
+            return this._pageSnapshotCache.get(pageIndex)!;
+        }
+
+        // Check if we have document snapshot and can extract the page
+        if (this._documentSnapshotCache) {
+            const pageSnapshot = this._documentSnapshotCache.getPageSnapshot(pageIndex);
+            if (pageSnapshot) {
+                // Cache it for future use
+                this._pageSnapshotCache.set(pageIndex, pageSnapshot);
+                return pageSnapshot;
+            }
+        }
+
+        // Fetch page snapshot from server
+        const pageSnapshot = await this.getPageSnapshot(pageIndex);
+        this._pageSnapshotCache.set(pageIndex, pageSnapshot);
+        return pageSnapshot;
+    }
+
+    /**
+     * Gets the document snapshot from cache or fetches it.
+     */
+    private async _getOrFetchDocumentSnapshot(): Promise<DocumentSnapshot> {
+        if (!this._documentSnapshotCache) {
+            this._documentSnapshotCache = await this.getDocumentSnapshot();
+        }
+        return this._documentSnapshotCache;
+    }
+
+    /**
+     * Invalidates all snapshot caches.
+     * Called after any mutation operation.
+     */
+    private _invalidateCache(): void {
+        this._documentSnapshotCache = null;
+        this._pageSnapshotCache.clear();
+        this._pagesCache = null;
+    }
+
+    /**
+     * Filters snapshot elements by Position criteria.
+     * Handles coordinates, text matching, and field name filtering.
+     */
+    private _filterByPosition(elements: ObjectRef[], position?: Position): ObjectRef[] {
+        if (!position) {
+            return elements;
+        }
+
+        let filtered = elements;
+
+        // Filter by page index
+        if (position.pageIndex !== undefined) {
+            filtered = filtered.filter(el => el.position.pageIndex === position.pageIndex);
+        }
+
+        // Filter by coordinates (point containment with tolerance)
+        if (position.boundingRect && position.shape === ShapeType.POINT) {
+            const x = position.boundingRect.x;
+            const y = position.boundingRect.y;
+            const tolerance = position.tolerance || 0;
+            filtered = filtered.filter(el => {
+                const rect = el.position.boundingRect;
+                if (!rect) return false;
+                return x >= rect.x - tolerance && x <= rect.x + rect.width + tolerance &&
+                    y >= rect.y - tolerance && y <= rect.y + rect.height + tolerance;
+            });
+        }
+
+        // Filter by text starts with
+        if (position.textStartsWith && filtered.length > 0) {
+            const textLower = position.textStartsWith.toLowerCase();
+            filtered = filtered.filter(el => {
+                const textObj = el as TextObjectRef;
+                return textObj.text && textObj.text.toLowerCase().startsWith(textLower);
+            });
+        }
+
+        // Filter by text pattern (regex)
+        if (position.textPattern && filtered.length > 0) {
+            const regex = this._compileTextPattern(position.textPattern);
+            filtered = filtered.filter(el => {
+                const textObj = el as TextObjectRef;
+                return textObj.text && regex.test(textObj.text);
+            });
+        }
+
+        // Filter by name (for form fields)
+        if (position.name && filtered.length > 0) {
+            filtered = filtered.filter(el => {
+                const formField = el as FormFieldRef;
+                return formField.name === position.name;
+            });
+        }
+
+        return filtered;
+    }
+
+    /**
+     * Filters FormFieldRef elements by Position criteria.
+     */
+    private _filterFormFieldsByPosition(elements: FormFieldRef[], position?: Position): FormFieldRef[] {
+        return this._filterByPosition(elements as ObjectRef[], position) as FormFieldRef[];
+    }
+
+    private _compileTextPattern(pattern: string): RegExp {
+        try {
+            return new RegExp(pattern);
+        } catch {
+            const inlineMatch = pattern.match(/^\(\?([a-z]+)\)/i);
+            if (inlineMatch) {
+                const supportedFlags = inlineMatch[1]
+                    .toLowerCase()
+                    .split('')
+                    .filter(flag => 'gimsuy'.includes(flag));
+                const flags = Array.from(new Set(supportedFlags)).join('');
+                const source = pattern.slice(inlineMatch[0].length);
+                try {
+                    return new RegExp(source, flags);
+                } catch {
+                    // fall through to literal fallback
+                }
+            }
+
+            const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            return new RegExp(escaped);
+        }
+    }
+
     // Manipulation Operations
 
     /**
@@ -756,7 +1188,12 @@ export class PDFDancer {
 
         const requestData = new DeleteRequest(objectRef).toDict();
         const response = await this._makeRequest('DELETE', '/pdf/delete', requestData);
-        return await response.json() as boolean;
+        const result = await response.json() as boolean;
+
+        // Invalidate cache after mutation
+        this._invalidateCache();
+
+        return result;
     }
 
     /**
@@ -772,7 +1209,12 @@ export class PDFDancer {
 
         const requestData = new MoveRequest(objectRef, position).toDict();
         const response = await this._makeRequest('PUT', '/pdf/move', requestData);
-        return await response.json() as boolean;
+        const result = await response.json() as boolean;
+
+        // Invalidate cache after mutation
+        this._invalidateCache();
+
+        return result;
     }
 
     /**
@@ -785,7 +1227,12 @@ export class PDFDancer {
 
         const requestData = new ChangeFormFieldRequest(formFieldRef, newValue).toDict();
         const response = await this._makeRequest('PUT', '/pdf/modify/formField', requestData);
-        return await response.json() as boolean;
+        const result = await response.json() as boolean;
+
+        // Invalidate cache after mutation
+        this._invalidateCache();
+
+        return result;
     }
 
     // Add Operations
@@ -829,13 +1276,33 @@ export class PDFDancer {
         return this._addObject(paragraph);
     }
 
+    /**
+     * Adds a page to the PDF document.
+     */
+    private async addPage(request?: AddPageRequest | null): Promise<PageRef> {
+        const payload = request ? request.toDict() : {};
+        const data = Object.keys(payload).length > 0 ? payload : undefined;
+        const response = await this._makeRequest('POST', '/pdf/page/add', data);
+        const result = await response.json();
+        const pageRef = this._parsePageRef(result);
+
+        this._invalidateCache();
+
+        return pageRef;
+    }
+
     /**
      * Internal method to add any PDF object.
      */
     private async _addObject(pdfObject: Image | Paragraph): Promise<boolean> {
         const requestData = new AddRequest(pdfObject).toDict();
         const response = await this._makeRequest('POST', '/pdf/add', requestData);
-        return await response.json() as boolean;
+        const result = await response.json() as boolean;
+
+        // Invalidate cache after mutation
+        this._invalidateCache();
+
+        return result;
     }
 
     // Modify Operations
@@ -843,7 +1310,7 @@ export class PDFDancer {
     /**
      * Modifies a paragraph object or its text content.
      */
-    private async modifyParagraph(objectRef: ObjectRef, newParagraph: Paragraph | string): Promise<CommandResult> {
+    private async modifyParagraph(objectRef: ObjectRef, newParagraph: Paragraph | string | null): Promise<CommandResult> {
         if (!objectRef) {
             throw new ValidationException("Object reference cannot be null");
         }
@@ -851,17 +1318,23 @@ export class PDFDancer {
             return CommandResult.empty("ModifyParagraph", objectRef.internalId);
         }
 
+        let result: CommandResult;
         if (typeof newParagraph === 'string') {
             // Text modification - returns CommandResult
             const requestData = new ModifyTextRequest(objectRef, newParagraph).toDict();
             const response = await this._makeRequest('PUT', '/pdf/text/paragraph', requestData);
-            return CommandResult.fromDict(await response.json());
+            result = CommandResult.fromDict(await response.json());
         } else {
             // Object modification
             const requestData = new ModifyRequest(objectRef, newParagraph).toDict();
             const response = await this._makeRequest('PUT', '/pdf/modify', requestData);
-            return CommandResult.fromDict(await response.json());
+            result = CommandResult.fromDict(await response.json());
         }
+
+        // Invalidate cache after mutation
+        this._invalidateCache();
+
+        return result;
     }
 
     /**
@@ -877,7 +1350,12 @@ export class PDFDancer {
 
         const requestData = new ModifyTextRequest(objectRef, newText).toDict();
         const response = await this._makeRequest('PUT', '/pdf/text/line', requestData);
-        return CommandResult.fromDict(await response.json());
+        const result = CommandResult.fromDict(await response.json());
+
+        // Invalidate cache after mutation
+        this._invalidateCache();
+
+        return result;
     }
 
     // Font Operations
@@ -939,16 +1417,22 @@ export class PDFDancer {
             const blob = new Blob([fontData.buffer as ArrayBuffer], {type: 'font/ttf'});
             formData.append('ttfFile', blob, filename);
 
+            const fingerprint = await this._getFingerprint();
+
             const response = await fetch(this._buildUrl('/font/register'), {
                 method: 'POST',
                 headers: {
                     'Authorization': `Bearer ${this._token}`,
-                    'X-Session-Id': this._sessionId
+                    'X-Session-Id': this._sessionId,
+                    'X-Generated-At': generateTimestamp(),
+                    'X-Fingerprint': fingerprint
                 },
                 body: formData,
                 signal: AbortSignal.timeout(30000)
             });
 
+            logGeneratedAtHeader(response, 'POST', '/font/register');
+
             if (!response.ok) {
                 const errorMessage = await this._extractErrorMessage(response);
                 throw new HttpClientException(`Font registration failed: ${errorMessage}`, response);
@@ -1011,6 +1495,17 @@ export class PDFDancer {
             return this._parseTextObjectRef(objData);
         }
 
+        // Check if this is a form field type
+        const formFieldTypes = [
+            ObjectType.FORM_FIELD,
+            ObjectType.TEXT_FIELD,
+            ObjectType.CHECKBOX,
+            ObjectType.RADIO_BUTTON
+        ];
+        if (formFieldTypes.includes(objectType)) {
+            return this._parseFormFieldRef(objData);
+        }
+
         return new ObjectRef(
             objData.internalId,
             position,
@@ -1021,6 +1516,7 @@ export class PDFDancer {
     private _isTextObjectData(objData: any, objectType: ObjectType): boolean {
         return objectType === ObjectType.PARAGRAPH ||
             objectType === ObjectType.TEXT_LINE ||
+            objectType === ObjectType.TEXT_ELEMENT ||
             typeof objData.text === 'string' ||
             typeof objData.fontName === 'string' ||
             Array.isArray(objData.children);
@@ -1074,10 +1570,15 @@ export class PDFDancer {
         );
 
         if (Array.isArray(objData.children) && objData.children.length > 0) {
-            textObject.children = objData.children.map((childData: any, index: number) => {
-                const childFallbackId = `${internalId || 'child'}-${index}`;
-                return this._parseTextObjectRef(childData, childFallbackId);
-            });
+            try {
+                textObject.children = objData.children.map((childData: any, index: number) => {
+                    const childFallbackId = `${internalId || 'child'}-${index}`;
+                    return this._parseTextObjectRef(childData, childFallbackId);
+                });
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                console.error(`Failed to parse children of ${internalId}: ${message}`);
+            }
         }
 
         return textObject;
@@ -1196,6 +1697,54 @@ export class PDFDancer {
         return position;
     }
 
+    /**
+     * Parse JSON data into DocumentSnapshot instance.
+     */
+    private _parseDocumentSnapshot(data: any): DocumentSnapshot {
+        const pageCount = typeof data.pageCount === 'number' ? data.pageCount : 0;
+
+        // Parse fonts
+        const fonts: FontRecommendation[] = [];
+        if (Array.isArray(data.fonts)) {
+            for (const fontData of data.fonts) {
+                if (fontData && typeof fontData === 'object') {
+                    const fontName = fontData.fontName || '';
+                    const fontType = fontData.fontType as FontType || FontType.SYSTEM;
+                    const similarityScore = typeof fontData.similarityScore === 'number' ? fontData.similarityScore : 0;
+                    fonts.push(new FontRecommendation(fontName, fontType, similarityScore));
+                }
+            }
+        }
+
+        // Parse pages
+        const pages: PageSnapshot[] = [];
+        if (Array.isArray(data.pages)) {
+            for (const pageData of data.pages) {
+                pages.push(this._parsePageSnapshot(pageData));
+            }
+        }
+
+        return new DocumentSnapshot(pageCount, fonts, pages);
+    }
+
+    /**
+     * Parse JSON data into PageSnapshot instance.
+     */
+    private _parsePageSnapshot(data: any): PageSnapshot {
+        // Parse page reference
+        const pageRef = this._parsePageRef(data.pageRef || {});
+
+        // Parse elements
+        const elements: ObjectRef[] = [];
+        if (Array.isArray(data.elements)) {
+            for (const elementData of data.elements) {
+                elements.push(this._parseObjectRef(elementData));
+            }
+        }
+
+        return new PageSnapshot(pageRef, elements);
+    }
+
     // Builder Pattern Support
 
 
@@ -1211,8 +1760,16 @@ export class PDFDancer {
         return objectRefs.map(ref => ImageObject.fromRef(this, ref));
     }
 
-    newImage() {
-        return new ImageBuilder(this);
+    newImage(pageIndex?: number) {
+        return new ImageBuilder(this, pageIndex);
+    }
+
+    newParagraph(pageIndex?: number) {
+        return new ParagraphBuilder(this, pageIndex);
+    }
+
+    newPage() {
+        return new PageBuilder(this);
     }
 
     page(pageIndex: number) {
@@ -1231,10 +1788,28 @@ export class PDFDancer {
         return objectRefs.map(ref => FormFieldObject.fromRef(this, ref));
     }
 
+    async selectElements(types?: ObjectType[]) {
+        const snapshot = await this.getDocumentSnapshot(types);
+        const elements: ObjectRef[] = [];
+        for (const pageSnapshot of snapshot.pages) {
+            elements.push(...pageSnapshot.elements);
+        }
+        return elements;
+    }
+
     async selectParagraphs() {
         return this.toParagraphObjects(await this.findParagraphs());
     }
 
+    async selectParagraphsMatching(pattern: string) {
+        if (!pattern) {
+            throw new ValidationException('Pattern cannot be empty');
+        }
+        const position = new Position();
+        position.textPattern = pattern;
+        return this.toParagraphObjects(await this.findParagraphs(position));
+    }
+
     private toParagraphObjects(objectRefs: TextObjectRef[]) {
         return objectRefs.map(ref => ParagraphObject.fromRef(this, ref));
     }
@@ -1243,7 +1818,11 @@ export class PDFDancer {
         return objectRefs.map(ref => TextLineObject.fromRef(this, ref));
     }
 
-    async selectLines() {
+    async selectTextLines() {
         return this.toTextLineObjects(await this.findTextLines());
     }
+
+    async selectLines() {
+        return this.selectTextLines();
+    }
 }