reamkit 1.25.1 → 1.27.0

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

@@ -1,5 +1,7 @@
 import { PdfFile } from './document.js';
 import { Reconstruction } from './flow-build.js';
+/** §9.10.2 — a glyph the face maps to no character (see `./font`). */
+export declare const UNMAPPED = "\uFFFD";
 /**
  * Heuristically reconstruct an untagged PDF into a {@link Reconstruction}
  * (E-PDF EP4). With no structure tree there is only positioned content, so
@@ -16,3 +18,33 @@ import { Reconstruction } from './flow-build.js';
  * @returns The reconstructed {@link FlowDoc} plus any read-time losses.
  */
 export declare function reconstructByLayout(file: PdfFile, mode?: 'flow' | 'positional'): Reconstruction;
+/**
+ * Whether a line ENDED a paragraph, rather than wrapping into the next.
+ *
+ * Leading alone cannot tell the two apart: five labels stacked at 15pt with a
+ * 12pt face look exactly like five wrapped lines, and alphatrans.pdf's five are
+ * read as one paragraph and re-wrapped into two. But a wrapping engine pulls
+ * the next word UP — so a line that stops well short of the measure stopped
+ * because its author stopped it, and the line after it begins something new.
+ * The same rule separates two paragraphs set with no extra space between them,
+ * which used to run together for the same reason.
+ *
+ * Only where both lines start at the same edge. Where they do not, the block is
+ * placed rather than set — a centred title's every line is short of the measure
+ * and none of them ends anything.
+ *
+ * @param prev   The line before: where it starts, how wide it is, its face.
+ * @param next   The line after — only where it starts matters.
+ * @param column The measure both were set in, when it is known.
+ * @returns Whether the first line ended a paragraph.
+ */
+export declare function endedParagraph(prev: {
+    x: number;
+    width: number;
+    fontSize: number;
+}, next: {
+    x: number;
+}, column: {
+    left: number;
+    right: number;
+} | undefined): boolean;

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

@@ -1,14 +1,14 @@
 import { pt } from "../core/ir/units.js";
 import { ResourceStore } from "../core/ir/resources.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 { collectEmbeddedFonts } from "./embedded-fonts.js";
 import { extractPageText } from "./text.js";
 import { collectPageVectors } from "./vector.js";
