OpenNoodl/dev-docs/tasks/phase-4-canvas-visualisation-views/CLINE-INSTRUCTIONS.md

Canvas Visualization Views - Cline Implementation Guide

Quick Start

READ THIS FIRST before starting any implementation work.

This project adds 7 visualization views to help users navigate complex Noodl projects. The views are divided into three types:

Type	What It Does	Examples
🗺️ Meta Views	Replace canvas with project-wide view	Topology Map, Trigger Chain
📋 Sidebar Panels	Open alongside canvas	X-Ray, Census
🎨 Canvas Overlays	Enhance canvas with persistent highlighting	Layers, Lineage, Impact

---

⚠️ CRITICAL: Prerequisites First!

DO NOT START VIEW IMPLEMENTATION until prerequisites are complete.

Prerequisite Order

PREREQ-001: Fix Webpack Caching ──────┐
                                      ├──► PREREQ-002 + PREREQ-003 (parallel)
                                      │           │
                                      │           ▼
                                      │    VIEW-000: Foundation
                                      │           │
                                      │           ▼
                                      │    First Views (002, 004)
                                      │           │
                                      │           ▼
                                      └──► PREREQ-004: Canvas Highlighting
                                                  │
                                                  ▼
                                           Canvas Overlays (005, 006, 007)
                                                  │
                                                  ▼
                                           Meta Views (001, 003)

PREREQ-001: Webpack 5 Caching Fix (CRITICAL)

Problem: Webpack 5 persistent caching prevents code changes from loading during development.

Location of issue documentation: dev-docs/tasks/phase-2/TASK-004B-componentsPanel-react-migration/STATUS-BLOCKED.md

Must fix before: Any development work

Potential solutions:

1. Disable persistent caching in dev mode (cache: false in webpack config)
2. Configure proper cache invalidation
3. Add cache-busting to development build

PREREQ-002: React 19 Debug Fixes

Problem: Legacy ReactDOM.render() calls crash debug infrastructure.

Files to fix:

nodegrapheditor.debuginspectors.js  → Replace ReactDOM.render() with createRoot()
commentlayer.ts                     → Reuse existing root instead of creating new one
TextStylePicker.jsx                 → Replace ReactDOM.render() with createRoot()

Pattern:

// Before (broken):
ReactDOM.render(<Component />, container);
ReactDOM.unmountComponentAtNode(container);

// After (correct):
if (!this.root) {
  this.root = createRoot(container);
}
this.root.render(<Component />);
// On dispose: this.root.unmount();

PREREQ-003: Document Canvas Overlay Pattern

Good news: CommentLayer already works as a React overlay on the canvas!

Task: Study and document how CommentLayer works:

1. How it renders React over the canvas
2. How it responds to pan/zoom
3. How it integrates with selection
4. Extract reusable patterns for other overlays

Key file: packages/noodl-editor/src/editor/src/views/nodegrapheditor/commentlayer.ts

PREREQ-004: Canvas Highlighting API

Needed for: VIEW-005 (Lineage), VIEW-006 (Impact), VIEW-007 (Layers)

Create API for persistent, multi-channel highlighting:

interface CanvasHighlightAPI {
  highlightNodes(nodeIds: string[], options: HighlightOptions): HighlightHandle;
  highlightConnections(connections: ConnectionRef[], options: HighlightOptions): HighlightHandle;
  highlightPath(path: PathDefinition, options: HighlightOptions): HighlightHandle;
  clearChannel(channel: string): void;
  clearAll(): void;
}

interface HighlightOptions {
  channel: string;      // 'lineage', 'impact', 'selection'
  color?: string;
  style?: 'solid' | 'pulse' | 'glow';
  persistent?: boolean; // Stay until dismissed
}

Key behavior: Highlights persist across component navigation!

---

Implementation Order

Phase 1: Foundation (After Prerequisites)

Start with VIEW-000 - this blocks everything else.

VIEW-000: Foundation & Shared Utilities
├── Graph traversal utilities
├── Cross-component resolution
├── View infrastructure (Meta Views, Overlays, Panels)
├── Navigation helpers
└── Debug infrastructure documentation

Phase 2: Quick Wins (Can parallelize)

These are low complexity and don't need canvas overlays:

VIEW-002: Component X-Ray (Sidebar Panel)
VIEW-004: Node Census (Sidebar Panel)

Phase 3: Canvas Overlays (After PREREQ-004)

VIEW-007: Semantic Layers (Canvas Overlay - simplest)
VIEW-005: Data Lineage (Canvas Overlay + panel)
VIEW-006: Impact Radar (Canvas Overlay + panel)

Phase 4: Meta Views (Most complex)

VIEW-001: Project Topology Map (Meta View)
VIEW-003: Trigger Chain Debugger (Meta View - needs runtime integration)

---

Key Architectural Decisions

