PSA/ee/docs/plans/2026-03-14-invoice-designer-paper-presets-and-margins/SCRATCHPAD.md

Scratchpad — Invoice Designer Paper Presets and Margins

• Plan slug: invoice-designer-paper-presets-and-margins
• Created: 2026-03-14

What This Is

Working notes for adding named paper presets and configurable page margins to the invoice template designer while keeping designer, preview, and PDF output aligned.

Decisions

• (2026-03-14) V1 scope is named paper presets only. No custom page dimensions.
• (2026-03-14) V1 margin scope is one uniform page margin value in millimeters. No per-side controls.
• (2026-03-14) Template-level print settings should be authoritative and persist in invoice template AST metadata.
• (2026-03-14) The plan must cover both current PDF generation services; changing only one path would preserve inconsistent output.
• (2026-03-14) This plan should introduce a shared PDF print-settings/options resolver rather than require full PDF service consolidation in the same change.
• (2026-03-14) Shared print-setting identifiers use Puppeteer-compatible preset names directly: Letter, A4, and Legal. This keeps AST metadata, UI labels, and PDF format values aligned without a second mapping layer.
• (2026-03-14) Default template print settings remain visually backward-compatible with the existing designer by using Letter plus the legacy 40px page padding converted to 10.58mm.
• (2026-03-14) Uniform page margins are clamped to a conservative 0-50mm range in the shared utility and schema. This is permissive for normal print layouts while preventing obviously broken geometry.
• (2026-03-14) Shared AST-based print-settings resolution now lives in packages/billing/src/lib/invoice-template-ast/printSettings.ts so preview shells and both PDF services can infer the same paper preset/margin from explicit metadata or legacy width/height/padding.
• (2026-03-14) PaperInvoice should prefer full templateAst input over raw printSettings so legacy templates without explicit metadata still preview at the correct sheet size and printable inset.
• (2026-03-14) Server-side document PDFs keep their pre-existing A4 + 10mm defaults; only invoice-template PDF flows were switched to the shared invoice print-settings resolver in this plan.

Discoveries / Constraints

• (2026-03-14) The design canvas is currently hard-coded to 816 x 1056 in packages/billing/src/components/invoice-designer/constants/layout.ts, which matches US Letter at 96dpi.
• (2026-03-14) The hidden page node already carries what functions like a page margin via layout.padding, with a current default of 40px.
• (2026-03-14) The preview shell is independently hard-coded in packages/billing/src/components/billing-dashboard/PaperInvoice.module.css with different dimensions/padding than the design canvas.
• (2026-03-14) There are two active invoice PDF generation implementations:
  • packages/billing/src/services/pdfGenerationService.ts
  • server/src/services/pdf-generation.service.ts
• (2026-03-14) The server-side PDF service hard-codes A4 plus explicit 10mm margins, while the package-level billing PDF service hard-codes A4 without an explicit margin block.
• (2026-03-14) The current renderer/preview path already respects exported inline width/height/padding styles, so print settings can reuse existing AST/style plumbing instead of inventing a separate render pipeline.
• (2026-03-14) The AST already has template metadata, but schema/types only currently cover templateName, description, locale, and currencyCode.
• (2026-03-14) Review follow-up: invoice margins must be treated as part of the template HTML/CSS box model, not duplicated as extra Puppeteer print-area margins, otherwise PDF output shrinks relative to preview.
• (2026-03-14) Review follow-up: unmatched legacy page dimensions should round-trip without silently persisting fallback Letter print metadata on save.
• (2026-03-14) Review follow-up: the billing PDF path must resolve print options from the same canonical AST used to render invoice HTML, not from a potentially stale list payload.

Completed Work

• (2026-03-14) Fixed invoice PDF parity so AST-backed invoice PDFs use zero Puppeteer margins and rely on template page padding for the printable inset, while generic document PDFs keep their existing default margin behavior.
• (2026-03-14) Hardened the billing PDF path to fetch canonical template AST when the list-selected template payload does not carry it, ensuring HTML rendering and PDF print options derive from the same template settings.
• (2026-03-14) Preserved unmatched legacy page dimensions during AST import/export instead of silently writing fallback Letter metadata for templates that do not map to a supported named preset.
• (2026-03-14) Fixed designer margin input behavior so blank drafts no longer commit 0mm, and no-op print setting commits no longer create extra history entries.
• (2026-03-14) Adjusted invoice preview scaling to reserve space for the paper shell chrome so the selected sheet frame is not clipped in the preview panel.
• (2026-03-14) exportWorkspace() strips runtime props.size, so first-class print settings must update authored style.width / style.height and page layout.padding in addition to runtime size / baseSize.
• (2026-03-14) Workspace AST import/export is the key persistence seam for print settings: import can infer or honor explicit metadata, while export can always write canonical metadata.printSettings back to the AST.
• (2026-03-14) packages/ui Input does not forward the id prop directly to the underlying <input>, so component tests for the margin control should target the spinbutton role rather than getElementById(...).
• (2026-03-14) Focused PDF service tests emit secret-file warnings in this worktree because .env.localtest falls back from secrets/db_password_server to env vars; the tests still pass and do not indicate a print-settings regression.

