AGENTS.md

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

Project overview

This guide covers src/tools/watermark-pdf. clampOpacity constrains values to the zero through one range. Body.astro embeds HelveticaBold, measures the watermark text, draws it centered on each page, uses gray text with the clamped opacity, rotates it 45 degrees, saves the document, and downloads watermarked.pdf.

Primary source files

• src/tools/watermark-pdf/index.ts defines meta and clampOpacity.
• src/tools/watermark-pdf/index.test.ts covers pass-through values, below-zero clamping, above-one clamping, and exact zero and one edges.
• src/tools/watermark-pdf/Body.astro owns text, opacity, font size, pdf-lib font embedding, page drawing, save, and download actions.
• src/tools/watermark-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

• Clamp opacity to the zero through one range before drawing.
• Use the same watermark text on every page.
• Center the text using measured text width.
• Rotate the watermark at a fixed 45 degrees unless UI and tests add angle control.
• Keep color and font defaults explicit in Body.astro.
• Surface pdf-lib errors in the note area rather than swallowing them.
• If image watermarks are added, keep text and image paths separately tested.

Testing

Test opacity boundaries, negative and oversized values, empty watermark text handling, font size controls, one-page and multi-page PDFs, rotation and centering assumptions, save/download behavior, and invalid PDFs.

PR checklist

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