PSA/ee/docs/plans/2026-02-09-invoice-template-designer-preview-workspace/SCRATCHPAD.md

Scratchpad — Invoice Template Designer Preview Workspace

• Plan slug: invoice-template-designer-preview-workspace
• Created: 2026-02-09
• Scope status: authoritative-preview-only

Scope Snapshot

Authoritative preview for invoice template designer:

1. GUI design -> compiler IR -> AssemblyScript source
2. AssemblyScript -> Wasm (same compile path/options as real templates)
3. Wasm -> HTML/CSS via real invoice rendering runtime
4. Layout verification compares rendered output vs expected design constraints

Decisions

• (2026-02-09) Preview output must come from the real rendering pipeline; canvas placeholder preview is non-authoritative.
• (2026-02-09) GUI designer requires a compiler path that emits AssemblyScript template logic.
• (2026-02-09) Layout verification is required in preview scope (not optional).
• (2026-02-09) Preview interactions remain read-only and side-effect free; invoice/template writes only happen on explicit save.

Key Constraints

• Reuse existing runtime rendering pipeline for parity (renderTemplateOnServer path and runtime dependencies).
• Reuse existing invoice data actions for preview inputs where possible (fetchInvoicesPaginated, getInvoiceForRendering).
• Avoid dual source-of-truth drift between GUI model and code model; source-of-truth behavior must be explicit.
• Verification must support tolerance rules so minor rendering variance is distinguishable from true layout regressions.

Current Focus Areas

• Define compiler architecture: IR schema, deterministic codegen contract, diagnostics mapping.
• Wire preview orchestration: data load -> compile -> render -> verify lifecycle.
• Define layout verification model: expected constraints, rendered geometry extraction, comparator rules.
• Decide save gating behavior when verification reports issues.

Runbooks

• Validate plan folder:
  • python3 /Users/roberisaacs/.codex/skills/alga-plan/scripts/validate_plan.py ee/docs/plans/2026-02-09-invoice-template-designer-preview-workspace
• Validate JSON files:
  • jq empty ee/docs/plans/2026-02-09-invoice-template-designer-preview-workspace/features.json
  • jq empty ee/docs/plans/2026-02-09-invoice-template-designer-preview-workspace/tests.json

References

• ee/docs/plans/2026-02-09-invoice-template-designer-preview-workspace/PRD.md
• packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.tsx
• packages/billing/src/components/invoice-designer/DesignerShell.tsx
• packages/billing/src/actions/invoiceTemplates.ts
• packages/billing/src/actions/invoiceQueries.ts
• packages/billing/src/lib/invoice-renderer/wasm-executor.ts
• docs/billing/invoice_templates.md

Open Questions

• Should code-tab editing be read-only for GUI-authored templates to prevent drift?
• What tolerance thresholds define pass/fail for layout verification?
• Should verification failure block save, or warn-and-allow in MVP?
• Should verification run automatically on every preview render or support manual trigger for heavier templates?

Execution Log

• (2026-02-09) F001 completed by verification: nested Design/Preview tabs already existed inside Visual mode and are wired through DesignerVisualWorkspace.
  • Evidence files: packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.tsx, packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.tsx
  • Validation command: npx vitest run packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.previewWorkspace.test.tsx
  • Result: 21/21 tests passed.
• (2026-02-09) F002 completed by verification: top-level Visual/Code tabs keep behavior and preserve nested visual sub-tab state while switching.
  • Evidence file: packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.tsx
  • Validation command: npx vitest run packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.previewWorkspace.test.tsx
  • Result: 6/6 tests passed.
• (2026-02-09) F003 implemented: preview session state now models compile/render/verify lifecycle phases with explicit idle|running|success|error status and per-phase error fields.
  • Rationale: later preview orchestration can dispatch phase transitions without overloading invoice list/detail loading flags.
  • Files: packages/billing/src/components/invoice-designer/preview/previewSessionState.ts, packages/billing/src/components/invoice-designer/preview/previewSessionState.test.ts
  • Validation command: npx vitest run packages/billing/src/components/invoice-designer/preview/previewSessionState.test.ts packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx
  • Result: 19/19 tests passed.
• (2026-02-09) F004 completed by verification: preview supports Sample/Existing source toggling through explicit control state in DesignerVisualWorkspace.
  • Evidence file: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.tsx
  • Validation command: npx vitest run packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx
  • Result: 15/15 tests passed.
