reamkit 1.24.0 → 1.25.1

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

@@ -1,5 +1,10 @@
+import { pt } from "../core/ir/units.js";
 import { ResourceStore } from "../core/ir/resources.js";
-import { buildFlowDoc, dedupeLosses, imageBlock, paragraphFromRuns, sectionFromPdfPages, shapeBlock } from "./flow-build.js";
+import { FEATURES } from "../core/ir/features.js";
+import { displayOf, placeImages, placeRuns, placeVectors } from "./display.js";
+import { buildFlowDoc, dedupeLosses, imageBlock, paragraphFromRuns, positionedText, sectionFromPdfPages, shapeBlock } from "./flow-build.js";
+import { collectEmbeddedFonts } from "./embedded-fonts.js";
+import { isRightToLeft } from "./content.js";
 import { collectPageImages } from "./images.js";
 import { extractPageText } from "./text.js";
 import { collectPageVectors } from "./vector.js";
@@ -19,19 +24,40 @@ import { collectPageVectors } from "./vector.js";
 * @param file The PDF to reconstruct.
 * @returns The reconstructed {@link FlowDoc} plus any read-time losses.
 */
-function reconstructByLayout(file) {
+function reconstructByLayout(file, mode = "flow") {
 	const pages = file.pages();
-	const pageRuns = pages.map((page) => extractPageText(file, page));
+	const shown = pages.map((page) => displayOf(page));
+	const pageRuns = pages.map((page, i) => placeRuns(extractPageText(file, page), shown[i]));
 	const medianFont = median(pageRuns.flat().map((r) => r.fontSizePt).filter((s) => s > 0)) || 12;
 	const resources = new ResourceStore();
 	const losses = [];
+	if (pageRuns.some((page) => page.some((r) => r.fillPatternName !== void 0))) losses.push({
+		severity: "degraded",
+		feature: FEATURES.text,
+		detail: "text filled with a tiling pattern is drawn as a flat tint of the pattern’s colour, not as the pattern"
+	});
 	const body = [];
 	pages.forEach((page, i) => {
 		const runs = pageRuns[i];
-		const [px0, , px1] = page.mediaBox;
-		const gutter = detectGutter(runs, Math.abs(px1 - px0));
+		const display = shown[i];
+		const pageWidth = display.width;
+		const gutter = detectGutter(runs, pageWidth);
 		const blocks = [];
-		const addColumn = (colRuns, col) => {
+		const addColumn = (allRuns, col) => {
+			const colRuns = mode === "positional" ? allRuns.filter((r) => r.type3 !== true && r.invisible !== true) : allRuns;
+			if (mode === "positional") {
+				for (const [angle, runs] of byAngle(colRuns)) for (const line of groupIntoLines(rotate(runs, -angle), true)) {
+					if (line.text.length === 0) continue;
+					const box = turnedBox(line, angle, pageWidth);
+					placed.push({
+						key: [Number.MAX_SAFE_INTEGER, placed.length],
+						col,
+						top: box.y + box.height,
+						make: (z) => positionedText(line.spans, box, frame, z, rotation60kOf(angle))
+					});
+				}
+				return;
+			}
 			const lines = groupIntoLines(colRuns).filter((l) => l.text.length > 0);
 			for (const para of groupIntoParagraphs(lines)) blocks.push({
 				col,
@@ -39,36 +65,74 @@ function reconstructByLayout(file) {
 				el: paragraphFromRuns(para.spans, headingLevel(para.fontSize, medianFont))
 			});
 		};
+		const placed = [];
 		if (gutter !== void 0) {
 			addColumn(runs.filter((r) => r.x < gutter), 0);
 			addColumn(runs.filter((r) => r.x >= gutter), 1);
 		} else addColumn(runs, 0);
 		const colOf = (centerX) => gutter !== void 0 && centerX >= gutter ? 1 : 0;
-		const imgs = collectPageImages(file, page);
+		const frame = {
+			left: 0,
+			top: display.height
+		};
+		const raw = collectPageImages(file, page);
+		const imgs = {
+			images: placeImages(raw.images, display),
+			losses: raw.losses
+		};
 		losses.push(...imgs.losses);
-		for (const img of imgs.images) blocks.push({
-			col: colOf(img.x + img.widthPt / 2),
-			top: img.y + img.heightPt,
-			el: imageBlock(img, resources)
-		});
-		for (const v of collectPageVectors(file, page)) blocks.push({
-			col: colOf((v.minX + v.maxX) / 2),
-			top: v.maxY,
-			el: shapeBlock(v)
+		const lifted = collectPageVectors(file, page, imgs.images.map((img) => ({
+			minX: img.x,
+			minY: img.y,
+			maxX: img.x + img.widthPt,
+			maxY: img.y + img.heightPt
+		})));
+		losses.push(...lifted.losses);
+		const vectors = placeVectors(lifted.vectors, display);
+		[
+			...imgs.images.map((img) => ({
+				key: img.orderKey,
+				col: colOf(img.x + img.widthPt / 2),
+				top: img.y + img.heightPt,
+				make: (z) => imageBlock(img, resources, void 0, frame, z)
+			})),
+			...vectors.map((v) => ({
+				key: v.orderKey,
+				col: colOf((v.minX + v.maxX) / 2),
+				top: v.maxY,
+				make: (z) => shapeBlock(v, frame, z)
+			})),
+			...placed
+		].sort((a, b) => compareOrder(a.key, b.key)).forEach((mark, z) => {
+			blocks.push({
+				col: mark.col,
+				top: mark.top,
+				el: mark.make(z)
+			});
 		});
 		blocks.sort((a, b) => a.col - b.col || b.top - a.top);
+		if (i > 0 && blocks.length > 0) body.push({
+			kind: "paragraph",
+			paragraph: {
+				properties: {
+					pageBreakBefore: true,
+					spacingLine: pt(0),
+					spacingLineRule: "exact"
+				},
+				runs: []
+			}
+		});
 		for (const block of blocks) body.push(block.el);
 	});
 	return {
-		doc: buildFlowDoc(body, resources, sectionFromPdfPages(pages)),
+		doc: buildFlowDoc(body, resources, sectionFromPdfPages(pages), collectEmbeddedFonts(file, pages)),
 		losses: dedupeLosses(losses)
 	};
 }
 function detectGutter(runs, pageWidth) {
 	if (runs.length < 30 || pageWidth <= 0) return void 0;
 	const fontSize = median(runs.map((r) => r.fontSizePt).filter((s) => s > 0)) || 10;
-	const right = (r) => r.x + Math.max(1, r.text.length) * (r.fontSizePt || fontSize) * .5;
-	const intervals = runs.map((r) => [r.x, right(r)]).sort((a, b) => a[0] - b[0]);
+	const intervals = runs.map((r) => [r.x, Math.max(r.endX, r.x + 1)]).sort((a, b) => a[0] - b[0]);
 	const minX = intervals[0][0];
 	const span = Math.max(...intervals.map((iv) => iv[1])) - minX;
 	if (span < pageWidth * .5) return void 0;
@@ -88,7 +152,96 @@ function detectGutter(runs, pageWidth) {
 	if (left < runs.length * .25 || left > runs.length * .75) return void 0;
 	return gapMid;
 }
-function groupIntoLines(runs) {
+/**
+* The gap, in ems, past which the placed reader cuts a line rather than write a
+* space across it.
+*
+* It began at four ems, from a measurement on 160F-2019.pdf: the gaps between
+* words there run 0.00–3.13 em and the gaps between COLUMNS 4.41–43.66 em, with
+* nothing in between. That told a column from a word, which was the question at
+* the time. It is not the question here.
+*
+* A placed piece is set down at the x it was measured at, so cutting costs
+* nothing — and a space costs whatever the page's gap was not. A quarter of an
+* em of type standing in for one em of pen leaves everything after it three
+* quarters of an em short, and the error runs on down the line. So the reader
+* cuts wherever {@link lineSpans} would otherwise write a space, and a placed
+* page never stands a space in for a gap it measured. Only the placed reader
+* does this — a flowing paragraph is meant to be read across.
+*/
+var SPACE_GAP_EM = .25;
+/** Runs by the direction of their baseline, upright first, each angle rounded. */
+function byAngle(runs) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const run of runs) {
+		const angle = Math.round(run.angleDeg ?? 0);
+		const group = groups.get(angle);
+		if (group) group.push(run);
+		else groups.set(angle, [run]);
+	}
+	return [...groups].sort((a, b) => Math.abs(a[0]) - Math.abs(b[0]));
+}
+/** The same runs seen from a frame turned by `deg`, where their baseline is flat. */
+function rotate(runs, deg) {
+	if (deg === 0) return [...runs];
+	const rad = deg * Math.PI / 180;
+	const cos = Math.cos(rad);
+	const sin = Math.sin(rad);
+	return runs.map((r) => ({
+		...r,
+		x: r.x * cos - r.y * sin,
+		y: r.x * sin + r.y * cos,
+		endX: r.endX * cos - r.endY * sin,
+		endY: r.endX * sin + r.endY * cos
+	}));
+}
+/**
+* A turned line's page-space box: the rectangle the renderer is to place and
+* then spin about its own centre, which is how a shape's rotation works
+* (§20.1.7.6 `a:xfrm rot`).
+*
+* The box is measured in the line's own frame and only its CENTRE is carried
+* back into page space — an axis-aligned box of the same size, centred there
+* and turned, puts the words back along the baseline they were set on.
+*/
+function turnedBox(line, angleDeg, pageWidth) {
+	const height = line.fontSize * 1.25;
+	const bottom = line.y - line.fontSize * .25;
+	const slack = line.width * 1.2 + line.fontSize;
+	const width = isRightToLeft(line.text) ? line.width : angleDeg === 0 ? Math.max(line.width, pageWidth - line.x) : slack;
+	if (angleDeg === 0) return {
+		x: line.x,
+		y: bottom,
+		width,
+		height
+	};
+	const rad = angleDeg * Math.PI / 180;
+	const cos = Math.cos(rad);
+	const sin = Math.sin(rad);
+	const cu = line.x + width / 2;
+	const cv = bottom + height / 2;
+	return {
+		x: cu * cos - cv * sin - width / 2,
+		y: cu * sin + cv * cos - height / 2,
+		width,
+		height
+	};
+}
+/** §20.1.7.6 — a shape turns CLOCKWISE in 1/60000°, and PDF measures the other way. */
+function rotation60kOf(angleDeg) {
+	if (angleDeg === 0) return void 0;
+	return Math.round((-angleDeg % 360 + 360) % 360 * 6e4);
+}
+/**
+* The step, in ems, past which a run does not share its neighbour's baseline
+* but stands above or below it — a superscript, or the next row of a form.
+*
+* Measured across the readable pdfjs corpus: 123 runs sit exactly on their
+* line's baseline, three within 0.02 em of it (rounding), one between 0.02 and
+* 0.05, and thirty at 0.05 em or more. A twentieth of an em sits in that gap.
+*/
+var BASELINE_STEP_EM = .05;
+function groupIntoLines(runs, split = false) {
 	const sorted = [...runs].sort((a, b) => b.y - a.y || a.x - b.x);
 	const clusters = [];
 	for (const run of sorted) {
@@ -103,28 +256,54 @@ function groupIntoLines(runs) {
 			runs: [run]
 		});
 	}
-	return clusters.map((c) => {
+	return clusters.flatMap((c) => {
 		const ordered = c.runs.sort((a, b) => a.x - b.x);
 		const fontSize = c.fontSize || 10;
-		const spans = lineSpans(ordered, fontSize);
-		return {
-			y: c.y,
-			fontSize,
-			text: spans.map((s) => s.text).join("").replace(/\s+/g, " ").trim(),
-			spans
-		};
+		if (!split) return [lineOf(ordered, c.y, fontSize)];
+		const pieces = [[]];
+		for (const run of ordered) {
+			const prev = pieces[pieces.length - 1];
+			const last = prev[prev.length - 1];
+			const size = run.fontSizePt || fontSize;
+			if (last !== void 0 && (Math.abs(run.x - last.endX) > size * SPACE_GAP_EM || Math.abs(run.y - prev[0].y) > size * BASELINE_STEP_EM || isRightToLeft(run.text) || isRightToLeft(last.text))) pieces.push([]);
+			pieces[pieces.length - 1].push(run);
+		}
+		return pieces.map((piece) => lineOf(piece, piece[0].y, Math.max(...piece.map((r) => r.fontSizePt || 0)) || fontSize));
 	});
 }
+/** One run of runs, left to right on a shared baseline, as a {@link Line}. */
+function lineOf(runs, y, fontSize) {
+	const ordered = lineSpans(runs, fontSize);
+	const spans = ordered.every((s) => s.text.trim() === "" || isRightToLeft(s.text)) ? [...ordered].reverse() : ordered;
+	const x = runs[0].x;
+	return {
+		x,
+		width: runs[runs.length - 1].endX - x,
+		y,
+		fontSize,
+		text: spans.map((s) => s.text).join("").replace(/\s+/g, " ").trim(),
+		spans
+	};
+}
 function lineSpans(runs, fontSize) {
 	const spans = [];
 	let prevEnd;
 	for (const run of runs) {
 		if (prevEnd !== void 0 && run.x - prevEnd > fontSize * .25) spans.push({ text: " " });
-		spans.push(run.href !== void 0 ? {
+		spans.push({
 			text: run.text,
-			href: run.href
-		} : { text: run.text });
-		prevEnd = run.x + run.text.length * (run.fontSizePt || fontSize) * .5;
+			sizePt: run.fontSizePt,
+			...run.colorHex !== "000000" ? { colorHex: run.colorHex } : {},
+			...run.fontName !== void 0 ? { fontName: run.fontName } : {},
+			...run.outlineHex !== void 0 ? { outline: {
+				colorHex: run.outlineHex,
+				widthPt: pt(run.outlineWidthPt ?? 1)
+			} } : {},
+			...run.bold ? { bold: true } : {},
+			...run.italic ? { italic: true } : {},
+			...run.href !== void 0 ? { href: run.href } : {}
+		});
+		prevEnd = run.endX;
 	}
 	return spans;
 }
@@ -152,5 +331,15 @@ function median(values) {
 	const sorted = [...values].sort((a, b) => a - b);
 	return sorted[Math.floor(sorted.length / 2)];
 }
+/**
+* Compare two painting-order keys (§8.5.3): position by position, and the
+* shorter one first where they agree — a form's call comes before the marks it
+* makes inside it.
+*/
+function compareOrder(a, b) {
+	const n = Math.min(a.length, b.length);
+	for (let i = 0; i < n; i++) if (a[i] !== b[i]) return a[i] - b[i];
+	return a.length - b.length;
+}
 //#endregion
 export { reconstructByLayout };

package/dist/esm/pdf-reader/pattern-tint.d.ts

@@ -0,0 +1,17 @@
+import { PdfDict } from '../pdf/objects.js';
+import { PdfFile } from './document.js';
+/** A tiling pattern read as a tint: the colour it paints, and how much of the cell. */
+export interface PatternTint {
+    readonly colorHex: string;
+    /** 0–1 — the share of the cell the pattern's marks cover. */
+    readonly coverage: number;
+}
+/**
+ * Read a named tiling pattern as a tint.
+ *
+ * @param file      The owning file.
+ * @param resources The resources the pattern is named in.
+ * @param name      The pattern's resource name.
+ * @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;

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

@@ -0,0 +1,181 @@
+import { PDF_NULL, PdfStream } from "../pdf/objects.js";
+import { interpretContent } from "./content.js";
+import { buildFonts } from "./text.js";
+//#region src/pdf-reader/pattern-tint.ts
+/** How many points across the cell are asked. 48² is 2304 samples per mark. */
+var GRID = 48;
+/** How deep the walk follows a tile that draws its marks through Type 3 glyphs. */
+var MAX_DEPTH = 4;
+/**
+* Read a named tiling pattern as a tint.
+*
+* @param file      The owning file.
+* @param resources The resources the pattern is named in.
+* @param name      The pattern's resource name.
+* @returns Its colour and coverage, or `undefined` when neither can be told.
+*/
+function patternTint(file, resources, name) {
+	if (!resources) return void 0;
+	const patterns = file.get(resources, "Pattern");
+	if (!(patterns instanceof Map)) return void 0;
+	const stream = file.resolve(patterns.get(name) ?? PDF_NULL);
+	if (!(stream instanceof PdfStream)) return void 0;
+	const cell = cellOf(file, stream.dict);
+	if (!cell) return void 0;
+	const marks = [];
+	const colours = [];
+	collect(file, stream, resources, marks, colours, 0, /* @__PURE__ */ new Set());
+	const colorHex = colours[0];
+	if (colorHex === void 0) return void 0;
+	return {
+		colorHex,
+		coverage: sample(marks, cell)
+	};
+}
+/** The cell a tile repeats on: `/XStep` × `/YStep` from the `/BBox`'s corner. */
+function cellOf(file, dict) {
+	const bbox = numbers(file, dict.get("BBox"));
+	if (!bbox || bbox.length < 4) return void 0;
+	const x = Math.min(bbox[0], bbox[2]);
+	const y = Math.min(bbox[1], bbox[3]);
+	const bw = Math.abs(bbox[2] - bbox[0]);
+	const bh = Math.abs(bbox[3] - bbox[1]);
+	const w = Math.abs(asNumber(file.resolve(dict.get("XStep") ?? PDF_NULL))) || bw;
+	const h = Math.abs(asNumber(file.resolve(dict.get("YStep") ?? PDF_NULL))) || bh;
+	return w > 0 && h > 0 ? {
+		x,
+		y,
+		w,
+		h
+	} : void 0;
+}
+/** Every mark the tile paints, in pattern space, following its Type 3 glyphs. */
+function collect(file, stream, fallback, marks, colours, depth, visiting) {
+	if (depth > MAX_DEPTH || visiting.has(stream)) return;
+	visiting.add(stream);
+	const own = file.get(stream.dict, "Resources");
+	const resources = own instanceof Map ? own : fallback;
+	const result = interpretContent(file.streamData(stream), buildFonts(file, resources));
+	for (const v of result.vectors) {
+		marks.push(v);
+		const hex = v.fillHex ?? v.strokeHex;
+		if (hex !== void 0 && hex !== "FFFFFF") colours.push(hex);
+	}
+	for (const run of result.texts) if (run.colorHex !== "FFFFFF") colours.push(run.colorHex);
+	for (const glyph of result.glyphs) {
+		const inner = interpretContent(file.streamData(glyph.stream), /* @__PURE__ */ new Map(), glyph.ctm);
+		for (const v of inner.vectors) {
+			marks.push(v);
+			const hex = v.fillHex ?? v.strokeHex;
+			if (hex !== void 0 && hex !== "FFFFFF") colours.push(hex);
+		}
+	}
+	visiting.delete(stream);
+}
+/** The share of the cell any mark covers, asked at a grid of points. */
+function sample(marks, cell) {
+	if (marks.length === 0) return 0;
+	const flat = marks.map((m) => ({
+		lines: flatten(m.segs),
+		filled: m.fillHex !== void 0 || m.gradient !== void 0,
+		half: m.strokeHex !== void 0 ? Math.max(m.lineWidth ?? 1, .1) / 2 : 0
+	}));
+	let hit = 0;
+	for (let iy = 0; iy < GRID; iy++) {
+		const py = cell.y + (iy + .5) / GRID * cell.h;
+		for (let ix = 0; ix < GRID; ix++) {
+			const px = cell.x + (ix + .5) / GRID * cell.w;
+			if (flat.some((m) => covers(m, px, py))) hit++;
+		}
+	}
+	return hit / (GRID * GRID);
+}
+/** Whether one mark paints the point — inside its outline, or under its pen. */
+function covers(mark, px, py) {
+	if (mark.half > 0) {
+		const limit = mark.half * mark.half;
+		for (const [x0, y0, x1, y1] of mark.lines) if (distanceSquared(px, py, x0, y0, x1, y1) <= limit) return true;
+	}
+	if (!mark.filled) return false;
+	let inside = false;
+	for (const [x0, y0, x1, y1] of mark.lines) if (y0 > py !== y1 > py && px < (x1 - x0) * (py - y0) / (y1 - y0) + x0) inside = !inside;
+	return inside;
+}
+/** The squared distance from a point to a segment. */
+function distanceSquared(px, py, x0, y0, x1, y1) {
+	const dx = x1 - x0;
+	const dy = y1 - y0;
+	const len = dx * dx + dy * dy;
+	const t = len > 0 ? Math.max(0, Math.min(1, ((px - x0) * dx + (py - y0) * dy) / len)) : 0;
+	const qx = x0 + t * dx - px;
+	const qy = y0 + t * dy - py;
+	return qx * qx + qy * qy;
+}
+/** A path as straight segments; a curve becomes the chords of its control net. */
+function flatten(segs) {
+	const out = [];
+	let sx = 0;
+	let sy = 0;
+	let cx = 0;
+	let cy = 0;
+	for (const seg of segs) switch (seg.op) {
+		case "move":
+			sx = cx = seg.x;
+			sy = cy = seg.y;
+			break;
+		case "line":
+			out.push([
+				cx,
+				cy,
+				seg.x,
+				seg.y
+			]);
+			cx = seg.x;
+			cy = seg.y;
+			break;
+		case "cubic": {
+			const steps = 8;
+			let lx = cx;
+			let ly = cy;
+			for (let i = 1; i <= steps; i++) {
+				const t = i / steps;
+				const u = 1 - t;
+				const x = u * u * u * cx + 3 * u * u * t * seg.x1 + 3 * u * t * t * seg.x2 + t * t * t * seg.x;
+				const y = u * u * u * cy + 3 * u * u * t * seg.y1 + 3 * u * t * t * seg.y2 + t * t * t * seg.y;
+				out.push([
+					lx,
+					ly,
+					x,
+					y
+				]);
+				lx = x;
+				ly = y;
+			}
+			cx = seg.x;
+			cy = seg.y;
+			break;
+		}
+		case "close":
+			out.push([
+				cx,
+				cy,
+				sx,
+				sy
+			]);
+			cx = sx;
+			cy = sy;
+			break;
+	}
+	return out;
+}
+function numbers(file, value) {
+	const v = file.resolve(value ?? PDF_NULL);
+	if (!Array.isArray(v)) return void 0;
+	const out = v.map((n) => asNumber(file.resolve(n)));
+	return out.some((n) => !Number.isFinite(n)) ? void 0 : out;
+}
+function asNumber(v) {
+	return typeof v === "number" ? v : NaN;
+}
+//#endregion
+export { patternTint };

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

@@ -1,3 +1,4 @@
+import { StreamFilters } from './document.js';
 import { DocumentReader, ReadResult } from '../core/ir/adapters.js';
 import { FlowDoc } from '../core/ir/flow.js';
 /**
@@ -10,9 +11,16 @@ import { FlowDoc } from '../core/ir/flow.js';
  * @param bytes    The complete PDF file bytes.
  * @param password The user password for an encrypted source; the empty string
  *                 opens permissions-only encryption.
+ * @param filters  Decoders for `/Filter` names this reader does not implement
+ *                 (§7.4); see {@link StreamFilters}.
+ * @param layout   `'flow'` reads a re-flowable document out of the page —
+ *                 paragraphs and tables in reading order, from the structure
+ *                 tree where there is one. `'positional'` keeps the page: every
+ *                 line stands where its glyphs do, beside the artwork, which is
+ *                 what a form or a drawing needs and what a paragraph cannot be.
  * @returns The reconstructed FlowDoc and its accumulated {@link Loss} report.
  */
-export declare function readPdf(bytes: Uint8Array, password?: string): ReadResult<FlowDoc>;
+export declare function readPdf(bytes: Uint8Array, password?: string, layout?: 'flow' | 'positional', filters?: StreamFilters): ReadResult<FlowDoc>;
 /**
  * The `pdfReader` adapter: a {@link DocumentReader} that sniffs the `%PDF-`
  * header and parses the bytes into a {@link FlowDoc} (E-PDF EP5).

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

@@ -18,19 +18,31 @@ function sniffPdf(bytes) {
 * @param bytes    The complete PDF file bytes.
 * @param password The user password for an encrypted source; the empty string
 *                 opens permissions-only encryption.
+* @param filters  Decoders for `/Filter` names this reader does not implement
+*                 (§7.4); see {@link StreamFilters}.
+* @param layout   `'flow'` reads a re-flowable document out of the page —
+*                 paragraphs and tables in reading order, from the structure
+*                 tree where there is one. `'positional'` keeps the page: every
+*                 line stands where its glyphs do, beside the artwork, which is
+*                 what a form or a drawing needs and what a paragraph cannot be.
 * @returns The reconstructed FlowDoc and its accumulated {@link Loss} report.
 */
-function readPdf(bytes, password = "") {
-	const file = PdfFile.parse(bytes, password);
+function readPdf(bytes, password = "", layout = "flow", filters = {}) {
+	const file = PdfFile.parse(bytes, password, filters);
 	const losses = [];
 	if (file.encryptionUnsupported) losses.push({
 		severity: "dropped",
 		feature: FEATURES.text,
 		detail: "encrypted PDF — the user password was missing or incorrect, or the handler is unsupported"
 	});
-	const tagged = reconstructTaggedPdf(file);
-	const reconstruction = tagged ?? reconstructByLayout(file);
-	if (!tagged) losses.push({
+	for (const name of file.unknownFilters) losses.push({
+		severity: "dropped",
+		feature: FEATURES.text,
+		detail: `PDF stream filter /${name} is not supported; streams using it are unreadable`
+	});
+	const tagged = layout === "positional" ? void 0 : reconstructTaggedPdf(file);
+	const reconstruction = tagged ?? reconstructByLayout(file, layout);
+	if (!tagged && layout !== "positional") losses.push({
 		severity: "degraded",
 		feature: FEATURES.text,
 		detail: "untagged PDF — text and headings reconstructed heuristically from glyph positions; structure is approximate"
@@ -39,7 +51,7 @@ function readPdf(bytes, password = "") {
 	losses.push({
 		severity: "dropped",
 		feature: FEATURES.images,
-		detail: "PDF clipping paths and bare-shading (sh) vector regions are not reconstructed"
+		detail: "PDF bare-shading (sh) vector regions are not reconstructed"
 	});
 	return {
 		doc: reconstruction.doc,
@@ -60,7 +72,11 @@ var pdfReader = {
 		FEATURES.images
 	]),
 	sniff: sniffPdf,
-	read: (bytes, opts) => readPdf(bytes, typeof opts?.password === "string" ? opts.password : "")
+	read: (bytes, opts) => readPdf(bytes, typeof opts?.password === "string" ? opts.password : "", opts?.pdfLayout === "positional" ? "positional" : "flow", isFilters(opts?.filters) ? opts.filters : {})
 };
+/** A caller's `filters` option, when it is the shape the reader can use. */
+function isFilters(value) {
+	return typeof value === "object" && value !== null;
+}
 //#endregion
 export { pdfReader };

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

@@ -11,3 +11,17 @@ import { PdfFile, PdfPage } from './document.js';
  * @returns A map from pattern resource name to its {@link ShapeGradient}.
  */
 export declare function buildShadingMap(file: PdfFile, page: PdfPage): Map<string, ShapeGradient>;
+/**
+ * §11.6.4.4 — the constant fill alpha (`/ca`) of every `/ExtGState` the page
+ * names, by name.
+ *
+ * `gs` sets a whole graphics state at once, and one of the things in it is how
+ * opaque the paint is. 22060_A1_01_Plans.pdf marks its evacuation routes with
+ * a green band at `ca` 0.6, meant to be read THROUGH: painted solid, the floor
+ * plan under each band disappears.
+ *
+ * @param file The owning file.
+ * @param page The page whose `/ExtGState` resources are wanted.
+ * @returns Name → fill alpha, for the states that state one below 1.
+ */
+export declare function buildAlphaMap(file: PdfFile, page: PdfPage): Map<string, number>;

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

@@ -153,5 +153,31 @@ function pushStop(stops, offset, colorHex) {
 		colorHex
 	});
 }
+/**
+* §11.6.4.4 — the constant fill alpha (`/ca`) of every `/ExtGState` the page
+* names, by name.
+*
+* `gs` sets a whole graphics state at once, and one of the things in it is how
+* opaque the paint is. 22060_A1_01_Plans.pdf marks its evacuation routes with
+* a green band at `ca` 0.6, meant to be read THROUGH: painted solid, the floor
+* plan under each band disappears.
+*
+* @param file The owning file.
+* @param page The page whose `/ExtGState` resources are wanted.
+* @returns Name → fill alpha, for the states that state one below 1.
+*/
+function buildAlphaMap(file, page) {
+	const out = /* @__PURE__ */ new Map();
+	if (!page.resources) return out;
+	const states = file.get(page.resources, "ExtGState");
+	if (!(states instanceof Map)) return out;
+	for (const [name, value] of states) {
+		const state = file.resolve(value);
+		if (!(state instanceof Map)) continue;
+		const ca = file.resolve(state.get("ca") ?? PDF_NULL);
+		if (typeof ca === "number" && ca >= 0 && ca < 1) out.set(name, ca);
+	}
+	return out;
+}
 //#endregion
-export { buildShadingMap };
+export { buildAlphaMap, buildShadingMap };