PDF.js 源码解读: catalog

// PDF 字节
//   → XRef.parse / getCatalogObj        （上一篇章：定位与取回）
//   → Catalog.constructor                （本篇：根字典进入文档模型）
//   → #catDict                           （所有 getter 的共同起点）
//   → 页面树 / 名称树 / 大纲 / 附件 / 表单 / OCG / 结构树
//   → PDFDocument / Page / PartialEvaluator / Worker 消息

  constructor(pdfManager, xref) {
    this.pdfManager = pdfManager;
    this.xref = xref;
 
    this.#catDict = xref.getCatalogObj();
    if (!(this.#catDict instanceof Dict)) {
      throw new FormatError("Catalog object is not a dictionary.");
    }
    // Given that `XRef.parse` will both fetch *and* validate the /Pages-entry,
    // the following call must always succeed here:
    this.toplevelPagesDict; // eslint-disable-line no-unused-expressions
  }

  cloneDict() {
    return this.#catDict.clone();
  }

class Catalog {
  #actualNumPages = null;
 
  #annotationAttachmentIdByRef = new RefMap();
 
  #annotationAttachmentRefById = new Map();
 
  #soundAttachmentIds = new Set();
 
  #catDict = null;
 
  builtInCMapCache = new Map();
 
  fontCache = new RefMap();
 
  globalColorSpaceCache = new GlobalColorSpaceCache();
 
  globalImageCache = new GlobalImageCache();
 
  nonBlendModesSet = new RefSet();
 
  pageDictCache = new RefMap();
 
  pageIndexCache = new RefMap();
 
  pageKidsCountCache = new RefMap();
 
  standardFontDataCache = new Map();
 
  systemFontCache = new Map();

function shadow(obj, prop, value, nonSerializable = false) {
  if (typeof PDFJSDev === 'undefined' || PDFJSDev.test('TESTING')) {
    assert(prop in obj, `shadow: Property "${prop && prop.toString()}" not found in object.`);
  }
  Object.defineProperty(obj, prop, {
    value,
    enumerable: !nonSerializable,
    configurable: true,
    writable: false,
  });
  return value;
}

  get version() {
    const version = this.#catDict.get("Version");
    if (version instanceof Name) {
      if (PDF_VERSION_REGEXP.test(version.name)) {
        return shadow(this, "version", version.name);
      }
      warn(`Invalid PDF catalog version: ${version.name}`);
    }
    return shadow(this, "version", null);
  }
 
  get lang() {
    const lang = this.#catDict.get("Lang");
    return shadow(
      this,
      "lang",
      lang && typeof lang === "string" ? stringToPDFString(lang) : null
    );
  }

  /**
   * @type {boolean} `true` for pure XFA documents,
   *   `false` for XFA Foreground documents.
   */
  get needsRendering() {
    const needsRendering = this.#catDict.get("NeedsRendering");
    return shadow(
      this,
      "needsRendering",
      typeof needsRendering === "boolean" ? needsRendering : false
    );
  }

  get collection() {
    let collection = null;
    try {
      const obj = this.#catDict.get("Collection");
      if (obj instanceof Dict && obj.size > 0) {
        collection = obj;
      }
    } catch (ex) {
      if (ex instanceof MissingDataException) {
        throw ex;
      }
      info("Cannot fetch Collection entry; assuming no collection is present.");
    }
    return shadow(this, "collection", collection);
  }

  get acroForm() {
    let acroForm = null;
    try {
      const obj = this.#catDict.get("AcroForm");
      if (obj instanceof Dict && obj.size > 0) {
        acroForm = obj;
      }
    } catch (ex) {
      if (ex instanceof MissingDataException) {
        throw ex;
      }
      info("Cannot fetch AcroForm entry; assuming no forms are present.");
    }
    return shadow(this, "acroForm", acroForm);
  }
 
  get acroFormRef() {
    const value = this.#catDict.getRaw("AcroForm");
    return shadow(this, "acroFormRef", value instanceof Ref ? value : null);
  }

  #readPermissions() {
    const encrypt = this.xref.trailer.get("Encrypt");
    if (!(encrypt instanceof Dict)) {
      return null;
    }
 
    let flags = encrypt.get("P");
    if (typeof flags !== "number") {
      return null;
    }
 
    // PDF integer objects are represented internally in signed 2's complement
    // form. Therefore, convert the signed decimal integer to a signed 2's
    // complement binary integer so we can use regular bitwise operations on it.
    flags += 2 ** 32;
 
    const permissions = new Set();
    for (const value of Object.values(PermissionFlag)) {
      if (flags & value) {
        permissions.add(value);
      }
    }
    return permissions;
  }

  #readMarkInfo() {
    const obj = this.#catDict.get("MarkInfo");
    if (!(obj instanceof Dict)) {
      return null;
    }
    const markInfo = new Map();
 
    for (const key of ["Marked", "UserProperties", "Suspects"]) {
      const val = obj.get(key);
      markInfo.set(key, typeof val === "boolean" ? val : false);
    }
    return markInfo;
  }

  get metadata() {
    const streamRef = this.#catDict.getRaw("Metadata");
    if (!(streamRef instanceof Ref)) {
      return shadow(this, "metadata", null);
    }
 
    let metadata = null;
    try {
      const stream = this.xref.fetch(
        streamRef,
        /* suppressEncryption = */ !this.xref.encrypt?.encryptMetadata
      );
 
      if (
        stream instanceof BaseStream &&
        isDict(stream.dict, "Metadata") &&
        isName(stream.dict.get("Subtype"), "XML")
      ) {
        // XXX: This should examine the charset the XML document defines,
        // however since there are currently no real means to decode arbitrary
        // charsets, let's just hope that the author of the PDF was reasonable
        // enough to stick with the XML default charset, which is UTF-8.
        const data = stringToUTF8String(stream.getString());
        if (data) {
          metadata = new MetadataParser(data).serializable;
        }
      }
    } catch (ex) {
      if (ex instanceof MissingDataException) {
        throw ex;
      }
      info(`Skipping invalid Metadata: "${ex}".`);
    }
    return shadow(this, "metadata", metadata);
  }

  get structTreeRoot() {
    let structTree = null;
    try {
      structTree = this.#readStructTreeRoot();
    } catch (ex) {
      if (ex instanceof MissingDataException) {
        throw ex;
      }
      warn("Unable read to structTreeRoot info.");
    }
    return shadow(this, "structTreeRoot", structTree);
  }
 
  #readStructTreeRoot() {
    const rawObj = this.#catDict.getRaw("StructTreeRoot"),
      obj = this.xref.fetchIfRef(rawObj);
    return obj instanceof Dict
      ? new StructTreeRoot(this.xref, obj, rawObj)
      : null;
  }

  get baseUrl() {
    const uri = this.#catDict.get("URI");
    if (uri instanceof Dict) {
      const base = uri.get("Base");
      if (typeof base === "string") {
        const absoluteUrl = createValidAbsoluteUrl(base, null, {
          tryConvertEncoding: true,
        });
        if (absoluteUrl) {
          return shadow(this, "baseUrl", absoluteUrl.href);
        }
      }
    }
    return shadow(this, "baseUrl", this.pdfManager.docBaseUrl);
  }

  get toplevelPagesDict() {
    const pagesObj = this.#catDict.get("Pages");
    if (!(pagesObj instanceof Dict)) {
      throw new FormatError("Invalid top-level pages dictionary.");
    }
    return shadow(this, "toplevelPagesDict", pagesObj);
  }

  get _pagesCount() {
    const obj = this.toplevelPagesDict.get("Count");
    if (!Number.isInteger(obj)) {
      throw new FormatError(
        "Page count in top-level pages dictionary is not an integer."
      );
    }
    return shadow(this, "_pagesCount", obj);
  }
 
  get numPages() {
    return this.#actualNumPages ?? this._pagesCount;
  }

  setActualNumPages(num = null) {
    this.#actualNumPages = num;
  }
 
  get hasActualNumPages() {
    return this.#actualNumPages !== null;
  }

  async getPageDict(pageIndex) {
    const nodesToVisit = [this.toplevelPagesDict];
    const visitedNodes = new RefSet();
 
    const pagesRef = this.#catDict.getRaw("Pages");
    if (pagesRef instanceof Ref) {
      visitedNodes.put(pagesRef);
    }
    const xref = this.xref,
      pageKidsCountCache = this.pageKidsCountCache,
      pageIndexCache = this.pageIndexCache,
      pageDictCache = this.pageDictCache;
    let currentPageIndex = 0;
 
    while (nodesToVisit.length) {
      const currentNode = nodesToVisit.pop();
 
      if (currentNode instanceof Ref) {
        const count = pageKidsCountCache.get(currentNode);
        // Skip nodes where the page can't be.
        if (count >= 0 && currentPageIndex + count <= pageIndex) {
          currentPageIndex += count;
          continue;
        }
        // Prevent circular references in the /Pages tree.
        if (visitedNodes.has(currentNode)) {
          throw new FormatError("Pages tree contains circular reference.");
        }
        visitedNodes.put(currentNode);
 
        const obj = await (pageDictCache.get(currentNode) ||
          xref.fetchAsync(currentNode));

        if (obj instanceof Dict) {
          let type = obj.getRaw("Type");
          if (type instanceof Ref) {
            type = await xref.fetchAsync(type);
          }
          if (isName(type, "Page") || !obj.has("Kids")) {
            // Cache the Page reference, since it can *greatly* improve
            // performance by reducing redundant lookups in long documents
            // where all nodes are found at *one* level of the tree.
            if (!pageKidsCountCache.has(currentNode)) {
              pageKidsCountCache.put(currentNode, 1);
            }
            // Help improve performance of the `getPageIndex` method.
            if (!pageIndexCache.has(currentNode)) {
              pageIndexCache.put(currentNode, currentPageIndex);
            }
 
            if (currentPageIndex === pageIndex) {
              return [obj, currentNode];
            }
            currentPageIndex++;
            continue;
          }
        }
        nodesToVisit.push(obj);
        continue;
      }

      // Must be a child page dictionary.
      if (!(currentNode instanceof Dict)) {
        throw new FormatError(
          "Page dictionary kid reference points to wrong type of object."
        );
      }
      const { objId } = currentNode;
 
      let count = currentNode.getRaw("Count");
      if (count instanceof Ref) {
        count = await xref.fetchAsync(count);
      }
      if (Number.isInteger(count) && count >= 0) {
        // Cache the Kids count, since it can reduce redundant lookups in
        // documents where all nodes are found at *one* level of the tree.
        if (objId && !pageKidsCountCache.has(objId)) {
          pageKidsCountCache.put(objId, count);
        }
 
        // Skip nodes where the page can't be.
        if (currentPageIndex + count <= pageIndex) {
          currentPageIndex += count;
          continue;
        }
      }
 
      let kids = currentNode.getRaw("Kids");
      if (kids instanceof Ref) {
        kids = await xref.fetchAsync(kids);
      }

      if (!Array.isArray(kids)) {
        // Prevent errors in corrupt PDF documents that violate the
        // specification by *inlining* Page dicts directly in the Kids
        // array, rather than using indirect objects (fixes issue9540.pdf).
        let type = currentNode.getRaw("Type");
        if (type instanceof Ref) {
          type = await xref.fetchAsync(type);
        }
        if (isName(type, "Page") || !currentNode.has("Kids")) {
          if (currentPageIndex === pageIndex) {
            return [currentNode, null];
          }
          currentPageIndex++;
          continue;
        }
 
        throw new FormatError("Page dictionary kids object is not an array.");
      }
 
      // Always check all `Kids` nodes, to avoid getting stuck in an empty
      // node further down in the tree (see issue5644.pdf, issue8088.pdf),
      // and to ensure that we actually find the correct `Page` dict.
      for (let last = kids.length - 1; last >= 0; last--) {
        const lastKid = kids[last];
        nodesToVisit.push(lastKid);
 
        // Launch all requests in parallel so we don't wait for each one in turn
        // when looking for a page near the end, if all the pages are top level.
        if (
          currentNode === this.toplevelPagesDict &&
          lastKid instanceof Ref &&
          !pageDictCache.has(lastKid)
        ) {
          pageDictCache.put(lastKid, xref.fetchAsync(lastKid));
        }
      }
    }
 
    throw new Error(`Page index ${pageIndex} not found.`);
  }

  async getAllPageDicts(recoveryMode = false) {
    const { ignoreErrors } = this.pdfManager.evaluatorOptions;
 
    const queue = [{ currentNode: this.toplevelPagesDict, posInKids: 0 }];
    const visitedNodes = new RefSet();
 
    const pagesRef = this.#catDict.getRaw("Pages");
    if (pagesRef instanceof Ref) {
      visitedNodes.put(pagesRef);
    }
    const map = new Map(),
      xref = this.xref,
      pageIndexCache = this.pageIndexCache;
    let pageIndex = 0;
 
    function addPageDict(pageDict, pageRef) {
      // Help improve performance of the `getPageIndex` method.
      if (pageRef && !pageIndexCache.has(pageRef)) {
        pageIndexCache.put(pageRef, pageIndex);
      }
 
      map.set(pageIndex++, [pageDict, pageRef]);
    }
    function addPageError(error) {
      if (error instanceof XRefEntryException && !recoveryMode) {
        throw error;
      }
      if (recoveryMode && ignoreErrors && pageIndex === 0) {
        // Ensure that the viewer will always load (fixes issue15590.pdf).
        warn(`getAllPageDicts - Skipping invalid first page: "${error}".`);
        error = Dict.empty;
      }
 
      map.set(pageIndex++, [error, null]);
    }

    while (queue.length > 0) {
      const queueItem = queue.at(-1);
      const { currentNode, posInKids } = queueItem;
 
      let kids = currentNode.getRaw("Kids");
      if (kids instanceof Ref) {
        try {
          kids = await xref.fetchAsync(kids);
        } catch (ex) {
          addPageError(ex);
          break;
        }
      }
      if (!Array.isArray(kids)) {
        // Prevent errors in corrupt PDF documents that violate the
        // specification by *inlining* Page dicts (fixes issue21436.pdf).
        let type = currentNode.getRaw("Type");
        if (type instanceof Ref) {
          try {
            type = await xref.fetchAsync(type);
          } catch (ex) {
            addPageError(ex);
            break;
          }
        }
        if (isName(type, "Page") || !currentNode.has("Kids")) {
          addPageDict(currentNode, null);
          break;
        }
 
        addPageError(
          new FormatError("Page dictionary kids object is not an array.")
        );
        break;
      }
 
      if (posInKids >= kids.length) {
        queue.pop();
        continue;
      }

      const kidObj = kids[posInKids];
      let obj;
      if (kidObj instanceof Ref) {
        // Prevent circular references in the /Pages tree.
        if (visitedNodes.has(kidObj)) {
          addPageError(
            new FormatError("Pages tree contains circular reference.")
          );
          break;
        }
        visitedNodes.put(kidObj);
 
        try {
          obj = await xref.fetchAsync(kidObj);
        } catch (ex) {
          addPageError(ex);
          break;
        }
      } else {
        // Prevent errors in corrupt PDF documents that violate the
        // specification by *inlining* Page dicts directly in the Kids
        // array, rather than using indirect objects (see issue9540.pdf).
        obj = kidObj;
      }
      if (!(obj instanceof Dict)) {
        addPageError(
          new FormatError(
            "Page dictionary kid reference points to wrong type of object."
          )
        );
        break;
      }
 
      let type = obj.getRaw("Type");
      if (type instanceof Ref) {
        try {
          type = await xref.fetchAsync(type);
        } catch (ex) {
          addPageError(ex);
          break;
        }
      }
      if (isName(type, "Page") || !obj.has("Kids")) {
        addPageDict(obj, kidObj instanceof Ref ? kidObj : null);
      } else {
        queue.push({ currentNode: obj, posInKids: 0 });
      }
      queueItem.posInKids++;
    }
    return map;
  }

  async getPageIndex(pageRef) {
    const cachedPageIndex = this.pageIndexCache.get(pageRef);
    if (cachedPageIndex !== undefined) {
      return cachedPageIndex;
    }
 
    // The page tree nodes have the count of all the leaves below them. To get
    // how many pages are before we just have to walk up the tree and keep
    // adding the count of siblings to the left of the node.
    const xref = this.xref;
    let total = 0,
      ref = pageRef;
    // Prevent circular references in the /Pages tree.
    const visited = new RefSet();
    visited.put(pageRef);
 
    while (true) {
      const node = await xref.fetchAsync(ref);
      if (
        isRefsEqual(ref, pageRef) &&
        !isDict(node, "Page") &&
        !(node instanceof Dict && !node.has("Type") && node.has("Contents"))
      ) {
        throw new FormatError(
          "The reference does not point to a /Page dictionary."
        );
      }
      if (!node) {
        break;
      }
      if (!(node instanceof Dict)) {
        throw new FormatError("Node must be a dictionary.");
      }
      const parentRef = node.getRaw("Parent");
      if (parentRef instanceof Ref) {
        if (visited.has(parentRef)) {
          throw new FormatError("Pages tree contains circular reference.");
        }
        visited.put(parentRef);
      }
 
      const parent = await node.getAsync("Parent");
      if (!parent) {
        break;
      }
      if (!(parent instanceof Dict)) {
        throw new FormatError("Parent must be a dictionary.");
      }

      const kids = await parent.getAsync("Kids");
      if (!kids) {
        break;
      }
      if (!Array.isArray(kids)) {
        throw new FormatError("Kids must be an array.");
      }
 
      const kidPromises = [];
      let found = false;
      for (const kid of kids) {
        if (!(kid instanceof Ref)) {
          throw new FormatError("Kid must be a reference.");
        }
        if (isRefsEqual(kid, ref)) {
          found = true;
          break;
        }
        kidPromises.push(
          xref.fetchAsync(kid).then(obj => {
            if (!(obj instanceof Dict)) {
              throw new FormatError("Kid node must be a dictionary.");
            }
            if (obj.has("Count")) {
              const count = obj.get("Count");
              if (Number.isInteger(count) && count >= 0) {
                total += count;
                return;
              }
              throw new FormatError("Count must be a (positive) integer.");
            }
            // Page leaf node.
            total++;
          })
        );
      }
      if (!found) {
        throw new FormatError("Kid reference not found in parent's kids.");
      }
      await Promise.all(kidPromises);
      ref = parentRef;
    }
 
    this.pageIndexCache.put(pageRef, total);
    return total;
  }

  get rawPageLabels() {
    const obj = this.#catDict.getRaw("PageLabels");
    if (!obj) {
      return null;
    }
 
    const numberTree = new NumberTree(obj, this.xref);
    return numberTree.getAll();
  }

  get pageLabels() {
    let obj = null;
    try {
      obj = this.#readPageLabels();
    } catch (ex) {
      if (ex instanceof MissingDataException) {
        throw ex;
      }
      warn("Unable to read page labels.");
    }
    return shadow(this, "pageLabels", obj);
  }
 
  #readPageLabels() {
    const nums = this.rawPageLabels;
    if (!nums) {
      return null;
    }
 
    const pageLabels = new Array(this.numPages);
    let style = null,
      prefix = "";
 
    let currentLabel = "",
      currentIndex = 1;
 
    for (let i = 0, ii = this.numPages; i < ii; i++) {
      const labelDict = nums.get(i);
 
      if (labelDict !== undefined) {
        if (!(labelDict instanceof Dict)) {
          throw new FormatError("PageLabel is not a dictionary.");
        }
 
        if (
          labelDict.has("Type") &&
          !isName(labelDict.get("Type"), "PageLabel")
        ) {
          throw new FormatError("Invalid type in PageLabel dictionary.");
        }
 
        if (labelDict.has("S")) {
          const s = labelDict.get("S");
          if (!(s instanceof Name)) {
            throw new FormatError("Invalid style in PageLabel dictionary.");
          }
          style = s.name;
        } else {
          style = null;
        }
 
        if (labelDict.has("P")) {
          const p = labelDict.get("P");
          if (typeof p !== "string") {
            throw new FormatError("Invalid prefix in PageLabel dictionary.");
          }
          prefix = stringToPDFString(p);
        } else {
          prefix = "";
        }
 
        if (labelDict.has("St")) {
          const st = labelDict.get("St");
          if (!(Number.isInteger(st) && st >= 1)) {
            throw new FormatError("Invalid start in PageLabel dictionary.");
          }
          currentIndex = st;
        } else {
          currentIndex = 1;
        }
      }

      switch (style) {
        case "D":
          currentLabel = currentIndex;
          break;
        case "R":
        case "r":
          currentLabel = toRomanNumerals(currentIndex, style === "r");
          break;
        case "A":
        case "a":
          const LIMIT = 26; // Use only the characters A-Z, or a-z.
          const letterIndex = currentIndex - 1;
          const character = String.fromCharCode(
            style.charCodeAt(0) + (letterIndex % LIMIT)
          );
          currentLabel = character.repeat(Math.floor(letterIndex / LIMIT) + 1);
          break;
        default:
          if (style) {
            throw new FormatError(
              `Invalid style "${style}" in PageLabel dictionary.`
            );
          }
          currentLabel = "";
      }
 
      pageLabels[i] = prefix + currentLabel;
      currentIndex++;
    }
    return pageLabels;
  }

  get destinations() {
    const dests = new Map();
 
    for (const obj of this.#readDests()) {
      if (obj instanceof NameTree) {
        for (const [key, value] of obj.getAll()) {
          const dest = fetchDest(value);
          if (dest) {
            dests.set(
              stringToPDFString(key, /* keepEscapeSequence = */ true),
              dest
            );
          }
        }
      } else if (obj instanceof Dict) {
        for (const [key, value] of obj) {
          const dest = fetchDest(value);
          if (dest) {
            // Always let the NameTree take precedence.
            dests.getOrInsert(
              stringToPDFString(key, /* keepEscapeSequence = */ true),
              dest
            );
          }
        }
      }
    }
    return shadow(this, "destinations", dests);
  }

  #readDests() {
    const obj = this.#catDict.get("Names");
    const rawDests = [];
    if (obj?.has("Dests")) {
      rawDests.push(new NameTree(obj.getRaw("Dests"), this.xref));
    }
    if (this.#catDict.has("Dests")) {
      // Simple destination dictionary.
      rawDests.push(this.#catDict.get("Dests"));
    }
    return rawDests;
  }