• (2026-02-09) F005 completed by verification: curated sample scenario catalog is present and wired as default preview source.
  • Evidence file: packages/billing/src/components/invoice-designer/preview/sampleScenarios.ts
  • Validation command: npx vitest run packages/billing/src/components/invoice-designer/preview/sampleScenarios.test.ts
  • Result: 2/2 tests passed.
• (2026-02-09) F006 completed by verification: Existing source selector queries invoice pages, supports search term filtering, and exposes pagination controls in preview workspace.
  • Evidence file: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.tsx
  • Validation command: npx vitest run packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx
  • Result: 15/15 tests passed.
• (2026-02-09) F007 completed by verification: selected existing invoice details are fetched and normalized with mapDbInvoiceToWasmViewModel before use in preview bindings.
  • Evidence files: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.tsx, packages/billing/src/lib/adapters/invoiceAdapters.ts
  • Validation command: npx vitest run packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx packages/billing/src/lib/adapters/invoiceAdapters.test.ts
  • Result: 17/17 tests passed.
  • Gotcha: running multiple vitest processes in parallel with coverage can race on server/coverage/.tmp; run related test files in a single vitest run invocation instead.
• (2026-02-09) F008 implemented: added compiler IR extraction module that converts workspace nodes into deterministic flat/tree IR with normalized metadata and canonicalized constraints.
  • Rationale: GUI compiler stages need stable node ordering and predictable metadata shape to produce deterministic codegen output.
  • Files: packages/billing/src/components/invoice-designer/compiler/guiIr.ts, packages/billing/src/components/invoice-designer/compiler/guiIr.test.ts
  • Validation command: npx vitest run packages/billing/src/components/invoice-designer/compiler/guiIr.test.ts
  • Result: 2/2 tests passed.
• (2026-02-09) F009 implemented: added deterministic AssemblyScript generator for GUI IR with stable node factory symbol emission and deterministic source hash output.
  • Files: packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.ts, packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.test.ts
  • Validation command: npx vitest run packages/billing/src/components/invoice-designer/compiler/guiIr.test.ts packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.test.ts
  • Result: 4/4 tests passed.
• (2026-02-09) F010 implemented: generator now emits binding helper functions and node-level binding expressions for field/table/totals metadata.
  • Field bindings: resolveInvoiceBinding(...) emitted from bindingKey + format.
  • Table bindings: per-column row emission uses resolveItemBinding(...).
  • Totals bindings: totals rows/containers emit subtotal/tax/total expressions from invoice model.
  • Validation command: npx vitest run packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.test.ts packages/billing/src/components/invoice-designer/compiler/guiIr.test.ts
  • Result: 5/5 tests passed.
• (2026-02-09) F011 implemented: generator emits layout/style declarations from GUI node geometry + layout metadata through deterministic applyGeneratedLayoutStyle(...) calls.
  • Includes width/height markers, position-derived spacing, and layout align/justify hints.
  • Validation command: npx vitest run packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.test.ts packages/billing/src/components/invoice-designer/compiler/guiIr.test.ts
  • Result: 6/6 tests passed.
• (2026-02-09) F012 implemented: added per-node source map segments in codegen plus diagnostics parser/linker that maps AssemblyScript compile errors back to GUI node IDs.
  • Files: packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.ts, packages/billing/src/components/invoice-designer/compiler/diagnostics.ts
  • Validation command: npx vitest run packages/billing/src/components/invoice-designer/compiler/diagnostics.test.ts packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.test.ts packages/billing/src/components/invoice-designer/compiler/guiIr.test.ts
  • Result: 8/8 tests passed.
• (2026-02-09) F013 implemented: introduced transient preview compile action and shared compile-command helper to keep preview and production on the same asc options path.
  • Shared helper: packages/billing/src/lib/invoice-template-compiler/assemblyScriptCompile.ts
  • Preview compile action: packages/billing/src/actions/invoiceTemplatePreview.ts
  • Production compile wiring updated in packages/billing/src/actions/invoiceTemplates.ts to use the shared command builder.
  • Validation command: npx vitest run packages/billing/src/lib/invoice-template-compiler/assemblyScriptCompile.test.ts packages/billing/src/actions/invoiceTemplateCompileParity.test.ts
  • Result: 3/3 tests passed.
