resolutionflow/docs/plans/IMPLEMENTATION-PLAN-TREE-EDITOR-CANVAS.md

# Implementation Plan: Tree Editor Canvas Redesign

> **Date:** February 17, 2026
> **Scope:** Replace NodeList + NodeEditorModal + TreePreviewPanel in Flow mode with a visual canvas + inline card editing
> **Estimated Components:** 3 new files, 4 modified files
> **Phases:** 4 (sequential)
> **Branch:** `feature/tree-editor-canvas`

---

## Overview

Replace the current text-outline + modal + passive preview layout with a single-pane visual canvas where nodes are cards, editing is inline, and branches are visually connected. The tree IS the editor — no separate preview panel needed.

### Current State

The tree editor uses a text-outline metaphor:
- Nodes listed as indented rows with ASCII tree lines in `NodeList.tsx`
- Editing requires opening `NodeEditorModal.tsx` for each node (click row → modal opens → edit → Done → modal closes)
- Passive `TreePreviewPanel.tsx` takes 40% of space but offers no editing
- Adding nodes is a two-step picker-then-modal flow
- Options/branches are opaque — can't see where each branch leads without clicking into the node

### Target State (5 Outcomes)

1. Flow mode uses a full-width `TreeCanvas` editor; preview panel is removed from Flow mode
2. Node editing is inline in cards with local draft + ✓ save + ✕ cancel (no modal)
3. Branches are visually rendered with parent-child connector lines and horizontal splits
4. Metadata moves to a right slide-in panel, collapsed by default, opened from toolbar in Flow mode only
5. Code mode remains functionally unchanged (Monaco + preview split)

### Layout After Redesign

```
┌─────────────────────────────────────────────────────────┐
│ TOOLBAR: [Flow Name] [Undo] [Redo] [Metadata] [Save] [Publish] │
├─────────────────────────────────────────────────────────┤
│                                                          │
│   [START]                                               │
│      │                                                   │
│   ┌─────────────────────────────┐                       │
│   │ ? What type of issue?       │ ← Decision card       │
│   │  ↳ [A] Network Issues       │                       │
│   │  ↳ [B] App Errors           │                       │
│   └─────────────────────────────┘                       │
│        │                │                               │
│   [Network card]   [App Errors card]                    │
│        │                                                │
│   [Solution card]                                       │
│                                                          │
│   [+ Add node here]  ← contextual add buttons           │
│                                                          │
└─────────────────────────────────────────────────────────┘
```

---

## Reusable Code Inventory

Before building anything, confirm these existing pieces are available and understand their APIs:

| Asset | Location | How It's Used |
|-------|----------|---------------|
| `useTreeEditorStore()` | `store/treeEditorStore.ts` | All CRUD: `addNode`, `updateNode`, `deleteNode`, `duplicateNode`, `reorderNodes`, `selectNode`, `findNode`, `validationErrors` |
| `NodeFormDecision` | `components/tree-editor/NodeFormDecision.tsx` | Decision node fields (question, help_text, options) — will be rendered inline in card |
| `NodeFormAction` | `components/tree-editor/NodeFormAction.tsx` | Action node fields — will be rendered inline in card |
| `NodeFormResolution` | `components/tree-editor/NodeFormResolution.tsx` | Solution node fields — will be rendered inline in card |
| `DynamicArrayField` | `components/tree-editor/DynamicArrayField.tsx` | Reuse for options array in inline card |
| `NodePicker` | `components/tree-editor/NodePicker.tsx` | Reuse for option target selection (needs `allowCreate` prop added) |
| `TreeMetadataForm` | `components/tree-editor/TreeMetadataForm.tsx` | Wraps into MetadataSidePanel as-is |
| `cn()` | `@/lib/utils` | Tailwind class merging utility |
| Design tokens | `tailwind.config.js` | `bg-card`, `border-border`, `text-foreground`, `font-heading`, `font-label` |
| Brand colors | `tailwind.config.js` | Blue (decision), Yellow (action), Green (solution) |
| `buildSharedLinksMap()` | `components/tree-preview/TreePreviewPanel.tsx` | Shared node detection logic — extract and reuse for jump/reference indicators |

