PSA/ee/docs/plans/2026-02-13-invoice-designer-native-css-layout-engine/SCRATCHPAD.md

# SCRATCHPAD — Invoice Designer Native CSS Layout Engine

## Context

Goal: remove bespoke geometry math in the invoice designer and rely on native browser layout (CSS flex/grid + box model). Replace custom drop-parent resolution with `@dnd-kit/core` DOM-driven collision detection.

## Target Deletions

- `packages/billing/src/components/invoice-designer/utils/constraintSolver.ts`
- `packages/billing/src/components/invoice-designer/utils/constraints.ts`
- `packages/billing/src/components/invoice-designer/utils/dropParentResolution.ts`
- `packages/billing/src/components/invoice-designer/utils/aspectRatio.ts`

## Decisions

- Prefer CSS-first semantics even if it means removing some legacy constraint behaviors.
- Drag-drop should be based on DOM geometry via dnd-kit collision detection (not custom math).
- Use CSS `aspect-ratio` for images. Avoid JS measurement loops.
- Scope decisions (2026-02-13):
  - Layout modes: flex + grid.
  - Resizing: enabled via CSS sizing props.
  - Snapping: edge + grid snapping as discrete insertion behavior.
  - Resize writes pixel values:
    - `updateNodeSize` rounds stored `node.size` to whole pixels and writes `node.style.width/height` as `Npx` strings (avoids float drift between size and CSS).

## Detailed Decisions

- Resizing:
  - Drag handles: `image`, `section`, `stack`.
  - No drag-resize for: `text`, `field`, `divider`, `totals`, `table`, `dynamic-table`.
  - No table column resizing.
  - Drag writes pixel sizing only (`px`). Non-px sizing can be entered via the property panel.
  - Flex main-axis resize should prefer `flex-basis` updates.
- Nesting allowlist:
  - Containers: `document`, `section`, `stack`, `grid` (if a node/type exists).
  - Leaves: `text`, `field`, `image`, `divider`, `totals`, `table`, `dynamic-table`.
- Drag-drop persistence:
  - Persist only `targetContainerId` + `insertionIndex` state changes. No coordinate-based persistence.
- "Basic snapping" definition:
  - Flex: snap to before/after sibling insertion indices.
  - Grid: snap to deterministic cell/index insertion based on grid tracks, not arbitrary pixel coordinates.

## Implemented

- 2026-02-13: `F001` CSS-first layout model
  - New node model fields in `packages/billing/src/components/invoice-designer/state/designerStore.ts`:
    - `node.layout`: `display: flex|grid` + flex/grid properties in CSS semantics.
    - `node.style`: width/height/min/max, flex item props, media props (aspectRatio/objectFit).
  - Removed constraint-solver state from the store snapshot and APIs (constraints are no longer part of `exportWorkspace()`).
  - Updated presets to accept legacy layout shapes while mapping them into CSS layout at insertion time:
    - `packages/billing/src/components/invoice-designer/constants/presets.ts`
    - `packages/billing/src/components/invoice-designer/state/designerStore.ts`
  - Deleted the constraints inspector tests and removed constraints UI from `packages/billing/src/components/invoice-designer/DesignerShell.tsx`.

- 2026-02-13: `F002` Layout/style -> DOM style mapping for canvas
  - New mapping helpers:
    - `packages/billing/src/components/invoice-designer/utils/cssLayout.ts`
  - Canvas applies mapped styles:
    - `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx`
      - outer node: uses `node.style` for width/height/min/max/flex props, still absolute-positioned during cutover
      - container child wrapper: uses `node.layout` to set `display`, flex/grid rules, `gap`, `padding`

- 2026-02-13: `F003` Flex row/column container layout
  - Children of flex/grid containers are now rendered as flow items (no absolute `top/left`), enabling native flex row/column layout:
    - `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx`
  - Child ordering uses `parent.childIds` when parent is `display:flex|grid` (stable authored order); legacy canvas containers remain position-sorted for now.

