pdf-codec.js 5.0.0 → 5.1.0

package/README.md

@@ -310,6 +310,31 @@ Reading a program's built-in encoding is what stops a symbol-encoded subset —
 
 **Where nothing states an answer, the answer is the replacement character plus a `text/unmapped-encoding` diagnostic, never a guess.** Two cases reach it in practice: a symbolic font with no embedded program and no `/ToUnicode`, and a subsetted font that both strips its glyph names and maps its glyphs only from private-use code points — a private-use code point identifies a glyph inside one font and says nothing about the character it draws, so it is treated as no answer rather than a wrong one.
 
+## Grouping text runs into lines and words
+
+`readPdf` reports one positioned run per text-showing operator, and a PDF says nothing about lines or words: a line of prose can arrive as one run, as one run per word, or as one run per glyph, entirely at the producer's discretion. `groupPdfTextRuns` turns those runs back into lines of words, and `pdf-codec/text-group` serves it without the write half or the vendored fonts, alongside `pdf-codec/read`.
+
+```ts
+import { readPdf } from "pdf-codec/read";
+import { groupPdfTextRuns } from "pdf-codec/text-group";
+
+const page = readPdf(bytes).pages[0];
+const runs = page.items.filter((item) => item.kind === "text");
+for (const line of groupPdfTextRuns(runs)) {
+  console.log(line.text);
+}
+```
+
+Two rules decide everything, and both were got wrong often enough by hand ([#1317](https://github.com/ExaDev/documents.js/issues/1317)) to be worth stating.
+
+Two runs are on one line when their baselines sit within a fraction of an em of each other, measured against **the smaller of the two**. Taken from the larger, a 30pt heading's own window reaches the 9pt line beneath it, the merged line's runs sort by x into a sequence whose gaps are negative, a negative gap reads as one word, and the two lines concatenate into exactly the run-together text the grouping exists to prevent. The default fraction is two thirds, bounded on both sides by real typography: two consecutive lines are never closer than solid setting puts them, one full em, so it has to stay under 1; a superscript raised by at most a third of its parent's size at no less than half that size shifts by at most two thirds of its own em, so anything tighter cuts footnote markers off the line they annotate.
+
+A run whose `widthPt` is absent states no advance, so where it ends is unknown and the gap after it is underivable. `runGapPt` reports `undefined` for that, and an undefined gap is **no evidence of a space**. Reading it as zero puts the previous run's end at its own start, turns its whole advance into an apparent gap, and produces "Com plete ly".
+
+Gaps that are derivable become a word space at an eighth of an em (the narrowest genuine one: the standard fourteen faces set their space glyph at 250/1000 em, and justified setting compresses to no less than half of that) and a column boundary past a full em (wider than the em space, the widest single space character there is), so a table's row reads as `"North\t4.2m\t11%"` rather than as one sentence. `runsShareBaseline` and `runGapPt` are exported on their own for a consumer with its own pipeline around them, and every threshold is overridable.
+
+Limits, each inherent to what a PDF states rather than to the implementation: grouping is by baseline alone with no page segmentation, so on a multi-column page whose columns sit at different vertical offsets a line of one can fall within tolerance of a line of the next and the two are reported as one line with a column boundary between them, which is the cut a caller needs (`document-outline.js`'s `segmentPdfRegions` finds the gutter first if you want them genuinely apart); text comes out in visual order, so a right-to-left script needs the Unicode Bidi Algorithm applied to the result; vertical writing modes are not recognised, because the content interpreter does not read a CMap's `WMode` ([#1358](https://github.com/ExaDev/documents.js/issues/1358)); and a word hyphenated across a line end stays split, hyphen intact, because rejoining it is a paragraph-level judgement this package leaves to its consumers.
+
 ## JBIG2 scope
 
 `src/image/jbig2*.ts` is a hand-written ITU-T T.88 decoder covering what real scanned PDFs actually contain.

package/dist/index.cjs

@@ -19,8 +19,12 @@ const require_measure = require("./measure.cjs");
 const require_write = require("./write.cjs");
 const require_codec = require("./codec.cjs");
 const require_font_face = require("./font-face.cjs");
+const require_text_group = require("./text-group.cjs");
 const require_raster = require("./raster.cjs");
+exports.DEFAULT_BASELINE_TOLERANCE_EM = require_text_group.DEFAULT_BASELINE_TOLERANCE_EM;
+exports.DEFAULT_COLUMN_GAP_EM = require_text_group.DEFAULT_COLUMN_GAP_EM;
 exports.DEFAULT_VERTICAL_METRIC_POLICY = require_measure.DEFAULT_VERTICAL_METRIC_POLICY;
+exports.DEFAULT_WORD_GAP_EM = require_text_group.DEFAULT_WORD_GAP_EM;
 exports.FontFaceParseError = require_font_face.FontFaceParseError;
 exports.Jbig2ParseError = require_image_jbig2_errors.Jbig2ParseError;
 exports.Jbig2UnsupportedError = require_image_jbig2_errors.Jbig2UnsupportedError;
@@ -66,6 +70,7 @@ exports.decodeCcittFax = require_image_ccitt.decodeCcittFax;
 exports.decodeJbig2Embedded = require_image_jbig2.decodeJbig2Embedded;
 exports.decodeJpeg2000 = require_image_jpeg2000.decodeJpeg2000;
 exports.filterScanlines = require_image_png_filter.filterScanlines;
+exports.groupPdfTextRuns = require_text_group.groupPdfTextRuns;
 exports.loadMathFont = require_math_font.loadMathFont;
 exports.looksLikeBareCodestream = require_image_jp2_boxes.looksLikeBareCodestream;
 exports.parseJp2Container = require_image_jp2_boxes.parseJp2Container;
@@ -76,6 +81,8 @@ exports.readPdf = require_read.readPdf;
 exports.renderPdfPage = require_raster.renderPdfPage;
 exports.resolveFaceWithRegistry = require_font_registry.resolveFaceWithRegistry;
 exports.resolveStandardFont = require_fonts.resolveStandardFont;
+exports.runGapPt = require_text_group.runGapPt;
+exports.runsShareBaseline = require_text_group.runsShareBaseline;
 exports.scaleMathStretchConstruction = require_math_stretch.scaleMathStretchConstruction;
 exports.unfilterScanlines = require_image_png_filter.unfilterScanlines;
 exports.writePdf = require_write.writePdf;

package/dist/index.d.cts

@@ -23,7 +23,8 @@ import { a as MathGlyphPart, c as MathVariants, n as MathGlyphAssembly, o as Mat
 import { a as scaleMathStretchConstruction, i as assembleStretchyGlyph, n as MathStretchOptions, r as MathStretchPlacement, t as MathStretchConstruction } from "./math-stretch-C2JanDAz.cjs";
 import { LoadedMathFont, MathFont, MathFontDescriptorMetrics, loadMathFont } from "./math-font.cjs";
 import { DEFAULT_VERTICAL_METRIC_POLICY, FontMeasurerOptions, StandardFontMeasurerOptions, VerticalMetricPolicy, createFontMeasurer, createStandardFontMeasurer } from "./measure.cjs";
+import { DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_WORD_GAP_EM, PdfTextBox, PdfTextGroupingOptions, PdfTextLine, PdfTextRunGeometry, PdfTextWord, PdfWordSeparator, groupPdfTextRuns, runGapPt, runsShareBaseline } from "./text-group.cjs";
 import { PageRasteriser, RasterDrawOp, RasterFillRectOp, RasterFillSpec, RasterImageOp, RasterMatrix, RasterPageGeometry, RasterPathOp, RasterPathSegment, RasterRegionPt, RasterStrokeSpec, RasterSubpath, RenderPdfPageOptions, renderPdfPage } from "./raster.cjs";
 import { FontRegistryOptions, FontSubstitution, MathAssembledGlyphs, MathBox, MathColor, MathFontMetrics, MathGlyphMetrics, MathGlyphPlacement, MathGlyphRun, MathLayoutItem, MathRule, MathStretchAxis, MathStretchGlyph, MathStretchResult, MathStroke, Point, PositionedFormula, ProvidedFont, StyledFragment, StyledRun, TextMeasurer, UnderlineMetrics, WrapOptions, WrappedLine } from "document-schema.js";
 export * from "byte-codec";
-export { type CcittFaxImage, type CcittFaxOptions, DEFAULT_VERTICAL_METRIC_POLICY, type EmbeddedFace, type EmbeddedFaceMetrics, type EmbeddedFaceSubstitution, type FontFace, FontFaceParseError, type FontMeasurerOptions, type FontMetrics, type FontRegistry, type FontRegistryOptions, type FontSubstitution, type GlyphInkBounds, type Jbig2DecodeOptions, type Jbig2Image, Jbig2ParseError, Jbig2UnsupportedError, type Jp2ChannelDefinition, type Jp2ColourSpace, type Jp2Container, type Jp2ImageHeader, type Jpeg2000ComponentMetadata, type Jpeg2000DecodeOptions, type Jpeg2000Image, type Jpeg2000Metadata, Jpeg2000ParseError, type Jpeg2000ProgressionOrder, type Jpeg2000QuantizationStyle, type Jpeg2000Transform, Jpeg2000UnsupportedError, LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, type LoadedMathFont, type MathAssembledGlyphs, type MathBox, type MathColor, type MathFont, type MathFontDescriptorMetrics, type MathFontMetrics, type MathGlyphAssembly, type MathGlyphConstruction, type MathGlyphMetrics, type MathGlyphPart, type MathGlyphPlacement, type MathGlyphRun, type MathGlyphVariant, type MathLayoutItem, type MathRule, type MathStretchAxis, type MathStretchConstruction, type MathStretchGlyph, type MathStretchOptions, type MathStretchPlacement, type MathStretchResult, type MathStroke, type MathVariants, NOOP_DIAGNOSTIC_SINK, type PageRasteriser, PdfBytesSchema, type PdfDiagnostic, type PdfDiagnosticSeverity, type PdfDiagnosticSink, PdfEncryptedError, PdfEncryptionError, type PdfEncryptionOptions, type PdfEncryptionPermissions, type PdfEncryptionScheme, PdfParseError, PdfPasswordRequiredError, type Point, type PositionedFormula, type ProvidedFont, type RasterDrawOp, type RasterFillRectOp, type RasterFillSpec, type RasterImageOp, type RasterMatrix, type RasterPageGeometry, type RasterPathOp, type RasterPathSegment, type RasterRegionPt, type RasterStrokeSpec, type RasterSubpath, type ReadPdfOptions, type RenderPdfPageOptions, type ResolvedFace, type ResolvedFont, STANDARD_METRICS, type StandardFontMeasurerOptions, type StandardFontName, type StyledFragment, type StyledRun, type TextMeasurer, type UnderlineMetrics, type VerticalMetricPolicy, type WinAnsiSubstitution, type WrapOptions, type WrappedLine, type WritePdfOptions, assembleStretchyGlyph, createFontMeasurer, createFontRegistry, createStandardFontMeasurer, decodeCcittFax, decodeJbig2Embedded, decodeJpeg2000, filterScanlines, loadMathFont, looksLikeBareCodestream, parseJp2Container, pdfCodec, readFontFace, readJpeg2000Metadata, readPdf, renderPdfPage, resolveFaceWithRegistry, resolveStandardFont, scaleMathStretchConstruction, unfilterScanlines, writePdf };
+export { type CcittFaxImage, type CcittFaxOptions, DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_VERTICAL_METRIC_POLICY, DEFAULT_WORD_GAP_EM, type EmbeddedFace, type EmbeddedFaceMetrics, type EmbeddedFaceSubstitution, type FontFace, FontFaceParseError, type FontMeasurerOptions, type FontMetrics, type FontRegistry, type FontRegistryOptions, type FontSubstitution, type GlyphInkBounds, type Jbig2DecodeOptions, type Jbig2Image, Jbig2ParseError, Jbig2UnsupportedError, type Jp2ChannelDefinition, type Jp2ColourSpace, type Jp2Container, type Jp2ImageHeader, type Jpeg2000ComponentMetadata, type Jpeg2000DecodeOptions, type Jpeg2000Image, type Jpeg2000Metadata, Jpeg2000ParseError, type Jpeg2000ProgressionOrder, type Jpeg2000QuantizationStyle, type Jpeg2000Transform, Jpeg2000UnsupportedError, LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, type LoadedMathFont, type MathAssembledGlyphs, type MathBox, type MathColor, type MathFont, type MathFontDescriptorMetrics, type MathFontMetrics, type MathGlyphAssembly, type MathGlyphConstruction, type MathGlyphMetrics, type MathGlyphPart, type MathGlyphPlacement, type MathGlyphRun, type MathGlyphVariant, type MathLayoutItem, type MathRule, type MathStretchAxis, type MathStretchConstruction, type MathStretchGlyph, type MathStretchOptions, type MathStretchPlacement, type MathStretchResult, type MathStroke, type MathVariants, NOOP_DIAGNOSTIC_SINK, type PageRasteriser, PdfBytesSchema, type PdfDiagnostic, type PdfDiagnosticSeverity, type PdfDiagnosticSink, PdfEncryptedError, PdfEncryptionError, type PdfEncryptionOptions, type PdfEncryptionPermissions, type PdfEncryptionScheme, PdfParseError, PdfPasswordRequiredError, type PdfTextBox, type PdfTextGroupingOptions, type PdfTextLine, type PdfTextRunGeometry, type PdfTextWord, type PdfWordSeparator, type Point, type PositionedFormula, type ProvidedFont, type RasterDrawOp, type RasterFillRectOp, type RasterFillSpec, type RasterImageOp, type RasterMatrix, type RasterPageGeometry, type RasterPathOp, type RasterPathSegment, type RasterRegionPt, type RasterStrokeSpec, type RasterSubpath, type ReadPdfOptions, type RenderPdfPageOptions, type ResolvedFace, type ResolvedFont, STANDARD_METRICS, type StandardFontMeasurerOptions, type StandardFontName, type StyledFragment, type StyledRun, type TextMeasurer, type UnderlineMetrics, type VerticalMetricPolicy, type WinAnsiSubstitution, type WrapOptions, type WrappedLine, type WritePdfOptions, assembleStretchyGlyph, createFontMeasurer, createFontRegistry, createStandardFontMeasurer, decodeCcittFax, decodeJbig2Embedded, decodeJpeg2000, filterScanlines, groupPdfTextRuns, loadMathFont, looksLikeBareCodestream, parseJp2Container, pdfCodec, readFontFace, readJpeg2000Metadata, readPdf, renderPdfPage, resolveFaceWithRegistry, resolveStandardFont, runGapPt, runsShareBaseline, scaleMathStretchConstruction, unfilterScanlines, writePdf };

package/dist/index.d.ts

@@ -23,7 +23,8 @@ import { a as MathGlyphPart, c as MathVariants, n as MathGlyphAssembly, o as Mat
 import { a as scaleMathStretchConstruction, i as assembleStretchyGlyph, n as MathStretchOptions, r as MathStretchPlacement, t as MathStretchConstruction } from "./math-stretch-BbC2o4Br.js";
 import { LoadedMathFont, MathFont, MathFontDescriptorMetrics, loadMathFont } from "./math-font.js";
 import { DEFAULT_VERTICAL_METRIC_POLICY, FontMeasurerOptions, StandardFontMeasurerOptions, VerticalMetricPolicy, createFontMeasurer, createStandardFontMeasurer } from "./measure.js";
+import { DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_WORD_GAP_EM, PdfTextBox, PdfTextGroupingOptions, PdfTextLine, PdfTextRunGeometry, PdfTextWord, PdfWordSeparator, groupPdfTextRuns, runGapPt, runsShareBaseline } from "./text-group.js";
 import { PageRasteriser, RasterDrawOp, RasterFillRectOp, RasterFillSpec, RasterImageOp, RasterMatrix, RasterPageGeometry, RasterPathOp, RasterPathSegment, RasterRegionPt, RasterStrokeSpec, RasterSubpath, RenderPdfPageOptions, renderPdfPage } from "./raster.js";
 import { FontRegistryOptions, FontSubstitution, MathAssembledGlyphs, MathBox, MathColor, MathFontMetrics, MathGlyphMetrics, MathGlyphPlacement, MathGlyphRun, MathLayoutItem, MathRule, MathStretchAxis, MathStretchGlyph, MathStretchResult, MathStroke, Point, PositionedFormula, ProvidedFont, StyledFragment, StyledRun, TextMeasurer, UnderlineMetrics, WrapOptions, WrappedLine } from "document-schema.js";
 export * from "byte-codec";
-export { type CcittFaxImage, type CcittFaxOptions, DEFAULT_VERTICAL_METRIC_POLICY, type EmbeddedFace, type EmbeddedFaceMetrics, type EmbeddedFaceSubstitution, type FontFace, FontFaceParseError, type FontMeasurerOptions, type FontMetrics, type FontRegistry, type FontRegistryOptions, type FontSubstitution, type GlyphInkBounds, type Jbig2DecodeOptions, type Jbig2Image, Jbig2ParseError, Jbig2UnsupportedError, type Jp2ChannelDefinition, type Jp2ColourSpace, type Jp2Container, type Jp2ImageHeader, type Jpeg2000ComponentMetadata, type Jpeg2000DecodeOptions, type Jpeg2000Image, type Jpeg2000Metadata, Jpeg2000ParseError, type Jpeg2000ProgressionOrder, type Jpeg2000QuantizationStyle, type Jpeg2000Transform, Jpeg2000UnsupportedError, LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, type LoadedMathFont, type MathAssembledGlyphs, type MathBox, type MathColor, type MathFont, type MathFontDescriptorMetrics, type MathFontMetrics, type MathGlyphAssembly, type MathGlyphConstruction, type MathGlyphMetrics, type MathGlyphPart, type MathGlyphPlacement, type MathGlyphRun, type MathGlyphVariant, type MathLayoutItem, type MathRule, type MathStretchAxis, type MathStretchConstruction, type MathStretchGlyph, type MathStretchOptions, type MathStretchPlacement, type MathStretchResult, type MathStroke, type MathVariants, NOOP_DIAGNOSTIC_SINK, type PageRasteriser, PdfBytesSchema, type PdfDiagnostic, type PdfDiagnosticSeverity, type PdfDiagnosticSink, PdfEncryptedError, PdfEncryptionError, type PdfEncryptionOptions, type PdfEncryptionPermissions, type PdfEncryptionScheme, PdfParseError, PdfPasswordRequiredError, type Point, type PositionedFormula, type ProvidedFont, type RasterDrawOp, type RasterFillRectOp, type RasterFillSpec, type RasterImageOp, type RasterMatrix, type RasterPageGeometry, type RasterPathOp, type RasterPathSegment, type RasterRegionPt, type RasterStrokeSpec, type RasterSubpath, type ReadPdfOptions, type RenderPdfPageOptions, type ResolvedFace, type ResolvedFont, STANDARD_METRICS, type StandardFontMeasurerOptions, type StandardFontName, type StyledFragment, type StyledRun, type TextMeasurer, type UnderlineMetrics, type VerticalMetricPolicy, type WinAnsiSubstitution, type WrapOptions, type WrappedLine, type WritePdfOptions, assembleStretchyGlyph, createFontMeasurer, createFontRegistry, createStandardFontMeasurer, decodeCcittFax, decodeJbig2Embedded, decodeJpeg2000, filterScanlines, loadMathFont, looksLikeBareCodestream, parseJp2Container, pdfCodec, readFontFace, readJpeg2000Metadata, readPdf, renderPdfPage, resolveFaceWithRegistry, resolveStandardFont, scaleMathStretchConstruction, unfilterScanlines, writePdf };
+export { type CcittFaxImage, type CcittFaxOptions, DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_VERTICAL_METRIC_POLICY, DEFAULT_WORD_GAP_EM, type EmbeddedFace, type EmbeddedFaceMetrics, type EmbeddedFaceSubstitution, type FontFace, FontFaceParseError, type FontMeasurerOptions, type FontMetrics, type FontRegistry, type FontRegistryOptions, type FontSubstitution, type GlyphInkBounds, type Jbig2DecodeOptions, type Jbig2Image, Jbig2ParseError, Jbig2UnsupportedError, type Jp2ChannelDefinition, type Jp2ColourSpace, type Jp2Container, type Jp2ImageHeader, type Jpeg2000ComponentMetadata, type Jpeg2000DecodeOptions, type Jpeg2000Image, type Jpeg2000Metadata, Jpeg2000ParseError, type Jpeg2000ProgressionOrder, type Jpeg2000QuantizationStyle, type Jpeg2000Transform, Jpeg2000UnsupportedError, LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, type LoadedMathFont, type MathAssembledGlyphs, type MathBox, type MathColor, type MathFont, type MathFontDescriptorMetrics, type MathFontMetrics, type MathGlyphAssembly, type MathGlyphConstruction, type MathGlyphMetrics, type MathGlyphPart, type MathGlyphPlacement, type MathGlyphRun, type MathGlyphVariant, type MathLayoutItem, type MathRule, type MathStretchAxis, type MathStretchConstruction, type MathStretchGlyph, type MathStretchOptions, type MathStretchPlacement, type MathStretchResult, type MathStroke, type MathVariants, NOOP_DIAGNOSTIC_SINK, type PageRasteriser, PdfBytesSchema, type PdfDiagnostic, type PdfDiagnosticSeverity, type PdfDiagnosticSink, PdfEncryptedError, PdfEncryptionError, type PdfEncryptionOptions, type PdfEncryptionPermissions, type PdfEncryptionScheme, PdfParseError, PdfPasswordRequiredError, type PdfTextBox, type PdfTextGroupingOptions, type PdfTextLine, type PdfTextRunGeometry, type PdfTextWord, type PdfWordSeparator, type Point, type PositionedFormula, type ProvidedFont, type RasterDrawOp, type RasterFillRectOp, type RasterFillSpec, type RasterImageOp, type RasterMatrix, type RasterPageGeometry, type RasterPathOp, type RasterPathSegment, type RasterRegionPt, type RasterStrokeSpec, type RasterSubpath, type ReadPdfOptions, type RenderPdfPageOptions, type ResolvedFace, type ResolvedFont, STANDARD_METRICS, type StandardFontMeasurerOptions, type StandardFontName, type StyledFragment, type StyledRun, type TextMeasurer, type UnderlineMetrics, type VerticalMetricPolicy, type WinAnsiSubstitution, type WrapOptions, type WrappedLine, type WritePdfOptions, assembleStretchyGlyph, createFontMeasurer, createFontRegistry, createStandardFontMeasurer, decodeCcittFax, decodeJbig2Embedded, decodeJpeg2000, filterScanlines, groupPdfTextRuns, loadMathFont, looksLikeBareCodestream, parseJp2Container, pdfCodec, readFontFace, readJpeg2000Metadata, readPdf, renderPdfPage, resolveFaceWithRegistry, resolveStandardFont, runGapPt, runsShareBaseline, scaleMathStretchConstruction, unfilterScanlines, writePdf };

package/dist/index.js

@@ -18,6 +18,7 @@ import { DEFAULT_VERTICAL_METRIC_POLICY, createFontMeasurer, createStandardFontM
 import { writePdf } from "./write.js";
 import { PdfBytesSchema, pdfCodec } from "./codec.js";
 import { FontFaceParseError, readFontFace } from "./font-face.js";
+import { DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_WORD_GAP_EM, groupPdfTextRuns, runGapPt, runsShareBaseline } from "./text-group.js";
 import { renderPdfPage } from "./raster.js";
 export * from "byte-codec";
-export { DEFAULT_VERTICAL_METRIC_POLICY, FontFaceParseError, Jbig2ParseError, Jbig2UnsupportedError, Jpeg2000ParseError, Jpeg2000UnsupportedError, LAYOUT_FORMAT_VERSION, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachmentSchema, LayoutDestinationSchema, LayoutDestinationTargetSchema, LayoutDocumentSchema, LayoutEllipseSchema, LayoutFormFieldSchema, LayoutFormWidgetSchema, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLinkSchema, LayoutItemSchema, LayoutLayerSchema, LayoutLineSchema, LayoutLinkSchema, LayoutOutlineItemSchema, LayoutPageSchema, LayoutPathSchema, LayoutPathSegmentSchema, LayoutRectSchema, LayoutStructureElementSchema, LayoutSubpathSchema, LayoutTextSchema, NOOP_DIAGNOSTIC_SINK, PdfBytesSchema, PdfEncryptedError, PdfEncryptionError, PdfParseError, PdfPasswordRequiredError, STANDARD_METRICS, assembleStretchyGlyph, createFontMeasurer, createFontRegistry, createStandardFontMeasurer, decodeCcittFax, decodeJbig2Embedded, decodeJpeg2000, filterScanlines, loadMathFont, looksLikeBareCodestream, parseJp2Container, pdfCodec, readFontFace, readJpeg2000Metadata, readPdf, renderPdfPage, resolveFaceWithRegistry, resolveStandardFont, scaleMathStretchConstruction, unfilterScanlines, writePdf };
+export { DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_VERTICAL_METRIC_POLICY, DEFAULT_WORD_GAP_EM, FontFaceParseError, Jbig2ParseError, Jbig2UnsupportedError, Jpeg2000ParseError, Jpeg2000UnsupportedError, LAYOUT_FORMAT_VERSION, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachmentSchema, LayoutDestinationSchema, LayoutDestinationTargetSchema, LayoutDocumentSchema, LayoutEllipseSchema, LayoutFormFieldSchema, LayoutFormWidgetSchema, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLinkSchema, LayoutItemSchema, LayoutLayerSchema, LayoutLineSchema, LayoutLinkSchema, LayoutOutlineItemSchema, LayoutPageSchema, LayoutPathSchema, LayoutPathSegmentSchema, LayoutRectSchema, LayoutStructureElementSchema, LayoutSubpathSchema, LayoutTextSchema, NOOP_DIAGNOSTIC_SINK, PdfBytesSchema, PdfEncryptedError, PdfEncryptionError, PdfParseError, PdfPasswordRequiredError, STANDARD_METRICS, assembleStretchyGlyph, createFontMeasurer, createFontRegistry, createStandardFontMeasurer, decodeCcittFax, decodeJbig2Embedded, decodeJpeg2000, filterScanlines, groupPdfTextRuns, loadMathFont, looksLikeBareCodestream, parseJp2Container, pdfCodec, readFontFace, readJpeg2000Metadata, readPdf, renderPdfPage, resolveFaceWithRegistry, resolveStandardFont, runGapPt, runsShareBaseline, scaleMathStretchConstruction, unfilterScanlines, writePdf };

package/dist/text-group.cjs

@@ -0,0 +1,217 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/text-group.ts
+const DEFAULT_BASELINE_TOLERANCE_EM = 2 / 3;
+const DEFAULT_WORD_GAP_EM = 1 / 8;
+const DEFAULT_COLUMN_GAP_EM = 1;
+const ROTATION_NOISE_DEG = 1e-6;
+const DEGREES_PER_TURN = 360;
+function normaliseRotationDeg(rotationDeg) {
+	return (Math.round((rotationDeg ?? 0) / ROTATION_NOISE_DEG) * ROTATION_NOISE_DEG % DEGREES_PER_TURN + DEGREES_PER_TURN) % DEGREES_PER_TURN;
+}
+const RADIANS_PER_TURN = 2 * Math.PI;
+function baselineAxis(rotationDeg) {
+	const radians = rotationDeg * RADIANS_PER_TURN / DEGREES_PER_TURN;
+	return {
+		cos: Math.cos(radians),
+		sin: Math.sin(radians)
+	};
+}
+function project(run, rotationDeg) {
+	const { cos, sin } = baselineAxis(rotationDeg);
+	return {
+		run,
+		alongPt: run.xPt * cos + run.yPt * sin,
+		acrossPt: run.yPt * cos - run.xPt * sin,
+		sizePt: run.sizePt
+	};
+}
+function unproject(alongPt, acrossPt, rotationDeg) {
+	const { cos, sin } = baselineAxis(rotationDeg);
+	return {
+		xPt: alongPt * cos - acrossPt * sin,
+		yPt: alongPt * sin + acrossPt * cos
+	};
+}
+/**
+* Whether two positioned runs sit on one visual line.
+*
+* The tolerance is a fraction of an em of the smaller of the two runs, never of one nominated run, so a large heading can never claim the small line beneath it. Runs set at different angles never share a line.
+* @param a - one run
+* @param b - the other run
+* @param options - only `baselineToleranceEm` is read; it defaults to {@link DEFAULT_BASELINE_TOLERANCE_EM}
+* @returns true when the two baselines are within tolerance of each other
+*/
+function runsShareBaseline(a, b, options = {}) {
+	const rotationDeg = normaliseRotationDeg(a.rotationDeg);
+	if (rotationDeg !== normaliseRotationDeg(b.rotationDeg)) return false;
+	const toleranceEm = options.baselineToleranceEm ?? .6666666666666666;
+	return Math.abs(project(a, rotationDeg).acrossPt - project(b, rotationDeg).acrossPt) <= toleranceEm * Math.min(a.sizePt, b.sizePt);
+}
+/**
+* The horizontal gap along the baseline between the end of `previous` and the start of `next`, or undefined when the geometry does not state one.
+*
+* Undefined has exactly two causes, and a caller must treat both as "no evidence of a space" rather than substituting zero: `previous` stated no advance width, so where it ends is unknown; or the two runs are set at different angles, so they share no axis to measure along. A negative result is real and means the two runs overlap.
+* @param previous - the run to the left, in reading order
+* @param next - the run that follows it
+* @returns the gap in points, or undefined when it cannot be derived
+*/
+function runGapPt(previous, next) {
+	const rotationDeg = normaliseRotationDeg(previous.rotationDeg);
+	if (rotationDeg !== normaliseRotationDeg(next.rotationDeg)) return;
+	const previousWidthPt = previous.widthPt;
+	if (previousWidthPt === void 0) return;
+	return project(next, rotationDeg).alongPt - (project(previous, rotationDeg).alongPt + previousWidthPt);
+}
+function clusterIntoLines(entries, toleranceEm) {
+	const lines = [];
+	for (const entry of entries) {
+		let nearest;
+		for (const line of lines) if (runsShareBaseline(line.anchor.run, entry.run, { baselineToleranceEm: toleranceEm })) nearest = line;
+		if (nearest === void 0) lines.push({
+			anchor: entry,
+			entries: [entry]
+		});
+		else nearest.entries.push(entry);
+	}
+	return lines;
+}
+function tokeniseRun(text) {
+	const words = text.match(/\S+/g) ?? [];
+	const leadingSpace = /^\s/.test(text);
+	const trailingSpace = /\s$/.test(text);
+	return {
+		words,
+		leadingSpace,
+		trailingSpace,
+		whole: words.length === 1 && !leadingSpace && !trailingSpace
+	};
+}
+const SEPARATOR_TEXT = {
+	none: "",
+	space: " ",
+	column: "	"
+};
+function separatorForGap(gapPt, smallerSizePt, wordGapEm, columnGapEm) {
+	if (gapPt === void 0) return "none";
+	if (gapPt >= columnGapEm * smallerSizePt) return "column";
+	if (gapPt >= wordGapEm * smallerSizePt) return "space";
+	return "none";
+}
+function boundsOf(minAlongPt, maxAlongEndPt, acrossPt, maxSizePt, rotationDeg) {
+	const origin = unproject(minAlongPt, acrossPt, rotationDeg);
+	return {
+		xPt: origin.xPt,
+		yPt: origin.yPt,
+		widthPt: maxAlongEndPt - minAlongPt,
+		heightPt: maxSizePt
+	};
+}
+function buildWords(line, rotationDeg, wordGapEm, columnGapEm) {
+	const working = [];
+	let previous;
+	for (const entry of line.entries) {
+		const tokens = tokeniseRun(entry.run.text);
+		const gapSeparator = previous === void 0 ? "none" : separatorForGap(runGapPt(previous.entry.run, entry.run), Math.min(previous.entry.sizePt, entry.sizePt), wordGapEm, columnGapEm);
+		const pendingSpace = previous?.trailingSpace === true;
+		let separator = "none";
+		if (working.length > 0) separator = gapSeparator === "none" && (pendingSpace || tokens.leadingSpace) ? "space" : gapSeparator;
+		const widthPt = entry.run.widthPt;
+		const alongEndPt = entry.alongPt + (widthPt ?? 0);
+		tokens.words.forEach((word, index) => {
+			const last = working[working.length - 1];
+			if (index === 0 && separator === "none" && last !== void 0) {
+				last.text += word;
+				last.runs.push(entry.run);
+				last.measurable = last.measurable && tokens.whole && widthPt !== void 0;
+				last.minAlongPt = Math.min(last.minAlongPt, entry.alongPt);
+				last.maxAlongEndPt = Math.max(last.maxAlongEndPt, alongEndPt);
+				last.maxSizePt = Math.max(last.maxSizePt, entry.sizePt);
+				return;
+			}
+			working.push({
+				text: word,
+				separatorBefore: index === 0 ? separator : "space",
+				runs: [entry.run],
+				measurable: tokens.whole && widthPt !== void 0,
+				minAlongPt: entry.alongPt,
+				maxAlongEndPt: alongEndPt,
+				maxSizePt: entry.sizePt
+			});
+		});
+		previous = {
+			entry,
+			trailingSpace: tokens.trailingSpace
+		};
+	}
+	return working.map((word) => ({
+		text: word.text,
+		separatorBefore: word.separatorBefore,
+		runs: word.runs,
+		...word.measurable ? { bounds: boundsOf(word.minAlongPt, word.maxAlongEndPt, line.anchor.acrossPt, word.maxSizePt, rotationDeg) } : {}
+	}));
+}
+function buildLine(line, rotationDeg, wordGapEm, columnGapEm) {
+	const words = buildWords(line, rotationDeg, wordGapEm, columnGapEm);
+	const text = words.map((word) => SEPARATOR_TEXT[word.separatorBefore] + word.text).join("");
+	let minAlongPt = Number.POSITIVE_INFINITY;
+	let maxAlongEndPt = Number.NEGATIVE_INFINITY;
+	let maxSizePt = 0;
+	let measurable = true;
+	for (const entry of line.entries) {
+		const widthPt = entry.run.widthPt;
+		if (widthPt === void 0) measurable = false;
+		minAlongPt = Math.min(minAlongPt, entry.alongPt);
+		maxAlongEndPt = Math.max(maxAlongEndPt, entry.alongPt + (widthPt ?? 0));
+		maxSizePt = Math.max(maxSizePt, entry.sizePt);
+	}
+	return {
+		text,
+		words,
+		baselineYPt: line.anchor.acrossPt,
+		rotationDeg,
+		...measurable ? { bounds: boundsOf(minAlongPt, maxAlongEndPt, line.anchor.acrossPt, maxSizePt, rotationDeg) } : {}
+	};
+}
+/**
+* Groups positioned PDF text runs into lines of words.
+*
+* Runs are grouped by baseline into lines, ordered down the page, and each line's runs are ordered along the baseline and split into words wherever the geometry between them, or the whitespace their own text carries, says a word ends. A gap wider than a full em of the smaller of the two runs is reported as a column boundary rather than a word space, so a table's columns stay distinct instead of reading as one sentence.
+*
+* Runs set at different angles are never grouped together: each angle is grouped in its own frame and reported as its own block of lines, unrotated text first and the remaining angles in ascending order. No attempt is made to interleave rotated text into the reading order of the unrotated text around it, because a page's geometry alone does not say where a rotated block belongs in that order.
+*
+* Grouping is by baseline alone, with no page segmentation: on a multi-column page whose columns are set at different vertical offsets, a line of one column can fall within tolerance of a line of the next and the two are reported as one line, because from geometry alone at this level that is what they are. The gutter between them still reads as a column boundary, so the separator says where to cut. A caller that needs the columns apart segments the page first, which is what document-outline.js's `segmentPdfRegions` is for, and groups each region's own runs.
+*
+* Known limitations, all of them inherent to what a PDF states rather than to this implementation. Text is reported in visual order, left to right along the baseline: a right-to-left script arrives from the content stream already laid out visually and carries no direction of its own, so a consumer needing logical order applies the Unicode Bidi Algorithm to the result. Vertical writing modes are not recognised, because this package's content interpreter does not read a CMap's WMode and so reports vertically set text with horizontal advances (ExaDev/documents.js#1358), which puts the positions beyond anything grouping could repair. A word hyphenated across a line end is left split, with its hyphen intact, because rejoining it needs to know the two lines belong to one paragraph, which is a semantic judgement this package deliberately leaves to its consumers. Runs with empty text are dropped, and so are the empty words a whitespace-only run would otherwise produce, but no other normalisation of the decoded text is attempted: a ligature and a zero-width character each reach the output exactly as the font's ToUnicode mapping spelled them.
+* @param runs - positioned text runs, in any order
+* @param options - tolerance overrides; each defaults to the exported constant of the same name
+* @returns the grouped lines, in reading order
+*/
+function groupPdfTextRuns(runs, options = {}) {
+	const toleranceEm = options.baselineToleranceEm ?? .6666666666666666;
+	const wordGapEm = options.wordGapEm ?? .125;
+	const columnGapEm = options.columnGapEm ?? 1;
+	const byRotation = /* @__PURE__ */ new Map();
+	for (const run of runs) {
+		if (run.text.length === 0) continue;
+		const rotationDeg = normaliseRotationDeg(run.rotationDeg);
+		const bucket = byRotation.get(rotationDeg);
+		if (bucket === void 0) byRotation.set(rotationDeg, [run]);
+		else bucket.push(run);
+	}
+	const result = [];
+	for (const rotationDeg of [...byRotation.keys()].sort((a, b) => a - b)) {
+		const entries = (byRotation.get(rotationDeg) ?? []).map((run) => project(run, rotationDeg)).sort((a, b) => b.acrossPt - a.acrossPt || a.alongPt - b.alongPt);
+		for (const line of clusterIntoLines(entries, toleranceEm)) {
+			line.entries.sort((a, b) => a.alongPt - b.alongPt);
+			result.push(buildLine(line, rotationDeg, wordGapEm, columnGapEm));
+		}
+	}
+	return result;
+}
+//#endregion
+exports.DEFAULT_BASELINE_TOLERANCE_EM = DEFAULT_BASELINE_TOLERANCE_EM;
+exports.DEFAULT_COLUMN_GAP_EM = DEFAULT_COLUMN_GAP_EM;
+exports.DEFAULT_WORD_GAP_EM = DEFAULT_WORD_GAP_EM;
+exports.groupPdfTextRuns = groupPdfTextRuns;
+exports.runGapPt = runGapPt;
+exports.runsShareBaseline = runsShareBaseline;

package/dist/text-group.d.cts

@@ -0,0 +1,73 @@
+//#region src/text-group.d.ts
+interface PdfTextRunGeometry {
+  readonly text: string;
+  readonly xPt: number;
+  readonly yPt: number;
+  readonly sizePt: number;
+  readonly widthPt?: number;
+  readonly rotationDeg?: number;
+}
+interface PdfTextBox {
+  readonly xPt: number;
+  readonly yPt: number;
+  readonly widthPt: number;
+  readonly heightPt: number;
+}
+type PdfWordSeparator = "none" | "space" | "column";
+interface PdfTextWord<TRun extends PdfTextRunGeometry> {
+  readonly text: string;
+  readonly separatorBefore: PdfWordSeparator;
+  readonly runs: readonly TRun[];
+  readonly bounds?: PdfTextBox;
+}
+interface PdfTextLine<TRun extends PdfTextRunGeometry> {
+  readonly text: string;
+  readonly words: readonly PdfTextWord<TRun>[];
+  readonly baselineYPt: number;
+  readonly rotationDeg: number;
+  readonly bounds?: PdfTextBox;
+}
+interface PdfTextGroupingOptions {
+  readonly baselineToleranceEm?: number;
+  readonly wordGapEm?: number;
+  readonly columnGapEm?: number;
+}
+declare const DEFAULT_BASELINE_TOLERANCE_EM: number;
+declare const DEFAULT_WORD_GAP_EM: number;
+declare const DEFAULT_COLUMN_GAP_EM = 1;
+/**
+ * Whether two positioned runs sit on one visual line.
+ *
+ * The tolerance is a fraction of an em of the smaller of the two runs, never of one nominated run, so a large heading can never claim the small line beneath it. Runs set at different angles never share a line.
+ * @param a - one run
+ * @param b - the other run
+ * @param options - only `baselineToleranceEm` is read; it defaults to {@link DEFAULT_BASELINE_TOLERANCE_EM}
+ * @returns true when the two baselines are within tolerance of each other
+ */
+declare function runsShareBaseline(a: PdfTextRunGeometry, b: PdfTextRunGeometry, options?: PdfTextGroupingOptions): boolean;
+/**
+ * The horizontal gap along the baseline between the end of `previous` and the start of `next`, or undefined when the geometry does not state one.
+ *
+ * Undefined has exactly two causes, and a caller must treat both as "no evidence of a space" rather than substituting zero: `previous` stated no advance width, so where it ends is unknown; or the two runs are set at different angles, so they share no axis to measure along. A negative result is real and means the two runs overlap.
+ * @param previous - the run to the left, in reading order
+ * @param next - the run that follows it
+ * @returns the gap in points, or undefined when it cannot be derived
+ */
+declare function runGapPt(previous: PdfTextRunGeometry, next: PdfTextRunGeometry): number | undefined;
+/**
+ * Groups positioned PDF text runs into lines of words.
+ *
+ * Runs are grouped by baseline into lines, ordered down the page, and each line's runs are ordered along the baseline and split into words wherever the geometry between them, or the whitespace their own text carries, says a word ends. A gap wider than a full em of the smaller of the two runs is reported as a column boundary rather than a word space, so a table's columns stay distinct instead of reading as one sentence.
+ *
+ * Runs set at different angles are never grouped together: each angle is grouped in its own frame and reported as its own block of lines, unrotated text first and the remaining angles in ascending order. No attempt is made to interleave rotated text into the reading order of the unrotated text around it, because a page's geometry alone does not say where a rotated block belongs in that order.
+ *
+ * Grouping is by baseline alone, with no page segmentation: on a multi-column page whose columns are set at different vertical offsets, a line of one column can fall within tolerance of a line of the next and the two are reported as one line, because from geometry alone at this level that is what they are. The gutter between them still reads as a column boundary, so the separator says where to cut. A caller that needs the columns apart segments the page first, which is what document-outline.js's `segmentPdfRegions` is for, and groups each region's own runs.
+ *
+ * Known limitations, all of them inherent to what a PDF states rather than to this implementation. Text is reported in visual order, left to right along the baseline: a right-to-left script arrives from the content stream already laid out visually and carries no direction of its own, so a consumer needing logical order applies the Unicode Bidi Algorithm to the result. Vertical writing modes are not recognised, because this package's content interpreter does not read a CMap's WMode and so reports vertically set text with horizontal advances (ExaDev/documents.js#1358), which puts the positions beyond anything grouping could repair. A word hyphenated across a line end is left split, with its hyphen intact, because rejoining it needs to know the two lines belong to one paragraph, which is a semantic judgement this package deliberately leaves to its consumers. Runs with empty text are dropped, and so are the empty words a whitespace-only run would otherwise produce, but no other normalisation of the decoded text is attempted: a ligature and a zero-width character each reach the output exactly as the font's ToUnicode mapping spelled them.
+ * @param runs - positioned text runs, in any order
+ * @param options - tolerance overrides; each defaults to the exported constant of the same name
+ * @returns the grouped lines, in reading order
+ */
+declare function groupPdfTextRuns<TRun extends PdfTextRunGeometry>(runs: readonly TRun[], options?: PdfTextGroupingOptions): PdfTextLine<TRun>[];
+//#endregion
+export { DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_WORD_GAP_EM, PdfTextBox, PdfTextGroupingOptions, PdfTextLine, PdfTextRunGeometry, PdfTextWord, PdfWordSeparator, groupPdfTextRuns, runGapPt, runsShareBaseline };

package/dist/text-group.d.ts

@@ -0,0 +1,73 @@
+//#region src/text-group.d.ts
+interface PdfTextRunGeometry {
+  readonly text: string;
+  readonly xPt: number;
+  readonly yPt: number;
+  readonly sizePt: number;
+  readonly widthPt?: number;
+  readonly rotationDeg?: number;
+}
+interface PdfTextBox {
+  readonly xPt: number;
+  readonly yPt: number;
+  readonly widthPt: number;
+  readonly heightPt: number;
+}
+type PdfWordSeparator = "none" | "space" | "column";
+interface PdfTextWord<TRun extends PdfTextRunGeometry> {
+  readonly text: string;
+  readonly separatorBefore: PdfWordSeparator;
+  readonly runs: readonly TRun[];
+  readonly bounds?: PdfTextBox;
+}
+interface PdfTextLine<TRun extends PdfTextRunGeometry> {
+  readonly text: string;
+  readonly words: readonly PdfTextWord<TRun>[];
+  readonly baselineYPt: number;
+  readonly rotationDeg: number;
+  readonly bounds?: PdfTextBox;
+}
+interface PdfTextGroupingOptions {
+  readonly baselineToleranceEm?: number;
+  readonly wordGapEm?: number;
+  readonly columnGapEm?: number;
+}
+declare const DEFAULT_BASELINE_TOLERANCE_EM: number;
+declare const DEFAULT_WORD_GAP_EM: number;
+declare const DEFAULT_COLUMN_GAP_EM = 1;
+/**
+ * Whether two positioned runs sit on one visual line.
+ *
+ * The tolerance is a fraction of an em of the smaller of the two runs, never of one nominated run, so a large heading can never claim the small line beneath it. Runs set at different angles never share a line.
+ * @param a - one run
+ * @param b - the other run
+ * @param options - only `baselineToleranceEm` is read; it defaults to {@link DEFAULT_BASELINE_TOLERANCE_EM}
+ * @returns true when the two baselines are within tolerance of each other
+ */
+declare function runsShareBaseline(a: PdfTextRunGeometry, b: PdfTextRunGeometry, options?: PdfTextGroupingOptions): boolean;
+/**
+ * The horizontal gap along the baseline between the end of `previous` and the start of `next`, or undefined when the geometry does not state one.
+ *
+ * Undefined has exactly two causes, and a caller must treat both as "no evidence of a space" rather than substituting zero: `previous` stated no advance width, so where it ends is unknown; or the two runs are set at different angles, so they share no axis to measure along. A negative result is real and means the two runs overlap.
+ * @param previous - the run to the left, in reading order
+ * @param next - the run that follows it
+ * @returns the gap in points, or undefined when it cannot be derived
+ */
+declare function runGapPt(previous: PdfTextRunGeometry, next: PdfTextRunGeometry): number | undefined;
+/**
+ * Groups positioned PDF text runs into lines of words.
+ *
+ * Runs are grouped by baseline into lines, ordered down the page, and each line's runs are ordered along the baseline and split into words wherever the geometry between them, or the whitespace their own text carries, says a word ends. A gap wider than a full em of the smaller of the two runs is reported as a column boundary rather than a word space, so a table's columns stay distinct instead of reading as one sentence.
+ *
+ * Runs set at different angles are never grouped together: each angle is grouped in its own frame and reported as its own block of lines, unrotated text first and the remaining angles in ascending order. No attempt is made to interleave rotated text into the reading order of the unrotated text around it, because a page's geometry alone does not say where a rotated block belongs in that order.
+ *
+ * Grouping is by baseline alone, with no page segmentation: on a multi-column page whose columns are set at different vertical offsets, a line of one column can fall within tolerance of a line of the next and the two are reported as one line, because from geometry alone at this level that is what they are. The gutter between them still reads as a column boundary, so the separator says where to cut. A caller that needs the columns apart segments the page first, which is what document-outline.js's `segmentPdfRegions` is for, and groups each region's own runs.
+ *
+ * Known limitations, all of them inherent to what a PDF states rather than to this implementation. Text is reported in visual order, left to right along the baseline: a right-to-left script arrives from the content stream already laid out visually and carries no direction of its own, so a consumer needing logical order applies the Unicode Bidi Algorithm to the result. Vertical writing modes are not recognised, because this package's content interpreter does not read a CMap's WMode and so reports vertically set text with horizontal advances (ExaDev/documents.js#1358), which puts the positions beyond anything grouping could repair. A word hyphenated across a line end is left split, with its hyphen intact, because rejoining it needs to know the two lines belong to one paragraph, which is a semantic judgement this package deliberately leaves to its consumers. Runs with empty text are dropped, and so are the empty words a whitespace-only run would otherwise produce, but no other normalisation of the decoded text is attempted: a ligature and a zero-width character each reach the output exactly as the font's ToUnicode mapping spelled them.
+ * @param runs - positioned text runs, in any order
+ * @param options - tolerance overrides; each defaults to the exported constant of the same name
+ * @returns the grouped lines, in reading order
+ */
+declare function groupPdfTextRuns<TRun extends PdfTextRunGeometry>(runs: readonly TRun[], options?: PdfTextGroupingOptions): PdfTextLine<TRun>[];
+//#endregion
+export { DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_WORD_GAP_EM, PdfTextBox, PdfTextGroupingOptions, PdfTextLine, PdfTextRunGeometry, PdfTextWord, PdfWordSeparator, groupPdfTextRuns, runGapPt, runsShareBaseline };

package/dist/text-group.js

@@ -0,0 +1,211 @@
+//#region src/text-group.ts
+const DEFAULT_BASELINE_TOLERANCE_EM = 2 / 3;
+const DEFAULT_WORD_GAP_EM = 1 / 8;
+const DEFAULT_COLUMN_GAP_EM = 1;
+const ROTATION_NOISE_DEG = 1e-6;
+const DEGREES_PER_TURN = 360;
+function normaliseRotationDeg(rotationDeg) {
+	return (Math.round((rotationDeg ?? 0) / ROTATION_NOISE_DEG) * ROTATION_NOISE_DEG % DEGREES_PER_TURN + DEGREES_PER_TURN) % DEGREES_PER_TURN;
+}
+const RADIANS_PER_TURN = 2 * Math.PI;
+function baselineAxis(rotationDeg) {
+	const radians = rotationDeg * RADIANS_PER_TURN / DEGREES_PER_TURN;
+	return {
+		cos: Math.cos(radians),
+		sin: Math.sin(radians)
+	};
+}
+function project(run, rotationDeg) {
+	const { cos, sin } = baselineAxis(rotationDeg);
+	return {
+		run,
+		alongPt: run.xPt * cos + run.yPt * sin,
+		acrossPt: run.yPt * cos - run.xPt * sin,
+		sizePt: run.sizePt
+	};
+}
+function unproject(alongPt, acrossPt, rotationDeg) {
+	const { cos, sin } = baselineAxis(rotationDeg);
+	return {
+		xPt: alongPt * cos - acrossPt * sin,
+		yPt: alongPt * sin + acrossPt * cos
+	};
+}
+/**
+* Whether two positioned runs sit on one visual line.
+*
+* The tolerance is a fraction of an em of the smaller of the two runs, never of one nominated run, so a large heading can never claim the small line beneath it. Runs set at different angles never share a line.
+* @param a - one run
+* @param b - the other run
+* @param options - only `baselineToleranceEm` is read; it defaults to {@link DEFAULT_BASELINE_TOLERANCE_EM}
+* @returns true when the two baselines are within tolerance of each other
+*/
+function runsShareBaseline(a, b, options = {}) {
+	const rotationDeg = normaliseRotationDeg(a.rotationDeg);
+	if (rotationDeg !== normaliseRotationDeg(b.rotationDeg)) return false;
+	const toleranceEm = options.baselineToleranceEm ?? .6666666666666666;
+	return Math.abs(project(a, rotationDeg).acrossPt - project(b, rotationDeg).acrossPt) <= toleranceEm * Math.min(a.sizePt, b.sizePt);
+}
+/**
+* The horizontal gap along the baseline between the end of `previous` and the start of `next`, or undefined when the geometry does not state one.
+*
+* Undefined has exactly two causes, and a caller must treat both as "no evidence of a space" rather than substituting zero: `previous` stated no advance width, so where it ends is unknown; or the two runs are set at different angles, so they share no axis to measure along. A negative result is real and means the two runs overlap.
+* @param previous - the run to the left, in reading order
+* @param next - the run that follows it
+* @returns the gap in points, or undefined when it cannot be derived
+*/
+function runGapPt(previous, next) {
+	const rotationDeg = normaliseRotationDeg(previous.rotationDeg);
+	if (rotationDeg !== normaliseRotationDeg(next.rotationDeg)) return;
+	const previousWidthPt = previous.widthPt;
+	if (previousWidthPt === void 0) return;
+	return project(next, rotationDeg).alongPt - (project(previous, rotationDeg).alongPt + previousWidthPt);
+}
+function clusterIntoLines(entries, toleranceEm) {
+	const lines = [];
+	for (const entry of entries) {
+		let nearest;
+		for (const line of lines) if (runsShareBaseline(line.anchor.run, entry.run, { baselineToleranceEm: toleranceEm })) nearest = line;
+		if (nearest === void 0) lines.push({
+			anchor: entry,
+			entries: [entry]
+		});
+		else nearest.entries.push(entry);
+	}
+	return lines;
+}
+function tokeniseRun(text) {
+	const words = text.match(/\S+/g) ?? [];
+	const leadingSpace = /^\s/.test(text);
+	const trailingSpace = /\s$/.test(text);
+	return {
+		words,
+		leadingSpace,
+		trailingSpace,
+		whole: words.length === 1 && !leadingSpace && !trailingSpace
+	};
+}
+const SEPARATOR_TEXT = {
+	none: "",
+	space: " ",
+	column: "	"
+};
+function separatorForGap(gapPt, smallerSizePt, wordGapEm, columnGapEm) {
+	if (gapPt === void 0) return "none";
+	if (gapPt >= columnGapEm * smallerSizePt) return "column";
+	if (gapPt >= wordGapEm * smallerSizePt) return "space";
+	return "none";
+}
+function boundsOf(minAlongPt, maxAlongEndPt, acrossPt, maxSizePt, rotationDeg) {
+	const origin = unproject(minAlongPt, acrossPt, rotationDeg);
+	return {
+		xPt: origin.xPt,
+		yPt: origin.yPt,
+		widthPt: maxAlongEndPt - minAlongPt,
+		heightPt: maxSizePt
+	};
+}
+function buildWords(line, rotationDeg, wordGapEm, columnGapEm) {
+	const working = [];
+	let previous;
+	for (const entry of line.entries) {
+		const tokens = tokeniseRun(entry.run.text);
+		const gapSeparator = previous === void 0 ? "none" : separatorForGap(runGapPt(previous.entry.run, entry.run), Math.min(previous.entry.sizePt, entry.sizePt), wordGapEm, columnGapEm);
+		const pendingSpace = previous?.trailingSpace === true;
+		let separator = "none";
+		if (working.length > 0) separator = gapSeparator === "none" && (pendingSpace || tokens.leadingSpace) ? "space" : gapSeparator;
+		const widthPt = entry.run.widthPt;
+		const alongEndPt = entry.alongPt + (widthPt ?? 0);
+		tokens.words.forEach((word, index) => {
+			const last = working[working.length - 1];
+			if (index === 0 && separator === "none" && last !== void 0) {
+				last.text += word;
+				last.runs.push(entry.run);
+				last.measurable = last.measurable && tokens.whole && widthPt !== void 0;
+				last.minAlongPt = Math.min(last.minAlongPt, entry.alongPt);
+				last.maxAlongEndPt = Math.max(last.maxAlongEndPt, alongEndPt);
+				last.maxSizePt = Math.max(last.maxSizePt, entry.sizePt);
+				return;
+			}
+			working.push({
+				text: word,
+				separatorBefore: index === 0 ? separator : "space",
+				runs: [entry.run],
+				measurable: tokens.whole && widthPt !== void 0,
+				minAlongPt: entry.alongPt,
+				maxAlongEndPt: alongEndPt,
+				maxSizePt: entry.sizePt
+			});
+		});
+		previous = {
+			entry,
+			trailingSpace: tokens.trailingSpace
+		};
+	}
+	return working.map((word) => ({
+		text: word.text,
+		separatorBefore: word.separatorBefore,
+		runs: word.runs,
+		...word.measurable ? { bounds: boundsOf(word.minAlongPt, word.maxAlongEndPt, line.anchor.acrossPt, word.maxSizePt, rotationDeg) } : {}
+	}));
+}
+function buildLine(line, rotationDeg, wordGapEm, columnGapEm) {
+	const words = buildWords(line, rotationDeg, wordGapEm, columnGapEm);
+	const text = words.map((word) => SEPARATOR_TEXT[word.separatorBefore] + word.text).join("");
+	let minAlongPt = Number.POSITIVE_INFINITY;
+	let maxAlongEndPt = Number.NEGATIVE_INFINITY;
+	let maxSizePt = 0;
+	let measurable = true;
+	for (const entry of line.entries) {
+		const widthPt = entry.run.widthPt;
+		if (widthPt === void 0) measurable = false;
+		minAlongPt = Math.min(minAlongPt, entry.alongPt);
+		maxAlongEndPt = Math.max(maxAlongEndPt, entry.alongPt + (widthPt ?? 0));
+		maxSizePt = Math.max(maxSizePt, entry.sizePt);
+	}
+	return {
+		text,
+		words,
+		baselineYPt: line.anchor.acrossPt,
+		rotationDeg,
+		...measurable ? { bounds: boundsOf(minAlongPt, maxAlongEndPt, line.anchor.acrossPt, maxSizePt, rotationDeg) } : {}
+	};
+}
+/**
+* Groups positioned PDF text runs into lines of words.
+*
+* Runs are grouped by baseline into lines, ordered down the page, and each line's runs are ordered along the baseline and split into words wherever the geometry between them, or the whitespace their own text carries, says a word ends. A gap wider than a full em of the smaller of the two runs is reported as a column boundary rather than a word space, so a table's columns stay distinct instead of reading as one sentence.
+*
+* Runs set at different angles are never grouped together: each angle is grouped in its own frame and reported as its own block of lines, unrotated text first and the remaining angles in ascending order. No attempt is made to interleave rotated text into the reading order of the unrotated text around it, because a page's geometry alone does not say where a rotated block belongs in that order.
+*
+* Grouping is by baseline alone, with no page segmentation: on a multi-column page whose columns are set at different vertical offsets, a line of one column can fall within tolerance of a line of the next and the two are reported as one line, because from geometry alone at this level that is what they are. The gutter between them still reads as a column boundary, so the separator says where to cut. A caller that needs the columns apart segments the page first, which is what document-outline.js's `segmentPdfRegions` is for, and groups each region's own runs.
+*
+* Known limitations, all of them inherent to what a PDF states rather than to this implementation. Text is reported in visual order, left to right along the baseline: a right-to-left script arrives from the content stream already laid out visually and carries no direction of its own, so a consumer needing logical order applies the Unicode Bidi Algorithm to the result. Vertical writing modes are not recognised, because this package's content interpreter does not read a CMap's WMode and so reports vertically set text with horizontal advances (ExaDev/documents.js#1358), which puts the positions beyond anything grouping could repair. A word hyphenated across a line end is left split, with its hyphen intact, because rejoining it needs to know the two lines belong to one paragraph, which is a semantic judgement this package deliberately leaves to its consumers. Runs with empty text are dropped, and so are the empty words a whitespace-only run would otherwise produce, but no other normalisation of the decoded text is attempted: a ligature and a zero-width character each reach the output exactly as the font's ToUnicode mapping spelled them.
+* @param runs - positioned text runs, in any order
+* @param options - tolerance overrides; each defaults to the exported constant of the same name
+* @returns the grouped lines, in reading order
+*/
+function groupPdfTextRuns(runs, options = {}) {
+	const toleranceEm = options.baselineToleranceEm ?? .6666666666666666;
+	const wordGapEm = options.wordGapEm ?? .125;
+	const columnGapEm = options.columnGapEm ?? 1;
+	const byRotation = /* @__PURE__ */ new Map();
+	for (const run of runs) {
+		if (run.text.length === 0) continue;
+		const rotationDeg = normaliseRotationDeg(run.rotationDeg);
+		const bucket = byRotation.get(rotationDeg);
+		if (bucket === void 0) byRotation.set(rotationDeg, [run]);
+		else bucket.push(run);
+	}
+	const result = [];
+	for (const rotationDeg of [...byRotation.keys()].sort((a, b) => a - b)) {
+		const entries = (byRotation.get(rotationDeg) ?? []).map((run) => project(run, rotationDeg)).sort((a, b) => b.acrossPt - a.acrossPt || a.alongPt - b.alongPt);
+		for (const line of clusterIntoLines(entries, toleranceEm)) {
+			line.entries.sort((a, b) => a.alongPt - b.alongPt);
+			result.push(buildLine(line, rotationDeg, wordGapEm, columnGapEm));
+		}
+	}
+	return result;
+}
+//#endregion
+export { DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_WORD_GAP_EM, groupPdfTextRuns, runGapPt, runsShareBaseline };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdf-codec.js",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "description": "Hand-written, dependency-minimal PDF codec: parses arbitrary real-world PDFs and generates new ones, built on its own codec-owned LayoutDocument item model and Zod 4 codecs.",
   "type": "module",
   "repository": {
@@ -72,8 +72,8 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "byte-codec": "1.6.2",
-    "document-schema.js": "7.11.4",
+    "byte-codec": "1.6.3",
+    "document-schema.js": "7.11.5",
     "fflate": "0.8.3",
     "zod": "4.4.3"
   },