Method copyRef

src/document/object-copier.ts:171–226

* Copy a reference, creating the referenced object in dest if needed. * * Handles circular references by registering a placeholder before * recursively copying the referenced object's contents.

(ref: PdfRef)

   * recursively copying the referenced object's contents.
   */
  private copyRef(ref: PdfRef): PdfRef {
    const key = `${ref.objectNumber}:${ref.generation}`;

    // Already copied (or being copied)?
    const existing = this.refMap.get(key);

    if (existing) {
      return existing;
    }

    // Resolve the source object
    const srcObj = this.source.getObject(ref);

    if (srcObj === null) {
      // Referenced object doesn't exist - this shouldn't happen in valid PDFs
      // but we handle it gracefully by returning a ref to a null object
      const nullRef = this.dest.register(new PdfDict());
      this.refMap.set(key, nullRef);

      return nullRef;
    }

    // For dicts and streams, we can handle circular references by:
    // 1. Create a clone/placeholder in dest and register it first
    // 2. Then copy contents (which may reference back to us)
    // This way, any back-references will find our ref in the map

    if (srcObj instanceof PdfStream) {
      return this.copyStreamRef(key, srcObj);
    }

    if (srcObj instanceof PdfDict) {
      return this.copyDictRef(key, srcObj);
    }

    if (srcObj instanceof PdfArray) {
      // Arrays can contain circular refs too
      const items: PdfObject[] = [];

      for (const item of srcObj) {
        items.push(this.copyObject(item));
      }

      const copiedArr = new PdfArray(items);
      const destRef = this.dest.register(copiedArr);
      this.refMap.set(key, destRef);

      return destRef;
    }

    // Primitives - just register them
    const destRef = this.dest.register(srcObj);
    this.refMap.set(key, destRef);

    return destRef;
  }

  /**