pdfdancer-client-python 0.2.17__py3-none-any.whl → 0.2.19__py3-none-any.whl

pdfdancer/pdfdancer_v1.py

@@ -5,23 +5,116 @@ A Python client that closely mirrors the Java Client class structure and functio
 Provides session-based PDF manipulation operations with strict validation.
 """
 
+import gzip
 import json
 import os
 import time
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import List, Optional, Union, BinaryIO, Mapping, Any
 
-import requests
+import httpx
 from dotenv import load_dotenv
 
+from .fingerprint import Fingerprint
+
 load_dotenv()
 
 # Global variable to disable SSL certificate verification
 # Set to True to skip SSL verification (useful for testing with self-signed certificates)
 # WARNING: Only use in development/testing environments
-DISABLE_SSL_VERIFY = False
+DISABLE_SSL_VERIFY = os.environ.get("PDFDANCER_CLIENT_DISABLE_SSL_VERIFY", False)
+
+DEBUG = os.environ.get("PDFDANCER_CLIENT_DEBUG", False)
+DEFAULT_TOLERANCE = 0.01
+
+
+def _generate_timestamp() -> str:
+    """
+    Generate a timestamp string in the format expected by the API.
+    Format: YYYY-MM-DDTHH:MM:SS.ffffffZ (with microseconds)
+
+    Returns:
+        Timestamp string with UTC timezone
+    """
+    return datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%S.%fZ')
+
+
+def _parse_timestamp(timestamp_str: str) -> datetime:
+    """
+    Parse timestamp string, handling both microseconds and nanoseconds precision.
+
+    Args:
+        timestamp_str: Timestamp string in format YYYY-MM-DDTHH:MM:SS.fffffffZ
+                      (with 6 or 9 fractional digits)
+
+    Returns:
+        datetime object with UTC timezone
+    """
+    # Remove the 'Z' suffix
+    ts = timestamp_str.rstrip('Z')
+
+    # Handle nanoseconds (9 digits) by truncating to microseconds (6 digits)
+    # Python's datetime only supports microseconds precision
+    if '.' in ts:
+        date_part, frac_part = ts.rsplit('.', 1)
+        if len(frac_part) > 6:
+            # Truncate to 6 digits (microseconds)
+            frac_part = frac_part[:6]
+        ts = f"{date_part}.{frac_part}"
+
+    return datetime.fromisoformat(ts).replace(tzinfo=timezone.utc)
+
+
+def _log_generated_at_header(response: httpx.Response, method: str, path: str) -> None:
+    """
+    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)
+
+    Args:
+        response: The HTTP response object
+        method: HTTP method used
+        path: API path
+    """
+    if not DEBUG:
+        return
+
+    generated_at = response.headers.get('X-Generated-At')
+    received_at = response.headers.get('X-Received-At')
+
+    if generated_at or received_at:
+        try:
+            log_parts = []
+            current_time = datetime.now(timezone.utc)
+
+            # Parse and log X-Received-At
+            received_time = None
+            if received_at:
+                received_time = _parse_timestamp(received_at)
+                time_since_received = (current_time - received_time).total_seconds()
+                log_parts.append(f"X-Received-At: {received_at}, time since received: {time_since_received:.3f}s")
+
+            # Parse and log X-Generated-At
+            generated_time = None
+            if generated_at:
+                generated_time = _parse_timestamp(generated_at)
+                time_since_generated = (current_time - generated_time).total_seconds()
+                log_parts.append(f"X-Generated-At: {generated_at}, time since generated: {time_since_generated:.3f}s")
+
+            # Calculate processing time (X-Generated-At - X-Received-At)
+            if received_time and generated_time:
+                processing_time = (generated_time - received_time).total_seconds()
+                log_parts.append(f"processing time: {processing_time:.3f}s")
+
+            if log_parts:
+                print(f"{time.time()}|{method} {path} - {', '.join(log_parts)}")
+
+        except (ValueError, AttributeError) as e:
+            print(f"{time.time()}|{method} {path} - Header parse error: {e}")
 
-DEBUG = False
 
 from . import ParagraphBuilder
 from .exceptions import (
@@ -36,7 +129,8 @@ from .models import (
     ObjectRef, Position, ObjectType, Font, Image, Paragraph, FormFieldRef, TextObjectRef, PageRef,
     FindRequest, DeleteRequest, MoveRequest, PageMoveRequest, AddRequest, ModifyRequest, ModifyTextRequest,
     ChangeFormFieldRequest, CommandResult,
-    ShapeType, PositionMode, PageSize, Orientation
+    ShapeType, PositionMode, PageSize, Orientation,
+    PageSnapshot, DocumentSnapshot, FontRecommendation, FontType
 )
 from .paragraph_builder import ParagraphPageBuilder
 from .types import PathObject, ParagraphObject, TextLineObject, ImageObject, FormObject, FormFieldObject
@@ -60,9 +154,10 @@ class PageClient:
         else:
             self.orientation = orientation
 
-    def select_paths_at(self, x: float, y: float) -> List[PathObject]:
+    def select_paths_at(self, x: float, y: float, tolerance: float = DEFAULT_TOLERANCE) -> List[PathObject]:
+        position = Position.at_page_coordinates(self.page_index, x, y)
         # noinspection PyProtectedMember
-        return self.root._to_path_objects(self.root._find_paths(Position.at_page_coordinates(self.page_index, x, y)))
+        return self.root._to_path_objects(self.root._find_paths(position, tolerance))
 
     def select_paragraphs(self) -> List[ParagraphObject]:
         # noinspection PyProtectedMember
@@ -86,10 +181,10 @@ class PageClient:
         # noinspection PyProtectedMember
         return self.root._to_textline_objects(self.root._find_text_lines(position))
 
-    def select_paragraphs_at(self, x: float, y: float) -> List[ParagraphObject]:
+    def select_paragraphs_at(self, x: float, y: float, tolerance: float = DEFAULT_TOLERANCE) -> List[ParagraphObject]:
         position = Position.at_page_coordinates(self.page_index, x, y)
         # noinspection PyProtectedMember
-        return self.root._to_paragraph_objects(self.root._find_paragraphs(position))
+        return self.root._to_paragraph_objects(self.root._find_paragraphs(position, tolerance))
 
     def select_text_lines(self) -> List[TextLineObject]:
         position = Position.at_page(self.page_index)
@@ -102,29 +197,29 @@ class PageClient:
         # noinspection PyProtectedMember
         return self.root._to_textline_objects(self.root._find_text_lines(position))
 
-    def select_text_lines_at(self, x, y) -> List[TextLineObject]:
+    def select_text_lines_at(self, x, y, tolerance: float = DEFAULT_TOLERANCE) -> List[TextLineObject]:
         position = Position.at_page_coordinates(self.page_index, x, y)
         # noinspection PyProtectedMember
-        return self.root._to_textline_objects(self.root._find_text_lines(position))
+        return self.root._to_textline_objects(self.root._find_text_lines(position, tolerance))
 
     def select_images(self) -> List[ImageObject]:
         # noinspection PyProtectedMember
         return self.root._to_image_objects(self.root._find_images(Position.at_page(self.page_index)))
 
-    def select_images_at(self, x: float, y: float) -> List[ImageObject]:
+    def select_images_at(self, x: float, y: float, tolerance: float = DEFAULT_TOLERANCE) -> List[ImageObject]:
         position = Position.at_page_coordinates(self.page_index, x, y)
         # noinspection PyProtectedMember
-        return self.root._to_image_objects(self.root._find_images(position))
+        return self.root._to_image_objects(self.root._find_images(position, tolerance))
 
     def select_forms(self) -> List[FormObject]:
         position = Position.at_page(self.page_index)
         # noinspection PyProtectedMember
         return self.root._to_form_objects(self.root._find_form_x_objects(position))
 
-    def select_forms_at(self, x: float, y: float) -> List[FormObject]:
+    def select_forms_at(self, x: float, y: float, tolerance: float = DEFAULT_TOLERANCE) -> List[FormObject]:
         position = Position.at_page_coordinates(self.page_index, x, y)
         # noinspection PyProtectedMember
-        return self.root._to_form_objects(self.root._find_form_x_objects(position))
+        return self.root._to_form_objects(self.root._find_form_x_objects(position, tolerance))
 
     def select_form_fields(self) -> List[FormFieldObject]:
         position = Position.at_page(self.page_index)
@@ -137,10 +232,10 @@ class PageClient:
         # noinspection PyProtectedMember
         return self.root._to_form_field_objects(self.root._find_form_fields(pos))
 
-    def select_form_fields_at(self, x: float, y: float) -> List[FormFieldObject]:
+    def select_form_fields_at(self, x: float, y: float, tolerance: float = DEFAULT_TOLERANCE) -> List[FormFieldObject]:
         position = Position.at_page_coordinates(self.page_index, x, y)
         # noinspection PyProtectedMember
-        return self.root._to_form_field_objects(self.root._find_form_fields(position))
+        return self.root._to_form_field_objects(self.root._find_form_fields(position, tolerance))
 
     @classmethod
     def from_ref(cls, root: 'PDFDancer', page_ref: PageRef) -> 'PageClient':
@@ -178,6 +273,18 @@ class PageClient:
     def new_paragraph(self):
         return ParagraphPageBuilder(self.root, self.page_index)
 
+    def new_path(self):
+        from .path_builder import PathBuilder
+        return PathBuilder(self.root, self.page_index)
+
+    def new_line(self):
+        from .path_builder import LineBuilder
+        return LineBuilder(self.root, self.page_index)
+
+    def new_bezier(self):
+        from .path_builder import BezierBuilder
+        return BezierBuilder(self.root, self.page_index)
+
     def select_paths(self):
         # noinspection PyProtectedMember
         return self.root._to_path_objects(self.root._find_paths(Position.at_page(self.page_index)))
@@ -229,9 +336,15 @@ class PDFDancer:
         """
         Create a client session, falling back to environment variables when needed.
 
