pdf-codec 5.4.0 → 5.5.1

package/README.md

@@ -93,7 +93,25 @@ An encrypted PDF that opens without a password decrypts transparently — no ext
 
 Both accept an optional `signal` (`AbortSignal`); `readPdf` additionally takes a `sink` (`PdfDiagnosticSink`, called once per recoverable parse diagnostic — see the three-tier failure policy under [Conventions](#conventions)), and `writePdf` an `onSubstitution` callback (called once per character not representable in a standard-14 font — see [Fidelity](#fidelity)).
 
-**Reading a subset of pages.** `readPdf(bytes, { pages: [0, 1, 2, -1] })` reads only the listed pages: zero-based indices into the page tree, a negative index counted from the end (`-1` is the last page). 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, and no embedded file is 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); an absent `attachments` therefore means "not read" whenever `pageCount` is set, which only a page-selected read does, so check `pageCount` before concluding a document has no attachments. The case this exists for is identifying a document from its first pages, or reading a code from its last page, inside a memory-capped runtime such as a Cloudflare Worker isolate, without paying for every page's content. What it still reads whole, because page references 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 (with its parent-tree diagnostics) and the `page-boxes` residue row. A destination a link states as a direct array is minted into `destinations` (as `dest1`, `dest2`, ...) only when its 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, each carrying its source position as `index` (read it through `sourcePageIndex(page, position)`, which falls back to the position on a full read), with the page tree's length as the document's `pageCount`; every document-level page reference keeps naming source indices, so a reference to a selected page resolves through `index`, and one to an unselected page names a page the result does not hold. A full read sets neither field, because there `pages.length` and each page's position already state them. An empty selection is valid and reads no page, which makes `{ pages: [] }` the cheapest way to learn a file's page count and metadata. An entry naming no page (outside `-pageCount` to `pageCount - 1`, or not an integer, `NaN` and the infinities included; `-0` is page 0) throws `PdfPageSelectionError` (a `PdfParseError` with code `pdf/page-out-of-range` or `pdf/page-index-not-integer`, carrying `pageIndex` and `pageCount`) before any page is read. A page-selected `LayoutDocument` is a reading of part of a file, not a document to re-emit: `writePdf` refuses one (any document carrying `pageCount`) with `PdfPartialDocumentError`, since it places pages by position and the references would point at the wrong pages.
+**Reading a subset of pages.** `readPdf(bytes, { pages: [0, 1, 2, -1] })` reads only the listed pages: zero-based indices into the page tree, a negative index counted from the end (`-1` is the last page). 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, and no embedded file is 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); an absent `attachments` therefore means "not read" whenever `pageCount` is set, which only a page-selected read does, so check `pageCount` before concluding a document has no attachments. The case this exists for is identifying a document from its first pages, or reading a code from its last page, inside a memory-capped runtime such as a Cloudflare Worker isolate, without paying for every page's content. What it still reads whole, because page references 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; every one of those but the page tree and metadata can be left out too, with `surfaces` (below). Two surfaces are built from page content and so cover selected pages only: the structure-ownership association an item's `structure` field names (with its parent-tree diagnostics) and the `page-boxes` residue row. A destination a link states as a direct array is minted into `destinations` (as `dest1`, `dest2`, ...) only when its page is interpreted, so an unselected page's direct link destinations are absent and a minted name depends on which pages were read (and on whether the outline was read, below); named destinations are unaffected. Duplicates collapse and the result's `pages` holds the selected pages in ascending document order, each carrying its source position as `index` (read it through `sourcePageIndex(page, position)`, which falls back to the position on a full read), with the page tree's length as the document's `pageCount`; every document-level page reference keeps naming source indices, so a reference to a selected page resolves through `index`, and one to an unselected page names a page the result does not hold. A full read sets neither field, because there `pages.length` and each page's position already state them. An empty selection is valid and reads no page, which makes `{ pages: [] }` the cheapest way to learn a file's page count and metadata. An entry naming no page (outside `-pageCount` to `pageCount - 1`, or not an integer, `NaN` and the infinities included; `-0` is page 0) throws `PdfPageSelectionError` (a `PdfParseError` with code `pdf/page-out-of-range` or `pdf/page-index-not-integer`, carrying `pageIndex` and `pageCount`) before any page is read. A page-selected `LayoutDocument` is a reading of part of a file, not a document to re-emit: `writePdf` refuses one (any document carrying `pageCount`) with `PdfPartialDocumentError`, since it places pages by position and the references would point at the wrong pages.
+
+**Leaving document-level surfaces out.** `readPdf(bytes, { surfaces: { structure: false, outline: false } })` reads the document without the surfaces turned off. `ReadPdfOptions.surfaces` is one object of independent booleans (`ReadPdfSurfaces`), one per surface, each read unless set to `false`, so omitting the setting reads everything exactly as before. It is independent of `pages`, applying to a full read and a page-selected read alike, and combined with a small selection it is what keeps identifying a document cheap: on a long tagged PDF the structure element tree and its `/ParentTree` can be most of what a page-selected read still parses, and `{ pages: [0, 1, 2, -1], surfaces: { outline: false, destinations: false, form: false, layers: false, structure: false, residue: false } }` reads nothing beyond opening the document (cross-reference table, trailer, catalog and any encryption dictionary), the page tree, metadata and those four pages. A surface turned off is never parsed (its part of the catalog is not walked, so a malformed outline, form, layer list or structure tree reports no diagnostic), its `LayoutDocument` field is absent whatever the file holds, and the result names it in `skippedSurfaces` (in the order `LayoutDocumentSurfaceSchema` lists them, absent when every surface was read). An absent `outline`, `destinations`, `form`, `layers`, `structure` or `source` therefore means "not read" whenever `skippedSurfaces` names it, so check `skippedSurfaces` before concluding a document has none, as with `pageCount` and attachments.
+
+Each surface, and what page items lose without it (everything else about every page item is exactly what a read with the surface on produces, apart from the renumbering a skipped outline causes):
+
+- `outline`: the `/Outlines` bookmark tree (`outline`). Page items do not depend on it, except through minted names. A destination stated as a direct array is named with the first unused `destN` in the order the reader meets it, and the outline is read before any page, so an outline entry's direct destination takes a lower number than any link's. Without the outline, the names minted for page links' direct destinations are renumbered and `destinations` loses the entries only the outline minted, while each link still resolves to the same target.
+
+- `destinations`: the named destinations of the catalog `/Dests` dictionary and the `/Names /Dests` name tree, and the registry links and outline entries name their targets through (`destinations`). Without it nothing can name an internal target, so a link whose target is internal (a `/Dest`, or a `/GoTo` action, whether it names a destination or states one directly) is left out of its page's items, and an outline entry, if the outline is read, carries no `destination`. A link to a URI is kept.
+
+- `form`: the AcroForm field tree (`form`). Page items do not depend on it, since a widget annotation is never a page item or annotation either way.
+
+- `layers`: optional content, the `/OCProperties` groups and their default visibility (`layers`). Without it no item carries a `layer`. The items themselves are all still read, so content the default configuration hides cannot be told from visible content, and a consumer that drops hidden-layer content (as documents.js's reconstruction does) keeps it.
+
+- `structure`: the `/StructTreeRoot` element tree and its `/ParentTree` ownership map (`structure`). Without it no item carries a `structure` owner, and the parent-tree diagnostics are not reported.
+
+- `residue`: the package-level residue rows (`source`), the per-page `page-boxes` row included. Page items do not depend on it, and `metadata` still reads the XMP packet it falls back to.
+
+A `LayoutDocument` read with any surface skipped is a reading with parts of the file deliberately unread, so `writePdf` refuses one (any document carrying `skippedSurfaces`) with `PdfSkippedSurfacesError`, which names the skipped surfaces; a document that is also page-selected reports `PdfPartialDocumentError` first.
 
 **Page boundaries: the crop box is the visible region** (ISO 32000-1 14.11.2). A page's reported `widthPt`/`heightPt` and coordinate frame come from its effective `/CropBox` — the rectangle a viewer displays and prints, inherited through the page tree like `/MediaBox` and defaulting to it — not from the media box: content an author placed outside the crop box (printer's marks, bleed, off-page slugs) is not visible and does not extract. Content wholly outside the crop box is dropped; content straddling the boundary keeps its original unclipped geometry (the item layer records what the file states — a viewer's clipping is a rendering fact, not source data); link annotations are anchored constructs rather than painted content and are never filtered, the same line the optional-content filter draws. The declared boundary rectangles a distinct crop box hides — plus `/BleedBox`/`/TrimBox`/`/ArtBox`, print-production facts with no field in the layout model — are quarantined verbatim as the `page-boxes` package-level residue row rather than silently dropped. A degenerate `/CropBox` (zero width or height) falls back to the media box with a `pdf/invalid-crop-box` warning.
 

package/dist/codec.d.cts

@@ -319,6 +319,14 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
     }>;
     xml: z.ZodString;
   }, z.core.$strict>>>;