---

## Link Model & Rendering Rules

**IMPORTANT:** These rules govern how the canvas renders node connections. Read before implementing Phase 2.

### Tree-First Rendering

Render only structural children (nodes in `node.children[]`) with visual connector lines. Do NOT draw cross-canvas connector lines for shared/cross-linked nodes.

For links to non-child/shared targets (where `option.next_node_id` points to a node that is NOT a direct child), show a compact "jump/reference" indicator badge in the card content instead of a connector line.

### Decision Child Lane Ordering

When a decision node has children, order the horizontal child lanes:
1. **First:** Children whose `id` matches an `option.next_node_id` — ordered by option order
2. **Then:** Append any remaining unlinked children

### Action Next-Child Rule

- If a child's `id` matches the action node's `next_node_id`, treat it as the primary "next" lane
- If no child matches `next_node_id`, keep child visible but show the link as an "unbound reference" indicator

### Deletion Safety

**Before calling `deleteNode(nodeId)`**, the canvas must clean up all inbound references:
- Scan all decision nodes: clear any `options[].next_node_id` that equals the deleted node's ID
- Scan all action nodes: clear any `next_node_id` that equals the deleted node's ID

This prevents stale link references. The current `treeEditorStore.deleteNode()` does NOT do this cleanup — the canvas orchestration layer handles it.

---

## Phase 1: TreeCanvasNode Component (Core Inline Editor Card)

**File:** `frontend/src/components/tree-editor/TreeCanvasNode.tsx` (NEW)

### Props Interface

```typescript
interface TreeCanvasNodeProps {
  node: TreeStructure
  depth: number
  fromOption?: string           // Which parent option label leads here
  isExpanded: boolean
  isNew: boolean                // Show "Unsaved" badge, cancel triggers delete
  onToggleExpand: () => void
  onSave: (nodeId: string, updates: Partial<TreeStructure>) => void
  onCancelNew: (nodeId: string) => void  // Delete unsaved node
  onDelete: (nodeId: string) => void
  onDuplicate: (nodeId: string) => void
  onDragStart: (e: React.DragEvent, nodeId: string) => void
  onDragOver: (e: React.DragEvent) => void
  onDrop: (e: React.DragEvent) => void
}
```

### Card States

**Compact (default):**
- Node type badge/icon (Decision ?, Action ⚡, Solution ✓)
- Title text (question for decisions, title for action/solution)
- Option labels or option count for decisions
- Validation error badge (red dot if errors on this node)
- "Unsaved" badge (yellow, if `isNew`)
- Click anywhere on card → calls `onToggleExpand`

**Expanded (editing):**
- Local draft state: `const [draft, setDraft] = useState<Partial<TreeStructure>>(() => cloneNodeWithoutChildren(node))`
- Renders the appropriate existing form subcomponent inline:
  - Decision: `<NodeFormDecision node={draft} onUpdate={setDraftField} />`
  - Action: `<NodeFormAction node={draft} onUpdate={setDraftField} />`
  - Solution: `<NodeFormResolution node={draft} onUpdate={setDraftField} />`
- Header actions row:
  - ✓ Save button → calls `onSave(node.id, draft)` (strip children from draft before passing)
  - ✕ Cancel button → if `isNew`, calls `onCancelNew(node.id)`. Otherwise resets draft to node values and collapses
  - Duplicate button (hide if root)
  - Delete button (hide if root)
- Drag handle in header (hide if root)

### Card Styling

Aesthetic direction: "Precision engineering tool" — clean, minimal chrome, confident typography.

```
All cards:       bg-card border-border rounded-xl shadow-sm
Decision:        border-l-4 border-blue-500
Action:          border-l-4 border-yellow-500
Solution:        border-l-4 border-green-500
Expanded ring:   ring-1 ring-primary
Titles:          font-heading (Plus Jakarta Sans)
Type badges:     font-label (Outfit)
```

### Implementation Steps