• (2026-02-09) F014 implemented: preview compile now uses an in-memory LRU cache keyed by source hash to skip recompilation for unchanged generated sources.
  • Cache controls exposed for tests via __previewCompileCacheTestUtils.
  • Validation command: npx vitest run packages/billing/src/actions/invoiceTemplatePreview.cache.test.ts packages/billing/src/actions/invoiceTemplateCompileParity.test.ts packages/billing/src/lib/invoice-template-compiler/assemblyScriptCompile.test.ts
  • Result: 5/5 tests passed.
• (2026-02-09) F015 implemented: preview pipeline now surfaces structured compiler diagnostics (severity/message/node mapping) and compile error details in Preview UI status panel.
  • Diagnostics come from AssemblyScript stderr parsing + GUI-node source map linking.
  • UI automation IDs: invoice-designer-preview-compile-error, invoice-designer-preview-compile-diagnostics-list, invoice-designer-preview-compile-diagnostic-item.
• (2026-02-09) F016 completed by implementation review: preview compile/render action path (invoiceTemplatePreview.ts) is transient-only and performs no invoice/template DB writes.
  • The pipeline uses temp files + wasm execution/rendering only, and does not import tenant DB helpers (createTenantKnex, withTransaction) in preview action module.
• (2026-02-09) F017 implemented: preview now runs authoritative runtime path in runAuthoritativeInvoiceTemplatePreview:
  1. GUI workspace -> IR -> AssemblyScript source
  2. AssemblyScript -> Wasm compile (compilePreviewAssemblyScript)
  3. Wasm execution (executeWasmTemplate) + HTML/CSS rendering (renderLayout)
  • UI now renders real output in invoice-designer-preview-render-iframe.
• (2026-02-09) F018 implemented: removed DesignCanvas preview rendering from Preview tab; authoritative output now comes from server-rendered HTML/CSS iframe only.
• (2026-02-09) F019 implemented: authoritative preview run effect is driven by debounced workspace nodes (useDebouncedValue(nodes, 140)), preventing unbounded compile/render churn during rapid edits.
• (2026-02-09) F020 implemented: Preview status panel includes manual Re-run control (invoice-designer-preview-rerun) that retriggers compile/render/verify and bypasses compile cache on demand.
• (2026-02-09) F021 implemented: Preview UI now has explicit loading/empty/error states across the pipeline:
  • Data load states for existing invoice list/detail (existing behavior retained)
  • Pipeline states for compile/render/verify (invoice-designer-preview-*-status)
  • Render empty/loading/error panels and verification error banner
• (2026-02-09) F022 implemented: preview rendering surface is now isolated iframe output with no designer interaction hooks (drag, resize, select) wired in Preview mode.
• (2026-02-09) F023 implemented: expected verification constraints are derived from GUI compiler IR via extractExpectedLayoutConstraintsFromIr (x/y/width/height constraint set per node).
• (2026-02-09) F024 implemented: rendered geometry extraction (collectRenderedGeometryFromLayout) collects normalized x/y/width/height metrics from authoritative render output element styles by node id.
• (2026-02-09) F025 implemented: comparator (compareLayoutConstraints) evaluates expected-vs-actual geometry with configurable tolerance and emits structured mismatch deltas.
• (2026-02-09) F026 implemented: Preview tab now renders verification summary block and mismatch list UI (invoice-designer-preview-verification-summary, ...-mismatch-list, ...-mismatch-item).
• (2026-02-09) F027 implemented: verification result now surfaces explicit pass/issues badge state on each preview run.
• (2026-02-09) F028 implemented: GUI-template save now compiles workspace snapshot to IR/AssemblyScript and persists generated source (with embedded designer state marker), ensuring save path aligns with preview source generation.
  • Validation command: npx vitest run packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.previewWorkspace.test.tsx packages/billing/src/components/invoice-designer/compiler/guiIr.test.ts packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.test.ts
  • Result: 12/12 tests passed.
• (2026-02-09) F029 implemented: codified source-of-truth rule for GUI templates as “Visual is authoritative, Code is generated read-only view.”
  • Code tab now shows generated source and blocks direct edits when GUI designer flag is enabled.