+  skippedSurfaces: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+    structure: "structure";
+    destinations: "destinations";
+    outline: "outline";
+    layers: "layers";
+    form: "form";
+    residue: "residue";
+  }>>>;
 }, z.core.$strip>>;
 //#endregion
 export { PdfBytesSchema, pdfCodec };

package/dist/codec.d.ts

@@ -319,6 +319,14 @@ declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Arr
     }>;
     xml: z.ZodString;
   }, z.core.$strict>>>;
+  skippedSurfaces: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+    structure: "structure";
+    destinations: "destinations";
+    outline: "outline";
+    layers: "layers";
+    form: "form";
+    residue: "residue";
+  }>>>;
 }, z.core.$strip>>;
 //#endregion
 export { PdfBytesSchema, pdfCodec };

package/dist/index.cjs

@@ -17,6 +17,7 @@ const require_math_stretch = require("./math-stretch.cjs");
 const require_math_font = require("./math-font.cjs");
 const require_font_registry = require("./font-registry.cjs");
 const require_measure = require("./measure.cjs");
+const require_write_skipped_surfaces = require("./write-skipped-surfaces.cjs");
 const require_write = require("./write.cjs");
 const require_codec = require("./codec.cjs");
 const require_font_face = require("./font-face.cjs");
@@ -37,6 +38,7 @@ exports.LayoutAttachmentSchema = require_layout.LayoutAttachmentSchema;
 exports.LayoutDestinationSchema = require_layout.LayoutDestinationSchema;
 exports.LayoutDestinationTargetSchema = require_layout.LayoutDestinationTargetSchema;
 exports.LayoutDocumentSchema = require_layout.LayoutDocumentSchema;
+exports.LayoutDocumentSurfaceSchema = require_layout.LayoutDocumentSurfaceSchema;
 exports.LayoutEllipseSchema = require_layout.LayoutEllipseSchema;
 exports.LayoutFormFieldSchema = require_layout.LayoutFormFieldSchema;
 exports.LayoutFormWidgetSchema = require_layout.LayoutFormWidgetSchema;
@@ -63,6 +65,7 @@ exports.PdfPageSelectionError = require_diagnostics.PdfPageSelectionError;
 exports.PdfParseError = require_diagnostics.PdfParseError;
 exports.PdfPartialDocumentError = require_write.PdfPartialDocumentError;
 exports.PdfPasswordRequiredError = require_diagnostics.PdfPasswordRequiredError;
+exports.PdfSkippedSurfacesError = require_write_skipped_surfaces.PdfSkippedSurfacesError;
 exports.STANDARD_METRICS = require_afm_widths.STANDARD_METRICS;
 exports.assembleStretchyGlyph = require_math_stretch.assembleStretchyGlyph;
 exports.createFontMeasurer = require_measure.createFontMeasurer;

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { n as STANDARD_METRICS, r as StandardFontName, t as FontMetrics } from "./afm-widths-D0Lu9kLv.cjs";
 import { a as PdfEncryptedError, c as PdfPasswordRequiredError, i as PdfDiagnosticSink, n as PdfDiagnostic, o as PdfPageSelectionError, r as PdfDiagnosticSeverity, s as PdfParseError, t as NOOP_DIAGNOSTIC_SINK } from "./diagnostics-BkG_Ej2x.cjs";
-import { LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, sourcePageIndex } from "./layout.cjs";
+import { LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutDocumentSurface, LayoutDocumentSurfaceSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, sourcePageIndex } from "./layout.cjs";
 import { t as GlyphInkBounds } from "./glyph-bounds-BV_Z40KS.cjs";
 import { PdfBytesSchema, pdfCodec } from "./codec.cjs";
 import { n as EmbeddedFaceMetrics, r as EmbeddedFaceSubstitution, t as EmbeddedFace } from "./embedded-font-CqePfvrl.cjs";
