PDF Reading Order

Reconstructs a defensible reading order from the text runs a PDF text-extraction library (pdf.js, pdfium, pdf-lib, PDFBox and similar) already produced -- x, y, width, height, text and fontSize -- plus a coordinate origin you declare. This library does not parse PDF files, and it makes no network access, ever.

THE SILENT FAILURE. PDF text extraction almost never throws. It returns a string, and the string is wrong in ways that read as merely bad OCR when they are actually structural -- the wrong text goes straight into a search index or an LLM context where nobody reads it closely enough to catch it.

COLUMN INTERLEAVING. A two-column page holds text runs whose y coordinates alternate between the two columns as the extractor walks the page's content stream. Sorting by y then x reads ACROSS the page, weaving the two columns into each other one line at a time. The result is grammatical-looking English that means nothing, and it never throws.

THE Y-AXIS POINTS THE OTHER WAY. PDF user space has its origin at the bottom-left corner with y increasing upward (ISO 32000-1 section 8.3.2.3). Nearly every developer assumes top-left, because that is how screens work. Sorting ascending by y under that wrong assumption returns the page bottom-to-top: a perfectly-ordered, completely reversed document that does not look like a parsing bug unless someone actually reads it start to finish.

ZERO RUNS IS NOT AN EMPTY DOCUMENT. A scanned page has no text layer at all. Extraction returns an empty string, and a pipeline that treats that the same as 'this page has no content' silently converts every page that needs OCR into empty rows, indistinguishable from a page that is genuinely blank. This library returns a distinct empty-page verdict rather than reusing an empty string to mean two different things.

LIGATURES AND HYPHENATION. The letters 'fi' are often extracted as a single glyph, so a search for 'financial' silently fails to match text that visibly contains the word. A word wrapped across a line boundary leaves two fragments that must be rejoined -- but rejoining every hyphen-newline pair also destroys genuine compounds like 'well-being'. Both failure directions are silent; every join this library makes is reported in an audit trail so a caller can revert one it disagrees with.

RUNNING HEADERS AND FOOTERS. The same header or footer repeats on every page and contaminates every extraction with phantom text at every page boundary, indistinguishable from a document title that is actually relevant to the query. Detection only ever reports candidates; removal is a separate, explicit call.

VERIFIED: 96 tests, re-measured by running the suite, 10 deliberate defects applied to the real source, 8 caught and 2 proved to change no observable behaviour (two guards whose conditions are already rejected by the checks after them) — the proofs ship in mutations.json after closing two gaps a first pass missed: an object nested inside a frozen wrapper that was never itself frozen, and a per-column line-index offset silently dropped when dehyphenation reports were combined across columns.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function detectColumns( runs: TextRun[], options?: ColumnDetectionOptions, ): ColumnDetectionResult;
  export function classifyRunColumn( run: TextRun, columns: ColumnBand[], spanOverlapThreshold = DEFAULTS.spanOverlapThreshold, ): ColumnClassification;
  export function detectRunningHeadersFooters( pages: PageRuns[], origin: CoordinateOrigin, options?: HeaderFooterOptions, ): HeaderFooterCandidate[];
  export function removeHeaderFooterRuns( pages: PageRuns[], origin: CoordinateOrigin, candidates: HeaderFooterCandidate[], options?: HeaderFooterOptions, ): PageRuns[];
  export function dehyphenate( lines: string[], options?: DehyphenationOptions, ):;
  export function normalizeLigatures(text: string):;
  export function containsLigature(text: string): boolean;
  export function reconstructPage( runs: TextRun[], origin: CoordinateOrigin, options?: ReadingOrderOptions, ): ReadingOrderResult;

  export type ColumnClassification = | { spanning: false;
  export type CoordinateOrigin = "bottom-left" | "top-left";
  export type ReadingOrderVerdict = "ok" | "empty-page";