• (2026-02-09) F030 completed by regression validation: existing workspace hydration + localStorage fallback behavior remains intact after authoritative preview pipeline integration (InvoiceTemplateEditor.previewWorkspace.test.tsx passing).
• (2026-02-09) F031 implemented: added stable automation IDs for preview rerun control, compile/render/verify statuses, render output container/iframe, compile diagnostics list, and verification summary/mismatch report rows.
• (2026-02-09) F032 completed: unit coverage added for IR extraction and deterministic AssemblyScript generation (guiIr.test.ts, assemblyScriptGenerator.test.ts).
• (2026-02-09) F033 implemented: added integration parity test that compiles GUI-generated AssemblyScript, executes the compiled Wasm directly, then asserts runAuthoritativeInvoiceTemplatePreview returns identical HTML/CSS for the same template + invoice payload.
  • Files: packages/billing/src/actions/invoiceTemplatePreview.integration.test.ts, packages/billing/src/actions/invoiceTemplatePreview.ts, packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.ts
  • Validation commands:
    • pnpm vitest packages/billing/src/actions/invoiceTemplatePreview.integration.test.ts
    • pnpm vitest packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.test.ts packages/billing/src/actions/invoiceTemplatePreview.integration.test.ts
    • pnpm vitest packages/billing/src/actions/invoiceTemplatePreview.cache.test.ts packages/billing/src/actions/invoiceTemplateCompileParity.test.ts packages/billing/src/lib/invoice-template-compiler/assemblyScriptCompile.test.ts
  • Result: parity integration test passing; preview compile regression fixed by creating temp_compile/preview/assembly symlink so generated ../assembly/types imports resolve in preview temp paths.
  • Gotcha: generated binding helper referenced viewModel.dueDate which does not exist in runtime AssemblyScript InvoiceViewModel; adjusted generator fallback for invoice.dueDate to return empty string to preserve compileability.
• (2026-02-09) F034 implemented: added fixture-based verification tests that assert pass/fail comparator behavior against known aligned/drifted design fixtures.
  • Files: packages/billing/src/lib/invoice-template-compiler/__fixtures__/layoutVerificationFixtures.ts, packages/billing/src/lib/invoice-template-compiler/layoutVerification.fixtures.test.ts
  • Validation command: pnpm vitest packages/billing/src/lib/invoice-template-compiler/layoutVerification.test.ts packages/billing/src/lib/invoice-template-compiler/layoutVerification.fixtures.test.ts
  • Result: 4/4 tests passed; failing fixture asserts deterministic mismatch ids (totals:x, totals:y, totals:width, totals:height) and mismatch payload shape.
• (2026-02-09) F035 implemented: added editor-level end-to-end flow tests that cover design edit -> authoritative preview -> verification -> save and existing-invoice preview refresh in one integrated harness.
  • File: packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.authoritativeFlow.test.tsx
  • Validation commands:
    • pnpm vitest packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.authoritativeFlow.test.tsx
    • pnpm vitest packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.previewWorkspace.test.tsx packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.authoritativeFlow.test.tsx packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx
  • Result: 25/25 tests passed across the combined editor + visual workspace integration suite.
• (2026-02-09) F036 implemented: updated billing invoice template documentation to describe the authoritative preview compiler/runtime pipeline, compile cache behavior, diagnostics/verification semantics, and GUI save alignment with generated source.
  • File: docs/billing/invoice_templates.md
  • Validation command: rg -n "authoritative|layout verification|GUI -> IR|runAuthoritativeInvoiceTemplatePreview" docs/billing/invoice_templates.md
  • Result: documentation now reflects implemented GUI -> IR -> AssemblyScript -> Wasm -> render -> verify preview flow and explicitly documents read-only/no-write preview guarantees.
• (2026-02-09) T001 completed: component coverage verifies nested Design and Preview tabs render under Visual workspace.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (renders Design and Preview tabs with stable automation IDs).
• (2026-02-09) T002 completed: top-level Visual/Code tab behavior remains intact with preview workflow additions.
  • Evidence: packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.previewWorkspace.test.tsx (preserves nested visual workspace state when switching Visual -> Code -> Visual).
• (2026-02-09) T003 completed: preview session reducer initializes compile/render/verify lifecycle statuses to idle.
  • Evidence: packages/billing/src/components/invoice-designer/preview/previewSessionState.test.ts (initializes with sample source and idle pipeline statuses).
• (2026-02-09) T004 completed: source switching test now explicitly verifies Sample<->Existing toggles do not drop current design workspace nodes.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (refreshes preview output when switching Sample -> Existing -> Sample).
  • Validation command: pnpm vitest packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx
• (2026-02-09) T005 completed: sample scenario catalog test enforces at least three curated scenarios.
  • Evidence: packages/billing/src/components/invoice-designer/preview/sampleScenarios.test.ts (exports at least three unique scenarios).
• (2026-02-09) T006 completed: sample payload test enforces required renderer fields and numeric totals/amounts types.
  • Evidence: packages/billing/src/components/invoice-designer/preview/sampleScenarios.test.ts (provides required preview fields for each sample).
• (2026-02-09) T007 completed: existing-invoice selector test verifies paginated tenant invoice query calls are issued.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (calls paginated invoice search with status=all and query filters).
• (2026-02-09) T008 completed: existing selector integration test verifies search term filtering drives invoice query input.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (calls paginated invoice search with status=all and query filters).
• (2026-02-09) T009 completed: selecting an existing invoice triggers detail fetch and normalization before preview.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (loads selected existing invoice detail and maps it for preview).
• (2026-02-09) T010 completed: invoice normalization unit test covers null/optional fields without crashes.
  • Evidence: packages/billing/src/lib/adapters/invoiceAdapters.test.ts (handles nullable/partial values safely).
• (2026-02-09) T011 completed: GUI compiler IR unit test covers supported node type conversion from workspace snapshot.
  • Evidence: packages/billing/src/components/invoice-designer/compiler/guiIr.test.ts (converts workspace nodes into compiler IR with all supported node types).
• (2026-02-09) T012 completed: IR extraction test preserves parent-child hierarchy and layout metadata.
  • Evidence: packages/billing/src/components/invoice-designer/compiler/guiIr.test.ts (preserves hierarchy and layout metadata for compiler consumers).
• (2026-02-09) T013 completed: deterministic codegen unit test confirms equivalent workspace inputs produce identical AssemblyScript output and hash.
  • Evidence: packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.test.ts (produces deterministic source for equivalent workspace models).
• (2026-02-09) T014 completed: codegen test covers field binding logic emission for supported field metadata bindings.
  • Evidence: packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.test.ts (emits field, table, and totals binding logic from GUI metadata).
• (2026-02-09) T015 completed: codegen test covers table/dynamic row binding emission via item binding helper calls.
  • Evidence: packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.test.ts (emits field, table, and totals binding logic from GUI metadata).
• (2026-02-09) T016 completed: totals binding/formatting hooks are validated in codegen output assertions.
  • Evidence: packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.test.ts (emits field, table, and totals binding logic from GUI metadata).
• (2026-02-09) T017 completed: layout/style declarations from GUI constraints are asserted in generated AssemblyScript output.
  • Evidence: packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.test.ts (emits layout/style declarations derived from node size, position, and layout metadata).
• (2026-02-09) T018 completed: diagnostics mapping tests validate compiler errors are linked back to GUI node ids when source map coverage exists.
  • Evidence: packages/billing/src/components/invoice-designer/compiler/diagnostics.test.ts.
• (2026-02-09) T019 completed: compile parity integration test validates preview compile path reuses shared AssemblyScript flags/options helper used by production compile.
  • Evidence: packages/billing/src/actions/invoiceTemplateCompileParity.test.ts.
• (2026-02-09) T020 completed: compile cache unit test verifies cached artifacts are reused for unchanged source hashes.
  • Evidence: packages/billing/src/actions/invoiceTemplatePreview.cache.test.ts (stores and retrieves entries by source hash key).
• (2026-02-09) T021 completed: cache test now asserts changed source hash keys produce cache misses/new artifacts (invalidation behavior).
  • Evidence: packages/billing/src/actions/invoiceTemplatePreview.cache.test.ts (treats changed source hashes as cache misses requiring new artifacts).
  • Validation command: pnpm vitest packages/billing/src/actions/invoiceTemplatePreview.cache.test.ts
• (2026-02-09) T022 completed: preview component test now asserts compile failure state renders actionable error + compiler detail text.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (displays actionable compile failure details in preview status panel).
  • Validation command: pnpm vitest packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx
• (2026-02-09) T023 completed: compile parity suite now enforces preview compile action has no template/invoice persistence helper dependencies.
  • Evidence: packages/billing/src/actions/invoiceTemplateCompileParity.test.ts (keeps preview compile path side-effect free from invoice/template persistence helpers).
  • Validation command: pnpm vitest packages/billing/src/actions/invoiceTemplateCompileParity.test.ts
