pdf-codec 4.3.0 → 4.4.0

package/README.md

@@ -234,7 +234,7 @@ The package is layered from generic primitives outward to the codec itself:
 - **`src/util/`** — two small independently-duplicated copies of family-shared logic: `base64.ts` (verbatim copy of `odf.js`'s own, replacing a former `ooxml.js` dependency for this one helper) and `abort.ts` (`throwIfAborted`, called at every page loop boundary — there is no `await` point in this synchronous pipeline for cancellation to hook into implicitly).
 - **`src/crypto/`** — MD5, SHA-256/384/512, RC4, and AES-CBC, hand-written with zero local imports, plus a thin `random.ts` wrapper around `globalThis.crypto.getRandomValues` for the writer's own salts/file keys/IVs. Not a preference: ISO 32000-1's key-derivation algorithms name MD5 and RC4 directly, neither offered by any portable platform crypto API, and `crypto.subtle` is asynchronous where this codec's read and write paths are both synchronous end to end — `getRandomValues` itself, unlike `crypto.subtle`, is synchronous and portable, so it is used directly rather than hand-written. Reaching for `node:crypto` would break the browser bundle. Each hash/cipher module cites its specification (RFC 1321, FIPS 180-4, FIPS 197) and is tested against published conformance vectors.
 - **The codec itself, importing only `layout`/`bytes`/`image`/`crypto`/`util` plus `document-schema.js`'s port types (no OOXML or ODF knowledge):**
-  - **Write**: `objects.ts` (the `PdfObject` discriminated union), `afm-widths.ts`/`encoding.ts`/`winansi.ts`/`fonts.ts` (standard-14 metrics, WinAnsi encoding, family resolution), `font-registry.ts` (resolution port plus `resolveFaceWithRegistry`, the one step both measurer and writer resolve through so they can never disagree about which face a `LayoutFont` means), `font-face.ts` (`readFontFace`, reading a standalone font file's family/bold/italic triple off its `name`/`OS/2`/`head` tables), `measure.ts`/`text-layout.ts` (greedy line-wrapping against either standard-14 AFM widths plus per-family correction or a resolved face's own real `hmtx` advances — never both), `content-write.ts` (`LayoutItem[]` → content-stream operators, with text branching on standard-14 vs embedded face encoding, pair-kerning split into `TJ` arrays, and stroke `style` becoming real dash/line-cap state), `write.ts` (the full object graph, cross-reference table, trailer, and embedded font groups).
+  - **Write**: `objects.ts` (the `PdfObject` discriminated union), `afm-widths.ts`/`encoding.ts`/`winansi.ts`/`fonts.ts` (standard-14 metrics, WinAnsi encoding, family resolution), `font-registry.ts` (resolution port plus `resolveFaceWithRegistry`, the one step both measurer and writer resolve through so they can never disagree about which face a `LayoutFont` means), `font-face.ts` (`readFontFace`, reading a standalone font file's family/bold/italic triple off its `name`/`OS/2`/`head` tables), `measure.ts`/`text-layout.ts` (greedy line-wrapping against either standard-14 AFM widths plus per-family correction or a resolved face's own real `hmtx` advances — never both), `content-write.ts` (`LayoutItem[]` → content-stream operators, with text branching on standard-14 vs embedded face encoding, pair-kerning split into `TJ` arrays, stroke `style` becoming real dash/line-cap state, and `/P <</MCID n /OC R>> BDC`…`EMC` spans around items carrying a structure owner or an optional-content layer — the one marked-content spelling both read-side channels resolve through), `write.ts` (the full object graph, cross-reference table, trailer, and embedded font groups, plus the document-level round-trip surfaces: the `/Names /EmbeddedFiles` attachments tree and `/Outlines` bookmark tree, `/OCProperties` optional-content groups with each layer stated explicitly into the default configuration's `/ON` or `/OFF` list, the `/AcroForm` field tree with the merged-field/widget spelling (a single widget merges into its field dict; further widgets are separate `/Subtype /Widget` kids, and fully-qualified names decompose back into the `/T` chain), the `/StructTreeRoot` element tree with its `/ParentTree` number tree associating each marked item's MCID to its owning element, and the package-level residue rows restored inline onto the Catalog or trailer — the XMP packet as an uncompressed `/Metadata` stream, and any row whose serialisation references source-file objects skipped rather than emitted as a dangling reference).
   - **sfnt font tables**: `sfnt.ts` (bounds-checked table-directory reader), `cmap-table.ts` (character code → glyph ID, formats 0/4/6/12, exposed both as the best Unicode lookup and as every subtable individually, since a (3, 0) or (1, 0) subtable is keyed by a font's own codes rather than by code points), `hmtx-table.ts` (per-glyph advance widths), `font-tables.ts` (`head`/`maxp`/`OS/2`/`post`/`name`, including `post`'s own glyph names where a font still carries them), `glyf.ts` (`loca` offset index, per-glyph headers, composite component records, `glyphInkBounds`), `math-table.ts` (OpenType `MATH` constants/glyph-info/variants subtables). `ot-layout-common.ts` (Coverage/ClassDef, stored as sorted glyph ranges searched by bisection). `gpos-table.ts` reads `GPOS` for exactly one thing: pair-advance kerning through the `kern` feature, both PairPos formats and LookupType 9 Extension indirection — mark attachment, cursive joining, and contextual positioning have no consumer here. Every parser degrades to `undefined` on a missing/truncated table rather than throwing.
   - **sfnt subsetting**: `sfnt-subset.ts` — a TrueType-outline glyph subsetter (Unicode code points → glyph IDs via `cmap`, transitive closure over `glyf` composite components, rebuilt sfnt carrying only used outlines). **Glyph IDs are preserved, never renumbered**, keeping composite component references valid and making CID == GID trivially true. Output rebuilds `head`/`hhea`/`maxp`/`loca`/`glyf`/`hmtx`, copies hinting programs verbatim, stubs `post`, omits `cmap`/`name`/`OS/2`/`GSUB`/`GPOS`/`kern` (none read through a `CIDFontType2` program per ISO 32000-1 9.9). Applies to `glyf`-flavoured fonts only; CFF returns `undefined`.
   - **Embedded math font**: `math-font.ts` (parses/caches the vendored STIX Two Math font, exposing size-specific `MathFontMetrics` and stretchy-glyph entry points), `math-stretch.ts` (OpenType MATH two-stage stretching: pick smallest pre-built variant reaching target, else assemble from repeated parts with seams overlapped), `math-font-write.ts` (builds the `/Type0`/`/CIDFontType0`/`/FontDescriptor`/`/FontFile3`/ToUnicode group), `math-content-write.ts` (`PositionedFormula[]` → content-stream bytes, Identity-H CIDs for text, `re`/`m`/`l` operators for rules, glyph-ID-addressed text objects for stretched constructions wrapped in `/ActualText`).

package/dist/content-write.cjs

@@ -313,16 +313,38 @@ function writeContentStream(items, context) {
 	const writer = new require_bytes_writer.ByteWriter();
 	const substitutions = [];
 	const missingGlyphs = [];
-	for (const item of items) if (item.kind === "text") writeText(writer, item, context, substitutions, missingGlyphs);
-	else if (item.kind === "image") writeImage(writer, item, context);
-	else if (item.kind === "rect") writeRect(writer, item);
-	else if (item.kind === "line") writeLine(writer, item);
-	else if (item.kind === "ellipse") writeEllipse(writer, item);
-	else if (item.kind === "path") writePath(writer, item);
+	const markedStructure = [];
+	for (const item of items) {
+		const itemLayer = "layer" in item ? item.layer : void 0;
+		const itemStructure = "structure" in item ? item.structure : void 0;
+		const layerObjectNum = itemLayer !== void 0 ? context.layerObjectNumberOf?.(itemLayer) : void 0;
+		const marked = itemStructure !== void 0 || layerObjectNum !== void 0;
+		if (marked) {
+			writer.writeAscii("/P <<");
+			if (itemStructure !== void 0 && context.nextMcid !== void 0) {
+				const mcid = context.nextMcid();
+				markedStructure.push({
+					mcid,
+					structureId: itemStructure
+				});
+				writer.writeAscii(` /MCID ${mcid}`);
+			}
+			if (layerObjectNum !== void 0) writer.writeAscii(` /OC ${layerObjectNum} 0 R`);
+			writer.writeAscii(" >> BDC\n");
+		}
+		if (item.kind === "text") writeText(writer, item, context, substitutions, missingGlyphs);
+		else if (item.kind === "image") writeImage(writer, item, context);
+		else if (item.kind === "rect") writeRect(writer, item);
+		else if (item.kind === "line") writeLine(writer, item);
+		else if (item.kind === "ellipse") writeEllipse(writer, item);
+		else if (item.kind === "path") writePath(writer, item);
+		if (marked) writer.writeAscii("EMC\n");
+	}
 	return {
 		bytes: writer.toBytes(),
 		substitutions,
-		missingGlyphs
+		missingGlyphs,
+		markedStructure
 	};
 }
 //#endregion

package/dist/content-write.d.cts

@@ -20,12 +20,19 @@ interface ContentWriteContext {
   readonly measurer: TextMeasurer;
   resolveFont(font: LayoutFont): ResolvedFontResource;
   resolveImage(imageId: string): ResolvedImageResource;
+  readonly layerObjectNumberOf?: (name: string) => number | undefined;
+  readonly nextMcid?: () => number;
 }
 interface ContentStreamResult {
   readonly bytes: Uint8Array<ArrayBuffer>;
+  readonly markedStructure: readonly MarkedStructureItem[];
   readonly substitutions: readonly WinAnsiSubstitution[];
   readonly missingGlyphs: readonly EmbeddedFaceSubstitution[];
 }
 declare function writeContentStream(items: readonly LayoutItem[], context: ContentWriteContext): ContentStreamResult;
+interface MarkedStructureItem {
+  readonly mcid: number;
+  readonly structureId: string;
+}
 //#endregion
-export { ContentStreamResult, ContentWriteContext, ResolvedFontResource, ResolvedImageResource, writeContentStream };
+export { ContentStreamResult, ContentWriteContext, MarkedStructureItem, ResolvedFontResource, ResolvedImageResource, writeContentStream };

package/dist/content-write.d.ts

@@ -20,12 +20,19 @@ interface ContentWriteContext {
   readonly measurer: TextMeasurer;
   resolveFont(font: LayoutFont): ResolvedFontResource;
   resolveImage(imageId: string): ResolvedImageResource;
+  readonly layerObjectNumberOf?: (name: string) => number | undefined;
+  readonly nextMcid?: () => number;
 }
 interface ContentStreamResult {
   readonly bytes: Uint8Array<ArrayBuffer>;
+  readonly markedStructure: readonly MarkedStructureItem[];
   readonly substitutions: readonly WinAnsiSubstitution[];
   readonly missingGlyphs: readonly EmbeddedFaceSubstitution[];
 }
 declare function writeContentStream(items: readonly LayoutItem[], context: ContentWriteContext): ContentStreamResult;
+interface MarkedStructureItem {
+  readonly mcid: number;
+  readonly structureId: string;
+}
 //#endregion
-export { ContentStreamResult, ContentWriteContext, ResolvedFontResource, ResolvedImageResource, writeContentStream };
+export { ContentStreamResult, ContentWriteContext, MarkedStructureItem, ResolvedFontResource, ResolvedImageResource, writeContentStream };

package/dist/content-write.js

@@ -312,16 +312,38 @@ function writeContentStream(items, context) {
 	const writer = new ByteWriter();
 	const substitutions = [];
 	const missingGlyphs = [];
-	for (const item of items) if (item.kind === "text") writeText(writer, item, context, substitutions, missingGlyphs);
-	else if (item.kind === "image") writeImage(writer, item, context);
-	else if (item.kind === "rect") writeRect(writer, item);
-	else if (item.kind === "line") writeLine(writer, item);
-	else if (item.kind === "ellipse") writeEllipse(writer, item);
-	else if (item.kind === "path") writePath(writer, item);
+	const markedStructure = [];
+	for (const item of items) {
+		const itemLayer = "layer" in item ? item.layer : void 0;
+		const itemStructure = "structure" in item ? item.structure : void 0;
+		const layerObjectNum = itemLayer !== void 0 ? context.layerObjectNumberOf?.(itemLayer) : void 0;
+		const marked = itemStructure !== void 0 || layerObjectNum !== void 0;
+		if (marked) {
+			writer.writeAscii("/P <<");
+			if (itemStructure !== void 0 && context.nextMcid !== void 0) {
+				const mcid = context.nextMcid();
+				markedStructure.push({
+					mcid,
+					structureId: itemStructure
+				});
+				writer.writeAscii(` /MCID ${mcid}`);
+			}
+			if (layerObjectNum !== void 0) writer.writeAscii(` /OC ${layerObjectNum} 0 R`);
+			writer.writeAscii(" >> BDC\n");
+		}
+		if (item.kind === "text") writeText(writer, item, context, substitutions, missingGlyphs);
+		else if (item.kind === "image") writeImage(writer, item, context);
+		else if (item.kind === "rect") writeRect(writer, item);
+		else if (item.kind === "line") writeLine(writer, item);
+		else if (item.kind === "ellipse") writeEllipse(writer, item);
+		else if (item.kind === "path") writePath(writer, item);
+		if (marked) writer.writeAscii("EMC\n");
+	}
 	return {
 		bytes: writer.toBytes(),
 		substitutions,
-		missingGlyphs
+		missingGlyphs,
+		markedStructure
 	};
 }
 //#endregion

package/dist/write.cjs

@@ -4,8 +4,10 @@ const require_notes_annotation_author = require("./notes-annotation-author.cjs")
 const require_objects = require("./objects.cjs");
 const require_bytes_writer = require("./bytes/writer.cjs");
 const require_serialize = require("./serialize.cjs");
+const require_bytes_reader = require("./bytes/reader.cjs");
 const require_bytes_flate = require("./bytes/flate.cjs");
 const require_util_base64 = require("./util/base64.cjs");
+const require_parse = require("./parse.cjs");
 const require_util_abort = require("./util/abort.cjs");
 const require_crypto_random = require("./crypto/random.cjs");
 const require_encrypt_write = require("./encrypt-write.cjs");
@@ -252,6 +254,24 @@ function buildNotesAnnotDict(notes) {
 function xrefEntry(offset, generation, inUse) {
 	return `${offset.toString().padStart(10, "0")} ${generation.toString().padStart(5, "0")} ${inUse ? "n" : "f"} \n`;
 }
+function parseResidueRow(residue) {
+	const reader = new require_bytes_reader.ByteReader(new TextEncoder().encode(residue.xml));
+	return require_parse.parseValue(reader, () => {});
+}
+function objectContainsReference(obj) {
+	if (obj.kind === "ref") return true;
+	if (obj.kind === "array") return obj.items.some(objectContainsReference);
+	if (obj.kind === "dict") return [...obj.entries.values()].some(objectContainsReference);
+	if (obj.kind === "stream") return [...obj.dict.entries.values()].some(objectContainsReference);
+	return false;
+}
+function restoreResidueRow(source, key) {
+	const row = source?.[key];
+	if (row === void 0) return;
+	const parsed = parseResidueRow(row);
+	if (parsed === void 0 || objectContainsReference(parsed)) return;
+	return parsed;
+}
 function writePdf(doc, options = {}) {
 	const compress = options.compress ?? true;
 	const registry = options.fonts;
@@ -340,10 +360,80 @@ function writePdf(doc, options = {}) {
 		};
 		for (let i = 0; i < countItems(doc.outline ?? []); i += 1) outlineItemNums.push(nextObjNum++);
 	}
+	const layerNumByName = /* @__PURE__ */ new Map();
+	for (const layer of doc.layers ?? []) layerNumByName.set(layer.name, nextObjNum++);
+	const formObjectNums = [];
+	const countFieldObjects = (fields) => {
+		let n = 0;
+		for (const field of fields) n += 1 + (field.fieldType !== "group" && field.widgets.length > 1 ? field.widgets.length - 1 : 0) + countFieldObjects(field.children);
+		return n;
+	};
+	for (let i = 0; i < countFieldObjects(doc.form ?? []); i += 1) formObjectNums.push(nextObjNum++);
+	const formNumByField = /* @__PURE__ */ new Map();
+	const formExtraWidgetNums = /* @__PURE__ */ new Map();
+	let formNumCursor = 0;
+	const claimFormNums = (fields) => {
+		for (const field of fields) {
+			formNumByField.set(field, formObjectNums[formNumCursor++]);
+			if (field.fieldType !== "group" && field.widgets.length > 1) formExtraWidgetNums.set(field, field.widgets.slice(1).map(() => formObjectNums[formNumCursor++]));
+			claimFormNums(field.children);
+		}
+	};
+	claimFormNums(doc.form ?? []);
+	const formNumOf = (field) => {
+		const num = formNumByField.get(field);
+		if (num === void 0) throw new Error("AcroForm field object number was not claimed -- this is a writePdf internal invariant violation");
+		return num;
+	};
+	const structElementNumById = /* @__PURE__ */ new Map();
+	const countElements = (elements) => {
+		let n = 0;
+		for (const element of elements) {
+			structElementNumById.set(element.id, nextObjNum++);
+			n += 1 + countElements(element.children);
+		}
+		return n;
+	};
+	const structElementCount = countElements(doc.structure ?? []);
+	const structRootNum = structElementCount > 0 ? nextObjNum++ : void 0;
+	const structParentTreeNum = structElementCount > 0 ? nextObjNum++ : void 0;
+	const residueXmpNum = doc.source?.xmp !== void 0 ? nextObjNum++ : void 0;
 	const objects = [];
 	const catalogEntries = [["Type", require_objects.pdfName("Catalog")], ["Pages", require_objects.pdfRef(pagesNum, 0)]];
 	if (attachmentsNamesNum !== void 0) catalogEntries.push(["Names", require_objects.pdfRef(attachmentsNamesNum, 0)]);
 	if (outlineRootNum !== void 0) catalogEntries.push(["Outlines", require_objects.pdfRef(outlineRootNum, 0)]);
+	if (layerNumByName.size > 0) {
+		const ocgRefs = [...layerNumByName.values()].map((num) => require_objects.pdfRef(num, 0));
+		const visible = [];
+		const hidden = [];
+		for (const layer of doc.layers ?? []) {
+			const num = layerNumByName.get(layer.name);
+			(layer.visible ? visible : hidden).push(require_objects.pdfRef(num, 0));
+		}
+		const defaultConfigEntries = [];
+		if (visible.length > 0) defaultConfigEntries.push(["ON", require_objects.pdfArray(visible)]);
+		if (hidden.length > 0) defaultConfigEntries.push(["OFF", require_objects.pdfArray(hidden)]);
+		catalogEntries.push(["OCProperties", require_objects.pdfDict({
+			OCGs: require_objects.pdfArray(ocgRefs),
+			D: require_objects.pdfDict(Object.fromEntries(defaultConfigEntries))
+		})]);
+	}
+	if (doc.form !== void 0 && doc.form.length > 0) catalogEntries.push(["AcroForm", require_objects.pdfDict({ Fields: require_objects.pdfArray(doc.form.map((field) => require_objects.pdfRef(formNumOf(field), 0))) })]);
+	if (structRootNum !== void 0) catalogEntries.push(["StructTreeRoot", require_objects.pdfRef(structRootNum, 0)]);
+	if (residueXmpNum !== void 0) catalogEntries.push(["Metadata", require_objects.pdfRef(residueXmpNum, 0)]);
+	const trailerIdRestore = restoreResidueRow(doc.source, "trailer-id");
+	for (const [rowKey, catalogKey] of [
+		["viewer-preferences", "ViewerPreferences"],
+		["page-mode", "PageMode"],
+		["page-layout", "PageLayout"],
+		["output-intents", "OutputIntents"],
+		["piece-info", "PieceInfo"],
+		["legal", "Legal"],
+		["collection", "Collection"]
+	]) {
+		const restored = restoreResidueRow(doc.source, rowKey);
+		if (restored !== void 0) catalogEntries.push([catalogKey, restored]);
+	}
 	objects.push({
 		num: catalogNum,
 		value: require_objects.pdfDict(Object.fromEntries(catalogEntries))
@@ -427,6 +517,118 @@ function writePdf(doc, options = {}) {
 			})
 		});
 	}