-//#region src/pdf-reader/layout.ts
+import { displayOf, placeImages, placeRuns, placeVectors } from "./display.js";
+import { buildFlowDoc, dedupeLosses, imageBlock, paragraphFromRuns, positionedText, sectionFromPdfPages, shapeBlock, withMeasuredMargins } from "./flow-build.js";
+import { collectPageImages } from "./images.js";
+import { markDrawnRules } from "./text-rules.js";
 /**
 * Heuristically reconstruct an untagged PDF into a {@link Reconstruction}
 * (E-PDF EP4). With no structure tree there is only positioned content, so
@@ -31,6 +31,11 @@ function reconstructByLayout(file, mode = "flow") {
 	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.text.includes("�")))) losses.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"
+	});
 	if (pageRuns.some((page) => page.some((r) => r.fillPatternName !== void 0))) losses.push({
 		severity: "degraded",
 		feature: FEATURES.text,
@@ -42,11 +47,12 @@ function reconstructByLayout(file, mode = "flow") {
 		const display = shown[i];
 		const pageWidth = display.width;
 		const gutter = detectGutter(runs, pageWidth);
+		const stepped = stepsBetweenWords(runs);
 		const blocks = [];
 		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)) {
+				for (const [angle, runs] of byAngle(colRuns)) for (const line of groupIntoLines(rotate(runs, -angle), true, stepped)) {
 					if (line.text.length === 0) continue;
 					const box = turnedBox(line, angle, pageWidth);
 					placed.push({
@@ -58,18 +64,21 @@ function reconstructByLayout(file, mode = "flow") {
 				}
 				return;
 			}
-			const lines = groupIntoLines(colRuns).filter((l) => l.text.length > 0);
-			for (const para of groupIntoParagraphs(lines)) blocks.push({
+			const lines = groupIntoLines(colRuns, false, stepped).filter((l) => l.text.length > 0);
+			const measure = lines.length > 0 ? {
+				left: Math.min(...lines.map((l) => l.x)),
+				right: Math.max(...lines.map((l) => l.x + l.width))
+			} : void 0;
+			for (const para of groupIntoParagraphs(lines, measure, display.height)) blocks.push({
 				col,
 				top: para.top,
-				el: paragraphFromRuns(para.spans, headingLevel(para.fontSize, medianFont))
+				el: paragraphFromRuns(para.spans, headingLevel(para.fontSize, medianFont), {
+					...para.alignment !== void 0 ? { alignment: para.alignment } : {},
+					...para.spacingBefore !== void 0 ? { spacingBefore: pt(para.spacingBefore) } : {}
+				})
 			});
 		};
 		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 frame = {
 			left: 0,
@@ -88,19 +97,26 @@ function reconstructByLayout(file, mode = "flow") {
 			maxY: img.y + img.heightPt
 		})));
 		losses.push(...lifted.losses);
-		const vectors = placeVectors(lifted.vectors, display);
+		const placedVectors = placeVectors(lifted.vectors, display);
+		const ruled = markDrawnRules(runs, placedVectors);
+		const vectors = placedVectors.filter((v) => !ruled.consumed.has(v));
+		if (gutter !== void 0) {
+			addColumn(ruled.runs.filter((r) => r.x < gutter), 0);
+			addColumn(ruled.runs.filter((r) => r.x >= gutter), 1);
+		} else addColumn(ruled.runs, 0);
+		const under = mode !== "positional";
 		[
 			...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)
+				make: (z) => imageBlock(img, resources, void 0, frame, z, under)
 			})),
 			...vectors.map((v) => ({
 				key: v.orderKey,
 				col: colOf((v.minX + v.maxX) / 2),
 				top: v.maxY,
-				make: (z) => shapeBlock(v, frame, z)
+				make: (z) => shapeBlock(v, frame, z, under)
 			})),
 			...placed
 		].sort((a, b) => compareOrder(a.key, b.key)).forEach((mark, z) => {
@@ -124,8 +140,9 @@ function reconstructByLayout(file, mode = "flow") {
 		});
 		for (const block of blocks) body.push(block.el);
 	});
+	const section = sectionFromPdfPages(pages);
 	return {
-		doc: buildFlowDoc(body, resources, sectionFromPdfPages(pages), collectEmbeddedFonts(file, pages)),
+		doc: buildFlowDoc(body, resources, mode === "positional" ? section : withMeasuredMargins(section, shown, pageRuns), collectEmbeddedFonts(file, pages, losses)),
 		losses: dedupeLosses(losses)
 	};
 }
@@ -241,7 +258,7 @@ function rotation60kOf(angleDeg) {
 * 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) {
+function groupIntoLines(runs, split = false, stepped = false) {
 	const sorted = [...runs].sort((a, b) => b.y - a.y || a.x - b.x);
 	const clusters = [];
 	for (const run of sorted) {
@@ -259,7 +276,7 @@ function groupIntoLines(runs, split = false) {
 	return clusters.flatMap((c) => {
 		const ordered = c.runs.sort((a, b) => a.x - b.x);
 		const fontSize = c.fontSize || 10;
-		if (!split) return [lineOf(ordered, c.y, fontSize)];
+		if (!split) return [lineOf(ordered, c.y, fontSize, stepped)];
 		const pieces = [[]];
 		for (const run of ordered) {
 			const prev = pieces[pieces.length - 1];
@@ -268,30 +285,96 @@ function groupIntoLines(runs, split = false) {
 			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));
+		return pieces.map((piece) => lineOf(piece, piece[0].y, Math.max(...piece.map((r) => r.fontSizePt || 0)) || fontSize, stepped));
 	});
 }
+/**
+* Where a line's INK is, which is not how far its pen travelled.
+*
+* A run of spaces advances the pen and marks nothing. basicapi.pdf sets its
+* page number as thirty-one spaces and "page 1 / 3" in ONE run, reaching 635pt
+* across a 595pt sheet — and the measure taken off that line was wide enough
+* that the centred title in the same column no longer looked centred.
+*
+* The blanks are deducted at the face's own space width, which the run carries
+* (§9.4.4); where the face states none, at a quarter of the size.
+*/
+function inkSpan(runs) {
+	const marked = runs.filter((r) => r.text.trim().length > 0);
+	if (marked.length === 0) {
+		const x = runs[0].x;
+		return {
+			x,
+			width: runs[runs.length - 1].endX - x
+		};
+	}
+	const first = marked[0];
+	const last = marked[marked.length - 1];
+	const space = (r) => r.spaceWidthPt !== void 0 && r.spaceWidthPt > 0 ? r.spaceWidthPt : (r.fontSizePt || 10) * .25;
+	const lead = (/^\s*/u.exec(first.text)?.[0].length ?? 0) * space(first);
+	const trail = (/\s*$/u.exec(last.text)?.[0].length ?? 0) * space(last);
+	const x = first.x + lead;
+	return {
+		x,
+		width: Math.max(0, last.endX - trail - x)
+	};
+}
 /** 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);
+function lineOf(runs, y, fontSize, stepped) {
+	const ordered = lineSpans(runs, fontSize, stepped);
 	const spans = ordered.every((s) => s.text.trim() === "" || isRightToLeft(s.text)) ? [...ordered].reverse() : ordered;
-	const x = runs[0].x;
+	const ink = inkSpan(runs);
 	return {
-		x,
-		width: runs[runs.length - 1].endX - x,
+		x: ink.x,
+		width: ink.width,
 		y,
 		fontSize,
 		text: spans.map((s) => s.text).join("").replace(/\s+/g, " ").trim(),
 		spans
 	};
 }
-function lineSpans(runs, fontSize) {
+/**
+* The gap between two runs that means a WORD SPACE stood there.
+*
+* A page that draws its own spaces has already said where its words divide, and
+* a gap between two of its runs is a COLUMN or a placement — 160F-2019.pdf is
+* ruled into fields a quarter-inch apart and a generous threshold keeps them
+* apart. A page that draws none has said nothing, and every word boundary on it
+* is a gap: bigboundingbox.pdf steps 0.226 em between words and never writes a
+* space, so at a quarter em its every line ran together — "OrangeDemoInc.",
+* "Whenpayingbycheck,pleasecompletethispaymentadvice".
+*
+* The two want different thresholds, and the page says which it is (see
+* {@link stepsBetweenWords}). The tight one still clears the gaps a producer
+* leaves INSIDE a word when it splits one for kerning, which measure eight
+* hundredths of an em at their widest across this corpus.
+*/
+function spaceGap(prev, fontSize, stepped) {
+	return (prev.fontSizePt || fontSize) * (stepped ? STEPPED_SPACE_EM : DRAWN_SPACE_EM);
+}
+/** A page that writes its own spaces: only a wide gap means anything more. */
+var DRAWN_SPACE_EM = .25;
+/** A page that writes none: the step between its words is all there is. */
+var STEPPED_SPACE_EM = .12;
+/**
+* Whether this page STEPS between its words rather than writing spaces.
+*
+* Counted rather than guessed: bigboundingbox.pdf writes a space in one run in
+* a hundred, TAMReview.pdf in a third of them, and no page does a little of
+* both. A page with almost no text says nothing either way and keeps the
+* cautious reading.
+*/
+function stepsBetweenWords(runs) {
+	if (runs.length < 8) return false;
+	return runs.filter((r) => /\s/u.test(r.text)).length / runs.length < .05;
+}
+function lineSpans(runs, fontSize, stepped) {
 	const spans = [];
-	let prevEnd;
+	let prev;
 	for (const run of runs) {
-		if (prevEnd !== void 0 && run.x - prevEnd > fontSize * .25) spans.push({ text: " " });
+		if (prev !== void 0 && run.x - prev.endX > spaceGap(prev, fontSize, stepped)) spans.push({ text: " " });
 		spans.push({
-			text: run.text,
+			text: run.text.replaceAll("�", ""),
 			sizePt: run.fontSizePt,
 			...run.colorHex !== "000000" ? { colorHex: run.colorHex } : {},
 			...run.fontName !== void 0 ? { fontName: run.fontName } : {},
@@ -301,26 +384,92 @@ function lineSpans(runs, fontSize) {
 			} } : {},
 			...run.bold ? { bold: true } : {},
 			...run.italic ? { italic: true } : {},
+			...run.markup !== void 0 ? { markup: run.markup } : {},
 			...run.href !== void 0 ? { href: run.href } : {}
 		});
-		prevEnd = run.endX;
+		prev = run;
 	}
 	return spans;
 }