• (2026-02-09) T024 completed: authoritative preview integration test validates compiled Wasm executes through the same runtime/render path as direct runtime calls.
  • Evidence: packages/billing/src/actions/invoiceTemplatePreview.integration.test.ts.
• (2026-02-09) T025 completed: integration parity test asserts preview render returns HTML/CSS contract identical to direct renderLayout output for same runtime layout.
  • Evidence: packages/billing/src/actions/invoiceTemplatePreview.integration.test.ts (expect(actionResult.render.html).toBe(directRender.html) / CSS parity assertion).
• (2026-02-09) T026 completed: preview component test verifies authoritative iframe output is used in preview mode and design-canvas shell is not used as authoritative output.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (uses authoritative preview output surface instead of design-canvas scaffolds).
  • Validation command: pnpm vitest packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx
• (2026-02-09) T027 completed: debounce unit coverage confirms rapid edits do not trigger immediate unbounded compile/render calls.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (recomputes preview after metadata changes and debounces rapid edits).
• (2026-02-09) T028 completed: manual rerun test verifies pipeline reruns without model delta and sets bypassCompileCache.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (manual rerun retriggers pipeline without workspace delta and bypasses compile cache).
  • Validation command: pnpm vitest packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx
• (2026-02-09) T029 completed: pipeline in-flight test asserts preview loading indicator and running compile/render statuses are shown.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (shows loading indicator while compile/render pipeline is in flight).
  • Validation command: pnpm vitest packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx
• (2026-02-09) T030 completed: preview UI test verifies explicit empty state when no preview data is selected (Existing source with no invoice selected).
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (shows preview empty state when no preview data is selected).
  • Validation command: pnpm vitest packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx
• (2026-02-09) T031 completed: preview verification error state test asserts explicit error badge and message when verification execution fails.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (shows distinct verification error state when layout verification execution fails).
  • Validation command: pnpm vitest packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx
• (2026-02-09) T032 completed: preview mode drag-like interaction test confirms node positions remain unchanged.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (blocks drag-like interactions while in preview mode).
  • Validation command: pnpm vitest packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx
• (2026-02-09) T033 completed: preview mode resize-like interaction test confirms node sizes remain unchanged.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (blocks resize-like interactions while in preview mode).
• (2026-02-09) T034 completed: preview mode keyboard shortcut test confirms delete/backspace do not remove workspace nodes.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (ignores destructive keyboard shortcuts while in preview mode).
• (2026-02-09) T035 completed: constraint extraction now emits categorized spacing/alignment/sizing/containment constraints for flex-layout parent/child relationships.
  • Files: packages/billing/src/lib/invoice-template-compiler/layoutVerification.ts, packages/billing/src/lib/invoice-template-compiler/layoutVerification.test.ts
  • Validation command: pnpm vitest packages/billing/src/lib/invoice-template-compiler/layoutVerification.test.ts packages/billing/src/lib/invoice-template-compiler/layoutVerification.fixtures.test.ts
• (2026-02-09) T036 completed: geometry collector coverage verifies normalized bounding-box metrics are produced from rendered layout style fields.
  • Evidence: packages/billing/src/lib/invoice-template-compiler/layoutVerification.test.ts (pass/fail fixtures call collectRenderedGeometryFromLayout before comparison).
• (2026-02-09) T037 completed: layout comparator pass behavior is validated for geometry within tolerance.
  • Evidence: packages/billing/src/lib/invoice-template-compiler/layoutVerification.test.ts (passes when rendered geometry stays within tolerance).
• (2026-02-09) T038 completed: layout comparator failure behavior is validated for geometry that exceeds configured tolerance.
  • Evidence: packages/billing/src/lib/invoice-template-compiler/layoutVerification.test.ts (reports mismatches when rendered geometry exceeds tolerance).
• (2026-02-09) T039 completed: mismatch report assertions validate presence of constraint id plus expected/actual/delta/tolerance fields.
  • Evidence: packages/billing/src/lib/invoice-template-compiler/layoutVerification.fixtures.test.ts (fails drifted design fixture with expected mismatch set).
