laminark 2.21.7 → 2.21.9

package/plugin/ui/graph.js

@@ -31,17 +31,8 @@ const ENTITY_STYLES = {
   Reference: { color: '#f0883e', shape: 'hexagon' },
 };
 
-// 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',
-};
+// Pathfinder highlight color
+var PATHFINDER_COLOR = '#f0883e';
 
 // Relationship type colors for edge coloring
 var EDGE_TYPE_COLORS = {
@@ -197,10 +188,17 @@ var hiddenEdgeLabelTypes = new Set(
   JSON.parse(localStorage.getItem('laminark-hidden-edge-types') || '[]')
 );
 
-// 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?}] }
+// 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;
 
 // ---------------------------------------------------------------------------
 // initGraph
@@ -252,7 +250,6 @@ 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');
 
@@ -263,16 +260,16 @@ function initGraph(containerId) {
       svgG.attr('transform', event.transform);
       currentZoom = event.transform.k;
       updateLevelOfDetail();
-      renderPathOverlay();
     });
   svg.call(zoomBehavior);
 
-  // Background click: deselect + hide detail panel
+  // Background click: deselect + hide detail panel + clear pathfinder
   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();
     }
   });
 
@@ -305,7 +302,9 @@ function initGraph(containerId) {
 
   initContextMenu();
   initEdgeLabelToggle();
-  initPathOverlayToggle();
+  initPathfinderToggle();
+  initFreezeButton();
+  initSyncButton();
 
   // Create tooltip element
   tooltipEl = document.createElement('div');
@@ -354,8 +353,11 @@ 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) {
-    return !d.source.hidden && !d.target.hidden;
+    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);
   });
 
   // Degree-scaled repulsion: more links = stronger push away
@@ -595,6 +597,12 @@ 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; });
@@ -658,6 +666,15 @@ 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);
@@ -682,11 +699,11 @@ async function loadGraphData(filters) {
     edgeData = [];
     renderGraph();
     updateGraphStats(0, 0);
-    showEmptyState();
+    showGraphEmptyState();
     return { nodeCount: 0, edgeCount: 0 };
   }
 
-  hideEmptyState();
+  hideGraphEmptyState();
 
   // Build data arrays
   nodeData = data.nodes.map(function (node) {
@@ -727,11 +744,6 @@ 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');
@@ -757,7 +769,7 @@ function addNode(nodeDataIn) {
       createdAt: nodeDataIn.createdAt,
       hidden: false,
     });
-    hideEmptyState();
+    hideGraphEmptyState();
   }
 
   renderGraph();
@@ -804,7 +816,7 @@ function removeElements(ids) {
   renderGraph();
   updateGraphStatsFromData();
 
-  if (nodeData.length === 0) showEmptyState();
+  if (nodeData.length === 0) showGraphEmptyState();
 }
 
 // ---------------------------------------------------------------------------
@@ -967,7 +979,7 @@ function updateFilterCounts() {
 // Empty state
 // ---------------------------------------------------------------------------
 
-function showEmptyState() {
+function showGraphEmptyState() {
   if (!containerEl) return;
   var existing = containerEl.querySelector('.graph-empty-state');
   if (existing) { existing.style.display = ''; return; }
@@ -978,7 +990,7 @@ function showEmptyState() {
   containerEl.appendChild(msg);
 }
 
-function hideEmptyState() {
+function hideGraphEmptyState() {
   if (!containerEl) return;
   var existing = containerEl.querySelector('.graph-empty-state');
   if (existing) existing.style.display = 'none';
@@ -1179,9 +1191,13 @@ function initEdgeLabelToggle() {
     dropdown.appendChild(row);
   });
 
-  // Insert dropdown after button
-  btn.parentElement.style.position = 'relative';
-  btn.insertAdjacentElement('afterend', dropdown);
+  // 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);
 
   // Toggle dropdown on click
   btn.addEventListener('click', function (e) {
@@ -1407,6 +1423,12 @@ 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;
 
@@ -1450,7 +1472,14 @@ function flushBatchUpdates() {
   batchFlushTimer = null;
 
   if (newNodes > 0 || newEdges > 0) {
-    hideEmptyState();
+    // 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();
     renderGraph();
     if (!isStaticLayout && simulation) simulation.alpha(0.3).restart();
     console.log('[laminark:graph] Batch update: added ' + newNodes + ' nodes, ' + newEdges + ' edges');
@@ -1612,7 +1641,7 @@ function updateBreadcrumbs() {
 // ---------------------------------------------------------------------------
 
 function setLayout(layoutName) {
-  var validLayouts = ['clustered', 'hierarchical', 'concentric', 'communities'];
+  var validLayouts = ['clustered', 'hierarchical', 'concentric', 'communities', 'detangle'];
   if (validLayouts.indexOf(layoutName) === -1) return;
 
   var previousLayout = currentLayout;
@@ -1635,6 +1664,8 @@ function setLayout(layoutName) {
       applyHierarchicalLayout();
     } else if (layoutName === 'concentric') {
       applyConcentricLayout();
+    } else if (layoutName === 'detangle') {
+      applyDetangleLayout();
     } else {
       applyClusteredLayout();
     }
@@ -1846,6 +1877,119 @@ 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) {
@@ -2098,182 +2242,265 @@ if (document.readyState === 'loading') {
 }
 
 // ---------------------------------------------------------------------------
-// Path overlay
+// Freeze button (pauses SSE-driven refreshes) + Sync button (reload stale data)
 // ---------------------------------------------------------------------------
 
-async function loadPathOverlay() {
-  if (!svg || !pathOverlayVisible) return;
+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);
+  }
+}
 
-  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 = []; }
-    }
+function toggleGraphFrozen() {
+  graphFrozen = !graphFrozen;
+  updateFreezeButton();
 
-    renderPathOverlay();
-  } catch (err) {
-    console.error('[laminark:graph] Failed to load path overlay:', err);
+  if (!graphFrozen && graphStale) {
+    // Unfreeze: reload pending data
+    graphStale = false;
+    clearPathfinder();
+    loadGraphData();
+    updateSyncButton();
   }
 }
 
-function renderPathOverlay() {
-  if (!pathOverlayGroup || !pathOverlayVisible) {
-    if (pathOverlayGroup) pathOverlayGroup.style('display', 'none');
-    return;
+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>';
   }
-  pathOverlayGroup.style('display', null);
-  pathOverlayGroup.selectAll('*').remove();
+}
 
-  if (pathData.length === 0) return;
+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);
+}
 
-  var width = containerEl ? containerEl.clientWidth : 800;
-  var height = containerEl ? containerEl.clientHeight : 600;
+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');
+  }
+}
 
-  // Get current transform to position in screen space
-  var transform = d3.zoomTransform(svg.node());
+// ---------------------------------------------------------------------------
+// Pathfinder: shortest path between two nodes
+// ---------------------------------------------------------------------------
 
-  pathData.forEach(function(path, pathIndex) {
-    if (!path.waypoints || path.waypoints.length === 0) return;
+function initPathfinderToggle() {
+  var btn = document.getElementById('paths-toggle-btn');
+  if (!btn) return;
 
-    var pathGroup = pathOverlayGroup.append('g')
-      .attr('class', 'path-trail')
-      .attr('data-path-id', path.id);
+  btn.classList.toggle('active', pathfinderActive);
 
-    // 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;
+  btn.addEventListener('click', function () {
+    pathfinderActive = !pathfinderActive;
+    btn.classList.toggle('active', pathfinderActive);
+    if (!pathfinderActive) {
+      clearPathfinder();
+    }
+  });
+}
 
-    var points = waypoints.map(function(wp, i) {
-      return { x: xStart + i * spacing, y: yBase + pathIndex * 40 / transform.k };
-    });
+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; });
+    }
 
-    // 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);
+    // 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');
     }