+        Authentication:
+        - If token is provided, uses it
+        - Otherwise, checks PDFDANCER_TOKEN environment variable
+        - If no token is found, automatically obtains an anonymous token
+
         Args:
             pdf_data: PDF payload supplied directly or via filesystem handles.
-            token: Override for the API token; falls back to `PDFDANCER_TOKEN` environement variable.
+            token: Override for the API token; falls back to `PDFDANCER_TOKEN` environment variable,
+                then to anonymous token if not set.
             base_url: Override for the API base URL; falls back to `PDFDANCER_BASE_URL`
                 or defaults to `https://api.pdfdancer.com`.
             timeout: HTTP read timeout in seconds.
@@ -242,6 +355,10 @@ class PDFDancer:
         resolved_token = cls._resolve_token(token)
         resolved_base_url = cls._resolve_base_url(base_url)
 
+        # If no token found, obtain anonymous token
+        if resolved_token is None:
+            resolved_token = cls._obtain_anonymous_token(resolved_base_url, timeout)
+
         return PDFDancer(resolved_token, pdf_data, resolved_base_url, timeout)
 
     @classmethod
@@ -252,18 +369,66 @@ class PDFDancer:
             resolved_base_url = "https://api.pdfdancer.com"
         return resolved_base_url
 
+    @classmethod
+    def _obtain_anonymous_token(cls, base_url: str, timeout: float = 30.0) -> str:
+        """
+        Obtain an anonymous token from the /keys/anon endpoint.
+
+        Args:
+            base_url: Base URL of the PDFDancer API server
+            timeout: HTTP read timeout in seconds
+
+        Returns:
+            Anonymous token string
+
+        Raises:
+            HttpClientException: If token request fails
+        """
+        try:
+            # Create temporary client without authentication
+            temp_client = httpx.Client(
+                http2=True,
+                verify=not DISABLE_SSL_VERIFY
+            )
+
+            headers = {
+                'X-Fingerprint': Fingerprint.generate()
+            }
+
+            response = temp_client.post(
+                cls._cleanup_url_path(base_url, "/keys/anon"),
+                headers=headers,
+                timeout=timeout if timeout > 0 else None
+            )
+
+            response.raise_for_status()
+            token_data = response.json()
+
+            # Extract token from response (matches Java AnonTokenResponse structure)
+            if isinstance(token_data, dict) and 'token' in token_data:
+                return token_data['token']
+            else:
+                raise HttpClientException("Invalid anonymous token response format")
+
+        except httpx.HTTPStatusError as e:
+            raise HttpClientException(f"Failed to obtain anonymous token: HTTP {e.response.status_code}",
+                                      response=e.response, cause=e) from None
+        except httpx.RequestError as e:
+            raise HttpClientException(f"Failed to obtain anonymous token: {str(e)}",
+                                      response=None, cause=e) from None
+        finally:
+            temp_client.close()
+
     @classmethod
     def _resolve_token(cls, token: Optional[str]) -> Optional[str]:
+        """
+        Resolve token from argument or environment variable.
+        Returns None if no token is found (allowing fallback to anonymous token).
+        """
         resolved_token = token.strip() if token and token.strip() else None
         if resolved_token is None:
             env_token = os.getenv("PDFDANCER_TOKEN")
             resolved_token = env_token.strip() if env_token and env_token.strip() else None
-
-        if resolved_token is None:
-            raise ValidationException(
-                "Missing PDFDancer API token. Pass a token via the `token` argument "
-                "or set the PDFDANCER_TOKEN environment variable."
-            )
         return resolved_token
 
     @classmethod