• (2026-02-09) T040 completed: preview component test verifies pass badge and pass summary message when all constraints satisfy verification.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (shows pass verification badge when all layout constraints pass).
  • Validation command: pnpm vitest packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx
• (2026-02-09) T041 completed: preview component test verifies issues badge and mismatch row rendering when verification detects failing constraints.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (shows issues verification badge when one or more constraints fail).
• (2026-02-09) T042 completed: editor integration test verifies save payload includes compiler-generated AssemblyScript source tied to current GUI workspace.
  • Evidence: packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.previewWorkspace.test.tsx and InvoiceTemplateEditor.authoritativeFlow.test.tsx.
• (2026-02-09) T043 completed: save compile wiring test verifies source-present save path routes through compile-and-save flow that persists/recompiles wasm artifacts.
  • Evidence: packages/billing/src/actions/invoiceTemplateCompileParity.test.ts (keeps save action wired to compile and persist wasm artifacts when source is present).
  • Validation command: pnpm vitest packages/billing/src/actions/invoiceTemplateCompileParity.test.ts
• (2026-02-09) T044 completed: Code tab behavior test validates generated/read-only rule for GUI templates and ignores manual code edits on save.
  • Evidence: packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.previewWorkspace.test.tsx (keeps Code tab generated/read-only for GUI templates).
  • Validation command: pnpm vitest packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.previewWorkspace.test.tsx
• (2026-02-09) T045 completed: synchronization test verifies Visual/Code switching keeps generated source aligned with GUI workspace metadata changes.
  • Evidence: packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.previewWorkspace.test.tsx (keeps generated source synchronized with GUI model while switching Visual and Code).
  • Validation command: pnpm vitest packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.previewWorkspace.test.tsx
• (2026-02-09) T046 completed: hydration tests validate source-embedded and localStorage workspace restore paths remain functional with compiler-enabled preview.
  • Evidence: packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.previewWorkspace.test.tsx (hydrates workspace from source-embedded designer state, hydrates workspace from localStorage fallback...).
• (2026-02-09) T047 completed: automation ID coverage verifies preview source and selector controls expose stable selectors.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (exposes stable automation IDs for source and selector controls).
• (2026-02-09) T048 completed: status-indicator automation ID test verifies compile/render/verify selectors are stable in preview UI.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (exposes stable automation ids for compile/render/verify status indicators).
  • Validation command: pnpm vitest packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx
• (2026-02-09) T049 completed: verification issues test now asserts mismatch list and mismatch item automation IDs are present.
  • Evidence: packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.test.tsx (shows issues verification badge when one or more constraints fail).
• (2026-02-09) T050 completed: added deterministic compiler golden snapshot test for representative fixtures (simple field/label and table+totals layouts).
  • Files: packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.test.ts, snapshot artifact in __snapshots__.
  • Validation command: pnpm vitest packages/billing/src/components/invoice-designer/compiler/assemblyScriptGenerator.test.ts
• (2026-02-09) T051 completed: integration parity test proves preview output equals real runtime output for same generated template and invoice input.
  • Evidence: packages/billing/src/actions/invoiceTemplatePreview.integration.test.ts.
• (2026-02-09) T052 completed: aligned layout fixture integration test verifies verification pass behavior when design/render geometry match.
  • Evidence: packages/billing/src/lib/invoice-template-compiler/layoutVerification.fixtures.test.ts (passes aligned design fixture within tolerance).
• (2026-02-09) T053 completed: drifted layout fixture integration test verifies expected mismatch set when rendered output diverges.
  • Evidence: packages/billing/src/lib/invoice-template-compiler/layoutVerification.fixtures.test.ts (fails drifted design fixture with expected mismatch set).
• (2026-02-09) T054 completed: editor-level e2e flow test covers design edit -> authoritative preview -> verification -> save.
  • Evidence: packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.authoritativeFlow.test.tsx (covers design edit -> authoritative preview -> verification -> save).
• (2026-02-09) T055 completed: editor-level e2e test covers existing invoice selection and authoritative preview update path.
  • Evidence: packages/billing/src/components/billing-dashboard/InvoiceTemplateEditor.authoritativeFlow.test.tsx (updates authoritative preview when switching to existing invoice data).
• (2026-02-09) T056 completed: billing invoice template documentation now describes authoritative preview compiler/runtime pipeline and verification semantics.
  • Evidence: docs/billing/invoice_templates.md authoritative preview sections.