Method parseXRefChain

src/parser/document-parser.ts:332–421

* Parse the XRef chain, following /Prev links for incremental updates. * * Handles hybrid-reference files (PDF 1.7 §7.5.8.4): when a traditional * xref table's trailer carries a /XRefStm entry, it points to a * supplementary xref stream containing entries for compressed objects * (whi

(
    xrefParser: XRefParser,
    startOffset: number,
  )

   * walks every revision.
   */
  private parseXRefChain(
    xrefParser: XRefParser,
    startOffset: number,
  ): { xref: Map<number, XRefEntry>; trailer: PdfDict } {
    const combinedXRef = new Map<number, XRefEntry>();
    let firstTrailer: PdfDict | null = null;

    // Track visited offsets to prevent infinite loops
    const visited = new Set<number>();
    const queue: number[] = [startOffset];

    while (queue.length > 0) {
      const offset = queue.shift();

      if (offset === undefined) {
        break;
      }

      // Circular reference check
      if (visited.has(offset)) {
        this.warnings.push(`Circular xref reference at offset ${offset}`);
        continue;
      }

      visited.add(offset);

      try {
        const xrefData = xrefParser.parseAt(offset);

        // Hybrid xref: if this revision has a /XRefStm entry, it points to a
        // supplementary xref stream whose entries override the table for the
        // object numbers it covers. Apply the stream BEFORE the table so its
        // entries win the "first-seen" merge below.
        const xrefStmOffset = xrefData.trailer.getNumber("XRefStm")?.value;

        if (xrefStmOffset !== undefined && !visited.has(xrefStmOffset)) {
          visited.add(xrefStmOffset);

          try {
            const stmData = xrefParser.parseAt(xrefStmOffset);

            for (const [objNum, entry] of stmData.entries) {
              if (!combinedXRef.has(objNum)) {
                combinedXRef.set(objNum, entry);
              }
            }
          } catch (error) {
            // Hybrid stream is optional from the legacy table's perspective;
            // if it's malformed, fall back to the table alone with a warning.
            const message = error instanceof Error ? error.message : String(error);

            this.warnings.push(`Error parsing /XRefStm at ${xrefStmOffset}: ${message}`);
          }
        }

        // Merge table entries (first definition wins — covers anything the
        // stream above didn't override, and any object not in the stream).
        for (const [objNum, entry] of xrefData.entries) {