PDF.js Deep Dive 8: PDFDocument

const LETTER_SIZE_MEDIABOX = [0, 0, 612, 792];

const STARTXREF_SIGNATURE = new Uint8Array([
  0x73, 0x74, 0x61, 0x72, 0x74, 0x78, 0x72, 0x65, 0x66,
]); // "startxref"

const ENDOBJ_SIGNATURE = new Uint8Array([0x65, 0x6e, 0x64, 0x6f, 0x62, 0x6a]); // "endobj"

function find(stream, signature, limit = 1024, backwards = false) {
  const signatureLength = signature.length;
  const scanBytes = stream.peekBytes(limit); // peek at most limit bytes without moving pos
  const scanLength = scanBytes.length - signatureLength;
  if (scanLength <= 0) {
    return false;
  }
  if (backwards) {
    const signatureEnd = signatureLength - 1;
    let pos = scanBytes.length - 1;
    while (pos >= signatureEnd) {
      let j = 0;
      while (
        j < signatureLength &&
        scanBytes[pos - j] === signature[signatureEnd - j]
      ) {
        j++;
      }
      if (j >= signatureLength) {
        stream.pos += pos - signatureEnd; // hit: move stream.pos to the start of the signature
        return true;
      }
      pos--;
    }
  } else {
    let pos = 0;
    while (pos <= scanLength) {
      let j = 0;
      while (j < signatureLength && scanBytes[pos + j] === signature[j]) {
        j++;
      }
      if (j >= signatureLength) {
        stream.pos += pos;
        return true;
      }
      pos++;
    }
  }
  return false;
}

constructor({
  pdfManager, xref, pageIndex, pageDict, ref,
  globalIdFactory, fontCache, builtInCMapCache, standardFontDataCache,
  globalColorSpaceCache, globalImageCache, systemFontCache,
  nonBlendModesSet, xfaFactory,
}) {
  this.pdfManager = pdfManager;
  this.pageIndex = pageIndex;
  this.pageDict = pageDict;
  this.xref = xref;
  this.ref = ref;
  this.fontCache = fontCache;
  /* ... remaining caches are stored as-is ... */
  this.evaluatorOptions = pdfManager.evaluatorOptions;
  this.xfaFactory = xfaFactory;
 
  const idCounters = { obj: 0 };
  this._localIdFactory = class extends globalIdFactory {
    static createObjId() {
      return `p${pageIndex}_${++idCounters.obj}`;
    }
    static getPageObjId() {
      return `p${ref.toString()}`;
    }
  };
}

_createPartialEvaluator(handler, pageIndex = this.pageIndex) {
  return new PartialEvaluator({
    xref: this.xref,
    handler,
    pageIndex,
    idFactory: this._localIdFactory,
    fontCache: this.fontCache,
    builtInCMapCache: this.builtInCMapCache,
    /* ... remaining caches ... */
    options: this.evaluatorOptions,
  });
}

#getInheritableProperty(key, getArray = false) {
  const value = getInheritableProperty({
    dict: this.pageDict,
    key,
    getArray,
    stopWhenFound: false, // collect every value along the inheritance chain
  });
  if (!Array.isArray(value)) {
    return value;
  }
  if (value.length === 1 || !(value[0] instanceof Dict)) {
    return value[0];
  }
  return Dict.merge({ xref: this.xref, dictArray: value });
}

get content() {
  return this.pageDict.getArray("Contents");
}

get resources() {
  // The spec requires \Resources to exist (it may be empty), but some documents omit it;
  // in that case fall back to an empty dict.
  const resources = this.#getInheritableProperty("Resources");
  return shadow(
    this,
    "resources",
    resources instanceof Dict ? resources : Dict.empty
  );
}

getBoundingBox(name) {
  if (this.xfaData) {
    return this.xfaData.bbox; // XFA page boxes are computed by the template
  }
  const box = lookupNormalRect(
    this.#getInheritableProperty(name, /* getArray = */ true),
    null
  );
  if (box) {
    if (box[2] - box[0] > 0 && box[3] - box[1] > 0) {
      return box;
    }
    warn(`Empty, or invalid, /${name} entry.`);
  }
  return null;
}

get mediaBox() {
  // reset an invalid mediaBox to Letter size
  return shadow(
    this,
    "mediaBox",
    this.getBoundingBox("MediaBox") || LETTER_SIZE_MEDIABOX
  );
}

get cropBox() {
  // degrade an invalid cropBox to mediaBox
  return shadow(this, "cropBox", this.getBoundingBox("CropBox") || this.mediaBox);
}

get userUnit() {
  const obj = this.pageDict.get("UserUnit");
  return shadow(this, "userUnit", typeof obj === "number" && obj > 0 ? obj : 1.0);
}

get view() {
  // Spec (6th edition, p.963): crop/bleed/trim/art box usually should not extend beyond mediaBox;
  // when they do, the effective area shrinks to their intersection.
  const { cropBox, mediaBox } = this;
  if (cropBox !== mediaBox && !isArrayEqual(cropBox, mediaBox)) {
    const box = Util.intersect(cropBox, mediaBox);
    if (box && box[2] - box[0] > 0 && box[3] - box[1] > 0) {
      return shadow(this, "view", box);
    }
    warn("Empty /CropBox and /MediaBox intersection.");
  }
  return shadow(this, "view", mediaBox);
}

get rotate() {
  let rotate = this.#getInheritableProperty("Rotate") || 0;
  // normalize: must be a multiple of 90 and fall in [0, 270]
  if (rotate % 90 !== 0) {
    rotate = 0;
  } else if (rotate >= 360) {
    rotate %= 360;
  } else if (rotate < 0) {
    // the spec does not cover negative numbers; interpret them as counter-clockwise
    rotate = ((rotate % 360) + 360) % 360;
  }
  return shadow(this, "rotate", rotate);
}

