AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Merge PDF Agent Guide

Agent guide for combining browser-selected PDFs with pdf-lib page copying and immutable file ordering.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Merge PDF in the alexandrai-tools project.

Project overview

This guide covers src/tools/merge-pdf. The pure module exposes validatePdfCount and orderFiles, while Body.astro dynamically imports pdf-lib, creates a new PDFDocument, loads each selected file as an ArrayBuffer, copies every source page in UI order, and downloads merged.pdf without sending files to a server.

Primary source files

  • src/tools/merge-pdf/index.ts defines meta, validatePdfCount, and orderFiles.
  • src/tools/merge-pdf/index.test.ts covers minimum file count and forward, backward, and no-op reordering.
  • src/tools/merge-pdf/Body.astro owns file input, merge action, download action, clear action, and pdf-lib copyPages flow.
  • src/tools/merge-pdf/i18n.ts owns localized labels.
  • src/lib/tools.ts registers the tool metadata.

Setup commands

npm install npm test npm run typecheck npm run build npm run dev

Change rules

  • Require at least two PDF files before a merge is valid.
  • Keep orderFiles immutable; even a same-index move returns a copy.
  • Preserve the visible file order when copying pages into the merged document.
  • Use PDFDocument.create for the output and PDFDocument.load for each input.
  • Copy all pages from each input with getPageIndices unless a future feature adds selection.
  • Keep pdf-lib loading in the browser component rather than the metadata module.
  • Never add hidden upload, remote processing, or telemetry to browser-local PDF handling.

Testing

Test validatePdfCount for zero, one, two, and many files; orderFiles forward, backward, and no-op behavior; Body.astro merge order; empty input disabling; corrupt PDF errors; Blob download naming; and clear-state reset.

PR checklist

  • npm test passes for merge-pdf.
  • PDF and binary file processing remain browser-local.
  • Pure helper behavior, UI state, and i18n labels stay aligned.
  • Invalid input, empty output, and download behavior are covered by tests.