- 2026-02-13: `F004` Spacing controls (gap/padding + border via existing presets)
  - Updated Inspector layout panel to edit `gap` and `padding` (px) and flex alignment using CSS semantics:
    - `packages/billing/src/components/invoice-designer/DesignerShell.tsx`
  - `resolveFlexPadding` updated to support both legacy numeric padding and CSS `padding: \"Npx\"` during cutover:
    - `packages/billing/src/components/invoice-designer/utils/layout.ts`

- 2026-02-13: `F005` Flex alignment controls (justify/align)
  - Layout inspector edits `align-items` and `justify-content` for containers and writes CSS values into `node.layout`:
    - `packages/billing/src/components/invoice-designer/DesignerShell.tsx`
  - Canvas applies `justifyContent`/`alignItems` via the container style mapping:
    - `packages/billing/src/components/invoice-designer/utils/cssLayout.ts`
    - `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx`

- 2026-02-13: `F006` Item sizing controls (CSS width/height/min/max)
  - Added "Sizing (CSS)" inspector panel that edits `node.style` sizing strings (`width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight`):
    - `packages/billing/src/components/invoice-designer/DesignerShell.tsx`
  - Canvas already applies these values via `resolveNodeBoxStyle(node.style)` (no geometry math).

- 2026-02-13: `F007` Flex item controls (grow/shrink/basis)
  - Added "Flex Item" inspector panel shown when the selected node is inside a `display:flex` parent; edits `flexGrow`, `flexShrink`, and `flexBasis` on `node.style`:
    - `packages/billing/src/components/invoice-designer/DesignerShell.tsx`
  - Canvas already applies these values via `resolveNodeBoxStyle(node.style)`.

- 2026-02-13: `F008` Grid container mode (CSS grid)
  - Layout inspector now supports switching a container between `display:flex` and `display:grid`.
  - When in grid mode, inspector exposes `grid-template-columns`, `grid-template-rows`, and `grid-auto-flow` (gap/padding remain shared):
    - `packages/billing/src/components/invoice-designer/DesignerShell.tsx`
  - Canvas already renders grid containers via `resolveContainerLayoutStyle(node.layout)` + flow children rendering.

- 2026-02-13: `F009` dnd-kit collision detection + sortable plumbing (start of DOM-driven DnD)
  - Added dnd-kit collision detection strategy (pointer-within preferred; smallest rect under pointer approximates "deepest" target) with closest-center fallback and Always measuring:
    - `packages/billing/src/components/invoice-designer/DesignerShell.tsx`
  - Introduced sortable contexts for flow-layout containers (flex/grid) and `useSortable` for flow children, enabling DOM-measured ordering targets (no coordinate math for flow drags):
    - `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx`
  - Added store action to move/reparent nodes by `parentId + insertionIndex`, with allowlist enforcement and cycle prevention:
    - `packages/billing/src/components/invoice-designer/state/designerStore.ts`

- 2026-02-13: `F010` Reorder within container (sortable)
  - Dragging a flow-layout node (inside a `display:flex|grid` parent) now reorders by updating the parent's `childIds` using dnd-kit sortable `over` resolution (no position math).

- 2026-02-13: `F011` Cross-container moves (flow layout)
  - Flow-layout nodes can be dragged into another eligible container (or onto a child within it) and are reparented by updating `parentId` + `childIds` insertion index (DOM-measured `over` target).

- 2026-02-13: `F012` Nesting allowlist enforcement
  - Reparenting via drag-drop is validated with `canNestWithinParent(childType, parentType)` and cycle prevention (no dropping into descendants):
    - `packages/billing/src/components/invoice-designer/state/designerStore.ts`

- 2026-02-13: `F013` Drop indicators (DOM-derived)
  - Added a before/after insertion indicator line for flow-layout drags, derived from active/over DOM rect midpoints (no custom geometry solver):
    - `packages/billing/src/components/invoice-designer/DesignerShell.tsx`
    - `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx`
  - Container drop targets are still highlighted via `useDroppable().isOver` rings (DOM-measured).