#onSubStreamError(reason, objId) {
  if (this.evaluatorOptions.ignoreErrors) {
    warn(`getContentStream - ignoring sub-stream (${objId}): "${reason}".`);
    return;
  }
  throw reason;
}

async getContentStream() {
  const content = await this.pdfManager.ensure(this, "content");
 
  if (content instanceof BaseStream && !content.isImageStream) {
    if (content.isAsync) {
      const bytes = await content.asyncGetBytes();
      if (bytes) {
        return new Stream(bytes, 0, bytes.length, content.dict);
      }
    }
    return content;
  }
  if (Array.isArray(content)) {
    const promises = [];
    for (let i = 0, ii = content.length; i < ii; i++) {
      const item = content[i];
      if (item instanceof BaseStream && item.isAsync) {
        promises.push(
          item.asyncGetBytes().then(bytes => {
            if (bytes) {
              content[i] = new Stream(bytes, 0, bytes.length, item.dict);
            }
          })
        );
      }
    }
    if (promises.length > 0) {
      await Promise.all(promises);
    }
    return new StreamsSequenceStream(content, this.#onSubStreamError.bind(this));
  }
  // no page content: substitute an empty stream
  return new NullStream();
}

get xfaData() {
  return shadow(
    this,
    "xfaData",
    this.xfaFactory ? { bbox: this.xfaFactory.getBoundingBox(this.pageIndex) } : null
  );
}

async #replaceIdByRef(annotations, deletedAnnotations, existingAnnotations) {
  const promises = [];
  for (const annotation of annotations) {
    if (!annotation.id) continue;
    const ref = Ref.fromString(annotation.id);
    if (!ref) {
      warn(`A non-linked annotation cannot be modified: ${annotation.id}`);
      continue;
    }
    if (annotation.deleted) {
      deletedAnnotations.put(ref); // mark for deletion
      if (annotation.popupRef) { /* delete the popup as well */ }
      continue;
    }
    if (annotation.popup?.deleted) { /* delete the popup on its own */ }
    existingAnnotations?.put(ref);
    annotation.ref = ref;
    promises.push(
      this.xref.fetchAsync(ref).then(obj => {
        if (obj instanceof Dict) {
          annotation.oldAnnotation = obj.clone(); // keep the old dict for incremental updates
        }
      }, () => warn(`Cannot fetch \`oldAnnotation\` for: ${ref}.`))
    );
    delete annotation.id;
  }
  await Promise.all(promises);
}

async saveNewAnnotations(handler, task, annotations, imagePromises, changes) {
  if (this.xfaFactory) {
    throw new Error("XFA: Cannot save new annotations.");
  }
  const partialEvaluator = this._createPartialEvaluator(handler);
 
  const deletedAnnotations = new RefSet();
  const existingAnnotations = new RefSet();
  await this.#replaceIdByRef(annotations, deletedAnnotations, existingAnnotations);
 
  const pageDict = this.pageDict;
  const annotationsArray = this.annotations.filter(
    a => !(a instanceof Ref && deletedAnnotations.has(a))
  );
  const newData = await AnnotationFactory.saveNewAnnotations(
    partialEvaluator, this.xref, task, annotations, imagePromises, changes
  );
 
  for (const { ref } of newData.annotations) {
    if (ref instanceof Ref && !existingAnnotations.has(ref)) {
      annotationsArray.push(ref); // attach the new annotation ref to the page
    }
  }
 
  const dict = pageDict.clone();
  dict.set("Annots", annotationsArray);
  changes.put(this.ref, { data: dict }); // the page dict itself is a change entry too
 
  for (const deletedRef of deletedAnnotations) {
    changes.put(deletedRef, { data: null }); // data: null means delete that object
  }
}

async save(handler, task, annotationStorage, changes) {
  const partialEvaluator = this._createPartialEvaluator(handler);
  const annotations = await this._parsedAnnotations;
 
  const promises = [];
  for (const annotation of annotations) {
    promises.push(
      annotation
        .save(partialEvaluator, task, annotationStorage, changes)
        .catch(reason => {
          warn(`save - ignoring annotation data during "${task.name}" task: "${reason}".`);
          return null;
        })
    );
  }
  return Promise.all(promises);
}

async loadResources(keys) {
  // TODO: add async `#getInheritableProperty` and remove this.
  await (this.#resourcesPromise ??= this.pdfManager.ensure(this, "resources"));
  await ObjectLoader.load(this.resources, keys, this.xref);
}

async #getMergedResources(streamDict, keys) {
  // in rare cases the /Contents stream dict also carries /Resources, which takes priority
  // (see issue18894.pdf)
  const localResources = streamDict?.get("Resources");
  if (!(localResources instanceof Dict && localResources.size)) {
    return this.resources;
  }
  await ObjectLoader.load(localResources, keys, this.xref);
  return Dict.merge({
    xref: this.xref,
    dictArray: [localResources, this.resources],
    mergeSubDicts: true,
  });
}

async getOperatorList({
  handler, sink, task, intent, cacheKey,
  pageIndex = this.pageIndex,
  annotationStorage = null,
  modifiedIds = null,
}) {
  const contentStreamPromise = this.getContentStream();
  const resourcesPromise = this.loadResources(RESOURCES_KEYS_OPERATOR_LIST);
  const partialEvaluator = this._createPartialEvaluator(handler, pageIndex);
 
  const newAnnotsByPage = !this.xfaFactory
    ? getNewAnnotationsMap(annotationStorage)
    : null;
  const newAnnots = newAnnotsByPage?.get(this.pageIndex);
  /* ... if there are new editor annotations: collect missing bitmaps, then
         AnnotationFactory.generateImages → AnnotationFactory.printNewAnnotations for their opList ... */
 
  const pageListPromise = Promise.all([
    contentStreamPromise,
    resourcesPromise,
  ]).then(async ([contentStream]) => {
    const resources = await this.#getMergedResources(
      contentStream.dict,
      RESOURCES_KEYS_OPERATOR_LIST
    );
    const opList = new OperatorList(intent, sink);
    handler.send("StartRenderPage", {
      transparency: partialEvaluator.hasBlendModes(resources, this.nonBlendModesSet),
      pageIndex,
      cacheKey,
    });
    await partialEvaluator.getOperatorList({
      stream: contentStream,
      task,
      resources,
      operatorList: opList,
    });
    return opList;
  });
 
  let [pageOpList, annotations, newAnnotations] = await Promise.all([
    pageListPromise,
    this._parsedAnnotations,
    newAnnotationsPromise,
  ]);
  /* ... merge the new annotations (refToReplace replaces the old ones) ... */
}

