js.documents 14.4.124 → 14.6.0

package/README.md

@@ -383,7 +383,49 @@ One subpath is a declared entry point in its own right: **`documents.js/read`**
 import { pdfToMarkdown } from "documents.js/read";
 ```
 
-It carries the ten `pdfTo*` conversions, `PdfToDocumentOptions`, `readDocumentMetadata` (with `ReadDocumentMetadataOptions`), `readNativeDocumentTree` (with `ReadNativeDocumentTreeOptions`), and `readContentDocument` (with `ReadContentDocumentOptions`) — identical functions to the root barrel's (the same forwarders, run through the composition engine's read half, and the same dispatch through the read-only codec half `src/codecs/read.ts`), never a forked behaviour; `convertDocument` and every X-to-PDF direction stay on the root barrel. `src/read-graph.test.ts` walks the entry's static import graph, follows `pdf-codec` specifiers through that package's real `exports` map into its source, and fails the build if the write path or any font asset becomes reachable.
+It carries the ten `pdfTo*` conversions, `PdfToDocumentOptions`, `readDocumentMetadata` (with `ReadDocumentMetadataOptions`), `readNativeDocumentTree` (with `ReadNativeDocumentTreeOptions`), and `readContentDocument` (with `ReadContentDocumentOptions`) — identical functions to the root barrel's (the same forwarders, run through the composition engine's read half, and the same read-only dispatch: `src/codecs/read.ts`'s `CONTENT_READERS` for a content format, and pdf-codec's `readPdf` directly for pdf), never a forked behaviour; `convertDocument` and every X-to-PDF direction stay on the root barrel. `src/read-graph.test.ts` walks the entry's static import graph, follows `pdf-codec` specifiers through that package's real `exports` map into its source, and fails the build if the write path or any font asset becomes reachable.
+
+### Converting a selection of a PDF's pages
+
+The PDF-sourced entry points that produce content take a `pages` option: the `pdfTo*` conversions (`PdfToDocumentOptions.pages`), `convertDocument` with a pdf source (`UnifiedConversionOptions.pages`), and `readNativeDocumentTree`/`readContentDocument` (`ReadNativeDocumentTreeOptions.pages`). It is pdf-codec's `ReadPdfOptions.pages` threaded through: zero-based page-tree indices, a negative index counted from the end (`-1` is the last page), duplicates collapsed, the result in document order, and `PdfPageSelectionError` for an index naming no page. Two entry points never take it: `readDocumentMetadata` always reads with an empty selection (and every document-level surface skipped, below), since metadata never depends on page content, so identifying a document reads no page at all; and `openPdf` always reads every page, since an editor holds a document to write back. `convertDocument` applies `pages` only when the source itself is pdf: a conversion from another format ignores it, including one whose route renders an intermediate pdf internally (docx to ods), because that pdf is not the caller's document.
+
+```ts
+import { pdfToMarkdown } from "documents.js/read";
+
+const coverAndLastPage = pdfToMarkdown(pdfBytes, { pages: [0, 1, 2, -1] });
+```
+
+What a selection skips: the unselected pages' content streams are never fetched, decoded or interpreted, the fonts and images only those pages use are never resolved, and the source's embedded files are never decoded, so the result carries no attachments; a caller holding the `LayoutDocument` checks `pageCount` (set only on a page-selected read) before concluding the document has none (see pdf-codec's README for exactly what is and is not read). That is what lets a caller identify a document from its first pages, or read a code from its last page, inside a memory-capped runtime such as a Cloudflare Worker isolate, without paying for every page's content.
+
+The output holds only the selected pages, and reconstruction sees only them, so a page can come out differently than in a full conversion. Heading detection measures text against the body size, taken as the most common text size across the pages read: a cover page read on its own, dominated by large title text, takes the title's size as its body, so the title becomes a paragraph rather than a heading. Reading the cover together with a few ordinary pages restores the document's real body size.
+
+Markdown output labels each selected page with its original one-based page number, written as `<!-- page N -->` on its own line at the start of the page (`pageNumberMarker`), alongside the `<!-- page break -->` marker between pages that share a section, so a caller can tell which pages it got without re-deriving the selection. The label is output-only: reading markdown back keeps it as an ordinary HTML-comment paragraph, exactly as any other comment in a markdown source is kept. A full conversion writes no labels, so its output is unchanged. A caller composing the stages itself (`readPdf` with `pages`, `reconstructWordprocessing`, then `buildMarkdownText` or `renderContentDocumentToMarkdown`) gets the same labels by passing `pageNumbers: layout.pages.map((page, position) => sourcePageIndex(page, position) + 1)`; `buildMarkdownText` throws `MarkdownPageNumberCountError` when the count does not match the document's pages, and a non-wordprocessing document flattened by `renderContentDocumentToMarkdown` counts as a single page.
+
+Every reconstructed node's frames name the page's index in the source PDF (the same index every destination and form widget names), which is why a page-selected conversion's reported `DocumentTree` carries no `pages` envelope: that array is indexed by frame page index, and a selection cannot fill it. Such a tree cannot be rebuilt to pdf either: `buildDocumentBytes(tree, "pdf")` needs that envelope and throws without it. A later stage's own page-addressing option, such as `page` for an svg target, counts within the selection. A page-selected `LayoutDocument` cannot be written back: `writePdf` refuses one with `PdfPartialDocumentError`. `PdfPageSelectionError`, `PdfPartialDocumentError` and `sourcePageIndex` are exported from the root barrel; the `documents.js/read` entry re-exports nothing (this package allows re-exports only in its root barrel), so a caller of that entry recognises a bad selection by the thrown error's `code` (`pdf/page-out-of-range` or `pdf/page-index-not-integer`), and resolves a page's source index as `page.index ?? position`.
+
+### Leaving a PDF's document-level surfaces out
+
+The same entry points take a `surfaces` option (`PdfToDocumentOptions.surfaces`, `UnifiedConversionOptions.surfaces`, `ReadNativeDocumentTreeOptions.surfaces`): pdf-codec's `ReadPdfOptions.surfaces` threaded through, one boolean per document-level surface (`outline`, `destinations`, `form`, `layers`, `structure`, `residue`), each read unless set to `false`, so omitting it converts exactly as before. It is independent of `pages`, and `convertDocument` hands it to the same hop `pages` goes to, so an intermediate pdf a route renders internally is always read whole. Combined with a small page selection it is what keeps identifying a document from a few pages cheap on a long tagged PDF, whose structure tree and `/ParentTree` a page selection alone still parses whole.
+
+```ts
+import { pdfToMarkdown } from "documents.js/read";
+
+const firstPages = pdfToMarkdown(pdfBytes, {
+  pages: [0, 1, 2, -1],
+  surfaces: {
+    outline: false,
+    destinations: false,
+    form: false,
+    layers: false,
+    structure: false,
+    residue: false,
+  },
+});
+```
+
+A skipped surface is never parsed, and the conversion carries nothing built from it. The `LayoutDocument` such a read produces lists the skipped surfaces in `skippedSurfaces`, so an absent field there means "not read" rather than "none", and `writePdf` refuses that `LayoutDocument` with `PdfSkippedSurfacesError`. The reported `DocumentTree` keeps its outline as `outline-N` entries inside the `destinations` table: without `outline` those entries are absent (and so are the `destN` entries only the outline minted, below), and without `destinations` the table holds none of the document's destinations, while a read outline's `outline-N` entries stay in it, each without a `destination`. There are no layers or residue tables for a skipped surface, and no structure entries in `definitions` without `structure`; internal link constructs are left out without `destinations` (links to a URI are kept), and the form's `contentControl` constructs are absent without `form`. Skipping the outline also renames internal link anchors: a destination stated as a direct array gets a reader-minted `destN` name, numbered in the order the reader meets them, and the outline is read before any page, so without it the names minted for page links (and the anchors their link constructs carry) are renumbered, while each still names the same target, and the tree's `destinations` table loses the `destN` entries only the outline minted. Two skips change reconstruction itself. Without `structure`, a tagged PDF's headings, table cells and divisions are inferred from geometry exactly as for an untagged file, so they can come out differently than in a full conversion. Without `layers`, nothing marks content as belonging to a hidden layer, so content the default view hides is kept as if it were visible. Those are also the two differences that reach a rebuild: a `DocumentTree` from a conversion without `pages` still carries its `pages` envelope, so `buildDocumentBytes(tree, "pdf")` rebuilds it, and the rebuilt PDF draws hidden-layer text visibly when `layers` was skipped and holds the geometry-inferred blocks when `structure` was skipped. The rebuild never re-emits the outline, destinations, form, layers, structure or residue whether or not a surface was skipped, since it builds the PDF from the tree's metadata, page sizes, embedded fonts and the positioned content alone: text runs, images, vectors, formulas, table-cell background rectangles and border lines, sheet-cell rectangles and border lines, and URI links attached to a recovered run. An external link whose rectangle covers no recovered run (a link over an image, say) stays a link construct in the tree and is not re-emitted. Its `LayoutDocument` never carries `skippedSurfaces`, so `writePdf` never refuses a rebuild.
+
+`readDocumentMetadata` always reads a pdf with an empty page selection and every surface skipped, since metadata comes from the trailer's `/Info`, the catalog's `/Lang` and the XMP packet alone, so identifying a document parses neither its pages nor its outline, destinations, form, layers, structure tree or residue, and returns the same metadata a full read does. `openPdf` takes neither option, since an editor holds a whole document to write back. `ReadPdfSurfaces`, `LayoutDocumentSurface` and `PdfSkippedSurfacesError` are exported from the root barrel.
 
 ### Reading and building xlsx content directly
 
@@ -821,8 +863,8 @@ The package is layered from generic primitives outward to the two conversion dir
 - **`src/firebird/`** — Tier 3: gbak logical-backup reader. `reader.ts` (attribute framing + RLE decompression + XDR decoding), `schema.ts`/`data.ts` (table/row walking). No ratified spec — built against Firebird's own engine source.
 - **`src/odb/`** — decoder-selection and pivot-mapping: `read.ts` routes to the right tier, `spreadsheet.ts`/`csv.ts` map to output formats. `odb/sql/` is the bounded SQL engine, `odb/formula/` is the rpt formula engine, `odb/report/` is the renderer, `odb/values.ts` is shared comparison/aggregation semantics.
 - **`src/convert/`** — the composition layer: `convert.ts` (the named conversion functions and their option types), `composition.ts` (the pathfinder, the primitive registry, the bridge/fromPdf executors, and `convertDocumentFromPdf` — the read half of the engine), `composition-to-pdf.ts` (`executeToPdf`, the layout-engine registry, and the full `convertDocument` binding — the write half, split out so a read-only consumer never statically imports a renderer), `from-pdf.ts` (the `pdfTo*` family, `readDocumentMetadata`, `readNativeDocumentTree`, `readContentDocument`, and the `documents.js/read` entry), `codec.ts` (`z.codec()` pairs), `port.ts`/`local.ts` (the `DocumentConverter` port), `variant-bridges.ts` (cross-variant semantic transforms), and `from-package.ts` (`buildDocumentBytes`, which flattens once at the boundary). The tree ⇄ flat transform those construction sites call — `assembleTree`, `decompose`, `flattenTree`, `factorStyles` — is not implemented here: it lives in `document-schema.js`, which owns both encodings. `bijection.test.ts` is this package's own gate on it, re-running the three laws over the real corpus every reader, editor, and conversion here produces.
-- **`src/codecs/`** — `DOCUMENT_FORMAT_CODECS`: every format's read/build capability as data, so `readDocumentMetadata`/`setDocumentMetadata`/`buildDocumentBytes` dispatch through one registry.
-- **`src/metadata/`** — cross-format metadata read/write via `DOCUMENT_FORMAT_CODECS`.
+- **`src/codecs/`** — `DOCUMENT_FORMAT_CODECS`: every format's read/build capability as data, so `setDocumentMetadata`/`buildDocumentBytes` dispatch through one registry; its read halves live in `read.ts`, whose `CONTENT_READERS` `readDocumentMetadata` uses for content formats (it reads pdf through pdf-codec's `readPdf` directly, with no page selected).
+- **`src/metadata/`**: cross-format metadata write via `DOCUMENT_FORMAT_CODECS`; the read side is `readDocumentMetadata` in `src/convert/from-pdf.ts`, which reads a content format through `CONTENT_READERS` and a pdf through `readPdf` with an empty page selection and every document-level surface skipped.
 - **`src/package-codec.ts`** — `decodeDocumentPackage`/`encodeDocumentPackage`/`decodeOdbPackage`.
 
 Dependency direction is downward and checkable. Twelve external dependencies each own a distinct concern: `ooxml.js` (docx/pptx/xlsx), `odf.js` (odt/ods/odp/odg), `document-schema.js` (shared schemas + port contracts), `pdf-codec` (PDF codec + text-layout/font primitives), `byte-codec` (byte/image utilities), `markdown-codec` (markdown), `rtf-codec` (rtf), `wpd-codec` (wpd, read-only), `doc-codec` (doc), `xls-codec` (xls), `ppt-codec` (ppt, through this package's own `src/ppt/` envelope adapter), `archive-codec` (the `[MS-CFB]` compound-file detection all three legacy binary codecs' own bytes schemas build on). No `PdfObject`/`PdfDict`/`PdfStream` type appears anywhere in this package.

package/dist/{composition-plan-CfvhXeOC.cjs → composition-plan-CSHdRyji.cjs}

@@ -23,7 +23,7 @@ const require_csv_write = require("./csv/write.cjs");
 const require_read$1 = require("./read-CahCZMwG.cjs");
 const require_svg_write = require("./svg/write.cjs");
 const require_ports_abort = require("./ports/abort.cjs");
-const require_reconstruct_presentations_prod = require("./reconstruct-presentations-prod-X315aBmI.cjs");
+const require_reconstruct_presentations_prod = require("./reconstruct-presentations-prod-CA4no_aw.cjs");
 const require_convert_pdf_package_tables = require("./convert/pdf-package-tables.cjs");
 const require_convert_variant_bridges = require("./convert/variant-bridges.cjs");
 const require_convert_capability = require("./convert/capability.cjs");
@@ -34,6 +34,7 @@ let doc_codec = require("doc-codec");
 let xls_codec = require("xls-codec");
 let rtf_codec = require("rtf-codec");
 let epub_codec = require("epub-codec");
+let pdf_codec_layout = require("pdf-codec/layout");
 require("markdown-codec");
 let wpd_codec = require("wpd-codec");
 let pdf_codec_read = require("pdf-codec/read");
@@ -127,7 +128,7 @@ const FORMAT_NODES = {
 			signal: options?.signal,
 			images: options?.images
 		}),
-		build: (content) => require_markdown_write.buildMarkdownText(content),
+		build: (content, options) => require_markdown_write.buildMarkdownText(content, { pageNumbers: options?.pageNumbers }),
 		encode: (text) => require_markdown_text.encodeMarkdownText(text),
 		hasSourcePackage: false
 	},
@@ -335,23 +336,32 @@ function executeBridge(source, target, bytes, options) {
 	options?.onDocument?.((0, document_schema_js.assembleTree)(buildContent));
 	return out;
 }
+function layoutPageNumbers(layout) {
+	return layout.pages.map((page, position) => (0, pdf_codec_layout.sourcePageIndex)(page, position) + 1);
+}
 function executeFromPdf(target, bytes, options) {
 	const node = FORMAT_NODES[target];
 	const layout = (0, pdf_codec_read.readPdf)(bytes, {
 		signal: options?.signal,
-		sink: options?.sink
+		sink: options?.sink,
+		pages: options?.pages,
+		surfaces: options?.surfaces
 	});
 	const content = RECONSTRUCTORS[node.variant](layout, {
 		signal: options?.signal,
 		onCellTypeInference: options?.onCellTypeInference
 	});
-	const pages = layout.pages.map((page) => ({
+	const selected = options?.pages !== void 0;
+	const pages = selected ? void 0 : layout.pages.map((page) => ({
 		widthPt: page.widthPt,
 		heightPt: page.heightPt
 	}));
 	let out;
 	if (isTextFormatNode(node)) {
-		const text = node.build(content, options);
+		const text = node.build(content, {
+			...options,
+			pageNumbers: selected ? layoutPageNumbers(layout) : void 0
+		});
 		out = node.encode(text);
 	} else {
 		const pkg = node.build(content);
@@ -367,9 +377,13 @@ function runCompositionPlan(plan, bytes, options, executors) {
 	for (let i = 0; i < plan.hops.length; i++) {
 		const hop = plan.hops[i];
 		if (hop === void 0) throw new Error("runCompositionPlan: resolveCompositionPlan returned a malformed hop");
-		const hopOptions = i === plan.hops.length - 1 ? options : options === void 0 ? void 0 : {
+		const isLastHop = i === plan.hops.length - 1;
+		const readsCallerPdf = i === 0 && hop.from === "pdf";
+		const hopOptions = options === void 0 ? void 0 : {
 			...options,
-			onDocument: void 0
+			onDocument: isLastHop ? options.onDocument : void 0,
+			pages: readsCallerPdf ? options.pages : void 0,
+			surfaces: readsCallerPdf ? options.surfaces : void 0
 		};
 		if (hop.executor === "toPdf") {
 			if (!isSourceContentFormat(hop.from)) throw new Error(`runCompositionPlan: toPdf source '${hop.from}' is not a content format`);

package/dist/{composition-plan-DU9nPPN7.d.cts → composition-plan-D7mR0HWB.d.cts}

@@ -9,6 +9,7 @@ import { ContentDocument, DocumentTree, FontSubstitution, ProvidedFont } from "d
 import { LayoutDocument, PdfDiagnosticSink, WinAnsiSubstitution } from "pdf-codec";
 import { MarkdownImageResolver } from "markdown-codec";
 import { Package } from "ooxml.js";
+import { ReadPdfSurfaces } from "pdf-codec/read";
 //#region src/convert/composition.d.ts
 declare const THROUGH_PDF_EDGE_COST = 3;
 declare const MAX_CONVERSION_PATH_NODES = 4;
@@ -33,6 +34,19 @@ interface UnifiedConversionOptions {
   readonly page?: number;
   readonly onSvgDiagnostic?: SvgDiagnosticSink;
   readonly clock?: ClockPort;
+  /**
+   * The pages of a pdf source to convert, as pdf-codec's `ReadPdfOptions.pages` reads them: zero-based page-tree indices, a negative index counted from the end, duplicates collapsed, the result in document order, and an index naming no page throwing `PdfPageSelectionError`. Only the plan's first hop receives it, and only when the conversion's source is pdf: a conversion from any other format ignores it, including one whose route renders an intermediate pdf internally (docx to ods goes through toPdf then fromPdf), since that pdf is not the caller's document. The unselected pages' content streams, the fonts and images only they use, and the source's embedded files are never read (see `ReadPdfOptions.pages` for exactly what is and is not skipped).
+   *
+   * The output holds only those pages. A markdown target labels each with its original one-based page number (`<!-- page 7 -->` at the start of the page, beside the usual `<!-- page break -->` between pages), so the text says which pages it holds. A page-addressing option of a later stage, such as `page` for an svg target, counts within the selection. Reconstruction infers from the selected pages alone, so a page can reconstruct differently than it would in a full conversion: the body text size heading detection compares against is the most common size across the selection, which on a cover page dominated by large title text is the title's own size, leaving the title a paragraph rather than a heading. The DocumentTree `onDocument` reports carries no `pages` envelope for a page-selected conversion: its frames name source page indices, which an envelope holding only the selected pages could not be indexed by.
+   */
+  readonly pages?: readonly number[];
+  /**
+   * The document-level surfaces of a pdf source to read, as pdf-codec's `ReadPdfOptions.surfaces` takes them: one boolean per surface (`outline`, `destinations`, `form`, `layers`, `structure`, `residue`), each read unless set to `false`, so omitting it reads everything as before. Independent of `pages`, and handed to the same hop: only the plan's first hop, and only when the conversion's source is pdf, so an intermediate pdf a route renders internally is always read whole. A skipped surface is never parsed and is absent from the read, so what the conversion builds from it is absent too: no `outline-N` entries in the tree's `destinations` table without `outline`, no destinations and no internal link constructs without `destinations` (a link to a URI is kept, and a read outline's `outline-N` entries stay, each without a `destination`), no form `contentControl` constructs without `form`, no layers table without `layers`, no structure entries in `definitions` without `structure`, no residue without `residue`; skipping the outline also renumbers the reader-minted `destN` names internal link anchors carry, since the outline mints its direct destinations first. Two skips also change reconstruction: without `structure` a tagged PDF's headings, table cells and divisions are inferred from geometry as for an untagged file, and without `layers` content the default view hides cannot be told apart and is kept as if visible. See `ReadPdfOptions.surfaces` for exactly what each covers.
+   */
+  readonly surfaces?: ReadPdfSurfaces;
+}
+interface TextBuildContext {
+  readonly pageNumbers?: readonly number[];
 }
 type ContentFormat = "docx" | "pptx" | "xlsx" | "odt" | "odp" | "ods" | "odg" | "svg" | "csv" | "markdown" | "rtf" | "doc" | "xls" | "ppt" | "epub";
 declare const CONTENT_FORMATS: readonly ContentFormat[];
@@ -51,7 +65,7 @@ interface TextFormatNode {
   readonly family: "markdown" | "csv" | "svg" | "rtf" | "doc" | "xls" | "ppt" | "epub";
   readonly decode: (bytes: Uint8Array<ArrayBuffer>) => string;
   readonly read: (text: string, options?: UnifiedConversionOptions) => ContentDocument;
-  readonly build: (content: ContentDocument, options?: UnifiedConversionOptions) => string;
+  readonly build: (content: ContentDocument, options?: UnifiedConversionOptions & TextBuildContext) => string;
   readonly encode: (text: string) => Uint8Array<ArrayBuffer>;
   readonly hasSourcePackage: false;
 }

package/dist/{composition-plan-l6QPO4FX.d.ts → composition-plan-DPZq6NhK.d.ts}

@@ -9,6 +9,7 @@ import { Package } from "ooxml.js";
 import { ContentDocument, DocumentTree, FontSubstitution, ProvidedFont } from "document-schema.js";
 import { LayoutDocument, PdfDiagnosticSink, WinAnsiSubstitution } from "pdf-codec";
 import { MarkdownImageResolver } from "markdown-codec";
+import { ReadPdfSurfaces } from "pdf-codec/read";
 //#region src/convert/composition.d.ts
 declare const THROUGH_PDF_EDGE_COST = 3;
 declare const MAX_CONVERSION_PATH_NODES = 4;
@@ -33,6 +34,19 @@ interface UnifiedConversionOptions {
   readonly page?: number;
   readonly onSvgDiagnostic?: SvgDiagnosticSink;
   readonly clock?: ClockPort;
+  /**
+   * The pages of a pdf source to convert, as pdf-codec's `ReadPdfOptions.pages` reads them: zero-based page-tree indices, a negative index counted from the end, duplicates collapsed, the result in document order, and an index naming no page throwing `PdfPageSelectionError`. Only the plan's first hop receives it, and only when the conversion's source is pdf: a conversion from any other format ignores it, including one whose route renders an intermediate pdf internally (docx to ods goes through toPdf then fromPdf), since that pdf is not the caller's document. The unselected pages' content streams, the fonts and images only they use, and the source's embedded files are never read (see `ReadPdfOptions.pages` for exactly what is and is not skipped).
+   *
+   * The output holds only those pages. A markdown target labels each with its original one-based page number (`<!-- page 7 -->` at the start of the page, beside the usual `<!-- page break -->` between pages), so the text says which pages it holds. A page-addressing option of a later stage, such as `page` for an svg target, counts within the selection. Reconstruction infers from the selected pages alone, so a page can reconstruct differently than it would in a full conversion: the body text size heading detection compares against is the most common size across the selection, which on a cover page dominated by large title text is the title's own size, leaving the title a paragraph rather than a heading. The DocumentTree `onDocument` reports carries no `pages` envelope for a page-selected conversion: its frames name source page indices, which an envelope holding only the selected pages could not be indexed by.
+   */
+  readonly pages?: readonly number[];
+  /**
+   * The document-level surfaces of a pdf source to read, as pdf-codec's `ReadPdfOptions.surfaces` takes them: one boolean per surface (`outline`, `destinations`, `form`, `layers`, `structure`, `residue`), each read unless set to `false`, so omitting it reads everything as before. Independent of `pages`, and handed to the same hop: only the plan's first hop, and only when the conversion's source is pdf, so an intermediate pdf a route renders internally is always read whole. A skipped surface is never parsed and is absent from the read, so what the conversion builds from it is absent too: no `outline-N` entries in the tree's `destinations` table without `outline`, no destinations and no internal link constructs without `destinations` (a link to a URI is kept, and a read outline's `outline-N` entries stay, each without a `destination`), no form `contentControl` constructs without `form`, no layers table without `layers`, no structure entries in `definitions` without `structure`, no residue without `residue`; skipping the outline also renumbers the reader-minted `destN` names internal link anchors carry, since the outline mints its direct destinations first. Two skips also change reconstruction: without `structure` a tagged PDF's headings, table cells and divisions are inferred from geometry as for an untagged file, and without `layers` content the default view hides cannot be told apart and is kept as if visible. See `ReadPdfOptions.surfaces` for exactly what each covers.
+   */
+  readonly surfaces?: ReadPdfSurfaces;
+}
+interface TextBuildContext {
+  readonly pageNumbers?: readonly number[];
 }
 type ContentFormat = "docx" | "pptx" | "xlsx" | "odt" | "odp" | "ods" | "odg" | "svg" | "csv" | "markdown" | "rtf" | "doc" | "xls" | "ppt" | "epub";
 declare const CONTENT_FORMATS: readonly ContentFormat[];
@@ -51,7 +65,7 @@ interface TextFormatNode {
   readonly family: "markdown" | "csv" | "svg" | "rtf" | "doc" | "xls" | "ppt" | "epub";
   readonly decode: (bytes: Uint8Array<ArrayBuffer>) => string;
   readonly read: (text: string, options?: UnifiedConversionOptions) => ContentDocument;
-  readonly build: (content: ContentDocument, options?: UnifiedConversionOptions) => string;
+  readonly build: (content: ContentDocument, options?: UnifiedConversionOptions & TextBuildContext) => string;
   readonly encode: (text: string) => Uint8Array<ArrayBuffer>;
   readonly hasSourcePackage: false;
 }

package/dist/{composition-plan-f0zaExUW.js → composition-plan-DQ8lPKIW.js}

@@ -23,7 +23,7 @@ import { buildCsvText } from "./csv/write.js";
 import { i as readSvgContent } from "./read-BSH--XB4.js";
 import { buildSvgText } from "./svg/write.js";
 import { throwIfAborted } from "./ports/abort.js";
-import { _ as reconstructWordprocessing, g as reconstructSpreadsheet, i as reconstructPresentation, r as reconstructDrawing } from "./reconstruct-presentations-prod-B5fkPiRZ.js";
+import { _ as reconstructWordprocessing, g as reconstructSpreadsheet, i as reconstructPresentation, r as reconstructDrawing } from "./reconstruct-presentations-prod-CC8ct-5O.js";
 import { stampPdfPackageTables } from "./convert/pdf-package-tables.js";
 import { drawingToPresentation, presentationToDrawing, presentationToWordprocessing, spreadsheetToWordprocessing, wordprocessingToPresentation } from "./convert/variant-bridges.js";
 import { UnsupportedConversionError } from "./convert/capability.js";
@@ -34,6 +34,7 @@ import { readDocContent, writeDocContent } from "doc-codec";
 import { readXlsContent, writeXlsContent } from "xls-codec";
 import { readRtfContent, rtfBytesFromLatin1, writeRtfContent } from "rtf-codec";
 import { readEpubContent, writeEpubContent } from "epub-codec";
+import { sourcePageIndex } from "pdf-codec/layout";
 import "markdown-codec";
 import { readWpdContent } from "wpd-codec";
 import { readPdf } from "pdf-codec/read";
@@ -127,7 +128,7 @@ const FORMAT_NODES = {
 			signal: options?.signal,
 			images: options?.images
 		}),
-		build: (content) => buildMarkdownText(content),
+		build: (content, options) => buildMarkdownText(content, { pageNumbers: options?.pageNumbers }),
 		encode: (text) => encodeMarkdownText(text),
 		hasSourcePackage: false
 	},
@@ -335,23 +336,32 @@ function executeBridge(source, target, bytes, options) {
 	options?.onDocument?.(assembleTree(buildContent));
 	return out;
 }
+function layoutPageNumbers(layout) {
+	return layout.pages.map((page, position) => sourcePageIndex(page, position) + 1);
+}
 function executeFromPdf(target, bytes, options) {
 	const node = FORMAT_NODES[target];
 	const layout = readPdf(bytes, {
 		signal: options?.signal,
-		sink: options?.sink
+		sink: options?.sink,
+		pages: options?.pages,
+		surfaces: options?.surfaces
 	});
 	const content = RECONSTRUCTORS[node.variant](layout, {
 		signal: options?.signal,
 		onCellTypeInference: options?.onCellTypeInference
 	});
-	const pages = layout.pages.map((page) => ({
+	const selected = options?.pages !== void 0;
+	const pages = selected ? void 0 : layout.pages.map((page) => ({
 		widthPt: page.widthPt,
 		heightPt: page.heightPt
 	}));
 	let out;
 	if (isTextFormatNode(node)) {
-		const text = node.build(content, options);
+		const text = node.build(content, {
+			...options,
+			pageNumbers: selected ? layoutPageNumbers(layout) : void 0
+		});
 		out = node.encode(text);
 	} else {
 		const pkg = node.build(content);
@@ -367,9 +377,13 @@ function runCompositionPlan(plan, bytes, options, executors) {
 	for (let i = 0; i < plan.hops.length; i++) {
 		const hop = plan.hops[i];
 		if (hop === void 0) throw new Error("runCompositionPlan: resolveCompositionPlan returned a malformed hop");
-		const hopOptions = i === plan.hops.length - 1 ? options : options === void 0 ? void 0 : {
+		const isLastHop = i === plan.hops.length - 1;
+		const readsCallerPdf = i === 0 && hop.from === "pdf";
+		const hopOptions = options === void 0 ? void 0 : {
 			...options,
-			onDocument: void 0
+			onDocument: isLastHop ? options.onDocument : void 0,
+			pages: readsCallerPdf ? options.pages : void 0,
+			surfaces: readsCallerPdf ? options.surfaces : void 0
 		};
 		if (hop.executor === "toPdf") {
 			if (!isSourceContentFormat(hop.from)) throw new Error(`runCompositionPlan: toPdf source '${hop.from}' is not a content format`);

package/dist/convert/composition-plan.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_composition_plan = require("../composition-plan-CfvhXeOC.cjs");
+const require_composition_plan = require("../composition-plan-CSHdRyji.cjs");
 exports.buildCompositionGraph = require_composition_plan.buildCompositionGraph;
 exports.isContentFormat = require_composition_plan.isContentFormat;
 exports.isSourceContentFormat = require_composition_plan.isSourceContentFormat;

package/dist/convert/composition-plan.d.cts

@@ -1,2 +1,2 @@
-import { a as buildCompositionGraph, c as resolveCompositionPlan, i as HopExecutor, l as shortestPath, n as ConversionPlan, o as isContentFormat, r as GraphEdge, s as isSourceContentFormat, t as CompositionHop } from "../composition-plan-DU9nPPN7.cjs";
+import { a as buildCompositionGraph, c as resolveCompositionPlan, i as HopExecutor, l as shortestPath, n as ConversionPlan, o as isContentFormat, r as GraphEdge, s as isSourceContentFormat, t as CompositionHop } from "../composition-plan-D7mR0HWB.cjs";
 export { CompositionHop, ConversionPlan, GraphEdge, HopExecutor, buildCompositionGraph, isContentFormat, isSourceContentFormat, resolveCompositionPlan, shortestPath };

package/dist/convert/composition-plan.d.ts

@@ -1,2 +1,2 @@
-import { a as buildCompositionGraph, c as resolveCompositionPlan, i as HopExecutor, l as shortestPath, n as ConversionPlan, o as isContentFormat, r as GraphEdge, s as isSourceContentFormat, t as CompositionHop } from "../composition-plan-l6QPO4FX.js";
+import { a as buildCompositionGraph, c as resolveCompositionPlan, i as HopExecutor, l as shortestPath, n as ConversionPlan, o as isContentFormat, r as GraphEdge, s as isSourceContentFormat, t as CompositionHop } from "../composition-plan-DPZq6NhK.js";
 export { CompositionHop, ConversionPlan, GraphEdge, HopExecutor, buildCompositionGraph, isContentFormat, isSourceContentFormat, resolveCompositionPlan, shortestPath };

package/dist/convert/composition-plan.js

@@ -1,2 +1,2 @@
-import { a as shortestPath, i as resolveCompositionPlan, n as isContentFormat, r as isSourceContentFormat, t as buildCompositionGraph } from "../composition-plan-f0zaExUW.js";
+import { a as shortestPath, i as resolveCompositionPlan, n as isContentFormat, r as isSourceContentFormat, t as buildCompositionGraph } from "../composition-plan-DQ8lPKIW.js";
 export { buildCompositionGraph, isContentFormat, isSourceContentFormat, resolveCompositionPlan, shortestPath };

package/dist/convert/composition-to-pdf.cjs

@@ -7,7 +7,7 @@ const require_ports_abort = require("../ports/abort.cjs");
 const require_sheets = require("../sheets-BQCpNXsE.cjs");
 const require_layout_drawing = require("../layout/drawing.cjs");
 const require_convert_capability = require("./capability.cjs");
-const require_composition_plan = require("../composition-plan-CfvhXeOC.cjs");
+const require_composition_plan = require("../composition-plan-CSHdRyji.cjs");
 let document_schema_js = require("document-schema.js");
 let pdf_codec = require("pdf-codec");
 //#region src/convert/composition-to-pdf.ts

package/dist/convert/composition-to-pdf.d.cts

@@ -1,5 +1,5 @@
 import { DocumentFormat } from "./port.cjs";
-import { S as SourceContentFormat, T as UnifiedConversionOptions } from "../composition-plan-DU9nPPN7.cjs";
+import { S as SourceContentFormat, T as UnifiedConversionOptions } from "../composition-plan-D7mR0HWB.cjs";
 //#region src/convert/composition-to-pdf.d.ts
 declare function executeToPdf(format: SourceContentFormat, bytes: Uint8Array<ArrayBuffer>, options?: UnifiedConversionOptions): Uint8Array<ArrayBuffer>;
 declare function convertDocument(source: DocumentFormat, target: DocumentFormat, bytes: Uint8Array<ArrayBuffer>, options?: UnifiedConversionOptions): Uint8Array<ArrayBuffer>;

package/dist/convert/composition-to-pdf.d.ts

@@ -1,5 +1,5 @@
 import { DocumentFormat } from "./port.js";
-import { S as SourceContentFormat, T as UnifiedConversionOptions } from "../composition-plan-l6QPO4FX.js";
+import { S as SourceContentFormat, T as UnifiedConversionOptions } from "../composition-plan-DPZq6NhK.js";
 //#region src/convert/composition-to-pdf.d.ts
 declare function executeToPdf(format: SourceContentFormat, bytes: Uint8Array<ArrayBuffer>, options?: UnifiedConversionOptions): Uint8Array<ArrayBuffer>;
 declare function convertDocument(source: DocumentFormat, target: DocumentFormat, bytes: Uint8Array<ArrayBuffer>, options?: UnifiedConversionOptions): Uint8Array<ArrayBuffer>;

package/dist/convert/composition-to-pdf.js

@@ -6,7 +6,7 @@ import { throwIfAborted } from "../ports/abort.js";
 import { l as convertSpreadsheetToLayout } from "../sheets-DWDvGN-g.js";
 import { convertDrawingToLayout } from "../layout/drawing.js";
 import { UnsupportedConversionError } from "./capability.js";
-import { _ as executeFromPdf, b as runCompositionPlan, c as LAYOUT_CAPABLE, d as READ_ONLY_FORMAT_NODES, g as executeBridge, i as resolveCompositionPlan, s as FORMAT_NODES, v as isReadOnlyContentFormat, y as isTextFormatNode } from "../composition-plan-f0zaExUW.js";
+import { _ as executeFromPdf, b as runCompositionPlan, c as LAYOUT_CAPABLE, d as READ_ONLY_FORMAT_NODES, g as executeBridge, i as resolveCompositionPlan, s as FORMAT_NODES, v as isReadOnlyContentFormat, y as isTextFormatNode } from "../composition-plan-DQ8lPKIW.js";
 import { assembleTree } from "document-schema.js";
 import { createFontMeasurer, createFontRegistry, loadMathFont, writePdf } from "pdf-codec";
 //#region src/convert/composition-to-pdf.ts

package/dist/convert/composition.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_composition_plan = require("../composition-plan-CfvhXeOC.cjs");
+const require_composition_plan = require("../composition-plan-CSHdRyji.cjs");
 exports.CONTENT_FORMATS = require_composition_plan.CONTENT_FORMATS;
 exports.FORMAT_NODES = require_composition_plan.FORMAT_NODES;
 exports.LAYOUT_CAPABLE = require_composition_plan.LAYOUT_CAPABLE;

package/dist/convert/composition.d.cts

@@ -1,2 +1,2 @@
-import { A as isTextFormatNode, C as THROUGH_PDF_EDGE_COST, D as executeBridge, E as convertDocumentFromPdf, O as executeFromPdf, S as SourceContentFormat, T as UnifiedConversionOptions, _ as READ_ONLY_CONTENT_FORMATS, b as ReadOnlyContentFormat, d as CompositionExecutorBinding, f as ContentFormat, g as MAX_CONVERSION_PATH_NODES, h as LAYOUT_CAPABLE, j as runCompositionPlan, k as isReadOnlyContentFormat, m as FormatNode, p as FORMAT_NODES, u as CONTENT_FORMATS, v as READ_ONLY_FORMAT_NODES, w as TRANSFORMS, x as ReadOnlyFormatNode, y as RECONSTRUCTORS } from "../composition-plan-DU9nPPN7.cjs";
+import { A as isTextFormatNode, C as THROUGH_PDF_EDGE_COST, D as executeBridge, E as convertDocumentFromPdf, O as executeFromPdf, S as SourceContentFormat, T as UnifiedConversionOptions, _ as READ_ONLY_CONTENT_FORMATS, b as ReadOnlyContentFormat, d as CompositionExecutorBinding, f as ContentFormat, g as MAX_CONVERSION_PATH_NODES, h as LAYOUT_CAPABLE, j as runCompositionPlan, k as isReadOnlyContentFormat, m as FormatNode, p as FORMAT_NODES, u as CONTENT_FORMATS, v as READ_ONLY_FORMAT_NODES, w as TRANSFORMS, x as ReadOnlyFormatNode, y as RECONSTRUCTORS } from "../composition-plan-D7mR0HWB.cjs";
 export { CONTENT_FORMATS, CompositionExecutorBinding, ContentFormat, FORMAT_NODES, FormatNode, LAYOUT_CAPABLE, MAX_CONVERSION_PATH_NODES, READ_ONLY_CONTENT_FORMATS, READ_ONLY_FORMAT_NODES, RECONSTRUCTORS, ReadOnlyContentFormat, ReadOnlyFormatNode, SourceContentFormat, THROUGH_PDF_EDGE_COST, TRANSFORMS, UnifiedConversionOptions, convertDocumentFromPdf, executeBridge, executeFromPdf, isReadOnlyContentFormat, isTextFormatNode, runCompositionPlan };

package/dist/convert/composition.d.ts

@@ -1,2 +1,2 @@
-import { A as isTextFormatNode, C as THROUGH_PDF_EDGE_COST, D as executeBridge, E as convertDocumentFromPdf, O as executeFromPdf, S as SourceContentFormat, T as UnifiedConversionOptions, _ as READ_ONLY_CONTENT_FORMATS, b as ReadOnlyContentFormat, d as CompositionExecutorBinding, f as ContentFormat, g as MAX_CONVERSION_PATH_NODES, h as LAYOUT_CAPABLE, j as runCompositionPlan, k as isReadOnlyContentFormat, m as FormatNode, p as FORMAT_NODES, u as CONTENT_FORMATS, v as READ_ONLY_FORMAT_NODES, w as TRANSFORMS, x as ReadOnlyFormatNode, y as RECONSTRUCTORS } from "../composition-plan-l6QPO4FX.js";
+import { A as isTextFormatNode, C as THROUGH_PDF_EDGE_COST, D as executeBridge, E as convertDocumentFromPdf, O as executeFromPdf, S as SourceContentFormat, T as UnifiedConversionOptions, _ as READ_ONLY_CONTENT_FORMATS, b as ReadOnlyContentFormat, d as CompositionExecutorBinding, f as ContentFormat, g as MAX_CONVERSION_PATH_NODES, h as LAYOUT_CAPABLE, j as runCompositionPlan, k as isReadOnlyContentFormat, m as FormatNode, p as FORMAT_NODES, u as CONTENT_FORMATS, v as READ_ONLY_FORMAT_NODES, w as TRANSFORMS, x as ReadOnlyFormatNode, y as RECONSTRUCTORS } from "../composition-plan-DPZq6NhK.js";
 export { CONTENT_FORMATS, CompositionExecutorBinding, ContentFormat, FORMAT_NODES, FormatNode, LAYOUT_CAPABLE, MAX_CONVERSION_PATH_NODES, READ_ONLY_CONTENT_FORMATS, READ_ONLY_FORMAT_NODES, RECONSTRUCTORS, ReadOnlyContentFormat, ReadOnlyFormatNode, SourceContentFormat, THROUGH_PDF_EDGE_COST, TRANSFORMS, UnifiedConversionOptions, convertDocumentFromPdf, executeBridge, executeFromPdf, isReadOnlyContentFormat, isTextFormatNode, runCompositionPlan };

package/dist/convert/composition.js

@@ -1,2 +1,2 @@
-import { _ as executeFromPdf, b as runCompositionPlan, c as LAYOUT_CAPABLE, d as READ_ONLY_FORMAT_NODES, f as RECONSTRUCTORS, g as executeBridge, h as convertDocumentFromPdf, l as MAX_CONVERSION_PATH_NODES, m as TRANSFORMS, o as CONTENT_FORMATS, p as THROUGH_PDF_EDGE_COST, s as FORMAT_NODES, u as READ_ONLY_CONTENT_FORMATS, v as isReadOnlyContentFormat, y as isTextFormatNode } from "../composition-plan-f0zaExUW.js";
+import { _ as executeFromPdf, b as runCompositionPlan, c as LAYOUT_CAPABLE, d as READ_ONLY_FORMAT_NODES, f as RECONSTRUCTORS, g as executeBridge, h as convertDocumentFromPdf, l as MAX_CONVERSION_PATH_NODES, m as TRANSFORMS, o as CONTENT_FORMATS, p as THROUGH_PDF_EDGE_COST, s as FORMAT_NODES, u as READ_ONLY_CONTENT_FORMATS, v as isReadOnlyContentFormat, y as isTextFormatNode } from "../composition-plan-DQ8lPKIW.js";
 export { CONTENT_FORMATS, FORMAT_NODES, LAYOUT_CAPABLE, MAX_CONVERSION_PATH_NODES, READ_ONLY_CONTENT_FORMATS, READ_ONLY_FORMAT_NODES, RECONSTRUCTORS, THROUGH_PDF_EDGE_COST, TRANSFORMS, convertDocumentFromPdf, executeBridge, executeFromPdf, isReadOnlyContentFormat, isTextFormatNode, runCompositionPlan };

package/dist/convert/from-package.cjs

@@ -15,7 +15,7 @@ let pdf_codec = require("pdf-codec");
 //#region src/convert/from-package.ts
 function buildDocumentBytes(pkg, target) {
 	if (target === "pdf") {
-		if (pkg.pages === void 0) throw new Error("this DocumentTree has no pages — only a package dumped from a <format>-to-pdf or pdf-to-<format> conversion carries them; a bridge conversion's own dump (e.g. odt-to-docx) never does, so 'pdf' is not a reachable target from it");
+		if (pkg.pages === void 0) throw new Error("this DocumentTree has no pages, so 'pdf' is not a reachable target from it: only a package dumped from a <format>-to-pdf conversion or a full pdf-to-<format> conversion carries them. A bridge conversion's own dump (e.g. odt-to-docx) never does, and neither does a page-selected pdf-to-<format> conversion's, whose frames name source page indices a pages array of only the selection could not be indexed by");
 		const { document: layout, formulas, fonts } = packageToLayout(pkg);
 		return (0, pdf_codec.writePdf)(layout, formulas.length > 0 ? {
 			formulas,

package/dist/convert/from-package.js

@@ -14,7 +14,7 @@ import { LAYOUT_FORMAT_VERSION, createFontMeasurer, createFontRegistry, loadMath
 //#region src/convert/from-package.ts
 function buildDocumentBytes(pkg, target) {
 	if (target === "pdf") {
-		if (pkg.pages === void 0) throw new Error("this DocumentTree has no pages — only a package dumped from a <format>-to-pdf or pdf-to-<format> conversion carries them; a bridge conversion's own dump (e.g. odt-to-docx) never does, so 'pdf' is not a reachable target from it");
+		if (pkg.pages === void 0) throw new Error("this DocumentTree has no pages, so 'pdf' is not a reachable target from it: only a package dumped from a <format>-to-pdf conversion or a full pdf-to-<format> conversion carries them. A bridge conversion's own dump (e.g. odt-to-docx) never does, and neither does a page-selected pdf-to-<format> conversion's, whose frames name source page indices a pages array of only the selection could not be indexed by");
 		const { document: layout, formulas, fonts } = packageToLayout(pkg);
 		return writePdf(layout, formulas.length > 0 ? {
 			formulas,

package/dist/convert/from-pdf.cjs

@@ -1,20 +1,34 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_reconstruct_presentations_prod = require("../reconstruct-presentations-prod-X315aBmI.cjs");
+const require_reconstruct_presentations_prod = require("../reconstruct-presentations-prod-CA4no_aw.cjs");
 const require_convert_pdf_package_tables = require("./pdf-package-tables.cjs");
-const require_composition_plan = require("../composition-plan-CfvhXeOC.cjs");
+const require_composition_plan = require("../composition-plan-CSHdRyji.cjs");
 const require_codecs_read = require("../codecs/read.cjs");
 let document_schema_js = require("document-schema.js");
 let pdf_codec_read = require("pdf-codec/read");
 //#region src/convert/from-pdf.ts
+const METADATA_SURFACES = {
+	outline: false,
+	destinations: false,
+	form: false,
+	layers: false,
+	structure: false,
+	residue: false
+};
 function readDocumentMetadata(format, bytes, options) {
-	if (format === "pdf") return require_codecs_read.readDocumentLayout(bytes, { signal: options?.signal }).metadata;
+	if (format === "pdf") return (0, pdf_codec_read.readPdf)(bytes, {
+		signal: options?.signal,
+		pages: [],
+		surfaces: METADATA_SURFACES
+	}).metadata;
 	return require_codecs_read.CONTENT_READERS[format](bytes, { signal: options?.signal }).metadata;
 }
 function readNativeContent(format, bytes, options) {
 	if (format === "pdf") {
 		const layout = (0, pdf_codec_read.readPdf)(bytes, {
 			signal: options?.signal,
-			sink: options?.sink
+			sink: options?.sink,
+			pages: options?.pages,
+			surfaces: options?.surfaces
 		});
 		return {
 			content: require_reconstruct_presentations_prod.reconstructWordprocessing(layout, { signal: options?.signal }),
@@ -29,10 +43,10 @@ function readNativeContent(format, bytes, options) {
 function readNativeDocumentTree(format, bytes, options) {
 	const { content, layout } = readNativeContent(format, bytes, options);
 	if (layout !== void 0) {
-		const pages = layout.pages.map((page) => ({
+		const pages = options?.pages === void 0 ? layout.pages.map((page) => ({
 			widthPt: page.widthPt,
 			heightPt: page.heightPt
-		}));
+		})) : void 0;
 		const reported = (0, document_schema_js.assembleTree)(content, pages);
 		require_convert_pdf_package_tables.stampPdfPackageTables(reported, layout);
 		return reported;

package/dist/convert/from-pdf.d.cts

@@ -3,6 +3,7 @@ import { CsvWriteOptions, SvgWriteOptions } from "./convert.cjs";
 import { ContentDocument, DocumentTree, LayoutMetadata } from "document-schema.js";
 import { PdfDiagnosticSink } from "pdf-codec";
 import { MarkdownImageResolver } from "markdown-codec";
+import { ReadPdfSurfaces } from "pdf-codec/read";
 //#region src/convert/from-pdf.d.ts
 interface ReadDocumentMetadataOptions {
   readonly signal?: AbortSignal;
@@ -12,6 +13,14 @@ interface ReadNativeDocumentTreeOptions {
   readonly signal?: AbortSignal;
   readonly images?: MarkdownImageResolver;
   readonly sink?: PdfDiagnosticSink;
+  /**
+   * The pages of a pdf source to read, exactly as UnifiedConversionOptions.pages describes them (zero-based, negative from the end, document order, `PdfPageSelectionError` for an index naming no page). Consulted only for a pdf source, since no other format's reader has pages to select. The unselected pages' content streams, the fonts and images only they use, and the source's embedded files are never read, and the selected pages are reconstructed from themselves alone (see PdfToDocumentOptions.pages for how that can change a cover page's headings). Every frame in the result names the page's index in the source PDF, so a DocumentTree read this way carries no `pages` envelope: that array is indexed by those source indices and a selection cannot fill it.
+   */
+  readonly pages?: readonly number[];
+  /**
+   * The document-level surfaces of a pdf source to read, exactly as UnifiedConversionOptions.surfaces describes them: one boolean per surface, each read unless set to `false`, independent of `pages`. Consulted only for a pdf source. A skipped surface is absent from the read, so the tree carries nothing built from it (see UnifiedConversionOptions.surfaces for exactly what: `outline-N` entries in `destinations`, destinations and internal link constructs, form `contentControl` constructs, the layers table, structure entries in `definitions`, residue), and reconstruction loses what it took from it: without `structure` a tagged PDF's headings, table cells and divisions are inferred from geometry, and without `layers` hidden-layer content is kept as if visible.
+   */
+  readonly surfaces?: ReadPdfSurfaces;
 }
 type ReadContentDocumentOptions = ReadNativeDocumentTreeOptions;
 declare function readNativeDocumentTree(format: DocumentFormat, bytes: Uint8Array<ArrayBuffer>, options?: ReadNativeDocumentTreeOptions): DocumentTree;
@@ -19,6 +28,16 @@ declare function readContentDocument(format: DocumentFormat, bytes: Uint8Array<A
 interface PdfToDocumentOptions {
   readonly signal?: AbortSignal;
   readonly sink?: PdfDiagnosticSink;
+  /**
+   * The pages to convert, exactly as UnifiedConversionOptions.pages describes them: zero-based page-tree indices, a negative index counted from the end, duplicates collapsed, document order, and `PdfPageSelectionError` for an index naming no page. The unselected pages' content streams, the fonts and images only they use, and the source's embedded files are never read. pdfToMarkdown labels each page it writes with its original one-based page number (`<!-- page 7 -->`), so the text says which pages it holds.
+   *
+   * Reconstruction sees only the selected pages, so a page can come out differently than it would in a full conversion. Heading detection measures text against the body size, taken as the most common size across the pages read: a cover page read on its own, dominated by large title text, takes the title's size as its body, and the title is then a paragraph rather than a heading. Reading the cover together with a few ordinary pages restores the document's real body size.
+   */
+  readonly pages?: readonly number[];
+  /**
+   * The document-level surfaces to read, exactly as UnifiedConversionOptions.surfaces describes them: one boolean per surface (`outline`, `destinations`, `form`, `layers`, `structure`, `residue`), each read unless set to `false`, independent of `pages`. A skipped surface is never parsed, and the conversion carries nothing built from it. Without `structure` a tagged PDF's headings, table cells and divisions are inferred from geometry as for an untagged file, and without `layers` content the default view hides is kept as if visible.
+   */
+  readonly surfaces?: ReadPdfSurfaces;
   readonly onDocument?: (pkg: DocumentTree) => void;
 }
 declare function pdfToDocx(bytes: Uint8Array<ArrayBuffer>, options?: PdfToDocumentOptions): Uint8Array<ArrayBuffer>;

package/dist/convert/from-pdf.d.ts

@@ -3,6 +3,7 @@ import { CsvWriteOptions, SvgWriteOptions } from "./convert.js";
 import { ContentDocument, DocumentTree, LayoutMetadata } from "document-schema.js";
 import { PdfDiagnosticSink } from "pdf-codec";
 import { MarkdownImageResolver } from "markdown-codec";
+import { ReadPdfSurfaces } from "pdf-codec/read";
 //#region src/convert/from-pdf.d.ts
 interface ReadDocumentMetadataOptions {
   readonly signal?: AbortSignal;
@@ -12,6 +13,14 @@ interface ReadNativeDocumentTreeOptions {
   readonly signal?: AbortSignal;
   readonly images?: MarkdownImageResolver;
   readonly sink?: PdfDiagnosticSink;
+  /**
+   * The pages of a pdf source to read, exactly as UnifiedConversionOptions.pages describes them (zero-based, negative from the end, document order, `PdfPageSelectionError` for an index naming no page). Consulted only for a pdf source, since no other format's reader has pages to select. The unselected pages' content streams, the fonts and images only they use, and the source's embedded files are never read, and the selected pages are reconstructed from themselves alone (see PdfToDocumentOptions.pages for how that can change a cover page's headings). Every frame in the result names the page's index in the source PDF, so a DocumentTree read this way carries no `pages` envelope: that array is indexed by those source indices and a selection cannot fill it.
+   */
+  readonly pages?: readonly number[];
+  /**
+   * The document-level surfaces of a pdf source to read, exactly as UnifiedConversionOptions.surfaces describes them: one boolean per surface, each read unless set to `false`, independent of `pages`. Consulted only for a pdf source. A skipped surface is absent from the read, so the tree carries nothing built from it (see UnifiedConversionOptions.surfaces for exactly what: `outline-N` entries in `destinations`, destinations and internal link constructs, form `contentControl` constructs, the layers table, structure entries in `definitions`, residue), and reconstruction loses what it took from it: without `structure` a tagged PDF's headings, table cells and divisions are inferred from geometry, and without `layers` hidden-layer content is kept as if visible.
+   */
+  readonly surfaces?: ReadPdfSurfaces;
 }
 type ReadContentDocumentOptions = ReadNativeDocumentTreeOptions;
 declare function readNativeDocumentTree(format: DocumentFormat, bytes: Uint8Array<ArrayBuffer>, options?: ReadNativeDocumentTreeOptions): DocumentTree;
@@ -19,6 +28,16 @@ declare function readContentDocument(format: DocumentFormat, bytes: Uint8Array<A
 interface PdfToDocumentOptions {
   readonly signal?: AbortSignal;
   readonly sink?: PdfDiagnosticSink;
+  /**
+   * The pages to convert, exactly as UnifiedConversionOptions.pages describes them: zero-based page-tree indices, a negative index counted from the end, duplicates collapsed, document order, and `PdfPageSelectionError` for an index naming no page. The unselected pages' content streams, the fonts and images only they use, and the source's embedded files are never read. pdfToMarkdown labels each page it writes with its original one-based page number (`<!-- page 7 -->`), so the text says which pages it holds.
+   *
+   * Reconstruction sees only the selected pages, so a page can come out differently than it would in a full conversion. Heading detection measures text against the body size, taken as the most common size across the pages read: a cover page read on its own, dominated by large title text, takes the title's size as its body, and the title is then a paragraph rather than a heading. Reading the cover together with a few ordinary pages restores the document's real body size.
+   */
+  readonly pages?: readonly number[];
+  /**
+   * The document-level surfaces to read, exactly as UnifiedConversionOptions.surfaces describes them: one boolean per surface (`outline`, `destinations`, `form`, `layers`, `structure`, `residue`), each read unless set to `false`, independent of `pages`. A skipped surface is never parsed, and the conversion carries nothing built from it. Without `structure` a tagged PDF's headings, table cells and divisions are inferred from geometry as for an untagged file, and without `layers` content the default view hides is kept as if visible.
+   */
+  readonly surfaces?: ReadPdfSurfaces;
   readonly onDocument?: (pkg: DocumentTree) => void;
 }
 declare function pdfToDocx(bytes: Uint8Array<ArrayBuffer>, options?: PdfToDocumentOptions): Uint8Array<ArrayBuffer>;