@muhammara/native-core 7.0.0-beta.3 → 7.0.0-rc.1

package/lib/recipe/page.js

@@ -1,6 +1,40 @@
 const muhammara = require("../muhammara");
+const { PAGE_CONTEXT_STATE } = require("./utils");
+const { PageLayout, Colorspace } = require("../recipe-constants");
+const {
+  planDeletedPageReferences,
+  pruneDeletedPageReferences,
+  setCatalogEntry,
+} = require("./page-references");
 
-/** Builds the retained page tree while marking deleted leaf pages. @private */
+// PDF dictionary keys and names the page-tree and page-label code reads.
+const PdfName = Object.freeze({
+  PAGES: "Pages",
+  KIDS: "Kids",
+  COUNT: "Count",
+  PARENT: "Parent",
+  PAGE_LABELS: "PageLabels",
+  LIMITS: "Limits",
+  NUMS: "Nums",
+});
+
+/**
+ * Build the retained page tree while marking deleted leaf pages.
+ * @private
+ * @param {Object} parser - The source PDF parser.
+ * @param {number} objectID - The object ID of the Pages node to read.
+ * @param {Set<number>} deletedPages - One-based page numbers to delete.
+ * @param {Set<number>} modifiedPageIDs - Object IDs of pages edited in this Recipe.
+ * @param {Object} pageState - Running state: pageNumber, deletedPageIDs and
+ *   retainedPageIDs, updated as leaves are visited.
+ * @param {number} [generation=0] - The generation of the node's reference.
+ * @param {Set<number>} [visited] - Pages nodes already read, to reject cycles.
+ * @param {number} [depth=0] - The nesting depth, limited to 1000.
+ * @returns {Object} The node: objectID, generation, values, retained
+ *   children, retained page count and whether it changed.
+ * @throws {Error} If the page tree is cyclic, too deep or inconsistent, or a
+ *   modified page has a nonzero generation.
+ */
 function readPageTree(
   parser,
   objectID,
@@ -20,11 +54,21 @@ function readPageTree(
   if (depth === 0 && values.Parent !== undefined) {
     throw new Error("deletePage requires a valid page tree");
   }
-  const kids = parser.queryDictionaryObject(dictionary, "Kids").toPDFArray();
+  const kids = parser.queryDictionaryObject(dictionary, "Kids")?.toPDFArray();
+  if (!kids) {
+    throw new Error("deletePage requires a valid page tree");
+  }
   const mappedChildren = kids.toJSArray().map((entry) => {
+    // Kids must be references to page tree dictionaries with a /Type.
     const reference = entry.toPDFIndirectObjectReference();
-    const childID = reference.getObjectID();
-    const childDictionary = parser.parseNewObject(childID).toPDFDictionary();
+    const childID = reference?.getObjectID();
+    const childDictionary =
+      childID === undefined
+        ? null
+        : parser.parseNewObject(childID)?.toPDFDictionary();
+    if (!childDictionary) {
+      throw new Error("deletePage requires a valid page tree");
+    }
     const childValues = childDictionary.toJSObject();
     const parentReference = childValues.Parent?.toPDFIndirectObjectReference();
     if (
@@ -34,8 +78,11 @@ function readPageTree(
     ) {
       throw new Error("deletePage requires a valid page tree");
     }
-    const type = childValues.Type.toPDFName().value;
-    if (type === "Pages") {
+    const type = childValues.Type?.toPDFName()?.value;
+    if (type === undefined) {
+      throw new Error("deletePage requires a valid page tree");
+    }
+    if (type === PdfName.PAGES) {
       return readPageTree(
         parser,
         childID,
@@ -83,7 +130,15 @@ function readPageTree(
   };
 }
 
-/** Writes changed page-tree nodes back to the modified PDF. @private */
+/**
+ * Write changed page-tree nodes back to the modified PDF with their new
+ * Count and Kids.
+ * @private
+ * @param {Object} writer - The PDF writer.
+ * @param {Object} copyingContext - Copies the unchanged entries.
+ * @param {Object} node - A node built by readPageTree().
+ * @returns {void}
+ */
 function writePageTree(writer, copyingContext, node) {
   node.children
     .filter((child) => child.children && child.changed)
@@ -94,13 +149,13 @@ function writePageTree(writer, copyingContext, node) {
   objectsContext.startModifiedIndirectObject(node.objectID);
   const dictionary = objectsContext.startDictionary();
   Object.keys(node.values).forEach((key) => {
-    if (key === "Count" || key === "Kids") return;
+    if (key === PdfName.COUNT || key === PdfName.KIDS) return;
     dictionary.writeKey(key);
     copyingContext.copyDirectObjectAsIs(node.values[key]);
   });
-  dictionary.writeKey("Count");
+  dictionary.writeKey(PdfName.COUNT);
   objectsContext.writeNumber(node.count);
-  dictionary.writeKey("Kids");
+  dictionary.writeKey(PdfName.KIDS);
   objectsContext.startArray();
   node.children.forEach((child) => {
     objectsContext.writeIndirectObjectReference(
@@ -116,6 +171,10 @@ function writePageTree(writer, copyingContext, node) {
  * alike - depth-first. Shared by every deletePage() pass that needs to walk
  * the tree readPageTree() already built, instead of re-parsing or re-walking
  * it independently.
+ * @private
+ * @param {Object} tree - The root node built by readPageTree().
+ * @param {function(Object): void} visit - Called with every node.
+ * @returns {void}
  */
 function walkPageTree(tree, visit) {
   const pending = [tree];
@@ -126,15 +185,17 @@ function walkPageTree(tree, visit) {
   }
 }
 
-/** Adds retained Pages-node object IDs to a set. @private */
-function collectPageTreeObjectIDs(tree, objectIDs) {
-  walkPageTree(tree, (node) => {
-    if (node.children) objectIDs.add(node.objectID);
-  });
-}
-
-/** Rejects page-tree objects that cannot be rewritten safely. @private */
-function assertSupportedModifiedGenerations(tree, pageLabels, root, writer) {
+/**
+ * Reject page-tree and page-label objects that cannot be rewritten safely:
+ * changed objects must have generation 0. The catalog is never rewritten in
+ * place, so its generation does not matter.
+ * @private
+ * @param {Object} tree - The root node built by readPageTree().
+ * @param {Object|null} pageLabels - The result of preparePageLabels().
+ * @returns {void}
+ * @throws {Error} If a changed object has a nonzero generation.
+ */
+function assertSupportedModifiedGenerations(tree, pageLabels) {
   walkPageTree(tree, (node) => {
     if (!node.children) return;
     if (node.changed && node.generation !== 0) {
@@ -148,162 +209,20 @@ function assertSupportedModifiedGenerations(tree, pageLabels, root, writer) {
       "deletePage does not support rewriting nonzero-generation objects",
     );
   }
-  // A writer with _setPageLabelsObject() (wasm) always attaches a new
-  // PageLabels entry through that dedicated hook and never rewrites the
-  // catalog object in place, so the catalog's own generation never matters
-  // there. Without it (native-core), writePageLabels() falls back to
-  // rewriting the catalog via startModifiedIndirectObject(rootID), which
-  // only supports generation 0.
-  if (pageLabels && !pageLabels.reference && !writer._setPageLabelsObject) {
-    if (root.getVersion() !== 0) {
-      throw new Error(
-        "deletePage does not support rewriting nonzero-generation objects",
-      );
-    }
-  }
-}
-
-/** Rejects retained structures that reference a deleted page. @private */
-function assertNoDeletedPageReferences(
-  parser,
-  value,
-  deletedPageIDs,
-  skippedObjectIDs,
-  visited = new Set(),
-  depth = 0,
-) {
-  if (!value) return;
-  if (depth > 1000) {
-    throw new Error("deletePage cannot validate deeply nested references");
-  }
-  const reference = value.toPDFIndirectObjectReference?.();
-  if (reference) {
-    const objectID = reference.getObjectID();
-    if (deletedPageIDs.has(objectID)) {
-      throw new Error(
-        "deletePage cannot remove a page referenced by retained document structures",
-      );
-    }
-    if (skippedObjectIDs.has(objectID) || visited.has(objectID)) return;
-    visited.add(objectID);
-    assertNoDeletedPageReferences(
-      parser,
-      parser.parseNewObject(objectID),
-      deletedPageIDs,
-      skippedObjectIDs,
-      visited,
-      depth + 1,
-    );
-    return;
-  }
-  const array =
-    value.toPDFArray?.() ||
-    (typeof value.toJSArray === "function" ? value : null);
-  if (array) {
-    array
-      .toJSArray()
-      .forEach((entry) =>
-        assertNoDeletedPageReferences(
-          parser,
-          entry,
-          deletedPageIDs,
-          skippedObjectIDs,
-          visited,
-          depth + 1,
-        ),
-      );
-    return;
-  }
-  const dictionary =
-    value.toPDFDictionary?.() ||
-    (typeof value.toJSObject === "function" ? value : null);
-  if (dictionary) {
-    Object.values(dictionary.toJSObject()).forEach((entry) =>
-      assertNoDeletedPageReferences(
-        parser,
-        entry,
-        deletedPageIDs,
-        skippedObjectIDs,
-        visited,
-        depth + 1,
-      ),
-    );
-    return;
-  }
-  const stream = value.toPDFStream?.();
-  if (stream) {
-    assertNoDeletedPageReferences(
-      parser,
-      stream.getDictionary(),
-      deletedPageIDs,
-      skippedObjectIDs,
-      visited,
-      depth + 1,
-    );
-  }
-}
-
-/** Checks retained document structures for deleted-page references. @private */
-function validateDeletedPageReferences(
-  parser,
-  catalog,
-  rootID,
-  tree,
-  pageLabels,
-  deletedPageIDs,
-  sourcePageCount,
-) {
-  const skippedObjectIDs = new Set([rootID]);
-  collectPageTreeObjectIDs(tree, skippedObjectIDs);
-  for (let pageIndex = 0; pageIndex < sourcePageCount; pageIndex += 1) {
-    skippedObjectIDs.add(parser.getPageObjectID(pageIndex));
-  }
-  const visited = new Set();
-  Object.entries(catalog)
-    .filter(([key]) => !["PageLabels", "Pages"].includes(key))
-    .forEach(([, value]) =>
-      assertNoDeletedPageReferences(
-        parser,
-        value,
-        deletedPageIDs,
-        skippedObjectIDs,
-        visited,
-      ),
-    );
-  if (pageLabels) {
-    Object.entries(pageLabels.values)
-      .filter(([key]) => !["Kids", "Limits", "Nums"].includes(key))
-      .forEach(([, value]) =>
-        assertNoDeletedPageReferences(
-          parser,
-          value,
-          deletedPageIDs,
-          skippedObjectIDs,
-          visited,
-        ),
-      );
-  }
-  // Walks the same tree readPageTree() already parsed - each retained leaf
-  // carries the page dictionary values readPageTree() read, so there is no
-  // need to re-parse every retained page's dictionary here.
-  walkPageTree(tree, (node) => {
-    const isLeaf = !node.children;
-    const skipKeys = isLeaf ? ["Parent"] : ["Count", "Kids", "Parent"];
-    Object.entries(node.values)
-      .filter(([key]) => !skipKeys.includes(key))
-      .forEach(([, value]) =>
-        assertNoDeletedPageReferences(
-          parser,
-          value,
-          deletedPageIDs,
-          skippedObjectIDs,
-          visited,
-        ),
-      );
-  });
 }
 
-/** Collects page-label number-tree entries. @private */
+/**
+ * Collect the entries of a page-label number tree.
+ * @private
+ * @param {Object} parser - The source PDF parser.
+ * @param {Object} dictionary - The number-tree node.
+ * @param {Object[]} entries - Receives {index, value} for every label.
+ * @param {Set<number>} [visited] - Nodes already read, to reject cycles.
+ * @param {number} [objectID=0] - The object ID of this node, if indirect.
+ * @param {number} [depth=0] - The nesting depth, limited to 1000.
+ * @returns {Object} The entries of this node's dictionary.
+ * @throws {Error} If the tree is cyclic, too deep or has invalid entries.
+ */
 function collectPageLabels(
   parser,
   dictionary,
@@ -335,7 +254,7 @@ function collectPageLabels(
   }
   if (values.Kids) {
     parser
-      .queryDictionaryObject(dictionary, "Kids")
+      .queryDictionaryObject(dictionary, PdfName.KIDS)
       .toPDFArray()
       .toJSArray()
       .forEach((entry) => {
@@ -353,7 +272,14 @@ function collectPageLabels(
   return values;
 }
 
-/** Resolves an indirect chain used by a page-label number tree. @private */
+/**
+ * Follow a chain of indirect references to the object it ends at.
+ * @private
+ * @param {Object} parser - The source PDF parser.
+ * @param {Object} value - The PDF object or reference.
+ * @returns {Object} The resolved object.
+ * @throws {Error} If the chain is cyclic or longer than 1000 references.
+ */
 function resolvePageLabelObject(parser, value) {
   const visited = new Set();
   let resolved = value;
@@ -368,7 +294,16 @@ function resolvePageLabelObject(parser, value) {
   return resolved;
 }
 
-/** Reads a page-label dictionary into a serializable value. @private */
+/**
+ * Read a page-label dictionary into a plain value.
+ * @private
+ * @param {Object} parser - The source PDF parser.
+ * @param {Object} value - The page-label dictionary.
+ * @returns {{style: (string|undefined), prefix: (Object|undefined),
+ *   start: (number|undefined)}} The label style name, prefix bytes with their
+ *   string kind, and start number.
+ * @throws {Error} If the value is not a dictionary.
+ */
 function readPageLabel(parser, value) {
   const dictionary = value?.toPDFDictionary();
   if (!dictionary) {
@@ -380,6 +315,9 @@ function readPageLabel(parser, value) {
   const start = values.St ? resolvePageLabelObject(parser, values.St) : null;
   const prefixHex = prefix?.toPDFHexString();
   const prefixLiteral = prefix?.toPDFLiteralString();
+  if (values.P !== undefined && !prefixHex && !prefixLiteral) {
+    throw new Error("deletePage requires valid PageLabels entries");
+  }
   return {
     style: style?.toPDFName()?.value,
     prefix:
@@ -393,7 +331,13 @@ function readPageLabel(parser, value) {
   };
 }
 
-/** Writes indirect objects for normalized page-label values. @private */
+/**
+ * Write one indirect page-label dictionary per entry.
+ * @private
+ * @param {Object} objectsContext - The writer objects context.
+ * @param {Object[]} entries - The normalized {index, value} entries.
+ * @returns {Object[]} The {index, objectID} of every written label.
+ */
 function writePageLabelObjects(objectsContext, entries) {
   return entries.map((entry) => {
     const objectID = objectsContext.startNewIndirectObject();
@@ -417,7 +361,17 @@ function writePageLabelObjects(objectsContext, entries) {
   });
 }
 
-/** Writes the number-tree dictionary for page labels. @private */
+/**
+ * Write a flat page-label number tree: the copied extra entries and a Nums
+ * array referencing the written labels.
+ * @private
+ * @param {Object} objectsContext - The writer objects context.
+ * @param {Object} copyingContext - Copies the extra entries.
+ * @param {Object} dictionary - The dictionary context to write into.
+ * @param {Object} values - The source number-tree entries.
+ * @param {Object[]} entries - The {index, objectID} of every label.
+ * @returns {void}
+ */
 function writePageLabelsDictionary(
   objectsContext,
   copyingContext,
@@ -426,11 +380,12 @@ function writePageLabelsDictionary(
   entries,
 ) {
   Object.keys(values).forEach((key) => {
-    if (key === "Kids" || key === "Limits" || key === "Nums") return;
+    if (key === PdfName.KIDS || key === PdfName.LIMITS || key === PdfName.NUMS)
+      return;
     dictionary.writeKey(key);
     copyingContext.copyDirectObjectAsIs(values[key]);
   });
-  dictionary.writeKey("Nums");
+  dictionary.writeKey(PdfName.NUMS);
   objectsContext.startArray();
   entries.forEach((entry) => {
     objectsContext.writeNumber(entry.index);
@@ -439,7 +394,18 @@ function writePageLabelsDictionary(
   objectsContext.endArray();
 }
 
-/** Reindexes page labels after removing source pages. @private */
+/**
+ * Reindex the page labels for the pages that remain after deletion, keeping
+ * each label's numbering continuous.
+ * @private
+ * @param {Object} parser - The source PDF parser.
+ * @param {Object} catalogDictionary - The catalog dictionary.
+ * @param {Set<number>} deletedPages - One-based page numbers to delete.
+ * @param {number} sourcePageCount - The source page count.
+ * @returns {Object|null} The PageLabels reference, the number tree values
+ *   and the normalized entries; null without page labels.
+ * @throws {Error} If PageLabels is not a valid number tree.
+ */
 function preparePageLabels(
   parser,
   catalogDictionary,
@@ -508,15 +474,21 @@ function preparePageLabels(
     }
   });
   return {
-    catalogValues,
     reference,
     values,
     entries: normalized,
   };
 }
 
-/** Writes updated page labels and attaches them to the catalog. @private */
-function writePageLabels(writer, copyingContext, rootID, pageLabels) {
+/**
+ * Write the updated page labels and attach them to the catalog.
+ * @private
+ * @param {Object} writer - The PDF writer.
+ * @param {Object} copyingContext - Copies unchanged entries.
+ * @param {Object|null} pageLabels - The result of preparePageLabels().
+ * @returns {void}
+ */
+function writePageLabels(writer, copyingContext, pageLabels) {
   if (!pageLabels) return;
 
   const objectsContext = writer.getObjectsContext();
@@ -548,21 +520,7 @@ function writePageLabels(writer, copyingContext, rootID, pageLabels) {
   );
   objectsContext.endDictionary(labelsDictionary).endIndirectObject();
 
-  if (writer._setPageLabelsObject) {
-    writer._setPageLabelsObject(labelsObjectID);
-    return;
-  }
-
-  objectsContext.startModifiedIndirectObject(rootID);
-  const dictionary = objectsContext.startDictionary();
-  Object.keys(pageLabels.catalogValues).forEach((key) => {
-    if (key === "PageLabels") return;
-    dictionary.writeKey(key);
-    copyingContext.copyDirectObjectAsIs(pageLabels.catalogValues[key]);
-  });
-  dictionary.writeKey("PageLabels");
-  objectsContext.writeIndirectObjectReference(labelsObjectID);
-  objectsContext.endDictionary(dictionary).endIndirectObject();
+  setCatalogEntry(writer, PdfName.PAGE_LABELS, labelsObjectID);
 }
 
 /**
@@ -572,8 +530,9 @@ function writePageLabels(writer, copyingContext, rootID, pageLabels) {
  * @name createPage
  * @function
  * @memberof Recipe#
- * @param {number|string} [pageWidth] - The page width, or name of medium size.
- * Known named medium sizes: executive, folio, legal, letter, ledger, tabloid, a0-a10, b0-b10, c0-c10, ra0-ra4, sra0-ara4
+ * @param {number|Recipe.PageSize} [pageWidth] - The page width, or a `Recipe.PageSize` name.
+ * Known named medium sizes: executive, folio, legal, letter, ledger, tabloid, a0-a10, b0-b10, c0-c10, ra0-ra4, sra0-sra4.
+ * Unknown names use the default letter size.
  * @param {number} [pageHeight] - The page height, or rotation (90) when page size name given.
  * @param {object} [margins] - page margin definitions.
  * @param {number} [margins.left] - Left margin.
@@ -581,6 +540,7 @@ function writePageLabels(writer, copyingContext, rootID, pageLabels) {
  * @param {number} [margins.top] - Top margin.
  * @param {number} [margins.bottom] - Bottom margin.
  * @returns {Recipe} The recipe instance.
+ * @throws {Error} If pages were deleted with deletePage() on this Recipe.
  */
 exports.createPage = function createPage(pageWidth, pageHeight, margins) {
   if (this.deletedPages?.size) {
@@ -615,10 +575,12 @@ exports.createPage = function createPage(pageWidth, pageHeight, margins) {
     }
   }
   // from 0
-  this.metadata.pageCount += 1;
+  this.metadata.pageCount =
+    (this.metadata.pageCount ?? this.metadata.pages ?? 0) + 1;
   const pageNumber = this.metadata.pageCount;
   const dimensions = [0, 0, pageWidth, pageHeight];
-  const layout = pageWidth > pageHeight ? "landscape" : "portrait";
+  const layout =
+    pageWidth > pageHeight ? PageLayout.LANDSCAPE : PageLayout.PORTRAIT;
   this.metadata[pageNumber] = {
     pageNumber,
     mediaBox: dimensions,
@@ -635,7 +597,7 @@ exports.createPage = function createPage(pageWidth, pageHeight, margins) {
   this.pageNumber = pageNumber;
   this.pageContext = this.writer.startPageContentContext(this.page);
   this.editingPage = false;
-  this.contextState = "active-new";
+  this.contextState = PAGE_CONTEXT_STATE.ACTIVE_NEW;
   if (!this.isNewPDF) this.pagesCreated = true;
 
   if (margins) {
@@ -646,15 +608,55 @@ exports.createPage = function createPage(pageWidth, pageHeight, margins) {
   return this;
 };
 
+// setPageBox() also accepts the PageBox names.
+const PAGE_BOX_CONSTANTS = {
+  [muhammara.PageBox.MEDIA]: muhammara.ePDFPageBoxMediaBox,
+  [muhammara.PageBox.CROP]: muhammara.ePDFPageBoxCropBox,
+  [muhammara.PageBox.BLEED]: muhammara.ePDFPageBoxBleedBox,
+  [muhammara.PageBox.TRIM]: muhammara.ePDFPageBoxTrimBox,
+  [muhammara.PageBox.ART]: muhammara.ePDFPageBoxArtBox,
+};
+
+/**
+ * Validate a page rotation. PDF allows only multiples of 90 degrees.
+ * @private
+ * @param {*} page - The active page, if any.
+ * @param {*} rotation - The requested rotation.
+ * @throws {TypeError} If no page is active or `rotation` is not a number.
+ * @throws {RangeError} If `rotation` is not a multiple of 90.
+ */
+function checkRotation(page, rotation) {
+  if (!page) {
+    throw new TypeError("rotate requires an active page");
+  }
+  if (typeof rotation !== "number") {
+    throw new TypeError("Rotation is not set to a number");
+  }
+  if (!Number.isInteger(rotation / 90)) {
+    throw new RangeError("Rotation must be a multiple of 90 degrees");
+  }
+}
+
 /**
  * Set the rotation of the current page.
  * @name rotate
  * @function
  * @memberof Recipe#
- * @param {number} rotation - The page rotation in degrees.
+ * @param {number} rotation - The page rotation in degrees, a multiple of 90.
  * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If no page is active or `rotation` is not a number.
+ * @throws {RangeError} If `rotation` is not a multiple of 90.
+ * @throws {Error} If the active page was opened with `editPage()`.
  */
 exports.rotate = function rotate(rotation) {
+  // A page modifier keeps the source page's /Rotate, so the rotation would
+  // only change Recipe's coordinate bookkeeping.
+  if (this.editingPage) {
+    throw new Error(
+      "rotate() is only available on pages created with createPage()",
+    );
+  }
+  checkRotation(this.page, rotation);
   this.page.rotate = rotation;
   this.metadata[this.pageNumber].rotate = rotation;
   return this;
@@ -665,15 +667,20 @@ exports.rotate = function rotate(rotation) {
  * @name setPageBox
  * @function
  * @memberof Recipe#
- * @param {number} box - An `ePDFPageBox*` constant.
+ * @param {number|string} box - An `ePDFPageBox*` constant or a `PageBox` name.
  * @param {number} left - The PDF left coordinate.
  * @param {number} bottom - The PDF bottom coordinate.
  * @param {number} right - The PDF right coordinate.
  * @param {number} top - The PDF top coordinate.
  * @returns {Recipe} The recipe instance.
  * @throws {RangeError} If the page box constant is unknown.
+ * @throws {TypeError} If no page is active.
  */
 exports.setPageBox = function setPageBox(box, left, bottom, right, top) {
+  box = PAGE_BOX_CONSTANTS[box] ?? box;
+  if ([left, bottom, right, top].some((value) => typeof value === "bigint")) {
+    throw new TypeError("setPageBox coordinates must be numbers");
+  }
   const boxes = {
     [muhammara.ePDFPageBoxMediaBox]: "mediaBox",
     [muhammara.ePDFPageBoxCropBox]: "cropBox",
@@ -695,18 +702,19 @@ exports.setPageBox = function setPageBox(box, left, bottom, right, top) {
       mediaBox: pageBox,
       width,
       height,
-      layout: width > height ? "landscape" : "portrait",
+      layout: width > height ? PageLayout.LANDSCAPE : PageLayout.PORTRAIT,
     });
   }
   return this;
 };
 
 /**
- * Finish a page
+ * Finish a page. Without an active page this does nothing.
  * @name endPage
  * @function
  * @memberof Recipe#
  * @returns {Recipe} The recipe instance.
+ * @throws {Error} If the page cannot be written.
  */
 exports.endPage = function endPage() {
   if (!this.page) {
@@ -714,7 +722,8 @@ exports.endPage = function endPage() {
   }
 
   if (this.page.endContext) {
-    if (this.contextState === "active-edit") this.page.endContext();
+    if (this.contextState === PAGE_CONTEXT_STATE.ACTIVE_EDIT)
+      this.page.endContext();
     this.page.writePage();
   } else {
     this.writer.writePage(this.page);
@@ -723,7 +732,7 @@ exports.endPage = function endPage() {
   this.pageContext = null;
   this.pageNumber = 0;
   this.editingPage = false;
-  this.contextState = "idle";
+  this.contextState = PAGE_CONTEXT_STATE.IDLE;
 
   return this;
 };
@@ -733,10 +742,17 @@ exports.endPage = function endPage() {
  * @name editPage
  * @function
  * @memberof Recipe#
- * @param {number} pageNumber - The page number to be edited.
+ * @param {number} pageNumber - The one-based page number to be edited.
  * @returns {Recipe} The recipe instance.
+ * @throws {Error} If the Recipe was not constructed from an existing PDF.
+ * @throws {Error} If the page does not exist in the source PDF.
  */
 exports.editPage = function editPage(pageNumber) {
+  if (this.isNewPDF) {
+    throw new Error(
+      "editPage requires a Recipe constructed from an existing PDF",
+    );
+  }
   const pdfWriter = this.writer;
   const pageIndex = pageNumber - 1;
   const pageModifier = new muhammara.PDFPageModifier(
@@ -748,7 +764,7 @@ exports.editPage = function editPage(pageNumber) {
   this.pageNumber = pageNumber;
   this.pageContext = pageModifier.startContext().getContext();
   this.editingPage = true;
-  this.contextState = "active-edit";
+  this.contextState = PAGE_CONTEXT_STATE.ACTIVE_EDIT;
   this.modifiedSourcePages.add(pageNumber);
 
   this._resumePageRotation(pageNumber);
@@ -759,9 +775,9 @@ exports.editPage = function editPage(pageNumber) {
     const startX = mediaBox[0];
     const startY = mediaBox[1];
     const textOptions = {
-      font: this.writer.getFontForFile(this.fonts["helvetica-bold"]),
+      font: this.writer.getFontForFile(this.fonts.helvetica.b),
       size: 50,
-      colorspace: "gray",
+      colorspace: Colorspace.GRAY,
       color: 0x00,
     };
     context.writeText(
@@ -798,21 +814,105 @@ exports.editPage = function editPage(pageNumber) {
   return this;
 };
 
+/**
+ * Read the page tree and check that the queued deletions can be applied:
+ * the page tree and page labels can be rewritten, and every retained
+ * reference to a deleted page can be pruned or there is none.
+ * @private
+ * @param {Object} recipe - The Recipe.
+ * @param {Object} copyingContext - A copying context for the modified file.
+ * @param {Set<number>} deletedPages - One-based page numbers to delete.
+ * @param {boolean} prune - Whether to prune references to deleted pages.
+ * @returns {Object} The page tree, page labels, catalog entries, deleted
+ *   page object IDs and the pruning plan.
+ * @throws {Error} If the deletion cannot be applied.
+ */
+function planPageDeletion(recipe, copyingContext, deletedPages, prune) {
+  const parser = copyingContext.getSourceDocumentParser();
+  const trailer = parser.getTrailer().toJSObject();
+  const rootID = trailer.Root.toPDFIndirectObjectReference().getObjectID();
+  const catalogDictionary = parser.parseNewObject(rootID).toPDFDictionary();
+  const catalog = catalogDictionary.toJSObject();
+  const pagesReference = catalog.Pages.toPDFIndirectObjectReference();
+  const pageLabels = preparePageLabels(
+    parser,
+    catalogDictionary,
+    deletedPages,
+    recipe.sourcePageCount,
+  );
+  const modifiedPageIDs = new Set(
+    Array.from(recipe.modifiedSourcePages, (pageNumber) =>
+      parser.getPageObjectID(pageNumber - 1),
+    ),
+  );
+  const pageState = {
+    pageNumber: 0,
+    deletedPageIDs: new Set(),
+    retainedPageIDs: new Set(),
+  };
+  const tree = readPageTree(
+    parser,
+    pagesReference.getObjectID(),
+    deletedPages,
+    modifiedPageIDs,
+    pageState,
+    pagesReference.getVersion(),
+  );
+  pageState.retainedPageIDs.forEach((objectID) =>
+    pageState.deletedPageIDs.delete(objectID),
+  );
+  assertSupportedModifiedGenerations(tree, pageLabels);
+  const plan = planDeletedPageReferences(
+    parser,
+    {
+      catalog,
+      rootID,
+      tree,
+      pageLabels,
+      deletedPageIDs: pageState.deletedPageIDs,
+      modifiedPageIDs,
+      sourcePageCount: recipe.sourcePageCount,
+    },
+    prune,
+  );
+  return {
+    catalog,
+    tree,
+    pageLabels,
+    deletedPageIDs: pageState.deletedPageIDs,
+    plan,
+  };
+}
+
 /**
  * Delete one or more pages from an existing PDF.
  * Page numbers are one-based and refer to the original source document.
+ *
+ * By default a page that retained structures still reference - outline
+ * items, link annotations and named destinations, form widgets, tagged-PDF
+ * structure elements or the open action - cannot be deleted. With
+ * `pruneReferences`, those references are removed instead: a destination
+ * that targets a deleted page becomes null (so outline items keep their
+ * title and children, and links do nothing), and every other direct
+ * reference to a deleted page is dropped. Pruning applies to every queued
+ * deletion once any deletePage() call enables it.
  * @name deletePage
  * @function
  * @memberof Recipe#
  * @param {number|number[]} pageNumbers - Page number or page numbers to delete.
+ * @param {Object} [options] - Deletion options.
+ * @param {boolean} [options.pruneReferences=false] - Remove references to the
+ *   deleted pages from retained structures instead of refusing the deletion.
  * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If options is not an object or pruneReferences is not
+ * a boolean.
  * @throws {RangeError} If a page number does not identify an original page.
  * @throws {Error} If the Recipe has no existing source, has ended, would delete
- * every page, or combines deletion with page composition. Page-tree,
- * retained-reference, and object-generation validation is deferred to
- * endPDF(), which throws those errors during finalization.
+ * every page, combines deletion with page composition, or the page tree,
+ * page labels or retained references cannot be rewritten. A failed call
+ * leaves the queued deletions unchanged.
  */
-exports.deletePage = function deletePage(pageNumbers) {
+exports.deletePage = function deletePage(pageNumbers, options) {
   if (this.ended) {
     throw new Error("Cannot delete a page after endPDF");
   }
@@ -828,6 +928,16 @@ exports.deletePage = function deletePage(pageNumbers) {
   if (this.pagesCreated) {
     throw new Error("deletePage cannot be combined with createPage");
   }
+  if (
+    options !== undefined &&
+    (options === null || typeof options !== "object" || Array.isArray(options))
+  ) {
+    throw new TypeError("deletePage expects an options object");
+  }
+  const pruneReferences = options?.pruneReferences;
+  if (pruneReferences !== undefined && typeof pruneReferences !== "boolean") {
+    throw new TypeError("deletePage pruneReferences must be a boolean");
+  }
   pageNumbers = Array.isArray(pageNumbers) ? pageNumbers : [pageNumbers];
   const deletedPages = new Set(this.deletedPages || []);
   pageNumbers.forEach((pageNumber) => {
@@ -843,67 +953,48 @@ exports.deletePage = function deletePage(pageNumbers) {
   if (deletedPages.size >= this.sourcePageCount) {
     throw new Error("At least one page must remain in the PDF");
   }
+  const prune = Boolean(this.pruneReferences || pruneReferences);
+  const copyingContext = this.writer.createPDFCopyingContextForModifiedFile();
+  try {
+    planPageDeletion(this, copyingContext, deletedPages, prune);
+  } finally {
+    copyingContext.end();
+  }
   this.deletedPages = deletedPages;
+  this.pruneReferences = prune;
   return this;
 };
 
-/** Applies queued page deletions during finalization. @private */
+/**
+ * Apply the queued page deletions during finalization: rewrite the page tree
+ * and page labels, prune references to deleted pages when enabled, and
+ * renumber metadata and pending annotations.
+ * @private
+ * @returns {Recipe} The recipe instance.
+ * @throws {Error} If the page tree, page labels or retained references
+ *   cannot be rewritten safely, for example after editing a page that holds
+ *   a pruned reference.
+ */
 exports._deletePages = function _deletePages() {
   if (!this.deletedPages?.size) return this;
 
   const copyingContext = this.writer.createPDFCopyingContextForModifiedFile();
   try {
-    const parser = copyingContext.getSourceDocumentParser();
-    const trailer = parser.getTrailer().toJSObject();
-    const rootReference = trailer.Root.toPDFIndirectObjectReference();
-    const rootID = rootReference.getObjectID();
-    const catalogDictionary = parser.parseNewObject(rootID).toPDFDictionary();
-    const catalog = catalogDictionary.toJSObject();
-    const pagesReference = catalog.Pages.toPDFIndirectObjectReference();
-    const pageLabels = preparePageLabels(
-      parser,
-      catalogDictionary,
+    const deletion = planPageDeletion(
+      this,
+      copyingContext,
       this.deletedPages,
-      this.sourcePageCount,
-    );
-    const modifiedPageIDs = new Set(
-      Array.from(this.modifiedSourcePages, (pageNumber) =>
-        parser.getPageObjectID(pageNumber - 1),
-      ),
+      Boolean(this.pruneReferences),
     );
-    const pageState = {
-      pageNumber: 0,
-      deletedPageIDs: new Set(),
-      retainedPageIDs: new Set(),
-    };
-    const tree = readPageTree(
-      parser,
-      pagesReference.getObjectID(),
-      this.deletedPages,
-      modifiedPageIDs,
-      pageState,
-      pagesReference.getVersion(),
-    );
-    pageState.retainedPageIDs.forEach((objectID) =>
-      pageState.deletedPageIDs.delete(objectID),
-    );
-    assertSupportedModifiedGenerations(
-      tree,
-      pageLabels,
-      rootReference,
+    writePageTree(this.writer, copyingContext, deletion.tree);
+    writePageLabels(this.writer, copyingContext, deletion.pageLabels);
+    pruneDeletedPageReferences(
       this.writer,
+      copyingContext,
+      deletion.catalog,
+      deletion.plan,
+      deletion.deletedPageIDs,
     );
-    validateDeletedPageReferences(
-      parser,
-      catalog,
-      rootID,
-      tree,
-      pageLabels,
-      pageState.deletedPageIDs,
-      this.sourcePageCount,
-    );
-    writePageTree(this.writer, copyingContext, tree);
-    writePageLabels(this.writer, copyingContext, rootID, pageLabels);
   } finally {
     copyingContext.end();
   }
@@ -940,6 +1031,15 @@ exports._deletePages = function _deletePages() {
   return this;
 };
 
+/**
+ * Apply the page rotation to an edited page's content context, so Recipe
+ * coordinates stay upright on rotated source pages.
+ * @private
+ * @param {number} [pageNumber] - The one-based page number; defaults to the active page.
+ * @param {Object} [context] - The content context; defaults to the page context.
+ * @returns {Recipe} The recipe instance.
+ * @throws {TypeError} If the page is unknown.
+ */
 exports._resumePageRotation = function _resumePageRotation(
   pageNumber,
   context,
@@ -981,11 +1081,15 @@ exports._resumePageRotation = function _resumePageRotation(
  * @name pageInfo
  * @function
  * @memberof Recipe#
- * @param {number} pageNumber - The page number.
+ * @param {number} pageNumber - The one-based page number.
  * @returns {RecipePageInfo} The page information.
+ * @throws {TypeError} If the page is unknown.
  */
 exports.pageInfo = function pageInfo(pageNumber) {
   const pageInfo = this.metadata[pageNumber];
+  if (!pageInfo) {
+    throw new TypeError(`Unknown page number: ${pageNumber}`);
+  }
   return {
     width: pageInfo.width,
     height: pageInfo.height,
@@ -1016,13 +1120,13 @@ exports.getCurrentPageInfo = function getCurrentPageInfo() {
  * @throws {Error} If there is no active page content context.
  */
 exports.pauseContext = function pauseContext() {
-  if (this.contextState === "active-edit") {
+  if (this.contextState === PAGE_CONTEXT_STATE.ACTIVE_EDIT) {
     this.page.endContext();
     this.pageContext = null;
-    this.contextState = "paused-edit";
-  } else if (this.contextState === "active-new") {
+    this.contextState = PAGE_CONTEXT_STATE.PAUSED_EDIT;
+  } else if (this.contextState === PAGE_CONTEXT_STATE.ACTIVE_NEW) {
     this.writer.pausePageContentContext(this.pageContext);
-    this.contextState = "paused-new";
+    this.contextState = PAGE_CONTEXT_STATE.PAUSED_NEW;
   } else {
     throw new Error("No active page content context to pause");
   }
@@ -1038,12 +1142,12 @@ exports.pauseContext = function pauseContext() {
  * @throws {Error} If there is no paused page content context.
  */
 exports.resumeContext = function resumeContext() {
-  if (this.contextState === "paused-edit") {
+  if (this.contextState === PAGE_CONTEXT_STATE.PAUSED_EDIT) {
     this.pageContext = this.page.startContext().getContext();
     this._resumePageRotation();
-    this.contextState = "active-edit";
-  } else if (this.contextState === "paused-new") {
-    this.contextState = "active-new";
+    this.contextState = PAGE_CONTEXT_STATE.ACTIVE_EDIT;
+  } else if (this.contextState === PAGE_CONTEXT_STATE.PAUSED_NEW) {
+    this.contextState = PAGE_CONTEXT_STATE.ACTIVE_NEW;
   } else {
     throw new Error("No paused page content context to resume");
   }