@@ -277,8 +442,14 @@ class PDFDancer:
         """
         Create a new blank PDF document with optional configuration.
 
+        Authentication:
+        - If token is provided, uses it
+        - Otherwise, checks PDFDANCER_TOKEN environment variable
+        - If no token is found, automatically obtains an anonymous token
+
         Args:
-            token: Override for the API token; falls back to `PDFDANCER_TOKEN` environment variable.
+            token: Override for the API token; falls back to `PDFDANCER_TOKEN` environment variable,
+                then to anonymous token if not set.
             base_url: Override for the API base URL; falls back to `PDFDANCER_BASE_URL`
                 or defaults to `https://api.pdfdancer.com`.
             timeout: HTTP read timeout in seconds.
@@ -293,6 +464,10 @@ class PDFDancer:
         resolved_token = cls._resolve_token(token)
         resolved_base_url = cls._resolve_base_url(base_url)
 
+        # If no token found, obtain anonymous token
+        if resolved_token is None:
+            resolved_token = cls._obtain_anonymous_token(resolved_base_url, timeout)
+
         # Create a new instance that will call _create_blank_pdf_session
         instance = object.__new__(cls)
 
@@ -304,11 +479,12 @@ class PDFDancer:
         instance._base_url = resolved_base_url.rstrip('/')
         instance._read_timeout = timeout
 
-        # Create HTTP session for connection reuse
-        instance._session = requests.Session()
-        instance._session.headers.update({
-            'Authorization': f'Bearer {instance._token}'
-        })
+        # Create HTTP client for connection reuse with HTTP/2 support
+        instance._client = httpx.Client(
+            http2=True,
+            headers={'Authorization': f'Bearer {instance._token}'},
+            verify=not DISABLE_SSL_VERIFY
+        )
 
         # Create blank PDF session
         instance._session_id = instance._create_blank_pdf_session(
@@ -320,6 +496,10 @@ class PDFDancer:
         # Set pdf_bytes to None since we don't have the PDF bytes yet
         instance._pdf_bytes = None
 
+        # Initialize snapshot caches (lazy-loaded)
+        instance._document_snapshot = None
+        instance._page_snapshots = {}
+
         return instance
 
     def __init__(self, token: str, pdf_data: Union[bytes, Path, str, BinaryIO],
@@ -351,15 +531,20 @@ class PDFDancer:
         # Process PDF data with validation
         self._pdf_bytes = self._process_pdf_data(pdf_data)
 
-        # Create HTTP session for connection reuse
-        self._session = requests.Session()
-        self._session.headers.update({
-            'Authorization': f'Bearer {self._token}'
-        })
+        # Create HTTP client for connection reuse with HTTP/2 support
+        self._client = httpx.Client(
+            http2=True,
+            headers={'Authorization': f'Bearer {self._token}'},
+            verify=not DISABLE_SSL_VERIFY
+        )
 
         # Create session - equivalent to Java constructor behavior
         self._session_id = self._create_session()
 
+        # Initialize snapshot caches (lazy-loaded)
+        self._document_snapshot: Optional[DocumentSnapshot] = None
+        self._page_snapshots: dict[int, PageSnapshot] = {}
+
     @staticmethod
     def _process_pdf_data(pdf_data: Union[bytes, Path, str, BinaryIO]) -> bytes:
         """
@@ -401,7 +586,7 @@ class PDFDancer:
         except (IOError, OSError) as e:
             raise PdfDancerException(f"Failed to read PDF data: {e}", cause=e)
 
-    def _extract_error_message(self, response: Optional[requests.Response]) -> str:
+    def _extract_error_message(self, response: Optional[httpx.Response]) -> str:
         """
         Extract meaningful error messages from API response.
         Parses JSON error responses with _embedded.errors structure.
@@ -437,7 +622,7 @@ class PDFDancer:
             # If JSON parsing fails, return response content or status
             return response.text or f"HTTP {response.status_code}"
 
-    def _handle_authentication_error(self, response: Optional[requests.Response]) -> None:
+    def _handle_authentication_error(self, response: Optional[httpx.Response]) -> None:
         """
         Translate authentication failures into a clear, actionable validation error.
         """
@@ -474,25 +659,54 @@ class PDFDancer:
         Creates a new PDF processing session by uploading the PDF data.
         """
         try:
-            files = {
-                'pdf': ('document.pdf', self._pdf_bytes, 'application/pdf')
-            }
+            # Build multipart body manually to avoid base64 encoding and enable compression
+            # httpx by default may add Content-Transfer-Encoding: base64 which the server rejects
+            import uuid
+
+            boundary = uuid.uuid4().hex
+
+            # Build multipart body with binary (not base64) encoding
+            body_parts = []
+            body_parts.append(f'--{boundary}\r\n'.encode('utf-8'))
+            body_parts.append(b'Content-Disposition: form-data; name="pdf"; filename="document.pdf"\r\n')
+            body_parts.append(b'Content-Type: application/pdf\r\n')
+            body_parts.append(b'\r\n')  # End of headers, no Content-Transfer-Encoding
+            body_parts.append(self._pdf_bytes)
+            body_parts.append(b'\r\n')
+            body_parts.append(f'--{boundary}--\r\n'.encode('utf-8'))
+
+            uncompressed_body = b''.join(body_parts)
+
+            # Compress entire request body using gzip
+            compressed_body = gzip.compress(uncompressed_body)
+
+            original_size = len(uncompressed_body)
+            compressed_size = len(compressed_body)
+            compression_ratio = (1 - compressed_size / original_size) * 100 if original_size > 0 else 0
 
-            request_size = len(self._pdf_bytes)
             if DEBUG:
-                print(f"{time.time()}|POST /session/create - request size: {request_size} bytes")
+                print(f"{time.time()}|POST /session/create - original size: {original_size} bytes, "
+                      f"compressed size: {compressed_size} bytes, "
+                      f"compression: {compression_ratio:.1f}%")
+
+            headers = {
+                'X-Generated-At': _generate_timestamp(),
+                'Content-Type': f'multipart/form-data; boundary={boundary}',
+                'Content-Encoding': 'gzip'
+            }
 
-            response = self._session.post(
+            response = self._client.post(
                 self._cleanup_url_path(self._base_url, "/session/create"),
-                files=files,
-                timeout=self._read_timeout if self._read_timeout > 0 else None,
-                verify=not DISABLE_SSL_VERIFY
+                content=compressed_body,
+                headers=headers,
+                timeout=self._read_timeout if self._read_timeout > 0 else None
             )
 
             response_size = len(response.content)
             if DEBUG:
                 print(f"{time.time()}|POST /session/create - response size: {response_size} bytes")
 
+            _log_generated_at_header(response, "POST", "/session/create")
             self._handle_authentication_error(response)
             response.raise_for_status()
             session_id = response.text.strip()
@@ -502,11 +716,14 @@ class PDFDancer:
 
             return session_id
 
-        except requests.exceptions.RequestException as e:
-            self._handle_authentication_error(getattr(e, 'response', None))
-            error_message = self._extract_error_message(getattr(e, 'response', None))
+        except httpx.HTTPStatusError as e:
+            self._handle_authentication_error(e.response)
+            error_message = self._extract_error_message(e.response)
             raise HttpClientException(f"Failed to create session: {error_message}",
-                                      response=getattr(e, 'response', None), cause=e) from None
+                                      response=e.response, cause=e) from None
+        except httpx.RequestError as e:
+            raise HttpClientException(f"Failed to create session: {str(e)}",
+                                      response=None, cause=e) from None
 
     def _create_blank_pdf_session(self,
                                   page_size: Optional[Union[PageSize, str, Mapping[str, Any]]] = None,
@@ -560,19 +777,22 @@ class PDFDancer:
             if DEBUG:
                 print(f"{time.time()}|POST /session/new - request size: {request_size} bytes")
 
-            headers = {'Content-Type': 'application/json'}
-            response = self._session.post(
+            headers = {
+                'Content-Type': 'application/json',
+                'X-Generated-At': _generate_timestamp()
+            }
+            response = self._client.post(
                 self._cleanup_url_path(self._base_url, "/session/new"),
                 json=request_data,
                 headers=headers,
-                timeout=self._read_timeout if self._read_timeout > 0 else None,
-                verify=not DISABLE_SSL_VERIFY
+                timeout=self._read_timeout if self._read_timeout > 0 else None
             )
 
             response_size = len(response.content)
             if DEBUG:
                 print(f"{time.time()}|POST /session/new - response size: {response_size} bytes")
 
+            _log_generated_at_header(response, "POST", "/session/new")
             self._handle_authentication_error(response)
             response.raise_for_status()
             session_id = response.text.strip()
@@ -582,20 +802,25 @@ class PDFDancer:
 
             return session_id
 
-        except requests.exceptions.RequestException as e:
-            self._handle_authentication_error(getattr(e, 'response', None))
-            error_message = self._extract_error_message(getattr(e, 'response', None))
+        except httpx.HTTPStatusError as e:
+            self._handle_authentication_error(e.response)
+            error_message = self._extract_error_message(e.response)
             raise HttpClientException(f"Failed to create blank PDF session: {error_message}",
-                                      response=getattr(e, 'response', None), cause=e) from None
+                                      response=e.response, cause=e) from None
+        except httpx.RequestError as e:
+            raise HttpClientException(f"Failed to create blank PDF session: {str(e)}",
+                                      response=None, cause=e) from None
 
     def _make_request(self, method: str, path: str, data: Optional[dict] = None,
-                      params: Optional[dict] = None) -> requests.Response:
+                      params: Optional[dict] = None) -> httpx.Response:
         """
         Make HTTP request with session headers and error handling.
         """
         headers = {
             'X-Session-Id': self._session_id,
-            'Content-Type': 'application/json'
+            'Content-Type': 'application/json',
+            'X-Generated-At': _generate_timestamp(),
+            'X-Fingerprint': Fingerprint.generate()
         }
 
         try:
