PSA/ee/docs/plans/2026-02-13-invoice-template-designer-safety-hardening/SCRATCHPAD.md

Scratchpad — Invoice Template + Designer Safety Hardening

• Plan slug: invoice-template-designer-safety-hardening
• Created: 2026-02-13

What This Is

Keep a lightweight, continuously-updated log of discoveries and decisions made while implementing this plan.

Prefer short bullets. Append new entries as you learn things, and also update earlier notes when a decision changes or an open question is resolved.

Decisions

• (2026-02-13) Canonical designer state is node.props + node.children.
  • Rationale: eliminates dual-source-of-truth bugs and aligns with the unified component AST direction.
• (2026-02-13) Generic patch/mutation API (setNodeProp/unsetNodeProp) must reject prototype-pollution keys in paths.
  • Rationale: path-based writes are otherwise a common source of prototype pollution.
• (2026-02-13) Leaf array unset splices the array (removes the element) instead of writing undefined.
  • Rationale: avoids sparse arrays and avoids JSON serialization converting undefined to null in history snapshots.
• (2026-02-13) Invoice template AST style identifiers are validated (reject invalid) rather than sanitized at render time.
  • Rationale: sanitization can create collisions; validation fails fast and keeps rendering deterministic.

Discoveries / Constraints

• (2026-02-13) Recent tracked secrets: server/.env.local.bak.* were committed and then removed in fc2625507.
• (2026-02-13) Added repo .gitignore patterns to ignore env-backup files (e.g. **/.env*.bak*, server/.env.local.bak*) to prevent credential leaks.
• (2026-02-13) Added repo guardrails to fail CI if any tracked file matches .env*.bak* patterns:
  • Script: scripts/guard-no-tracked-env-backups.mjs
  • CI: .github/workflows/secrets-env-backup-guard.yml
• (2026-02-13) Current patch implementation writes to both props.* and legacy top-level fields via expandPaths:
  • packages/billing/src/components/invoice-designer/state/designerStore.ts
• (2026-02-13) Designer store now normalizes legacy patch paths (name, metadata.*, layout.*, style.*) to canonical props.* and writes only canonical state.
  • packages/billing/src/components/invoice-designer/state/designerStore.ts
• (2026-02-13) Legacy node fields (name, metadata, layout, style) are treated as derived views of canonical props.* (no independent writes).
  • packages/billing/src/components/invoice-designer/state/designerStore.ts
• (2026-02-13) Hierarchy mutations now treat node.children as canonical and no longer rely on or update childIds.
  • packages/billing/src/components/invoice-designer/state/patchOps.ts
  • packages/billing/src/components/invoice-designer/state/designerStore.ts
• (2026-02-13) UI call sites now use canonical props reads via getNodeName/getNodeMetadata/getNodeLayout/getNodeStyle (no direct legacy field reads in UI components touched).
  • packages/billing/src/components/invoice-designer/DesignerShell.tsx
  • packages/billing/src/components/invoice-designer/palette/OutlineView.tsx
  • packages/billing/src/components/invoice-designer/labelText.ts
  • Removed stale layout.mode/layout.sizing references from section-fit messaging; CSS-first layout now keys off layout.display.
• (2026-02-13) Continuous typing interactions in the metadata inspector now use commit=false on onChange and commit=true on onBlur to avoid history spam.
  • packages/billing/src/components/invoice-designer/DesignerShell.tsx
• (2026-02-13) Patch ops currently allow arbitrary object keys and could write __proto__ unless guarded:
  • packages/billing/src/components/invoice-designer/state/patchOps.ts
• (2026-02-13) Patch ops now reject prototype-pollution path segments (__proto__, prototype, constructor) at any depth (safe no-op):
  • packages/billing/src/components/invoice-designer/state/patchOps.ts
  • Rejection behavior: returns the original nodes reference and performs no mutation or history side-effects.
  • Observability: rejected patches emit a dev-only console.warn.
• (2026-02-13) Patch ops unset for leaf array indices now splices the array (removes element, no undefined holes).
  • packages/billing/src/components/invoice-designer/state/patchOps.ts
  • Nested unsets inside array elements keep the element in place; if the element becomes empty it is left as {} to remain JSON-serializable.
• (2026-02-13) Patch ops now reject non-JSON values in setNodeProp (e.g. undefined, NaN, Infinity, functions, class instances) to keep history snapshots deterministic.
  • packages/billing/src/components/invoice-designer/state/patchOps.ts
  • Array set fills missing indices with null to avoid sparse arrays (JSON stringification would otherwise introduce null implicitly).
• (2026-02-13) Invoice template AST renderer emits CSS selectors/vars based on unvalidated identifiers:
  • packages/billing/src/lib/invoice-template-ast/react-renderer.tsx
  • packages/billing/src/lib/invoice-template-ast/schema.ts
• (2026-02-13) Invoice template AST schema now validates style identifiers (class keys, token ids, styleRef tokenIds) against a strict safe identifier regex and rejects invalid inputs.
  • packages/billing/src/lib/invoice-template-ast/schema.ts
• (2026-02-13) Invoice template AST renderer now sanitizes style identifiers before emitting CSS selectors and custom properties (defense-in-depth even if schema validation is bypassed).
  • packages/billing/src/lib/invoice-template-ast/react-renderer.tsx
