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

PRD — Invoice Designer Paper Presets and Margins

• Slug: invoice-designer-paper-presets-and-margins
• Date: 2026-03-14
• Status: Draft

Summary

Add first-class print settings to the invoice template designer so template authors can choose a named paper preset and a configurable uniform page margin, and have the designer canvas, preview surface, and generated PDFs all honor the same settings.

V1 scope is intentionally constrained:

• named paper presets only
• one uniform page margin value in millimeters
• no custom paper sizes
• no per-side margin controls

The implementation should introduce a shared print-settings model and a shared PDF print-options resolver so both current PDF generation paths behave consistently without requiring a full service consolidation in the same change.

Problem

The invoice template designer currently has no intentional page-setup model.

Instead, page size and printable area are split across unrelated hard-coded implementations:

• the design canvas uses a fixed 816 x 1056 surface, which is US Letter at 96dpi
• the page node defaults include 40px padding that acts like a content margin
• the preview shell uses a separate fixed “paper” chrome with different dimensions and padding
• one PDF generation path hard-codes A4 with explicit 10mm margins
• another PDF generation path hard-codes A4 with no explicit margin block

This creates three user-facing failures:

1. template authors cannot intentionally choose a target sheet size
2. PDF output margin behavior is inconsistent and not user-configurable
3. designer, preview, and exported PDF can disagree about what the page actually is

Goals

• Let template authors choose a named paper preset from the designer UI.
• Let template authors set a uniform page margin value for the template.
• Make the designer artboard reshape immediately when the selected paper preset changes.
• Make the preview shell reflect the same page dimensions and printable inset as the selected settings.
• Make both current PDF generation paths honor the same resolved paper preset and margin settings.
• Preserve compatibility for existing templates without requiring a database migration.
• Keep one authoritative template-level source of truth for print settings.

Non-goals

• Custom paper sizes in v1.
• Separate top/right/bottom/left margin controls in v1.
• Full multi-page pagination or page-break authoring improvements.
• Full consolidation of the package-level and server-level PDF services in this plan.
• New observability, metrics, rollout flags, or operational tooling beyond normal validation and regression coverage.

Users and Primary Flows

Primary users

• Billing admins authoring invoice templates.
• Implementers validating that visual designer output matches exported PDFs.

Primary flows

1. Choose a paper preset

   • User opens the invoice template designer.
   • User selects Letter, A4, or Legal.
   • The artboard, rulers, and visible page chrome reshape immediately.

2. Adjust page margin

   • User edits the page margin in millimeters.
   • The printable area inset updates in the designer and preview.
   • Saving the template persists the setting.

3. Preview with production parity

   • User opens preview for a sample or existing invoice.
   • Preview reflects the same sheet size and margin as the design surface.

4. Generate a PDF

   • User generates or downloads a PDF through any existing invoice PDF flow.
   • The generated PDF uses the selected paper preset and margin instead of hard-coded defaults.

5. Open an older template

   • User opens an existing template that predates explicit print settings.
   • The system infers or falls back to sensible resolved settings without breaking load, preview, save, or PDF generation.

UX / UI Notes

• Print settings must be reachable even though the page node is not normally selectable on the canvas.
• V1 should expose page setup in a dedicated, obvious control surface in the designer, such as:
  • a document/page settings section in the inspector when no specific child node is selected, or
  • a page setup control area in the designer shell/toolbar
• Paper preset control:
  • dropdown/select with named presets
  • initial preset list for v1: Letter, A4, Legal
• Margin control:
  • numeric input in millimeters
  • one value applied uniformly to all sides
  • live updates while editing, with validation/clamping for obviously invalid values
• The preview paper shell should stop using independent fixed dimensions and instead derive its chrome from resolved print settings.
• The code tab remains generated/read-only; no raw print-settings JSON editor is needed in v1.

Requirements

Functional Requirements