1. Create `TreeCanvasNode.tsx` with compact view only (type badge, title, option count)
2. Add expanded view with local draft state and inline form rendering
3. Wire save/cancel/delete/duplicate actions
4. Add drag handle events
5. Add validation badge and unsaved badge
6. Style with brand tokens

### Verification

- Render a single card in isolation with mock data
- Confirm compact → expanded toggle works
- Confirm save commits draft (log output), cancel resets
- Confirm cancel on `isNew=true` calls `onCancelNew`
- Run `npm run build` — no TypeScript errors

---

## Phase 2: TreeCanvas Component (Layout & Orchestration)

**File:** `frontend/src/components/tree-editor/TreeCanvas.tsx` (NEW)

### Canvas State Model

```typescript
// Local UI state (NOT in Zustand store — canvas-only concerns)
const [expandedNodeIds, setExpandedNodeIds] = useState<Set<string>>(new Set())
const [newNodeIds, setNewNodeIds] = useState<Set<string>>(new Set())
const [pendingAddTarget, setPendingAddTarget] = useState<string | null>(null)
const [pendingLinkByNodeId, setPendingLinkByNodeId] = useState<Map<string, {
  parentId: string
  optionId?: string  // For decision option linking
}>>(new Map())
const [dragState, setDragState] = useState<{
  nodeId: string
  parentId: string
  index: number
} | null>(null)
```

**Single expanded card policy:** Only one card expanded at a time. When expanding a card, collapse the previously expanded one.

### Rendering

Recursive rendering of `treeStructure` from the store:
- Root at top, rendered as a "START" card
- Vertical flow downward
- When a decision node has multiple options with children, render children in horizontal lanes side-by-side
- Single-pane scrollable area (`overflow-auto`)
- Background: `bg-background` with subtle CSS radial dot grid pattern

### Connector Lines

Use CSS borders (not SVG) for connecting lines:
- **Parent-to-children trunk line:** `border-l border-border` extending down from parent
- **Horizontal fork line:** `border-t border-border` connecting sibling lane tops
- **Vertical stubs:** `border-l border-border` dropping into each child card

### Add-Node Flow

| Parent Type | Add Button Behavior |
|-------------|-------------------|
| Decision | Show `+ Add child` per option row (next to each option label) |
| Action | Show single `+ Add child` below the card |
| Solution | No add button (terminal node) |

- `+ Add` buttons use dashed border, appear on hover of parent card bottom edge
- Clicking `+ Add` sets `pendingAddTarget` → shows inline type picker (decision/action/solution buttons) at that position
- Selecting a type:
  1. Calls `addNode(parentId, type)` → gets new node ID
  2. Adds node ID to `newNodeIds`
  3. Adds entry to `pendingLinkByNodeId` (parent ID + option ID if from a decision option)
  4. Auto-expands the new node card
  5. Clears `pendingAddTarget`

### Save Behavior for New Child Nodes

When user clicks ✓ on a new node:
1. Call `updateNode(nodeId, draft)` to save content to store
2. If `pendingLinkByNodeId.has(nodeId)`:
   - Get the pending link info (`parentId`, `optionId`)
   - If `optionId` exists: update parent's `options[].next_node_id` to point to this node
   - If no `optionId` (action parent): update parent's `next_node_id` to point to this node
3. Remove from `newNodeIds`
4. Remove from `pendingLinkByNodeId`

### Cancel Behavior for New Nodes

When user clicks ✕ on a new (unsaved) node:
1. Call `deleteNode(nodeId)`
2. Remove from `newNodeIds`
3. Remove from `pendingLinkByNodeId`

### Delete Behavior (Any Node)

When user clicks delete on any node:
1. **Clean inbound references first** (see Link Model section above):
   - Walk the full tree and clear any `options[].next_node_id` or `next_node_id` matching the node being deleted
2. Then call `deleteNode(nodeId)`
3. Remove from `expandedNodeIds` if present

### Sibling Reorder

- Drag handle in card header (Phase 1 wired the events)
- Drop zones rendered between sibling cards (visual indicator line)
- On drop: call `reorderNodes(parentId, fromIndex, toIndex)`

