feca-mailshots-plugin/requirements/dompdf_investigation.md

dompdf Investigation Requirement

Document Context

This investigation requirement is governed by requirements/environment.md and requirements/top-level.md. No fallback behavior is permitted without explicit instruction.

Purpose

Determine whether dompdf is suitable for generating production-quality mailshot PDFs from the sample templates:

• samples/renewal_draft.html
• samples/invoicing.html

Inputs

1. Template sources:
   • samples/renewal_draft.html
   • samples/invoicing.html
2. Representative field values for all template tokens.
3. FECA logo asset content equivalent to pdf_asset('FenEdgeLogoOrange').

Investigation Route

1. Render-ready normalization

   • Produce render-ready HTML for each sample by replacing template tokens/macros with fixed test data.
   • Ensure pdf_asset('FenEdgeLogoOrange') resolves to concrete HTML/image content.

2. dompdf spike execution

   • Provide an executable spike script in working/codex-spikes/ (agent artefacts, not user operational scripts) that:
     • loads each normalized template,
     • renders via dompdf,
     • writes PDFs to working/,
     • fails with non-zero exit code on render errors.

3. Structured suitability checks

   • renewal_draft.html checks:
     • watermark (position: fixed, transform, transparency)
     • table borders, spacing, and mm-based layout
     • logo placement and title/header integrity
   • invoicing.html checks:
     • line-break behavior from macro expansion
     • currency/symbol rendering (£, ✉, ☎)
     • emoji contact symbols such as 📞/📧 must be normalized to PDF-safe symbols (☎/✉) and pinned to DejaVu Sans before Dompdf rendering.
     • spacing, wrapping, and pagination

4. Baseline comparison

   • Generate browser print-to-PDF baselines for both templates.
   • Compare dompdf output to browser baseline using a fixed checklist.

5. Decision criteria

   • Suitable: all critical checks pass with no blocking defects.
   • Suitable with constraints: non-blocking defects exist; template constraints/workarounds are documented.
   • Not suitable: one or more blocking defects remain.

6. Contingency (only if explicitly instructed)

   • Evaluate one alternative renderer against the same inputs/checklist for comparison.

Deliverables

1. Rendered HTML artefacts for both sample templates.
2. dompdf-generated PDFs for both sample templates.
3. Completed suitability checklist with pass/fail evidence.
4. Recommendation outcome: suitable / suitable with constraints / not suitable.
5. Documented required template constraints (if any).

Execution Notes

• Investigation outputs should be isolated under working/.
• Any generated test artefacts must be cleaned up by the test process when they are no longer needed.