Commands / Runbooks

• (2026-03-14) Inspect current designer canvas sizing:
  • sed -n '1,80p' packages/billing/src/components/invoice-designer/constants/layout.ts
  • sed -n '1360,1465p' packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx
• (2026-03-14) Inspect current page/document defaults:
  • sed -n '621,687p' packages/billing/src/components/invoice-designer/state/designerStore.ts
  • sed -n '561,607p' packages/billing/src/components/invoice-designer/schema/componentSchema.ts
• (2026-03-14) Inspect current preview paper shell:
  • sed -n '1,120p' packages/billing/src/components/billing-dashboard/PaperInvoice.tsx
  • sed -n '1,120p' packages/billing/src/components/billing-dashboard/PaperInvoice.module.css
• (2026-03-14) Inspect current AST metadata/schema:
  • sed -n '1,80p' packages/types/src/lib/invoice-template-ast.ts
  • sed -n '422,448p' packages/billing/src/lib/invoice-template-ast/schema.ts
• (2026-03-14) Inspect current PDF generation paths:
  • sed -n '1,220p' packages/billing/src/services/pdfGenerationService.ts
  • sed -n '240,390p' server/src/services/pdf-generation.service.ts
• (2026-03-14) Validate the plan folder after edits:
  • python3 scripts/validate_plan.py ee/docs/plans/2026-03-14-invoice-designer-paper-presets-and-margins
• (2026-03-14) Focused validation for the shared print-settings/model slice:
  • cd server && npx vitest run --config vitest.config.ts ../packages/billing/src/lib/invoice-template-ast/printSettings.test.ts ../packages/billing/src/lib/invoice-template-ast/schema.test.ts ../packages/billing/src/components/invoice-designer/ast/workspaceAst.printSettings.test.ts ../packages/billing/src/components/invoice-designer/state/designerStore.printSettings.test.ts
  • cd server && npx vitest run --config vitest.config.ts ../packages/billing/src/components/invoice-designer/ast/workspaceAst.test.ts ../packages/billing/src/components/invoice-designer/state/designerStore.exportWorkspace.test.ts ../packages/billing/src/components/invoice-designer/state/designerStore.exportWorkspace.canonical.test.ts ../packages/billing/src/components/invoice-designer/state/designerStore.loadWorkspace.legacy.test.ts
• (2026-03-14) Focused validation for designer UI, preview shell, and PDF resolver wiring:
  • cd server && npx vitest run --config vitest.config.ts ../packages/billing/src/lib/invoice-template-ast/printSettings.test.ts ../packages/billing/src/components/invoice-designer/state/designerStore.printSettings.test.ts ../packages/billing/src/components/invoice-designer/DesignerShell.printSettings.integration.test.tsx ../packages/billing/src/components/invoice-designer/canvas/DesignCanvas.printSettings.integration.test.tsx ../packages/billing/src/components/billing-dashboard/PaperInvoice.printSettings.test.tsx ../packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx ../packages/billing/src/services/pdfGenerationService.printSettings.test.ts ../server/src/services/pdf-generation.service.printSettings.test.ts

Links / References

• Related prior plans:
  • ee/docs/plans/2026-02-09-invoice-template-designer-preview-workspace/
  • ee/docs/plans/2026-02-12-invoice-template-json-ast-renderer-cutover/
  • ee/docs/plans/2026-02-13-invoice-designer-native-css-layout-engine/
  • ee/docs/plans/2026-03-08-invoice-template-transforms-designer/
• Key implementation files:
  • packages/billing/src/components/invoice-designer/DesignerShell.tsx
  • packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.tsx
  • packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx
  • packages/billing/src/components/invoice-designer/state/designerStore.ts
  • packages/billing/src/components/invoice-designer/ast/workspaceAst.ts
  • packages/billing/src/components/billing-dashboard/PaperInvoice.tsx
  • packages/billing/src/components/billing-dashboard/PaperInvoice.module.css
  • packages/billing/src/services/pdfGenerationService.ts
  • server/src/services/pdf-generation.service.ts