### Selection Integration

- Click on a card calls `selectNode(nodeId)` in the store
- Watch `selectedNodeId` from store (including changes from `ValidationSummary` clicks):
  - Auto-expand the selected node's card
  - Scroll the card into view with `scrollIntoView({ behavior: 'smooth', block: 'nearest' })`

### Implementation Steps

1. Create `TreeCanvas.tsx` with recursive tree rendering (compact cards only, no editing)
2. Add CSS connector lines between parent and children
3. Add horizontal branching for decision nodes with multiple children
4. Add canvas state model (expandedNodeIds, newNodeIds, etc.)
5. Wire card expand/collapse with single-expanded-card policy
6. Add inline type picker and add-node flow with pending link tracking
7. Wire save/cancel with pending link resolution
8. Wire delete with inbound reference cleanup
9. Add drag-and-drop sibling reorder
10. Add selection sync (auto-expand + scroll into view)
11. Add grid background pattern
12. Style add buttons (dashed border, hover reveal)

### Verification

- Create a new tree → see canvas with root START card
- Click root → expands inline (no modal)
- Add 2 options, save → see branch lanes
- Add child from each option → pending link resolves on save
- Cancel a new node → node deleted, link cleaned up
- Delete a linked node → parent's reference cleared
- Drag reorder siblings
- Run `npm run build` — no TypeScript errors

---

## Phase 3: Form Refactoring + Layout Update

### 3A: Form Refactoring for Inline Reuse Safety

**Files to modify:**
- `frontend/src/components/tree-editor/NodeFormDecision.tsx`
- `frontend/src/components/tree-editor/NodePicker.tsx`

#### NodeFormDecision.tsx Changes

**Problem:** Currently, option reordering calls `reorderOptions()` directly on the store. In inline canvas editing, this would write to the store before the user clicks ✓ save (breaking the local draft model).

**Fix:** Change option reordering to mutate the local `node.options` array through the `onUpdate` callback instead of calling the store directly.

```typescript
// BEFORE (writes to store immediately):
const handleReorderOptions = (fromIndex: number, toIndex: number) => {
  reorderOptions(node.id, fromIndex, toIndex)
}

// AFTER (mutates local draft via onUpdate):
const handleReorderOptions = (fromIndex: number, toIndex: number) => {
  const newOptions = [...(node.options || [])]
  const [moved] = newOptions.splice(fromIndex, 1)
  newOptions.splice(toIndex, 0, moved)
  onUpdate({ options: newOptions })
}
```

**Keep modal compatibility:** This change is backward-compatible. In the legacy modal path, `onUpdate` already propagates to the store. In the canvas path, `onUpdate` updates the local draft.

#### NodePicker.tsx Changes

**Problem:** `NodePicker` currently has create-new-node options (`__create_decision__`, etc.) that call `addNode()` on the store. In canvas inline editing, this would create nodes as a side effect of browsing the picker during draft editing.

**Fix:** Add an `allowCreate` prop:

```typescript
interface NodePickerProps {
  // ... existing props
  allowCreate?: boolean  // default: true
}
```

- When `allowCreate={false}`, hide the "Create New" option group
- Pass `allowCreate={false}` from `TreeCanvasNode` expanded editing
- Pass `allowCreate={true}` (default) in legacy modal path

### 3B: Layout Update

**File:** `frontend/src/components/tree-editor/TreeEditorLayout.tsx`

#### Changes

```typescript
interface TreeEditorLayoutProps {
  isMobile?: boolean
  isMetadataOpen: boolean        // NEW
  onCloseMetadata: () => void    // NEW
}
```

**Flow mode (replace the 60/40 split):**

```
BEFORE:
  <div className="w-3/5">
    <TreeMetadataForm />
    <NodeList />
  </div>
  <div className="flex-1">
    <TreePreviewPanel />
  </div>

AFTER:
  <TreeCanvas />  (full width)
  <MetadataSidePanel isOpen={isMetadataOpen} onClose={onCloseMetadata} />  (overlay)
```

