# 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 (`£`, `✉`, `📞`)
     - 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.