+  } 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...');
+  }
+}
 
-    // 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 }));
-            }
-          });
+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);
         }
       });
-    });
+      return { nodeIds: nodeIds, edgeIds: edgeIds, path: current.path, relTypes: relTypes };
+    }
 
-    // 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));
+    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 }]),
+        });
+      }
     }
-  });
-}
+  }
 
-function addPathOverlay(pathEvent) {
-  loadPathOverlay();
+  return null; // No path found
 }
 
-function updatePathOverlay(waypointEvent) {
-  loadPathOverlay();
-}
+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); });
 
-function resolvePathOverlay(resolveEvent) {
-  loadPathOverlay();
+  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 initPathOverlayToggle() {
-  var btn = document.getElementById('paths-toggle-btn');
-  if (!btn) return;
+function clearPathfinder() {
+  pathfinderSelection = [];
+  pathfinderResult = null;
+  clearPathfinderVisuals();
+  hidePathfinderInfo();
+}
 
-  btn.classList.toggle('active', pathOverlayVisible);
+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);
+}
 
-  btn.addEventListener('click', function() {
-    pathOverlayVisible = !pathOverlayVisible;
-    localStorage.setItem('laminark-path-overlay', pathOverlayVisible ? 'true' : 'false');
-    btn.classList.toggle('active', pathOverlayVisible);
+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 = '';
+}
 
-    if (pathOverlayVisible) {
-      loadPathOverlay();
-    } else {
-      if (pathOverlayGroup) pathOverlayGroup.style('display', 'none');
-    }
-  });
+function hidePathfinderInfo() {
+  if (pathfinderInfoEl) pathfinderInfoEl.style.display = 'none';
 }
 
 // ---------------------------------------------------------------------------
@@ -2297,6 +2524,7 @@ window.laminarkGraph = {
   hideDetailPanel: hideDetailPanel,
   selectAndCenterNode: selectAndCenterNode,
   queueBatchUpdate: queueBatchUpdate,
+  clearBatchQueue: clearBatchQueue,
   togglePerfOverlay: togglePerfOverlay,
   enterFocusMode: enterFocusMode,
   exitFocusMode: exitFocusMode,
@@ -2312,11 +2540,10 @@ window.laminarkGraph = {
   clearCommunityColors: clearCommunityColors,
   showLinkedNodesOfType: showLinkedNodesOfType,
   hideContextMenu: hideContextMenu,
-  addPathOverlay: addPathOverlay,
-  updatePathOverlay: updatePathOverlay,
-  resolvePathOverlay: resolvePathOverlay,
-  loadPathOverlay: loadPathOverlay,
-  isPathOverlayVisible: function() { return pathOverlayVisible; },
+  clearPathfinder: clearPathfinder,
+  isPathfinderActive: function () { return pathfinderActive; },
+  isGraphFrozen: function () { return graphFrozen; },
+  toggleGraphFrozen: toggleGraphFrozen,
   toggleEdgeLabels: function (type) {
     if (type) {
       if (hiddenEdgeLabelTypes.has(type)) hiddenEdgeLabelTypes.delete(type);