• FR-001 Add a shared invoice print preset registry for at least Letter, A4, and Legal.
• FR-002 Represent template print settings as first-class invoice template AST metadata, including paper preset identity and uniform margin.
• FR-003 Keep print settings additive and backward-compatible so templates without explicit print metadata still load and render.
• FR-004 Infer legacy/resolved print settings from existing page/document width, height, and padding when explicit metadata is absent and known preset dimensions are detected.
• FR-005 Preserve print settings through designer workspace import/export, save, reopen, and preview flows.
• FR-006 Add a designer store action that applies print settings by synchronizing runtime geometry and authored style/layout state for the hidden document/page nodes.
• FR-007 Initialize new designer workspaces with default print settings and matching document/page geometry.
• FR-008 Add reachable UI controls for selecting a named paper preset in the visual designer.
• FR-009 Add reachable UI controls for editing a uniform margin value in millimeters.
• FR-010 Validate paper preset and margin input so invalid settings are rejected or corrected before they produce broken layout/PDF output.
• FR-011 Update the design canvas, artboard bounds, and rulers to derive dimensions from resolved print settings instead of fixed constants alone.
• FR-012 Update the preview paper shell to derive visible sheet dimensions and printable inset from resolved print settings instead of hard-coded CSS dimensions and padding.
• FR-013 Ensure authoritative preview export/render uses the resolved page size and margin so preview content matches the configured print settings.
• FR-014 Introduce a shared resolver that converts template print settings into Puppeteer PDF options.
• FR-015 Wire the server-side invoice PDF generation service to the shared print-settings resolver instead of hard-coded A4/margin defaults.
• FR-016 Wire the package-level billing PDF generation service to the same shared print-settings resolver instead of hard-coded A4 defaults.
• FR-017 Ensure both current PDF generation paths produce the same paper preset and margin behavior for the same template settings.
• FR-018 Preserve older templates with no explicit print metadata through preview and PDF generation without schema migration or manual repair.

Non-functional Requirements

• NFR-001 Mapping from named paper preset -> designer size -> preview shell -> Puppeteer options must be deterministic and centralized.
• NFR-002 Existing invoice templates must remain loadable and editable without a breaking schema migration.
• NFR-003 The designer should reshape quickly enough that switching paper presets feels immediate in normal editing flows.
• NFR-004 Print setting changes must not create parity drift between preview and generated PDFs.
• NFR-005 V1 should minimize scope by reusing the existing template AST, workspace import/export, preview pipeline, and PDF generation entry points.

Data / API / Integrations

• Extend invoice template AST metadata to include a print-settings shape, for example:
  • paperPreset
  • marginMm
• Keep template-level metadata as the semantic source of truth.
• Continue exporting resolved width/height/padding into the AST layout/styles needed by the current renderer paths so existing HTML/CSS rendering behavior stays compatible.
• Add a shared preset/dimension utility that can:
  • map preset -> physical size in mm
  • map preset -> editor size in px at 96dpi
  • convert uniform margin mm -> preview/canvas padding representation
  • convert resolved settings -> Puppeteer format and margin
• Update the workspace import/export layer so explicit metadata wins, while legacy width/height/padding can still be interpreted when metadata is absent.
• No new external API endpoints are required for v1.

Security / Permissions

• No new permission model is introduced.
• Existing invoice template edit permissions continue to govern who can change print settings.
• Existing invoice/PDF read or generate permissions continue to govern who can preview or export invoices.

Observability

• No new observability scope is included in v1 beyond normal editor validation states and existing error surfacing.

Rollout / Migration

• No database migration is required.
• Existing templates without explicit print metadata should load through inference or fallback behavior.
• New templates should initialize with explicit print settings so they no longer depend on legacy hard-coded geometry alone.
• This plan does not require immediate consolidation of the two PDF services, but it does require both services to share one print-settings resolution path.

Open Questions

• None blocking for the v1 plan. The selected scope is:
  • named presets only
  • uniform margin only
  • no custom sizes

Acceptance Criteria (Definition of Done)

• A template author can choose a named paper preset in the invoice designer.
• A template author can set a uniform page margin in millimeters.
• Changing the selected preset reshapes the designer canvas to the matching page size.
• Preview reflects the same page size and printable inset as the selected settings.
• Both current PDF generation paths honor the same selected preset and margin instead of hard-coded defaults.
• Existing templates without explicit print settings still load, preview, save, and export successfully.
• Saving and reopening a template preserves the configured paper preset and margin.
• Automated coverage exists for schema/import-export behavior, canvas reshape behavior, preview shell behavior, and both PDF paths.