Method copyPagesFrom

src/api/pdf.ts:1734–1789

(
    source: PDF,
    indices: number[],
    options: CopyPagesOptions = {},
  )

   */
  // oxlint-disable-next-line typescript/require-await -- Public async API kept for backward compat; ObjectCopier is sync.
  async copyPagesFrom(
    source: PDF,
    indices: number[],
    options: CopyPagesOptions = {},
  ): Promise<PDFPage[]> {
    const copier = new ObjectCopier(source, this, {
      includeAnnotations: options.includeAnnotations ?? true,
      includeBeads: options.includeBeads ?? false,
      includeThumbnails: options.includeThumbnails ?? false,
      includeStructure: options.includeStructure ?? false,
    });

    const copiedPages: PDFPage[] = [];

    // Fail-fast: validate all indices first
    for (const index of indices) {
      if (index < 0 || index >= source.getPageCount()) {
        throw new RangeError(`Page index ${index} out of bounds (0-${source.getPageCount() - 1})`);
      }
    }

    // Copy each page
    const copiedRefs: PdfRef[] = [];

    for (const index of indices) {
      const srcPage = source.getPage(index);

      if (!srcPage) {
        throw new Error(`Source page ${index} not found`);
      }

      const copiedPageRef = copier.copyPage(srcPage.ref);
      copiedRefs.push(copiedPageRef);
    }

    // Insert copied pages at specified position (or append)
    let insertIndex = options.insertAt ?? this.getPageCount();

    for (const copiedRef of copiedRefs) {
      const copiedDict = this.getObject(copiedRef);

      if (!(copiedDict instanceof PdfDict)) {
        throw new Error("Copied page is not a dictionary");
      }

      this.ctx.pages.insertPage(insertIndex, copiedRef, copiedDict);

      // Create PDFPage wrapper and add to result
      const page = new PDFPage(copiedRef, copiedDict, insertIndex, this.ctx);
      copiedPages.push(page);

      insertIndex++;
    }

    return copiedPages;
  }

  /**