reamkit 1.30.0 → 1.31.0

package/dist/esm/pdf-reader/page-numbers.d.ts

@@ -0,0 +1,53 @@
+import { NumberingFormat } from '../core/document-model/index.js';
+/** A page's number as its band prints it. */
+export interface PageNumber {
+    /** The numeral as the page shows it: "iv", "47". */
+    readonly text: string;
+    readonly value: number;
+    readonly format: NumberingFormat;
+}
+/** A stretch of pages counted in one sequence (§17.6.12). */
+export interface NumberingRun {
+    /** The first page of the stretch. */
+    readonly from: number;
+    readonly format: NumberingFormat;
+    /** The number the stretch's first page carries. */
+    readonly start: number;
+}
+/** What the pages' bands say about their numbering. */
+export interface PageNumbering {
+    /** Each page's number, where its band shows one. */
+    readonly numbers: ReadonlyArray<PageNumber | undefined>;
+    /** The sequences the pages are counted in, first page first. */
+    readonly runs: ReadonlyArray<NumberingRun>;
+}
+/**
+ * The numerals a band's text holds, in order.
+ *
+ * @param text The band's text on one page.
+ * @returns Its numerals; a roman one only where it is a numeral as written.
+ */
+export declare function numeralsIn(text: string): Array<PageNumber>;
+/**
+ * The page numbers a document's running band prints, and the sequences they
+ * run in.
+ *
+ * The number is the numeral that CHANGES from page to page: "Page 3 of 10" is
+ * counted by its first, "Chapter I — 47" by its last. A sequence goes on while
+ * each page's number is one more than the last in the same numerals, and
+ * starts again where it does not — i, ii, iii and then 1 are two sequences.
+ * A page whose band shows no number is counted on.
+ *
+ * @param bands Each page's band text, or undefined where the page has none.
+ * @returns The numbering, or undefined where the bands show no page number
+ *          worth reading as one.
+ */
+export declare function pageNumberingOf(bands: ReadonlyArray<string | undefined>): PageNumbering | undefined;
+/**
+ * The sequence a page is counted in.
+ *
+ * @param runs The document's sequences, first page first.
+ * @param page The page.
+ * @returns The run that page belongs to.
+ */
+export declare function runOf(runs: ReadonlyArray<NumberingRun>, page: number): NumberingRun | undefined;

package/dist/esm/pdf-reader/page-numbers.js