function fetchDest(dest) {
  if (dest instanceof Dict) {
    dest = dest.get('D');
  }
  return isValidExplicitDest(dest) ? dest : null;
}

  getDestination(id) {
    // Avoid extra lookup/parsing when all destinations are already available.
    if (Object.hasOwn(this, "destinations")) {
      return this.destinations.get(id) ?? null;
    }
 
    for (const obj of this.#readDests()) {
      if (obj instanceof NameTree || obj instanceof Dict) {
        const dest = fetchDest(obj.get(id));
        if (dest) {
          return dest;
        }
      }
    }
 
    // Always fallback to checking all destinations, in order to support:
    //  - PDF documents with out-of-order NameTrees (fixes issue 10272).
    //  - Destination keys that use PDFDocEncoding (fixes issue 19835).
    return this.destinations.get(id) ?? null;
  }

  get pageLayout() {
    const obj = this.#catDict.get("PageLayout");
    // Purposely use a non-standard default value, rather than 'SinglePage', to
    // allow differentiating between `undefined` and /SinglePage since that does
    // affect the Scroll mode (continuous/non-continuous) used in Adobe Reader.
    let pageLayout = "";
 
    if (obj instanceof Name) {
      switch (obj.name) {
        case "SinglePage":
        case "OneColumn":
        case "TwoColumnLeft":
        case "TwoColumnRight":
        case "TwoPageLeft":
        case "TwoPageRight":
          pageLayout = obj.name;
      }
    }
    return shadow(this, "pageLayout", pageLayout);
  }

  get pageMode() {
    const obj = this.#catDict.get("PageMode");
    let pageMode = "UseNone"; // Default value.
 
    if (obj instanceof Name) {
      switch (obj.name) {
        case "UseNone":
        case "UseOutlines":
        case "UseThumbs":
        case "FullScreen":
        case "UseOC":
        case "UseAttachments":
          pageMode = obj.name;
      }
    }
    return shadow(this, "pageMode", pageMode);
  }

  get viewerPreferences() {
    const obj = this.#catDict.get("ViewerPreferences");
    if (!(obj instanceof Dict)) {
      return shadow(this, "viewerPreferences", null);
    }
    let prefs = null;
 
    for (const [key, value] of obj) {
      let prefValue;
 
      switch (key) {
        case "HideToolbar":
        case "HideMenubar":
        case "HideWindowUI":
        case "FitWindow":
        case "CenterWindow":
        case "DisplayDocTitle":
        case "PickTrayByPDFSize":
          if (typeof value === "boolean") {
            prefValue = value;
          }
          break;

        case "NonFullScreenPageMode":
          if (value instanceof Name) {
            switch (value.name) {
              case "UseNone":
              case "UseOutlines":
              case "UseThumbs":
              case "UseOC":
                prefValue = value.name;
                break;
              default:
                prefValue = "UseNone";
            }
          }
          break;
        case "Direction":
          if (value instanceof Name) {
            switch (value.name) {
              case "L2R":
              case "R2L":
                prefValue = value.name;
                break;
              default:
                prefValue = "L2R";
            }
          }
          break;
        case "ViewArea":
        case "ViewClip":
        case "PrintArea":
        case "PrintClip":
          if (value instanceof Name) {
            switch (value.name) {
              case "MediaBox":
              case "CropBox":
              case "BleedBox":
              case "TrimBox":
              case "ArtBox":
                prefValue = value.name;
                break;
              default:
                prefValue = "CropBox";
            }
          }
          break;
        case "PrintScaling":
          if (value instanceof Name) {
            switch (value.name) {
              case "None":
              case "AppDefault":
                prefValue = value.name;
                break;
              default:
                prefValue = "AppDefault";
            }
          }
          break;
        case "Duplex":
          if (value instanceof Name) {
            switch (value.name) {
              case "Simplex":
              case "DuplexFlipShortEdge":
              case "DuplexFlipLongEdge":
                prefValue = value.name;
                break;
              default:
                prefValue = "None";
            }
          }
          break;

        case "PrintPageRange":
          // The number of elements must be even.
          if (
            Array.isArray(value) &&
            value.length % 2 === 0 &&
            value.every(
              (page, i, arr) =>
                Number.isInteger(page) &&
                page > 0 &&
                (i === 0 || page >= arr[i - 1]) &&
                page <= this.numPages
            )
          ) {
            prefValue = value;
          }
          break;
        case "NumCopies":
          if (Number.isInteger(value) && value > 0) {
            prefValue = value;
          }
          break;
        default:
          warn(`Ignoring non-standard key in ViewerPreferences: ${key}.`);
          continue;
      }
 
      if (prefValue === undefined) {
        warn(`Bad value, for key "${key}", in ViewerPreferences: ${value}.`);
        continue;
      }
      (prefs ??= new Map()).set(key, prefValue);
    }
    return shadow(this, "viewerPreferences", prefs);

  get openAction() {
    const obj = this.#catDict.get("OpenAction");
    const openAction = new Map();
 
    if (obj instanceof Dict) {
      // Convert the OpenAction dictionary into a format that works with
      // `parseDestDictionary`, to avoid having to re-implement those checks.
      const destDict = new Dict(this.xref);
      destDict.set("A", obj);
 
      const resultObj = { url: null, dest: null, action: null };
      Catalog.parseDestDictionary({ destDict, resultObj });
 
      if (Array.isArray(resultObj.dest)) {
        openAction.set("dest", resultObj.dest);
      } else if (resultObj.action) {
        openAction.set("action", resultObj.action);
      }
    } else if (isValidExplicitDest(obj)) {
      openAction.set("dest", obj);
    }
    return shadow(this, "openAction", openAction.size ? openAction : null);
  }

  #collectJavaScript() {
    const obj = this.#catDict.get("Names");
    let javaScript = null;
 
    function appendIfJavaScriptDict(name, jsDict) {
      if (!(jsDict instanceof Dict) || !isName(jsDict.get("S"), "JavaScript")) {
        return;
      }
      let js = jsDict.get("JS");
      if (js instanceof BaseStream) {
        js = js.getString();
      } else if (typeof js !== "string") {
        return;
      }
      js = stringToPDFString(js, /* keepEscapeSequence = */ true).replaceAll(
        "\x00",
        ""
      );
      // Skip empty entries, similar to the `_collectJS` function.
      if (js) {
        (javaScript ??= new Map()).set(name, js);
      }
    }
 
    if (obj instanceof Dict && obj.has("JavaScript")) {
      const nameTree = new NameTree(obj.getRaw("JavaScript"), this.xref);
      for (const [key, value] of nameTree.getAll()) {
        appendIfJavaScriptDict(
          stringToPDFString(key, /* keepEscapeSequence = */ true),
          value
        );
      }
    }
    // Append OpenAction "JavaScript" actions, if any, to the JavaScript map.
    const openAction = this.#catDict.get("OpenAction");
    if (openAction) {
      appendIfJavaScriptDict("OpenAction", openAction);
    }
 
    return javaScript;
  }

  get jsActions() {
    const javaScript = this.#collectJavaScript();
    let actions = collectActions(
      this.xref,
      this.#catDict,
      DocumentActionEventType
    );
 
    if (javaScript) {
      actions ??= new Map();
 
      for (const [key, val] of javaScript) {
        actions.getOrInsertComputed(key, makeArr).push(val);
      }
    }
    return shadow(this, "jsActions", actions);
  }

  get documentOutline() {
    let obj = null;
    try {
      obj = this.#readDocumentOutline();
    } catch (ex) {
      if (ex instanceof MissingDataException) {
        throw ex;
      }
      warn("Unable to read document outline.");
    }
    return shadow(this, "documentOutline", obj);
  }
 
  #readDocumentOutline(options = {}) {
    let obj = this.#catDict.get("Outlines");
    if (!(obj instanceof Dict)) {
      return null;
    }
    obj = obj.getRaw("First");
    if (!(obj instanceof Ref)) {
      return null;
    }
 
    const root = { items: [] };
    const queue = [{ obj, parent: root }];
    // To avoid recursion, keep track of the already processed items.
    const processed = new RefSet();
    processed.put(obj);
    const xref = this.xref,
      blackColor = new Uint8ClampedArray(3);
 
    while (queue.length > 0) {
      const i = queue.shift();
      const outlineDict = xref.fetchIfRef(i.obj);
      if (outlineDict === null) {
        continue;
      }
      if (!outlineDict.has("Title")) {
        warn("Invalid outline item encountered.");
      }
 
      const data = { url: null, dest: null, action: null };
      Catalog.parseDestDictionary({
        destDict: outlineDict,
        resultObj: data,
        docBaseUrl: this.baseUrl,
        docAttachments: this.attachments,
      });

const title = outlineDict.get('Title');
const flags = outlineDict.get('F') || 0;
const color = outlineDict.getArray('C');
const count = outlineDict.get('Count');
let rgbColor = blackColor;
 
// We only need to parse the color when it's valid, and non-default.
if (isNumberArray(color, 3) && (color[0] !== 0 || color[1] !== 0 || color[2] !== 0)) {
  rgbColor = ColorSpaceUtils.rgb.getRgb(color, 0);
}
 
const outlineItem = {
  action: data.action,
  attachmentId: data.attachmentId,
  attachment: data.attachment,
  dest: data.dest,
  url: data.url,
  unsafeUrl: data.unsafeUrl,
  newWindow: data.newWindow,
  setOCGState: data.setOCGState,
  title: typeof title === 'string' ? stringToPDFString(title) : '',
  color: rgbColor,
  count: Number.isInteger(count) ? count : undefined,
  bold: !!(flags & 2),
  italic: !!(flags & 1),
  items: [],
};
 
if (options.keepRawDict) {
  outlineItem.rawDict = outlineDict;
}

      i.parent.items.push(outlineItem);
      obj = outlineDict.getRaw("First");
      if (obj instanceof Ref && !processed.has(obj)) {
        queue.push({ obj, parent: outlineItem });
        processed.put(obj);
      }
      obj = outlineDict.getRaw("Next");
      if (obj instanceof Ref && !processed.has(obj)) {
        queue.push({ obj, parent: i.parent });
        processed.put(obj);
      }
    }
    return root.items.length > 0 ? root.items : null;
  }

  get documentOutlineForEditor() {
    let obj = null;
    try {
      obj = this.#readDocumentOutline({ keepRawDict: true });
    } catch (ex) {
      if (ex instanceof MissingDataException) {
        throw ex;
      }
      warn("Unable to read document outline.");
    }
    return shadow(this, "documentOutlineForEditor", obj);
  }

  get attachments() {
    const obj = this.#catDict.get("Names");
    /** @type {Map<string, CatalogAttachment> | null} */
    let attachments = null;
 
    if (obj instanceof Dict && obj.has("EmbeddedFiles")) {
      const nameTree = new NameTree(obj.getRaw("EmbeddedFiles"), this.xref);
      for (const [key, value] of nameTree.getAll()) {
        (attachments ??= new Map()).set(
          stringToPDFString(key, /* keepEscapeSequence = */ true),
          new FileSpec(value).serializable
        );
      }
    }
    return shadow(this, "attachments", attachments);
  }

  attachmentContent(id) {
    const namedContent = this.#attachmentContentByName(id);
    if (namedContent !== undefined) {
      return namedContent;
    }
 
    // Annotation-local attachments register the reference of their embedded
    // content in the catalog, so it's re-fetched from the xref on demand
    // instead of being cached (which would then need to survive `cleanup`).
    // The reference points either at the file-spec dictionary or, for an inline
    // file-spec, straight at the embedded-file stream.
    const ref = this.#annotationAttachmentRefById.get(id);
    if (ref) {
      const target = this.xref.fetch(ref);
      if (target instanceof BaseStream) {
        const content = FileSpec.readStreamContent(target);
        if (this.#soundAttachmentIds.has(id)) {
          return soundStreamToWav(target, content) ?? content;
        }
        return content;
      }
      return target instanceof Dict ? FileSpec.readContent(target) : null;
    }
    return null;
  }

  getAttachmentIdForAnnotation(ref, isSound = false) {
    let id = this.#annotationAttachmentIdByRef.get(ref);
    if (!id) {
      const baseId = `attachmentRef:${ref.toString()}`;
      id = baseId;
 
      let i = 1;
      while (
        this.#annotationAttachmentRefById.has(id) ||
        this.attachments?.has(id)
      ) {
        id = `${baseId}-${i++}`;
      }
 
      this.#annotationAttachmentIdByRef.put(ref, id);
      this.#annotationAttachmentRefById.set(id, ref);
    }
    if (isSound) {
      this.#soundAttachmentIds.add(id);
    }
    return id;
  }

  get rawEmbeddedFiles() {
    const obj = this.#catDict.get("Names");
    if (!(obj instanceof Dict) || !obj.has("EmbeddedFiles")) {
      return null;
    }
    const nameTree = new NameTree(obj.getRaw("EmbeddedFiles"), this.xref);
    return nameTree.getAll(/* isRaw = */ true);
  }
 
  get xfaImages() {
    const obj = this.#catDict.get("Names");
    let xfaImages = null;
 
    if (obj instanceof Dict && obj.has("XFAImages")) {
      const nameTree = new NameTree(obj.getRaw("XFAImages"), this.xref);
      for (const [key, value] of nameTree.getAll()) {
        if (value instanceof BaseStream) {
          xfaImages ??= new Map();
          xfaImages.set(
            stringToPDFString(key, /* keepEscapeSequence = */ true),
            value.getBytes()
          );
        }
      }
    }
    return shadow(this, "xfaImages", xfaImages);
  }

  get optionalContentConfig() {
    let config = null;
    try {
      const properties = this.#catDict.get("OCProperties");
      if (!properties) {
        return shadow(this, "optionalContentConfig", null);
      }
      const defaultConfig = properties.get("D");
      if (!defaultConfig) {
        return shadow(this, "optionalContentConfig", null);
      }
      const groupsData = properties.get("OCGs");
      if (!Array.isArray(groupsData)) {
        return shadow(this, "optionalContentConfig", null);
      }
      const groupRefCache = new RefMap();
      // Ensure all the optional content groups are valid.
      for (const groupRef of groupsData) {
        if (!(groupRef instanceof Ref) || groupRefCache.has(groupRef)) {
          continue;
        }
        groupRefCache.put(groupRef, this.#readOptionalContentGroup(groupRef));
      }
      config = this.#readOptionalContentConfig(defaultConfig, groupRefCache);
    } catch (ex) {
      if (ex instanceof MissingDataException) {
        throw ex;
      }
      warn(`Unable to read optional content config: ${ex}`);
    }
    return shadow(this, "optionalContentConfig", config);
  }

  #readOptionalContentGroup(groupRef) {
    const group = this.xref.fetch(groupRef);
    const obj = {
      id: groupRef.toString(),
      name: null,
      intent: null,
      usage: {
        print: null,
        view: null,
      },
      rbGroups: [],
    };
 
    const name = group.get("Name");
    if (typeof name === "string") {
      obj.name = stringToPDFString(name);
    }
 
    let intent = group.getArray("Intent");
    if (!Array.isArray(intent)) {
      intent = [intent];
    }
    if (intent.every(i => i instanceof Name)) {
      obj.intent = intent.map(i => i.name);
    }
 
    const usage = group.get("Usage");
    if (!(usage instanceof Dict)) {
      return obj;
    }
    const usageObj = obj.usage;
 
    const print = usage.get("Print");
    if (print instanceof Dict) {
      const printState = print.get("PrintState");
      if (printState instanceof Name) {
        switch (printState.name) {
          case "ON":
          case "OFF":
            usageObj.print = { printState: printState.name };
        }
      }
    }

const xref = this.xref,
  parsedOrderRefs = new RefSet(),
  MAX_NESTED_LEVELS = 10;
 
parseRBGroups(config.get('RBGroups'));
 
return {
  name: typeof config.get('Name') === 'string' ? stringToPDFString(config.get('Name')) : null,
  creator:
    typeof config.get('Creator') === 'string' ? stringToPDFString(config.get('Creator')) : null,
  baseState: config.get('BaseState') instanceof Name ? config.get('BaseState').name : null,
  on: parseOnOff(config.get('ON')),
  off: parseOnOff(config.get('OFF')),
  order: parseOrder(config.get('Order')),
  groups: [...groupRefCache],
};

function parseOrder(refs, nestedLevels = 0) {
  if (!Array.isArray(refs)) {
    return null;
  }
  const order = [];
 
  for (const value of refs) {
    if (value instanceof Ref && groupRefCache.has(value)) {
      parsedOrderRefs.put(value); // Handle "hidden" groups, see below.
 
      order.push(value.toString());
      continue;
    }
    // Handle nested /Order arrays (see e.g. issue 9462 and bug 1240641).
    const nestedOrder = parseNestedOrder(value, nestedLevels);
    if (nestedOrder) {
      order.push(nestedOrder);
    }
  }
 
  if (nestedLevels > 0) {
    return order;
  }
  const hiddenGroups = [];
  for (const [groupRef] of groupRefCache.items()) {
    if (parsedOrderRefs.has(groupRef)) {
      continue;
    }
    hiddenGroups.push(groupRef.toString());
  }
  if (hiddenGroups.length) {
    order.push({ name: null, order: hiddenGroups });
  }
 
  return order;
}

function parseNestedOrder(ref, nestedLevels) {
  if (++nestedLevels > MAX_NESTED_LEVELS) {
    warn('parseNestedOrder - reached MAX_NESTED_LEVELS.');
    return null;
  }
  const value = xref.fetchIfRef(ref);
  if (!Array.isArray(value)) {
    return null;
  }
  const nestedName = xref.fetchIfRef(value[0]);
  if (typeof nestedName !== 'string') {
    return null;
  }
  const nestedOrder = parseOrder(value.slice(1), nestedLevels);
  if (!nestedOrder?.length) {
    return null;
  }
  return { name: stringToPDFString(nestedName), order: nestedOrder };
}