PSA/ee/docs/plans/2026-02-12-invoice-template-json-ast-renderer-cutover/PRD.md

PRD — Invoice Template Execution Abstraction Cutover (JSON AST + Shared React Renderer)

• Slug: invoice-template-json-ast-renderer-cutover
• Date: 2026-02-12
• Status: Draft
• Supersedes: ee/docs/plans/2026-02-09-invoice-template-designer-preview-workspace/

Summary

Replace the current invoice template execution pipeline (GUI IR -> AssemblyScript generation -> Wasm compile -> Wasm/QuickJS execution) with a declarative JSON AST and one shared React/TypeScript renderer.

The template is data, not executable code. The Designer should output a versioned JSON AST. Rendering should run through one shared renderer in both:

1. interactive preview in the app, and
2. backend PDF generation via headless browser.

The system must still support future customization of invoice line-item calculations and groupings by expressing those behaviors declaratively (and optionally via whitelisted strategy hooks), not by embedding arbitrary per-template code.

Problem

Current architecture requires maintaining multiple custom layers for one invoice output path:

• GUI state compiler IR
• AssemblyScript source generation
• AssemblyScript compilation orchestration
• runtime module loading/execution (Wasm/QuickJS)
• host function glue and compile artifact caching

This increases complexity, testing surface, runtime failure modes, and maintenance burden. It also creates a conceptual mismatch: an invoice layout definition is fundamentally declarative data.

Insight

An invoice template is a declarative UI/data-shaping structure, not a program.

Goals

• Make Designer the source of truth for a versioned JSON AST.
• Implement one generic invoice renderer in React/TS that consumes AST + invoice data.
• Use identical render logic for preview and PDF generation.
• Preserve extensibility for future custom line-item calculations/groupings through declarative transform specs and optional whitelisted strategy hooks.
• Remove compiler/executor layers and their operational burden.
• Eliminate generated Wasm artifact management and cache concerns.

Non-goals

• Supporting arbitrary user-authored executable code in templates.
• Full migration tooling for tenant custom templates (none exist yet).
• Replatforming invoice data sources or billing domain logic.
• Reworking unrelated billing UI flows outside template render/edit/preview/PDF paths.

Users and Primary Flows

Primary personas:

• Billing admins designing invoice templates.
• Implementers maintaining template rendering reliability.

Primary flows:

1. Design -> Preview

   • User edits template in visual designer.
   • Designer emits AST snapshot.
   • Shared data-shaping evaluator + renderer produces preview output.

2. Save -> Reopen

   • User saves template AST.
   • Reopening editor hydrates from persisted AST.

3. Invoice PDF generation

   • Invoice generation selects template AST.
   • Same renderer path generates HTML/CSS in headless browser.
   • PDF output matches preview behavior.

4. Future customization (calculation/grouping)

   • Template AST declares group/filter/sort/aggregate/computed-field rules.
   • Evaluator applies them consistently in preview and PDF.
   • Optional strategyId can route to vetted server-side functions for advanced behavior.

UX / UI Notes

• Keep top-level editor tabs (Visual, Code) unless product decides otherwise.
• In Visual -> Preview, retain source selection UX (Sample / Existing) and status surface.
• Preview status terminology should reflect new phases (shape, render, verify) instead of compile.
• If Code tab remains for GUI templates, show generated/read-only AST JSON (or remove tab in a follow-up).

Requirements

Functional Requirements

• Define a versioned InvoiceTemplateAst schema with runtime validation.
• AST must represent layout tree, style tokens, bindings, and repeatable item regions.
• AST must support declarative data-shaping blocks for:
  • filtering,
  • sorting,
  • grouping,
  • aggregations,
  • computed fields,
  • totals composition.
