PSA/ee/docs/plans/2026-02-13-invoice-designer-unified-component-ast/SCRATCHPAD.md

# SCRATCHPAD — Invoice Designer Unified Component AST

## Context

Goal: collapse designer state into a unified generic node tree so adding new properties (for example `borderRadius`) is mostly schema work, not store plumbing.

This plan intentionally continues the simplification arc:

1. Templates are data (`templateAst` JSON) not code/WASM.
2. Layout math is delegated to the DOM/CSS engine (flex/grid + dnd-kit).
3. Designer state becomes a single generic AST with schema-driven editing.

## Current State (Starting Point)

- Designer store uses `DesignerNode[]` with typed fields:
  - `position`, `size`, `parentId`, `childIds`, `allowedChildren`, `layout`, `style`, `metadata`, etc.
- Property editing is largely hardcoded in `packages/billing/src/components/invoice-designer/DesignerShell.tsx`.
- Nesting rules are defined in `packages/billing/src/components/invoice-designer/state/hierarchy.ts`.
- Palette metadata defaults live in `packages/billing/src/components/invoice-designer/constants/componentCatalog.ts`.

## Decisions (Implementation Choices That Minimize Trouble)

- Source of truth for hierarchy is `children` arrays only.
  - Do not persist `parentId` (redundant and easy to desync).
  - Parent lookup is derived when needed (tree sizes are small enough for O(n) searches).
- Patch API uses dot-notation paths (for example `style.width`, `metadata.bindingKey`) rather than JSON Pointer to keep call sites readable.
  - Internally, patch operations should be applied immutably (structural sharing).
  - This patch API is a hard requirement for the strategy: without it, the refactor cost is paid without getting the “new prop = schema change” velocity gain.
- Component schema becomes the single source of truth for:
  - palette labels/descriptions/categories
  - defaults (initial props)
  - editable props schema (inspector UI)
  - allowed parents/children (nesting rules)
- Inspector will support a small set of core field widgets plus opt-in custom widgets for complex objects/arrays (tables).

## Notes / Gotchas

- Ensure history/undo remains stable:
  - Either snapshot `nodesById + rootId` per commit, or store patches and replay.
  - Snapshotting is simpler and aligns with current approach; patch replay is smaller but more error-prone.
- Some existing code expects `allowedChildren` to be present on nodes; that must become a derived selector from schema.
- Export/import to invoice-template AST needs a single authoritative mapping; avoid letting schema defaults leak into exported templates unexpectedly.

## File Targets (Likely Touchpoints)

- Store:
  - `packages/billing/src/components/invoice-designer/state/designerStore.ts`
- Hierarchy rules removal:
  - `packages/billing/src/components/invoice-designer/state/hierarchy.ts` (delete)
- Component schema/catalog:
  - `packages/billing/src/components/invoice-designer/constants/componentCatalog.ts` (likely merged into or replaced by schema module)
- Inspector refactor:
  - `packages/billing/src/components/invoice-designer/DesignerShell.tsx`
- Canvas rendering:
  - `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx`
- Workspace AST mapping:
  - `packages/billing/src/components/invoice-designer/ast/workspaceAst.ts`

## Validation Runbook (When Implementing)

- Tree invariants:
  - every child id exists in `nodesById`
  - no cycles (walk from root and track visited)
  - all nodes are reachable from root (or explicitly allow unattached nodes, but prefer not to)
- Quick grep for legacy references:
  - `rg -n "parentId|allowedChildren|updateNodeStyle\\(|updateNodeLayout\\(|updateNodeMetadata\\(" packages/billing/src/components/invoice-designer -S`

## Developer Guide (Adding Props / Components)

### Component Schema Source Of Truth

- File: `packages/billing/src/components/invoice-designer/schema/componentSchema.ts`
- Each component defines:
  - `label`/`description`/`category` (palette + inspector display metadata)
  - `defaults`: initial `name`, `layout`, `style`, `metadata`, `size`
  - `hierarchy`: `allowedParents` + `allowedChildren`
  - `inspector`: panels/fields (schema-driven Inspector)
- Helpers now live on the schema module:
  - `getAllowedChildrenForType(type)`
  - `getAllowedParentsForType(type)`
  - `canNestWithinParent(childType, parentType)`

### Inspector Schema Format

- Files:
  - `packages/billing/src/components/invoice-designer/schema/inspectorSchema.ts` (field/panel types)
  - `packages/billing/src/components/invoice-designer/inspector/DesignerSchemaInspector.tsx` (renderer)
- Field kinds supported:
  - primitives: `string`, `number`, `boolean`, `enum`
  - CSS-ish: `css-length`, `css-color`
  - complex: `widget` (custom React editor for component-specific metadata)
