AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Split PDF Agent Guide

Agent guide for range parsing and extracting selected PDF pages into a new browser-local document.

AGENTS.md

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

Project overview

This guide covers src/tools/split-pdf. The helper parses comma-separated one-based page specs into a sorted deduped list, clamps range ends to total pages, rejects reversed ranges, rejects zero pages, drops single pages beyond the total, and lets Body.astro default a blank UI range to all pages before copying selected pages into extracted.pdf.

Primary source files

  • src/tools/split-pdf/index.ts defines meta, PageRangeError, and parsePageRanges.
  • src/tools/split-pdf/index.test.ts covers ranges, single pages, dedupe, clamping, blank specs, reversed ranges, zero pages, garbage input, and multiple ranges.
  • src/tools/split-pdf/Body.astro loads the PDF, calculates total pages, maps one-based pages to zero-based indices, copies pages with pdf-lib, and downloads extracted.pdf.
  • src/tools/split-pdf/i18n.ts owns localized page range copy.
  • 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

  • Treat user-facing page numbers as one-based.
  • Convert parsed pages to zero-based indices only at the pdf-lib boundary.
  • Return an empty array for blank specs in the pure helper.
  • In the UI, default a blank range to the full document range.
  • Clamp range ends to total page count.
  • Reject reversed ranges, zero page numbers, and unparseable tokens with PageRangeError.
  • Throw a clear error when the final selected page list is empty.

Testing

Test range parsing, duplicate pages, ranges beyond total, single pages beyond total, blank UI defaulting, empty final selections, one-based to zero-based conversion, copied page order, corrupt PDFs, and download-state reset.

PR checklist

  • npm test passes for split-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.