const renderForms = !!(intent & RenderingIntentFlag.ANNOTATIONS_FORMS),
  isEditing = !!(intent & RenderingIntentFlag.IS_EDITING),
  intentAny = !!(intent & RenderingIntentFlag.ANY),
  intentDisplay = !!(intent & RenderingIntentFlag.DISPLAY),
  intentPrint = !!(intent & RenderingIntentFlag.PRINT);
 
for (const annotation of annotations) {
  if (
    intentAny ||
    (intentDisplay && annotation.mustBeViewed(...) && annotation.mustBeViewedWhenEditing(...)) ||
    (intentPrint && annotation.mustBePrinted(annotationStorage))
  ) {
    opListPromises.push(annotation.getOperatorList(partialEvaluator, task, intent, annotationStorage));
  }
}
const opLists = await Promise.all(opListPromises);
for (const { opList, separateForm, separateCanvas } of opLists) {
  pageOpList.addOpList(opList);
  form ||= separateForm;
  canvas ||= separateCanvas;
}
pageOpList.flush(true, { form, canvas });

async extractTextContent({
  handler, task, includeMarkedContent, disableNormalization, sink, intersector = null,
}) {
  const contentStreamPromise = this.getContentStream();
  const resourcesPromise = this.loadResources(RESOURCES_KEYS_TEXT_CONTENT);
  const langPromise = this.pdfManager.ensureCatalog("lang");
 
  const [contentStream, , lang] = await Promise.all([...]);
  const resources = await this.#getMergedResources(
    contentStream.dict, RESOURCES_KEYS_TEXT_CONTENT
  );
  const partialEvaluator = this._createPartialEvaluator(handler);
 
  return partialEvaluator.getTextContent({
    stream: contentStream, task, resources,
    includeMarkedContent, disableNormalization, sink,
    viewBox: this.view, lang, intersector,
  });
}

async getStructTree() {
  const structTreeRoot = await this.pdfManager.ensureCatalog("structTreeRoot");
  if (!structTreeRoot) return null;
  // ensure structTree includes this page's annotations
  await this._parsedAnnotations;
  try {
    const structTree = await this.pdfManager.ensure(this, "_parseStructTree", [structTreeRoot]);
    return await this.pdfManager.ensure(structTree, "serializable");
  } catch (ex) {
    warn(`getStructTree: "${ex}".`);
    return null;
  }
}

_parseStructTree(structTreeRoot) {
  const tree = new StructTreePage(structTreeRoot, this.pageDict);
  tree.parse(this.ref);
  return tree;
}

async getAnnotationsData(handler, task, intent) {
  const annotations = await this._parsedAnnotations;
  if (annotations.length === 0) return annotations;
 
  const annotationsData = [], textContentPromises = [];
  let partialEvaluator;
  /* ... unpack the intent flags ... */
  const highlightedAnnotations = [];
 
  for (const annotation of annotations) {
    const isVisible = intentAny || (intentDisplay && annotation.viewable);
    if (isVisible || (intentPrint && annotation.printable)) {
      annotationsData.push(annotation.data); // serialized data
    }
    if (annotation.hasTextContent && isVisible) {
      // popup-like annotations need their content text extracted
      partialEvaluator ??= this._createPartialEvaluator(handler);
      textContentPromises.push(annotation.extractTextContent(partialEvaluator, task, [-Inf, -Inf, Inf, Inf]));
    } else if (annotation.overlaysTextContent && isVisible) {
      highlightedAnnotations.push(annotation);
    }
  }
 
  if (highlightedAnnotations.length > 0) {
    const intersector = new Intersector(highlightedAnnotations);
    textContentPromises.push(
      this.extractTextContent({ /* ..., */ intersector })
        .then(() => intersector.setText())
    );
  }
  await Promise.all(textContentPromises);
  return annotationsData;
}

get annotations() {
  const annots = this.#getInheritableProperty("Annots");
  return shadow(this, "annotations", Array.isArray(annots) ? annots : []);
}

get _parsedAnnotations() {
  const promise = this.pdfManager
    .ensure(this, "annotations")
    .then(async annots => {
      if (annots.length === 0) return annots;
 
      const [annotationGlobals, fieldObjects] = await Promise.all([
        this.pdfManager.ensureDoc("annotationGlobals"),
        this.pdfManager.ensureDoc("fieldObjects"),
      ]);
      if (!annotationGlobals) return [];
 
      const orphanFields = fieldObjects?.orphanFields;
      const annotationPromises = [];
      for (const annotationRef of annots) {
        annotationPromises.push(
          AnnotationFactory.create(
            this.xref, annotationRef, annotationGlobals,
            this._localIdFactory, false, orphanFields, null, this.ref
          ).catch(reason => {
            warn(`_parsedAnnotations: "${reason}".`);
            return null; // a single failure does not affect the rest
          })
        );
      }
 
      const sortedAnnotations = [];
      let popupAnnotations, widgetAnnotations;
      // Popup depends on its parent annotation existing in the display layer, so it must come last (fixes issue 11362)
      for (const annotation of await Promise.all(annotationPromises)) {
        if (!annotation) continue;
        if (annotation instanceof WidgetAnnotation) {
          (widgetAnnotations ||= []).push(annotation);
          continue;
        }
        if (annotation instanceof PopupAnnotation) {
          (popupAnnotations ||= []).push(annotation);
          continue;
        }
        sortedAnnotations.push(annotation);
      }
      if (widgetAnnotations) sortedAnnotations.push(...widgetAnnotations);
      if (popupAnnotations) sortedAnnotations.push(...popupAnnotations);
      return sortedAnnotations;
    });
 
  return shadow(this, "_parsedAnnotations", promise);
}