- 2026-02-13: `F014` Invalid drop UX
  - Invalid drop targets now show a blocked visual state (red insertion line or red target ring) and a `not-allowed` cursor on the drag overlay; drops do not mutate state:
    - `packages/billing/src/components/invoice-designer/DesignerShell.tsx`
    - `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx`
  - Drop end emits an error toast-style banner via existing `dropFeedback` mechanism when invalid.

- 2026-02-13: `F015` Image aspect ratio + object-fit (CSS)
  - Media nodes (`image`, `logo`, `qr`) now render with CSS `aspect-ratio` (wrapper) and `object-fit` (img) support, with inspector controls writing `node.style.aspectRatio` and `node.style.objectFit`:
    - `packages/billing/src/components/invoice-designer/DesignerShell.tsx`
    - `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx`
  - New media nodes default to `objectFit: contain` (and `qr` defaults to `aspectRatio: 1 / 1`) without any JS measurement loops:
    - `packages/billing/src/components/invoice-designer/state/designerStore.ts`

- 2026-02-13: `F016` Resize handles (limited types)
  - Resize handles are now limited to `image/logo/qr` and container blocks (`section`, `container`) per PRD; resizing continues to write pixel `width/height` into `node.style` via `updateNodeSize` (no constraint solver):
    - `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx`

- 2026-02-13: `F016A` Property-panel sizing strings
  - Inspector "Sizing (CSS)" panel accepts arbitrary CSS strings (`%`, `rem`, `auto`, `calc(...)`, etc.) for size/min/max while drag-resize continues to write pixel values (px):
    - `packages/billing/src/components/invoice-designer/DesignerShell.tsx`
    - `packages/billing/src/components/invoice-designer/state/designerStore.ts`

- 2026-02-13: `F016B` Basic snapping (discrete insertion)
  - Flex parents now resolve insertion as before/after based on DOM rect midpoint along the main axis; grid uses the sortable `over` cell/index deterministically (no pixel snapping math):
    - `packages/billing/src/components/invoice-designer/DesignerShell.tsx`

- 2026-02-13: `F016C` Drag-drop persistence (no coordinates)
  - Dragging nodes no longer writes `position.x/y` during drop; drag-drop mutations are limited to `targetParentId + insertionIndex` updates (`parentId` + `childIds`):
    - `packages/billing/src/components/invoice-designer/DesignerShell.tsx`
    - `packages/billing/src/components/invoice-designer/state/designerStore.ts`

- 2026-02-13: `F017` Delete legacy geometry utilities
  - Deleted legacy solver + geometry/drop-parent modules and their tests (removed from runtime graph):
    - `packages/billing/src/components/invoice-designer/utils/constraintSolver.ts`
    - `packages/billing/src/components/invoice-designer/utils/constraints.ts`
    - `packages/billing/src/components/invoice-designer/utils/dropParentResolution.ts`
    - `packages/billing/src/components/invoice-designer/utils/aspectRatio.ts`
  - Simplified component insertion parent resolution in the designer to no longer depend on `dropParentResolution`.

- 2026-02-13: `F018` Reduce `utils/layout.ts`
  - `packages/billing/src/components/invoice-designer/utils/layout.ts` now contains only lightweight helpers (e.g. `resolveFlexPadding`) and type exports; alignment/geometry helpers were removed from this module.
  - Legacy drag-move guide/preview logic in `DesignerShell` was pared back (no coordinate-based preview updates).

- 2026-02-13: `F019` Persist CSS-like layout props in AST import/export
  - AST export writes CSS-like sizing, flex/grid container props, and media props (`aspectRatio`, `objectFit`) into `style.inline`:
    - `packages/billing/src/components/invoice-designer/ast/workspaceAst.ts`
  - AST import now hydrates `DesignerNode.style` and `DesignerNode.layout` from `style.inline` (with safe defaults for containers) so export -> import roundtrips CSS semantics.
  - Import mapping now treats top-level AST `section` nodes as designer `page` nodes (avoids a duplicate designer-only page wrapper).

