@type extract_option() :: {:layout, boolean()}

Options for reconstructed string extraction.

@type matrix() :: [float()]

A six-value PDF affine matrix in [a, b, c, d, e, f] order.

@type render_mode() :: 0..7

A PDF text rendering mode from 0 through 7.

@type span_option() :: {:order, :source | :visual}

Options for positioned span extraction.

@type text_document() :: %{page_count: non_neg_integer(), pages: [text_page()]}

A page-preserving positioned-text extraction result.

@type text_page() :: %{
  number: pos_integer(),
  media_box: [number()],
  rotation: 0 | 90 | 180 | 270,
  spans: [text_span()]
}

Positioned text for one resolved PDF page.

media_box is [left, bottom, right, top] in PDF default user-space units. rotation is the effective inherited page rotation normalized to 0, 90, 180, or 270 degrees. Every resolved page is returned, including pages whose spans list is empty.

@type text_span() :: %{
  text: String.t(),
  source_index: non_neg_integer(),
  x: float(),
  y: float(),
  end_x: float(),
  end_y: float(),
  font_resource: String.t(),
  font_size: float(),
  text_matrix: matrix(),
  ctm: matrix(),
  render_mode: render_mode(),
  paints_text?: boolean(),
  adds_to_clip_path?: boolean(),
  joins_previous?: boolean()
}

A decoded text-showing operand and its positioned extraction context.

source_index is zero-based within a page and follows text-show execution order. Page content streams are traversed in /Contents order, and Form XObjects are traversed where their Do operator occurs. Reusing a Form therefore produces new spans with new indexes.

x, y, end_x, and end_y describe the text baseline in normalized display coordinates. The origin is the top-left of the rotated MediaBox, X increases rightward, Y increases downward, and page rotation and Form CTMs are applied. These points are not glyph bounding boxes. The end point uses the PDF font widths available to the extractor and can be approximate when a font omits explicit metrics.

text_matrix is the PDF text matrix at the start of the operand. ctm is the active PDF current transformation matrix, including Form transforms. Neither matrix includes the final MediaBox/page-rotation normalization represented by the baseline coordinates.

font_resource is the active PDF resource name, not a guaranteed font family or PostScript name. font_size is the Tf text-space size, not a calculated display-space height.

paints_text? and adds_to_clip_path? are derived only from render_mode. They describe the requested PDF text rendering operation; they do not claim that the text is visually visible or clipped. joins_previous? identifies a later string operand from the same TJ array, preserving the existing source-order string projection behavior.