pdf-codec.js 5.0.1 → 5.2.0

package/dist/text-group.d.ts

@@ -0,0 +1,75 @@
+//#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;
+  readonly writingMode?: "vertical";
+}
+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 writingMode?: "vertical";
+  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. A vertically set run is grouped into columns rather than lines, from the writingMode its own reader reported, and its column is reported with a rotationDeg of 270 and its own writingMode; columns order right to left, the direction vertical setting is read in. What is NOT recognised is a predefined non-Identity CMap's own byte decoding, so a vertically set font using one (90ms-RKSJ-V and its siblings) still has its codes read as two-byte CIDs, which is this package's own long-standing composite-font limit rather than anything about writing mode. 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,221 @@
+//#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;
+const VERTICAL_ADVANCE_OFFSET_DEG = -90;
+function advanceAngleDeg(run) {
+	const raw = (run.rotationDeg ?? 0) + (run.writingMode === "vertical" ? VERTICAL_ADVANCE_OFFSET_DEG : 0);
+	return (Math.round(raw / 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 = advanceAngleDeg(a);
+	if (rotationDeg !== advanceAngleDeg(b) || a.writingMode !== b.writingMode) 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 = advanceAngleDeg(previous);
+	if (rotationDeg !== advanceAngleDeg(next) || previous.writingMode !== next.writingMode) 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, vertical, 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,
+		...vertical ? { writingMode: "vertical" } : {},
+		...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. A vertically set run is grouped into columns rather than lines, from the writingMode its own reader reported, and its column is reported with a rotationDeg of 270 and its own writingMode; columns order right to left, the direction vertical setting is read in. What is NOT recognised is a predefined non-Identity CMap's own byte decoding, so a vertically set font using one (90ms-RKSJ-V and its siblings) still has its codes read as two-byte CIDs, which is this package's own long-standing composite-font limit rather than anything about writing mode. 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 buckets = /* @__PURE__ */ new Map();
+	for (const run of runs) {
+		if (run.text.length === 0) continue;
+		const rotationDeg = advanceAngleDeg(run);
+		const vertical = run.writingMode === "vertical";
+		const key = `${String(rotationDeg)}|${String(vertical)}`;
+		const bucket = buckets.get(key);
+		if (bucket === void 0) buckets.set(key, {
+			rotationDeg,
+			vertical,
+			runs: [run]
+		});
+		else bucket.runs.push(run);
+	}
+	const result = [];
+	const ordered = [...buckets.values()].sort((a, b) => a.rotationDeg - b.rotationDeg || Number(a.vertical) - Number(b.vertical));
+	for (const bucket of ordered) {
+		const entries = bucket.runs.map((run) => project(run, bucket.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, bucket.rotationDeg, bucket.vertical, 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.1",
+  "version": "5.2.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": {