- 2026-02-13: `F020` Preview uses authoritative renderer CSS semantics
  - Preview pipeline now passes only the `DesignerWorkspaceSnapshot` fields (removed stale `constraints` plumbing that no longer exists in the store snapshot):
    - `packages/billing/src/components/invoice-designer/DesignerVisualWorkspace.tsx`
  - Preview iframe `srcDoc` is now a full HTML document with `html, body { margin: 0; padding: 0; }` so the renderer-scoped CSS (`.invoice-template-root { ... }`) behaves the same inside the iframe as it does in the app / PDF (avoids default iframe body margins affecting layout).

- 2026-02-13: `F021` Audit imports of deleted geometry utilities
  - Confirmed no runtime imports/references remain for deleted modules:
    - `packages/billing/src/components/invoice-designer/utils/constraintSolver.ts`
    - `packages/billing/src/components/invoice-designer/utils/constraints.ts`
    - `packages/billing/src/components/invoice-designer/utils/dropParentResolution.ts`
    - `packages/billing/src/components/invoice-designer/utils/aspectRatio.ts`
  - Grep runbook:
    - `rg -n "utils/(constraintSolver|constraints|dropParentResolution|aspectRatio)" -S .`

## Remaining Design Choices

- Collision strategy and snapping thresholds are intentionally selected to minimize custom geometry logic:
  - Collision detection:
    - Use `pointerWithin` first (deepest eligible droppable under cursor).
    - Fallback to `closestCenter` if pointer is not within any droppable.
    - Configure measuring to keep DOM rects fresh during drag.
  - Sensors and overlay:
    - `PointerSensor` with activation distance (e.g. 6px).
    - `DragOverlay` to avoid layout reflow while dragging.
  - Sorting strategies:
    - Flex column: `verticalListSortingStrategy`
    - Flex row: `horizontalListSortingStrategy`
    - Grid: `rectSortingStrategy`
  - Snapping threshold behavior:
    - Flex uses midpoint rule on hovered rect (before/after) for insertion indicators.
    - Grid uses sortable `over` resolution directly (deterministic cell/index).

## Developer Notes (DnD + Nesting)

- Collision detection (why pointer-within first):
  - Implemented in `packages/billing/src/components/invoice-designer/DesignerShell.tsx` as `collisionDetection`.
  - We use `pointerWithin(args)` and return the collisions sorted by smallest droppable rect area first, as a practical proxy for "deepest nested droppable under the cursor".
  - If no droppable contains the pointer (fast drag / overlay edges), we fall back to `closestCenter(args)` so the drag never “loses” an `over` target.
  - Measuring is configured as `MeasuringStrategy.Always` on the `DndContext` to avoid stale droppable rects in nested flex/grid layouts.

- Droppable id conventions (how `over.id` maps back to a node):
  - Container drop zones use `id: \`droppable-\${node.id}\`` in `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx`.
  - Flow items use `useSortable({ id: node.id, ... })` (sortable id is the node id).
  - When debugging: if `over.id` starts with `droppable-`, it represents “drop into this container”; otherwise it is a sortable item id representing “drop relative to this item”.

- Nesting rules (authoritative allowlist):
  - Implemented in `packages/billing/src/components/invoice-designer/state/hierarchy.ts` and enforced via `canNestWithinParent(...)`.
  - Store actions that move/reparent nodes must validate:
    - type allowlist (`canNestWithinParent`)
    - cycle prevention (no dropping into descendants)
  - When adding a new node type, update `HIERARCHY_RULES` and ensure `allowedChildren` on container nodes matches the same intent.

- Where to tune UX:
  - Activation threshold (avoid accidental drags): `PointerSensor` `activationConstraint.distance` in `packages/billing/src/components/invoice-designer/DesignerShell.tsx`.
  - Over-target selection behavior: the `collisionDetection` callback in `packages/billing/src/components/invoice-designer/DesignerShell.tsx`.
  - Sort strategy selection (row/column/grid): `SortableContext` `strategy` selection in `packages/billing/src/components/invoice-designer/canvas/DesignCanvas.tsx`.

