pdf-codec 5.3.32 → 5.4.0

package/dist/layout.js

@@ -172,8 +172,18 @@ const LayoutPageSchema = z.object({
 	heightPt: z.number().positive(),
 	items: z.array(LayoutItemSchema),
 	annotations: z.array(LayoutAnnotationSchema).optional(),
-	notes: z.string().optional()
+	notes: z.string().optional(),
+	index: z.number().int().nonnegative().optional()
 });
+/**
+* The zero-based index in the source PDF's page tree of the page at `position` in a `LayoutDocument`'s `pages`: the page's own `index` when a page-selected read set one, otherwise `position` itself, which is the source index whenever `pages` holds every page in document order. The one place that rule is spelled, so every consumer resolving a page against a document-level reference (a destination, a form widget, a frame) agrees on it.
+* @param page - the page as it appears in `pages`
+* @param position - the page's position in `pages`
+* @returns the page's index in the source document's page tree
+*/
+function sourcePageIndex(page, position) {
+	return page.index ?? position;
+}
 const LayoutImageAssetSchema = z.object({
 	format: z.enum(["png", "jpeg"]),
 	base64: z.string(),
@@ -262,6 +272,7 @@ const LayoutDocumentSchema = z.object({
 	formatVersion: z.literal(1),
 	metadata: LayoutMetadataSchema,
 	pages: z.array(LayoutPageSchema),
+	pageCount: z.number().int().nonnegative().optional(),
 	images: z.record(z.string(), LayoutImageAssetSchema),
 	destinations: z.array(LayoutDestinationSchema).optional(),
 	outline: z.array(LayoutOutlineItemSchema).optional(),
@@ -272,4 +283,4 @@ const LayoutDocumentSchema = z.object({
 	source: z.record(z.string(), SourceResidueSchema).optional()
 });
 //#endregion
-export { LAYOUT_FORMAT_VERSION, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachmentSchema, LayoutDestinationSchema, LayoutDestinationTargetSchema, LayoutDocumentSchema, LayoutEllipseSchema, LayoutFormFieldSchema, LayoutFormWidgetSchema, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLinkSchema, LayoutItemSchema, LayoutLayerSchema, LayoutLineSchema, LayoutLinkSchema, LayoutOutlineItemSchema, LayoutPageSchema, LayoutPathSchema, LayoutPathSegmentSchema, LayoutRectSchema, LayoutStructureElementSchema, LayoutSubpathSchema, LayoutTextSchema };
+export { LAYOUT_FORMAT_VERSION, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachmentSchema, LayoutDestinationSchema, LayoutDestinationTargetSchema, LayoutDocumentSchema, LayoutEllipseSchema, LayoutFormFieldSchema, LayoutFormWidgetSchema, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLinkSchema, LayoutItemSchema, LayoutLayerSchema, LayoutLineSchema, LayoutLinkSchema, LayoutOutlineItemSchema, LayoutPageSchema, LayoutPathSchema, LayoutPathSegmentSchema, LayoutRectSchema, LayoutStructureElementSchema, LayoutSubpathSchema, LayoutTextSchema, sourcePageIndex };

package/dist/names.d.cts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.cjs";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.cjs";
 import { r as PdfObject } from "./objects-e2RS3-yT.cjs";
 import { PdfObjectResolver } from "./interpret-types.cjs";
 //#region src/names.d.ts

package/dist/names.d.ts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.js";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.js";
 import { r as PdfObject } from "./objects-e2RS3-yT.js";
 import { PdfObjectResolver } from "./interpret-types.js";
 //#region src/names.d.ts

package/dist/navigation.d.cts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.cjs";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.cjs";
 import { n as PdfDict, r as PdfObject } from "./objects-e2RS3-yT.cjs";
 import { PdfObjectResolver } from "./interpret-types.cjs";
 import { LayoutDestination, LayoutDestinationTarget, LayoutOutlineItem } from "./layout.cjs";

package/dist/navigation.d.ts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.js";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.js";
 import { n as PdfDict, r as PdfObject } from "./objects-e2RS3-yT.js";
 import { PdfObjectResolver } from "./interpret-types.js";
 import { LayoutDestination, LayoutDestinationTarget, LayoutOutlineItem } from "./layout.js";

package/dist/optional-content.d.cts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.cjs";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.cjs";
 import { n as PdfDict, r as PdfObject } from "./objects-e2RS3-yT.cjs";
 import { PdfObjectResolver } from "./interpret-types.cjs";
 import { LayoutLayer } from "./layout.cjs";

package/dist/optional-content.d.ts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.js";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.js";
 import { n as PdfDict, r as PdfObject } from "./objects-e2RS3-yT.js";
 import { PdfObjectResolver } from "./interpret-types.js";
 import { LayoutLayer } from "./layout.js";

package/dist/parse.d.cts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.cjs";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.cjs";
 import { r as PdfObject } from "./objects-e2RS3-yT.cjs";
 import { ByteReader } from "./bytes/reader.cjs";
 //#region src/parse.d.ts

package/dist/parse.d.ts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.js";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.js";
 import { r as PdfObject } from "./objects-e2RS3-yT.js";
 import { ByteReader } from "./bytes/reader.js";
 //#region src/parse.d.ts

package/dist/predictors.d.cts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.cjs";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.cjs";
 import { n as PdfDict } from "./objects-e2RS3-yT.cjs";
 //#region src/predictors.d.ts
 interface PredictorParams {

package/dist/predictors.d.ts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.js";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.js";
 import { n as PdfDict } from "./objects-e2RS3-yT.js";
 //#region src/predictors.d.ts
 interface PredictorParams {

package/dist/raster-text.d.cts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.cjs";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.cjs";
 import { n as PdfDict } from "./objects-e2RS3-yT.cjs";
 import { r as Matrix } from "./matrix-B7_SBKQ5.cjs";
 import { ExtractedTextRun, PdfObjectResolver } from "./interpret-types.cjs";

package/dist/raster-text.d.ts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.js";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.js";
 import { n as PdfDict } from "./objects-e2RS3-yT.js";
 import { r as Matrix } from "./matrix-B7_SBKQ5.js";
 import { ExtractedTextRun, PdfObjectResolver } from "./interpret-types.js";

package/dist/raster.d.cts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.cjs";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.cjs";
 import { t as SfntFont } from "./sfnt-V08bb5ut.cjs";
 import { r as GlyfTable } from "./glyf-DFyknMrW.cjs";
 import { Color } from "document-schema.js";

package/dist/raster.d.ts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.js";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.js";
 import { t as SfntFont } from "./sfnt-V08bb5ut.js";
 import { r as GlyfTable } from "./glyf-Bv1katwK.js";
 import { Color } from "document-schema.js";

package/dist/read-convert.d.cts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.cjs";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.cjs";
 import { n as PdfDict } from "./objects-e2RS3-yT.cjs";
 import { r as Matrix } from "./matrix-B7_SBKQ5.cjs";
 import { ExtractedEllipse, ExtractedImage, ExtractedItem, ExtractedLine, ExtractedPaint, ExtractedPath, ExtractedRect, ExtractedSubpath, ExtractedTextRun, PdfObjectResolver } from "./interpret-types.cjs";

package/dist/read-convert.d.ts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.js";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.js";
 import { n as PdfDict } from "./objects-e2RS3-yT.js";
 import { r as Matrix } from "./matrix-B7_SBKQ5.js";
 import { ExtractedEllipse, ExtractedImage, ExtractedItem, ExtractedLine, ExtractedPaint, ExtractedPath, ExtractedRect, ExtractedSubpath, ExtractedTextRun, PdfObjectResolver } from "./interpret-types.js";

package/dist/read.cjs

@@ -20,6 +20,15 @@ const require_font_read = require("./font-read.cjs");
 const require_interpret = require("./interpret-BDVrFWhd.cjs");
 const require_navigation = require("./navigation.cjs");
 //#region src/read.ts
+function resolvePageSelection(selection, pageCount) {
+	const resolved = /* @__PURE__ */ new Set();
+	for (const requested of selection) {
+		const index = requested < 0 ? pageCount + requested : requested;
+		if (!Number.isInteger(requested) || index < 0 || index >= pageCount) throw new require_diagnostics.PdfPageSelectionError(requested, pageCount);
+		resolved.add(index);
+	}
+	return resolved;
+}
 const PDF_HEADER_BYTES = new TextEncoder().encode("%PDF-");
 const HEADER_SEARCH_WINDOW = 1024;
 const DEFAULT_PAGE_WIDTH_PT = 612;
@@ -45,19 +54,24 @@ function readPdf(bytes, options) {
 	const images = {};
 	const imageIdCache = /* @__PURE__ */ new Map();
 	const pageDicts = doc.pages();
+	const selection = options?.pages === void 0 ? void 0 : resolvePageSelection(options.pages, pageDicts.length);
 	const destinationRegistry = require_navigation.createDestinationRegistry(doc.catalog, doc, (obj) => doc.pageIndex(obj), sink);
 	const outline = require_navigation.readOutline(doc.catalog, destinationRegistry, doc, sink);
-	const attachments = require_attachments.readAttachments(doc.catalog, pageDicts, doc, sink);
+	const attachments = selection === void 0 ? require_attachments.readAttachments(doc.catalog, pageDicts, doc, sink) : [];
 	const optionalContent = require_optional_content.readOptionalContent(doc.catalog, doc, sink);
 	const form = require_form.readAcroForm(doc.catalog, doc, (obj) => doc.pageIndex(obj), sink);
-	const structure = require_structure.readStructure(doc.catalog, pageDicts, doc, sink);
+	const structure = require_structure.readStructure(doc.catalog, pageDicts, (index) => selection === void 0 || selection.has(index), doc, sink);
 	const source = readDocumentResidue(doc, sink);
 	const pageBoxRows = [];
-	const pages = pageDicts.map((pageDict, index) => {
+	const pages = pageDicts.flatMap((pageDict, index) => {
+		if (selection !== void 0 && !selection.has(index)) return [];
 		require_util_abort.throwIfAborted(signal);
 		const read = readPage(index, pageDict, doc, fontResolver, images, imageIdCache, destinationRegistry, optionalContent.layerNameOf, structure.ownerOf, sink);
 		if (read.boxRow !== void 0) pageBoxRows.push(read.boxRow);
-		return read.page;
+		return [selection === void 0 ? read.page : {
+			...read.page,
+			index
+		}];
 	});
 	if (pageBoxRows.length > 0) source["page-boxes"] = {
 		format: "pdf",
@@ -67,6 +81,7 @@ function readPdf(bytes, options) {
 		formatVersion: 1,
 		metadata: readMetadata(doc.trailer, doc, doc.catalog, sink),
 		pages,
+		...selection !== void 0 ? { pageCount: pageDicts.length } : {},
 		images,
 		...destinationRegistry.entries.length > 0 ? { destinations: [...destinationRegistry.entries] } : {},
 		...outline.length > 0 ? { outline } : {},

package/dist/read.d.cts

@@ -1,10 +1,20 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.cjs";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.cjs";
 import { r as Matrix } from "./matrix-B7_SBKQ5.cjs";
 import { LayoutDocument } from "./layout.cjs";
 //#region src/read.d.ts
 interface ReadPdfOptions {
   readonly sink?: PdfDiagnosticSink;
   readonly signal?: AbortSignal;
+  /**
+   * The pages to read, as zero-based indices into the document's page tree; a negative index counts from the end (`-1` is the last page). Omitted, every page is read.
+   *
+   * What a selected read skips: an unselected page's content stream is never fetched, decoded or interpreted, so the fonts and images only unselected pages use are never resolved; embedded-file payloads are never decoded, so `attachments` is absent from a page-selected result (an attachment is document-level payload whose size is independent of the pages asked for, and decoding it would cost the same whichever pages were selected).
+   *
+   * What it still reads whole, because a negative index and every document-level page reference resolve against it or because it is document-level and holds no page content stream: the page tree, the outline, named destinations, optional-content layers, the AcroForm, the structure element tree and the /ParentTree number tree (both of which scale with the document), metadata and package residue. Two surfaces are built from page content and so cover selected pages only: the structure-ownership association an item's `structure` field names (and its parent-tree diagnostics), and the `page-boxes` residue row. Destinations a link states as a direct array are minted into `destinations` (as `dest1`, `dest2`, ...) only when their page is interpreted, so an unselected page's direct link destinations are absent and a minted name depends on which pages were read; named destinations are unaffected.
+   *
+   * Duplicates collapse, and the result's `pages` holds the selected pages in ascending document order whatever order they were asked for in, each carrying its source position as `index`, with the document's total as `pageCount`; every document-level reference keeps naming source indices. An empty array is a valid selection: it reads no page and returns the document-level surfaces with `pageCount`, the cheapest way to learn a file's length and metadata. An entry naming no page throws `PdfPageSelectionError` rather than being skipped.
+   */
+  readonly pages?: readonly number[];
 }
 declare function readPdf(bytes: Uint8Array<ArrayBuffer>, options?: ReadPdfOptions): LayoutDocument;
 type PageRotation = 0 | 90 | 180 | 270;

package/dist/read.d.ts

@@ -1,10 +1,20 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.js";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.js";
 import { r as Matrix } from "./matrix-B7_SBKQ5.js";
 import { LayoutDocument } from "./layout.js";
 //#region src/read.d.ts
 interface ReadPdfOptions {
   readonly sink?: PdfDiagnosticSink;
   readonly signal?: AbortSignal;
+  /**
+   * The pages to read, as zero-based indices into the document's page tree; a negative index counts from the end (`-1` is the last page). Omitted, every page is read.
+   *
+   * What a selected read skips: an unselected page's content stream is never fetched, decoded or interpreted, so the fonts and images only unselected pages use are never resolved; embedded-file payloads are never decoded, so `attachments` is absent from a page-selected result (an attachment is document-level payload whose size is independent of the pages asked for, and decoding it would cost the same whichever pages were selected).
+   *
+   * What it still reads whole, because a negative index and every document-level page reference resolve against it or because it is document-level and holds no page content stream: the page tree, the outline, named destinations, optional-content layers, the AcroForm, the structure element tree and the /ParentTree number tree (both of which scale with the document), metadata and package residue. Two surfaces are built from page content and so cover selected pages only: the structure-ownership association an item's `structure` field names (and its parent-tree diagnostics), and the `page-boxes` residue row. Destinations a link states as a direct array are minted into `destinations` (as `dest1`, `dest2`, ...) only when their page is interpreted, so an unselected page's direct link destinations are absent and a minted name depends on which pages were read; named destinations are unaffected.
+   *
+   * Duplicates collapse, and the result's `pages` holds the selected pages in ascending document order whatever order they were asked for in, each carrying its source position as `index`, with the document's total as `pageCount`; every document-level reference keeps naming source indices. An empty array is a valid selection: it reads no page and returns the document-level surfaces with `pageCount`, the cheapest way to learn a file's length and metadata. An entry naming no page throws `PdfPageSelectionError` rather than being skipped.
+   */
+  readonly pages?: readonly number[];
 }
 declare function readPdf(bytes: Uint8Array<ArrayBuffer>, options?: ReadPdfOptions): LayoutDocument;
 type PageRotation = 0 | 90 | 180 | 270;

package/dist/read.js

@@ -12,13 +12,22 @@ import { readXmpMetadata } from "./xmp.js";
 import { readOptionalContent } from "./optional-content.js";
 import { readStructure } from "./structure.js";
 import "./layout.js";
-import { NOOP_DIAGNOSTIC_SINK, PdfParseError } from "./diagnostics.js";
+import { NOOP_DIAGNOSTIC_SINK, PdfPageSelectionError, PdfParseError } from "./diagnostics.js";
 import { openPdfDocument } from "./document.js";
 import { throwIfAborted } from "./util/abort.js";
 import { createFontResolver } from "./font-read.js";
 import { t as interpretContentStream } from "./interpret---0lZPlv.js";
 import { createDestinationRegistry, readOutline } from "./navigation.js";
 //#region src/read.ts
+function resolvePageSelection(selection, pageCount) {
+	const resolved = /* @__PURE__ */ new Set();
+	for (const requested of selection) {
+		const index = requested < 0 ? pageCount + requested : requested;
+		if (!Number.isInteger(requested) || index < 0 || index >= pageCount) throw new PdfPageSelectionError(requested, pageCount);
+		resolved.add(index);
+	}
+	return resolved;
+}
 const PDF_HEADER_BYTES = new TextEncoder().encode("%PDF-");
 const HEADER_SEARCH_WINDOW = 1024;
 const DEFAULT_PAGE_WIDTH_PT = 612;
@@ -44,19 +53,24 @@ function readPdf(bytes, options) {
 	const images = {};
 	const imageIdCache = /* @__PURE__ */ new Map();
 	const pageDicts = doc.pages();
+	const selection = options?.pages === void 0 ? void 0 : resolvePageSelection(options.pages, pageDicts.length);
 	const destinationRegistry = createDestinationRegistry(doc.catalog, doc, (obj) => doc.pageIndex(obj), sink);
 	const outline = readOutline(doc.catalog, destinationRegistry, doc, sink);
-	const attachments = readAttachments(doc.catalog, pageDicts, doc, sink);
+	const attachments = selection === void 0 ? readAttachments(doc.catalog, pageDicts, doc, sink) : [];
 	const optionalContent = readOptionalContent(doc.catalog, doc, sink);
 	const form = readAcroForm(doc.catalog, doc, (obj) => doc.pageIndex(obj), sink);
-	const structure = readStructure(doc.catalog, pageDicts, doc, sink);
+	const structure = readStructure(doc.catalog, pageDicts, (index) => selection === void 0 || selection.has(index), doc, sink);
 	const source = readDocumentResidue(doc, sink);
 	const pageBoxRows = [];
-	const pages = pageDicts.map((pageDict, index) => {
+	const pages = pageDicts.flatMap((pageDict, index) => {
+		if (selection !== void 0 && !selection.has(index)) return [];
 		throwIfAborted(signal);
 		const read = readPage(index, pageDict, doc, fontResolver, images, imageIdCache, destinationRegistry, optionalContent.layerNameOf, structure.ownerOf, sink);
 		if (read.boxRow !== void 0) pageBoxRows.push(read.boxRow);
-		return read.page;
+		return [selection === void 0 ? read.page : {
+			...read.page,
+			index
+		}];
 	});
 	if (pageBoxRows.length > 0) source["page-boxes"] = {
 		format: "pdf",
@@ -66,6 +80,7 @@ function readPdf(bytes, options) {
 		formatVersion: 1,
 		metadata: readMetadata(doc.trailer, doc, doc.catalog, sink),
 		pages,
+		...selection !== void 0 ? { pageCount: pageDicts.length } : {},
 		images,
 		...destinationRegistry.entries.length > 0 ? { destinations: [...destinationRegistry.entries] } : {},
 		...outline.length > 0 ? { outline } : {},

package/dist/structure.cjs

@@ -6,7 +6,16 @@ const NEVER_DICT = {
 	kind: "dict",
 	entries: /* @__PURE__ */ new Map()
 };
-function readStructure(catalog, pages, resolver, sink) {
+/**
+* Reads the tagged-structure element tree and the (page, MCID) ownership map.
+* @param catalog - the document catalog
+* @param pages - every page of the page tree, in document order, so a position is a source page index
+* @param includePage - whether the page at a source index is being read: ownership entries and parent-tree diagnostics are built for those pages only, while the element tree itself is document-level and always read whole
+* @param resolver - the object resolver
+* @param sink - where recoverable parse diagnostics go
+* @returns the element tree and an owner lookup answering for included pages
+*/
+function readStructure(catalog, pages, includePage, resolver, sink) {
 	const root = resolver.resolveDict(require_objects.dictGet(catalog, "StructTreeRoot"));
 	if (root === void 0) return {
 		tree: [],
@@ -68,7 +77,7 @@ function readStructure(catalog, pages, resolver, sink) {
 	}
 	return {
 		tree,
-		ownerOf: parentTreeOwners(root, pages, resolver, idByDict, sink)
+		ownerOf: parentTreeOwners(root, pages, includePage, resolver, idByDict, sink)
 	};
 }
 const ATTRIBUTE_KEYS = [
@@ -146,7 +155,7 @@ function numberTreeEntries(node, resolver, visited) {
 	}
 	return entries;
 }
-function parentTreeOwners(root, pages, resolver, idByDict, sink) {
+function parentTreeOwners(root, pages, includePage, resolver, idByDict, sink) {
 	const documentTree = resolver.resolveDict(require_objects.dictGet(root, "ParentTree"));
 	if (documentTree === void 0) {
 		if (require_objects.dictGet(root, "ParentTree") !== void 0) sink({
@@ -159,6 +168,7 @@ function parentTreeOwners(root, pages, resolver, idByDict, sink) {
 	const entries = new Map(numberTreeEntries(documentTree, resolver, /* @__PURE__ */ new Set()));
 	const owners = /* @__PURE__ */ new Map();
 	pages.forEach((page, pageIndex) => {
+		if (!includePage(pageIndex)) return;
 		const structParents = require_objects.asNumber(require_objects.dictGet(page, "StructParents"));
 		if (structParents === void 0) return;
 		const entry = entries.get(structParents);

package/dist/structure.d.cts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.cjs";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.cjs";
 import { n as PdfDict } from "./objects-e2RS3-yT.cjs";
 import { PdfObjectResolver } from "./interpret-types.cjs";
 import { LayoutStructureElement } from "./layout.cjs";
@@ -7,6 +7,15 @@ interface StructureContext {
   readonly tree: readonly LayoutStructureElement[];
   readonly ownerOf: (pageIndex: number, mcid: number) => string | undefined;
 }
-declare function readStructure(catalog: PdfDict, pages: readonly PdfDict[], resolver: Readonly<PdfObjectResolver>, sink: PdfDiagnosticSink): StructureContext;
+/**
+ * Reads the tagged-structure element tree and the (page, MCID) ownership map.
+ * @param catalog - the document catalog
+ * @param pages - every page of the page tree, in document order, so a position is a source page index
+ * @param includePage - whether the page at a source index is being read: ownership entries and parent-tree diagnostics are built for those pages only, while the element tree itself is document-level and always read whole
+ * @param resolver - the object resolver
+ * @param sink - where recoverable parse diagnostics go
+ * @returns the element tree and an owner lookup answering for included pages
+ */
+declare function readStructure(catalog: PdfDict, pages: readonly PdfDict[], includePage: (pageIndex: number) => boolean, resolver: Readonly<PdfObjectResolver>, sink: PdfDiagnosticSink): StructureContext;
 //#endregion
 export { StructureContext, readStructure };

package/dist/structure.d.ts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.js";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.js";
 import { n as PdfDict } from "./objects-e2RS3-yT.js";
 import { PdfObjectResolver } from "./interpret-types.js";
 import { LayoutStructureElement } from "./layout.js";
@@ -7,6 +7,15 @@ interface StructureContext {
   readonly tree: readonly LayoutStructureElement[];
   readonly ownerOf: (pageIndex: number, mcid: number) => string | undefined;
 }
-declare function readStructure(catalog: PdfDict, pages: readonly PdfDict[], resolver: Readonly<PdfObjectResolver>, sink: PdfDiagnosticSink): StructureContext;
+/**
+ * Reads the tagged-structure element tree and the (page, MCID) ownership map.
+ * @param catalog - the document catalog
+ * @param pages - every page of the page tree, in document order, so a position is a source page index
+ * @param includePage - whether the page at a source index is being read: ownership entries and parent-tree diagnostics are built for those pages only, while the element tree itself is document-level and always read whole
+ * @param resolver - the object resolver
+ * @param sink - where recoverable parse diagnostics go
+ * @returns the element tree and an owner lookup answering for included pages
+ */
+declare function readStructure(catalog: PdfDict, pages: readonly PdfDict[], includePage: (pageIndex: number) => boolean, resolver: Readonly<PdfObjectResolver>, sink: PdfDiagnosticSink): StructureContext;
 //#endregion
 export { StructureContext, readStructure };

package/dist/structure.js

@@ -5,7 +5,16 @@ const NEVER_DICT = {
 	kind: "dict",
 	entries: /* @__PURE__ */ new Map()
 };
-function readStructure(catalog, pages, resolver, sink) {
+/**
+* Reads the tagged-structure element tree and the (page, MCID) ownership map.
+* @param catalog - the document catalog
+* @param pages - every page of the page tree, in document order, so a position is a source page index
+* @param includePage - whether the page at a source index is being read: ownership entries and parent-tree diagnostics are built for those pages only, while the element tree itself is document-level and always read whole
+* @param resolver - the object resolver
+* @param sink - where recoverable parse diagnostics go
+* @returns the element tree and an owner lookup answering for included pages
+*/
+function readStructure(catalog, pages, includePage, resolver, sink) {
 	const root = resolver.resolveDict(dictGet(catalog, "StructTreeRoot"));
 	if (root === void 0) return {
 		tree: [],
@@ -67,7 +76,7 @@ function readStructure(catalog, pages, resolver, sink) {
 	}
 	return {
 		tree,
-		ownerOf: parentTreeOwners(root, pages, resolver, idByDict, sink)
+		ownerOf: parentTreeOwners(root, pages, includePage, resolver, idByDict, sink)
 	};
 }
 const ATTRIBUTE_KEYS = [
@@ -145,7 +154,7 @@ function numberTreeEntries(node, resolver, visited) {
 	}
 	return entries;
 }
-function parentTreeOwners(root, pages, resolver, idByDict, sink) {
+function parentTreeOwners(root, pages, includePage, resolver, idByDict, sink) {
 	const documentTree = resolver.resolveDict(dictGet(root, "ParentTree"));
 	if (documentTree === void 0) {
 		if (dictGet(root, "ParentTree") !== void 0) sink({
@@ -158,6 +167,7 @@ function parentTreeOwners(root, pages, resolver, idByDict, sink) {
 	const entries = new Map(numberTreeEntries(documentTree, resolver, /* @__PURE__ */ new Set()));
 	const owners = /* @__PURE__ */ new Map();
 	pages.forEach((page, pageIndex) => {
+		if (!includePage(pageIndex)) return;
 		const structParents = asNumber(dictGet(page, "StructParents"));
 		if (structParents === void 0) return;
 		const entry = entries.get(structParents);

package/dist/write.cjs

@@ -69,7 +69,21 @@ function buildFontObjects(standardName, descriptorRef) {
 function codePointsOf(texts) {
 	return new Set(texts.flatMap((text) => [...text].map((character) => character.codePointAt(0))));
 }
+/**
+* writePdf was handed a LayoutDocument from a page-selected read (one carrying `pageCount`). Such a document is a reading of part of a file, not a document to re-emit: its pages are a selection while its destinations, form widgets and outline still name source page indices, and the writer places pages by position, so writing it would point those references at the wrong pages or past the end. Thrown rather than writing a file whose links silently lie.
+*/
+var PdfPartialDocumentError = class extends Error {
+	pageCount;
+	selectedPageCount;
+	constructor(pageCount, selectedPageCount) {
+		super(`this LayoutDocument holds ${String(selectedPageCount)} pages selected from a ${String(pageCount)}-page file (it carries pageCount, which only a page-selected read sets); its page references name pages of the source file, so it cannot be written as a document of its own`);
+		this.name = "PdfPartialDocumentError";
+		this.pageCount = pageCount;
+		this.selectedPageCount = selectedPageCount;
+	}
+};
 function writePdf(doc, options = {}) {
+	if (doc.pageCount !== void 0) throw new PdfPartialDocumentError(doc.pageCount, doc.pages.length);
 	const compress = options.compress ?? true;
 	const registry = options.fonts;
 	const measurer = require_measure.createFontMeasurer(registry);
@@ -478,4 +492,5 @@ function writePdf(doc, options = {}) {
 	return writer.toBytes();
 }
 //#endregion
+exports.PdfPartialDocumentError = PdfPartialDocumentError;
 exports.writePdf = writePdf;

package/dist/write.d.cts

@@ -18,6 +18,14 @@ interface WritePdfOptions {
   readonly formulas?: readonly PositionedFormula[];
   readonly encryption?: PdfEncryptionOptions;
 }
+/**
+ * writePdf was handed a LayoutDocument from a page-selected read (one carrying `pageCount`). Such a document is a reading of part of a file, not a document to re-emit: its pages are a selection while its destinations, form widgets and outline still name source page indices, and the writer places pages by position, so writing it would point those references at the wrong pages or past the end. Thrown rather than writing a file whose links silently lie.
+ */
+declare class PdfPartialDocumentError extends Error {
+  readonly pageCount: number;
+  readonly selectedPageCount: number;
+  constructor(pageCount: number, selectedPageCount: number);
+}
 declare function writePdf(doc: LayoutDocument, options?: WritePdfOptions): Uint8Array<ArrayBuffer>;
 //#endregion
-export { WritePdfOptions, writePdf };
+export { PdfPartialDocumentError, WritePdfOptions, writePdf };

package/dist/write.d.ts

@@ -18,6 +18,14 @@ interface WritePdfOptions {
   readonly formulas?: readonly PositionedFormula[];
   readonly encryption?: PdfEncryptionOptions;
 }
+/**
+ * writePdf was handed a LayoutDocument from a page-selected read (one carrying `pageCount`). Such a document is a reading of part of a file, not a document to re-emit: its pages are a selection while its destinations, form widgets and outline still name source page indices, and the writer places pages by position, so writing it would point those references at the wrong pages or past the end. Thrown rather than writing a file whose links silently lie.
+ */
+declare class PdfPartialDocumentError extends Error {
+  readonly pageCount: number;
+  readonly selectedPageCount: number;
+  constructor(pageCount: number, selectedPageCount: number);
+}
 declare function writePdf(doc: LayoutDocument, options?: WritePdfOptions): Uint8Array<ArrayBuffer>;
 //#endregion
-export { WritePdfOptions, writePdf };
+export { PdfPartialDocumentError, WritePdfOptions, writePdf };

package/dist/write.js

@@ -68,7 +68,21 @@ function buildFontObjects(standardName, descriptorRef) {
 function codePointsOf(texts) {
 	return new Set(texts.flatMap((text) => [...text].map((character) => character.codePointAt(0))));
 }
+/**
+* writePdf was handed a LayoutDocument from a page-selected read (one carrying `pageCount`). Such a document is a reading of part of a file, not a document to re-emit: its pages are a selection while its destinations, form widgets and outline still name source page indices, and the writer places pages by position, so writing it would point those references at the wrong pages or past the end. Thrown rather than writing a file whose links silently lie.
+*/
+var PdfPartialDocumentError = class extends Error {
+	pageCount;
+	selectedPageCount;
+	constructor(pageCount, selectedPageCount) {
+		super(`this LayoutDocument holds ${String(selectedPageCount)} pages selected from a ${String(pageCount)}-page file (it carries pageCount, which only a page-selected read sets); its page references name pages of the source file, so it cannot be written as a document of its own`);
+		this.name = "PdfPartialDocumentError";
+		this.pageCount = pageCount;
+		this.selectedPageCount = selectedPageCount;
+	}
+};
 function writePdf(doc, options = {}) {
+	if (doc.pageCount !== void 0) throw new PdfPartialDocumentError(doc.pageCount, doc.pages.length);
 	const compress = options.compress ?? true;
 	const registry = options.fonts;
 	const measurer = createFontMeasurer(registry);
@@ -477,4 +491,4 @@ function writePdf(doc, options = {}) {
 	return writer.toBytes();
 }
 //#endregion
-export { writePdf };
+export { PdfPartialDocumentError, writePdf };

package/dist/xref.d.cts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.cjs";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.cjs";
 import { n as PdfDict } from "./objects-e2RS3-yT.cjs";
 //#region src/xref.d.ts
 interface XrefOffsetEntry {

package/dist/xref.d.ts

@@ -1,4 +1,4 @@
-import { i as PdfDiagnosticSink } from "./diagnostics-C9FxfZ6H.js";
+import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.js";
 import { n as PdfDict } from "./objects-e2RS3-yT.js";
 //#region src/xref.d.ts
 interface XrefOffsetEntry {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdf-codec",
-  "version": "5.3.32",
+  "version": "5.4.0",
   "description": "Hand-written, dependency-minimal PDF codec: parses arbitrary real-world PDFs and generates new ones, built on its own codec-owned LayoutDocument item model and Zod 4 codecs.",
   "type": "module",
   "repository": {

package/dist/diagnostics-C9FxfZ6H.d.cts

@@ -1,22 +0,0 @@
-//#region src/diagnostics.d.ts
-type PdfDiagnosticSeverity = "info" | "warning";
-interface PdfDiagnostic {
-  readonly code: string;
-  readonly severity: PdfDiagnosticSeverity;
-  readonly message: string;
-  readonly pageIndex?: number;
-}
-type PdfDiagnosticSink = (diagnostic: PdfDiagnostic) => void;
-declare const NOOP_DIAGNOSTIC_SINK: PdfDiagnosticSink;
-declare class PdfParseError extends Error {
-  readonly code: string;
-  constructor(code: string, message: string);
-}
-declare class PdfEncryptedError extends PdfParseError {
-  constructor(message?: string);
-}
-declare class PdfPasswordRequiredError extends PdfParseError {
-  constructor(message?: string);
-}
-//#endregion
-export { PdfEncryptedError as a, PdfDiagnosticSink as i, PdfDiagnostic as n, PdfParseError as o, PdfDiagnosticSeverity as r, PdfPasswordRequiredError as s, NOOP_DIAGNOSTIC_SINK as t };

package/dist/diagnostics-C9FxfZ6H.d.ts

@@ -1,22 +0,0 @@
-//#region src/diagnostics.d.ts
-type PdfDiagnosticSeverity = "info" | "warning";
-interface PdfDiagnostic {
-  readonly code: string;
-  readonly severity: PdfDiagnosticSeverity;
-  readonly message: string;
-  readonly pageIndex?: number;
-}
-type PdfDiagnosticSink = (diagnostic: PdfDiagnostic) => void;
-declare const NOOP_DIAGNOSTIC_SINK: PdfDiagnosticSink;
-declare class PdfParseError extends Error {
-  readonly code: string;
-  constructor(code: string, message: string);
-}
-declare class PdfEncryptedError extends PdfParseError {
-  constructor(message?: string);
-}
-declare class PdfPasswordRequiredError extends PdfParseError {
-  constructor(message?: string);
-}
-//#endregion
-export { PdfEncryptedError as a, PdfDiagnosticSink as i, PdfDiagnostic as n, PdfParseError as o, PdfDiagnosticSeverity as r, PdfPasswordRequiredError as s, NOOP_DIAGNOSTIC_SINK as t };