- Visibility rules:
  - `visibleWhen` supports `nodeIsContainer`, `pathEquals`, `parentPathEquals`
- Widgets:
  - Implement widgets in `packages/billing/src/components/invoice-designer/inspector/widgets/`
  - Register by referencing the widget `id` in schema (example: `table-editor` for `metadata.columns`)

### Patch API (How To Mutate State)

- File: `packages/billing/src/components/invoice-designer/state/designerStore.ts`
- Only supported mutation surface (for anything persistent/undoable):
  - `setNodeProp(nodeId, path, value, commit?)`
  - `unsetNodeProp(nodeId, path, commit?)`
  - `insertChild(parentId, childId, index)`
  - `removeChild(parentId, childId)`
  - `moveNode(nodeId, nextParentId, nextIndex)`
  - `deleteNode(nodeId)`
- Dot-path conventions (recommended):
  - `name`
  - `style.*` (sizing/typography/media CSS-like props)
  - `layout.*` (container layout props)
  - `metadata.*` (component-specific config)
- History/undo semantics:
  - `commit` defaults to `true`
  - For multi-step edits that should be a single undo step: use `commit=false` for intermediate writes and `commit=true` for the final write.

### Persistence Rules (What Gets Serialized)

- Persisted workspace snapshot is `{ rootId, nodesById, canvas settings }`.
- `exportWorkspace()` sanitizes node `props` to drop runtime/editor-only keys:
  - `position`, `size`, `baseSize`, `layoutPresetId`
- If a prop should survive reload and affect output, it should live under:
  - `props.style`, `props.layout`, or `props.metadata` (and be surfaced via schema).

### Conventions For Adding A New Property

1. Add/extend the schema field in `componentSchema.ts` (usually via `COMMON_INSPECTOR` or component-specific `inspector`).
2. Provide a default in `defaults.style` / `defaults.layout` / `defaults.metadata` only if it must exist on insertion.
3. Avoid adding store actions/reducers: use `setNodeProp`/`unsetNodeProp` from inspector and other UI.

### Conventions For Adding A New Component

1. Add a `DesignerComponentSchema` entry in `DESIGNER_COMPONENT_SCHEMAS`.
2. Define `hierarchy.allowedParents` and `hierarchy.allowedChildren` (the only authority for nesting rules).
3. Define `defaults` and `inspector` panels/fields.
4. Canvas/palette/outline should not need bespoke wiring if schema is complete.

## Progress Log

- 2026-02-13: Implemented unified AST type definitions in `packages/billing/src/components/invoice-designer/state/designerAst.ts`:
  - `DesignerAstNode` with `{ id, type, props, children }`
  - `DesignerAstWorkspace` with `{ rootId, nodesById }`
  - Stable document root id constant: `DESIGNER_AST_DOCUMENT_ID = 'designer-document-root'`
- 2026-02-13: Added canonical indexing to the designer store state in `packages/billing/src/components/invoice-designer/state/designerStore.ts`:
  - Store state now includes `rootId` and `nodesById` kept in sync with the existing `nodes` array via a `setWithIndex` wrapper.
  - This is an incremental cutover step so downstream UI/tests can migrate off `nodes` progressively.
- 2026-02-13: Implemented generic patch operations in `packages/billing/src/components/invoice-designer/state/patchOps.ts` and exposed them on the store:
  - `setNodeProp` / `unsetNodeProp` for dot-path updates (immutable deep updates with empty-object cleanup).
  - `insertChild` / `removeChild` / `moveNode` / `deleteNode` for hierarchy mutations (cycle prevention in `moveNode`).
  - Renamed legacy coordinate nudge API to `moveNodeByDelta` to free `moveNode` for tree moves.
- 2026-02-13: Refined undo/redo history behavior in `packages/billing/src/components/invoice-designer/state/designerStore.ts`:
  - Store now initializes history with a baseline snapshot so the first committed mutation can be undone.
  - `setNodeProp` / `unsetNodeProp` now commit to history by default to match existing property-edit behavior.
- 2026-02-13: Introduced component schema definitions in `packages/billing/src/components/invoice-designer/schema/componentSchema.ts`:
  - Defines per-component label/description/category, defaults (size/layout/metadata), and hierarchy allowlists.
  - `packages/billing/src/components/invoice-designer/constants/componentCatalog.ts` now derives palette definitions from schema (schema is the new source of truth for palette metadata/defaults).
- 2026-02-13: Hierarchy allowlists are now resolved via schema:
  - `packages/billing/src/components/invoice-designer/state/hierarchy.ts` is now a thin wrapper over `getComponentSchema(type).hierarchy`.