get jsActions() {
  const actions = collectActions(this.xref, this.pageDict, PageActionEventType);
  return shadow(this, "jsActions", actions);
}

async collectAnnotationsByType(handler, task, types, promises, annotationGlobals) {
  const { pageIndex } = this;
 
  if (Object.hasOwn(this, "_parsedAnnotations")) {
    // already parsed: filter from the cache by type
    const cachedAnnotations = await this._parsedAnnotations;
    for (const { data } of cachedAnnotations) {
      if (!types || types.has(data.annotationType)) {
        data.pageIndex = pageIndex;
        promises.push(Promise.resolve(data));
      }
    }
    return;
  }
 
  // not parsed: create lazily and filter by type at create time (avoid fully parsing every annotation)
  const annots = await this.pdfManager.ensure(this, "annotations");
  let partialEvaluator;
  for (const annotationRef of annots) {
    promises.push(
      AnnotationFactory.create(
        this.xref, annotationRef, annotationGlobals, this._localIdFactory,
        false, null, types, this.ref
      ).then(async annotation => {
        if (!annotation) return null;
        annotation.data.pageIndex = pageIndex;
        if (annotation.hasTextContent && annotation.viewable) {
          partialEvaluator ??= this._createPartialEvaluator(handler);
          await annotation.extractTextContent(/* ... */);
        }
        return annotation.data;
      })
      /* ... catch for fault tolerance ... */
    );
  }
}

constructor(pdfManager, stream) {
  /* test builds assert that stream is a BaseStream */
  if (stream.length <= 0) {
    throw new InvalidPDFException("The PDF file is empty, i.e. its size is zero bytes.");
  }
  this.pdfManager = pdfManager;
  this.stream = stream;
  this.xref = new XRef(stream, pdfManager);
 
  const idCounters = { font: 0 };
  this._globalIdFactory = class {
    static getDocId() {
      return `g_${pdfManager.docId}`;
    }
    static createFontId() {
      return `f${++idCounters.font}`;
    }
    static createObjId() {
      unreachable("Abstract method `createObjId` called.");
    }
    static getPageObjId() {
      unreachable("Abstract method `getPageObjId` called.");
    }
  };
}

parse(recoveryMode) {
  this.xref.parse(recoveryMode);
  this.catalog = new Catalog(this.pdfManager, this.xref);
}

get linearization() {
  let linearization = null;
  try {
    linearization = Linearization.create(this.stream);
  } catch (err) {
    if (err instanceof MissingDataException) {
      throw err; // data has not arrived during streaming; rethrow so the layer below keeps fetching
    }
    info(err); // other errors are only logged; treat the document as non-linearized
  }
  return shadow(this, "linearization", linearization);
}

get startXRef() {
  const stream = this.stream;
  let startXRef = 0;
 
  if (this.linearization) {
    // linearized document: find the first object's endobj; the xref of the first page section follows
    stream.reset();
    if (find(stream, ENDOBJ_SIGNATURE)) {
      stream.skip(6);
      let ch = stream.peekByte();
      while (isWhiteSpace(ch)) { stream.pos++; ch = stream.peekByte(); }
      startXRef = stream.pos - stream.start;
    }
  } else {
    // ordinary document: scan backwards from the end of the file for startxref
    const step = 1024;
    const startXRefLength = STARTXREF_SIGNATURE.length;
    let found = false, pos = stream.end;
    while (!found && pos > 0) {
      pos -= step - startXRefLength;
      if (pos < 0) pos = 0;
      stream.pos = pos;
      found = find(stream, STARTXREF_SIGNATURE, step, true); // backwards
    }
    if (found) {
      stream.skip(9);
      let ch;
      do { ch = stream.getByte(); } while (isWhiteSpace(ch));
      let str = "";
      while (ch >= 0x20 && ch <= 0x39) {
        str += String.fromCharCode(ch);
        ch = stream.getByte();
      }
      startXRef = parseInt(str, 10);
      if (isNaN(startXRef)) startXRef = 0;
    }
  }
  return shadow(this, "startXRef", startXRef);
}

checkHeader() {
  const stream = this.stream;
  stream.reset();
 
  if (!find(stream, PDF_HEADER_SIGNATURE)) {
    // probably not a PDF file, but do not throw; let parsing continue (best effort)
    return;
  }
  stream.moveStart(); // move the stream start to the signature; all later offsets are relative to it
 
  stream.skip(PDF_HEADER_SIGNATURE.length); // skip "%PDF-"
  let version = "", ch;
  while ((ch = stream.getByte()) > 0x20 && version.length < 7) {
    version += String.fromCharCode(ch);
  }
  if (PDF_VERSION_REGEXP.test(version)) {
    this.#version = version; // e.g. "1.7"
  } else {
    warn(`Invalid PDF header version: ${version}`);
  }
}

parseStartXRef() {
  this.xref.setStartXRef(this.startXRef);
}

get numPages() {
  let num = 0;
  if (this.catalog.hasActualNumPages) {
    num = this.catalog.numPages;
  } else if (this.xfaFactory) {
    num = this.xfaFactory.getNumPages(); // returns a Promise
  } else if (this.linearization) {
    num = this.linearization.numPages;
  } else {
    num = this.catalog.numPages;
  }
  return shadow(this, "numPages", num);
}