@@ -0,0 +1,167 @@
+//#region src/pdf-reader/page-numbers.ts
+/** A numeral standing as a word of its own: digits, or roman in one case. */
+var NUMERAL = /(?<=^|\s)(\d{1,4}|[ivxlcdm]{1,9}|[IVXLCDM]{1,9})(?=\s|$)/gu;
+/**
+* More sequences than this and the "numbers" are something else that changes
+* from page to page — a date, a figure count — and the pages are left counted
+* the ordinary way.
+*/
+var MOST_RUNS = 4;
+/**
+* …unless the sequences run long: a book leaves its blank pages out and skips
+* their numbers, and freeculture.pdf's count jumps two at five of its chapters
+* — seven sequences over three hundred and thirty-five numbered pages, and
+* read as none its footer printed no number at all. A date or a figure count
+* starts a sequence of its own on nearly every page.
+*/
+var LEAST_RUN_PAGES = 10;
+/**
+* The numerals a band's text holds, in order.
+*
+* @param text The band's text on one page.
+* @returns Its numerals; a roman one only where it is a numeral as written.
+*/
+function numeralsIn(text) {
+	const out = [];
+	for (const m of text.matchAll(NUMERAL)) {
+		const token = m[1];
+		if (/^\d+$/u.test(token)) {
+			out.push({
+				text: token,
+				value: Number(token),
+				format: "decimal"
+			});
+			continue;
+		}
+		const value = romanValue(token);
+		if (value === void 0) continue;
+		out.push({
+			text: token,
+			value,
+			format: token === token.toLowerCase() ? "lowerRoman" : "upperRoman"
+		});
+	}
+	return out;
+}
+/**
+* A roman numeral's value, where the letters ARE one as a numeral is written
+* — "iv", "xiv", "MCMXC" — and not merely letters a numeral uses: "ic", "vx"
+* and "mix" are words or nothing.
+*/
+function romanValue(token) {
+	const upper = token.toUpperCase();
+	const worth = {
+		I: 1,
+		V: 5,
+		X: 10,
+		L: 50,
+		C: 100,
+		D: 500,
+		M: 1e3
+	};
+	let value = 0;
+	for (let i = 0; i < upper.length; i++) {
+		const here = worth[upper[i]];
+		const next = worth[upper[i + 1] ?? ""] ?? 0;
+		value += here < next ? -here : here;
+	}
+	return value > 0 && value < 4e3 && toRoman(value) === upper ? value : void 0;
+}
+/** The canonical roman numeral for a value, which is how a valid one reads. */
+function toRoman(value) {
+	const steps = [
+		[1e3, "M"],
+		[900, "CM"],
+		[500, "D"],
+		[400, "CD"],
+		[100, "C"],
+		[90, "XC"],
+		[50, "L"],
+		[40, "XL"],
+		[10, "X"],
+		[9, "IX"],
+		[5, "V"],
+		[4, "IV"],
+		[1, "I"]
+	];
+	let out = "";
+	let left = value;
+	for (const [n, s] of steps) while (left >= n) {
+		out += s;
+		left -= n;
+	}
+	return out;
+}
+/**
+* The page numbers a document's running band prints, and the sequences they
+* run in.
+*
+* The number is the numeral that CHANGES from page to page: "Page 3 of 10" is
+* counted by its first, "Chapter I — 47" by its last. A sequence goes on while
+* each page's number is one more than the last in the same numerals, and
+* starts again where it does not — i, ii, iii and then 1 are two sequences.
+* A page whose band shows no number is counted on.
+*
+* @param bands Each page's band text, or undefined where the page has none.
+* @returns The numbering, or undefined where the bands show no page number
+*          worth reading as one.
+*/
+function pageNumberingOf(bands) {
+	const found = bands.map((text) => text === void 0 ? [] : numeralsIn(text));
+	const counted = found.filter((n) => n.length > 0);
+	if (counted.length < 2) return void 0;
+	const width = Math.min(...counted.map((n) => n.length));
+	let at = -1;
+	for (let k = 0; k < width && at < 0; k++) if (new Set(counted.map((n) => n[k].text)).size > 1) at = k;
+	if (at < 0) return void 0;
+	const numbers = found.map((n) => n[at]);
+	const runs = [];
+	numbers.forEach((number, page) => {
+		if (number === void 0) return;
+		const run = runs[runs.length - 1];
+		if (run !== void 0) {
+			const expected = run.start + (page - run.from);
+			if (number.format === run.format && number.value === expected) return;
+			runs.push({
+				from: page,
+				format: number.format,
+				start: number.value
+			});
+			return;
+		}
+		const start = number.value - page;
+		if (start >= 1) runs.push({
+			from: 0,
+			format: number.format,
+			start
+		});
+		else runs.push({
+			from: 0,
+			format: "decimal",
+			start: 1
+		}, {
+			from: page,
+			format: number.format,
+			start: number.value
+		});
+	});
+	if (runs.length === 0 || runs.length > Math.max(MOST_RUNS, counted.length / LEAST_RUN_PAGES)) return;
+	return {
+		numbers,
+		runs
+	};
+}
+/**
+* The sequence a page is counted in.
+*
+* @param runs The document's sequences, first page first.
+* @param page The page.
+* @returns The run that page belongs to.
+*/
+function runOf(runs, page) {
+	let found;
+	for (const run of runs) if (run.from <= page) found = run;
+	return found;
+}
+//#endregion
+export { pageNumberingOf, runOf };

package/dist/esm/pdf-reader/tagged.js