-function groupIntoParagraphs(lines) {
+function groupIntoParagraphs(lines, column, pageHeight = 0) {
 	const groups = [];
-	let prevY;
+	const gaps = [];
+	let prev;
 	for (const line of lines) {
-		const gap = prevY !== void 0 ? prevY - line.y : 0;
-		if (groups.length === 0 || prevY !== void 0 && gap > line.fontSize * 1.5) groups.push([]);
+		const gap = prev !== void 0 ? prev.y - line.y : 0;
+		const opened = prev !== void 0 && gap > line.fontSize * 1.5;
+		if (groups.length === 0 || opened || prev !== void 0 && endedParagraph(prev, line, column)) {
+			groups.push([]);
+			gaps.push(prev === void 0 ? 0 : gap);
+		}
 		groups[groups.length - 1].push(line);
-		prevY = line.y;
+		prev = line;
 	}
-	return groups.map((g) => ({
-		spans: g.flatMap((l, i) => i > 0 ? [{ text: " " }, ...l.spans] : [...l.spans]),
-		fontSize: Math.max(...g.map((l) => l.fontSize)),
-		top: g[0].y
+	return groups.map((g, i) => {
+		const first = g[0];
+		const fontSize = Math.max(...g.map((l) => l.fontSize));
+		const opened = (gaps[i] ?? 0) - fontSize * 1.2;
+		const most = pageHeight > 0 ? pageHeight / 3 : fontSize * 3;
+		const spacingBefore = opened > fontSize * .3 ? Math.min(opened, most) : void 0;
+		return {
+			spans: g.flatMap((l, k) => k > 0 ? [{ text: " " }, ...l.spans] : [...l.spans]),
+			fontSize,
+			top: first.y,
+			...spacingBefore !== void 0 ? { spacingBefore } : {},
+			...alignmentOf(g, column)
+		};
+	});
+}
+/**
+* Whether a line ENDED a paragraph, rather than wrapping into the next.
+*
+* Leading alone cannot tell the two apart: five labels stacked at 15pt with a
+* 12pt face look exactly like five wrapped lines, and alphatrans.pdf's five are
+* read as one paragraph and re-wrapped into two. But a wrapping engine pulls
+* the next word UP — so a line that stops well short of the measure stopped
+* because its author stopped it, and the line after it begins something new.
+* The same rule separates two paragraphs set with no extra space between them,
+* which used to run together for the same reason.
+*
+* Only where both lines start at the same edge. Where they do not, the block is
+* placed rather than set — a centred title's every line is short of the measure
+* and none of them ends anything.
+*
+* @param prev   The line before: where it starts, how wide it is, its face.
+* @param next   The line after — only where it starts matters.
+* @param column The measure both were set in, when it is known.
+* @returns Whether the first line ended a paragraph.
+*/
+function endedParagraph(prev, next, column) {
+	if (!column) return false;
+	const width = column.right - column.left;
+	if (!(width > 0)) return false;
+	if (Math.abs(prev.x - next.x) > Math.max(prev.fontSize, 4)) return false;
+	return column.right - (prev.x + prev.width) > width * .25;
+}
+/**
+* §17.3.1.13 — where a paragraph sits across its column, which is the only
+* witness a PDF leaves of how it was set: every line is placed absolutely and
+* nothing says "centred".
+*
+* A paragraph whose lines are inset by about as much on each side is centred; a
+* one-line paragraph pushed to the right edge is right-aligned. Everything else
+* is left alone — a justified paragraph and a ragged-right one look the same
+* from here, and guessing between them would re-set the body of every document.
+*/
+function alignmentOf(lines, column) {
+	if (!column || lines.length === 0) return {};
+	const width = column.right - column.left;
+	if (!(width > 0)) return {};
+	const insets = lines.map((l) => ({
+		lead: l.x - column.left,
+		trail: column.right - (l.x + l.width)
 	}));
+	const meaningful = width * .1;
+	const even = width * .06;
+	if (insets.every((i) => Math.abs(i.lead - i.trail) <= even) && Math.max(...insets.map((i) => Math.min(i.lead, i.trail))) >= meaningful) return { alignment: "center" };
+	if (insets.every((i) => i.trail <= even) && Math.max(...insets.map((i) => i.lead)) >= meaningful) return { alignment: "right" };
+	return {};
 }
 function headingLevel(fontSize, medianFont) {
 	if (fontSize >= medianFont * 1.5) return 0;
@@ -342,4 +491,4 @@ function compareOrder(a, b) {
 	return a.length - b.length;
 }
 //#endregion
-export { reconstructByLayout };
+export { endedParagraph, reconstructByLayout };

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

@@ -45,6 +45,8 @@ export declare class Lexer {
     constructor(buf: Uint8Array, pos?: number);
     /** The length of the underlying byte buffer. */
     get length(): number;
+    /** The bytes between two offsets, as a view onto the buffer. */
+    slice(from: number, to: number): Uint8Array;
     /** The byte at index `i`, or −1 when out of range. */
     byteAt(i: number): number;
     /** §7.2.3 — skip whitespace and `%`-to-end-of-line comments. */

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

@@ -34,6 +34,10 @@ var Lexer = class {
 	get length() {
 		return this.buf.length;
 	}
+	/** The bytes between two offsets, as a view onto the buffer. */
+	slice(from, to) {
+		return this.buf.subarray(Math.max(0, from), Math.min(this.buf.length, Math.max(from, to)));
+	}
 	/** The byte at index `i`, or −1 when out of range. */
 	byteAt(i) {
 		return i >= 0 && i < this.buf.length ? this.buf[i] : -1;

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

@@ -0,0 +1,36 @@
+import { PdfDict, PdfStream, PdfValue } from '../pdf/objects.js';
+import { PdfFile } from './document.js';
+/**
+ * The optional-content groups the file's DEFAULT configuration turns off
+ * (§8.11.4.3).
+ *
+ * `/BaseState` says what an unlisted group does — `/ON` unless the file says
+ * `/OFF` — and the `/ON` and `/OFF` arrays name the exceptions, `/OFF` last.
+ *
+ * @param file The document.
+ * @returns The resolved OCG dictionaries that are hidden.
+ */
+export declare function hiddenGroups(file: PdfFile): ReadonlySet<PdfValue>;
+/**
+ * Whether an `/OC` entry names something the page does not show.
+ *
+ * The entry is either a group itself or an `/OCMD` — a membership dictionary
+ * naming several groups and a `/P` policy over them (§8.11.2.3). `AnyOn` is the
+ * default and the common case: the content shows if any of its groups does.
+ *
+ * @param file The document.
+ * @param oc   The `/OC` value, unresolved.
+ * @returns `true` where the content it guards is hidden.
+ */
+export declare function hiddenByOc(file: PdfFile, oc: PdfValue | undefined): boolean;
+/**
+ * The `/Properties` names a page's content may name in `/OC … BDC` that are
+ * hidden (§8.11.3.2).
+ *
+ * @param file      The document.
+ * @param resources The resource dictionary in force.
+ * @returns Name → hidden, for the names that ARE hidden.
+ */
+export declare function hiddenProperties(file: PdfFile, resources: PdfDict | undefined): Set<string>;
+/** Whether an XObject carries an `/OC` that hides it (§8.11.3.1). */
+export declare function hiddenXObject(file: PdfFile, stream: PdfStream): boolean;

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

@@ -0,0 +1,93 @@
+import { PDF_NULL, PdfName } from "../pdf/objects.js";
+//#region src/pdf-reader/optional-content.ts
+/** The document's own answer to "is this group shown?", worked out once. */
+var cache = /* @__PURE__ */ new WeakMap();
+/** An `/OCMD` naming more groups than this is not read: it is not a document. */
+var MAX_GROUPS = 4096;
+/**
+* The optional-content groups the file's DEFAULT configuration turns off
+* (§8.11.4.3).
+*
+* `/BaseState` says what an unlisted group does — `/ON` unless the file says
+* `/OFF` — and the `/ON` and `/OFF` arrays name the exceptions, `/OFF` last.
+*
+* @param file The document.
+* @returns The resolved OCG dictionaries that are hidden.
+*/
+function hiddenGroups(file) {
+	const had = cache.get(file);
+	if (had) return had;
+	const hidden = /* @__PURE__ */ new Set();
+	const props = file.get(file.catalog, "OCProperties");
+	const config = props instanceof Map ? file.get(props, "D") : void 0;
+	if (config instanceof Map) {
+		const base = file.get(config, "BaseState");
+		if (base instanceof PdfName && base.value === "OFF") {
+			const all = file.get(props instanceof Map ? props : /* @__PURE__ */ new Map(), "OCGs");
+			for (const g of asArray(file, all)) hidden.add(g);
+		}
+		for (const g of asArray(file, file.get(config, "ON"))) hidden.delete(g);
+		for (const g of asArray(file, file.get(config, "OFF"))) hidden.add(g);
+	}
+	cache.set(file, hidden);
+	return hidden;
+}
+/**
+* Whether an `/OC` entry names something the page does not show.
+*
+* The entry is either a group itself or an `/OCMD` — a membership dictionary
+* naming several groups and a `/P` policy over them (§8.11.2.3). `AnyOn` is the
+* default and the common case: the content shows if any of its groups does.
+*
+* @param file The document.
+* @param oc   The `/OC` value, unresolved.
+* @returns `true` where the content it guards is hidden.
+*/
+function hiddenByOc(file, oc) {
+	if (oc === void 0) return false;
+	const hidden = hiddenGroups(file);
+	const resolved = file.resolve(oc);
+	if (!(resolved instanceof Map)) return false;
+	const type = file.get(resolved, "Type");
+	if (!(type instanceof PdfName) || type.value !== "OCMD") return hidden.has(resolved);
+	const groups = asArray(file, file.get(resolved, "OCGs"));
+	const single = file.resolve(resolved.get("OCGs") ?? PDF_NULL);
+	const list = groups.length > 0 ? groups : single instanceof Map ? [single] : [];
+	if (list.length === 0) return false;
+	const on = list.filter((g) => !hidden.has(g)).length;
+	const policy = file.get(resolved, "P");
+	switch (policy instanceof PdfName ? policy.value : "AnyOn") {
+		case "AllOn": return on < list.length;
+		case "AnyOff": return on === list.length;
+		case "AllOff": return on > 0;
+		default: return on === 0;
+	}
+}
+/**
+* The `/Properties` names a page's content may name in `/OC … BDC` that are
+* hidden (§8.11.3.2).
+*
+* @param file      The document.
+* @param resources The resource dictionary in force.
+* @returns Name → hidden, for the names that ARE hidden.
+*/
+function hiddenProperties(file, resources) {
+	const out = /* @__PURE__ */ new Set();
+	if (!resources) return out;
+	const props = file.get(resources, "Properties");
+	if (!(props instanceof Map)) return out;
+	for (const [name, value] of props) if (hiddenByOc(file, value)) out.add(name);
+	return out;
+}
+/** Whether an XObject carries an `/OC` that hides it (§8.11.3.1). */
+function hiddenXObject(file, stream) {
+	return hiddenByOc(file, stream.dict.get("OC"));
+}
+/** An array entry, resolved; a missing or malformed one comes back empty. */
+function asArray(file, value) {
+	const r = value !== void 0 ? file.resolve(value) : void 0;
+	if (!Array.isArray(r)) return [];
+	return r.slice(0, MAX_GROUPS).map((v) => file.resolve(v));
+}
+//#endregion
+export { hiddenProperties, hiddenXObject };

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

@@ -13,14 +13,17 @@ import { FlowDoc } from '../core/ir/flow.js';
  *                 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 —
+ * @param layout   `'auto'` (the default) lets the FILE decide: a page that is
+ *                 mostly marks is reproduced, one that is mostly lines is re-set,
+ *                 and the reader records which it chose. `'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, layout?: 'flow' | 'positional', filters?: StreamFilters): ReadResult<FlowDoc>;
+export declare function readPdf(bytes: Uint8Array, password?: string, layout?: 'flow' | 'positional' | 'auto', 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).