#hasOnlyDocumentSignatures(fields, recursionDepth = 0) {
  const RECURSION_LIMIT = 10;
  if (!Array.isArray(fields)) return false;
  return fields.every(field => {
    field = this.xref.fetchIfRef(field);
    if (!(field instanceof Dict)) return false;
    if (field.has("Kids")) {
      if (++recursionDepth > RECURSION_LIMIT) {
        warn("#hasOnlyDocumentSignatures: maximum recursion depth reached");
        return false;
      }
      return this.#hasOnlyDocumentSignatures(field.get("Kids"), recursionDepth);
    }
    const isSignature = isName(
      getInheritableProperty({ dict: field, key: "FT" }),
      "Sig"
    );
    const rectangle = field.get("Rect");
    const isInvisible = Array.isArray(rectangle) && rectangle.every(v => v === 0);
    return isSignature && isInvisible;
  });
}

get _xfaStreams() {
  const { acroForm } = this.catalog;
  if (!acroForm) return null;
 
  const xfa = acroForm.get("XFA");
  const entries = new Map(
    ["xdp:xdp", "template", "datasets", "config", "connectionSet",
     "localeSet", "stylesheet", "/xdp:xdp"].map(e => [e, null])
  );
  if (xfa instanceof BaseStream && !xfa.isEmpty) {
    entries.set("xdp:xdp", xfa); // single-stream form: the whole XDP packed into one stream
    return entries;
  }
  if (!Array.isArray(xfa) || xfa.length === 0) return null;
 
  for (let i = 0, ii = xfa.length; i < ii; i += 2) {
    let name;
    if (i === 0) name = "xdp:xdp";
    else if (i === ii - 2) name = "/xdp:xdp";
    else name = xfa[i];
    if (!entries.has(name)) continue;
    const data = this.xref.fetchIfRef(xfa[i + 1]);
    if (!(data instanceof BaseStream) || data.isEmpty) continue;
    entries.set(name, data);
  }
  return entries;
}

get xfaDatasets() {
  const streams = this._xfaStreams;
  if (!streams) return shadow(this, "xfaDatasets", null);
  for (const key of ["datasets", "xdp:xdp"]) {
    const stream = streams.get(key);
    if (!stream) continue;
    try {
      const str = stringToUTF8String(stream.getString());
      return shadow(this, "xfaDatasets", new DatasetReader({ [key]: str }));
    } catch {
      warn("XFA - Invalid utf-8 string.");
      break;
    }
  }
  return shadow(this, "xfaDatasets", null);
}

get xfaData() {
  const streams = this._xfaStreams;
  if (!streams) return null;
  const data = new Map();
  for (const [key, stream] of streams) {
    if (!stream) continue;
    try {
      data.set(key, stringToUTF8String(stream.getString()));
    } catch {
      warn("XFA - Invalid utf-8 string.");
      return null;
    }
  }
  return data;
}

get xfaFactory() {
  let data;
  if (
    this.pdfManager.enableXfa &&
    this.catalog.needsRendering &&
    this.formInfo.hasXfa &&
    !this.formInfo.hasAcroForm
  ) {
    data = this.xfaData;
  }
  return shadow(this, "xfaFactory", data ? new XFAFactory(data) : null);
}

get isPureXfa() {
  return this.xfaFactory ? this.xfaFactory.isValid() : false;
}

get htmlForXfa() {
  return this.xfaFactory ? this.xfaFactory.getPages() : null;
}

async #loadXfaImages() {
  const xfaImages = await this.pdfManager.ensureCatalog("xfaImages");
  if (!xfaImages) return;
  this.xfaFactory.setImages(xfaImages);
}

async #loadXfaFonts(handler, task) {
  const acroForm = await this.pdfManager.ensureCatalog("acroForm");
  if (!acroForm) return;
  const resources = await acroForm.getAsync("DR"); // document-level default resources
  if (!(resources instanceof Dict)) return;
  await ObjectLoader.load(resources, ["Font"], this.xref);
 
  const fontRes = resources.get("Font");
  if (!(fontRes instanceof Dict)) return;
 
  const options = Object.assign(
    Object.create(null),
    this.pdfManager.evaluatorOptions,
    { useSystemFonts: false } // XFA fonts must use embedded data for consistent rendering
  );
  const { builtInCMapCache, fontCache, standardFontDataCache } = this.catalog;
 
  const partialEvaluator = new PartialEvaluator({
    xref: this.xref,
    handler,
    pageIndex: -1, // global context, not belonging to any page
    idFactory: this._globalIdFactory,
    fontCache, builtInCMapCache, standardFontDataCache,
    options,
  });
  const pdfFonts = [];
  const initialState = {
    get font() { return pdfFonts.at(-1); },
    set font(font) { pdfFonts.push(font); },
    clone() { return this; },
  };
  /* ... walk fontRes, build cssFontInfo from the FontDescriptor, load via parseFont ... */
  await Promise.all(promises);
  const missingFonts = this.xfaFactory.setFonts(pdfFonts);
  /* ... for missing fonts, use getXfaFontDict to generate Regular/Bold/Italic/BoldItalic
         substitutes and load one more round, then appendFonts ... */
}

loadXfaResources(handler, task) {
  return Promise.all([
    this.#loadXfaFonts(handler, task).catch(() => {
      // ignore errors so the document can still open
    }),
    this.#loadXfaImages(),
  ]);
}

serializeXfaData(annotationStorage) {
  return this.xfaFactory ? this.xfaFactory.serializeData(annotationStorage) : null;
}

get version() {
  return this.catalog.version || this.#version;
}