@@ -3,13 +3,14 @@ import { ResourceStore } from "../core/ir/resources.js";
 import { FEATURES } from "../core/ir/features.js";
 import { collectEmbeddedFonts } from "./embedded-fonts.js";
 import { collectFaceFamilies } from "./font.js";
+import { displayOf, placeRuns, placeVectors, textFrameOf, wordsTurnOf } from "./display.js";
+import { ASCENDER, CARRIER_LINE_PT, buildFlowDoc, dedupeLosses, floatOntoSheet, imageBlock, paragraphBlock, paragraphFromRuns, sectionFromPdfPages, sectionOnSheet, shapeBlock, spaceAfter, withMeasuredMargins } from "./flow-build.js";
+import { faceOutlinesOf, kernedFaces, pageSpacing } from "./face-outlines.js";
 import { extractPageText } from "./text.js";
 import { collectPageVectors } from "./vector.js";
-import { displayOf, placeRuns, placeVectors } from "./display.js";
-import { buildFlowDoc, dedupeLosses, imageBlock, paragraphBlock, paragraphFromRuns, sectionFromPdfPages, shapeBlock, spaceAfter, withMeasuredMargins } from "./flow-build.js";
 import { collectPageImages } from "./images.js";
 import { markDrawnRules } from "./text-rules.js";
-import { endedParagraph } from "./layout.js";
+import { FOOTER_PART, HEADER_PART, endedParagraph, footerBand, numberedFrom, numberingOf, pageTextEdges, runningFoot, stepsBetweenWords } from "./layout.js";
 import { readStructTree } from "./struct-tree.js";
 //#region src/pdf-reader/tagged.ts
 var ASSUMED_CONTENT_WIDTH_PT = 468;