**Code mode:** Unchanged. Keep existing 60/40 Monaco + preview behavior.

### 3C: MetadataSidePanel Component

**File:** `frontend/src/components/tree-editor/MetadataSidePanel.tsx` (NEW)

Right-side slide-in panel (320px wide) that wraps `<TreeMetadataForm />`.

```typescript
interface MetadataSidePanelProps {
  isOpen: boolean
  onClose: () => void
}
```

Behavior:
- Slides in from right edge, overlays the canvas (does NOT resize it)
- Close triggers: panel close button, backdrop click, Escape key
- Uses existing overlay/backdrop pattern from other modals in the app
- Only rendered in Flow mode

### Implementation Steps

1. Refactor `NodeFormDecision.tsx` — option reorder through `onUpdate`
2. Add `allowCreate` prop to `NodePicker.tsx`
3. Create `MetadataSidePanel.tsx`
4. Update `TreeEditorLayout.tsx` — swap Flow mode layout, add metadata panel props
5. Verify legacy modal path still works (if still referenced anywhere)

### Verification

- Open tree editor in Flow mode → see full-width canvas (no 60/40 split)
- Open tree editor in Code mode → see unchanged Monaco + preview layout
- Click Metadata button → panel slides in from right, canvas doesn't resize
- Close metadata panel via close button, backdrop click, and Escape key
- Edit options in inline card → reorder does NOT write to store until ✓ save
- NodePicker in inline card → no "Create New" options shown
- Run `npm run build` — no TypeScript errors

---

## Phase 4: Toolbar Wiring + Exports

**File:** `frontend/src/pages/TreeEditorPage.tsx` (modify)

### Changes

1. Add local state: `const [isMetadataOpen, setIsMetadataOpen] = useState(false)`
2. Add "Metadata" toolbar button — visible in Flow mode only
3. Auto-close metadata panel when switching to Code mode:
   ```typescript
   // In mode switch handler:
   if (newMode === 'code') setIsMetadataOpen(false)
   ```
4. Pass metadata props into `TreeEditorLayout`:
   ```typescript
   <TreeEditorLayout
     isMetadataOpen={isMetadataOpen}
     onCloseMetadata={() => setIsMetadataOpen(false)}
   />
   ```
5. Keep all existing toolbar actions unchanged: undo/redo, save/publish, validate, analytics

**File:** `frontend/src/components/tree-editor/index.ts` (modify)

Add exports:
```typescript
export { TreeCanvas } from './TreeCanvas'
export { TreeCanvasNode } from './TreeCanvasNode'
export { MetadataSidePanel } from './MetadataSidePanel'
```

Keep all legacy exports (`NodeList`, `NodeEditorModal`, `TreePreviewPanel`) — they remain in the codebase but are no longer imported in the active Flow path.

### Implementation Steps

1. Add metadata panel state and toolbar button to `TreeEditorPage.tsx`
2. Add auto-close on Code mode switch
3. Pass props through to `TreeEditorLayout`
4. Update `index.ts` exports
5. Verify no dead imports remain

### Verification

- Flow mode toolbar shows "Metadata" button
- Code mode toolbar does NOT show "Metadata" button
- Click Metadata → panel opens. Switch to Code → panel auto-closes
- Undo/redo/save/publish/validate all still work
- Run `npm run build` — no TypeScript errors

---

## Critical Files Summary

| File | Action | Phase | Notes |
|------|--------|-------|-------|
| `TreeCanvasNode.tsx` | Create | 1 | Inline-editing card with local draft + commit model |
| `TreeCanvas.tsx` | Create | 2 | Main canvas orchestration with full state model |
| `MetadataSidePanel.tsx` | Create | 3 | 320px right slide-in overlay wrapping TreeMetadataForm |
| `NodeFormDecision.tsx` | Refactor | 3 | Option reorder through onUpdate (remove store write) |
| `NodePicker.tsx` | Refactor | 3 | Add `allowCreate` prop (default true) |
| `TreeEditorLayout.tsx` | Modify | 3 | Replace 60/40 split with full-width canvas + overlay |
| `TreeEditorPage.tsx` | Modify | 4 | Add metadata panel toggle, auto-close on Code switch |
| `index.ts` | Update | 4 | Export new components, keep legacy exports |
| `treeEditorStore.ts` | No changes | — | Store logic is solid as-is |
| `NodeList.tsx` | Keep (legacy) | — | Removed from active Flow path |
| `NodeEditorModal.tsx` | Keep (legacy) | — | Removed from active Flow path |
| `TreePreviewPanel.tsx` | Keep (legacy) | — | Removed from active Flow path |