@@ -17,8 +17,9 @@ import { Jpeg2000ProgressionOrder, Jpeg2000QuantizationStyle, Jpeg2000Transform
 import { Jpeg2000ParseError, Jpeg2000UnsupportedError } from "./image/jpeg2000-errors.cjs";
 import { Jpeg2000ComponentMetadata, Jpeg2000DecodeOptions, Jpeg2000Image, Jpeg2000Metadata, decodeJpeg2000, readJpeg2000Metadata } from "./image/jpeg2000.cjs";
 import { filterScanlines, unfilterScanlines } from "./image/png-filter.cjs";
-import { ReadPdfOptions, readPdf } from "./read.cjs";
+import { ReadPdfOptions, ReadPdfSurfaces, readPdf } from "./read.cjs";
 import { PdfPartialDocumentError, WritePdfOptions, writePdf } from "./write.cjs";
+import { PdfSkippedSurfacesError } from "./write-skipped-surfaces.cjs";
 import { a as MathGlyphPart, c as MathVariants, n as MathGlyphAssembly, o as MathGlyphVariant, r as MathGlyphConstruction } from "./math-table-gFNB8DmQ.cjs";
 import { a as scaleMathStretchConstruction, i as assembleStretchyGlyph, n as MathStretchOptions, r as MathStretchPlacement, t as MathStretchConstruction } from "./math-stretch-C2JanDAz.cjs";
 import { LoadedMathFont, MathFont, MathFontDescriptorMetrics, loadMathFont } from "./math-font.cjs";
@@ -27,4 +28,4 @@ import { DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_WORD_GAP_
 import { PageRasteriser, RasterDrawOp, RasterFillRectOp, RasterFillSpec, RasterImageOp, RasterMatrix, RasterPageGeometry, RasterPathOp, RasterPathSegment, RasterRegionPt, RasterStrokeSpec, RasterSubpath, RenderPdfPageOptions, renderPdfPage } from "./raster.cjs";
 import { FontRegistryOptions, FontSubstitution, MathAssembledGlyphs, MathBox, MathColor, MathFontMetrics, MathGlyphMetrics, MathGlyphPlacement, MathGlyphRun, MathLayoutItem, MathRule, MathStretchAxis, MathStretchGlyph, MathStretchResult, MathStroke, Point, PositionedFormula, ProvidedFont, StyledFragment, StyledRun, TextMeasurer, UnderlineMetrics, WrapOptions, WrappedLine } from "document-schema.js";
 export * from "byte-codec";
-export { type CcittFaxImage, type CcittFaxOptions, DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_VERTICAL_METRIC_POLICY, DEFAULT_WORD_GAP_EM, type EmbeddedFace, type EmbeddedFaceMetrics, type EmbeddedFaceSubstitution, type FontFace, FontFaceParseError, type FontMeasurerOptions, type FontMetrics, type FontRegistry, type FontRegistryOptions, type FontSubstitution, type GlyphInkBounds, type Jbig2DecodeOptions, type Jbig2Image, Jbig2ParseError, Jbig2UnsupportedError, type Jp2ChannelDefinition, type Jp2ColourSpace, type Jp2Container, type Jp2ImageHeader, type Jpeg2000ComponentMetadata, type Jpeg2000DecodeOptions, type Jpeg2000Image, type Jpeg2000Metadata, Jpeg2000ParseError, type Jpeg2000ProgressionOrder, type Jpeg2000QuantizationStyle, type Jpeg2000Transform, Jpeg2000UnsupportedError, LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, type LoadedMathFont, type MathAssembledGlyphs, type MathBox, type MathColor, type MathFont, type MathFontDescriptorMetrics, type MathFontMetrics, type MathGlyphAssembly, type MathGlyphConstruction, type MathGlyphMetrics, type MathGlyphPart, type MathGlyphPlacement, type MathGlyphRun, type MathGlyphVariant, type MathLayoutItem, type MathRule, type MathStretchAxis, type MathStretchConstruction, type MathStretchGlyph, type MathStretchOptions, type MathStretchPlacement, type MathStretchResult, type MathStroke, type MathVariants, NOOP_DIAGNOSTIC_SINK, type PageRasteriser, PdfBytesSchema, type PdfDiagnostic, type PdfDiagnosticSeverity, type PdfDiagnosticSink, PdfEncryptedError, PdfEncryptionError, type PdfEncryptionOptions, type PdfEncryptionPermissions, type PdfEncryptionScheme, PdfPageSelectionError, PdfParseError, PdfPartialDocumentError, PdfPasswordRequiredError, type PdfTextBox, type PdfTextGroupingOptions, type PdfTextLine, type PdfTextRunGeometry, type PdfTextWord, type PdfWordSeparator, type Point, type PositionedFormula, type ProvidedFont, type RasterDrawOp, type RasterFillRectOp, type RasterFillSpec, type RasterImageOp, type RasterMatrix, type RasterPageGeometry, type RasterPathOp, type RasterPathSegment, type RasterRegionPt, type RasterStrokeSpec, type RasterSubpath, type ReadPdfOptions, type RenderPdfPageOptions, type ResolvedFace, type ResolvedFont, STANDARD_METRICS, type StandardFontMeasurerOptions, type StandardFontName, type StyledFragment, type StyledRun, type TextMeasurer, type UnderlineMetrics, type VerticalMetricPolicy, type WinAnsiSubstitution, type WrapOptions, type WrappedLine, type WritePdfOptions, assembleStretchyGlyph, createFontMeasurer, createFontRegistry, createStandardFontMeasurer, decodeCcittFax, decodeJbig2Embedded, decodeJpeg2000, filterScanlines, groupPdfTextRuns, loadMathFont, looksLikeBareCodestream, parseJp2Container, pdfCodec, readFontFace, readJpeg2000Metadata, readPdf, renderPdfPage, resolveFaceWithRegistry, resolveStandardFont, runGapPt, runsShareBaseline, scaleMathStretchConstruction, sourcePageIndex, unfilterScanlines, writePdf };
+export { type CcittFaxImage, type CcittFaxOptions, DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_VERTICAL_METRIC_POLICY, DEFAULT_WORD_GAP_EM, type EmbeddedFace, type EmbeddedFaceMetrics, type EmbeddedFaceSubstitution, type FontFace, FontFaceParseError, type FontMeasurerOptions, type FontMetrics, type FontRegistry, type FontRegistryOptions, type FontSubstitution, type GlyphInkBounds, type Jbig2DecodeOptions, type Jbig2Image, Jbig2ParseError, Jbig2UnsupportedError, type Jp2ChannelDefinition, type Jp2ColourSpace, type Jp2Container, type Jp2ImageHeader, type Jpeg2000ComponentMetadata, type Jpeg2000DecodeOptions, type Jpeg2000Image, type Jpeg2000Metadata, Jpeg2000ParseError, type Jpeg2000ProgressionOrder, type Jpeg2000QuantizationStyle, type Jpeg2000Transform, Jpeg2000UnsupportedError, LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutDocumentSurface, LayoutDocumentSurfaceSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, type LoadedMathFont, type MathAssembledGlyphs, type MathBox, type MathColor, type MathFont, type MathFontDescriptorMetrics, type MathFontMetrics, type MathGlyphAssembly, type MathGlyphConstruction, type MathGlyphMetrics, type MathGlyphPart, type MathGlyphPlacement, type MathGlyphRun, type MathGlyphVariant, type MathLayoutItem, type MathRule, type MathStretchAxis, type MathStretchConstruction, type MathStretchGlyph, type MathStretchOptions, type MathStretchPlacement, type MathStretchResult, type MathStroke, type MathVariants, NOOP_DIAGNOSTIC_SINK, type PageRasteriser, PdfBytesSchema, type PdfDiagnostic, type PdfDiagnosticSeverity, type PdfDiagnosticSink, PdfEncryptedError, PdfEncryptionError, type PdfEncryptionOptions, type PdfEncryptionPermissions, type PdfEncryptionScheme, PdfPageSelectionError, PdfParseError, PdfPartialDocumentError, PdfPasswordRequiredError, PdfSkippedSurfacesError, type PdfTextBox, type PdfTextGroupingOptions, type PdfTextLine, type PdfTextRunGeometry, type PdfTextWord, type PdfWordSeparator, type Point, type PositionedFormula, type ProvidedFont, type RasterDrawOp, type RasterFillRectOp, type RasterFillSpec, type RasterImageOp, type RasterMatrix, type RasterPageGeometry, type RasterPathOp, type RasterPathSegment, type RasterRegionPt, type RasterStrokeSpec, type RasterSubpath, type ReadPdfOptions, type ReadPdfSurfaces, type RenderPdfPageOptions, type ResolvedFace, type ResolvedFont, STANDARD_METRICS, type StandardFontMeasurerOptions, type StandardFontName, type StyledFragment, type StyledRun, type TextMeasurer, type UnderlineMetrics, type VerticalMetricPolicy, type WinAnsiSubstitution, type WrapOptions, type WrappedLine, type WritePdfOptions, assembleStretchyGlyph, createFontMeasurer, createFontRegistry, createStandardFontMeasurer, decodeCcittFax, decodeJbig2Embedded, decodeJpeg2000, filterScanlines, groupPdfTextRuns, loadMathFont, looksLikeBareCodestream, parseJp2Container, pdfCodec, readFontFace, readJpeg2000Metadata, readPdf, renderPdfPage, resolveFaceWithRegistry, resolveStandardFont, runGapPt, runsShareBaseline, scaleMathStretchConstruction, sourcePageIndex, unfilterScanlines, writePdf };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { n as STANDARD_METRICS, r as StandardFontName, t as FontMetrics } from "./afm-widths-D0Lu9kLv.js";
 import { a as PdfEncryptedError, c as PdfPasswordRequiredError, i as PdfDiagnosticSink, n as PdfDiagnostic, o as PdfPageSelectionError, r as PdfDiagnosticSeverity, s as PdfParseError, t as NOOP_DIAGNOSTIC_SINK } from "./diagnostics-BkG_Ej2x.js";
-import { LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, sourcePageIndex } from "./layout.js";
+import { LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutDocumentSurface, LayoutDocumentSurfaceSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, sourcePageIndex } from "./layout.js";
 import { t as GlyphInkBounds } from "./glyph-bounds-BV_Z40KS.js";
 import { PdfBytesSchema, pdfCodec } from "./codec.js";
 import { n as EmbeddedFaceMetrics, r as EmbeddedFaceSubstitution, t as EmbeddedFace } from "./embedded-font-CQZbTTDM.js";
@@ -17,8 +17,9 @@ import { Jpeg2000ProgressionOrder, Jpeg2000QuantizationStyle, Jpeg2000Transform
 import { Jpeg2000ParseError, Jpeg2000UnsupportedError } from "./image/jpeg2000-errors.js";
 import { Jpeg2000ComponentMetadata, Jpeg2000DecodeOptions, Jpeg2000Image, Jpeg2000Metadata, decodeJpeg2000, readJpeg2000Metadata } from "./image/jpeg2000.js";
 import { filterScanlines, unfilterScanlines } from "./image/png-filter.js";
-import { ReadPdfOptions, readPdf } from "./read.js";
+import { ReadPdfOptions, ReadPdfSurfaces, readPdf } from "./read.js";
 import { PdfPartialDocumentError, WritePdfOptions, writePdf } from "./write.js";
+import { PdfSkippedSurfacesError } from "./write-skipped-surfaces.js";
 import { a as MathGlyphPart, c as MathVariants, n as MathGlyphAssembly, o as MathGlyphVariant, r as MathGlyphConstruction } from "./math-table-DhPrNoPa.js";
 import { a as scaleMathStretchConstruction, i as assembleStretchyGlyph, n as MathStretchOptions, r as MathStretchPlacement, t as MathStretchConstruction } from "./math-stretch-BbC2o4Br.js";
 import { LoadedMathFont, MathFont, MathFontDescriptorMetrics, loadMathFont } from "./math-font.js";
@@ -27,4 +28,4 @@ import { DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_WORD_GAP_
 import { PageRasteriser, RasterDrawOp, RasterFillRectOp, RasterFillSpec, RasterImageOp, RasterMatrix, RasterPageGeometry, RasterPathOp, RasterPathSegment, RasterRegionPt, RasterStrokeSpec, RasterSubpath, RenderPdfPageOptions, renderPdfPage } from "./raster.js";
 import { FontRegistryOptions, FontSubstitution, MathAssembledGlyphs, MathBox, MathColor, MathFontMetrics, MathGlyphMetrics, MathGlyphPlacement, MathGlyphRun, MathLayoutItem, MathRule, MathStretchAxis, MathStretchGlyph, MathStretchResult, MathStroke, Point, PositionedFormula, ProvidedFont, StyledFragment, StyledRun, TextMeasurer, UnderlineMetrics, WrapOptions, WrappedLine } from "document-schema.js";
 export * from "byte-codec";
-export { type CcittFaxImage, type CcittFaxOptions, DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_VERTICAL_METRIC_POLICY, DEFAULT_WORD_GAP_EM, type EmbeddedFace, type EmbeddedFaceMetrics, type EmbeddedFaceSubstitution, type FontFace, FontFaceParseError, type FontMeasurerOptions, type FontMetrics, type FontRegistry, type FontRegistryOptions, type FontSubstitution, type GlyphInkBounds, type Jbig2DecodeOptions, type Jbig2Image, Jbig2ParseError, Jbig2UnsupportedError, type Jp2ChannelDefinition, type Jp2ColourSpace, type Jp2Container, type Jp2ImageHeader, type Jpeg2000ComponentMetadata, type Jpeg2000DecodeOptions, type Jpeg2000Image, type Jpeg2000Metadata, Jpeg2000ParseError, type Jpeg2000ProgressionOrder, type Jpeg2000QuantizationStyle, type Jpeg2000Transform, Jpeg2000UnsupportedError, LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, type LoadedMathFont, type MathAssembledGlyphs, type MathBox, type MathColor, type MathFont, type MathFontDescriptorMetrics, type MathFontMetrics, type MathGlyphAssembly, type MathGlyphConstruction, type MathGlyphMetrics, type MathGlyphPart, type MathGlyphPlacement, type MathGlyphRun, type MathGlyphVariant, type MathLayoutItem, type MathRule, type MathStretchAxis, type MathStretchConstruction, type MathStretchGlyph, type MathStretchOptions, type MathStretchPlacement, type MathStretchResult, type MathStroke, type MathVariants, NOOP_DIAGNOSTIC_SINK, type PageRasteriser, PdfBytesSchema, type PdfDiagnostic, type PdfDiagnosticSeverity, type PdfDiagnosticSink, PdfEncryptedError, PdfEncryptionError, type PdfEncryptionOptions, type PdfEncryptionPermissions, type PdfEncryptionScheme, PdfPageSelectionError, PdfParseError, PdfPartialDocumentError, PdfPasswordRequiredError, type PdfTextBox, type PdfTextGroupingOptions, type PdfTextLine, type PdfTextRunGeometry, type PdfTextWord, type PdfWordSeparator, type Point, type PositionedFormula, type ProvidedFont, type RasterDrawOp, type RasterFillRectOp, type RasterFillSpec, type RasterImageOp, type RasterMatrix, type RasterPageGeometry, type RasterPathOp, type RasterPathSegment, type RasterRegionPt, type RasterStrokeSpec, type RasterSubpath, type ReadPdfOptions, type RenderPdfPageOptions, type ResolvedFace, type ResolvedFont, STANDARD_METRICS, type StandardFontMeasurerOptions, type StandardFontName, type StyledFragment, type StyledRun, type TextMeasurer, type UnderlineMetrics, type VerticalMetricPolicy, type WinAnsiSubstitution, type WrapOptions, type WrappedLine, type WritePdfOptions, assembleStretchyGlyph, createFontMeasurer, createFontRegistry, createStandardFontMeasurer, decodeCcittFax, decodeJbig2Embedded, decodeJpeg2000, filterScanlines, groupPdfTextRuns, loadMathFont, looksLikeBareCodestream, parseJp2Container, pdfCodec, readFontFace, readJpeg2000Metadata, readPdf, renderPdfPage, resolveFaceWithRegistry, resolveStandardFont, runGapPt, runsShareBaseline, scaleMathStretchConstruction, sourcePageIndex, unfilterScanlines, writePdf };
+export { type CcittFaxImage, type CcittFaxOptions, DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_VERTICAL_METRIC_POLICY, DEFAULT_WORD_GAP_EM, type EmbeddedFace, type EmbeddedFaceMetrics, type EmbeddedFaceSubstitution, type FontFace, FontFaceParseError, type FontMeasurerOptions, type FontMetrics, type FontRegistry, type FontRegistryOptions, type FontSubstitution, type GlyphInkBounds, type Jbig2DecodeOptions, type Jbig2Image, Jbig2ParseError, Jbig2UnsupportedError, type Jp2ChannelDefinition, type Jp2ColourSpace, type Jp2Container, type Jp2ImageHeader, type Jpeg2000ComponentMetadata, type Jpeg2000DecodeOptions, type Jpeg2000Image, type Jpeg2000Metadata, Jpeg2000ParseError, type Jpeg2000ProgressionOrder, type Jpeg2000QuantizationStyle, type Jpeg2000Transform, Jpeg2000UnsupportedError, LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutDocumentSurface, LayoutDocumentSurfaceSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, type LoadedMathFont, type MathAssembledGlyphs, type MathBox, type MathColor, type MathFont, type MathFontDescriptorMetrics, type MathFontMetrics, type MathGlyphAssembly, type MathGlyphConstruction, type MathGlyphMetrics, type MathGlyphPart, type MathGlyphPlacement, type MathGlyphRun, type MathGlyphVariant, type MathLayoutItem, type MathRule, type MathStretchAxis, type MathStretchConstruction, type MathStretchGlyph, type MathStretchOptions, type MathStretchPlacement, type MathStretchResult, type MathStroke, type MathVariants, NOOP_DIAGNOSTIC_SINK, type PageRasteriser, PdfBytesSchema, type PdfDiagnostic, type PdfDiagnosticSeverity, type PdfDiagnosticSink, PdfEncryptedError, PdfEncryptionError, type PdfEncryptionOptions, type PdfEncryptionPermissions, type PdfEncryptionScheme, PdfPageSelectionError, PdfParseError, PdfPartialDocumentError, PdfPasswordRequiredError, PdfSkippedSurfacesError, type PdfTextBox, type PdfTextGroupingOptions, type PdfTextLine, type PdfTextRunGeometry, type PdfTextWord, type PdfWordSeparator, type Point, type PositionedFormula, type ProvidedFont, type RasterDrawOp, type RasterFillRectOp, type RasterFillSpec, type RasterImageOp, type RasterMatrix, type RasterPageGeometry, type RasterPathOp, type RasterPathSegment, type RasterRegionPt, type RasterStrokeSpec, type RasterSubpath, type ReadPdfOptions, type ReadPdfSurfaces, type RenderPdfPageOptions, type ResolvedFace, type ResolvedFont, STANDARD_METRICS, type StandardFontMeasurerOptions, type StandardFontName, type StyledFragment, type StyledRun, type TextMeasurer, type UnderlineMetrics, type VerticalMetricPolicy, type WinAnsiSubstitution, type WrapOptions, type WrappedLine, type WritePdfOptions, assembleStretchyGlyph, createFontMeasurer, createFontRegistry, createStandardFontMeasurer, decodeCcittFax, decodeJbig2Embedded, decodeJpeg2000, filterScanlines, groupPdfTextRuns, loadMathFont, looksLikeBareCodestream, parseJp2Container, pdfCodec, readFontFace, readJpeg2000Metadata, readPdf, renderPdfPage, resolveFaceWithRegistry, resolveStandardFont, runGapPt, runsShareBaseline, scaleMathStretchConstruction, sourcePageIndex, unfilterScanlines, writePdf };

package/dist/index.js

@@ -6,7 +6,7 @@ import { filterScanlines, unfilterScanlines } from "./image/png-filter.js";
 import { Jpeg2000ParseError, Jpeg2000UnsupportedError } from "./image/jpeg2000-errors.js";
 import { looksLikeBareCodestream, parseJp2Container } from "./image/jp2-boxes.js";
 import { decodeJpeg2000, readJpeg2000Metadata } from "./image/jpeg2000.js";
-import { 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 } from "./layout.js";
+import { LAYOUT_FORMAT_VERSION, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachmentSchema, LayoutDestinationSchema, LayoutDestinationTargetSchema, LayoutDocumentSchema, LayoutDocumentSurfaceSchema, LayoutEllipseSchema, LayoutFormFieldSchema, LayoutFormWidgetSchema, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLinkSchema, LayoutItemSchema, LayoutLayerSchema, LayoutLineSchema, LayoutLinkSchema, LayoutOutlineItemSchema, LayoutPageSchema, LayoutPathSchema, LayoutPathSegmentSchema, LayoutRectSchema, LayoutStructureElementSchema, LayoutSubpathSchema, LayoutTextSchema, sourcePageIndex } from "./layout.js";
 import { NOOP_DIAGNOSTIC_SINK, PdfEncryptedError, PdfPageSelectionError, PdfParseError, PdfPasswordRequiredError } from "./diagnostics.js";
 import { resolveStandardFont } from "./fonts.js";
 import { DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_WORD_GAP_EM, groupPdfTextRuns, runGapPt, runsShareBaseline } from "./text-group.js";
@@ -16,9 +16,10 @@ import { assembleStretchyGlyph, scaleMathStretchConstruction } from "./math-stre
 import { loadMathFont } from "./math-font.js";
 import { createFontRegistry, resolveFaceWithRegistry } from "./font-registry.js";
 import { DEFAULT_VERTICAL_METRIC_POLICY, createFontMeasurer, createStandardFontMeasurer } from "./measure.js";
+import { PdfSkippedSurfacesError } from "./write-skipped-surfaces.js";
 import { PdfPartialDocumentError, writePdf } from "./write.js";
 import { PdfBytesSchema, pdfCodec } from "./codec.js";
 import { FontFaceParseError, readFontFace } from "./font-face.js";
 import { r as renderPdfPage } from "./raster-DUmwfi3F.js";
 export * from "byte-codec";
-export { DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_VERTICAL_METRIC_POLICY, DEFAULT_WORD_GAP_EM, FontFaceParseError, Jbig2ParseError, Jbig2UnsupportedError, Jpeg2000ParseError, Jpeg2000UnsupportedError, 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, NOOP_DIAGNOSTIC_SINK, PdfBytesSchema, PdfEncryptedError, PdfEncryptionError, PdfPageSelectionError, PdfParseError, PdfPartialDocumentError, PdfPasswordRequiredError, STANDARD_METRICS, assembleStretchyGlyph, createFontMeasurer, createFontRegistry, createStandardFontMeasurer, decodeCcittFax, decodeJbig2Embedded, decodeJpeg2000, filterScanlines, groupPdfTextRuns, loadMathFont, looksLikeBareCodestream, parseJp2Container, pdfCodec, readFontFace, readJpeg2000Metadata, readPdf, renderPdfPage, resolveFaceWithRegistry, resolveStandardFont, runGapPt, runsShareBaseline, scaleMathStretchConstruction, sourcePageIndex, unfilterScanlines, writePdf };
+export { DEFAULT_BASELINE_TOLERANCE_EM, DEFAULT_COLUMN_GAP_EM, DEFAULT_VERTICAL_METRIC_POLICY, DEFAULT_WORD_GAP_EM, FontFaceParseError, Jbig2ParseError, Jbig2UnsupportedError, Jpeg2000ParseError, Jpeg2000UnsupportedError, LAYOUT_FORMAT_VERSION, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachmentSchema, LayoutDestinationSchema, LayoutDestinationTargetSchema, LayoutDocumentSchema, LayoutDocumentSurfaceSchema, LayoutEllipseSchema, LayoutFormFieldSchema, LayoutFormWidgetSchema, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLinkSchema, LayoutItemSchema, LayoutLayerSchema, LayoutLineSchema, LayoutLinkSchema, LayoutOutlineItemSchema, LayoutPageSchema, LayoutPathSchema, LayoutPathSegmentSchema, LayoutRectSchema, LayoutStructureElementSchema, LayoutSubpathSchema, LayoutTextSchema, NOOP_DIAGNOSTIC_SINK, PdfBytesSchema, PdfEncryptedError, PdfEncryptionError, PdfPageSelectionError, PdfParseError, PdfPartialDocumentError, PdfPasswordRequiredError, PdfSkippedSurfacesError, STANDARD_METRICS, assembleStretchyGlyph, createFontMeasurer, createFontRegistry, createStandardFontMeasurer, decodeCcittFax, decodeJbig2Embedded, decodeJpeg2000, filterScanlines, groupPdfTextRuns, loadMathFont, looksLikeBareCodestream, parseJp2Container, pdfCodec, readFontFace, readJpeg2000Metadata, readPdf, renderPdfPage, resolveFaceWithRegistry, resolveStandardFont, runGapPt, runsShareBaseline, scaleMathStretchConstruction, sourcePageIndex, unfilterScanlines, writePdf };

package/dist/layout.cjs

@@ -269,6 +269,17 @@ const LayoutStructureElementSchema = zod.z.lazy(() => zod.z.object({
 	actualText: zod.z.string().optional(),
 	children: zod.z.array(LayoutStructureElementSchema)
 }));
+/**
+* The document-level surfaces a read can leave out (`ReadPdfOptions.surfaces`), each named by the `LayoutDocument` field it fills: `outline`, `destinations`, `form`, `layers` and `structure` are those fields, and `residue` is the package-level `source` channel. A `LayoutDocument` lists the ones its read skipped in `skippedSurfaces`.
+*/
+const LayoutDocumentSurfaceSchema = zod.z.enum([
+	"outline",
+	"destinations",
+	"form",
+	"layers",
+	"structure",
+	"residue"
+]);
 const LayoutDocumentSchema = zod.z.object({
 	formatVersion: zod.z.literal(1),
 	metadata: document_schema_js.LayoutMetadataSchema,
@@ -281,7 +292,8 @@ const LayoutDocumentSchema = zod.z.object({
 	layers: zod.z.array(LayoutLayerSchema).optional(),
 	structure: zod.z.array(LayoutStructureElementSchema).optional(),
 	form: zod.z.array(LayoutFormFieldSchema).optional(),
-	source: zod.z.record(zod.z.string(), document_schema_js.SourceResidueSchema).optional()
+	source: zod.z.record(zod.z.string(), document_schema_js.SourceResidueSchema).optional(),
+	skippedSurfaces: zod.z.array(LayoutDocumentSurfaceSchema).min(1).optional()
 });
 //#endregion
 exports.LAYOUT_FORMAT_VERSION = LAYOUT_FORMAT_VERSION;
@@ -291,6 +303,7 @@ exports.LayoutAttachmentSchema = LayoutAttachmentSchema;
 exports.LayoutDestinationSchema = LayoutDestinationSchema;
 exports.LayoutDestinationTargetSchema = LayoutDestinationTargetSchema;
 exports.LayoutDocumentSchema = LayoutDocumentSchema;
+exports.LayoutDocumentSurfaceSchema = LayoutDocumentSurfaceSchema;
 exports.LayoutEllipseSchema = LayoutEllipseSchema;
 exports.LayoutFormFieldSchema = LayoutFormFieldSchema;
 exports.LayoutFormWidgetSchema = LayoutFormWidgetSchema;

package/dist/layout.d.cts

@@ -784,6 +784,18 @@ interface LayoutStructureElement {
   readonly actualText?: string;
   readonly children: readonly LayoutStructureElement[];
 }
+/**
+ * The document-level surfaces a read can leave out (`ReadPdfOptions.surfaces`), each named by the `LayoutDocument` field it fills: `outline`, `destinations`, `form`, `layers` and `structure` are those fields, and `residue` is the package-level `source` channel. A `LayoutDocument` lists the ones its read skipped in `skippedSurfaces`.
+ */
+declare const LayoutDocumentSurfaceSchema: z.ZodEnum<{
+  structure: "structure";
+  destinations: "destinations";
+  outline: "outline";
+  layers: "layers";
+  form: "form";
+  residue: "residue";
+}>;
+type LayoutDocumentSurface = z.infer<typeof LayoutDocumentSurfaceSchema>;
 declare const LayoutDocumentSchema: z.ZodObject<{
   formatVersion: z.ZodLiteral<1>;
   metadata: z.ZodObject<{
@@ -1101,7 +1113,15 @@ declare const LayoutDocumentSchema: z.ZodObject<{
     }>;
     xml: z.ZodString;
   }, z.core.$strict>>>;
+  skippedSurfaces: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+    structure: "structure";
+    destinations: "destinations";
+    outline: "outline";
+    layers: "layers";
+    form: "form";
+    residue: "residue";
+  }>>>;
 }, z.core.$strip>;
 type LayoutDocument = z.infer<typeof LayoutDocumentSchema>;
 //#endregion
-export { LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, sourcePageIndex };
+export { LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutDocumentSurface, LayoutDocumentSurfaceSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, sourcePageIndex };

package/dist/layout.d.ts

@@ -784,6 +784,18 @@ interface LayoutStructureElement {
   readonly actualText?: string;
   readonly children: readonly LayoutStructureElement[];
 }
+/**
+ * The document-level surfaces a read can leave out (`ReadPdfOptions.surfaces`), each named by the `LayoutDocument` field it fills: `outline`, `destinations`, `form`, `layers` and `structure` are those fields, and `residue` is the package-level `source` channel. A `LayoutDocument` lists the ones its read skipped in `skippedSurfaces`.
+ */
+declare const LayoutDocumentSurfaceSchema: z.ZodEnum<{
+  structure: "structure";
+  destinations: "destinations";
+  outline: "outline";
+  layers: "layers";
+  form: "form";
+  residue: "residue";
+}>;
+type LayoutDocumentSurface = z.infer<typeof LayoutDocumentSurfaceSchema>;
 declare const LayoutDocumentSchema: z.ZodObject<{
   formatVersion: z.ZodLiteral<1>;
   metadata: z.ZodObject<{
@@ -1101,7 +1113,15 @@ declare const LayoutDocumentSchema: z.ZodObject<{
     }>;
     xml: z.ZodString;
   }, z.core.$strict>>>;
+  skippedSurfaces: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+    structure: "structure";
+    destinations: "destinations";
+    outline: "outline";
+    layers: "layers";
+    form: "form";
+    residue: "residue";
+  }>>>;
 }, z.core.$strip>;
 type LayoutDocument = z.infer<typeof LayoutDocumentSchema>;
 //#endregion
-export { LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, sourcePageIndex };
+export { LAYOUT_FORMAT_VERSION, LayoutAnnotation, LayoutAnnotationQuad, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachment, LayoutAttachmentSchema, LayoutDestination, LayoutDestinationSchema, LayoutDestinationTarget, LayoutDestinationTargetSchema, LayoutDocument, LayoutDocumentSchema, LayoutDocumentSurface, LayoutDocumentSurfaceSchema, LayoutEllipse, LayoutEllipseSchema, LayoutFormField, LayoutFormFieldSchema, LayoutFormWidget, LayoutFormWidgetSchema, LayoutImage, LayoutImageAsset, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLink, LayoutInternalLinkSchema, LayoutItem, LayoutItemSchema, LayoutLayer, LayoutLayerSchema, LayoutLine, LayoutLineSchema, LayoutLink, LayoutLinkSchema, LayoutOutlineItem, LayoutOutlineItemSchema, LayoutPage, LayoutPageSchema, LayoutPath, LayoutPathSchema, LayoutPathSegment, LayoutPathSegmentSchema, LayoutRect, LayoutRectSchema, LayoutStructureElement, LayoutStructureElementSchema, LayoutSubpath, LayoutSubpathSchema, LayoutText, LayoutTextSchema, sourcePageIndex };

package/dist/layout.js

@@ -268,6 +268,17 @@ const LayoutStructureElementSchema = z.lazy(() => z.object({
 	actualText: z.string().optional(),
 	children: z.array(LayoutStructureElementSchema)
 }));
+/**
+* The document-level surfaces a read can leave out (`ReadPdfOptions.surfaces`), each named by the `LayoutDocument` field it fills: `outline`, `destinations`, `form`, `layers` and `structure` are those fields, and `residue` is the package-level `source` channel. A `LayoutDocument` lists the ones its read skipped in `skippedSurfaces`.
+*/
+const LayoutDocumentSurfaceSchema = z.enum([
+	"outline",
+	"destinations",
+	"form",
+	"layers",
+	"structure",
+	"residue"
+]);
 const LayoutDocumentSchema = z.object({
 	formatVersion: z.literal(1),
 	metadata: LayoutMetadataSchema,
@@ -280,7 +291,8 @@ const LayoutDocumentSchema = z.object({
 	layers: z.array(LayoutLayerSchema).optional(),
 	structure: z.array(LayoutStructureElementSchema).optional(),
 	form: z.array(LayoutFormFieldSchema).optional(),
-	source: z.record(z.string(), SourceResidueSchema).optional()
+	source: z.record(z.string(), SourceResidueSchema).optional(),
+	skippedSurfaces: z.array(LayoutDocumentSurfaceSchema).min(1).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, sourcePageIndex };
+export { LAYOUT_FORMAT_VERSION, LayoutAnnotationQuadSchema, LayoutAnnotationSchema, LayoutAttachmentSchema, LayoutDestinationSchema, LayoutDestinationTargetSchema, LayoutDocumentSchema, LayoutDocumentSurfaceSchema, LayoutEllipseSchema, LayoutFormFieldSchema, LayoutFormWidgetSchema, LayoutImageAssetSchema, LayoutImageSchema, LayoutInternalLinkSchema, LayoutItemSchema, LayoutLayerSchema, LayoutLineSchema, LayoutLinkSchema, LayoutOutlineItemSchema, LayoutPageSchema, LayoutPathSchema, LayoutPathSegmentSchema, LayoutRectSchema, LayoutStructureElementSchema, LayoutSubpathSchema, LayoutTextSchema, sourcePageIndex };

package/dist/read.cjs

@@ -12,7 +12,7 @@ const require_form = require("./form.cjs");
 const require_xmp = require("./xmp.cjs");
 const require_optional_content = require("./optional-content.cjs");
 const require_structure = require("./structure.cjs");
-require("./layout.cjs");
+const require_layout = require("./layout.cjs");
 const require_diagnostics = require("./diagnostics.cjs");
 const require_document = require("./document.cjs");
 const require_util_abort = require("./util/abort.cjs");
@@ -20,6 +20,13 @@ 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 skippedSurfacesOf(surfaces) {
+	return require_layout.LayoutDocumentSurfaceSchema.options.filter((surface) => surfaces?.[surface] === false);
+}
+const UNREAD_DESTINATION_REGISTRY = {
+	entries: [],
+	intern: () => void 0
+};
 function resolvePageSelection(selection, pageCount) {
 	const resolved = /* @__PURE__ */ new Set();
 	for (const requested of selection) {
@@ -55,25 +62,27 @@ function readPdf(bytes, options) {
 	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 skippedSurfaces = skippedSurfacesOf(options?.surfaces);
+	const reads = (surface) => !skippedSurfaces.includes(surface);
+	const destinationRegistry = reads("destinations") ? require_navigation.createDestinationRegistry(doc.catalog, doc, (obj) => doc.pageIndex(obj), sink) : UNREAD_DESTINATION_REGISTRY;
+	const outline = reads("outline") ? require_navigation.readOutline(doc.catalog, destinationRegistry, doc, sink) : void 0;
 	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, (index) => selection === void 0 || selection.has(index), doc, sink);
-	const source = readDocumentResidue(doc, sink);
+	const optionalContent = reads("layers") ? require_optional_content.readOptionalContent(doc.catalog, doc, sink) : void 0;
+	const form = reads("form") ? require_form.readAcroForm(doc.catalog, doc, (obj) => doc.pageIndex(obj), sink) : void 0;
+	const structure = reads("structure") ? require_structure.readStructure(doc.catalog, pageDicts, (index) => selection === void 0 || selection.has(index), doc, sink) : void 0;
+	const source = reads("residue") ? readDocumentResidue(doc, sink) : void 0;
 	const pageBoxRows = [];
 	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);
+		const read = readPage(index, pageDict, doc, fontResolver, images, imageIdCache, destinationRegistry, optionalContent?.layerNameOf ?? noLayerName, structure?.ownerOf ?? noStructureOwner, sink);
 		if (read.boxRow !== void 0) pageBoxRows.push(read.boxRow);
 		return [selection === void 0 ? read.page : {
 			...read.page,
 			index
 		}];
 	});
-	if (pageBoxRows.length > 0) source["page-boxes"] = {
+	if (source !== void 0 && pageBoxRows.length > 0) source["page-boxes"] = {
 		format: "pdf",
 		xml: require_serialize.serializeObjectToText(require_objects.pdfArray(pageBoxRows))
 	};
@@ -84,14 +93,17 @@ function readPdf(bytes, options) {
 		...selection !== void 0 ? { pageCount: pageDicts.length } : {},
 		images,
 		...destinationRegistry.entries.length > 0 ? { destinations: [...destinationRegistry.entries] } : {},
-		...outline.length > 0 ? { outline } : {},
+		...outline !== void 0 && outline.length > 0 ? { outline } : {},
 		...attachments.length > 0 ? { attachments } : {},
-		...optionalContent.layers.length > 0 ? { layers: [...optionalContent.layers] } : {},
-		...form.length > 0 ? { form } : {},
-		...structure.tree.length > 0 ? { structure: [...structure.tree] } : {},
-		...Object.keys(source).length > 0 ? { source } : {}
+		...optionalContent !== void 0 && optionalContent.layers.length > 0 ? { layers: [...optionalContent.layers] } : {},
+		...form !== void 0 && form.length > 0 ? { form } : {},
+		...structure !== void 0 && structure.tree.length > 0 ? { structure: [...structure.tree] } : {},
+		...source !== void 0 && Object.keys(source).length > 0 ? { source } : {},
+		...skippedSurfaces.length > 0 ? { skippedSurfaces } : {}
 	};
 }
+function noLayerName() {}
+function noStructureOwner() {}
 function readDeclaredPageBox(page, key) {
 	const arr = require_objects.asArray(require_objects.dictGet(page, key));
 	if (arr === void 0) return;

package/dist/read.d.cts

@@ -1,6 +1,6 @@
 import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.cjs";
 import { r as Matrix } from "./matrix-B7_SBKQ5.cjs";
-import { LayoutDocument } from "./layout.cjs";
+import { LayoutDocument, LayoutDocumentSurface } from "./layout.cjs";
 //#region src/read.d.ts
 interface ReadPdfOptions {
   readonly sink?: PdfDiagnosticSink;
@@ -10,12 +10,31 @@ interface ReadPdfOptions {
    *
    * 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.
+   * 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; every one of those but the page tree and metadata can be left out as well with `surfaces`. 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 (and on whether the outline was read: see `surfaces`); 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[];
+  /**
+   * Which document-level surfaces to read. Each is read unless its entry is `false`, so omitting the setting, or an entry, reads it as before. Independent of `pages`: it applies to a full read and a page-selected read alike.
+   *
+   * A surface turned off is never parsed (its part of the catalog is not walked, so a malformed outline, form, layer list or structure tree reports no diagnostic) and its field is absent from the result whatever the file holds; the result lists it in `skippedSurfaces`, which is how a caller tells "not read" from "none". What each one covers, and what page items lose without it:
+   *
+   * - `outline`: the `/Outlines` bookmark tree (`outline`). Page items do not depend on it, except through minted names: a destination stated as a direct array is named with the first unused `destN` in the order the reader meets it, and the outline is read before any page, so an outline entry's direct destination takes a lower number than any link's. Without the outline, the names minted for page links' direct destinations are renumbered, and `destinations` loses the entries only the outline minted; each link still resolves to the same target.
+   * - `destinations`: the named destinations of the catalog `/Dests` dictionary and the `/Names /Dests` name tree, and the registry links and outline entries name their targets through (`destinations`). Without it nothing can name an internal target, so a link whose target is internal (a `/Dest`, or a `/GoTo` action, named or direct) is left out of its page's items, and a read outline entry carries no `destination`; a link to a URI is kept as usual.
+   * - `form`: the AcroForm field tree (`form`). Page items do not depend on it: a widget annotation is never a page item or annotation either way.
+   * - `layers`: optional content, the `/OCProperties` groups and their default visibility (`layers`). Without it no item carries a `layer`, since an `/OC` membership resolves to no name; the items themselves are all still read, so content the default view hides is indistinguishable from visible content.
+   * - `structure`: the `/StructTreeRoot` element tree and its `/ParentTree` ownership map (`structure`). Without it no item carries a `structure` owner, and the parent-tree diagnostics are not reported.
+   * - `residue`: the package-level residue rows (`source`), including the per-page `page-boxes` row. Page items do not depend on it; `metadata` still reads the XMP packet it falls back to.
+   *
+   * Apart from those stated losses and the renumbering a skipped outline causes, every page item is exactly what a read with the surface on produces.
+   */
+  readonly surfaces?: ReadPdfSurfaces;
 }
+/**
+ * One entry per document-level surface `readPdf` can leave out, each read unless set to `false` (see `ReadPdfOptions.surfaces` for what each covers and what page items lose without it).
+ */
+type ReadPdfSurfaces = Readonly<Partial<Record<LayoutDocumentSurface, boolean>>>;
 declare function readPdf(bytes: Uint8Array<ArrayBuffer>, options?: ReadPdfOptions): LayoutDocument;
 type PageRotation = 0 | 90 | 180 | 270;
 declare function normalizeRotation(rotate: number | undefined): PageRotation;
@@ -26,4 +45,4 @@ interface PageRotationResult {
 }
 declare function pageRotationTransform(rotation: PageRotation, w: number, h: number): PageRotationResult;
 //#endregion
-export { ReadPdfOptions, normalizeRotation, pageRotationTransform, readPdf };
+export { ReadPdfOptions, ReadPdfSurfaces, normalizeRotation, pageRotationTransform, readPdf };

package/dist/read.d.ts

@@ -1,6 +1,6 @@
 import { i as PdfDiagnosticSink } from "./diagnostics-BkG_Ej2x.js";
 import { r as Matrix } from "./matrix-B7_SBKQ5.js";
-import { LayoutDocument } from "./layout.js";
+import { LayoutDocument, LayoutDocumentSurface } from "./layout.js";
 //#region src/read.d.ts
 interface ReadPdfOptions {
   readonly sink?: PdfDiagnosticSink;
@@ -10,12 +10,31 @@ interface ReadPdfOptions {
    *
    * 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.
+   * 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; every one of those but the page tree and metadata can be left out as well with `surfaces`. 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 (and on whether the outline was read: see `surfaces`); 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[];
+  /**
+   * Which document-level surfaces to read. Each is read unless its entry is `false`, so omitting the setting, or an entry, reads it as before. Independent of `pages`: it applies to a full read and a page-selected read alike.
+   *
+   * A surface turned off is never parsed (its part of the catalog is not walked, so a malformed outline, form, layer list or structure tree reports no diagnostic) and its field is absent from the result whatever the file holds; the result lists it in `skippedSurfaces`, which is how a caller tells "not read" from "none". What each one covers, and what page items lose without it:
+   *
+   * - `outline`: the `/Outlines` bookmark tree (`outline`). Page items do not depend on it, except through minted names: a destination stated as a direct array is named with the first unused `destN` in the order the reader meets it, and the outline is read before any page, so an outline entry's direct destination takes a lower number than any link's. Without the outline, the names minted for page links' direct destinations are renumbered, and `destinations` loses the entries only the outline minted; each link still resolves to the same target.
+   * - `destinations`: the named destinations of the catalog `/Dests` dictionary and the `/Names /Dests` name tree, and the registry links and outline entries name their targets through (`destinations`). Without it nothing can name an internal target, so a link whose target is internal (a `/Dest`, or a `/GoTo` action, named or direct) is left out of its page's items, and a read outline entry carries no `destination`; a link to a URI is kept as usual.
+   * - `form`: the AcroForm field tree (`form`). Page items do not depend on it: a widget annotation is never a page item or annotation either way.
+   * - `layers`: optional content, the `/OCProperties` groups and their default visibility (`layers`). Without it no item carries a `layer`, since an `/OC` membership resolves to no name; the items themselves are all still read, so content the default view hides is indistinguishable from visible content.
+   * - `structure`: the `/StructTreeRoot` element tree and its `/ParentTree` ownership map (`structure`). Without it no item carries a `structure` owner, and the parent-tree diagnostics are not reported.
+   * - `residue`: the package-level residue rows (`source`), including the per-page `page-boxes` row. Page items do not depend on it; `metadata` still reads the XMP packet it falls back to.
+   *
+   * Apart from those stated losses and the renumbering a skipped outline causes, every page item is exactly what a read with the surface on produces.
+   */
+  readonly surfaces?: ReadPdfSurfaces;
 }
+/**
+ * One entry per document-level surface `readPdf` can leave out, each read unless set to `false` (see `ReadPdfOptions.surfaces` for what each covers and what page items lose without it).
+ */
+type ReadPdfSurfaces = Readonly<Partial<Record<LayoutDocumentSurface, boolean>>>;
 declare function readPdf(bytes: Uint8Array<ArrayBuffer>, options?: ReadPdfOptions): LayoutDocument;
 type PageRotation = 0 | 90 | 180 | 270;
 declare function normalizeRotation(rotate: number | undefined): PageRotation;
@@ -26,4 +45,4 @@ interface PageRotationResult {
 }
 declare function pageRotationTransform(rotation: PageRotation, w: number, h: number): PageRotationResult;
 //#endregion
-export { ReadPdfOptions, normalizeRotation, pageRotationTransform, readPdf };
+export { ReadPdfOptions, ReadPdfSurfaces, normalizeRotation, pageRotationTransform, readPdf };

package/dist/read.js

@@ -11,7 +11,7 @@ import { readAcroForm } from "./form.js";
 import { readXmpMetadata } from "./xmp.js";
 import { readOptionalContent } from "./optional-content.js";
 import { readStructure } from "./structure.js";
-import "./layout.js";
+import { LayoutDocumentSurfaceSchema } from "./layout.js";
 import { NOOP_DIAGNOSTIC_SINK, PdfPageSelectionError, PdfParseError } from "./diagnostics.js";
 import { openPdfDocument } from "./document.js";
 import { throwIfAborted } from "./util/abort.js";
@@ -19,6 +19,13 @@ 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 skippedSurfacesOf(surfaces) {
+	return LayoutDocumentSurfaceSchema.options.filter((surface) => surfaces?.[surface] === false);
+}
+const UNREAD_DESTINATION_REGISTRY = {
+	entries: [],
+	intern: () => void 0
+};
 function resolvePageSelection(selection, pageCount) {
 	const resolved = /* @__PURE__ */ new Set();
 	for (const requested of selection) {
@@ -54,25 +61,27 @@ function readPdf(bytes, options) {
 	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 skippedSurfaces = skippedSurfacesOf(options?.surfaces);
+	const reads = (surface) => !skippedSurfaces.includes(surface);
+	const destinationRegistry = reads("destinations") ? createDestinationRegistry(doc.catalog, doc, (obj) => doc.pageIndex(obj), sink) : UNREAD_DESTINATION_REGISTRY;
+	const outline = reads("outline") ? readOutline(doc.catalog, destinationRegistry, doc, sink) : void 0;
 	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, (index) => selection === void 0 || selection.has(index), doc, sink);
-	const source = readDocumentResidue(doc, sink);
+	const optionalContent = reads("layers") ? readOptionalContent(doc.catalog, doc, sink) : void 0;
+	const form = reads("form") ? readAcroForm(doc.catalog, doc, (obj) => doc.pageIndex(obj), sink) : void 0;
+	const structure = reads("structure") ? readStructure(doc.catalog, pageDicts, (index) => selection === void 0 || selection.has(index), doc, sink) : void 0;
+	const source = reads("residue") ? readDocumentResidue(doc, sink) : void 0;
 	const pageBoxRows = [];
 	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);
+		const read = readPage(index, pageDict, doc, fontResolver, images, imageIdCache, destinationRegistry, optionalContent?.layerNameOf ?? noLayerName, structure?.ownerOf ?? noStructureOwner, sink);
 		if (read.boxRow !== void 0) pageBoxRows.push(read.boxRow);
 		return [selection === void 0 ? read.page : {
 			...read.page,
 			index
 		}];
 	});
-	if (pageBoxRows.length > 0) source["page-boxes"] = {
+	if (source !== void 0 && pageBoxRows.length > 0) source["page-boxes"] = {
 		format: "pdf",
 		xml: serializeObjectToText(pdfArray(pageBoxRows))
 	};
@@ -83,14 +92,17 @@ function readPdf(bytes, options) {
 		...selection !== void 0 ? { pageCount: pageDicts.length } : {},
 		images,
 		...destinationRegistry.entries.length > 0 ? { destinations: [...destinationRegistry.entries] } : {},
-		...outline.length > 0 ? { outline } : {},
+		...outline !== void 0 && outline.length > 0 ? { outline } : {},
 		...attachments.length > 0 ? { attachments } : {},
-		...optionalContent.layers.length > 0 ? { layers: [...optionalContent.layers] } : {},
-		...form.length > 0 ? { form } : {},
-		...structure.tree.length > 0 ? { structure: [...structure.tree] } : {},
-		...Object.keys(source).length > 0 ? { source } : {}
+		...optionalContent !== void 0 && optionalContent.layers.length > 0 ? { layers: [...optionalContent.layers] } : {},
+		...form !== void 0 && form.length > 0 ? { form } : {},
+		...structure !== void 0 && structure.tree.length > 0 ? { structure: [...structure.tree] } : {},
+		...source !== void 0 && Object.keys(source).length > 0 ? { source } : {},
+		...skippedSurfaces.length > 0 ? { skippedSurfaces } : {}
 	};
 }
+function noLayerName() {}
+function noStructureOwner() {}
 function readDeclaredPageBox(page, key) {
 	const arr = asArray(dictGet(page, key));
 	if (arr === void 0) return;

package/dist/write-skipped-surfaces.cjs

@@ -0,0 +1,16 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/write-skipped-surfaces.ts
+/**
+* writePdf was handed a LayoutDocument from a read that left document-level surfaces out (one carrying `skippedSurfaces`, which only `ReadPdfOptions.surfaces` sets). Such a document is a reading with parts of the file deliberately unread, not a document to re-emit: each skipped surface's field is absent whatever the source holds, and its page items lack what depended on it (internal links without destinations, structure owners without the structure tree, layer names without layers), so writing it would silently drop the source's outline, form, layers, structure or residue. Thrown rather than writing a file that looks complete. Checked after `PdfPartialDocumentError`, so a page-selected read that also skipped surfaces reports the page selection.
+*/
+var PdfSkippedSurfacesError = class extends Error {
+	/** The surfaces the read skipped, as the document's `skippedSurfaces` lists them. */
+	skippedSurfaces;
+	constructor(skippedSurfaces) {
+		super(`this LayoutDocument was read with ${skippedSurfaces.join(", ")} left out (it carries skippedSurfaces, which only a read with ReadPdfOptions.surfaces sets); writing it would drop whatever the source holds there, so it cannot be written as a document of its own`);
+		this.name = "PdfSkippedSurfacesError";
+		this.skippedSurfaces = skippedSurfaces;
+	}
+};
+//#endregion
+exports.PdfSkippedSurfacesError = PdfSkippedSurfacesError;

package/dist/write-skipped-surfaces.d.cts

@@ -0,0 +1,12 @@
+import { LayoutDocumentSurface } from "./layout.cjs";
+//#region src/write-skipped-surfaces.d.ts
+/**
+ * writePdf was handed a LayoutDocument from a read that left document-level surfaces out (one carrying `skippedSurfaces`, which only `ReadPdfOptions.surfaces` sets). Such a document is a reading with parts of the file deliberately unread, not a document to re-emit: each skipped surface's field is absent whatever the source holds, and its page items lack what depended on it (internal links without destinations, structure owners without the structure tree, layer names without layers), so writing it would silently drop the source's outline, form, layers, structure or residue. Thrown rather than writing a file that looks complete. Checked after `PdfPartialDocumentError`, so a page-selected read that also skipped surfaces reports the page selection.
+ */
+declare class PdfSkippedSurfacesError extends Error {
+  /** The surfaces the read skipped, as the document's `skippedSurfaces` lists them. */
+  readonly skippedSurfaces: readonly LayoutDocumentSurface[];
+  constructor(skippedSurfaces: readonly LayoutDocumentSurface[]);
+}
+//#endregion
+export { PdfSkippedSurfacesError };

package/dist/write-skipped-surfaces.d.ts

@@ -0,0 +1,12 @@
+import { LayoutDocumentSurface } from "./layout.js";
+//#region src/write-skipped-surfaces.d.ts
+/**
+ * writePdf was handed a LayoutDocument from a read that left document-level surfaces out (one carrying `skippedSurfaces`, which only `ReadPdfOptions.surfaces` sets). Such a document is a reading with parts of the file deliberately unread, not a document to re-emit: each skipped surface's field is absent whatever the source holds, and its page items lack what depended on it (internal links without destinations, structure owners without the structure tree, layer names without layers), so writing it would silently drop the source's outline, form, layers, structure or residue. Thrown rather than writing a file that looks complete. Checked after `PdfPartialDocumentError`, so a page-selected read that also skipped surfaces reports the page selection.
+ */
+declare class PdfSkippedSurfacesError extends Error {
+  /** The surfaces the read skipped, as the document's `skippedSurfaces` lists them. */
+  readonly skippedSurfaces: readonly LayoutDocumentSurface[];
+  constructor(skippedSurfaces: readonly LayoutDocumentSurface[]);
+}
+//#endregion
+export { PdfSkippedSurfacesError };

package/dist/write-skipped-surfaces.js

@@ -0,0 +1,15 @@
+//#region src/write-skipped-surfaces.ts
+/**
+* writePdf was handed a LayoutDocument from a read that left document-level surfaces out (one carrying `skippedSurfaces`, which only `ReadPdfOptions.surfaces` sets). Such a document is a reading with parts of the file deliberately unread, not a document to re-emit: each skipped surface's field is absent whatever the source holds, and its page items lack what depended on it (internal links without destinations, structure owners without the structure tree, layer names without layers), so writing it would silently drop the source's outline, form, layers, structure or residue. Thrown rather than writing a file that looks complete. Checked after `PdfPartialDocumentError`, so a page-selected read that also skipped surfaces reports the page selection.
+*/
+var PdfSkippedSurfacesError = class extends Error {
+	/** The surfaces the read skipped, as the document's `skippedSurfaces` lists them. */
+	skippedSurfaces;
+	constructor(skippedSurfaces) {
+		super(`this LayoutDocument was read with ${skippedSurfaces.join(", ")} left out (it carries skippedSurfaces, which only a read with ReadPdfOptions.surfaces sets); writing it would drop whatever the source holds there, so it cannot be written as a document of its own`);
+		this.name = "PdfSkippedSurfacesError";
+		this.skippedSurfaces = skippedSurfaces;
+	}
+};
+//#endregion
+export { PdfSkippedSurfacesError };

package/dist/write.cjs

@@ -15,6 +15,7 @@ const require_font_registry = require("./font-registry.cjs");
 const require_measure = require("./measure.cjs");
 const require_write_page_emit = require("./write-page-emit.cjs");
 const require_write_outline = require("./write-outline.cjs");
+const require_write_skipped_surfaces = require("./write-skipped-surfaces.cjs");
 let byte_codec = require("byte-codec");
 //#region src/write.ts
 const MATH_FONT_RESOURCE_NAME = "MF";
@@ -84,6 +85,7 @@ var PdfPartialDocumentError = class extends Error {
 };
 function writePdf(doc, options = {}) {
 	if (doc.pageCount !== void 0) throw new PdfPartialDocumentError(doc.pageCount, doc.pages.length);
+	if (doc.skippedSurfaces !== void 0) throw new require_write_skipped_surfaces.PdfSkippedSurfacesError(doc.skippedSurfaces);
 	const compress = options.compress ?? true;
 	const registry = options.fonts;
 	const measurer = require_measure.createFontMeasurer(registry);

package/dist/write.js

@@ -14,6 +14,7 @@ import { resolveFaceWithRegistry } from "./font-registry.js";
 import { createFontMeasurer } from "./measure.js";
 import { emitPageObjects } from "./write-page-emit.js";
 import { emitOutlineObjects } from "./write-outline.js";
+import { PdfSkippedSurfacesError } from "./write-skipped-surfaces.js";
 import { base64ToBytes } from "byte-codec";
 //#region src/write.ts
 const MATH_FONT_RESOURCE_NAME = "MF";
@@ -83,6 +84,7 @@ var PdfPartialDocumentError = class extends Error {
 };
 function writePdf(doc, options = {}) {
 	if (doc.pageCount !== void 0) throw new PdfPartialDocumentError(doc.pageCount, doc.pages.length);
+	if (doc.skippedSurfaces !== void 0) throw new PdfSkippedSurfacesError(doc.skippedSurfaces);
 	const compress = options.compress ?? true;
 	const registry = options.fonts;
 	const measurer = createFontMeasurer(registry);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pdf-codec",
-  "version": "5.4.0",
+  "version": "5.5.1",
   "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": {
@@ -100,7 +100,7 @@
   "packageManager": "pnpm@12.4.1+sha512.2e81e399d73fe8390dab25e06aa788ab7a5908248d2f5a370f82b481147a6a7a367bf8048f9a6fdb6460f21a66f0542dedb8b94ca2c8723596741920b1656d4c",
   "dependencies": {
     "byte-codec": "2.0.2",
-    "document-schema.js": "7.16.1",
+    "document-schema.js": "7.16.2",
     "fflate": "0.8.3",
     "zod": "4.4.3"
   },