get formInfo() {
  const formInfo = {
    hasFields: false, hasAcroForm: false, hasXfa: false, hasSignatures: false,
  };
  const { acroForm } = this.catalog;
  if (!acroForm) return shadow(this, "formInfo", formInfo);
 
  try {
    const fields = acroForm.get("Fields");
    const hasFields = Array.isArray(fields) && fields.length > 0;
    formInfo.hasFields = hasFields;
 
    const xfa = acroForm.get("XFA");
    formInfo.hasXfa =
      (Array.isArray(xfa) && xfa.length > 0) ||
      (xfa instanceof BaseStream && !xfa.isEmpty);
 
    // some documents contain only XFA but put invisible document signatures in Fields;
    // bit 1 of SigFlags (spec Table 219) detects that signatures exist
    const sigFlags = acroForm.get("SigFlags");
    const hasSignatures = !!(sigFlags & 0x1);
    const hasOnlyDocumentSignatures =
      hasSignatures && this.#hasOnlyDocumentSignatures(fields);
    formInfo.hasAcroForm = hasFields && !hasOnlyDocumentSignatures;
    formInfo.hasSignatures = hasSignatures;
  } catch (ex) {
    if (ex instanceof MissingDataException) throw ex;
    warn(`Cannot fetch form information: "${ex}".`);
  }
  return shadow(this, "formInfo", formInfo);
}

get documentInfo() {
  const docInfo = {
    PDFFormatVersion: this.version,
    Language: catalog.lang,
    EncryptFilterName: xref.encrypt?.filterName ?? null,
    IsLinearized: !!this.linearization,
    IsAcroFormPresent: formInfo.hasAcroForm,
    IsXFAPresent: formInfo.hasXfa,
    IsCollectionPresent: !!catalog.collection,
    IsSignaturesPresent: formInfo.hasSignatures,
  };
 
  let infoDict;
  try {
    infoDict = xref.trailer.get("Info");
  } catch (err) { /* rethrow MissingDataException, log the rest via info */ }
  if (!(infoDict instanceof Dict)) return shadow(this, "documentInfo", docInfo);
 
  for (const [key, value] of infoDict) {
    switch (key) {
      case "Title": case "Author": /* ... the 8 standard keys ... */
        if (typeof value === "string") { docInfo[key] = stringToPDFString(value); continue; }
        break;
      case "Trapped":
        if (value instanceof Name) { docInfo[key] = value; continue; }
        break;
      default:
        // custom keys: only whitelisted types string/number/boolean/Name are accepted,
        // so that non-serializable objects such as Dict/Stream are not sent to the main thread
        /* ... */
        (docInfo.Custom ??= new Map()).set(key, customValue);
        continue;
    }
    warn(`Bad value, for key "${key}", in Info: ${value}.`);
  }
  return shadow(this, "documentInfo", docInfo);
}

get fingerprints() {
  const FINGERPRINT_FIRST_BYTES = 1024;
  const EMPTY_FINGERPRINT = "\x00".repeat(16);
 
  function validate(data) {
    return typeof data === "string" && data.length === 16 && data !== EMPTY_FINGERPRINT;
  }
 
  const id = this.xref.trailer.get("ID");
  let hashOriginal, hashModified;
  if (Array.isArray(id) && validate(id[0])) {
    hashOriginal = stringToBytes(id[0]);
    if (id[1] !== id[0] && validate(id[1])) {
      hashModified = stringToBytes(id[1]);
    }
  } else {
    hashOriginal = calculateMD5(
      this.stream.getByteRange(0, FINGERPRINT_FIRST_BYTES), 0, FINGERPRINT_FIRST_BYTES
    );
  }
  return shadow(this, "fingerprints", [hashOriginal.toHex(), hashModified?.toHex() ?? null]);
}

async #getLinearizationPage(pageIndex) {
  /* test builds assert linearization.pageFirst === pageIndex */
  const ref = Ref.get(linearization.objectNumberFirst, 0);
  try {
    const obj = await xref.fetchAsync(ref);
    if (obj instanceof Dict) {
      let type = obj.getRaw("Type");
      if (type instanceof Ref) type = await xref.fetchAsync(type);
      if (
        isName(type, "Page") ||
        (!obj.has("Type") && !obj.has("Kids") && obj.has("Contents"))
      ) {
        // opportunistically fill the two Catalog caches to speed up later getPageIndex
        if (!catalog.pageKidsCountCache.has(ref)) catalog.pageKidsCountCache.put(ref, 1);
        if (!catalog.pageIndexCache.has(ref)) catalog.pageIndexCache.put(ref, 0);
        return [obj, ref];
      }
    }
    throw new FormatError("The Linearization dictionary doesn't point to a valid Page dictionary.");
  } catch (reason) {
    warn(`_getLinearizationPage: "${reason.message}".`);
    return catalog.getPageDict(pageIndex); // fall back to the normal page tree walk
  }
}

getPage(pageIndex) {
  const cachedPromise = this.#pagePromises.get(pageIndex);
  if (cachedPromise) return cachedPromise;
  const { catalog, linearization, xfaFactory } = this;
 
  let promise;
  if (xfaFactory) {
    promise = Promise.resolve([Dict.empty, null]); // pure XFA: empty page dict
  } else if (linearization?.pageFirst === pageIndex) {
    promise = this.#getLinearizationPage(pageIndex); // linearized first-page shortcut
  } else {
    promise = catalog.getPageDict(pageIndex); // normal: walk the page tree
  }
  promise = promise.then(
    ([pageDict, ref]) =>
      new Page({
        pdfManager: this.pdfManager,
        xref: this.xref, pageIndex, pageDict, ref,
        globalIdFactory: this._globalIdFactory,
        fontCache: catalog.fontCache,
        /* ... every document-level cache held by Catalog ... */
        nonBlendModesSet: catalog.nonBlendModesSet,
        xfaFactory,
      })
  );
 
  this.#pagePromises.set(pageIndex, promise);
  return promise;
}

async checkFirstPage(recoveryMode = false) {
  if (recoveryMode) return;
  try {
    await this.getPage(0);
  } catch (reason) {
    if (reason instanceof XRefEntryException) {
      // clear the cache first so that stale inconsistent state does not break later getPage calls
      this.#pagePromises.delete(0);
      await this.cleanup();
      throw new XRefParseException();
    }
  }
}