+	for (const layer of doc.layers ?? []) {
+		const num = layerNumByName.get(layer.name);
+		objects.push({
+			num,
+			value: require_objects.pdfDict({
+				Type: require_objects.pdfName("OCG"),
+				Name: require_objects.pdfLiteralString(new TextEncoder().encode(layer.name))
+			})
+		});
+	}
+	const widgetRectArray = (widget) => require_objects.pdfArray([
+		widget.xPt,
+		widget.yPt,
+		widget.xPt + widget.widthPt,
+		widget.yPt + widget.heightPt
+	].map((n) => require_objects.pdfNum(n)));
+	const widgetDict = (widget) => require_objects.pdfDict({
+		Subtype: require_objects.pdfName("Widget"),
+		Rect: widgetRectArray(widget),
+		P: require_objects.pdfRef(pageAllocs[widget.pageIndex].pageNum, 0)
+	});
+	const FIELD_TYPE_PDF_NAME = {
+		text: "Tx",
+		checkbox: "Btn",
+		radio: "Btn",
+		button: "Btn",
+		listbox: "Ch",
+		combobox: "Ch",
+		signature: "Sig"
+	};
+	const emitFormFieldObjects = (fields, parentName) => {
+		for (const field of fields) {
+			const ownName = parentName.length > 0 && field.name.startsWith(`${parentName}.`) ? field.name.slice(parentName.length + 1) : field.name;
+			const entries = [];
+			if (ownName.length > 0) entries.push(["T", require_objects.pdfLiteralString(new TextEncoder().encode(ownName))]);
+			if (field.alias !== void 0) entries.push(["TU", require_objects.pdfLiteralString(new TextEncoder().encode(field.alias))]);
+			if (field.fieldType === "group") entries.push(["Kids", require_objects.pdfArray(field.children.map((child) => require_objects.pdfRef(formNumOf(child), 0)))]);
+			else {
+				entries.push(["FT", require_objects.pdfName(FIELD_TYPE_PDF_NAME[field.fieldType])]);
+				const FLAG_READ_ONLY = 1;
+				const FLAG_PUSHBUTTON = 4;
+				const FLAG_RADIO = 32768;
+				const FLAG_COMBO = 131072;
+				let flags = 0;
+				if (field.readOnly === true) flags |= FLAG_READ_ONLY;
+				if (field.fieldType === "button") flags |= FLAG_PUSHBUTTON;
+				if (field.fieldType === "radio") flags |= FLAG_RADIO;
+				if (field.fieldType === "combobox") flags |= FLAG_COMBO;
+				if (flags !== 0) entries.push(["Ff", require_objects.pdfNum(flags)]);
+				if (field.fieldType === "text" || field.fieldType === "listbox" || field.fieldType === "combobox") {
+					if (field.value !== void 0) entries.push(["V", require_objects.pdfLiteralString(new TextEncoder().encode(field.value))]);
+				} else if (field.fieldType === "checkbox" || field.fieldType === "radio") entries.push(["V", require_objects.pdfName(field.checked === false || field.value === void 0 ? field.value ?? (field.checked === true ? "Yes" : "Off") : field.value)]);
+				if (field.options !== void 0) entries.push(["Opt", require_objects.pdfArray(field.options.map((option) => require_objects.pdfLiteralString(new TextEncoder().encode(option))))]);
+				const firstWidget = field.widgets[0];
+				if (field.widgets.length === 1 && firstWidget !== void 0) {
+					entries.push(["Subtype", require_objects.pdfName("Widget")]);
+					entries.push(["Rect", widgetRectArray(firstWidget)]);
+					entries.push(["P", require_objects.pdfRef(pageAllocs[firstWidget.pageIndex].pageNum, 0)]);
+				} else if (field.widgets.length > 1 && firstWidget !== void 0) {
+					const extraNums = formExtraWidgetNums.get(field) ?? [];
+					entries.push(["Kids", require_objects.pdfArray([widgetDict(firstWidget), ...extraNums.map((num) => require_objects.pdfRef(num, 0))])]);
+				}
+			}
+			objects.push({
+				num: formNumOf(field),
+				value: require_objects.pdfDict(Object.fromEntries(entries))
+			});
+			const extraNums = formExtraWidgetNums.get(field) ?? [];
+			for (const [index, num] of extraNums.entries()) {
+				const widget = field.widgets[index + 1];
+				objects.push({
+					num,
+					value: widgetDict(widget)
+				});
+			}
+			emitFormFieldObjects(field.children, field.name);
+		}
+	};
+	emitFormFieldObjects(doc.form ?? [], "");
+	if (structRootNum !== void 0 && structParentTreeNum !== void 0) {
+		const emitStructureElement = (element, parentNum) => {
+			const entries = [
+				["Type", require_objects.pdfName("StructElem")],
+				["S", require_objects.pdfName(element.type)],
+				["P", require_objects.pdfRef(parentNum, 0)]
+			];
+			if (element.title !== void 0) entries.push(["T", require_objects.pdfLiteralString(new TextEncoder().encode(element.title))]);
+			if (element.language !== void 0) entries.push(["Lang", require_objects.pdfLiteralString(new TextEncoder().encode(element.language))]);
+			if (element.alt !== void 0) entries.push(["Alt", require_objects.pdfLiteralString(new TextEncoder().encode(element.alt))]);
+			if (element.actualText !== void 0) entries.push(["ActualText", require_objects.pdfLiteralString(new TextEncoder().encode(element.actualText))]);
+			if (element.children.length > 0) entries.push(["K", require_objects.pdfArray(element.children.map((child) => {
+				const num = structElementNumById.get(child.id);
+				if (num === void 0) throw new Error(`structure element "${child.id}" was not allocated -- this is a writePdf internal invariant violation`);
+				return require_objects.pdfRef(num, 0);
+			}))]);
+			const ownNum = structElementNumById.get(element.id);
+			if (ownNum === void 0) throw new Error(`structure element "${element.id}" was not allocated -- this is a writePdf internal invariant violation`);
+			objects.push({
+				num: ownNum,
+				value: require_objects.pdfDict(Object.fromEntries(entries))
+			});
+			for (const child of element.children) emitStructureElement(child, ownNum);
+		};
+		for (const element of doc.structure ?? []) emitStructureElement(element, structRootNum);
+	}
+	if (residueXmpNum !== void 0 && doc.source?.xmp !== void 0) objects.push({
+		num: residueXmpNum,
+		value: require_objects.pdfStream(require_objects.pdfDict({
+			Type: require_objects.pdfName("Metadata"),
+			Subtype: require_objects.pdfName("XML")
+		}), new TextEncoder().encode(doc.source.xmp.xml))
+	});
 	for (const [standardName, alloc] of fontAllocs) {
 		const { font, descriptor } = buildFontObjects(standardName, require_objects.pdfRef(alloc.descNum, 0));
 		objects.push({
@@ -521,6 +723,7 @@ function writePdf(doc, options = {}) {
 	}
 	if (imageAllocs.size > 0) resourceEntries.set("XObject", require_objects.pdfDict(new Map([...imageAllocs.values()].map((alloc) => [alloc.resourceName, require_objects.pdfRef(alloc.imageNum, 0)]))));
 	const resourcesDict = require_objects.pdfDict(resourceEntries);
+	const markedStructureByPage = /* @__PURE__ */ new Map();
 	const formulasByPage = /* @__PURE__ */ new Map();
 	for (const formula of formulas) {
 		const forPage = formulasByPage.get(formula.pageIndex);
@@ -557,7 +760,14 @@ function writePdf(doc, options = {}) {
 	doc.pages.forEach((page, pageIndex) => {
 		require_util_abort.throwIfAborted(options.signal);
 		const { pageNum, contentsNum } = pageAllocs[pageIndex];
-		const { bytes: contentBytes, substitutions, missingGlyphs } = require_content_write.writeContentStream(page.items, context);
+		let pageMcid = 0;
+		const pageContext = {
+			...context,
+			nextMcid: () => pageMcid++,
+			layerObjectNumberOf: (name) => layerNumByName.get(name)
+		};
+		const { bytes: contentBytes, substitutions, missingGlyphs, markedStructure } = require_content_write.writeContentStream(page.items, pageContext);
+		if (markedStructure.length > 0) markedStructureByPage.set(pageIndex, [...markedStructure]);
 		for (const substitution of substitutions) options.onSubstitution?.(substitution, { pageIndex });
 		for (const missing of missingGlyphs) options.onMissingGlyph?.(missing, { pageIndex });
 		const pageFormulas = formulasByPage.get(pageIndex);
@@ -587,11 +797,41 @@ function writePdf(doc, options = {}) {
 			["Contents", require_objects.pdfRef(contentsNum, 0)]
 		]);
 		if (annots.length > 0) pageEntries.set("Annots", require_objects.pdfArray(annots));
+		if ((markedStructureByPage.get(pageIndex) ?? []).length > 0) pageEntries.set("StructParents", require_objects.pdfNum(pageIndex));
 		objects.push({
 			num: pageNum,
 			value: require_objects.pdfDict(pageEntries)
 		});
 	});
+	if (structRootNum !== void 0 && structParentTreeNum !== void 0) {
+		const nums = [];
+		for (const [pageIndex, marks] of markedStructureByPage) {
+			const maxMcid = Math.max(...marks.map((mark) => mark.mcid));
+			const byMcid = Array.from({ length: maxMcid + 1 }, () => require_objects.pdfNull());
+			for (const mark of marks) {
+				const elementNum = structElementNumById.get(mark.structureId);
+				if (elementNum !== void 0) byMcid[mark.mcid] = require_objects.pdfRef(elementNum, 0);
+			}
+			nums.push(require_objects.pdfNum(pageIndex), require_objects.pdfArray(byMcid));
+		}
+		objects.push({
+			num: structParentTreeNum,
+			value: require_objects.pdfDict({ Nums: require_objects.pdfArray(nums) })
+		});
+		const rootEntries = [
+			["Type", require_objects.pdfName("StructTreeRoot")],
+			["K", require_objects.pdfArray((doc.structure ?? []).map((element) => {
+				const num = structElementNumById.get(element.id);
+				if (num === void 0) throw new Error(`structure element "${element.id}" was not allocated -- this is a writePdf internal invariant violation`);
+				return require_objects.pdfRef(num, 0);
+			}))],
+			["ParentTree", require_objects.pdfRef(structParentTreeNum, 0)]
+		];
+		objects.push({
+			num: structRootNum,
+			value: require_objects.pdfDict(Object.fromEntries(rootEntries))
+		});
+	}
 	let fileId;
 	let encryptedObjects = objects;
 	if (options.encryption !== void 0 && encryptDictNum !== void 0) {
@@ -633,7 +873,7 @@ function writePdf(doc, options = {}) {
 	if (fileId !== void 0 && encryptDictNum !== void 0) {
 		trailerEntries.set("ID", require_objects.pdfArray([require_objects.pdfHexString(fileId), require_objects.pdfHexString(fileId)]));
 		trailerEntries.set("Encrypt", require_objects.pdfRef(encryptDictNum, 0));
-	}
+	} else if (trailerIdRestore !== void 0) trailerEntries.set("ID", trailerIdRestore);
 	writer.writeAscii("trailer\n");
 	require_serialize.writeObject(writer, require_objects.pdfDict(trailerEntries));
 	writer.writeAscii("\nstartxref\n");

package/dist/write.js

@@ -3,8 +3,10 @@ import { NOTES_ANNOTATION_AUTHOR } from "./notes-annotation-author.js";
 import { pdfArray, pdfDict, pdfHexString, pdfLiteralString, pdfName, pdfNull, pdfNum, pdfRef, pdfStream } from "./objects.js";
 import { ByteWriter, concatBytes } from "./bytes/writer.js";
 import { writeObject } from "./serialize.js";
+import { ByteReader } from "./bytes/reader.js";
 import { deflate } from "./bytes/flate.js";
 import { base64ToBytes } from "./util/base64.js";
+import { parseValue } from "./parse.js";
 import { throwIfAborted } from "./util/abort.js";
 import { randomBytes } from "./crypto/random.js";
 import { createStandardEncryptor, encryptIndirectObject } from "./encrypt-write.js";
@@ -251,6 +253,24 @@ function buildNotesAnnotDict(notes) {
 function xrefEntry(offset, generation, inUse) {
 	return `${offset.toString().padStart(10, "0")} ${generation.toString().padStart(5, "0")} ${inUse ? "n" : "f"} \n`;
 }
+function parseResidueRow(residue) {
+	const reader = new ByteReader(new TextEncoder().encode(residue.xml));
+	return parseValue(reader, () => {});
+}
+function objectContainsReference(obj) {
+	if (obj.kind === "ref") return true;
+	if (obj.kind === "array") return obj.items.some(objectContainsReference);
+	if (obj.kind === "dict") return [...obj.entries.values()].some(objectContainsReference);
+	if (obj.kind === "stream") return [...obj.dict.entries.values()].some(objectContainsReference);
+	return false;
+}
+function restoreResidueRow(source, key) {
+	const row = source?.[key];
+	if (row === void 0) return;
+	const parsed = parseResidueRow(row);
+	if (parsed === void 0 || objectContainsReference(parsed)) return;
+	return parsed;
+}
 function writePdf(doc, options = {}) {
 	const compress = options.compress ?? true;
 	const registry = options.fonts;
@@ -339,10 +359,80 @@ function writePdf(doc, options = {}) {
 		};
 		for (let i = 0; i < countItems(doc.outline ?? []); i += 1) outlineItemNums.push(nextObjNum++);
 	}
+	const layerNumByName = /* @__PURE__ */ new Map();
+	for (const layer of doc.layers ?? []) layerNumByName.set(layer.name, nextObjNum++);
+	const formObjectNums = [];
+	const countFieldObjects = (fields) => {
+		let n = 0;
+		for (const field of fields) n += 1 + (field.fieldType !== "group" && field.widgets.length > 1 ? field.widgets.length - 1 : 0) + countFieldObjects(field.children);
+		return n;
+	};
+	for (let i = 0; i < countFieldObjects(doc.form ?? []); i += 1) formObjectNums.push(nextObjNum++);
+	const formNumByField = /* @__PURE__ */ new Map();
+	const formExtraWidgetNums = /* @__PURE__ */ new Map();
+	let formNumCursor = 0;
+	const claimFormNums = (fields) => {
+		for (const field of fields) {
+			formNumByField.set(field, formObjectNums[formNumCursor++]);
+			if (field.fieldType !== "group" && field.widgets.length > 1) formExtraWidgetNums.set(field, field.widgets.slice(1).map(() => formObjectNums[formNumCursor++]));
+			claimFormNums(field.children);
+		}
+	};
+	claimFormNums(doc.form ?? []);
+	const formNumOf = (field) => {
+		const num = formNumByField.get(field);
+		if (num === void 0) throw new Error("AcroForm field object number was not claimed -- this is a writePdf internal invariant violation");
+		return num;
+	};
+	const structElementNumById = /* @__PURE__ */ new Map();
+	const countElements = (elements) => {
+		let n = 0;
+		for (const element of elements) {
+			structElementNumById.set(element.id, nextObjNum++);
+			n += 1 + countElements(element.children);
+		}
+		return n;
+	};
+	const structElementCount = countElements(doc.structure ?? []);
+	const structRootNum = structElementCount > 0 ? nextObjNum++ : void 0;
+	const structParentTreeNum = structElementCount > 0 ? nextObjNum++ : void 0;
+	const residueXmpNum = doc.source?.xmp !== void 0 ? nextObjNum++ : void 0;
 	const objects = [];
 	const catalogEntries = [["Type", pdfName("Catalog")], ["Pages", pdfRef(pagesNum, 0)]];
 	if (attachmentsNamesNum !== void 0) catalogEntries.push(["Names", pdfRef(attachmentsNamesNum, 0)]);
 	if (outlineRootNum !== void 0) catalogEntries.push(["Outlines", pdfRef(outlineRootNum, 0)]);
+	if (layerNumByName.size > 0) {
+		const ocgRefs = [...layerNumByName.values()].map((num) => pdfRef(num, 0));
+		const visible = [];
+		const hidden = [];
+		for (const layer of doc.layers ?? []) {
+			const num = layerNumByName.get(layer.name);
+			(layer.visible ? visible : hidden).push(pdfRef(num, 0));
+		}
+		const defaultConfigEntries = [];
+		if (visible.length > 0) defaultConfigEntries.push(["ON", pdfArray(visible)]);
+		if (hidden.length > 0) defaultConfigEntries.push(["OFF", pdfArray(hidden)]);
+		catalogEntries.push(["OCProperties", pdfDict({
+			OCGs: pdfArray(ocgRefs),
+			D: pdfDict(Object.fromEntries(defaultConfigEntries))
+		})]);
+	}
+	if (doc.form !== void 0 && doc.form.length > 0) catalogEntries.push(["AcroForm", pdfDict({ Fields: pdfArray(doc.form.map((field) => pdfRef(formNumOf(field), 0))) })]);
+	if (structRootNum !== void 0) catalogEntries.push(["StructTreeRoot", pdfRef(structRootNum, 0)]);
+	if (residueXmpNum !== void 0) catalogEntries.push(["Metadata", pdfRef(residueXmpNum, 0)]);
+	const trailerIdRestore = restoreResidueRow(doc.source, "trailer-id");
+	for (const [rowKey, catalogKey] of [
+		["viewer-preferences", "ViewerPreferences"],
+		["page-mode", "PageMode"],
+		["page-layout", "PageLayout"],
+		["output-intents", "OutputIntents"],
+		["piece-info", "PieceInfo"],
+		["legal", "Legal"],
+		["collection", "Collection"]
+	]) {
+		const restored = restoreResidueRow(doc.source, rowKey);
+		if (restored !== void 0) catalogEntries.push([catalogKey, restored]);
+	}
 	objects.push({
 		num: catalogNum,
 		value: pdfDict(Object.fromEntries(catalogEntries))
@@ -426,6 +516,118 @@ function writePdf(doc, options = {}) {
 			})
 		});
 	}
+	for (const layer of doc.layers ?? []) {
+		const num = layerNumByName.get(layer.name);
+		objects.push({
+			num,
+			value: pdfDict({
+				Type: pdfName("OCG"),
+				Name: pdfLiteralString(new TextEncoder().encode(layer.name))
+			})
+		});
+	}
+	const widgetRectArray = (widget) => pdfArray([
+		widget.xPt,
+		widget.yPt,
+		widget.xPt + widget.widthPt,
+		widget.yPt + widget.heightPt
+	].map((n) => pdfNum(n)));
+	const widgetDict = (widget) => pdfDict({
+		Subtype: pdfName("Widget"),
+		Rect: widgetRectArray(widget),
+		P: pdfRef(pageAllocs[widget.pageIndex].pageNum, 0)
+	});
+	const FIELD_TYPE_PDF_NAME = {
+		text: "Tx",
+		checkbox: "Btn",
+		radio: "Btn",
+		button: "Btn",
+		listbox: "Ch",
+		combobox: "Ch",
+		signature: "Sig"
+	};
+	const emitFormFieldObjects = (fields, parentName) => {
+		for (const field of fields) {
+			const ownName = parentName.length > 0 && field.name.startsWith(`${parentName}.`) ? field.name.slice(parentName.length + 1) : field.name;
+			const entries = [];
+			if (ownName.length > 0) entries.push(["T", pdfLiteralString(new TextEncoder().encode(ownName))]);
+			if (field.alias !== void 0) entries.push(["TU", pdfLiteralString(new TextEncoder().encode(field.alias))]);
+			if (field.fieldType === "group") entries.push(["Kids", pdfArray(field.children.map((child) => pdfRef(formNumOf(child), 0)))]);
+			else {
+				entries.push(["FT", pdfName(FIELD_TYPE_PDF_NAME[field.fieldType])]);
+				const FLAG_READ_ONLY = 1;
+				const FLAG_PUSHBUTTON = 4;
+				const FLAG_RADIO = 32768;
+				const FLAG_COMBO = 131072;
+				let flags = 0;
+				if (field.readOnly === true) flags |= FLAG_READ_ONLY;
+				if (field.fieldType === "button") flags |= FLAG_PUSHBUTTON;
+				if (field.fieldType === "radio") flags |= FLAG_RADIO;
+				if (field.fieldType === "combobox") flags |= FLAG_COMBO;
+				if (flags !== 0) entries.push(["Ff", pdfNum(flags)]);
+				if (field.fieldType === "text" || field.fieldType === "listbox" || field.fieldType === "combobox") {
+					if (field.value !== void 0) entries.push(["V", pdfLiteralString(new TextEncoder().encode(field.value))]);
+				} else if (field.fieldType === "checkbox" || field.fieldType === "radio") entries.push(["V", pdfName(field.checked === false || field.value === void 0 ? field.value ?? (field.checked === true ? "Yes" : "Off") : field.value)]);
+				if (field.options !== void 0) entries.push(["Opt", pdfArray(field.options.map((option) => pdfLiteralString(new TextEncoder().encode(option))))]);
+				const firstWidget = field.widgets[0];
+				if (field.widgets.length === 1 && firstWidget !== void 0) {
+					entries.push(["Subtype", pdfName("Widget")]);
+					entries.push(["Rect", widgetRectArray(firstWidget)]);
+					entries.push(["P", pdfRef(pageAllocs[firstWidget.pageIndex].pageNum, 0)]);
+				} else if (field.widgets.length > 1 && firstWidget !== void 0) {
+					const extraNums = formExtraWidgetNums.get(field) ?? [];
+					entries.push(["Kids", pdfArray([widgetDict(firstWidget), ...extraNums.map((num) => pdfRef(num, 0))])]);
+				}
+			}
+			objects.push({
+				num: formNumOf(field),
+				value: pdfDict(Object.fromEntries(entries))
+			});
+			const extraNums = formExtraWidgetNums.get(field) ?? [];
+			for (const [index, num] of extraNums.entries()) {
+				const widget = field.widgets[index + 1];
+				objects.push({
+					num,
+					value: widgetDict(widget)
+				});
+			}
+			emitFormFieldObjects(field.children, field.name);
+		}
+	};
+	emitFormFieldObjects(doc.form ?? [], "");
+	if (structRootNum !== void 0 && structParentTreeNum !== void 0) {
+		const emitStructureElement = (element, parentNum) => {
+			const entries = [
+				["Type", pdfName("StructElem")],
+				["S", pdfName(element.type)],
+				["P", pdfRef(parentNum, 0)]
+			];
+			if (element.title !== void 0) entries.push(["T", pdfLiteralString(new TextEncoder().encode(element.title))]);
+			if (element.language !== void 0) entries.push(["Lang", pdfLiteralString(new TextEncoder().encode(element.language))]);
+			if (element.alt !== void 0) entries.push(["Alt", pdfLiteralString(new TextEncoder().encode(element.alt))]);
+			if (element.actualText !== void 0) entries.push(["ActualText", pdfLiteralString(new TextEncoder().encode(element.actualText))]);
+			if (element.children.length > 0) entries.push(["K", pdfArray(element.children.map((child) => {
+				const num = structElementNumById.get(child.id);
+				if (num === void 0) throw new Error(`structure element "${child.id}" was not allocated -- this is a writePdf internal invariant violation`);
+				return pdfRef(num, 0);
+			}))]);
+			const ownNum = structElementNumById.get(element.id);
+			if (ownNum === void 0) throw new Error(`structure element "${element.id}" was not allocated -- this is a writePdf internal invariant violation`);
+			objects.push({
+				num: ownNum,
+				value: pdfDict(Object.fromEntries(entries))
+			});
+			for (const child of element.children) emitStructureElement(child, ownNum);
+		};
+		for (const element of doc.structure ?? []) emitStructureElement(element, structRootNum);
+	}
+	if (residueXmpNum !== void 0 && doc.source?.xmp !== void 0) objects.push({
+		num: residueXmpNum,
+		value: pdfStream(pdfDict({
+			Type: pdfName("Metadata"),
+			Subtype: pdfName("XML")
+		}), new TextEncoder().encode(doc.source.xmp.xml))
+	});
 	for (const [standardName, alloc] of fontAllocs) {
 		const { font, descriptor } = buildFontObjects(standardName, pdfRef(alloc.descNum, 0));
 		objects.push({
@@ -520,6 +722,7 @@ function writePdf(doc, options = {}) {
 	}
 	if (imageAllocs.size > 0) resourceEntries.set("XObject", pdfDict(new Map([...imageAllocs.values()].map((alloc) => [alloc.resourceName, pdfRef(alloc.imageNum, 0)]))));
 	const resourcesDict = pdfDict(resourceEntries);
+	const markedStructureByPage = /* @__PURE__ */ new Map();
 	const formulasByPage = /* @__PURE__ */ new Map();
 	for (const formula of formulas) {
 		const forPage = formulasByPage.get(formula.pageIndex);
@@ -556,7 +759,14 @@ function writePdf(doc, options = {}) {
 	doc.pages.forEach((page, pageIndex) => {
 		throwIfAborted(options.signal);
 		const { pageNum, contentsNum } = pageAllocs[pageIndex];
-		const { bytes: contentBytes, substitutions, missingGlyphs } = writeContentStream(page.items, context);
+		let pageMcid = 0;
+		const pageContext = {
+			...context,
+			nextMcid: () => pageMcid++,
+			layerObjectNumberOf: (name) => layerNumByName.get(name)
+		};
+		const { bytes: contentBytes, substitutions, missingGlyphs, markedStructure } = writeContentStream(page.items, pageContext);
+		if (markedStructure.length > 0) markedStructureByPage.set(pageIndex, [...markedStructure]);
 		for (const substitution of substitutions) options.onSubstitution?.(substitution, { pageIndex });
 		for (const missing of missingGlyphs) options.onMissingGlyph?.(missing, { pageIndex });
 		const pageFormulas = formulasByPage.get(pageIndex);
@@ -586,11 +796,41 @@ function writePdf(doc, options = {}) {
 			["Contents", pdfRef(contentsNum, 0)]
 		]);
 		if (annots.length > 0) pageEntries.set("Annots", pdfArray(annots));
+		if ((markedStructureByPage.get(pageIndex) ?? []).length > 0) pageEntries.set("StructParents", pdfNum(pageIndex));
 		objects.push({
 			num: pageNum,
 			value: pdfDict(pageEntries)
 		});
 	});
+	if (structRootNum !== void 0 && structParentTreeNum !== void 0) {
+		const nums = [];
+		for (const [pageIndex, marks] of markedStructureByPage) {
+			const maxMcid = Math.max(...marks.map((mark) => mark.mcid));
+			const byMcid = Array.from({ length: maxMcid + 1 }, () => pdfNull());
+			for (const mark of marks) {
+				const elementNum = structElementNumById.get(mark.structureId);
+				if (elementNum !== void 0) byMcid[mark.mcid] = pdfRef(elementNum, 0);
+			}
+			nums.push(pdfNum(pageIndex), pdfArray(byMcid));
+		}
+		objects.push({
+			num: structParentTreeNum,
+			value: pdfDict({ Nums: pdfArray(nums) })
+		});
+		const rootEntries = [
+			["Type", pdfName("StructTreeRoot")],
+			["K", pdfArray((doc.structure ?? []).map((element) => {
+				const num = structElementNumById.get(element.id);
+				if (num === void 0) throw new Error(`structure element "${element.id}" was not allocated -- this is a writePdf internal invariant violation`);
+				return pdfRef(num, 0);
+			}))],
+			["ParentTree", pdfRef(structParentTreeNum, 0)]
+		];
+		objects.push({
+			num: structRootNum,
+			value: pdfDict(Object.fromEntries(rootEntries))
+		});
+	}
 	let fileId;
 	let encryptedObjects = objects;
 	if (options.encryption !== void 0 && encryptDictNum !== void 0) {
@@ -632,7 +872,7 @@ function writePdf(doc, options = {}) {
 	if (fileId !== void 0 && encryptDictNum !== void 0) {
 		trailerEntries.set("ID", pdfArray([pdfHexString(fileId), pdfHexString(fileId)]));
 		trailerEntries.set("Encrypt", pdfRef(encryptDictNum, 0));
-	}
+	} else if (trailerIdRestore !== void 0) trailerEntries.set("ID", trailerIdRestore);
 	writer.writeAscii("trailer\n");
 	writeObject(writer, pdfDict(trailerEntries));
 	writer.writeAscii("\nstartxref\n");

package/package.json

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