• Add optional strategyId hooks that resolve only to whitelisted server-side implementations.
• Implement a shared evaluator that transforms invoice view-model data according to AST shape rules.
• Evaluator output must be deterministic for equivalent inputs.
• Implement one shared React renderer that consumes evaluated AST context and renders invoice HTML/CSS.
• DesignerVisualWorkspace export path must persist AST directly (no IR->AssemblyScript generation).
• Template save/get actions must use AST as canonical template payload.
• Preview action must run evaluator + shared renderer (no Wasm compile/execute).
• Preview must continue supporting sample and existing-invoice sources.
• Backend PDF generation must use the same renderer output path in headless browser.
• Remove compile-cache behavior tied to generated Wasm artifacts.
• Remove runtime dependency on custom compiler/executor modules listed in this PRD.
• Preserve clear, structured errors for schema, evaluator, strategy, and rendering failures.

Non-functional Requirements

• Preview and PDF rendering should remain functionally consistent for the same template + invoice data.
• Rendering path should be fast enough for iterative design/preview usage.
• Renderer/evaluator modules must be unit-testable without external compiler toolchains.
• Architecture should reduce moving parts versus current compiler + runtime stack.

Data / API / Integrations

• Update invoice template type contracts to include canonical AST payload.
• Keep invoice data retrieval and mapping (fetchInvoicesPaginated, getInvoiceForRendering, adapter mapping) intact.
• Introduce shared modules for:
  • AST schema,
  • evaluator,
  • React invoice renderer,
  • server-side render-to-html wrapper for PDF.
• Update save/load/query paths in billing actions/models to use AST as primary source.
• Standard templates should be represented in AST form for this cutover path.

Security / Permissions

• No template execution of arbitrary code.
• strategyId resolution must be allowlisted, tenant-safe, and auditable.
• Existing tenant isolation requirements for invoice/template access remain unchanged.
• Preview and PDF rendering must remain read-only relative to invoice mutation.

Deleted / Eliminated Layers

Delete these modules and remove call paths:

• packages/billing/src/components/invoice-designer/compiler/guiIr.ts
• packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.ts
• packages/billing/src/components/invoice-designer/compiler/diagnostics.ts
• packages/billing/src/lib/invoice-template-compiler/assemblyScriptCompile.ts
• packages/billing/src/lib/invoice-renderer/wasm-executor.ts
• packages/billing/src/lib/invoice-renderer/quickjs-executor.ts
• packages/billing/src/lib/invoice-renderer/host-functions.ts

And eliminate generated Wasm module caching/management (including preview compile cache concerns).

Rollout / Migration

• No tenant custom templates currently exist, so no backfill migration is required for custom template payloads.
• Implement as a forward cutover for template authoring/rendering pipeline.
• Keep legacy columns/artifacts only as temporary compatibility scaffolding if needed during implementation; prioritize runtime cutover first.

Risks

• Functional parity drift between old and new rendering semantics.
• Ambiguity in declarative transform expressiveness for advanced grouping/calc scenarios.
• Under-specified strategy hook boundaries could reintroduce ad hoc execution behavior.

Open Questions

1. Should Code tab for GUI templates become read-only AST JSON immediately, or be hidden in this cutover?
2. Which initial strategy hooks are required in MVP (none, custom-group-key, custom-aggregate, etc.)?
3. Do we keep layout verification in MVP, and if yes, does it compare AST-intended constraints to rendered DOM geometry?

Acceptance Criteria (Definition of Done)

• Designer persists a validated JSON AST as canonical template representation.
• Preview pipeline uses shared evaluator + React renderer (no compiler/Wasm executor path).
• PDF generation uses same renderer path in headless browser and matches preview semantics.
• Declarative grouping/calculation rules are supported in AST evaluator.
• Optional whitelisted strategyId hooks are supported without arbitrary code execution.
• Legacy compiler/executor modules listed above are deleted and no longer referenced.
• No generated Wasm compile cache/module lifecycle remains in invoice template pipeline.
• Automated tests cover AST validation, evaluator behavior, preview/PDF parity, and error handling.