Open Questions

• If a legacy template’s dimensions do not match any supported preset cleanly, should the editor display a fallback preset silently or surface a “legacy unresolved” state? Current plan assumes fallback behavior can stay silent if rendering remains stable.

Progress Log

• (2026-03-14) Completed F001 by adding shared invoice print preset utilities in packages/types/src/lib/invoice-print-settings.ts, including mm dimensions, px dimensions at 96dpi, preset lookup, margin clamping, legacy inference, and shared PDF option resolution primitives.
• (2026-03-14) Completed F002 by extending InvoiceTemplateAstMetadata and the billing AST schema with additive metadata.printSettings.paperPreset and metadata.printSettings.marginMm.
• (2026-03-14) Completed F003 by teaching workspace AST import/export to resolve print settings from legacy document/page width, height, and page padding when explicit metadata is absent.
• (2026-03-14) Completed F004 by round-tripping explicit print settings through workspace AST import/export so reopened designer workspaces keep canonical template-level print metadata.
• (2026-03-14) Completed F005 by adding applyPrintSettings in designerStore.ts to update document/page runtime size, baseSize, authored width/height, page padding, and document metadata together.
• (2026-03-14) Completed F006 by bootstrapping new designer workspaces and component schema defaults from the shared default print settings instead of fixed hard-coded geometry.
• (2026-03-14) Completed F007 / F008 / F009 by wiring a no-selection page-setup inspector in packages/billing/src/components/invoice-designer/DesignerShell.tsx and driving live paper-preset / margin updates into DesignCanvas geometry and ruler extents via applyPrintSettings.
• (2026-03-14) Completed F010 / F011 by teaching PaperInvoice and preview consumers (DesignerVisualWorkspace.tsx, InvoicePreviewPanel.tsx, InvoiceTemplateManager.tsx) to resolve sheet size and printable inset from the template AST, including legacy inference.
• (2026-03-14) Completed F012 by adding shared AST-based print-resolution / PDF-options helpers in packages/billing/src/lib/invoice-template-ast/printSettings.ts.
• (2026-03-14) Completed F013 / F014 / F015 by switching both invoice PDF services to shared AST-derived PDF print options and verifying the two services pass identical page.pdf(...) options for the same template settings.
• (2026-03-14) Completed F016 by covering legacy no-metadata fallback through existing load/save tests plus new preview-shell and billing PDF-service fallback coverage.
• (2026-03-14) Completed F017 by adding focused regression coverage for designer page-setup controls, canvas reshaping, preview shell sizing, authoritative preview export, shared PDF option resolution, both PDF services, and legacy fallback behavior.
• (2026-03-14) Completed T001 / T002 with shared preset registry coverage in packages/billing/src/lib/invoice-template-ast/printSettings.test.ts.
• (2026-03-14) Completed T003 / T004 / T005 with AST schema validation coverage for valid print metadata, unknown presets, and out-of-range margins in packages/billing/src/lib/invoice-template-ast/schema.test.ts.
• (2026-03-14) Completed T006 / T007 / T008 / T009 / T010 with workspace AST print-settings inference and round-trip coverage in packages/billing/src/components/invoice-designer/ast/workspaceAst.printSettings.test.ts.
• (2026-03-14) Completed T012 / T013 / T014 / T015 with designer-store print-settings coverage in packages/billing/src/components/invoice-designer/state/designerStore.printSettings.test.ts.
• (2026-03-14) Completed T016 / T017 / T018 / T019 / T020 in packages/billing/src/components/invoice-designer/DesignerShell.printSettings.integration.test.tsx.
• (2026-03-14) Completed T021 in packages/billing/src/components/invoice-designer/canvas/DesignCanvas.printSettings.integration.test.tsx.
• (2026-03-14) Completed T022 / T023 / T024 with explicit and legacy preview-shell coverage in packages/billing/src/components/billing-dashboard/PaperInvoice.printSettings.test.tsx.
• (2026-03-14) Completed T025 in packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx.
• (2026-03-14) Completed T026 / T027 in packages/billing/src/lib/invoice-template-ast/printSettings.test.ts.
• (2026-03-14) Completed T028 / T030 / T031 in server/src/services/pdf-generation.service.printSettings.test.ts.
• (2026-03-14) Completed T029 / T032 / T033 in packages/billing/src/services/pdfGenerationService.printSettings.test.ts.
• (2026-03-14) Completed T034 by running the focused regression suite spanning schema, workspace/store, designer shell, design canvas, preview shell, preview workspace, and both PDF services.