1. Three View Types

🗺️ Meta Views replace the canvas entirely:

• Tab in header: [🗺️ Canvas] [📊 Topology] [⚡ Triggers]
• Full-screen project-wide or timeline view
• Component panel still exists but works differently

📋 Sidebar Panels open alongside canvas:

• Use existing SidebarModel (already React-ready)
• Click items to navigate/highlight on canvas

🎨 Canvas Overlays enhance the beloved canvas:

• Toggle buttons in canvas area: [Layers] [Lineage] [Impact]
• Based on CommentLayer pattern (already works!)
• Persistent highlighting until dismissed

2. Persistent Highlighting (Level 5000 Feature)

When user traces lineage:

1. Path lights up with glowing connections
2. User navigates to parent component
3. Path STAYS LIT on visible nodes
4. Indicator shows "Path continues in child: [Component Name]"
5. Click [×] to dismiss

3. Real-Time Updates

All views sync in real-time with:

• Canvas changes (add/remove nodes)
• Runtime state (live values)
• Preview interactions

4. State Persistence

View state persists across sessions:

• Active overlays
• Filter settings
• Traced paths

---

Key Files & Locations

Existing Code to Leverage

packages/noodl-editor/src/editor/src/
├── contexts/
│   └── NodeGraphContext/       # Already provides switchToComponent()
├── models/
│   ├── sidebar/sidebarmodel.tsx   # Already supports React panels
│   └── componentmodel.ts       # Component data
├── views/
│   └── nodegrapheditor/
│       ├── nodegrapheditor.ts  # Main canvas (2000+ lines)
│       └── commentlayer.ts     # TEMPLATE for overlays!

New Code Locations

packages/noodl-editor/src/editor/src/
├── utils/
│   └── graphAnalysis/          # VIEW-000 utilities
│       ├── traversal.ts
│       ├── crossComponent.ts
│       ├── categorization.ts
│       └── duplicateDetection.ts
├── views/
│   ├── MetaViews/              # Meta view tab system
│   │   ├── MetaViewTabs.tsx
│   │   ├── TopologyMapView/
│   │   └── TriggerChainView/
│   ├── CanvasOverlays/         # Canvas overlay system
│   │   ├── CanvasOverlayManager.tsx
│   │   ├── LayersOverlay/
│   │   ├── LineageOverlay/
│   │   └── ImpactOverlay/
│   └── panels/                 # Sidebar panels (existing pattern)
│       ├── XRayPanel/
│       └── CensusPanel/

---

Testing Strategy

For Each View

1. Unit tests for graph analysis utilities
2. Integration tests for view rendering
3. Manual testing with complex real projects

Test Projects

Use projects with:

• Deep component nesting (5+ levels)
• Cross-component data flow
• Duplicate node names
• Complex event chains

---

Common Patterns

Registering a Sidebar Panel

SidebarModel.instance.register({
  id: 'xray',
  name: 'X-Ray',
  icon: IconName.Search,
  panel: ComponentXRayPanel  // React component
});

Navigating to Canvas

import { NodeGraphContextTmp } from '@noodl-contexts/NodeGraphContext';

// Switch to component
NodeGraphContextTmp.switchToComponent(component, {
  node: nodeId,           // Optional: select specific node
  zoomToFit: true
});

Accessing Project Data

import { ProjectModel } from '@noodl-models/projectmodel';

// Get all components
ProjectModel.instance.getComponents();

// Get component by name
ProjectModel.instance.getComponentWithName('/MyComponent');

// Get current component
nodeGraph.activeComponent;

---

Troubleshooting

"Changes not loading"

→ Webpack caching issue. See PREREQ-001.

"ReactDOM.render is not a function"

→ React 19 migration incomplete. See PREREQ-002.

"Debug inspector crashes"

→ Legacy React patterns in debug code. See PREREQ-002.

"Canvas overlay not responding to zoom"

→ Check CommentLayer pattern for transform handling.

---

Success Criteria

For the complete project:

• Prerequisites resolved (webpack, React 19, overlay pattern, highlighting API)
• VIEW-000 foundation complete and tested
• All 7 views implemented and functional
• Persistent highlighting works across component navigation
• Real-time updates working
• State persists across sessions
• No regressions in existing canvas functionality
• Performance acceptable with large projects (100+ components)

---

Reference Documents

• README.md - Project overview and architecture
• VIEW-PREREQ-modernization-roadmap.md - Prerequisites detail
• VIEW-000-foundation/README.md - Foundation implementation
• Individual VIEW-XXX folders - Detailed specs for each view

---

Questions?

If you encounter blockers or need clarification:

1. Check the individual VIEW-XXX README for detailed specs
2. Reference existing patterns in codebase (CommentLayer, SidebarModel)
3. Document discoveries in a LEARNINGS.md file for future reference