async checkLastPage(recoveryMode = false) {
  const { catalog, pdfManager } = this;
  catalog.setActualNumPages(); // always reset first
  let numPages;
  try {
    await Promise.all([
      pdfManager.ensureDoc("xfaFactory"),
      pdfManager.ensureDoc("linearization"),
      pdfManager.ensureCatalog("numPages"),
    ]);
    if (this.xfaFactory) return; // XFA page counts are always reliable
    numPages = this.linearization ? this.linearization.numPages : catalog.numPages;
    if (!Number.isInteger(numPages)) {
      throw new FormatError("Page count is not an integer.");
    } else if (numPages <= 1) return;
    await this.getPage(numPages - 1); // try to fetch the last page
  } catch (reason) {
    this.#pagePromises.delete(numPages - 1);
    await this.cleanup();
    if (reason instanceof XRefEntryException && !recoveryMode) {
      throw new XRefParseException();
    }
    warn(`checkLastPage - invalid /Pages tree /Count: ${numPages}.`);
 
    let pagesTree;
    try {
      pagesTree = await catalog.getAllPageDicts(recoveryMode); // walk the entire page tree
    } catch (reasonAll) {
      /* XRefEntryException: throw to recovery as above; otherwise settle on 1 page */
      catalog.setActualNumPages(1);
      return;
    }
    // rebuild the whole page cache from the real walk and correct the page count
    for (const [pageIndex, [pageDict, ref]] of pagesTree) {
      let promise;
      if (pageDict instanceof Error) {
        promise = Promise.reject(pageDict);
        promise.catch(() => {}); // avoid flooding with "uncaught exception"
      } else {
        promise = Promise.resolve(new Page({ /* ... */ }));
      }
      this.#pagePromises.set(pageIndex, promise);
    }
    catalog.setActualNumPages(pagesTree.size);
  }
}

async fontFallback(id, handler) {
  const { catalog, pdfManager } = this;
  for (const translatedFont of await Promise.all(catalog.fontCache)) {
    if (translatedFont.loadedName === id) {
      translatedFont.fallback(handler, pdfManager.evaluatorOptions);
      return;
    }
  }
}

async cleanup(manuallyTriggered = false) {
  return this.catalog ? this.catalog.cleanup(manuallyTriggered) : clearGlobalCaches();
}

async #collectFieldObjects(
  name, parentRef, fieldRef, promises, annotationGlobals, visitedRefs, orphanFields
) {
  const { xref } = this;
  if (!(fieldRef instanceof Ref) || visitedRefs.has(fieldRef)) return;
  visitedRefs.put(fieldRef);
  const field = await xref.fetchAsync(fieldRef);
  if (!(field instanceof Dict)) return;
 
  let subtype = await field.getAsync("Subtype");
  subtype = subtype instanceof Name ? subtype.name : null;
  switch (subtype) {
    case "Link": return; // skip unrelated annotation types (issue 19281)
  }
 
  if (field.has("T")) {
    const partName = stringToPDFString(await field.getAsync("T"));
    name = name === "" ? partName : `${name}.${partName}`; // build the hierarchical name a.b.c
  } else {
    // the field has no /T of its own: walk up the Parent chain (with cycle detection)
    let obj = field;
    const walkedRefs = new RefSet();
    while (true) {
      obj = obj.getRaw("Parent") || parentRef;
      /* ... visitedRefs + walkedRefs, two sets, guard against Parent cycles ... */
      if (obj.has("T")) { /* build the name and break */ }
    }
  }
 
  if (parentRef && !field.has("Parent") && isName(field.get("Subtype"), "Widget")) {
    orphanFields.put(fieldRef, parentRef); // the parent field refers to it, but it has no Parent
  }
 
  promises.getOrInsertComputed(name, makeArr).push(
    AnnotationFactory.create(xref, fieldRef, annotationGlobals, null, true, orphanFields, null, null)
      .then(annotation => annotation?.getFieldObject())
      .catch(/* tolerate failure, return null */)
  );
 
  if (!field.has("Kids")) return;
  const kids = await field.getAsync("Kids");
  if (Array.isArray(kids)) {
    for (const kid of kids) {
      await this.#collectFieldObjects(name, fieldRef, kid, promises, ...); // recurse downwards
    }
  }
}

get fieldObjects() {
  const promise = this.pdfManager.ensureDoc("formInfo").then(async formInfo => {
    if (!formInfo.hasFields) return null;
    const annotationGlobals = await this.annotationGlobals;
    if (!annotationGlobals) return null;
    const { acroForm } = annotationGlobals;
 
    const visitedRefs = new RefSet();
    const allFields = new Map();
    const fieldPromises = new Map();
    const orphanFields = new RefMap();
    for (const fieldRef of acroForm.get("Fields")) {
      await this.#collectFieldObjects("", null, fieldRef, fieldPromises,
        annotationGlobals, visitedRefs, orphanFields);
    }
 
    const allPromises = [];
    for (const [name, promises] of fieldPromises) {
      allPromises.push(
        Promise.all(promises).then(fields => {
          fields = fields.filter(Boolean);
          if (fields.length > 0) allFields.set(name, fields);
        })
      );
    }
    await Promise.all(allPromises);
    return {
      allFields: allFields.size ? allFields : null,
      orphanFields,
    };
  });
  return shadow(this, "fieldObjects", promise);
}

