pdfdancer-client-typescript 1.0.12 → 1.0.14

package/src/pdfdancer_v1.ts

@@ -12,6 +12,7 @@ import {
     ValidationException
 } from './exceptions';
 import {
+    AddPageRequest,
     AddRequest,
     BoundingRect,
     ChangeFormFieldRequest,
@@ -19,9 +20,10 @@ import {
     CommandResult,
     CreatePdfRequest,
     DeleteRequest,
+    DocumentSnapshot,
     FindRequest,
     Font,
-    FontRecommendation,
+    DocumentFontInfo,
     FontType,
     FormFieldRef,
     Image,
@@ -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.
@@ -226,7 +359,7 @@ export class PDFDancer {
         token: string,
         pdfData: Uint8Array | File | ArrayBuffer,
         baseUrl: string | null = null,
-        readTimeout: number = 30000
+        readTimeout: number = 60000
     ) {
 
         if (!token || !token.trim()) {
@@ -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;
     }
 
     /**
@@ -265,15 +403,15 @@ export class PDFDancer {
     }
 
     static async open(pdfData: Uint8Array, token?: string, baseUrl?: string, timeout?: number): Promise<PDFDancer> {
-        const resolvedToken = token ?? process.env.PDFDANCER_TOKEN;
         const resolvedBaseUrl =
             baseUrl ??
             process.env.PDFDANCER_BASE_URL ??
             "https://api.pdfdancer.com";
-        const resolvedTimeout = timeout ?? 30000;
+        const resolvedTimeout = timeout ?? 60000;
 
+        let resolvedToken = token?.trim() ?? process.env.PDFDANCER_TOKEN?.trim() ?? null;
         if (!resolvedToken) {
-            throw new ValidationException("Missing PDFDancer API token. Pass a token via the `token` argument or set the PDFDANCER_TOKEN environment variable.");
+            resolvedToken = await PDFDancer._obtainAnonymousToken(resolvedBaseUrl, resolvedTimeout);
         }
 
         const client = new PDFDancer(resolvedToken, pdfData, resolvedBaseUrl, resolvedTimeout);
@@ -289,7 +427,7 @@ export class PDFDancer {
      * @param options.initialPageCount Number of initial pages (default: 1)
      * @param token Authentication token (optional, can use PDFDANCER_TOKEN env var)
      * @param baseUrl Base URL for the PDFDancer API (optional)
-     * @param timeout Request timeout in milliseconds (default: 30000)
+     * @param timeout Request timeout in milliseconds (default: 60000)
      */
     static async new(
         options?: {
@@ -301,15 +439,15 @@ export class PDFDancer {
         baseUrl?: string,
         timeout?: number
     ): Promise<PDFDancer> {
-        const resolvedToken = token ?? process.env.PDFDANCER_TOKEN;
         const resolvedBaseUrl =
             baseUrl ??
             process.env.PDFDANCER_BASE_URL ??
             "https://api.pdfdancer.com";
-        const resolvedTimeout = timeout ?? 30000;
+        const resolvedTimeout = timeout ?? 60000;
 
+        let resolvedToken = token?.trim() ?? process.env.PDFDANCER_TOKEN?.trim() ?? null;
         if (!resolvedToken) {
-            throw new ValidationException("Missing PDFDancer token (pass it explicitly or set PDFDANCER_TOKEN in environment).");
+            resolvedToken = await PDFDancer._obtainAnonymousToken(resolvedBaseUrl, resolvedTimeout);
         }
 
         let createRequest: CreatePdfRequest;
@@ -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) {
@@ -368,6 +517,47 @@ export class PDFDancer {
         }
     }
 
+    private static async _obtainAnonymousToken(baseUrl: string, timeout: number = 60000): Promise<string> {
+        const normalizedBaseUrl = (baseUrl || "https://api.pdfdancer.com").replace(/\/+$/, '');
+        const url = `${normalizedBaseUrl}/keys/anon`;
+
+        try {
+            const fingerprint = await generateFingerprint();
+            const response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-Fingerprint': fingerprint,
+                    'X-Generated-At': generateTimestamp()
+                },
+                signal: timeout > 0 ? AbortSignal.timeout(timeout) : undefined
+            });
+
+            if (!response.ok) {
+                const errorText = await response.text().catch(() => '');
+                throw new HttpClientException(
+                    `Failed to obtain anonymous token: ${errorText || `HTTP ${response.status}`}`,
+                    response
+                );
+            }
+
+            const tokenPayload: any = await response.json().catch(() => null);
+            const tokenValue = typeof tokenPayload?.token === 'string' ? tokenPayload.token.trim() : '';
+
+            if (!tokenValue) {
+                throw new HttpClientException("Invalid anonymous token response format", response);
+            }
+
+            return tokenValue;
+        } catch (error) {
+            if (error instanceof HttpClientException) {
+                throw error;
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            throw new HttpClientException(`Failed to obtain anonymous token: ${errorMessage}`, undefined, error as Error);
+        }
+    }
+
     /**
      * Process PDF data from various input types with strict validation.
      */
@@ -470,15 +660,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 +706,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 +732,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 +750,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 +788,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 +885,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 +985,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 +999,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 +1037,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 +1229,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 +1250,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 +1268,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 +1317,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 +1351,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 +1359,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 +1391,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 +1458,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)
+                signal: AbortSignal.timeout(60000)
             });
 