@@ -606,20 +831,21 @@ class PDFDancer:
             if DEBUG:
                 print(f"{time.time()}|{method} {path} - request size: {request_size} bytes")
 
-            response = self._session.request(
+            response = self._client.request(
                 method=method,
                 url=self._cleanup_url_path(self._base_url, path),
                 json=data,
                 params=params,
                 headers=headers,
-                timeout=self._read_timeout if self._read_timeout > 0 else None,
-                verify=not DISABLE_SSL_VERIFY
+                timeout=self._read_timeout if self._read_timeout > 0 else None
             )
 
             response_size = len(response.content)
             if DEBUG:
                 print(f"{time.time()}|{method} {path} - response size: {response_size} bytes")
 
+            _log_generated_at_header(response, method, path)
+
             # Handle FontNotFoundException
             if response.status_code == 404:
                 try:
@@ -633,53 +859,86 @@ class PDFDancer:
             response.raise_for_status()
             return response
 
-        except requests.exceptions.RequestException as e:
-            self._handle_authentication_error(getattr(e, 'response', None))
-            error_message = self._extract_error_message(getattr(e, 'response', None))
-            raise HttpClientException(f"API request failed: {error_message}", response=getattr(e, 'response', None),
+        except httpx.HTTPStatusError as e:
+            self._handle_authentication_error(e.response)
+            error_message = self._extract_error_message(e.response)
+            raise HttpClientException(f"API request failed: {error_message}", response=e.response,
+                                      cause=e) from None
+        except httpx.RequestError as e:
+            raise HttpClientException(f"API request failed: {str(e)}", response=None,
                                       cause=e) from None
 
-    def _find(self, object_type: Optional[ObjectType] = None, position: Optional[Position] = None) -> List[ObjectRef]:
+    def _find(self, object_type: Optional[ObjectType] = None, position: Optional[Position] = None,
+              tolerance: float = DEFAULT_TOLERANCE) -> List[ObjectRef]:
         """
         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.
+        Uses snapshot cache for all queries except paths at specific coordinates.
 
         Args:
             object_type: The type of objects to find (None for all types)
             position: Positional constraints for the search (None for all positions)
+            tolerance: Tolerance in points for spatial matching (default: DEFAULT_TOLERANCE)
 
         Returns:
             List of object references matching the search criteria
         """
-        request_data = FindRequest(object_type, position).to_dict()
-        response = self._make_request('POST', '/pdf/find', data=request_data)
-
-        # Parse response into ObjectRef objects
-        objects_data = response.json()
-        return [self._parse_object_ref(obj_data) for obj_data in objects_data]
+        # Special case: PATH queries with bounding_rect need API (full vector data)
+        if object_type == ObjectType.PATH and position and position.bounding_rect:
+            request_data = FindRequest(object_type, position).to_dict()
+            response = self._make_request('POST', '/pdf/find', data=request_data)
+            objects_data = response.json()
+            return [self._parse_object_ref(obj_data) for obj_data in objects_data]
+
+        # Use snapshot for all other queries
+        if position and position.page_index is not None:
+            snapshot = self._get_or_fetch_page_snapshot(position.page_index)
+            return self._filter_snapshot_elements(snapshot.elements, object_type, position, tolerance)
+        else:
+            snapshot = self._get_or_fetch_document_snapshot()
+            all_elements = []
+            for page_snap in snapshot.pages:
+                all_elements.extend(page_snap.elements)
+            return self._filter_snapshot_elements(all_elements, object_type, position, tolerance)
 
-    def select_paragraphs(self) -> List[TextObjectRef]:
+    def select_paragraphs(self) -> List[ParagraphObject]:
         """
-        Searches for paragraph objects returning TextObjectRef with hierarchical structure.
+        Searches for paragraph objects returning ParagraphObject instances.
         """
-        return self._find_paragraphs(None)
+        return self._to_paragraph_objects(self._find_paragraphs(None))
 
-    def _find_paragraphs(self, position: Optional[Position] = None) -> List[TextObjectRef]:
+    def _find_paragraphs(self, position: Optional[Position] = None, tolerance: float = DEFAULT_TOLERANCE) -> List[
+        TextObjectRef]:
         """
         Searches for paragraph objects returning TextObjectRef with hierarchical structure.
+        Uses snapshot cache for all queries.
         """
-        request_data = FindRequest(ObjectType.PARAGRAPH, position).to_dict()
-        response = self._make_request('POST', '/pdf/find', data=request_data)
-
-        objects_data = response.json()
-        return [self._parse_text_object_ref(obj_data) for obj_data in objects_data]
+        # Use snapshot for all queries (including spatial)
+        if position and position.page_index is not None:
+            snapshot = self._get_or_fetch_page_snapshot(position.page_index)
+            return self._filter_snapshot_elements(snapshot.elements, ObjectType.PARAGRAPH, position, tolerance)
+        else:
+            snapshot = self._get_or_fetch_document_snapshot()
+            all_elements = []
+            for page_snap in snapshot.pages:
+                all_elements.extend(page_snap.elements)
+            return self._filter_snapshot_elements(all_elements, ObjectType.PARAGRAPH, position, tolerance)
 
-    def _find_images(self, position: Optional[Position] = None) -> List[ObjectRef]:
+    def _find_images(self, position: Optional[Position] = None, tolerance: float = DEFAULT_TOLERANCE) -> List[
+        ObjectRef]:
         """
         Searches for image objects at the specified position.
+        Uses snapshot cache for all queries.
         """
-        return self._find(ObjectType.IMAGE, position)
+        # Use snapshot for all queries (including spatial)
+        if position and position.page_index is not None:
+            snapshot = self._get_or_fetch_page_snapshot(position.page_index)
+            return self._filter_snapshot_elements(snapshot.elements, ObjectType.IMAGE, position, tolerance)
+        else:
+            snapshot = self._get_or_fetch_document_snapshot()
+            all_elements = []
+            for page_snap in snapshot.pages:
+                all_elements.extend(page_snap.elements)
+            return self._filter_snapshot_elements(all_elements, ObjectType.IMAGE, position, tolerance)
 
     def select_images(self) -> List[ImageObject]:
         """
@@ -693,11 +952,22 @@ class PDFDancer:
         """
         return self._to_form_objects(self._find(ObjectType.FORM_X_OBJECT, None))
 
-    def _find_form_x_objects(self, position: Optional[Position] = None) -> List[ObjectRef]:
+    def _find_form_x_objects(self, position: Optional[Position] = None, tolerance: float = DEFAULT_TOLERANCE) -> List[
+        ObjectRef]:
         """
-        Searches for form field objects at the specified position.
+        Searches for form X objects at the specified position.
+        Uses snapshot cache for all queries.
         """
-        return self._find(ObjectType.FORM_X_OBJECT, position)
+        # Use snapshot for all queries (including spatial)
+        if position and position.page_index is not None:
+            snapshot = self._get_or_fetch_page_snapshot(position.page_index)
+            return self._filter_snapshot_elements(snapshot.elements, ObjectType.FORM_X_OBJECT, position, tolerance)
+        else:
+            snapshot = self._get_or_fetch_document_snapshot()
+            all_elements = []
+            for page_snap in snapshot.pages:
+                all_elements.extend(page_snap.elements)
+            return self._filter_snapshot_elements(all_elements, ObjectType.FORM_X_OBJECT, position, tolerance)
 
     def select_form_fields(self) -> List[FormFieldObject]:
         """
@@ -711,17 +981,23 @@ class PDFDancer:
         """
         return self._to_form_field_objects(self._find_form_fields(Position.by_name(field_name)))
 
-    def _find_form_fields(self, position: Optional[Position] = None) -> List[FormFieldRef]:
+    def _find_form_fields(self, position: Optional[Position] = None, tolerance: float = DEFAULT_TOLERANCE) -> List[
+        FormFieldRef]:
         """
         Searches for form fields at the specified position.
         Returns FormFieldRef objects with name and value properties.
+        Uses snapshot cache for all queries (including name and spatial filtering).
         """
-        request_data = FindRequest(ObjectType.FORM_FIELD, position).to_dict()
-        response = self._make_request('POST', '/pdf/find', data=request_data)
-
-        # Parse response into ObjectRef objects
-        objects_data = response.json()
-        return [self._parse_form_field_ref(obj_data) for obj_data in objects_data]
+        # Use snapshot for all queries (including name and spatial)
+        if position and position.page_index is not None:
+            snapshot = self._get_or_fetch_page_snapshot(position.page_index)
+            return self._filter_snapshot_elements(snapshot.elements, ObjectType.FORM_FIELD, position, tolerance)
+        else:
+            snapshot = self._get_or_fetch_document_snapshot()
+            all_elements = []
+            for page_snap in snapshot.pages:
+                all_elements.extend(page_snap.elements)
+            return self._filter_snapshot_elements(all_elements, ObjectType.FORM_FIELD, position, tolerance)
 
     def _change_form_field(self, form_field_ref: FormFieldRef, new_value: str) -> bool:
         """
@@ -730,9 +1006,12 @@ class PDFDancer:
         if form_field_ref is None:
             raise ValidationException("Form field reference cannot be null")
 
-        request_data = ChangeFormFieldRequest(form_field_ref, new_value).to_dict()
-        response = self._make_request('PUT', '/pdf/modify/formField', data=request_data)
-        return response.json()
+        try:
+            request_data = ChangeFormFieldRequest(form_field_ref, new_value).to_dict()
+            response = self._make_request('PUT', '/pdf/modify/formField', data=request_data)
+            return response.json()
+        finally:
+            self._invalidate_snapshots()
 
     def select_paths(self) -> List[ObjectRef]:
         """
@@ -740,21 +1019,45 @@ class PDFDancer:
         """
         return self._find(ObjectType.PATH, None)
 
-    def _find_paths(self, position: Optional[Position] = None) -> List[ObjectRef]:
+    def _find_paths(self, position: Optional[Position] = None, tolerance: float = DEFAULT_TOLERANCE) -> List[ObjectRef]:
         """
         Searches for vector path objects at the specified position.
-        """
-        return self._find(ObjectType.PATH, position)
+        Note: Spatial queries (with bounding_rect) fall back to API since snapshots
+        don't include full vector path data needed for precise intersection tests.
+        """
+        # Special case: paths at specific coordinates need full vector data
+        # which is not available in snapshots, so pass through to API
+        if position and position.bounding_rect:
+            return self._find(ObjectType.PATH, position, tolerance)
+
+        # For simple page-level "all paths" queries, use snapshot
+        if position and position.page_index is not None:
+            snapshot = self._get_or_fetch_page_snapshot(position.page_index)
+            return self._filter_snapshot_elements(snapshot.elements, ObjectType.PATH, position, tolerance)
+        else:
+            # Document-level query - use document snapshot
+            snapshot = self._get_or_fetch_document_snapshot()
+            all_elements = []
+            for page_snap in snapshot.pages:
+                all_elements.extend(page_snap.elements)
+            return self._filter_snapshot_elements(all_elements, ObjectType.PATH, position, tolerance)
 
-    def _find_text_lines(self, position: Optional[Position] = None) -> List[TextObjectRef]:
+    def _find_text_lines(self, position: Optional[Position] = None, tolerance: float = DEFAULT_TOLERANCE) -> List[
+        TextObjectRef]:
         """
         Searches for text line objects returning TextObjectRef with hierarchical structure.
+        Uses snapshot cache for all queries.
         """
-        request_data = FindRequest(ObjectType.TEXT_LINE, position).to_dict()
-        response = self._make_request('POST', '/pdf/find', data=request_data)
-
-        objects_data = response.json()
-        return [self._parse_text_object_ref(obj_data) for obj_data in objects_data]
+        # Use snapshot for all queries (including spatial)
+        if position and position.page_index is not None:
+            snapshot = self._get_or_fetch_page_snapshot(position.page_index)
+            return self._filter_snapshot_elements(snapshot.elements, ObjectType.TEXT_LINE, position, tolerance)
+        else:
+            snapshot = self._get_or_fetch_document_snapshot()
+            all_elements = []
+            for page_snap in snapshot.pages:
+                all_elements.extend(page_snap.elements)
+            return self._filter_snapshot_elements(all_elements, ObjectType.TEXT_LINE, position, tolerance)
 
     def select_text_lines(self) -> List[TextLineObject]:
         """
@@ -764,7 +1067,7 @@ class PDFDancer:
 
     def page(self, page_index: int) -> PageClient:
         """
-        Get a specific page by index, fetching page properties from the server.
+        Get a specific page by index, using snapshot cache when available.
 
         Args:
             page_index: The 0-based page index
@@ -772,11 +1075,16 @@ class PDFDancer:
         Returns:
             PageClient with page properties populated
         """
+        # Try to get page ref from snapshot first (avoids API call)
+        page_snapshot = self._get_or_fetch_page_snapshot(page_index)
+        if page_snapshot and page_snapshot.page_ref:
+            return PageClient.from_ref(self, page_snapshot.page_ref)
+
+        # Fallback to API if snapshot doesn't have page ref
         page_ref = self._get_page(page_index)
         if page_ref:
             return PageClient.from_ref(self, page_ref)
         else:
-            # Fallback to basic PageClient if page not found
             return PageClient(page_index, self)
 
     # Page Operations
@@ -786,11 +1094,11 @@ class PDFDancer:
 
     def _get_pages(self) -> List[PageRef]:
         """
-        Retrieves references to all pages in the PDF document.
+        Retrieves references to all pages in the PDF document using snapshot cache.
         """
-        response = self._make_request('POST', '/pdf/page/find')
-        pages_data = response.json()
-        return [self._parse_page_ref(page_data) for page_data in pages_data]
+        # Use document snapshot which includes all pages (avoids API call)
+        doc_snapshot = self._get_or_fetch_document_snapshot()
+        return [page_snap.page_ref for page_snap in doc_snapshot.pages]
 
     def _get_page(self, page_index: int) -> Optional[PageRef]:
         """
@@ -830,7 +1138,13 @@ class PDFDancer:
         request_data = page_ref.to_dict()
 
         response = self._make_request('DELETE', '/pdf/page/delete', data=request_data)
-        return response.json()
+        result = response.json()
+
+        # Invalidate snapshot caches after mutation
+        if result:
+            self._invalidate_snapshots()
+
+        return result
 
     def move_page(self, from_page_index: int, to_page_index: int) -> bool:
         """Move a page to a different index within the document."""
@@ -849,6 +1163,11 @@ class PDFDancer:
         request_data = PageMoveRequest(from_page_index, to_page_index).to_dict()
         response = self._make_request('PUT', '/pdf/page/move', data=request_data)
         result = response.json()
+
+        # Invalidate snapshot caches after mutation
+        if result:
+            self._invalidate_snapshots()
+
         return bool(result)
 
     # Manipulation Operations
@@ -868,7 +1187,13 @@ class PDFDancer:
 
         request_data = DeleteRequest(object_ref).to_dict()
         response = self._make_request('DELETE', '/pdf/delete', data=request_data)
-        return response.json()
+        result = response.json()
+
+        # Invalidate snapshot caches after mutation
+        if result:
+            self._invalidate_snapshots()
+
+        return result
 
     def _move(self, object_ref: ObjectRef, position: Position) -> bool:
         """
@@ -888,7 +1213,13 @@ class PDFDancer:
 
         request_data = MoveRequest(object_ref, position).to_dict()
         response = self._make_request('PUT', '/pdf/move', data=request_data)
-        return response.json()
+        result = response.json()
+
+        # Invalidate snapshot caches after mutation
+        if result:
+            self._invalidate_snapshots()
+
+        return result
 
     # Add Operations
 
@@ -935,24 +1266,58 @@ class PDFDancer:
 
         return self._add_object(paragraph)
 
+    def _add_path(self, path: 'Path') -> bool:
+        """
+        Internal method to add a path to the document after validation.
+        """
+        from .models import Path as PathModel
+
+        if path is None:
+            raise ValidationException("Path cannot be null")
+        if path.get_position() is None:
+            raise ValidationException("Path position is null")
+        if path.get_position().page_index is None:
+            raise ValidationException("Path position page index is null")
+        if path.get_position().page_index < 0:
+            raise ValidationException("Path position page index is less than 0")
+        if not path.get_path_segments() or len(path.get_path_segments()) == 0:
+            raise ValidationException("Path must have at least one segment")
+
+        return self._add_object(path)
+
     def _add_object(self, pdf_object) -> bool:
         """
         Internal method to add any PDF object.
         """
         request_data = AddRequest(pdf_object).to_dict()
         response = self._make_request('POST', '/pdf/add', data=request_data)
-        return response.json()
+        result = response.json()
+
+        # Invalidate snapshot caches after mutation
+        if result:
+            self._invalidate_snapshots()
+
+        return result
 
     def new_paragraph(self) -> ParagraphBuilder:
         return ParagraphBuilder(self)
 
     def new_page(self):
         response = self._make_request('POST', '/pdf/page/add', data=None)
-        return self._parse_page_ref(response.json())
+        result = self._parse_page_ref(response.json())
+
+        # Invalidate snapshot caches after adding page
+        self._invalidate_snapshots()
+
+        return result
 
     def new_image(self) -> ImageBuilder:
         return ImageBuilder(self)
 
+    def new_path(self) -> 'PathBuilder':
+        from .path_builder import PathBuilder
+        return PathBuilder(self)
+
     # Modify Operations
     def _modify_paragraph(self, object_ref: ObjectRef, new_paragraph: Union[Paragraph, str]) -> CommandResult:
         """
@@ -974,12 +1339,16 @@ class PDFDancer:
             # Text modification - returns CommandResult
             request_data = ModifyTextRequest(object_ref, new_paragraph).to_dict()
             response = self._make_request('PUT', '/pdf/text/paragraph', data=request_data)
-            return CommandResult.from_dict(response.json())
+            result = CommandResult.from_dict(response.json())
         else:
             # Object modification
             request_data = ModifyRequest(object_ref, new_paragraph).to_dict()
             response = self._make_request('PUT', '/pdf/modify', data=request_data)
-            return CommandResult.from_dict(response.json())
+            result = CommandResult.from_dict(response.json())
+
+        # Invalidate snapshot caches after mutation
+        self._invalidate_snapshots()
+        return result
 
     def _modify_text_line(self, object_ref: ObjectRef, new_text: str) -> CommandResult:
         """
@@ -999,7 +1368,11 @@ class PDFDancer:
 
         request_data = ModifyTextRequest(object_ref, new_text).to_dict()
         response = self._make_request('PUT', '/pdf/text/line', data=request_data)
-        return CommandResult.from_dict(response.json())
+        result = CommandResult.from_dict(response.json())
+
+        # Invalidate snapshot caches after mutation
+        self._invalidate_snapshots()
+        return result
 
     # Font Operations
 
@@ -1083,31 +1456,220 @@ class PDFDancer:
             if DEBUG:
                 print(f"{time.time()}|POST /font/register - request size: {request_size} bytes")
 
-            headers = {'X-Session-Id': self._session_id}
-            response = self._session.post(
+            headers = {
+                'X-Session-Id': self._session_id,
+                'X-Generated-At': _generate_timestamp()
+            }
+            response = self._client.post(
                 self._cleanup_url_path(self._base_url, "/font/register"),
                 files=files,
                 headers=headers,
-                timeout=30,
-                verify=not DISABLE_SSL_VERIFY
+                timeout=30
             )
 
             response_size = len(response.content)
             if DEBUG:
                 print(f"{time.time()}|POST /font/register - response size: {response_size} bytes")
 
+            _log_generated_at_header(response, "POST", "/font/register")
             response.raise_for_status()
             return response.text.strip()
 
         except (IOError, OSError) as e:
             raise PdfDancerException(f"Failed to read font file: {e}", cause=e)
-        except requests.exceptions.RequestException as e:
-            error_message = self._extract_error_message(getattr(e, 'response', None))
+        except httpx.HTTPStatusError as e:
+            error_message = self._extract_error_message(e.response)
             raise HttpClientException(f"Font registration failed: {error_message}",
-                                      response=getattr(e, 'response', None), cause=e) from None
+                                      response=e.response, cause=e) from None
+        except httpx.RequestError as e:
+            raise HttpClientException(f"Font registration failed: {str(e)}",
+                                      response=None, cause=e) from None
 
     # Document Operations
 
+    # Snapshot Operations
+
+    def get_document_snapshot(self, types: Optional[str] = None) -> DocumentSnapshot:
+        """
+        Retrieve a snapshot of the entire document with all pages and elements.
+
+        Args:
+            types: Optional comma-separated string of object types to filter (e.g., "PARAGRAPH,IMAGE")
+
+        Returns:
+            DocumentSnapshot containing page count, fonts, and all page snapshots
+        """
+        params = {}
+        if types:
+            params['types'] = types
+
+        response = self._make_request('GET', '/pdf/document/snapshot', params=params)
+        data = response.json()
+
+        return self._parse_document_snapshot(data)
+
+    def get_page_snapshot(self, page_index: int, types: Optional[str] = None) -> PageSnapshot:
+        """
+        Retrieve a snapshot of a specific page with all its elements.
+
+        Args:
+            page_index: The index of the page to snapshot (0-based)
+            types: Optional comma-separated string of object types to filter (e.g., "PARAGRAPH,IMAGE")
+
+        Returns:
+            PageSnapshot containing page reference and all elements on that page
+        """
+        if page_index < 0:
+            raise ValidationException(f"Page index must be >= 0, got {page_index}")
+
+        params = {}
+        if types:
+            params['types'] = types
+
+        response = self._make_request('GET', f'/pdf/page/{page_index}/snapshot', params=params)
+        data = response.json()
+
+        return self._parse_page_snapshot(data)
+
+    def _get_or_fetch_document_snapshot(self) -> DocumentSnapshot:
+        """
+        Get document snapshot from cache or fetch if not cached.
+        This is used internally by select_* methods for optimization.
+        Also caches individual page snapshots from the document snapshot.
+        """
+        if self._document_snapshot is None:
+            self._document_snapshot = self.get_document_snapshot()
+            # Cache individual page snapshots from document snapshot
+            for i, page_snapshot in enumerate(self._document_snapshot.pages):
+                if i not in self._page_snapshots:
+                    self._page_snapshots[i] = page_snapshot
+        return self._document_snapshot
+
+    def _get_or_fetch_page_snapshot(self, page_index: int) -> PageSnapshot:
+        """
+        Get page snapshot from cache or fetch if not cached.
+        This is used internally by select_* methods for optimization.
+        If document snapshot exists, uses page from it instead of making separate API call.
+        """
+        # Check if already cached
+        if page_index in self._page_snapshots:
+            return self._page_snapshots[page_index]
+
+        # If document snapshot exists, get page from it (no API call needed)
+        if self._document_snapshot is not None:
+            if 0 <= page_index < len(self._document_snapshot.pages):
+                page_snapshot = self._document_snapshot.pages[page_index]
+                self._page_snapshots[page_index] = page_snapshot
+                return page_snapshot
+
+        # Otherwise fetch page snapshot individually
+        self._page_snapshots[page_index] = self.get_page_snapshot(page_index)
+        return self._page_snapshots[page_index]
+
+    def _invalidate_snapshots(self) -> None:
+        """
+        Clear all snapshot caches.
+        Called after mutations (delete, move, modify) to ensure fresh data on next select.
+        """
+        self._document_snapshot = None
+        self._page_snapshots.clear()
+
+    def _filter_snapshot_elements(self, elements: List, object_type: ObjectType,
+                                  position: Optional[Position] = None, tolerance: float = DEFAULT_TOLERANCE) -> List:
+        """
+        Filter snapshot elements client-side based on object type and position criteria.
+
+        Args:
+            elements: List of elements from snapshot (ObjectRef, TextObjectRef, etc.)
+            object_type: Type to filter for
+            position: Optional position filter with text matching, bounding rect, etc.
+            tolerance: Tolerance in points for spatial matching (default: 10.0)
+
+        Returns:
+            Filtered list of elements matching the criteria
+        """
+        import re
+
+        # Filter by object type (handle form field subtypes)
+        if object_type == ObjectType.FORM_FIELD:
+            # Form fields include TEXT_FIELD, CHECK_BOX, RADIO_BUTTON, BUTTON, DROPDOWN
+            form_field_types = {ObjectType.FORM_FIELD, ObjectType.TEXT_FIELD,
+                                ObjectType.CHECK_BOX, ObjectType.RADIO_BUTTON,
+                                ObjectType.BUTTON, ObjectType.DROPDOWN}
+            filtered = [e for e in elements if e.type in form_field_types]
+        else:
+            filtered = [e for e in elements if e.type == object_type]
+
+        if position is None:
+            return filtered
+
+        # Apply position filters
+        result = filtered
+
+        # Text starts with filter (case-insensitive to match API behavior)
+        if position.text_starts_with:
+            search_text = position.text_starts_with.lower()
+            result = [
+                e for e in result
+                if isinstance(e, TextObjectRef) and e.text and e.text.lower().startswith(search_text)
+            ]
+
+        # Regex pattern filter
+        if position.text_pattern:
+            pattern = re.compile(position.text_pattern)
+            result = [
+                e for e in result
+                if isinstance(e, TextObjectRef) and e.text and pattern.search(e.text)
+            ]
+
+        # Bounding rect filter (spatial queries like at(x, y))
+        if position.bounding_rect:
+            rect = position.bounding_rect
+            result = [
+                e for e in result
+                if e.position and e.position.bounding_rect and
+                   self._rects_intersect(e.position.bounding_rect, rect, tolerance)
+            ]
+
+        # Name filter (for form fields)
+        if position.name:
+            from .models import FormFieldRef
+            result = [
+                e for e in result
+                if isinstance(e, FormFieldRef) and e.name == position.name
+            ]
+
+        return result
+
+    @staticmethod
+    def _rects_intersect(rect1, rect2, tolerance: float = DEFAULT_TOLERANCE) -> bool:
+        """
+        Check if two bounding rectangles intersect or are very close.
+        Handles point queries (width/height = 0) with tolerance.
+
+        Args:
+            rect1: First bounding rectangle
+            rect2: Second bounding rectangle
+            tolerance: Tolerance in points for position matching (default: 10.0)
+        """
+        # Get effective bounds with tolerance
+        r1_left = rect1.x - tolerance
+        r1_right = rect1.x + rect1.width + tolerance
+        r1_top = rect1.y - tolerance
+        r1_bottom = rect1.y + rect1.height + tolerance
+
+        r2_left = rect2.x - tolerance
+        r2_right = rect2.x + rect2.width + tolerance
+        r2_top = rect2.y - tolerance
+        r2_bottom = rect2.y + rect2.height + tolerance
+
+        # Check if rectangles overlap
+        if r1_right < r2_left or r2_right < r1_left:
+            return False
+        if r1_bottom < r2_top or r2_bottom < r1_top:
+            return False
+        return True
+
     def get_bytes(self) -> bytes:
         """
         Downloads the current state of the PDF document with all modifications applied.
@@ -1298,6 +1860,175 @@ class PDFDancer:
             orientation=orientation
         )
 
+    def _parse_path_segment(self, segment_data: dict) -> 'PathSegment':
+        """Parse JSON data into PathSegment instance (Line or Bezier)."""
+        from .models import Line, Bezier, PathSegment, Point, Color
+
+        segment_type = segment_data.get('segmentType', segment_data.get('type', '')).upper()
+
+        # Parse common properties
+        stroke_color = None
+        stroke_color_data = segment_data.get('strokeColor')
+        if isinstance(stroke_color_data, dict):
+            r = stroke_color_data.get('red', 0)
+            g = stroke_color_data.get('green', 0)
+            b = stroke_color_data.get('blue', 0)
+            a = stroke_color_data.get('alpha', 255)
+            if all(isinstance(v, int) for v in [r, g, b]):
+                stroke_color = Color(r, g, b, a)
+
+        fill_color = None
+        fill_color_data = segment_data.get('fillColor')
+        if isinstance(fill_color_data, dict):
+            r = fill_color_data.get('red', 0)
+            g = fill_color_data.get('green', 0)
+            b = fill_color_data.get('blue', 0)
+            a = fill_color_data.get('alpha', 255)
+            if all(isinstance(v, int) for v in [r, g, b]):
+                fill_color = Color(r, g, b, a)
+
+        stroke_width = segment_data.get('strokeWidth')
+        dash_array = segment_data.get('dashArray')
+        dash_phase = segment_data.get('dashPhase')
+
+        # Parse specific segment type
+        if segment_type == 'LINE':
+            p0_data = segment_data.get('p0', {})
+            p1_data = segment_data.get('p1', {})
+
+            p0 = Point(p0_data.get('x', 0.0), p0_data.get('y', 0.0)) if p0_data else None
+            p1 = Point(p1_data.get('x', 0.0), p1_data.get('y', 0.0)) if p1_data else None
+
+            return Line(
+                stroke_color=stroke_color,
+                fill_color=fill_color,
+                stroke_width=stroke_width,
+                dash_array=dash_array,
+                dash_phase=dash_phase,
+                p0=p0,
+                p1=p1
+            )
+        elif segment_type == 'BEZIER':
+            p0_data = segment_data.get('p0', {})
+            p1_data = segment_data.get('p1', {})
+            p2_data = segment_data.get('p2', {})
+            p3_data = segment_data.get('p3', {})
+
+            p0 = Point(p0_data.get('x', 0.0), p0_data.get('y', 0.0)) if p0_data else None
+            p1 = Point(p1_data.get('x', 0.0), p1_data.get('y', 0.0)) if p1_data else None
+            p2 = Point(p2_data.get('x', 0.0), p2_data.get('y', 0.0)) if p2_data else None
+            p3 = Point(p3_data.get('x', 0.0), p3_data.get('y', 0.0)) if p3_data else None
+
+            return Bezier(
+                stroke_color=stroke_color,
+                fill_color=fill_color,
+                stroke_width=stroke_width,
+                dash_array=dash_array,
+                dash_phase=dash_phase,
+                p0=p0,
+                p1=p1,
+                p2=p2,
+                p3=p3
+            )
+        else:
+            # Fallback to base PathSegment for unknown types
+            return PathSegment(
+                stroke_color=stroke_color,
+                fill_color=fill_color,
+                stroke_width=stroke_width,
+                dash_array=dash_array,
+                dash_phase=dash_phase
+            )
+
+    def _parse_path(self, obj_data: dict) -> 'Path':
+        """Parse JSON data into Path instance with path segments."""
+        from .models import Path
+
+        position_data = obj_data.get('position', {})
+        position = self._parse_position(position_data) if position_data else None
+
+        # Parse path segments
+        path_segments = []
+        segments_data = obj_data.get('pathSegments', [])
+        if isinstance(segments_data, list):
+            for segment_data in segments_data:
+                if isinstance(segment_data, dict):
+                    path_segments.append(self._parse_path_segment(segment_data))
+
+        even_odd_fill = obj_data.get('evenOddFill')
+
+        return Path(
+            position=position,
+            path_segments=path_segments if path_segments else None,
+            even_odd_fill=even_odd_fill
+        )
+
+    def _parse_font_recommendation(self, data: dict) -> FontRecommendation:
+        """Parse JSON data into FontRecommendation instance."""
+        font_type_str = data.get('fontType', 'SYSTEM')
+        font_type = FontType(font_type_str)
+
+        return FontRecommendation(
+            font_name=data.get('fontName', ''),
+            font_type=font_type,
+            similarity_score=data.get('similarityScore', 0.0)
+        )
+
+    def _parse_page_snapshot(self, data: dict) -> PageSnapshot:
+        """Parse JSON data into PageSnapshot instance with proper type handling."""
+        page_ref = self._parse_page_ref(data.get('pageRef', {}))
+
+        # Parse elements using appropriate parser based on type
+        elements = []
+        for elem_data in data.get('elements', []):
+            elem_type_str = elem_data.get('type')
+            if not elem_type_str:
+                continue
+
+            try:
+                # Normalize type string (API returns "CHECKBOX" but enum is "CHECK_BOX")
+                if elem_type_str == "CHECKBOX":
+                    elem_type_str = "CHECK_BOX"
+                    # Deep copy to avoid modifying original
+                    import copy
+                    elem_data = copy.deepcopy(elem_data)
+                    elem_data['type'] = elem_type_str  # Update type in data
+
+                elem_type = ObjectType(elem_type_str)
+
+                # Use appropriate parser based on element type
+                if elem_type in (ObjectType.PARAGRAPH, ObjectType.TEXT_LINE):
+                    # Parse as TextObjectRef to capture text, font, color, children
+                    elements.append(self._parse_text_object_ref(elem_data))
+                elif elem_type in (ObjectType.FORM_FIELD, ObjectType.TEXT_FIELD,
+                                   ObjectType.CHECK_BOX, ObjectType.RADIO_BUTTON,
+                                   ObjectType.BUTTON, ObjectType.DROPDOWN):
+                    # Parse as FormFieldRef to capture name and value
+                    elements.append(self._parse_form_field_ref(elem_data))
+                else:
+                    # Parse as basic ObjectRef
+                    elements.append(self._parse_object_ref(elem_data))
+            except (ValueError, KeyError):
+                # Skip elements with invalid types
+                continue
+
+        return PageSnapshot(
+            page_ref=page_ref,
+            elements=elements
+        )
+
+    def _parse_document_snapshot(self, data: dict) -> DocumentSnapshot:
+        """Parse JSON data into DocumentSnapshot instance."""
+        page_count = data.get('pageCount', 0)
+        fonts = [self._parse_font_recommendation(font_data) for font_data in data.get('fonts', [])]
+        pages = [self._parse_page_snapshot(page_data) for page_data in data.get('pages', [])]
+
+        return DocumentSnapshot(
+            page_count=page_count,
+            fonts=fonts,
+            pages=pages
+        )
+
     # Builder Pattern Support
 
     def _paragraph_builder(self) -> 'ParagraphBuilder':
@@ -1316,9 +2047,17 @@ class PDFDancer:
 
     def __exit__(self, exc_type, exc_val, exc_tb):
         """Context manager exit - cleanup if needed."""
+        # Close the HTTP client to free resources
+        if hasattr(self, '_client'):
+            self._client.close()
         # TODO Could add session cleanup here if API supports it. Cleanup on the server
         pass
 
+    def close(self):
+        """Close the HTTP client and free resources."""
+        if hasattr(self, '_client'):
+            self._client.close()
+
     def _to_path_objects(self, refs: List[ObjectRef]) -> List[PathObject]:
         return [PathObject(self, ref.internal_id, ref.type, ref.position) for ref in refs]