Pdf

pdf — professional PDFs

Note: PDF is a final format with no reflow engine. If the recipient must edit, deliver the editable source (.docx/.xlsx) and the PDF.

Path 1 — quick content PDF (make_document tool)

Copy code
make_document(format="pdf", content={ title, pages:[{ heading, paragraphs, image:{path} }] })

Flow layout, US-Letter, single column, word-wrapped. Good for reports/summaries/letters. For forms, precise layout, or custom fonts → Path 3.

Path 2 — edit an existing PDF (edit_document tool)

• fill_form {fields} — fill existing AcroForm fields by name (text/checkbox/dropdown).
• merge {pdfs} / add_pages {pdfs} · split {pages} · remove_pages {pages}.
• stamp {text} · watermark {text} (45° translucent).

Form decision: first detect whether the PDF has real fillable fields. If it does → fill them (clean, type-validated). If it's a flat/scanned form (no fields) → you must draw text at coordinates instead (Path 3, annotations) — never assume fields exist.

Path 3 — full power: script @cantoo/pdf-lib

Brigade bundles @cantoo/pdf-lib (a maintained pdf-lib fork — note the scoped name) plus @pdf-lib/fontkit (custom-font embedding) and unpdf (text extraction). write a gen.cjs, run brigade exec-node gen.cjs:

jsCopy code
// gen.cjs — illustrative
const fs = require("node:fs");
const { PDFDocument, StandardFonts, rgb } = require("@cantoo/pdf-lib");

(async () => {
  const pdf = await PDFDocument.create();

  // embed a custom font (real bold / CJK / Unicode) — requires fontkit
  // const fontkit = require("@pdf-lib/fontkit"); pdf.registerFontkit(fontkit);
  // const font = await pdf.embedFont(fs.readFileSync("Brand-Bold.ttf"));
  const font = await pdf.embedFont(StandardFonts.HelveticaBold);

  const page = pdf.addPage([612, 792]);                 // US Letter; origin is BOTTOM-LEFT, y-up
  page.drawText("Invoice", { x: 54, y: 720, size: 22, font, color: rgb(0.1, 0.1, 0.1) });
  page.drawRectangle({ x: 54, y: 700, width: 504, height: 1, color: rgb(0.8, 0.8, 0.8) }); // vector rule

  // CREATE fillable form fields
  const form = pdf.getForm();
  const name = form.createTextField("client.name");
  name.addToPage(page, { x: 120, y: 640, width: 300, height: 18 });
  const agree = form.createCheckBox("agree");
  agree.addToPage(page, { x: 54, y: 600, width: 14, height: 14 });
  // form.flatten();                                     // bake fields into static content if no further filling

  fs.writeFileSync(process.argv[2] || "out.pdf", await pdf.save());
  console.log("wrote");
})();

@cantoo/pdf-lib covers: draw text/lines/rects/ellipses/SVG paths/images; embed custom TTF/OTF fonts (subset, full Unicode); create AND fill AcroForm text/checkbox/radio/dropdown/option-list fields; flatten; copy/merge/split/rotate pages; metadata; password encryption (the reason this fork is bundled). Extract text/structure with unpdf.

Coordinate gotcha: pdf-lib origin is bottom-left, y-up. If you author field positions from a top-left image/spec, convert: y_pdf = pageHeight - y_top - height. One coordinate convention per script.

Path 4 — pixel-perfect / branded PDF from HTML+CSS (optional)

pdf-lib has no HTML/CSS layout engine — for a designed, brand-styled document, render HTML→PDF. Use whatever is present (detect first):

bashCopy code
command -v soffice >/dev/null 2>&1 && soffice --headless --convert-to pdf brand.html      # LibreOffice route

A headless browser (Puppeteer/Playwright page.pdf()) is the higher-fidelity alternative if installed. Prefer Path 1/3 unless the brand design genuinely requires CSS.

Conventions

• Use real AcroForm fields when filling a fillable PDF; only fall back to drawn-text annotations for flat/scanned forms.
• Embed a font for anything beyond basic Latin — standard PDF fonts lack bold-as-a-face and all CJK/emoji (missing glyphs render as boxes).
• Keep ≥0.5" margins; align to a grid; don't rely on text reflowing (there's no engine — you place it).

Verify (required)

Confirm the output exists and opens. For filled/created forms, re-open and read back the field values (or render to an image with soffice/a viewer and look at placement) before declaring done — never fill or place blind.