laminark 0.1.0 → 2.21.7

package/plugin/ui/graph.js

@@ -31,8 +31,17 @@ const ENTITY_STYLES = {
   Reference: { color: '#f0883e', shape: 'hexagon' },
 };
 
-// Pathfinder highlight color
-var PATHFINDER_COLOR = '#f0883e';
+// Waypoint type colors for path overlay
+var WAYPOINT_TYPE_COLORS = {
+  error: '#f85149',
+  attempt: '#d29922',
+  failure: '#f0883e',
+  success: '#3fb950',
+  pivot: '#a371f7',
+  revert: '#79c0ff',
+  discovery: '#58a6ff',
+  resolution: '#3fb950',
+};
 
 // Relationship type colors for edge coloring
 var EDGE_TYPE_COLORS = {
@@ -188,17 +197,10 @@ var hiddenEdgeLabelTypes = new Set(
   JSON.parse(localStorage.getItem('laminark-hidden-edge-types') || '[]')
 );
 
-// Pathfinder state
-var pathfinderActive = false;
-var pathfinderSelection = []; // Max 2 node IDs: [startId, endId]
-var pathfinderResult = null; // { nodeIds: Set, edgeIds: Set, path: [{nodeId, edgeId}] }
-var pathfinderInfoEl = null;
-
-// Graph freeze state (suppresses SSE-driven refreshes)
-var graphFrozen = false;
-var graphStale = false;
-var syncBtnEl = null;
-var freezeBtnEl = null;
+// Path overlay state
+var pathOverlayGroup = null;
+var pathOverlayVisible = localStorage.getItem('laminark-path-overlay') !== 'false';
+var pathData = []; // Array of { id, status, triggerSummary, waypoints: [{id, type, summary, nodeId?}] }
 
 // ---------------------------------------------------------------------------
 // initGraph
@@ -250,6 +252,7 @@ function initGraph(containerId) {
   // Layer groups in paint order (back to front)
   edgesGroup = svgG.append('g').attr('class', 'edges-group');
   edgeLabelsGroup = svgG.append('g').attr('class', 'edge-labels-group');
+  pathOverlayGroup = svgG.append('g').attr('class', 'path-overlay-group');
   nodesGroup = svgG.append('g').attr('class', 'nodes-group');
   nodeLabelsGroup = svgG.append('g').attr('class', 'node-labels-group');
 
@@ -260,16 +263,16 @@ function initGraph(containerId) {
       svgG.attr('transform', event.transform);
       currentZoom = event.transform.k;
       updateLevelOfDetail();
+      renderPathOverlay();
     });
   svg.call(zoomBehavior);
 
-  // Background click: deselect + hide detail panel + clear pathfinder
+  // Background click: deselect + hide detail panel
   svg.on('click', function (event) {
     if (event.target === svg.node() || event.target.closest('.graph-zoom-group') === svgG.node() && !event.target.closest('.node-group')) {
       hideDetailPanel();
       selectedNodeId = null;
       if (nodesGroup) nodesGroup.selectAll('.node-group').classed('selected', false);
-      clearPathfinder();
     }
   });
 
@@ -302,9 +305,7 @@ function initGraph(containerId) {
 
   initContextMenu();
   initEdgeLabelToggle();
-  initPathfinderToggle();
-  initFreezeButton();
-  initSyncButton();
+  initPathOverlayToggle();
 
   // Create tooltip element
   tooltipEl = document.createElement('div');
@@ -353,11 +354,8 @@ function createSimulation() {
   var width = containerEl ? containerEl.clientWidth : 800;
   var height = containerEl ? containerEl.clientHeight : 600;
 
-  var simNodeIds = new Set(nodeData.filter(function (d) { return !d.hidden; }).map(function (d) { return d.id; }));
   var visibleEdges = edgeData.filter(function (d) {
-    var srcId = typeof d.source === 'object' ? d.source.id : d.source;
-    var tgtId = typeof d.target === 'object' ? d.target.id : d.target;
-    return simNodeIds.has(srcId) && simNodeIds.has(tgtId);
+    return !d.source.hidden && !d.target.hidden;
   });
 
   // Degree-scaled repulsion: more links = stronger push away
@@ -597,12 +595,6 @@ function dragEnded(event, d) {
 // ---------------------------------------------------------------------------
 
 async function handleNodeClick(d) {
-  // Pathfinder mode: collect start/end nodes
-  if (pathfinderActive) {
-    handlePathfinderClick(d);
-    return;
-  }
-
   selectedNodeId = d.id;
   if (nodesGroup) {
     nodesGroup.selectAll('.node-group').classed('selected', function (n) { return n.id === d.id; });
@@ -666,15 +658,6 @@ async function loadGraphData(filters) {
     return { nodeCount: nodeData.length, edgeCount: edgeData.length };
   }
 
-  // Don't reload while graph is frozen (manual pause or pathfinder result).
-  // Data will be fetched when the user unfreezes or clicks sync.
-  if (graphFrozen) {
-    console.log('[laminark:graph] Skipping loadGraphData (graph frozen)');
-    graphStale = true;
-    updateSyncButton();
-    return { nodeCount: nodeData.length, edgeCount: edgeData.length };
-  }
-
   var data;
   if (window.laminarkApp && window.laminarkApp.fetchGraphData) {
     data = await window.laminarkApp.fetchGraphData(filters);
@@ -699,11 +682,11 @@ async function loadGraphData(filters) {
     edgeData = [];
     renderGraph();
     updateGraphStats(0, 0);
-    showGraphEmptyState();
+    showEmptyState();
     return { nodeCount: 0, edgeCount: 0 };
   }
 
-  hideGraphEmptyState();
+  hideEmptyState();
 
   // Build data arrays
   nodeData = data.nodes.map(function (node) {
@@ -744,6 +727,11 @@ async function loadGraphData(filters) {
     setTimeout(function () { fitToView(); }, 800);
   }
 
+  // Load path overlay after graph data
+  if (pathOverlayVisible) {
+    setTimeout(function () { loadPathOverlay(); }, 1000);
+  }
+
   var counts = { nodeCount: data.nodes.length, edgeCount: data.edges.length };
   updateGraphStats(counts.nodeCount, counts.edgeCount);
   console.log('[laminark:graph] Loaded', counts.nodeCount, 'nodes,', counts.edgeCount, 'edges');
@@ -769,7 +757,7 @@ function addNode(nodeDataIn) {
       createdAt: nodeDataIn.createdAt,
       hidden: false,
     });
-    hideGraphEmptyState();
+    hideEmptyState();
   }
 
   renderGraph();
@@ -816,7 +804,7 @@ function removeElements(ids) {
   renderGraph();
   updateGraphStatsFromData();
 
-  if (nodeData.length === 0) showGraphEmptyState();
+  if (nodeData.length === 0) showEmptyState();
 }
 
 // ---------------------------------------------------------------------------
@@ -979,7 +967,7 @@ function updateFilterCounts() {
 // Empty state
 // ---------------------------------------------------------------------------
 
-function showGraphEmptyState() {
+function showEmptyState() {
   if (!containerEl) return;
   var existing = containerEl.querySelector('.graph-empty-state');
   if (existing) { existing.style.display = ''; return; }
@@ -990,7 +978,7 @@ function showGraphEmptyState() {
   containerEl.appendChild(msg);
 }
 
-function hideGraphEmptyState() {
+function hideEmptyState() {
   if (!containerEl) return;
   var existing = containerEl.querySelector('.graph-empty-state');
   if (existing) existing.style.display = 'none';
@@ -1191,13 +1179,9 @@ function initEdgeLabelToggle() {
     dropdown.appendChild(row);
   });
 
-  // Insert dropdown after button — wrap btn in a relative container
-  // so the dropdown positions correctly without breaking the toolbar's absolute positioning
-  var btnWrapper = document.createElement('div');
-  btnWrapper.style.position = 'relative';
-  btn.parentElement.insertBefore(btnWrapper, btn);
-  btnWrapper.appendChild(btn);
-  btnWrapper.appendChild(dropdown);
+  // Insert dropdown after button
+  btn.parentElement.style.position = 'relative';
+  btn.insertAdjacentElement('afterend', dropdown);
 
   // Toggle dropdown on click
   btn.addEventListener('click', function (e) {
@@ -1423,12 +1407,6 @@ function queueBatchUpdate(update) {
   batchFlushTimer = setTimeout(flushBatchUpdates, BATCH_DELAY_MS);
 }
 
-function clearBatchQueue() {
-  if (batchFlushTimer) clearTimeout(batchFlushTimer);
-  batchFlushTimer = null;
-  batchQueue = [];
-}
-
 function flushBatchUpdates() {
   if (!svg || batchQueue.length === 0) return;
 
@@ -1472,14 +1450,7 @@ function flushBatchUpdates() {
   batchFlushTimer = null;
 
   if (newNodes > 0 || newEdges > 0) {
-    // Suppress rendering while graph is frozen
-    if (graphFrozen) {
-      console.log('[laminark:graph] Batch data accumulated but render suppressed (graph frozen)');
-      graphStale = true;
-      updateSyncButton();
-      return;
-    }
-    hideGraphEmptyState();
+    hideEmptyState();
     renderGraph();
     if (!isStaticLayout && simulation) simulation.alpha(0.3).restart();
     console.log('[laminark:graph] Batch update: added ' + newNodes + ' nodes, ' + newEdges + ' edges');
@@ -1641,7 +1612,7 @@ function updateBreadcrumbs() {
 // ---------------------------------------------------------------------------
 
 function setLayout(layoutName) {
-  var validLayouts = ['clustered', 'hierarchical', 'concentric', 'communities', 'detangle'];
+  var validLayouts = ['clustered', 'hierarchical', 'concentric', 'communities'];
   if (validLayouts.indexOf(layoutName) === -1) return;
 
   var previousLayout = currentLayout;
@@ -1664,8 +1635,6 @@ function setLayout(layoutName) {
       applyHierarchicalLayout();
     } else if (layoutName === 'concentric') {
       applyConcentricLayout();
-    } else if (layoutName === 'detangle') {
-      applyDetangleLayout();
     } else {
       applyClusteredLayout();
     }
@@ -1877,119 +1846,6 @@ function applyCommunitiesLayout() {
     });
 }
 
-// ---------------------------------------------------------------------------
-// Detangle layout — minimizes edge crossings via custom force
-// ---------------------------------------------------------------------------
-
-/**
- * Tests whether line segment (p1→p2) crosses (p3→p4).
- * Returns true if the segments properly intersect.
- */
-function segmentsIntersect(p1x, p1y, p2x, p2y, p3x, p3y, p4x, p4y) {
-  var d1x = p2x - p1x, d1y = p2y - p1y;
-  var d2x = p4x - p3x, d2y = p4y - p3y;
-  var cross = d1x * d2y - d1y * d2x;
-  if (Math.abs(cross) < 1e-10) return false;
-  var t = ((p3x - p1x) * d2y - (p3y - p1y) * d2x) / cross;
-  var u = ((p3x - p1x) * d1y - (p3y - p1y) * d1x) / cross;
-  return t > 0.01 && t < 0.99 && u > 0.01 && u < 0.99;
-}
-
-/**
- * Custom D3 force that detects edge crossings and pushes nodes apart
- * to untangle the graph. Runs O(E^2) per tick — fine for <1000 edges.
- */
-function forceUncross(edges) {
-  var strength = 8;
-  var nodes;
-
-  function force(alpha) {
-    if (!nodes || edges.length < 2) return;
-    var effectiveStrength = strength * alpha;
-
-    for (var i = 0; i < edges.length; i++) {
-      var e1 = edges[i];
-      var s1 = e1.source, t1 = e1.target;
-      if (!s1 || !t1 || s1.x == null || t1.x == null) continue;
-
-      for (var j = i + 1; j < edges.length; j++) {
-        var e2 = edges[j];
-        var s2 = e2.source, t2 = e2.target;
-        if (!s2 || !t2 || s2.x == null || t2.x == null) continue;
-
-        // Skip if edges share a node
-        if (s1 === s2 || s1 === t2 || t1 === s2 || t1 === t2) continue;
-
-        if (segmentsIntersect(s1.x, s1.y, t1.x, t1.y, s2.x, s2.y, t2.x, t2.y)) {
-          // Push the midpoints of the two edges apart
-          var m1x = (s1.x + t1.x) / 2, m1y = (s1.y + t1.y) / 2;
-          var m2x = (s2.x + t2.x) / 2, m2y = (s2.y + t2.y) / 2;
-          var dx = m1x - m2x, dy = m1y - m2y;
-          var dist = Math.sqrt(dx * dx + dy * dy) || 1;
-          var push = effectiveStrength / dist;
-          var fx = dx * push, fy = dy * push;
-
-          // Apply to non-fixed nodes of edge 1 (push away from edge 2)
-          if (s1.fx == null) { s1.vx += fx * 0.5; s1.vy += fy * 0.5; }
-          if (t1.fx == null) { t1.vx += fx * 0.5; t1.vy += fy * 0.5; }
-          // Apply to non-fixed nodes of edge 2 (push opposite direction)
-          if (s2.fx == null) { s2.vx -= fx * 0.5; s2.vy -= fy * 0.5; }
-          if (t2.fx == null) { t2.vx -= fx * 0.5; t2.vy -= fy * 0.5; }
-        }
-      }
-    }
-  }
-
-  force.initialize = function (_nodes) { nodes = _nodes; };
-  force.strength = function (s) { if (!arguments.length) return strength; strength = s; return force; };
-
-  return force;
-}
-
-function applyDetangleLayout() {
-  isStaticLayout = false;
-  nodeData.forEach(function (d) { d.fx = null; d.fy = null; });
-
-  // Let renderGraph create the standard simulation first (it calls createSimulation)
-  renderGraph();
-
-  // Now enhance the existing simulation with the uncross force
-  if (simulation) {
-    var simNodeIds = new Set(nodeData.filter(function (d) { return !d.hidden; }).map(function (d) { return d.id; }));
-    var visibleEdges = edgeData.filter(function (d) {
-      var srcId = typeof d.source === 'object' ? d.source.id : d.source;
-      var tgtId = typeof d.target === 'object' ? d.target.id : d.target;
-      return simNodeIds.has(srcId) && simNodeIds.has(tgtId);
-    });
-
-    var width = containerEl ? containerEl.clientWidth : 800;
-    var height = containerEl ? containerEl.clientHeight : 600;
-
-    // Widen link distances and strengthen repulsion for more spacing
-    simulation
-      .force('link', d3.forceLink(visibleEdges)
-        .id(function (d) { return d.id; })
-        .distance(function (d) {
-          var srcDeg = (typeof d.source === 'object' ? d.source._degree : 0) || 0;
-          var tgtDeg = (typeof d.target === 'object' ? d.target._degree : 0) || 0;
-          return 140 + Math.sqrt(srcDeg + tgtDeg) * 25;
-        })
-        .strength(0.8))
-      .force('collide', d3.forceCollide().radius(function (d) {
-        return getNodeSize(d) + 20;
-      }).strength(1))
-      .force('uncross', forceUncross(visibleEdges).strength(12))
-      .force('x', d3.forceX(width / 2).strength(0.02))
-      .force('y', d3.forceY(height / 2).strength(0.02))
-      .alphaDecay(0.01)
-      .velocityDecay(0.4)
-      .alpha(1)
-      .restart();
-  }
-
-  setTimeout(function () { fitToView(); }, 1500);
-}
-
 function initLayoutSelector() {
   var btns = document.querySelectorAll('.layout-btn');
   btns.forEach(function (btn) {
@@ -2242,265 +2098,182 @@ if (document.readyState === 'loading') {
 }
 
 // ---------------------------------------------------------------------------
-// Freeze button (pauses SSE-driven refreshes) + Sync button (reload stale data)
+// Path overlay
 // ---------------------------------------------------------------------------
 
-function initFreezeButton() {
-  // Add freeze toggle to the toolbar (toolbar is sibling of containerEl, not inside it)
-  var graphArea = containerEl ? containerEl.parentElement : null;
-  var toolbar = graphArea ? graphArea.querySelector('.graph-toolbar') : null;
-  if (!toolbar) return;
-
-  freezeBtnEl = document.createElement('button');
-  freezeBtnEl.className = 'graph-freeze-btn';
-  freezeBtnEl.title = 'Pause live updates';
-  freezeBtnEl.innerHTML = '<svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor"><path d="M5.5 3.5A1.5 1.5 0 0 1 7 5v6a1.5 1.5 0 0 1-3 0V5a1.5 1.5 0 0 1 1.5-1.5zm5 0A1.5 1.5 0 0 1 12 5v6a1.5 1.5 0 0 1-3 0V5a1.5 1.5 0 0 1 1.5-1.5z"/></svg>';
-  freezeBtnEl.addEventListener('click', function () {
-    toggleGraphFrozen();
-  });
-  // Insert before the fit button (last in toolbar)
-  var fitBtn = toolbar.querySelector('.fit-btn');
-  if (fitBtn) {
-    toolbar.insertBefore(freezeBtnEl, fitBtn);
-  } else {
-    toolbar.appendChild(freezeBtnEl);
-  }
-}
+async function loadPathOverlay() {
+  if (!svg || !pathOverlayVisible) return;
 
-function toggleGraphFrozen() {
-  graphFrozen = !graphFrozen;
-  updateFreezeButton();
+  try {
+    var params = new URLSearchParams();
+    if (window.laminarkState && window.laminarkState.currentProject) {
+      params.set('project', window.laminarkState.currentProject);
+    }
+    params.set('limit', '10');
+    var url = '/api/paths' + (params.toString() ? '?' + params.toString() : '');
+    var res = await fetch(url);
+    if (!res.ok) throw new Error('HTTP ' + res.status);
+    var data = await res.json();
+    pathData = (data.paths || []).filter(function(p) { return p.status === 'active' || p.status === 'resolved'; });
+
+    // For each path, fetch waypoints
+    for (var i = 0; i < pathData.length; i++) {
+      try {
+        var detailRes = await fetch('/api/paths/' + encodeURIComponent(pathData[i].id));
+        if (detailRes.ok) {
+          var detail = await detailRes.json();
+          pathData[i].waypoints = detail.waypoints || [];
+        }
+      } catch (e) { pathData[i].waypoints = []; }
+    }
 
-  if (!graphFrozen && graphStale) {
-    // Unfreeze: reload pending data
-    graphStale = false;
-    clearPathfinder();
-    loadGraphData();
-    updateSyncButton();
+    renderPathOverlay();
+  } catch (err) {
+    console.error('[laminark:graph] Failed to load path overlay:', err);
   }
 }
 
-function setGraphFrozen(frozen) {
-  graphFrozen = frozen;
-  updateFreezeButton();
-}
-
-function updateFreezeButton() {
-  if (!freezeBtnEl) return;
-  freezeBtnEl.classList.toggle('active', graphFrozen);
-  freezeBtnEl.title = graphFrozen ? 'Resume live updates' : 'Pause live updates';
-  // Swap icon: pause when live, play when frozen
-  if (graphFrozen) {
-    freezeBtnEl.innerHTML = '<svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor"><path d="M4 2l10 6-10 6V2z"/></svg>';
-  } else {
-    freezeBtnEl.innerHTML = '<svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor"><path d="M5.5 3.5A1.5 1.5 0 0 1 7 5v6a1.5 1.5 0 0 1-3 0V5a1.5 1.5 0 0 1 1.5-1.5zm5 0A1.5 1.5 0 0 1 12 5v6a1.5 1.5 0 0 1-3 0V5a1.5 1.5 0 0 1 1.5-1.5z"/></svg>';
+function renderPathOverlay() {
+  if (!pathOverlayGroup || !pathOverlayVisible) {
+    if (pathOverlayGroup) pathOverlayGroup.style('display', 'none');
+    return;
   }
-}
+  pathOverlayGroup.style('display', null);
+  pathOverlayGroup.selectAll('*').remove();
 
-function initSyncButton() {
-  if (!containerEl) return;
-  syncBtnEl = document.createElement('button');
-  syncBtnEl.className = 'graph-sync-btn hidden';
-  syncBtnEl.innerHTML = '<svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor"><path d="M1.5 8a6.5 6.5 0 0 1 11.25-4.4l-1.54 1.54A.5.5 0 0 0 11.56 6H15.5a.5.5 0 0 0 .5-.5V1.56a.5.5 0 0 0-.85-.35L13.6 2.76A8 8 0 0 0 0 8h1.5zm13 0a6.5 6.5 0 0 1-11.25 4.4l1.54-1.54A.5.5 0 0 0 4.44 10H.5a.5.5 0 0 0-.5.5v3.94a.5.5 0 0 0 .85.35l1.55-1.55A8 8 0 0 0 16 8h-1.5z"/></svg> Sync';
-  syncBtnEl.addEventListener('click', function () {
-    graphStale = false;
-    graphFrozen = false;
-    updateFreezeButton();
-    clearPathfinder();
-    loadGraphData();
-    updateSyncButton();
-  });
-  containerEl.appendChild(syncBtnEl);
-}
+  if (pathData.length === 0) return;
 
-function updateSyncButton() {
-  if (!syncBtnEl) return;
-  if (graphStale && graphFrozen) {
-    syncBtnEl.classList.remove('hidden');
-    syncBtnEl.classList.add('stale');
-  } else {
-    syncBtnEl.classList.add('hidden');
-    syncBtnEl.classList.remove('stale');
-  }
-}
+  var width = containerEl ? containerEl.clientWidth : 800;
+  var height = containerEl ? containerEl.clientHeight : 600;
 
-// ---------------------------------------------------------------------------
-// Pathfinder: shortest path between two nodes
-// ---------------------------------------------------------------------------
+  // Get current transform to position in screen space
+  var transform = d3.zoomTransform(svg.node());
 
-function initPathfinderToggle() {
-  var btn = document.getElementById('paths-toggle-btn');
-  if (!btn) return;
+  pathData.forEach(function(path, pathIndex) {
+    if (!path.waypoints || path.waypoints.length === 0) return;
 
-  btn.classList.toggle('active', pathfinderActive);
+    var pathGroup = pathOverlayGroup.append('g')
+      .attr('class', 'path-trail')
+      .attr('data-path-id', path.id);
 
-  btn.addEventListener('click', function () {
-    pathfinderActive = !pathfinderActive;
-    btn.classList.toggle('active', pathfinderActive);
-    if (!pathfinderActive) {
-      clearPathfinder();
-    }
-  });
-}
+    // Position waypoints evenly spaced along a line
+    var waypoints = path.waypoints;
+    var margin = 80;
+    var yBase = (height - 60) / transform.k - transform.y / transform.k;
+    var xStart = (-transform.x / transform.k) + margin / transform.k;
+    var xEnd = (-transform.x / transform.k) + (width - margin) / transform.k;
+    var spacing = waypoints.length > 1 ? (xEnd - xStart) / (waypoints.length - 1) : 0;
 
-function handlePathfinderClick(d) {
-  if (pathfinderSelection.length === 0) {
-    // First node selected
-    pathfinderSelection = [d.id];
-    pathfinderResult = null;
-    clearPathfinderVisuals();
-    if (nodesGroup) {
-      nodesGroup.selectAll('.node-group')
-        .classed('pathfinder-start', function (n) { return n.id === d.id; })
-        .classed('pathfinder-end', false);
-    }
-    updatePathfinderInfo('Select target node...');
-  } else if (pathfinderSelection.length === 1) {
-    if (pathfinderSelection[0] === d.id) return; // Same node
-    pathfinderSelection.push(d.id);
-
-    // Mark end node
-    if (nodesGroup) {
-      nodesGroup.selectAll('.node-group')
-        .classed('pathfinder-end', function (n) { return n.id === d.id; });
-    }
+    var points = waypoints.map(function(wp, i) {
+      return { x: xStart + i * spacing, y: yBase + pathIndex * 40 / transform.k };
+    });
 
-    // Run BFS
-    var result = bfsShortestPath(pathfinderSelection[0], pathfinderSelection[1]);
-    if (result) {
-      pathfinderResult = result;
-      visualizePathfinderResult(result);
-      // Auto-freeze to protect the path visualization
-      setGraphFrozen(true);
-    } else {
-      updatePathfinderInfo('No path found between these nodes');
+    // Draw connecting line (animated dashed)
+    if (points.length > 1) {
+      var lineGen = d3.line()
+        .x(function(d) { return d.x; })
+        .y(function(d) { return d.y; })
+        .curve(d3.curveCatmullRom.alpha(0.5));
+
+      pathGroup.append('path')
+        .attr('class', 'path-line' + (path.status === 'active' ? ' path-line-active' : ''))
+        .attr('d', lineGen(points))
+        .attr('fill', 'none')
+        .attr('stroke', path.status === 'resolved' ? '#3fb950' : '#d29922')
+        .attr('stroke-width', 2.5 / transform.k)
+        .attr('stroke-dasharray', (6 / transform.k) + ' ' + (4 / transform.k))
+        .attr('opacity', 0.8);
     }
-  } else {
-    // Already have 2 — restart with this node as new start
-    pathfinderSelection = [d.id];
-    pathfinderResult = null;
-    clearPathfinderVisuals();
-    if (nodesGroup) {
-      nodesGroup.selectAll('.node-group')
-        .classed('pathfinder-start', function (n) { return n.id === d.id; })
-        .classed('pathfinder-end', false);
-    }
-    updatePathfinderInfo('Select target node...');
-  }
-}
 
-function bfsShortestPath(startId, endId) {
-  // Build adjacency from edgeData (treat as undirected)
-  var adj = {};
-  edgeData.forEach(function (e) {
-    var srcId = typeof e.source === 'object' ? e.source.id : e.source;
-    var tgtId = typeof e.target === 'object' ? e.target.id : e.target;
-    if (!adj[srcId]) adj[srcId] = [];
-    if (!adj[tgtId]) adj[tgtId] = [];
-    adj[srcId].push({ nodeId: tgtId, edgeId: e.id });
-    adj[tgtId].push({ nodeId: srcId, edgeId: e.id });
-  });
-
-  // BFS
-  var visited = new Set();
-  visited.add(startId);
-  var queue = [{ nodeId: startId, path: [{ nodeId: startId, edgeId: null }] }];
-
-  while (queue.length > 0) {
-    var current = queue.shift();
-    if (current.nodeId === endId) {
-      // Build result sets
-      var nodeIds = new Set();
-      var edgeIds = new Set();
-      var relTypes = [];
-      current.path.forEach(function (step) {
-        nodeIds.add(step.nodeId);
-        if (step.edgeId) {
-          edgeIds.add(step.edgeId);
-          var edge = edgeData.find(function (e) { return e.id === step.edgeId; });
-          if (edge) relTypes.push(edge.type);
+    // Draw waypoint markers
+    points.forEach(function(pt, i) {
+      var wp = waypoints[i];
+      var color = WAYPOINT_TYPE_COLORS[wp.waypoint_type] || '#8b949e';
+      var radius = 6 / transform.k;
+
+      var marker = pathGroup.append('g')
+        .attr('class', 'waypoint-marker')
+        .attr('transform', 'translate(' + pt.x + ',' + pt.y + ')')
+        .style('cursor', 'pointer');
+
+      marker.append('circle')
+        .attr('r', radius)
+        .attr('fill', color)
+        .attr('stroke', '#0d1117')
+        .attr('stroke-width', 1.5 / transform.k);
+
+      // Sequence number
+      marker.append('text')
+        .attr('text-anchor', 'middle')
+        .attr('dominant-baseline', 'central')
+        .attr('font-size', (8 / transform.k) + 'px')
+        .attr('fill', '#fff')
+        .attr('font-weight', '700')
+        .attr('pointer-events', 'none')
+        .text(wp.sequence_order);
+
+      // Tooltip on hover
+      marker.append('title')
+        .text(wp.waypoint_type + ': ' + (wp.summary || '').substring(0, 80));
+
+      // Click to show path detail
+      marker.on('click', function(event) {
+        event.stopPropagation();
+        if (window.laminarkApp && window.laminarkApp.fetchPathDetail) {
+          window.laminarkApp.fetchPathDetail(path.id).then(function(detail) {
+            if (detail) {
+              document.dispatchEvent(new CustomEvent('laminark:show_path_detail', { detail: detail }));
+            }
+          });
         }
       });
-      return { nodeIds: nodeIds, edgeIds: edgeIds, path: current.path, relTypes: relTypes };
-    }
+    });
 
-    var neighbors = adj[current.nodeId] || [];
-    for (var i = 0; i < neighbors.length; i++) {
-      var nb = neighbors[i];
-      if (!visited.has(nb.nodeId)) {
-        visited.add(nb.nodeId);
-        queue.push({
-          nodeId: nb.nodeId,
-          path: current.path.concat([{ nodeId: nb.nodeId, edgeId: nb.edgeId }]),
-        });
-      }
+    // Path label
+    if (points.length > 0) {
+      var labelX = points[0].x;
+      var labelY = points[0].y - 12 / transform.k;
+      pathGroup.append('text')
+        .attr('class', 'path-label')
+        .attr('x', labelX)
+        .attr('y', labelY)
+        .attr('font-size', (10 / transform.k) + 'px')
+        .attr('fill', path.status === 'resolved' ? '#3fb950' : '#d29922')
+        .attr('opacity', 0.9)
+        .text((path.trigger_summary || 'Debug Path').substring(0, 40));
     }
-  }
-
-  return null; // No path found
+  });
 }
 
-function visualizePathfinderResult(result) {
-  if (!nodesGroup || !edgesGroup) return;
-
-  // Dim non-path nodes
-  nodesGroup.selectAll('.node-group')
-    .classed('search-dimmed', function (d) { return !result.nodeIds.has(d.id); })
-    .classed('pathfinder-start', function (d) { return d.id === pathfinderSelection[0]; })
-    .classed('pathfinder-end', function (d) { return d.id === pathfinderSelection[1]; });
-
-  nodeLabelsGroup.selectAll('.node-label')
-    .classed('search-dimmed', function (d) { return !result.nodeIds.has(d.id); });
-
-  // Dim non-path edges, highlight path edges
-  edgesGroup.selectAll('.edge')
-    .classed('search-dimmed', function (d) { return !result.edgeIds.has(d.id); })
-    .classed('path-highlight', function (d) { return result.edgeIds.has(d.id); });
-
-  edgeLabelsGroup.selectAll('.edge-label')
-    .classed('search-dimmed', function (d) { return !result.edgeIds.has(d.id); });
-
-  // Show info
-  var hops = result.path.length - 1;
-  var types = result.relTypes.join(' > ');
-  updatePathfinderInfo(hops + ' hop' + (hops !== 1 ? 's' : '') + ': ' + types);
+function addPathOverlay(pathEvent) {
+  loadPathOverlay();
 }
 
-function clearPathfinder() {
-  pathfinderSelection = [];
-  pathfinderResult = null;
-  clearPathfinderVisuals();
-  hidePathfinderInfo();
+function updatePathOverlay(waypointEvent) {
+  loadPathOverlay();
 }
 
-function clearPathfinderVisuals() {
-  if (!nodesGroup) return;
-  nodesGroup.selectAll('.node-group')
-    .classed('pathfinder-start', false)
-    .classed('pathfinder-end', false)
-    .classed('search-dimmed', false);
-  nodeLabelsGroup.selectAll('.node-label')
-    .classed('search-dimmed', false);
-  edgesGroup.selectAll('.edge')
-    .classed('search-dimmed', false)
-    .classed('path-highlight', false);
-  edgeLabelsGroup.selectAll('.edge-label')
-    .classed('search-dimmed', false);
+function resolvePathOverlay(resolveEvent) {
+  loadPathOverlay();
 }
 
-function updatePathfinderInfo(text) {
-  if (!containerEl) return;
-  if (!pathfinderInfoEl) {
-    pathfinderInfoEl = document.createElement('div');
-    pathfinderInfoEl.className = 'pathfinder-info';
-    containerEl.appendChild(pathfinderInfoEl);
-  }
-  pathfinderInfoEl.textContent = text;
-  pathfinderInfoEl.style.display = '';
-}
+function initPathOverlayToggle() {
+  var btn = document.getElementById('paths-toggle-btn');
+  if (!btn) return;
+
+  btn.classList.toggle('active', pathOverlayVisible);
 
-function hidePathfinderInfo() {
-  if (pathfinderInfoEl) pathfinderInfoEl.style.display = 'none';
+  btn.addEventListener('click', function() {
+    pathOverlayVisible = !pathOverlayVisible;
+    localStorage.setItem('laminark-path-overlay', pathOverlayVisible ? 'true' : 'false');
+    btn.classList.toggle('active', pathOverlayVisible);
+
+    if (pathOverlayVisible) {
+      loadPathOverlay();
+    } else {
+      if (pathOverlayGroup) pathOverlayGroup.style('display', 'none');
+    }
+  });
 }
 
 // ---------------------------------------------------------------------------
@@ -2524,7 +2297,6 @@ window.laminarkGraph = {
   hideDetailPanel: hideDetailPanel,
   selectAndCenterNode: selectAndCenterNode,
   queueBatchUpdate: queueBatchUpdate,
-  clearBatchQueue: clearBatchQueue,
   togglePerfOverlay: togglePerfOverlay,
   enterFocusMode: enterFocusMode,
   exitFocusMode: exitFocusMode,
@@ -2540,10 +2312,11 @@ window.laminarkGraph = {
   clearCommunityColors: clearCommunityColors,
   showLinkedNodesOfType: showLinkedNodesOfType,
   hideContextMenu: hideContextMenu,
-  clearPathfinder: clearPathfinder,
-  isPathfinderActive: function () { return pathfinderActive; },
-  isGraphFrozen: function () { return graphFrozen; },
-  toggleGraphFrozen: toggleGraphFrozen,
+  addPathOverlay: addPathOverlay,
+  updatePathOverlay: updatePathOverlay,
+  resolvePathOverlay: resolvePathOverlay,
+  loadPathOverlay: loadPathOverlay,
+  isPathOverlayVisible: function() { return pathOverlayVisible; },
   toggleEdgeLabels: function (type) {
     if (type) {
       if (hiddenEdgeLabelTypes.has(type)) hiddenEdgeLabelTypes.delete(type);