AlexandrAI AGENTS.md
agents-md

AlexandrAI Tools Add Page Numbers to PDF Agent Guide

Agent guide for formatting page labels and stamping positions onto every PDF page in the browser.

AGENTS.md

Guidance for coding agents working on AlexandrAI Tools Add Page Numbers to PDF in the alexandrai-tools project.

Project overview

This guide covers src/tools/add-page-numbers-pdf. formatPageLabel supports plain, of-n, and page label styles. Body.astro clamps the start number to at least one, embeds Helvetica, calculates six top and bottom positions with a fixed margin and text width, draws labels on every page, saves the PDF, and downloads page-numbered.pdf.

Primary source files

  • src/tools/add-page-numbers-pdf/index.ts defines meta, PageNumberStyle, and formatPageLabel.
  • src/tools/add-page-numbers-pdf/index.test.ts covers plain, of-n, page, and computed start-number behavior.
  • src/tools/add-page-numbers-pdf/Body.astro owns start number input, label style, position selection, text placement, pdf-lib font embedding, and download action.
  • src/tools/add-page-numbers-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

  • Keep label formatting pure and independent of pdf-lib.
  • Support exactly plain, of-n, and page styles unless tests and UI are updated.
  • Clamp the UI start number to one or greater.
  • Use start number plus page index as the visible label number.
  • Measure label width before horizontal center or right alignment.
  • Keep the default font size and margin centralized in Body.astro unless extracted with tests.
  • Update tests when adding label styles, positions, or custom font settings.

Testing

Test every label style, start numbers greater than one, total-page values in of-n labels, six positions, text-width alignment, one-page PDFs, multi-page PDFs, download-state behavior, and corrupt input errors.

PR checklist

  • npm test passes for add-page-numbers-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.