reamkit 1.24.0 → 1.25.1

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

@@ -1,6 +1,39 @@
 import { PDF_NULL, PdfHexString, PdfName } from "../pdf/objects.js";
 import { Lexer } from "./lexer.js";
 //#region src/pdf-reader/content.ts
+/**
+* A painted path emitted by the path-painting operators (§8.5.3), captured in
+* page space (y-up). The optional fields record only what the paint mode set:
+* a fill colour/gradient (EP10/EP16c) and/or a stroke colour + width (EP11),
+* plus the enclosing structure id.
+*/
+/** A path's page-space bounding box, or `undefined` when it names no point. */
+function pathBox(segs) {
+	let minX = Infinity;
+	let minY = Infinity;
+	let maxX = -Infinity;
+	let maxY = -Infinity;
+	const add = (x, y) => {
+		minX = Math.min(minX, x);
+		minY = Math.min(minY, y);
+		maxX = Math.max(maxX, x);
+		maxY = Math.max(maxY, y);
+	};
+	for (const seg of segs) if (seg.op === "move" || seg.op === "line") add(seg.x, seg.y);
+	else if (seg.op === "cubic") {
+		add(seg.x1, seg.y1);
+		add(seg.x2, seg.y2);
+		add(seg.x, seg.y);
+	}
+	return Number.isFinite(minX) ? {
+		minX,
+		minY,
+		maxX,
+		maxY
+	} : void 0;
+}
+/** The area of a box, for choosing the smaller of two clip regions. */
+var area = (b) => Math.max(0, b.maxX - b.minX) * Math.max(0, b.maxY - b.minY);
 /** The identity {@link Matrix} (no transform). */
 var IDENTITY = [
 	1,
@@ -36,12 +69,15 @@ var FALLBACK_FONT = {
 	decode: (codes) => codes.map((c) => String.fromCharCode(c)).join(""),
 	width: () => 500
 };
+/** Below this a baseline is upright: a rounded matrix is not a turned one. */
+var UPRIGHT_TOLERANCE_DEG = .5;
 function initialState() {
 	return {
 		ctm: IDENTITY,
 		fontKey: "",
 		font: FALLBACK_FONT,
 		fontSize: 0,
+		renderMode: 0,
 		charSpacing: 0,
 		wordSpacing: 0,
 		hScale: 1,
@@ -50,7 +86,10 @@ function initialState() {
 		fillColor: "000000",
 		strokeColor: "000000",
 		lineWidth: 1,
-		fillGradient: void 0
+		fillGradient: void 0,
+		fillPattern: void 0,
+		fillAlpha: 1,
+		clip: void 0
 	};
 }
 /**
@@ -65,12 +104,14 @@ function initialState() {
 *                   an unmapped key falls back to Latin-1 with a half-em advance.
 * @param initialCtm The starting CTM mapping user space to page space.
 * @param shadings   Shading patterns by name, selected by `scn`/`sc` (EP16c).
+* @param alphas     Constant fill alphas by `/ExtGState` name, selected by `gs`.
 * @returns The extracted text runs, image placements and vector paths.
 */
-function interpretContent(bytes, fonts, initialCtm = IDENTITY, shadings = /* @__PURE__ */ new Map()) {
+function interpretContent(bytes, fonts, initialCtm = IDENTITY, shadings = /* @__PURE__ */ new Map(), alphas = /* @__PURE__ */ new Map()) {
 	const runs = [];
 	const images = [];
 	const vectors = [];
+	const glyphs = [];
 	const lexer = new Lexer(bytes);
 	const stack = [];
 	let state = initialState();
@@ -78,6 +119,8 @@ function interpretContent(bytes, fonts, initialCtm = IDENTITY, shadings = /* @__
 	let tm = IDENTITY;
 	let tlm = IDENTITY;
 	let path = [];
+	let pendingClip = false;
+	let paintOrder = 0;
 	let operands = [];
 	const mcStack = [];
 	const toPage = (x, y) => [x * state.ctm[0] + y * state.ctm[2] + state.ctm[4], x * state.ctm[1] + y * state.ctm[3] + state.ctm[5]];
@@ -127,8 +170,12 @@ function interpretContent(bytes, fonts, initialCtm = IDENTITY, shadings = /* @__
 		if (path.length >= 2 && (fill || stroke)) {
 			const mcid = mcStack.length > 0 ? mcStack[mcStack.length - 1] : void 0;
 			vectors.push({
+				order: paintOrder++,
 				segs: path,
+				...state.clip ? { clip: state.clip } : {},
+				...fill && state.fillPattern !== void 0 ? { patternName: state.fillPattern } : {},
 				...fill ? { fillHex: state.fillColor } : {},
+				...fill && state.fillAlpha < 1 ? { alpha: state.fillAlpha } : {},
 				...fill && state.fillGradient ? { gradient: state.fillGradient } : {},
 				...stroke ? {
 					strokeHex: state.strokeColor,
@@ -137,6 +184,17 @@ function interpretContent(bytes, fonts, initialCtm = IDENTITY, shadings = /* @__
 				...mcid !== void 0 ? { mcid } : {}
 			});
 		}
+		if (pendingClip) {
+			pendingClip = false;
+			const box = pathBox(path);
+			if (box) {
+				const next = {
+					segs: path,
+					...box
+				};
+				state.clip = state.clip && area(state.clip) <= area(next) ? state.clip : next;
+			}
+		}
 		path = [];
 	};
 	const num = (i) => {
@@ -144,6 +202,26 @@ function interpretContent(bytes, fonts, initialCtm = IDENTITY, shadings = /* @__
 		return typeof v === "number" ? v : 0;
 	};
 	const advanceGlyph = (code) => {
+		const type3 = state.font.type3;
+		if (type3) {
+			const stream = type3.proc(code);
+			if (stream) {
+				const scale = [
+					state.fontSize * state.hScale,
+					0,
+					0,
+					state.fontSize,
+					0,
+					state.rise
+				];
+				glyphs.push({
+					stream,
+					resources: type3.resources,
+					ctm: multiply(type3.matrix, multiply(scale, multiply(tm, state.ctm))),
+					order: paintOrder++
+				});
+			}
+		}
 		const w0 = state.font.width(code) / 1e3;
 		const isSpace = state.font.bytesPerCode === 1 && code === 32;
 		tm = multiply(translation((w0 * state.fontSize + state.charSpacing + (isSpace ? state.wordSpacing : 0)) * state.hScale, 0), tm);
@@ -153,28 +231,41 @@ function interpretContent(bytes, fonts, initialCtm = IDENTITY, shadings = /* @__
 		for (const code of codes) advanceGlyph(code);
 		return state.font.decode(codes);
 	};
-	const emitAt = (origin, text) => {
+	const emitAt = (origin, shown, end) => {
+		const text = logicalOrder(shown);
 		if (text.length === 0) return;
 		const scaleY = Math.hypot(origin[2], origin[3]) || 1;
 		const mcid = mcStack.length > 0 ? mcStack[mcStack.length - 1] : void 0;
+		const angle = Math.atan2(origin[1], origin[0]) * 180 / Math.PI;
 		runs.push({
 			text,
 			x: origin[4],
 			y: origin[5],
+			endX: end[4],
+			endY: end[5],
+			...Math.abs(angle) > UPRIGHT_TOLERANCE_DEG ? { angleDeg: angle } : {},
 			fontSizePt: state.fontSize * scaleY,
 			fontKey: state.fontKey,
+			...state.font.name !== void 0 ? { fontName: state.font.name } : {},
+			...state.font.type3 ? { type3: true } : {},
+			...state.renderMode === 3 || state.renderMode === 7 ? { invisible: true } : {},
+			...state.fillPattern !== void 0 ? { fillPatternName: state.fillPattern } : {},
+			...strokesText(state.renderMode) ? {
+				outlineHex: state.strokeColor,
+				outlineWidthPt: ctmLineWidth()
+			} : {},
+			...state.font.bold ? { bold: true } : {},
+			...state.font.italic ? { italic: true } : {},
+			colorHex: state.fillColor,
 			...mcid !== void 0 ? { mcid } : {}
 		});
 	};
 	const showString = (operand) => {
-		emitAt(multiply(tm, state.ctm), consume(operand));
+		emitAt(multiply(tm, state.ctm), consume(operand), multiply(tm, state.ctm));
 	};
 	const showArray = (arr) => {
-		const origin = multiply(tm, state.ctm);
-		let text = "";
 		for (const el of arr) if (typeof el === "number") tm = multiply(translation(-el / 1e3 * state.fontSize * state.hScale, 0), tm);
-		else if (typeof el === "string" || el instanceof PdfHexString) text += consume(el);
-		emitAt(origin, text);
+		else if (typeof el === "string" || el instanceof PdfHexString) emitAt(multiply(tm, state.ctm), consume(el), multiply(tm, state.ctm));
 	};
 	const exec = (op) => {
 		switch (op) {
@@ -222,6 +313,9 @@ function interpretContent(bytes, fonts, initialCtm = IDENTITY, shadings = /* @__
 			case "Tc":
 				state.charSpacing = num(0);
 				break;
+			case "Tr":
+				state.renderMode = num(0);
+				break;
 			case "Tw":
 				state.wordSpacing = num(0);
 				break;
@@ -267,6 +361,7 @@ function interpretContent(bytes, fonts, initialCtm = IDENTITY, shadings = /* @__
 				if (nm instanceof PdfName) {
 					const mcid = mcStack.length > 0 ? mcStack[mcStack.length - 1] : void 0;
 					images.push({
+						order: paintOrder++,
 						name: nm.value,
 						ctm: state.ctm,
 						...mcid !== void 0 ? { mcid } : {}
@@ -277,19 +372,24 @@ function interpretContent(bytes, fonts, initialCtm = IDENTITY, shadings = /* @__
 			case "rg":
 				state.fillColor = rgbHex(num(0), num(1), num(2));
 				state.fillGradient = void 0;
+				state.fillPattern = void 0;
 				break;
 			case "g":
 				state.fillColor = grayHex(num(0));
 				state.fillGradient = void 0;
+				state.fillPattern = void 0;
 				break;
 			case "k":
 				state.fillColor = cmykHex(num(0), num(1), num(2), num(3));
 				state.fillGradient = void 0;
+				state.fillPattern = void 0;
 				break;
 			case "scn":
 			case "sc": {
 				const last = operands[operands.length - 1];
-				state.fillGradient = last instanceof PdfName ? shadings.get(last.value) : void 0;
+				const named = last instanceof PdfName ? last.value : void 0;
+				state.fillGradient = named !== void 0 ? shadings.get(named) : void 0;
+				state.fillPattern = named !== void 0 && !state.fillGradient ? named : void 0;
 				break;
 			}
 			case "RG":
@@ -343,8 +443,15 @@ function interpretContent(bytes, fonts, initialCtm = IDENTITY, shadings = /* @__
 			case "n":
 				paintPath(false, false);
 				break;
+			case "gs": {
+				const nm = operands[operands.length - 1];
+				if (nm instanceof PdfName) state.fillAlpha = alphas.get(nm.value) ?? 1;
+				break;
+			}
 			case "W":
-			case "W*": break;
+			case "W*":
+				pendingClip = true;
+				break;
 			default: break;
 		}
 	};
@@ -384,9 +491,59 @@ function interpretContent(bytes, fonts, initialCtm = IDENTITY, shadings = /* @__
 	return {
 		texts: runs,
 		images,
-		vectors
+		vectors,
+		glyphs
 	};
 }
+/** §9.3.6 — the rendering modes that put a line round the glyphs. */
+function strokesText(mode) {
+	return mode === 1 || mode === 2 || mode === 5 || mode === 6;
+}
+/**
+* §9.4 — a show operator paints its glyphs along the baseline, left to right,
+* whatever the script. For Arabic or Hebrew that means the string a PDF holds
+* is in VISUAL order: the first character of the word is the last one shown.
+*
+* Every reader turns this back into logical order before handing it on, because
+* everything downstream — a search, a markdown file, a layout engine that does
+* its own bidi — takes logical order and reverses it again for display.
+* ArabicCIDTrueType.pdf came out mirrored for exactly that reason: the reader
+* passed visual order through and the layout reversed it a second time.
+*
+* A run is reversed only when it is wholly right-to-left. Anything mixed — a
+* number inside an Arabic sentence runs left to right — needs the full bidi
+* algorithm, and guessing at it would be worse than leaving it alone.
+*/
+function logicalOrder(text) {
+	return isRightToLeft(text) ? [...text].reverse().join("") : text;
+}
+/**
+* Whether a string is wholly right-to-left: at least one letter of an RTL
+* script and nothing of any other, spaces and joiners aside.
+*
+* Anything mixed — a number inside an Arabic sentence runs left to right —
+* needs the full bidi algorithm, and guessing at it would be worse than
+* leaving it alone.
+*
+* @param text The string to judge.
+* @returns Whether it is one run of right-to-left script.
+*/
+function isRightToLeft(text) {
+	let rtl = false;
+	for (const ch of text) {
+		const cp = ch.codePointAt(0);
+		if (isRtl(cp)) {
+			rtl = true;
+			continue;
+		}
+		if (cp !== 32 && cp !== 10 && cp !== 8204 && cp !== 8205) return false;
+	}
+	return rtl;
+}
+/** The right-to-left blocks: Hebrew, Arabic, Syriac, Thaana, and the forms. */
+function isRtl(cp) {
+	return cp >= 1424 && cp <= 1535 || cp >= 1536 && cp <= 1791 || cp >= 1792 && cp <= 1871 || cp >= 1920 && cp <= 1983 || cp >= 2208 && cp <= 2303 || cp >= 64285 && cp <= 65023 || cp >= 65136 && cp <= 65279;
+}
 function clamp255(v) {
 	return Math.max(0, Math.min(255, Math.round(v * 255)));
 }
@@ -474,4 +631,4 @@ function skipInlineImage(lexer) {
 	lexer.pos = ei < 0 ? lexer.length : ei + 2;
 }
 //#endregion
-export { IDENTITY, interpretContent, multiply };
+export { IDENTITY, interpretContent, isRightToLeft, multiply };

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

@@ -0,0 +1,56 @@
+import { TextRun } from './content.js';
+import { PdfImage } from './images.js';
+import { PdfPage } from './document.js';
+import { PdfVector } from './vector.js';
+/** A page's shown geometry: how big it is, and how to place a mark on it. */
+export interface Display {
+    /** The shown page's width in points — the `/MediaBox`'s, swapped on a quarter turn. */
+    readonly width: number;
+    /** The shown page's height in points. */
+    readonly height: number;
+    /** How far every mark turns with the page, degrees counter-clockwise. */
+    readonly turnDeg: number;
+    /** Map a `/MediaBox`-space point into the shown page's own y-up frame. */
+    readonly place: (x: number, y: number) => {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * The {@link Display} a page's `/MediaBox` and `/Rotate` describe.
+ *
+ * `/Rotate` turns the page CLOCKWISE when shown, so the content turns with it —
+ * counter-clockwise by the same amount as seen from the content's own frame,
+ * which is what `turnDeg` states.
+ *
+ * @param page The page whose shown geometry is wanted.
+ * @returns Its size, its turn, and the map onto it.
+ */
+export declare function displayOf(page: PdfPage): Display;
+/**
+ * The same runs, placed on the shown page.
+ *
+ * @param runs The runs as the content stream drew them.
+ * @param d    The page's shown geometry.
+ * @returns The runs in the shown page's frame, each carrying the page's turn.
+ */
+export declare function placeRuns(runs: ReadonlyArray<TextRun>, d: Display): Array<TextRun>;
+/**
+ * The same pictures, placed on the shown page. A quarter turn swaps a picture's
+ * width and height and leaves it standing on its side, which the caller carries
+ * as the picture's own rotation.
+ *
+ * @param images The pictures as the content stream placed them.
+ * @param d      The page's shown geometry.
+ * @returns The pictures in the shown page's frame.
+ */
+export declare function placeImages(images: ReadonlyArray<PdfImage>, d: Display): Array<PdfImage>;
+/**
+ * The same paths, placed on the shown page. A path is geometry, so every point
+ * of it moves and the bounding box is taken again from what comes out.
+ *
+ * @param vectors The paths as the content stream painted them.
+ * @param d       The page's shown geometry.
+ * @returns The paths in the shown page's frame.
+ */
+export declare function placeVectors(vectors: ReadonlyArray<PdfVector>, d: Display): Array<PdfVector>;

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

@@ -0,0 +1,162 @@
+//#region src/pdf-reader/display.ts
+/**
+* The {@link Display} a page's `/MediaBox` and `/Rotate` describe.
+*
+* `/Rotate` turns the page CLOCKWISE when shown, so the content turns with it —
+* counter-clockwise by the same amount as seen from the content's own frame,
+* which is what `turnDeg` states.
+*
+* @param page The page whose shown geometry is wanted.
+* @returns Its size, its turn, and the map onto it.
+*/
+function displayOf(page) {
+	const [x0, y0, x1, y1] = page.mediaBox;
+	const left = Math.min(x0, x1);
+	const bottom = Math.min(y0, y1);
+	const w = Math.abs(x1 - x0);
+	const h = Math.abs(y1 - y0);
+	const quarter = page.rotate === 90 || page.rotate === 270;
+	const place = (x, y) => {
+		const mx = x - left;
+		const my = y - bottom;
+		switch (page.rotate) {
+			case 90: return {
+				x: my,
+				y: w - mx
+			};
+			case 180: return {
+				x: w - mx,
+				y: h - my
+			};
+			case 270: return {
+				x: h - my,
+				y: mx
+			};
+			default: return {
+				x: mx,
+				y: my
+			};
+		}
+	};
+	return {
+		width: quarter ? h : w,
+		height: quarter ? w : h,
+		turnDeg: page.rotate === 90 ? -90 : page.rotate === 180 ? 180 : page.rotate === 270 ? 90 : 0,
+		place
+	};
+}
+/**
+* The same runs, placed on the shown page.
+*
+* @param runs The runs as the content stream drew them.
+* @param d    The page's shown geometry.
+* @returns The runs in the shown page's frame, each carrying the page's turn.
+*/
+function placeRuns(runs, d) {
+	return runs.map((r) => {
+		const origin = d.place(r.x, r.y);
+		const end = d.place(r.endX, r.endY);
+		const angle = ((r.angleDeg ?? 0) + d.turnDeg) % 360 + 0;
+		const { angleDeg: _was, ...rest } = r;
+		return {
+			...rest,
+			x: origin.x,
+			y: origin.y,
+			endX: end.x,
+			endY: end.y,
+			...Math.abs(angle) > .5 ? { angleDeg: angle } : {}
+		};
+	});
+}
+/**
+* The same pictures, placed on the shown page. A quarter turn swaps a picture's
+* width and height and leaves it standing on its side, which the caller carries
+* as the picture's own rotation.
+*
+* @param images The pictures as the content stream placed them.
+* @param d      The page's shown geometry.
+* @returns The pictures in the shown page's frame.
+*/
+function placeImages(images, d) {
+	return images.map((img) => {
+		const corners = [
+			d.place(img.x, img.y),
+			d.place(img.x + img.widthPt, img.y),
+			d.place(img.x + img.widthPt, img.y + img.heightPt),
+			d.place(img.x, img.y + img.heightPt)
+		];
+		const xs = corners.map((c) => c.x);
+		const ys = corners.map((c) => c.y);
+		const minX = Math.min(...xs);
+		const minY = Math.min(...ys);
+		return {
+			...img,
+			x: minX,
+			y: minY,
+			widthPt: Math.max(...xs) - minX,
+			heightPt: Math.max(...ys) - minY
+		};
+	});
+}
+/**
+* The same paths, placed on the shown page. A path is geometry, so every point
+* of it moves and the bounding box is taken again from what comes out.
+*
+* @param vectors The paths as the content stream painted them.
+* @param d       The page's shown geometry.
+* @returns The paths in the shown page's frame.
+*/
+function placeVectors(vectors, d) {
+	return vectors.map((v) => {
+		const segs = v.segs.map((s) => {
+			switch (s.op) {
+				case "move":
+				case "line": {
+					const p = d.place(s.x, s.y);
+					return {
+						op: s.op,
+						x: p.x,
+						y: p.y
+					};
+				}
+				case "cubic": {
+					const c1 = d.place(s.x1, s.y1);
+					const c2 = d.place(s.x2, s.y2);
+					const p = d.place(s.x, s.y);
+					return {
+						op: "cubic",
+						x1: c1.x,
+						y1: c1.y,
+						x2: c2.x,
+						y2: c2.y,
+						x: p.x,
+						y: p.y
+					};
+				}
+				case "close": return s;
+			}
+		});
+		const xs = [];
+		const ys = [];
+		for (const s of segs) {
+			if (s.op === "close") continue;
+			xs.push(s.x);
+			ys.push(s.y);
+			if (s.op === "cubic") xs.push(s.x1, s.x2), ys.push(s.y1, s.y2);
+		}
+		if (xs.length === 0) return {
+			...v,
+			segs
+		};
+		return {
+			...v,
+			segs,
+			minX: Math.min(...xs),
+			minY: Math.min(...ys),
+			maxX: Math.max(...xs),
+			maxY: Math.max(...ys)
+		};
+	});
+}
+//#endregion
+export { displayOf, placeImages, placeRuns, placeVectors };

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

@@ -5,6 +5,11 @@ export type Rectangle = readonly [number, number, number, number];
 export interface PdfPage {
     readonly dict: PdfDict;
     readonly mediaBox: Rectangle;
+    /**
+     * §14.11.1 `/Rotate` — how far the page turns CLOCKWISE when it is shown,
+     * normalised to 0, 90, 180 or 270 and inherited down the page tree.
+     */
+    readonly rotate: 0 | 90 | 180 | 270;
     readonly resources: PdfDict | undefined;
 }
 /**
@@ -19,6 +24,8 @@ export declare class PdfFile {
     private readonly buf;
     private readonly xref;
     readonly trailer: PdfDict;
+    /** Caller-supplied decoders, by `/Filter` name (see {@link StreamFilters}). */
+    readonly filters: StreamFilters;
     private readonly cache;
     private readonly objStmCache;
     private decryptor;
@@ -31,9 +38,10 @@ export declare class PdfFile {
      * @param bytes    The complete PDF file bytes.
      * @param password The user password for an encrypted source (EP14); the empty
      *                 string opens permissions-only encryption.
+     * @param filters  Decoders for `/Filter` names this reader does not implement.
      * @returns A ready-to-query {@link PdfFile}.
      */
-    static parse(bytes: Uint8Array, password?: string): PdfFile;
+    static parse(bytes: Uint8Array, password?: string, filters?: StreamFilters): PdfFile;
     /**
      * Build the decryptor from `/Encrypt` (§7.6). Runs before any other object is
      * resolved, so the `/Encrypt` dictionary itself is read in the clear; its object
@@ -78,6 +86,33 @@ export declare class PdfFile {
      * `/Predictor` supported; unknown filters pass through undecoded).
      */
     streamData(stream: PdfStream): Uint8Array;
+    /** Filter names met in this file that nothing here can undo. */
+    readonly unknownFilters: Set<string>;
 }
+/**
+ * A decoder for one `/Filter` name, supplied by the caller.
+ *
+ * §7.4 leaves the filter set open, and a reader is not obliged to implement
+ * every one — but it cannot pretend, either: an undecoded stream is not the
+ * stream. Brotli-Prototype-FileA.pdf compresses all thirty of its streams with
+ * `/BrotliDecode` (PDF 2.0), including the cross-reference, so unread it is a
+ * document with no pages at all.
+ *
+ * Rather than carry a decoder for every filter anyone might write — Brotli
+ * alone is RFC 7932's context-modelled Huffman scheme and a 122 KB static
+ * dictionary, in every bundle, for a filter almost nothing produces — the
+ * reader takes one from whoever needs it:
+ *
+ * ```ts
+ * import { brotliDecompressSync } from 'node:zlib';
+ * Ream.parse(pdf, { filters: { BrotliDecode: (b) => brotliDecompressSync(b) } });
+ * ```
+ *
+ * A decoder that throws is treated as one that was never supplied: the filter
+ * is reported unreadable rather than its failure escaping into the parse.
+ */
+export type StreamFilter = (bytes: Uint8Array) => Uint8Array;
+/** Caller-supplied {@link StreamFilter}s, keyed by `/Filter` name (no slash). */
+export type StreamFilters = Readonly<Record<string, StreamFilter | undefined>>;
 /** Re-export for callers that walk a resolved dict's array values. */
 export type { PdfArray };