# 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.