reamkit 1.29.0 → 1.31.0

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

@@ -71,6 +71,16 @@ export declare class Lexer {
      * `endstream` when a stream's `/Length` is missing or an unresolved reference.
      */
     indexOfAscii(needle: string, from: number): number;
+    /**
+     * Where `word` next stands as a keyword of its own — whitespace (or the
+     * start) before it, whitespace, a delimiter or the end after it — rather
+     * than as two bytes inside something else.
+     *
+     * @param word The keyword.
+     * @param from Where to start looking.
+     * @returns Its offset, or −1 where it does not stand anywhere after `from`.
+     */
+    indexOfKeyword(word: string, from: number): number;
     /**
      * §7.3.8.1 — read a stream's raw bytes. `pos` must sit right after the `stream`
      * keyword. The keyword is followed by CRLF (or a lone LF); the data then runs

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

@@ -252,6 +252,23 @@ var Lexer = class {
 		return -1;
 	}
 	/**
+	* Where `word` next stands as a keyword of its own — whitespace (or the
+	* start) before it, whitespace, a delimiter or the end after it — rather
+	* than as two bytes inside something else.
+	*
+	* @param word The keyword.
+	* @param from Where to start looking.
+	* @returns Its offset, or −1 where it does not stand anywhere after `from`.
+	*/
+	indexOfKeyword(word, from) {
+		for (let at = this.indexOfAscii(word, from); at >= 0; at = this.indexOfAscii(word, at + 1)) {
+			const before = this.byteAt(at - 1);
+			const after = this.byteAt(at + word.length);
+			if ((at === from || before < 0 || isWhitespace(before)) && (after < 0 || isWhitespace(after) || isDelimiter(after))) return at;
+		}
+		return -1;
+	}
+	/**
 	* §7.3.8.1 — read a stream's raw bytes. `pos` must sit right after the `stream`
 	* keyword. The keyword is followed by CRLF (or a lone LF); the data then runs
 	* for `length` bytes, or — when the length is unknown — up to `endstream`.

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/pattern-tint.d.ts

@@ -12,6 +12,16 @@ export interface PatternTint {
  * @param file      The owning file.
  * @param resources The resources the pattern is named in.
  * @param name      The pattern's resource name.
+ * @param paint     §8.7.3.3 — the colour an UNCOLOURED pattern (`/PaintType
+ *                  2`) is painted in, which the page gives with `scn` and its
+ *                  own content may not state.
  * @returns Its colour and coverage, or `undefined` when neither can be told.
  */
-export declare function patternTint(file: PdfFile, resources: PdfDict | undefined, name: string): PatternTint | undefined;
+export declare function patternTint(file: PdfFile, resources: PdfDict | undefined, name: string, paint?: string): PatternTint | undefined;
+/**
+ * A colour laid over white paper at `coverage` strength, as a 6-hex string.
+ *
+ * @param colorHex The colour at full strength.
+ * @param coverage How much of the paper it covers, `0..1`.
+ */
+export declare function tintedHex(colorHex: string, coverage: number): string;

package/dist/esm/pdf-reader/pattern-tint.js

@@ -12,9 +12,12 @@ var MAX_DEPTH = 4;
 * @param file      The owning file.
 * @param resources The resources the pattern is named in.
 * @param name      The pattern's resource name.
+* @param paint     §8.7.3.3 — the colour an UNCOLOURED pattern (`/PaintType
+*                  2`) is painted in, which the page gives with `scn` and its
+*                  own content may not state.
 * @returns Its colour and coverage, or `undefined` when neither can be told.
 */
-function patternTint(file, resources, name) {
+function patternTint(file, resources, name, paint) {
 	if (!resources) return void 0;
 	const patterns = file.get(resources, "Pattern");
 	if (!(patterns instanceof Map)) return void 0;
@@ -25,13 +28,28 @@ function patternTint(file, resources, name) {
 	const marks = [];
 	const colours = [];
 	collect(file, stream, resources, marks, colours, 0, /* @__PURE__ */ new Set());
-	const colorHex = colours[0];
+	const colorHex = file.get(stream.dict, "PaintType") === 2 ? paint : colours[0] ?? paint;
 	if (colorHex === void 0) return void 0;
 	return {
 		colorHex,
 		coverage: sample(marks, cell)
 	};
 }
+/**
+* A colour laid over white paper at `coverage` strength, as a 6-hex string.
+*
+* @param colorHex The colour at full strength.
+* @param coverage How much of the paper it covers, `0..1`.
+*/
+function tintedHex(colorHex, coverage) {
+	const k = Math.min(1, Math.max(0, coverage));
+	if (k >= 1) return colorHex;
+	const channel = (at) => {
+		const c = Number.parseInt(colorHex.slice(at, at + 2), 16);
+		return Math.round(255 - (255 - (Number.isFinite(c) ? c : 0)) * k).toString(16).toUpperCase().padStart(2, "0");
+	};
+	return `${channel(0)}${channel(2)}${channel(4)}`;
+}
 /** The cell a tile repeats on: `/XStep` × `/YStep` from the `/BBox`'s corner. */
 function cellOf(file, dict) {
 	const bbox = numbers(file, dict.get("BBox"));
@@ -178,4 +196,4 @@ function asNumber(v) {
 	return typeof v === "number" ? v : NaN;
 }
 //#endregion
-export { patternTint };
+export { patternTint, tintedHex };

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

@@ -0,0 +1,25 @@
+import { TextRun } from './content.js';
+/** A band of blocks side by side, each a column of its own. */
+export interface SideBySide {
+    readonly kind: 'side';
+    readonly cells: ReadonlyArray<{
+        readonly runs: ReadonlyArray<TextRun>;
+        /** Where the cell's own ink starts and ends across the page. */
+        readonly from: number;
+        readonly to: number;
+    }>;
+}
+/** A stretch of the column read line by line, straight down. */
+export interface Flowing {
+    readonly kind: 'flow';
+    readonly runs: ReadonlyArray<TextRun>;
+}
+export type Region = Flowing | SideBySide;
+/**
+ * The column's runs cut into its regions, top of the page first.
+ *
+ * @param runs The column's runs.
+ * @returns The regions, in reading order; one `flow` region where the column
+ *          has no side-by-side band.
+ */
+export declare function regionsOf(runs: ReadonlyArray<TextRun>): Array<Region>;

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

@@ -0,0 +1,167 @@
+//#region src/pdf-reader/regions.ts
+/**
+* The column's runs cut into its regions, top of the page first.
+*
+* @param runs The column's runs.
+* @returns The regions, in reading order; one `flow` region where the column
+*          has no side-by-side band.
+*/
+function regionsOf(runs) {
+	const lines = clusterLines(runs);
+	const out = [];
+	let pending = [];
+	const flush = (flow) => {
+		if (flow.length > 0) out.push({
+			kind: "flow",
+			runs: flow.flatMap((l) => l.runs)
+		});
+	};
+	let floor = 0;
+	for (let i = 0; i < lines.length;) {
+		const band = bandFrom(lines, i, floor);
+		if (band === void 0) {
+			pending.push(lines[i]);
+			i++;
+			continue;
+		}
+		flush(pending.slice(0, pending.length - (i - band.start)));
+		out.push(band.region);
+		pending = [];
+		i = band.end;
+		floor = band.end;
+	}
+	flush(pending);
+	return out;
+}
+function clusterLines(runs) {
+	const sorted = [...runs].sort((a, b) => b.y - a.y || a.x - b.x);
+	const out = [];
+	for (const run of sorted) {
+		const last = out[out.length - 1];
+		if (last && Math.abs(last.y - run.y) <= Math.max(1, (run.fontSizePt || 10) * .5)) {
+			last.runs.push(run);
+			last.size = Math.max(last.size, run.fontSizePt || 0);
+		} else out.push({
+			y: run.y,
+			size: run.fontSizePt || 10,
+			runs: [run]
+		});
+	}
+	return out;
+}
+/** What a run marks: nothing for a blank or for a glyph that names no character. */
+var inked = (r) => r.text.replaceAll("�", "").trim() !== "";
+/** A line's pieces: its runs cut where a gap only a column leaves opens. */
+function piecesOf(line) {
+	const runs = line.runs.filter(inked).sort((a, b) => a.x - b.x);
+	const out = [];
+	for (const run of runs) {
+		const last = out[out.length - 1];
+		const size = run.fontSizePt || 10;
+		if (last && run.x - last.to < Math.max(size, last.size) * PIECE_GAP_EM) {
+			last.to = Math.max(last.to, run.endX);
+			last.ys.push(run.y);
+			last.size = Math.max(last.size, size);
+		} else out.push({
+			from: run.x,
+			to: run.endX,
+			ys: [run.y],
+			size
+		});
+	}
+	return out.map((p) => ({
+		from: p.from,
+		to: p.to,
+		y: middle(p.ys),
+		size: p.size
+	}));
+}
+/**
+* Whether a line's pieces stand on different baselines — the mark of two
+* blocks set side by side with leading of their own, which the clustering has
+* run together.
+*/
+function misaligned(line) {
+	const pieces = piecesOf(line);
+	if (pieces.length < 2) return false;
+	const ys = pieces.map((p) => p.y);
+	const size = Math.min(...pieces.map((p) => p.size));
+	return Math.max(...ys) - Math.min(...ys) > Math.max(ALIGN_SLACK_PT, size * ALIGN_SLACK_EM);
+}
+/**
+* The side-by-side band starting at line `i`, where one does: lines around a
+* misaligned one that keep clear of the same gutters, cut into the blocks
+* between them.
+*/
+function bandFrom(lines, i, floor) {
+	if (!misaligned(lines[i])) return void 0;
+	let from = i;
+	let to = i + 1;
+	const count = (a, b) => guttersOf(lines.slice(a, b)).length;
+	if (count(from, to) === 0) return void 0;
+	const near = (a, b) => Math.abs(a.y - b.y) <= Math.max(a.size, b.size) * BAND_REACH_EM;
+	while (to < lines.length && near(lines[to - 1], lines[to]) && count(from, to + 1) >= count(from, to)) to++;
+	while (from > floor && near(lines[from], lines[from - 1]) && count(from - 1, to) >= count(from, to)) from--;
+	const band = lines.slice(from, to);
+	const gutters = guttersOf(band);
+	if (gutters.length === 0) return void 0;
+	const edges = [
+		-Infinity,
+		...gutters.map((g) => (g.from + g.to) / 2),
+		Infinity
+	];
+	const cells = edges.slice(0, -1).map((left, k) => {
+		const right = edges[k + 1];
+		const runs = band.flatMap((l) => l.runs.filter((r) => {
+			const mid = (r.x + r.endX) / 2;
+			return mid >= left && mid < right;
+		}));
+		const ink = runs.filter(inked);
+		return {
+			runs,
+			from: Math.min(...ink.map((r) => r.x)),
+			to: Math.max(...ink.map((r) => r.endX))
+		};
+	});
+	if (cells.filter((c) => c.runs.some(inked)).length < 2) return void 0;
+	return {
+		region: {
+			kind: "side",
+			cells: cells.filter((c) => c.runs.some(inked))
+		},
+		start: from,
+		end: to
+	};
+}
+/** The strips across a band that no line's ink crosses, and that are wide enough to be gutters. */
+function guttersOf(band) {
+	const spans = band.flatMap((l) => piecesOf(l)).map((p) => [p.from, p.to]).sort((a, b) => a[0] - b[0]);
+	const size = middle(band.map((l) => l.size));
+	const out = [];
+	let reach = spans[0]?.[1] ?? 0;
+	for (const [from, to] of spans.slice(1)) {
+		if (from - reach >= size * PIECE_GAP_EM) out.push({
+			from: reach,
+			to: from
+		});
+		reach = Math.max(reach, to);
+	}
+	return out;
+}
+function middle(values) {
+	const sorted = [...values].sort((a, b) => a - b);
+	return sorted[Math.floor(sorted.length / 2)] ?? 0;
+}
+/** A gap this wide, in ems, is one a column leaves, not a word space or a tab within a line. */
+var PIECE_GAP_EM = 1.5;
+/**
+* How far apart two pieces' baselines may stand and still be one line: past a
+* point and a half — or a sixth of the size — the two were set with leading of
+* their own, not on one line with a rounding in it.
+*/
+var ALIGN_SLACK_PT = 1.5;
+var ALIGN_SLACK_EM = 1 / 6;
+/** How far, in ems, a line may stand from the band and still belong to it. */
+var BAND_REACH_EM = 2.5;
+//#endregion
+export { regionsOf };

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

@@ -4,6 +4,7 @@ import { PdfFunction } from './function.js';
 import { ShapeGradient } from '../core/vector.js';
 import { PdfDict } from '../pdf/objects.js';
 import { PdfFile } from './document.js';
+import { Matrix } from './content.js';
 /**
  * Resolve a page's `/Pattern` resources into gradient fills (E-PDF EP16c, ISO
  * 32000-1 §8.7.4.5). Every `PatternType` 2 (shading) pattern is evaluated — its
@@ -17,7 +18,45 @@ import { PdfFile } from './document.js';
  *                  annotation appearance's own.
  * @returns A map from pattern resource name to its {@link ShapeGradient}.
  */
-export declare function buildShadingMap(file: PdfFile, resources: PdfDict | undefined): Map<string, ShapeGradient>;
+export declare function buildShadingMap(file: PdfFile, resources: PdfDict | undefined): Map<string, PageGradient>;
+/**
+ * §8.7.4.5.3 — where an axial shading's axis runs on the page, y up: its
+ * first stop at (x0, y0) and its last at (x1, y1).
+ */
+export interface GradientAxis {
+    readonly x0: number;
+    readonly y0: number;
+    readonly x1: number;
+    readonly y1: number;
+}
+/**
+ * A gradient as the page states it: the model's, and where its axis runs. A
+ * shape shows the part of the axis its box covers, and the model's gradient
+ * spans the box — see {@link gradientOverBox}.
+ */
+export type PageGradient = ShapeGradient & {
+    readonly axis?: GradientAxis;
+};
+/**
+ * A page's gradient as a shape filled with it shows it: its stops re-mapped
+ * from the whole axis to the part of it the shape's box covers.
+ *
+ * A DrawingML gradient spans the shape it fills, and a PDF shading spans its
+ * own axis, which may reach far past the shape: issue10572.pdf's pattern
+ * runs twenty-four stripes down 1800 points, of which its 450-point square
+ * shows six — spread over the square, all twenty-four came back as hairlines.
+ * Beyond either end of the axis the end colour carries on, as `/Extend` asks.
+ *
+ * @param g   The gradient, with its axis where the page states one.
+ * @param box The shape's box, in the same space as the axis.
+ * @returns The gradient as the shape shows it, with no axis.
+ */
+export declare function gradientOverBox(g: PageGradient, box: {
+    readonly minX: number;
+    readonly minY: number;
+    readonly maxX: number;
+    readonly maxY: number;
+}): ShapeGradient;
 /**
  * §8.7.4.5.2 — an axial or radial shading as a gradient, for a bare `sh`.
  *
@@ -29,7 +68,7 @@ export declare function buildShadingMap(file: PdfFile, resources: PdfDict | unde
  * @param sh   The shading dictionary.
  * @returns The gradient, or `undefined` for a type this does not read.
  */
-export declare function gradientShading(file: PdfFile, sh: PdfDict): ShapeGradient | undefined;
+export declare function gradientShading(file: PdfFile, sh: PdfDict, ctm?: Matrix): PageGradient | undefined;
 /**
  * §8.7.4.5 — which kind of shading this is, as the file states it.
  *
@@ -128,7 +167,24 @@ export interface GsPaint {
      * `false` where the state names `/None`, which takes a mask off.
      */
     readonly masked?: boolean;
+    /** §8.4.5 `/LW` — the line width, in user space. */
+    readonly lineWidth?: number;
+    /** §8.4.5 `/D` — the dash pattern's lengths, in user space; empty is solid. */
+    readonly dash?: ReadonlyArray<number>;
+    /** §8.4.5 `/LC` — the line cap: 0 butt, 1 round, 2 projecting square. */
+    readonly lineCap?: number;
+    /** §11.6.4.4 `/CA` — the constant STROKE alpha, where the state names one. */
+    readonly strokeAlpha?: number;
 }
+/**
+ * §8.4.3.6 — a dash array as a stroke can use it: lengths that are numbers and
+ * not negative, and none at all where every one is zero, which draws nothing
+ * and is solid by the spec's own reading.
+ *
+ * @param value The array, as the file states it.
+ * @returns The lengths, or an empty array for a solid line.
+ */
+export declare function dashLengths(value: unknown): ReadonlyArray<number>;
 /**
  * §8.6 — how many components a colour space takes, and what they mean.
  *