- 2026-02-13: Palette insertion now uses schema defaults and generic tree ops:
  - `packages/billing/src/components/invoice-designer/state/designerStore.ts` `addNodeFromPalette` now pulls size/layout/style/metadata defaults from `getComponentSchema(type).defaults` and attaches nodes using `insertChild` semantics (`patchOps.insertChild`).
  - Default metadata normalization for repeated insertions (table columns, attachment items) moved into the store (`normalizeDefaultMetadataForNewNode`), removing hardcoded defaults from `DesignerShell.tsx`.
- 2026-02-13: Outline + breadcrumbs now traverse the tree via children arrays:
  - `packages/billing/src/components/invoice-designer/palette/OutlineView.tsx` now renders from `rootId` and `nodesById`, deriving parent lookup only for expand behavior.
  - `packages/billing/src/components/invoice-designer/DesignerShell.tsx` breadcrumbs now derive parent links from `childIds` instead of relying on persisted `parentId`.
- 2026-02-13: Selection/hover state now validates ids against `nodesById`:
  - `packages/billing/src/components/invoice-designer/state/designerStore.ts` `selectNode`/`setHoverNode` clear invalid ids and `deleteNode` clears selection/hover if the referenced node is removed as part of a subtree delete.
- 2026-02-13: Canvas rendering now resolves from unified node props:
  - Added `packages/billing/src/components/invoice-designer/utils/nodeProps.ts` as the canonical accessor for `props.name`, `props.layout`, `props.style`, `props.metadata` (with temporary legacy fallbacks during cutover).
  - `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx` and `packages/billing/src/components/invoice-designer/canvas/previewScaffolds.ts` now render using `props.*` accessors.
  - Store mutations keep `props` in sync with legacy fields for now (`packages/billing/src/components/invoice-designer/state/designerStore.ts`).
- 2026-02-13: Drag-drop reparent/reorder now uses generic tree ops:
  - `packages/billing/src/components/invoice-designer/DesignerShell.tsx` now calls `store.moveNode(...)` (tree move) instead of `moveNodeToParentAtIndex`.
  - `packages/billing/src/components/invoice-designer/state/designerStore.flowDnd.test.ts` updated to exercise `moveNode(...)` directly.
- 2026-02-13: Resizing now writes through the generic patch API:
  - Removed `updateNodeSize` from `packages/billing/src/components/invoice-designer/state/designerStore.ts`.
  - `packages/billing/src/components/invoice-designer/DesignerShell.tsx` now implements `resizeNode(...)` using `setNodeProp` writes (`size.*`, `baseSize.*`, `style.*`) with a single history commit on mouse-up.
  - `setNodeProp`/`unsetNodeProp` now mirror `name`/`style.*`/`layout.*`/`metadata.*` updates into both legacy fields and `props.*` during cutover.
- 2026-02-13: Started schema-driven Inspector cutover:
  - Added a minimal inspector schema format in `packages/billing/src/components/invoice-designer/schema/inspectorSchema.ts` and attached schemas to component definitions in `packages/billing/src/components/invoice-designer/schema/componentSchema.ts`.
  - Implemented `packages/billing/src/components/invoice-designer/inspector/DesignerSchemaInspector.tsx` which renders panels/fields from the selected node's component schema and writes edits via `setNodeProp`/`unsetNodeProp` (commit-on-blur for text fields).
  - Updated `packages/billing/src/components/invoice-designer/DesignerShell.tsx` to render the schema-driven inspector for supported metadata panels while leaving complex editors (tables/attachments/media) on the legacy path for now.
- 2026-02-13: Expanded schema-driven Inspector field types and conditional panels:
  - `packages/billing/src/components/invoice-designer/schema/inspectorSchema.ts` now supports `number`, `css-length`, `css-color` field kinds plus `visibleWhen` rules (`nodeIsContainer`, `pathEquals`, `parentPathEquals`).
  - `packages/billing/src/components/invoice-designer/schema/componentSchema.ts` now defines a `COMMON_INSPECTOR` (Layout, Sizing, Flex Item) and merges it into all component schemas, so layout/style edits are schema-defined rather than hardcoded in the shell.
  - `packages/billing/src/components/invoice-designer/DesignerShell.tsx` removed the hardcoded Layout/Sizing/Flex Item inspector blocks and relies on `DesignerSchemaInspector` for those panels; legacy metadata editors remain only for complex types (table columns, attachment items, media).