• (2026-02-13) Legacy workspace nodes[] imports can include props: {}; snapshotting now materializes canonical props.name/metadata/layout/style from legacy top-level fields so UI helpers can consistently read canonical props.
  • packages/billing/src/components/invoice-designer/state/designerStore.ts
  • Test: packages/billing/src/components/invoice-designer/state/designerStore.loadWorkspace.legacy.test.ts
• (2026-02-13) Added hierarchy unit coverage to ensure canonical children is authoritative and childIds is not used/written during mutations.
  • Test: packages/billing/src/components/invoice-designer/state/patchOps.insertChild.test.ts
• (2026-02-13) Extended hierarchy unit coverage for moveNode to assert ordering adjustments, cycle prevention, and canonical children authority (no legacy childIds writes).
  • Test: packages/billing/src/components/invoice-designer/state/patchOps.moveNode.test.ts
• (2026-02-13) Extended hierarchy unit coverage for deleteNode to ensure subtree traversal keys off canonical children and does not mutate legacy childIds.
  • Test: packages/billing/src/components/invoice-designer/state/patchOps.deleteNode.test.ts
• (2026-02-13) Added UI integration coverage to ensure Outline/tree rendering prefers canonical props.name over legacy top-level name.
  • Test: packages/billing/src/components/invoice-designer/palette/OutlineView.integration.test.tsx
• (2026-02-13) Added a focused DesignerShell UI test to ensure the selected-node header uses getNodeName (canonical props.name takes precedence over legacy name).
  • Test: packages/billing/src/components/invoice-designer/DesignerShell.selectedContext.integration.test.tsx
• (2026-02-13) Added unit coverage for leaf array unset semantics: leaf index unsets splice the array (no undefined holes).
  • Test: packages/billing/src/components/invoice-designer/state/patchOps.unsetNodeProp.test.ts
• (2026-02-13) Added unit coverage to ensure nested unsets inside array elements remove only the nested property (do not splice the element).
  • Test: packages/billing/src/components/invoice-designer/state/patchOps.unsetNodeProp.test.ts
• (2026-02-13) Added undo/redo coverage for canonical JSON snapshots involving array edits (set + leaf-array unset splice) to ensure history restores exact committed state.
  • Test: packages/billing/src/components/invoice-designer/state/designerStore.undoRedo.test.ts
• (2026-02-13) Added undo/redo coverage for a mixed sequence of setNodeProp + hierarchy ops (move/delete) to ensure history replay is deterministic.
  • Test: packages/billing/src/components/invoice-designer/state/designerStore.undoRedo.test.ts
• (2026-02-13) Added direct store-level tests for commit=false vs commit=true semantics to prevent history spam during continuous interactions.
  • Test: packages/billing/src/components/invoice-designer/state/designerStore.historyCommit.test.ts
• (2026-02-13) Added DesignCanvas pointer-driven resize integration test asserting onResize(..., commit=false) during motion and a final commit=true on pointer-up.
  • Test: packages/billing/src/components/invoice-designer/canvas/DesignCanvas.resizeProps.integration.test.tsx
• (2026-02-13) Added schema coverage ensuring invoice-template AST style class keys must pass safe CSS identifier validation.
  • Test: packages/billing/src/lib/invoice-template-ast/schema.test.ts
• (2026-02-13) Added schema coverage ensuring token ids and styleRef tokenIds must pass safe CSS identifier validation.
  • Test: packages/billing/src/lib/invoice-template-ast/schema.test.ts
• (2026-02-13) Added authoritative preview coverage: schema validation failures return compile diagnostics and do not proceed to render HTML/CSS output.
  • Test: packages/billing/src/actions/invoiceTemplatePreview.schemaFailure.test.ts
• (2026-02-13) Added renderer defense-in-depth coverage: even if invalid identifiers bypass schema validation, CSS selectors/vars and HTML class names are sanitized.
  • Test: packages/billing/src/lib/invoice-template-ast/react-renderer.test.tsx

Commands / Runbooks

• (2026-02-13) Check for tracked env backups:
  • git ls-files | rg "\\.env\\.local\\.bak\\.|\\.env\\.bak\\."
• (2026-02-13) Check .gitignore contains env-backup ignore patterns:
  • node scripts/test-gitignore-env-backups.mjs
• (2026-02-13) Test env-backup guard script (pass + fail cases in a temp git repo):
  • node scripts/test-guard-no-tracked-env-backups.mjs
• (2026-02-13) Run invoice-designer unit tests (Vitest config root is server/):
  • cd server && npx vitest run ../packages/billing/src/components/invoice-designer/state/patchOps.setNodeProp.test.ts
• (2026-02-13) Gotcha: Vitest can fail with ENOSPC (no space left on device); running with --coverage=false reduces temp output and avoided the issue locally.

Links / References

• PRDs, issues, PRs, docs, dashboards, logs, and key file paths.
• Key files:
  • packages/billing/src/components/invoice-designer/state/patchOps.ts
  • packages/billing/src/components/invoice-designer/state/designerStore.ts
  • packages/billing/src/components/invoice-designer/utils/nodeProps.ts
  • packages/billing/src/lib/invoice-template-ast/schema.ts
  • packages/billing/src/lib/invoice-template-ast/react-renderer.tsx

Open Questions

• Questions that block the work or need follow-up.
• Do we want patch rejection to be silent no-op, console-warn, or surfaced as a formal diagnostic in the designer UI?