## Implementation Sketch (Non-binding)

- Introduce a single "layout props -> style props" mapping function used by:
  - designer canvas rendering
  - preview rendering (if different)
  - AST export (if relevant)
- Add dnd-kit:
  - sensors: pointer + keyboard (optional)
  - sortable contexts for sibling reordering
  - collision detection tuned for nested containers
- Enforce nesting rules in drop handler (reject invalid parent).
- Remove legacy util usage, then delete files.

## Useful Commands

- Search for legacy geometry imports:
  - `rg -n \"constraintSolver|constraints|dropParentResolution|aspectRatio\" packages/billing/src/components/invoice-designer`
- Run a single designer test under the server Vitest config:
  - `cd server && npx vitest run ../packages/billing/src/components/invoice-designer/utils/cssLayout.test.ts`
  - `cd server && npx vitest run ../packages/billing/src/components/invoice-designer/canvas/DesignCanvas.flexColumn.integration.test.tsx`
  - `cd server && npx vitest run ../packages/billing/src/components/invoice-designer/canvas/DesignCanvas.flexRow.integration.test.tsx`
  - `cd server && npx vitest run ../packages/billing/src/components/invoice-designer/canvas/DesignCanvas.spacing.integration.test.tsx`
  - `cd server && npx vitest run ../packages/billing/src/components/invoice-designer/canvas/DesignCanvas.alignment.integration.test.tsx`
  - `cd server && npx vitest run ../packages/billing/src/components/invoice-designer/canvas/DesignCanvas.sizing.integration.test.tsx`
  - `cd server && npx vitest run ../packages/billing/src/components/invoice-designer/canvas/DesignCanvas.flexItem.integration.test.tsx`
  - `cd server && npx vitest run ../packages/billing/src/components/invoice-designer/canvas/DesignCanvas.grid.integration.test.tsx`
  - `cd server && npx vitest run ../packages/billing/src/components/invoice-designer/utils/dndCollision.test.ts`
  - `cd server && npx vitest run ../packages/billing/src/components/invoice-designer/state/designerStore.flowDnd.test.ts`
  - `cd server && npx vitest run ../packages/billing/src/components/invoice-designer/utils/dropIndicator.test.ts`
  - `cd server && npx vitest run ../packages/billing/src/components/invoice-designer/canvas/DesignCanvas.mediaAspect.integration.test.tsx`

## Repo/Test Gotchas (Discovered 2026-02-13)

- Vitest + React tests were failing when `NODE_ENV=production` leaked into the test process (React test utils expect non-production builds).
  - Fix: `server/vitest.globalSetup.js` now forces `process.env.NODE_ENV = 'test'`.
- Package tests under `../packages/**` were not being discovered when running Vitest from `server/`.
  - Fix: `server/vitest.config.ts` now includes `../packages/**/*.{test,spec}.*` explicitly.
- Coverage provider version must match Vitest major version.
  - `server/` is currently on `vitest@3.2.4`, so `@vitest/coverage-v8@3.2.4` is added to `server/package.json` to avoid resolving the repo-root `@vitest/coverage-v8@4.x`.
- Running tests from repo root:
  - `npm run test:local` currently shells out to a system `dotenv` binary in some environments (CLI flag mismatch).
  - Reliable alternative: `cd server && npx vitest run <path-to-test>` (uses `server/vitest.globalSetup.js` to load `../.env.localtest`).

## Notes (Renderer Schema)

- Preview/renderer schema must allow the same safe CSS subset that the designer exports into `style.inline`.
  - Added support for: `flexDirection`, grid inline props (`gridTemplateColumns`, `gridTemplateRows`, `gridAutoFlow`), and media props (`aspectRatio`, `objectFit`) in:
    - `packages/billing/src/lib/invoice-template-ast/schema.ts`