- 2026-02-13: Added first complex schema widget for metadata:
  - Implemented `packages/billing/src/components/invoice-designer/inspector/widgets/TableEditorWidget.tsx` and wired it into the schema via a `widget` inspector field (`table-editor`).
  - `packages/billing/src/components/invoice-designer/schema/componentSchema.ts` now attaches the table editor widget to both `table` and `dynamic-table` schemas.
  - Removed the hardcoded table/dynamic-table inspector block from `packages/billing/src/components/invoice-designer/DesignerShell.tsx` (tables now render their metadata editor via schema widget).
- 2026-02-13: Updated designer <-> invoice-template AST mapping to prefer unified props + children:
  - `packages/billing/src/components/invoice-designer/ast/workspaceAst.ts` now reads `name/layout/style/metadata` via `packages/billing/src/components/invoice-designer/utils/nodeProps.ts` helpers and traverses `children` (fallback to `childIds` for legacy nodes).
  - Import now materializes `props` and `children` on generated nodes and keeps them in sync with legacy fields during cutover.
  - Updated `packages/billing/src/components/invoice-designer/ast/workspaceAst.test.ts` fixtures to set `props` + `children` so export/import exercises the unified tree.
- 2026-02-13: Added undo/redo history regression test in `packages/billing/src/components/invoice-designer/state/designerStore.undoRedo.test.ts`:
  - Verifies tree state returns exactly to prior snapshots after a `moveNode` followed by `deleteNode`, via sequential `undo()` and `redo()`.
- 2026-02-13: Added schema invariants test in `packages/billing/src/components/invoice-designer/schema/componentSchema.test.ts`:
  - Ensures every component type has defaults, an inspector schema, and reciprocal nesting allowlists (parent allowedChildren aligns with child allowedParents).
- 2026-02-13: Added repo/unit guard ensuring `packages/billing/src/components/invoice-designer/state/hierarchy.ts` stays deleted and is not imported anywhere in the invoice designer code.
- 2026-02-13: Added palette insertion integration test in `packages/billing/src/components/invoice-designer/state/designerStore.addNodeFromPalette.test.ts`:
  - Verifies `addNodeFromPalette` pulls `layout/metadata/size` defaults from the component schema and attaches the new node id into the parent `children` array.
- 2026-02-13: Added outline rendering integration test in `packages/billing/src/components/invoice-designer/palette/OutlineView.integration.test.tsx`:
  - Verifies outline order matches `childIds` ordering and selection state drives highlight styling.
- 2026-02-13: Added breadcrumbs hierarchy integration coverage in `packages/billing/src/components/invoice-designer/DesignerShell.breadcrumbs.test.ts`:
  - Validates breadcrumb path is derived from `childIds` (children-only hierarchy) and does not depend on persisted `parentId`.
- 2026-02-13: Added unified props rendering integration test in `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.unifiedProps.integration.test.tsx`:
  - Ensures `node.props.layout` and `node.props.style` are sufficient to drive DOM styles (without relying on `node.layout` / `node.style`).
- 2026-02-13: Added drag-drop reorder integration test in `packages/billing/src/components/invoice-designer/state/designerStore.dragDropReorder.integration.test.ts`:
  - Uses `loadWorkspace({ rootId, nodesById })` to validate `moveNode(...)` reorders `children` for flow (flex) containers in the unified snapshot format.
- 2026-02-13: Added drag-drop reparent integration test in `packages/billing/src/components/invoice-designer/state/designerStore.dragDropMoveAcross.integration.test.ts`:
  - Validates moving across containers updates only the unified `children` arrays in the exported workspace snapshot and rejects invalid parent targets via schema nesting rules.
- 2026-02-13: Added resize-to-DOM integration test in `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.resizeProps.integration.test.tsx`:
  - Simulates resize writes via `store.setNodeProp('style.width'/'style.height', ...)` and verifies the rendered canvas node element updates its inline sizing.
- 2026-02-13: Persisted workspace snapshots now omit runtime geometry/editor-only props:
  - `packages/billing/src/components/invoice-designer/state/designerStore.ts` `exportWorkspace()` sanitizes `node.props` to drop `position`, `size`, `baseSize`, and `layoutPresetId` (new saves are unified-only).
  - Updated `packages/billing/src/actions/invoicePreviewPdfParity.integration.test.ts` workspace fixture to use `{ rootId, nodesById }` (no `nodes` / `constraints`).
  - Updated `packages/billing/src/components/invoice-designer/state/designerStore.constraints.test.ts` assertions to validate unified snapshots.