async #collectSignatureFields(fields, out, visitedRefs) {
  if (!Array.isArray(fields)) return;
  for (const fieldRef of fields) {
    if (fieldRef instanceof Ref) {
      if (visitedRefs.has(fieldRef)) continue;
      visitedRefs.put(fieldRef);
    }
    const field = await this.xref.fetchIfRefAsync(fieldRef);
    if (!(field instanceof Dict)) continue;
    if (isName(await field.getAsync("FT"), "Sig")) {
      const sigDict = await field.getAsync("V"); // the signature dictionary
      if (sigDict instanceof Dict) {
        const parsed = await this.#parseSignatureDict(field, sigDict, fieldRef);
        if (parsed) out.push(parsed);
      }
    }
    if (field.has("Kids")) {
      // the Widget child annotations of a terminal field must be visited too, so collect self first, then recurse
      await this.#collectSignatureFields(await field.getAsync("Kids"), out, visitedRefs);
    }
  }
}

async #getByteRange(begin, end) {
  try {
    return this.stream.getByteRange(begin, end);
  } catch (ex) {
    if (!(ex instanceof MissingDataException)) throw ex;
    await this.pdfManager.requestRange(begin, end); // streaming: request the missing range, then retry
    return this.#getByteRange(begin, end);
  }
}

async #coversWholeDocument(signedEnd, modificationsAfterSignature) {
  if (modificationsAfterSignature > 0) return false;
 
  const fileLength = this.stream.end;
  for (let begin = signedEnd; begin < fileLength; begin += SIGNATURE_TAIL_CHUNK_SIZE) {
    const end = Math.min(begin + SIGNATURE_TAIL_CHUNK_SIZE, fileLength);
    const tail = await this.#getByteRange(begin, end);
    for (const byte of tail) {
      if (byte !== 0x00 && byte !== 0x09 && byte !== 0x0a &&
          byte !== 0x0c && byte !== 0x0d && byte !== 0x20) {
        return false; // a non-whitespace byte after the signed range means the whole file is not covered
      }
    }
  }
  return true;
}

async #parseSignatureDict(field, sigDict, fieldRef) {
  const byteRange = await sigDict.getAsync("ByteRange");
  if (!Array.isArray(byteRange) || byteRange.length !== 4 ||
      byteRange.some(n => !Number.isInteger(n) || n < 0)) {
    return null;
  }
  // ByteRange = [a, b, c, d]: the signed bytes are the two ranges [a..a+b] and [c..c+d];
  // the gap in between is the PKCS#7 hex string of /Contents itself
  const [a, b, c, d] = byteRange;
  const fileLength = this.stream.end || 0; // use stream.end, not length (offsets are relative to the raw bytes)
  // reject structurally impossible ByteRange values: it must start at the file header, the first range must be non-empty,
  // there must be room for /Contents between the two ranges, and nothing may go out of bounds — this prevents forged "full coverage"
  if (a !== 0 || b <= 0 || a + b > c || c + d > fileLength || fileLength === 0) {
    return null;
  }
 
  const contents = await sigDict.getAsync("Contents");
  if (typeof contents !== "string" || contents.length === 0) return null;
 
  const [filterName, subFilterName, t, name, reason, location, contactInfo, m] =
    await Promise.all([/* Filter/SubFilter/T/Name/Reason/Location/ContactInfo/M */]);
  let signatureType = null;
  if (subFilter === "adbe.pkcs7.detached") signatureType = 0;
  else if (subFilter === "adbe.pkcs7.sha1") signatureType = 1;
 
  const refKey = fieldRef instanceof Ref ? fieldRef.toString() : "inline";
  return {
    id: `${refKey}:${a}-${b}-${c}-${d}`,
    fieldName, signerName, reason, location, contactInfo, signingTime,
    filter, subFilter, signatureType, byteRange,
    pkcs7: stringToBytes(contents),
    revisionIndex: 0, parentId: null,
  };
}

get signatures() {
  const promise = this.pdfManager.ensureDoc("formInfo").then(async formInfo => {
    if (!formInfo.hasSignatures || !formInfo.hasFields) return null;
    const annotationGlobals = await this.annotationGlobals;
    if (!annotationGlobals) return null;
    const fields = annotationGlobals.acroForm.get("Fields");
 
    const collected = [];
    await this.#collectSignatureFields(fields, collected, new RefSet());
 
    await Promise.all(
      collected.map(async signature => {
        const signedEnd = signature.byteRange[2] + signature.byteRange[3];
        signature.modificationsAfterSignature = this.xref.countUpdatesAfter(signedEnd);
        signature.coversWholeDocument = await this.#coversWholeDocument(
          signedEnd, signature.modificationsAfterSignature
        );
      })
    );
 
    // sort by ByteRange coverage (descending): the widest coverage is the outermost revision;
    // each signature points to the first larger signature before it as its parentId (the revision chain)
    collected.sort((a, b) => b.byteRange[2] + b.byteRange[3] - (a.byteRange[2] + a.byteRange[3]));
    for (let i = 0, ii = collected.length; i < ii; i++) {
      const sig = collected[i];
      sig.revisionIndex = i;
      for (let j = i - 1; j >= 0; j--) {
        const candidate = collected[j];
        if (candidate.byteRange[2] + candidate.byteRange[3] > sig.byteRange[2] + sig.byteRange[3]) {
          sig.parentId = candidate.id;
          break;
        }
      }
    }
 
    // keep pkcs7 and byteRange on the worker side to slim down the metadata;
    // during verification the main thread fetches them on demand by id via getSignatureData
    const signatureData = new Map();
    const metadata = collected.map(sig => {
      const { pkcs7, ...rest } = sig;
      signatureData.set(sig.id, { byteRange: sig.byteRange, pkcs7 });
      return rest;
    });
    this.#signatureData = signatureData;
    return metadata.length ? metadata : null;
  });
  return shadow(this, "signatures", promise);
}

async getSignatureData(id) {
  await this.signatures; // ensure parsing is complete and #signatureData is populated
  const signature = this.#signatureData?.get(id);
  if (!signature) return null;
  const { byteRange, pkcs7 } = signature;
  const [a, b, c, d] = byteRange;
  const data = await Promise.all([
    this.#getByteRange(a, a + b),
    this.#getByteRange(c, c + d),
  ]);
  return { data, pkcs7 };
}