@@ -31,8 +32,15 @@ function reconstructTaggedPdf(file) {
 	const root = readStructTree(file);
 	if (!root) return void 0;
 	const pages = file.pages();
-	const shown = pages.map((page) => displayOf(page));
-	const placedRuns = pages.map((page, i) => placeRuns(extractPageText(file, page), shown[i]));
+	const sheets = pages.map((page) => displayOf(page));
+	const painted = /* @__PURE__ */ new Map();
+	const extracted = pages.map((page) => extractPageText(file, page, painted));
+	const spacing = pageSpacing(extracted);
+	const onSheets = extracted.map((runs, i) => placeRuns(runs, sheets[i]));
+	const worded = onSheets.filter((runs) => runs.some((r) => r.text.trim() !== ""));
+	const turned = worded.length > 0 && worded.every((runs) => wordsTurnOf(runs) === 270);
+	const shown = turned ? sheets.map((sheet) => textFrameOf(sheet)) : sheets;
+	const placedRuns = turned ? extracted.map((runs, i) => placeRuns(runs, shown[i])) : onSheets;
 	const vectorLosses = [];
 	const pageVectors = pages.map((page, i) => {
 		const lifted = collectPageVectors(file, page, collectPageImages(file, page).images.map((img) => ({
@@ -106,6 +114,23 @@ function reconstructTaggedPdf(file) {
 	});
 	const collectText = (node) => squash([textOf(node), ...node.children.map(collectText)].join(" "));
 	const setting = /* @__PURE__ */ new Map();
+	const pageOf = /* @__PURE__ */ new Map();
+	/** The highest baseline a page's own paragraphs stand on, page space (y up). */
+	const highestOf = (own) => {
+		const tops = own.flatMap((el) => {
+			const set = setting.get(el);
+			return set ? [set.top] : [];
+		});
+		return tops.length > 0 ? Math.max(...tops) : void 0;
+	};
+	/** The lowest baseline a page's own paragraphs reach, page space (y up). */
+	const lowestOf = (own) => {
+		const bottoms = own.flatMap((el) => {
+			const set = setting.get(el);
+			return set ? [set.bottom] : [];
+		});
+		return bottoms.length > 0 ? Math.min(...bottoms) : void 0;
+	};
 	/** The topmost and bottommost baseline under a node, and its largest face. */
 	function baselinesOf(node) {
 		let top;
@@ -205,33 +230,48 @@ function reconstructTaggedPdf(file) {
 		}).filter((l) => l.spans.some((sp) => sp.text.trim().length > 0));
 	}
 	function emit(node, out) {
+		const on = (el) => {
+			const page = firstPageOf(node);
+			if (page !== void 0) pageOf.set(el, page);
+			return el;
+		};
 		if (node.type === "Table") {
 			const table = buildTable(node);
-			if (table) out.push(table);
+			if (table) out.push(on(table));
 			return;
 		}
 		if (node.type === "Figure") {
 			for (const img of imagesForNode(node)) {
 				emitted.add(img);
-				out.push(imageBlock(img, resources, node.alt));
+				out.push(on(imageBlock(img, resources, node.alt)));
 			}
 			return;
 		}
 		if (node.type === "LI") {
 			const text = collectText(node);
-			if (text.length > 0) out.push(paragraphBlock(text, void 0));
+			if (text.length > 0) out.push(on(paragraphBlock(text, void 0)));
 			return;
 		}
 		if (node.children.length === 0) {
 			if (textOf(node).length > 0) for (const part of settingsOf(node)) {
 				const el = paragraphFromRuns(part.spans, headingLevel(node.type));
 				setting.set(el, part.set);
-				out.push(el);
+				out.push(on(el));
 			}
 			return;
 		}
 		for (const child of node.children) emit(child, out);
 	}
+	/** The first page any marked content under a node stands on. */
+	function firstPageOf(node) {
+		let first;
+		const visit = (n) => {
+			for (const { page } of n.mcids) if (first === void 0 || page < first) first = page;
+			for (const child of n.children) visit(child);
+		};
+		visit(node);
+		return first;
+	}
 	function buildTable(tableNode) {
 		const raw = [];
 		const collectRows = (n) => {
@@ -295,9 +335,14 @@ function reconstructTaggedPdf(file) {
 			cells
 		};
 	}
-	const body = [];
-	emit(root, body);
-	spaceParagraphs(body, setting, shown[0]?.height ?? 0);
+	const named = [];
+	emit(root, named);
+	const byPage = pages.map(() => []);
+	let current = 0;
+	for (const el of named) {
+		current = Math.max(current, pageOf.get(el) ?? current);
+		byPage[current].push(el);
+	}
 	let zOrder = -1e6;
 	imageLosses.push(...vectorLosses);
 	pages.forEach((_page, index) => {
@@ -306,31 +351,104 @@ function reconstructTaggedPdf(file) {
 			top: shown[index].height
 		};
 		const taken = ruled[index]?.consumed;
+		const drawn = [];
 		for (const v of pageVectors[index] ?? []) {
 			if (taken?.has(v) === true) continue;
-			body.push(shapeBlock(v, frame, zOrder++, true));
+			const shape = shapeBlock(v, frame, zOrder++, true);
+			drawn.push(turned ? floatOntoSheet(shape, shown[index].height) : shape);
 		}
+		byPage[index].unshift(...drawn);
 	});
-	const orphans = [];
 	pageImages.forEach((p, page) => {
-		for (const img of p.images) if (!emitted.has(img)) orphans.push({
-			page,
-			img
-		});
+		const left = p.images.filter((img) => !emitted.has(img)).sort((a, b) => b.y - a.y);
+		byPage[page].push(...left.map((img) => imageBlock(img, resources)));
+	});
+	if (byPage.every((own) => own.length === 0)) return void 0;
+	const loose = placedRuns.map((runs, i) => shown[i].sheet ? [] : runs.filter((r) => !claimed.has(r)));
+	const foot = runningFoot(loose, shown, "foot");
+	const head = runningFoot(loose, shown, "head");
+	const numberedBand = foot?.numbered === true ? foot : head?.numbered === true ? head : void 0;
+	const numbering = numberingOf(numberedBand);
+	const lifted = (r, i) => foot?.lift[i]?.has(r) === true || head?.lift[i]?.has(r) === true;
+	const measured = withMeasuredMargins(sectionFromPdfPages(pages, shown[0]), shown, placedRuns.map((runs, i) => runs.filter((r) => !lifted(r, i))), pageImages.map((p) => p.images), foot?.band);
+	const body = [];
+	const top = measured?.margins?.top ?? 0;
+	const bottom = measured?.margins?.bottom ?? 0;
+	const ends = byPage.map((own) => lowestOf(own));
+	const tops = byPage.map((own) => highestOf(own));
+	const sectionsFrom = (numbering?.runs ?? []).map((run) => run.from).filter((from) => from > 0);
+	const endsAt = [];
+	let sectionFrom = 0;
+	byPage.forEach((own, index) => {
+		if (sectionsFrom.includes(index)) {
+			endsAt.push({
+				at: body.length,
+				from: sectionFrom
+			});
+			sectionFrom = index;
+		}
+		const height = shown[index]?.height ?? 0;
+		spaceParagraphs(own, setting, height);
+		const ended = ends[index - 1];
+		const opens = index > 0 && (own.length === 0 || ended === void 0 || ended - bottom > (height - top - bottom) * SHORT_PAGE_SHARE);
+		const lead = own.findIndex((el) => !floats(el));
+		const set = lead >= 0 ? setting.get(own[lead]) : void 0;
+		const fresh = index === 0 || opens || sectionsFrom.includes(index);
+		const highest = tops[index];
+		const first = set !== void 0 && highest !== void 0 && set.top >= highest - set.size;
+		if (fresh && first && measured?.margins) {
+			const gap = height - top - (set.top + set.size * ASCENDER);
+			if (gap > 1) own[lead] = spacedBefore(own[lead], gap);
+		}
+		if (opens && !sectionsFrom.includes(index)) body.push(pageBreak(true));
+		else if (index === 0 && own.length === 0 && pages.length > 1) body.push(pageBreak(false));
+		body.push(...own);
 	});
-	orphans.sort((a, b) => a.page - b.page || b.img.y - a.img.y);
-	for (const { img } of orphans) body.push(imageBlock(img, resources));
-	if (body.length === 0) return void 0;
 	if (placedRuns.some((page) => page.some((r) => r.text.includes("�")))) imageLosses.push({
 		severity: "dropped",
 		feature: FEATURES.text,
 		detail: "some glyphs map to no character — the font states no /ToUnicode and its program says nothing either, so that text is unrecoverable"
 	});
-	const onPage = placedRuns.flat().reduce((n, r) => n + r.text.length, 0);
+	const onPage = placedRuns.flatMap((runs, i) => runs.filter((r) => !lifted(r, i))).reduce((n, r) => n + r.text.length, 0);
 	const reached = [...claimed].reduce((n, r) => n + r.text.length, 0);
 	if (onPage > 0 && reached * 2 < onPage) return void 0;
+	endsAt.push({
+		at: body.length,
+		from: sectionFrom
+	});
+	const stepped0 = stepsBetweenWords(placedRuns[0] ?? []);
+	const edges0 = pageTextEdges(placedRuns[0] ?? []);
+	const numeralOf = (of) => {
+		if (of === void 0 || of !== numberedBand || numbering === void 0) return void 0;
+		const first = of.lift.findIndex((set) => set.size > 0);
+		return first >= 0 ? numbering.numbers[first]?.text : void 0;
+	};
+	const footBand = foot ? footerBand(foot.band, stepped0, edges0, foot.numbered, numeralOf(foot)) : [];
+	const headBand = head ? footerBand(head.band, stepped0, edges0, head.numbered, numeralOf(head)) : [];
+	const sectionAt = (from) => {
+		const base = sectionOnSheet(measured, shown[0]);
+		return base ? {
+			...base,
+			...numberedFrom(numbering, from),
+			...footBand.length > 0 ? { footers: [{
+				type: "default",
+				relationshipId: FOOTER_PART
+			}] } : {},
+			...headBand.length > 0 ? { headers: [{
+				type: "default",
+				relationshipId: HEADER_PART
+			}] } : {}
+		} : base;
+	};
+	const sections = endsAt.length > 1 ? endsAt.flatMap((end) => {
+		const properties = sectionAt(end.from);
+		return properties ? [{
+			properties,
+			endIndex: end.at
+		}] : [];
+	}) : [];
 	return {
-		doc: buildFlowDoc(body, resources, withMeasuredMargins(sectionFromPdfPages(pages), shown, placedRuns, pageImages.map((p) => p.images)), collectEmbeddedFonts(file, pages, imageLosses), [], void 0, collectFaceFamilies(file, pages)),
+		doc: buildFlowDoc(body, resources, sectionAt(0), collectEmbeddedFonts(file, pages, imageLosses), sections, footBand.length > 0 || headBand.length > 0 ? new Map([...footBand.length > 0 ? [[FOOTER_PART, footBand]] : [], ...headBand.length > 0 ? [[HEADER_PART, headBand]] : []]) : void 0, collectFaceFamilies(file, pages), faceOutlinesOf(painted, spacing), kernedFaces(spacing)),
 		losses: imageLosses
 	};
 }
@@ -437,6 +555,47 @@ var MCID_SPACE_EM = .15;
 function squash(text) {
 	return text.replace(/\s+/g, " ").trim();
 }
+/**
+* How much of a page's text area the page may leave empty below its last line
+* and still be FULL: a page that ends higher than this ended on purpose.
+*/
+var SHORT_PAGE_SHARE = .25;
+/** Whether an element FLOATS — a drawing anchored to its page, which takes no room. */
+function floats(el) {
+	return el.kind === "image" && el.image.float !== void 0 || el.kind === "shape" && el.shape.float !== void 0;
+}
+/** A paragraph given the space the page left above it; anything else as it is. */
+function spacedBefore(el, before) {
+	if (el.kind !== "paragraph") return el;
+	const properties = {
+		...el.paragraph.properties,
+		spacingBefore: pt(before)
+	};
+	return {
+		...el,
+		paragraph: {
+			...el.paragraph,
+			properties
+		}
+	};
+}
+/**
+* An empty paragraph that takes no room: the carrier of a page break, or of
+* nothing at all on a blank first sheet the next page's break has to follow.
+*/
+function pageBreak(breaks) {
+	return {
+		kind: "paragraph",
+		paragraph: {
+			properties: {
+				...breaks ? { pageBreakBefore: true } : {},
+				spacingLine: CARRIER_LINE_PT,
+				spacingLineRule: "exact"
+			},
+			runs: []
+		}
+	};
+}
 function headingLevel(type) {
 	const m = /^H([1-6])$/.exec(type);
 	return m ? Number(m[1]) - 1 : void 0;

package/dist/esm/pdf-reader/text.d.ts

@@ -1,4 +1,5 @@
 import { ContentFont, TextRun } from './content.js';
+import { ShownCodes } from './face-outlines.js';
 import { PdfDict } from '../pdf/objects.js';
 import { PdfFile, PdfPage } from './document.js';
 /**
@@ -8,11 +9,13 @@ import { PdfFile, PdfPage } from './document.js';
  * origin falls inside a `/Link` annotation's `/Rect` with that link's URI (EP8)
  * so hyperlinks survive.
  *
- * @param file The owning {@link PdfFile}.
- * @param page The page to extract.
+ * @param file  The owning {@link PdfFile}.
+ * @param page  The page to extract.
+ * @param painted Where to gather the codes each font painted, for a caller
+ *                that embeds the faces (see `./face-outlines`).
  * @returns The page's runs, each carrying an `href` when it sits under a link.
  */
-export declare function extractPageText(file: PdfFile, page: PdfPage): Array<TextRun>;
+export declare function extractPageText(file: PdfFile, page: PdfPage, painted?: ShownCodes): Array<TextRun>;
 /**
  * The `/Font` resources of one dictionary, built into interpreter fonts. Shared
  * with the path and picture walks, which need them for one thing only: a Type 3