- 2026-02-13: Removed legacy hierarchy module:
  - Deleted `packages/billing/src/components/invoice-designer/state/hierarchy.ts`.
  - Moved `getAllowedChildrenForType` / `getAllowedParentsForType` / `canNestWithinParent` helpers into `packages/billing/src/components/invoice-designer/schema/componentSchema.ts` and updated call sites to import from schema.
- 2026-02-13: Removed per-property store actions in favor of patch ops:
  - Deleted legacy store APIs: `updateNodeName`, `updateNodeMetadata`, `updateNodeLayout`, `updateNodeStyle`, `setNodePosition`, `moveNodeByDelta`, `moveNodeToParentAtIndex`.
  - Kept label text behavior by normalizing label `name` <-> `metadata.text` changes inside `setNodeProp`/`unsetNodeProp` (only when mutating `name` or `metadata.*`).
  - Fixed `rootId` indexing so `exportWorkspace()` snapshots can be round-tripped via `loadWorkspace()` even when legacy fixtures use non-canonical document ids.
  - Updated affected tests and UI call sites to use `setNodeProp`/`unsetNodeProp` exclusively.
- 2026-02-13: Added deterministic unified-tree traversal helper and tests:
  - `packages/billing/src/components/invoice-designer/state/designerAst.ts` now exports `traverseDesignerAstNodeIds`.
  - Added `packages/billing/src/components/invoice-designer/state/designerAst.test.ts`.
- 2026-02-13: Added patch ops unit coverage:
  - Added `packages/billing/src/components/invoice-designer/state/patchOps.setNodeProp.test.ts` to validate immutable deep dot-path updates.
  - Added `packages/billing/src/components/invoice-designer/state/patchOps.unsetNodeProp.test.ts` to validate cleanup behavior for empty objects.
  - Added `packages/billing/src/components/invoice-designer/state/patchOps.insertChild.test.ts` to validate deterministic child insertion ordering.
  - Added `packages/billing/src/components/invoice-designer/state/patchOps.moveNode.test.ts` to validate reorder/reparent semantics + cycle prevention.
  - Added `packages/billing/src/components/invoice-designer/state/patchOps.deleteNode.test.ts` to validate subtree deletion behavior.
- 2026-02-13: Added schema-driven inspector integration coverage:
  - Added `packages/billing/src/components/invoice-designer/inspector/DesignerSchemaInspector.integration.test.tsx` to assert the inspector renders fields from schema and writes unified `props.*` via generic patch operations.
  - Testing gotcha: our shared `<Input>` doesn’t reliably forward `id` to the native `<input>`, so tests query controls by placeholder rather than label association.
- 2026-02-13: Extracted Inspector input normalizers and added unit coverage:
  - Added `packages/billing/src/components/invoice-designer/inspector/normalizers.ts` (+ `normalizeString`, `normalizeCssLength`, `normalizeCssColor`, `normalizeNumber`) and wired `DesignerSchemaInspector` to use them.
  - Added `packages/billing/src/components/invoice-designer/inspector/normalizers.test.ts` to validate canonicalization behavior (for example unitless CSS lengths become `px`, empty strings unset).
- 2026-02-13: Added table editor schema widget integration coverage:
  - Added `packages/billing/src/components/invoice-designer/inspector/TableEditorWidget.integration.test.tsx` to assert the `table-editor` widget updates `metadata.columns` and the canvas preview header reacts to the updated columns list.
- 2026-02-13: Made workspace <-> template AST export/import deterministic:
  - Updated `packages/billing/src/components/invoice-designer/ast/workspaceAst.ts` import to treat a single top-level AST `section` wrapper as the designer `page` node (avoids nested page->section wrapping on roundtrip).
  - Added `export -> import -> export` deterministic roundtrip assertion in `packages/billing/src/components/invoice-designer/ast/workspaceAst.test.ts`.
- 2026-02-13: Added persisted workspace snapshot format coverage:
  - Added `packages/billing/src/components/invoice-designer/state/designerStore.exportWorkspace.test.ts` to ensure `exportWorkspace()` returns only `{ rootId, nodesById, snapToGrid, gridSize, showGuides, showRulers, canvasScale }` and strips runtime/editor-only `props` keys (`position`, `size`, `baseSize`, `layoutPresetId`).
- 2026-02-13: Added repo guards for refactor completeness:
  - Added `packages/billing/src/components/invoice-designer/state/noLegacyApis.guard.test.ts` to enforce removed per-property store action names stay gone, and to keep hierarchy traversal using `children` (no `childIds` usage outside `state/`).
  - Updated `packages/billing/src/components/invoice-designer/palette/OutlineView.tsx`, `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx`, and `packages/billing/src/components/invoice-designer/DesignerShell.tsx` to traverse `children` rather than `childIds`.