---

## Assumptions & Defaults

- **Link rendering:** Tree-first (no full cross-canvas graph lines for shared targets)
- **Inline edit commit:** On checkmark save (local draft, cancel discards)
- **Metadata drawer:** Flow mode only
- **Expanded card policy:** One expanded card at a time
- **Legacy components:** Remain in repo, removed from active Flow path only
- **Connector lines:** CSS borders (not SVG — simpler, matches existing patterns)

---

## Testing

### Automated Tests

**Files:** `TreeCanvas.test.tsx`, `TreeCanvasNode.test.tsx`

| Test Case | What It Verifies |
|-----------|-----------------|
| Select node expands and scrolls card | Selection sync works |
| Inline save commits store updates | Draft → store pipeline works |
| Cancel on new node triggers deletion | Unsaved node cleanup works |
| Add child from decision option sets `next_node_id` on save | Pending link resolution works |
| Delete node clears inbound references | Reference cleanup works |
| Sibling drag reorder calls `reorderNodes` | Drag-and-drop wiring works |
| `allowCreate={false}` hides create options in NodePicker | Form safety works |
| Option reorder in inline card does NOT write to store | Draft isolation works |

Run: `npm run build && npm run test` (or targeted vitest files)

### Manual Acceptance Checklist

- [ ] Create a new tree — canvas shows root START card
- [ ] Click root card — expands inline with decision fields (no modal appears)
- [ ] Fill in question, add 2 options, click ✓ — saves inline, see branch lanes
- [ ] `+ Add child` buttons appear below each option
- [ ] Add a child node inline — verify parent link is set correctly
- [ ] Cancel a new unsaved node — confirm it is deleted from the tree
- [ ] Delete a node that is referenced by another — confirm references are cleaned
- [ ] Drag to reorder sibling nodes
- [ ] Open Metadata panel — edit metadata — close panel (button, backdrop, Escape)
- [ ] Validate and Publish — confirm tree saves correctly
- [ ] Switch Flow → Code mode — metadata panel auto-closes, Code mode works normally
- [ ] Switch Code → Flow mode — canvas renders correctly
- [ ] Run `npm run build` — no TypeScript errors
- [ ] Run `npm run test` — all tests pass

---

## Git Strategy

- Branch: `feature/tree-editor-canvas`
- One commit per phase (4 commits total)
- Commit messages:
  1. `feat: Add TreeCanvasNode inline editor card component`
  2. `feat: Add TreeCanvas layout with visual branching and orchestration`
  3. `refactor: Update forms for inline safety, add MetadataSidePanel, update layout`
  4. `feat: Wire toolbar metadata toggle and update exports`
- PR when all 4 phases pass `npm run build && npm run test`
- Include `Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>`

---

## Notes for Implementation

1. **Read existing code first:** Before creating any new file, read the files listed in the Reusable Code Inventory to understand current patterns and prop interfaces
2. **Follow existing patterns:** Match the component structure, Tailwind usage, and TypeScript conventions already in the tree-editor directory
3. **Dark mode:** All new components must support light/dark themes via existing Tailwind classes
4. **Keyboard navigation:** Support Escape to close metadata panel, Tab through form fields in expanded cards
5. **Loading states:** Canvas should handle the case where `treeStructure` is null (show empty state)
6. **No store changes:** The `treeEditorStore.ts` should NOT be modified. All new state is local to the canvas components
7. **Test each phase independently:** Each phase should leave the app in a buildable, testable state before moving to the next