+            logGeneratedAtHeader(response, 'POST', '/font/register');
+
             if (!response.ok) {
                 const errorMessage = await this._extractErrorMessage(response);
                 throw new HttpClientException(`Font registration failed: ${errorMessage}`, response);
@@ -1011,6 +1536,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 +1557,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);
@@ -1038,25 +1575,30 @@ export class PDFDancer {
         let status: TextStatus | undefined;
         const statusData = objData.status;
         if (statusData && typeof statusData === 'object') {
-            // Parse font recommendation
-            const fontRecData = statusData.fontRecommendation;
-            let fontRec: FontRecommendation;
-            if (fontRecData && typeof fontRecData === 'object') {
-                fontRec = new FontRecommendation(
-                    fontRecData.fontName || '',
-                    (fontRecData.fontType as FontType) || FontType.SYSTEM,
-                    fontRecData.similarityScore || 0.0
-                );
-            } else {
-                // Create empty font recommendation if not provided
-                fontRec = new FontRecommendation('', FontType.SYSTEM, 0.0);
+            const fontInfoSource = statusData.fontInfoDto ?? statusData.fontRecommendation;
+            let fontInfo: DocumentFontInfo | undefined;
+            if (fontInfoSource && typeof fontInfoSource === 'object') {
+                const documentFontName = typeof fontInfoSource.documentFontName === 'string'
+                    ? fontInfoSource.documentFontName
+                    : (typeof fontInfoSource.fontName === 'string' ? fontInfoSource.fontName : '');
+                const systemFontName = typeof fontInfoSource.systemFontName === 'string'
+                    ? fontInfoSource.systemFontName
+                    : (typeof fontInfoSource.fontName === 'string' ? fontInfoSource.fontName : '');
+                fontInfo = new DocumentFontInfo(documentFontName, systemFontName);
             }
 
+            const modified = statusData.modified !== undefined ? Boolean(statusData.modified) : false;
+            const encodable = statusData.encodable !== undefined ? Boolean(statusData.encodable) : true;
+            const fontTypeValue = typeof statusData.fontType === 'string'
+                && (Object.values(FontType) as string[]).includes(statusData.fontType)
+                ? statusData.fontType as FontType
+                : FontType.SYSTEM;
+
             status = new TextStatus(
-                statusData.modified || false,
-                statusData.encodable !== undefined ? statusData.encodable : true,
-                (statusData.fontType as FontType) || FontType.SYSTEM,
-                fontRec
+                modified,
+                encodable,
+                fontTypeValue,
+                fontInfo
             );
         }
 
@@ -1074,10 +1616,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 +1743,57 @@ 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: DocumentFontInfo[] = [];
+        if (Array.isArray(data.fonts)) {
+            for (const fontData of data.fonts) {
+                if (fontData && typeof fontData === 'object') {
+                    const documentFontName = typeof fontData.documentFontName === 'string'
+                        ? fontData.documentFontName
+                        : (typeof fontData.fontName === 'string' ? fontData.fontName : '');
+                    const systemFontName = typeof fontData.systemFontName === 'string'
+                        ? fontData.systemFontName
+                        : (typeof fontData.fontName === 'string' ? fontData.fontName : '');
+                    fonts.push(new DocumentFontInfo(documentFontName, systemFontName));
+                }
+            }
+        }
+
+        // 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 +1809,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 +1837,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 +1867,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();
+    }
 }