Querying the DOM

Once your spatial document is loaded (or provided via the doc object), you can query elements exactly like a browser DOM. The SpatialDocument utility supports querySelector and querySelectorAll with complex CSS combinators like commas, direct children (>), and siblings (+, ~).

Coordinate System & Pagination

Before extracting geometry, it is important to understand how Fork PDF maps coordinates to the physical document:

• Bottom-Left Origin: PDF coordinates use the bottom-left corner of the page as the origin point (0,0). This means the y value represents the distance from the bottom edge of the page, moving upward.
• 0-Indexed Pages: Document pages are 0-indexed. The first page is always page 0, the second is page 1, and so forth.

Available Node Properties

Each extracted SpatialNode contains robust rendering information:

• tag_name & attributes: The HTML tag and its associated attributes (e.g., id, class, src).
• styles: The final computed CSS styles applied to the element when rendered.
• geometry: The exact bounding box coordinates (x, y, width, height) of the element on the page, mapped from the bottom-left origin.
• pages: An array of 0-indexed page numbers that the element spans across.
• innerText: Combines all text content from the node and its nested children.
• textChild: Returns the actual inner #text node object. This is highly useful when you need to inspect exact styling (like fontFamily) or specific bounding coordinates of the text itself, independent of its parent container.
• parentNode & childNodes: References to the parent node and an array of child nodes, allowing you to traverse up and down the extracted DOM tree.
• has_layout: A boolean indicating whether the element physically takes up space on the page (i.e., width or height is greater than zero). Hidden elements evaluate to false.
• is_shadow_node: A boolean indicating if the element is inside a Shadow DOM. (Note: When using the local SDK, you must initialize the document with pierceShadowDOM: true to query these nodes. For server-side validation tests, this configuration is strictly locked to false).
• is_image_loaded: A boolean exclusively for <img> tags, confirming whether the network request finished successfully without corruption.

You can also access global document dimensions directly from the doc object, such as pageWidth, pageHeight, printableWidth, printableHeight, as well as exact margins (marginTop, marginLeft, marginRight, marginBottom).

Usage Examples

Below are a few common ways to extract geometry, verify formatting, and query nodes.

const heading = doc.querySelector('h1.title');
const items = doc.querySelectorAll('.list-item > a');

// 1. Extract Layout Geometry
console.log(heading.geometry); 
// { x: 40, y: 120, width: 300, height: 45 }
// Note: y=120 means the bottom edge of this box is 120 pixels from the bottom of the page.

// 2. Determine Pagination Boundaries
console.log(heading.pages); 
// [0] (renders entirely on the first page)

// 3. Inspect text-specific styling using textChild
const watermarkNode = doc.querySelector('#watermark');
const textChild = watermarkNode?.textChild;

if (textChild && textChild.styles.fontFamily !== 'Courier New') {
  console.error("Watermark font failed to load correctly.");
}

// 4. Combine all nested text
console.log(heading.innerText); 

// 5. Check global document boundaries
console.log(`Document spans ${doc.pageWidth}x${doc.pageHeight} pixels`);

const heading = doc.querySelector('h1.title');
const items = doc.querySelectorAll('.list-item > a');

// 1. Extract Layout Geometry
console.log(heading?.geometry); 
// { x: 40, y: 120, width: 300, height: 45 }
// Note: y=120 means the bottom edge of this box is 120 pixels from the bottom of the page.

// 2. Determine Pagination Boundaries
console.log(heading?.pages); 
// [0] (renders entirely on the first page)

// 3. Inspect text-specific styling using textChild
const watermarkNode = doc.querySelector('#watermark');
const textChild = watermarkNode?.textChild;

if (textChild && textChild.styles.fontFamily !== 'Courier New') {
  console.error("Watermark font failed to load correctly.");
}

// 4. Combine all nested text
console.log(heading?.innerText); 

// 5. Check global document boundaries
console.log(`Document spans ${doc.pageWidth}x${doc.pageHeight} pixels`);