From a6af1a37eeba90814c0ebc708b208ff1dc932e8d Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 15:29:18 -0600
Subject: [PATCH 01/23] refactor: extract shared search sub-components from
 SearchBar
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extract five reusable components to web/src/components/shared/search/:
- ConceptSearchInput: search input + spinner + dropdown (was 4x duplicated)
- SelectedConceptChip: concept selection display with Change button (5x)
- SliderControl: labeled range slider for similarity/depth/hops (6x)
- LoadButtons: Clean Graph / Add to Existing button pair (3x)
- PathResults: path list, selection, and load buttons

SearchBar uses these in all three mode sections. No behavior change —
same three tabs, same state, same handlers. Reduces SearchBar from
1170 to 801 lines; extracted components are 260 lines total.
---
 web/src/components/shared/SearchBar.tsx       | 1064 ++++++-----------
 .../shared/search/ConceptSearchInput.tsx      |   52 +
 .../components/shared/search/LoadButtons.tsx  |   30 +
 .../components/shared/search/PathResults.tsx  |  103 ++
 .../shared/search/SelectedConceptChip.tsx     |   28 +
 .../shared/search/SliderControl.tsx           |   47 +
 web/src/components/shared/search/index.ts     |    5 +
 7 files changed, 613 insertions(+), 716 deletions(-)
 create mode 100644 web/src/components/shared/search/ConceptSearchInput.tsx
 create mode 100644 web/src/components/shared/search/LoadButtons.tsx
 create mode 100644 web/src/components/shared/search/PathResults.tsx
 create mode 100644 web/src/components/shared/search/SelectedConceptChip.tsx
 create mode 100644 web/src/components/shared/search/SliderControl.tsx
 create mode 100644 web/src/components/shared/search/index.ts

diff --git a/web/src/components/shared/SearchBar.tsx b/web/src/components/shared/SearchBar.tsx
index 22730f8f..0e84fab1 100644
--- a/web/src/components/shared/SearchBar.tsx
+++ b/web/src/components/shared/SearchBar.tsx
@@ -3,13 +3,8 @@
  *
  * Top-level: Query mode selection via radio dial
  * - Smart Search (with sub-modes: Concept/Neighborhood/Path)
- * - Block Builder (future)
- * - openCypher Editor (future)
- *
- * Within Smart Search:
- * - Concept: Semantic search for individual concepts (IMPLEMENTED)
- * - Neighborhood: Explore concepts within N hops (IMPLEMENTED)
- * - Path: Find paths connecting two concepts (IMPLEMENTED)
+ * - Block Builder
+ * - openCypher Editor
  */
 
 import React, { useState } from 'react';
@@ -21,8 +16,14 @@ import { useGraphStore } from '../../store/graphStore';
 import { ModeDial } from './ModeDial';
 import { apiClient } from '../../api/client';
 import { BlockBuilder } from '../blocks/BlockBuilder';
-import { SearchResultsDropdown } from './SearchResultsDropdown';
 import { getZIndexClass } from '../../config/zIndex';
+import {
+  ConceptSearchInput,
+  SelectedConceptChip,
+  SliderControl,
+  LoadButtons,
+  PathResults,
+} from './search';
 
 type SmartSearchSubMode = 'concept' | 'neighborhood' | 'path';
 
@@ -48,41 +49,22 @@ export const SearchBar: React.FC = () => {
 
   const toggleSmartSearch = () => {
     setSmartSearchExpanded(!smartSearchExpanded);
-
-    // Trigger window resize event after a short delay to let the DOM update
-    setTimeout(() => {
-      window.dispatchEvent(new Event('resize'));
-    }, 100);
+    setTimeout(() => window.dispatchEvent(new Event('resize')), 100);
   };
 
   const toggleSection = (mode: SmartSearchSubMode) => {
-    setExpandedSections(prev => ({
-      ...prev,
-      [mode]: !prev[mode],
-    }));
-
-    // Trigger window resize event after a short delay to let the DOM update
-    setTimeout(() => {
-      window.dispatchEvent(new Event('resize'));
-    }, 100);
+    setExpandedSections(prev => ({ ...prev, [mode]: !prev[mode] }));
+    setTimeout(() => window.dispatchEvent(new Event('resize')), 100);
   };
 
   const toggleCypherEditor = () => {
     setCypherEditorExpanded(!cypherEditorExpanded);
-
-    // Trigger window resize event after a short delay to let the DOM update
-    setTimeout(() => {
-      window.dispatchEvent(new Event('resize'));
-    }, 100);
+    setTimeout(() => window.dispatchEvent(new Event('resize')), 100);
   };
 
   const toggleBlockBuilder = () => {
     setBlockBuilderExpanded(!blockBuilderExpanded);
-
-    // Trigger window resize event after a short delay to let the DOM update
-    setTimeout(() => {
-      window.dispatchEvent(new Event('resize'));
-    }, 100);
+    setTimeout(() => window.dispatchEvent(new Event('resize')), 100);
   };
 
   // Shared controls - use global similarity threshold from store
@@ -117,16 +99,14 @@ LIMIT 50`);
 
   const { setSearchParams, setRawGraphData, mergeRawGraphData, setGraphData } = useGraphStore();
 
-  // Debounce values to prevent excessive API calls while user is typing/dragging sliders
-  // 800ms for typing (embeddings are expensive), 500ms for sliders (cheaper operations)
+  // Debounce values to prevent excessive API calls
   const debouncedConceptQuery = useDebouncedValue(conceptQuery, 800);
   const debouncedNeighborhoodQuery = useDebouncedValue(neighborhoodQuery, 800);
   const debouncedPathFromQuery = useDebouncedValue(pathFromQuery, 800);
   const debouncedPathToQuery = useDebouncedValue(pathToQuery, 800);
   const debouncedSimilarity = useDebouncedValue(similarity, 500);
 
-  // Concept search results (only when no concept selected)
-  // Uses debounced similarity to prevent search spam while dragging slider
+  // Search hooks (gated by mode + selection state)
   const { data: conceptResults, isLoading: isLoadingConcepts } = useSearchConcepts(
     debouncedConceptQuery,
     {
@@ -136,7 +116,6 @@ LIMIT 50`);
     }
   );
 
-  // Neighborhood center search results (only when no center selected)
   const { data: neighborhoodSearchResults, isLoading: isLoadingNeighborhoodSearch } = useSearchConcepts(
     debouncedNeighborhoodQuery,
     {
@@ -146,7 +125,6 @@ LIMIT 50`);
     }
   );
 
-  // Path From search results (only when no from concept selected)
   const { data: pathFromSearchResults, isLoading: isLoadingPathFromSearch } = useSearchConcepts(
     debouncedPathFromQuery,
     {
@@ -156,7 +134,6 @@ LIMIT 50`);
     }
   );
 
-  // Path To search results (only when no to concept selected)
   const { data: pathToSearchResults, isLoading: isLoadingPathToSearch } = useSearchConcepts(
     debouncedPathToQuery,
     {
@@ -166,37 +143,30 @@ LIMIT 50`);
     }
   );
 
-  // Note: Path search is now manual (via button) instead of auto-search
-  // This prevents the UI from appearing to hang during expensive path searches
-
-  // Handler: Select concept in Concept mode
+  // Selection handlers
   const handleSelectConcept = (concept: any) => {
     setSelectedConcept(concept);
     setConceptQuery('');
   };
 
-  // Handler: Select center concept in Neighborhood mode
   const handleSelectCenterConcept = (concept: any) => {
     setSelectedCenterConcept(concept);
     setNeighborhoodQuery('');
   };
 
-  // Handler: Select From concept in Path mode
   const handleSelectFromConcept = (concept: any) => {
     setSelectedFromConcept(concept);
     setPathFromQuery('');
   };
 
-  // Handler: Select To concept in Path mode
   const handleSelectToConcept = (concept: any) => {
     setSelectedToConcept(concept);
     setPathToQuery('');
   };
 
-  // Handler: Load concept (sets search parameters for App.tsx to react to)
+  // Load handlers
   const handleLoadConcept = (loadMode: 'clean' | 'add') => {
     if (!selectedConcept) return;
-
     setSearchParams({
       mode: 'concept',
       conceptId: selectedConcept.concept_id,
@@ -204,10 +174,8 @@ LIMIT 50`);
     });
   };
 
-  // Handler: Load neighborhood (sets search parameters for App.tsx to react to)
   const handleLoadNeighborhood = (loadMode: 'clean' | 'add') => {
     if (!selectedCenterConcept) return;
-
     setSearchParams({
       mode: 'neighborhood',
       centerConceptId: selectedCenterConcept.concept_id,
@@ -216,7 +184,7 @@ LIMIT 50`);
     });
   };
 
-  // Handler: Search for paths between selected concepts (stores results locally)
+  // Path search (manual, not auto)
   const handleFindPaths = async () => {
     if (!selectedFromConcept || !selectedToConcept) return;
 
@@ -243,18 +211,13 @@ LIMIT 50`);
         errorMessage = error.message;
       }
 
-      setPathResults({
-        error: errorMessage,
-        count: 0,
-        paths: []
-      });
+      setPathResults({ error: errorMessage, count: 0, paths: [] });
     } finally {
       setIsLoadingPath(false);
     }
   };
 
-  // Handler: Load selected path directly into graph
-  // Converts the specific selected path to graph format (matching useFindConnection logic)
+  // Load selected path directly into graph
   const handleLoadPath = (loadMode: 'clean' | 'add') => {
     if (!selectedPath) return;
 
@@ -301,12 +264,11 @@ LIMIT 50`);
       mergeRawGraphData({ nodes, links });
     }
 
-    // Dismiss the path selection UI after loading
     setPathResults(null);
     setSelectedPath(null);
   };
 
-  // Handler: Execute openCypher query
+  // Cypher execution
   const handleExecuteCypher = async () => {
     if (!cypherQuery.trim()) return;
 
@@ -316,20 +278,15 @@ LIMIT 50`);
     try {
       const result = await apiClient.executeCypherQuery({
         query: cypherQuery,
-        limit: 100, // Default limit for safety
+        limit: 100,
       });
 
-      // Transform result to graph format and load
       const { transformForD3 } = await import('../../utils/graphTransform');
-
-      // Convert CypherNode to our node format
       const nodes = result.nodes.map((n: any) => ({
         concept_id: n.id,
         label: n.label,
         ontology: n.properties?.ontology || 'default',
       }));
-
-      // Convert CypherRelationship to our link format
       const links = result.relationships.map((r: any) => ({
         from_id: r.from_id,
         to_id: r.to_id,
@@ -338,7 +295,6 @@ LIMIT 50`);
 
       const graphData = transformForD3(nodes, links);
       useGraphStore.getState().setGraphData(graphData);
-
     } catch (error: any) {
       console.error('Failed to execute Cypher query:', error);
       setCypherError(error.response?.data?.detail || error.message || 'Query execution failed');
@@ -347,29 +303,20 @@ LIMIT 50`);
     }
   };
 
-  // Handler: Send compiled blocks to openCypher editor
+  // Block builder → Cypher editor
   const handleSendToEditor = (compiledCypher: string) => {
-    // Check if there's existing code in the editor
     const hasExistingCode = cypherQuery.trim().length > 0;
-
     if (hasExistingCode) {
       const confirmed = window.confirm(
         'The openCypher editor already has code. Do you want to overwrite it with the compiled query from the block builder?'
       );
-
-      if (!confirmed) {
-        return; // User cancelled
-      }
+      if (!confirmed) return;
     }
-
-    // Load the compiled query into the editor
     setCypherQuery(compiledCypher);
-
-    // Switch to cypher-editor mode
     setQueryMode('cypher-editor');
   };
 
-  // Get mode-specific info for the header
+  // Mode info for header
   const getModeInfo = () => {
     switch (queryMode) {
       case 'smart-search':
@@ -396,11 +343,59 @@ LIMIT 50`);
   const modeInfo = getModeInfo();
   const ModeIcon = modeInfo.icon;
 
+  // "No results" content for concept search (with below-threshold suggestions)
+  const conceptNoResults = conceptResults && conceptResults.results && conceptResults.results.length === 0 && (
+    <div className="absolute top-full left-0 right-0 mt-2 bg-card border border-border rounded-lg shadow-lg p-4 z-50">
+      <div className="text-center">
+        {conceptResults.below_threshold_count ? (
+          <div className="space-y-3">
+            <div className="text-muted-foreground">
+              <div className="font-medium mb-2">No results at {(similarity * 100).toFixed(0)}% similarity</div>
+              <div className="text-sm">
+                Found {conceptResults.below_threshold_count} concept{conceptResults.below_threshold_count > 1 ? 's' : ''} at lower similarity
+              </div>
+            </div>
+            {conceptResults.suggested_threshold && (
+              <button
+                onClick={() => setSimilarity(conceptResults.suggested_threshold)}
+                className="px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium"
+              >
+                Try {(conceptResults.suggested_threshold * 100).toFixed(0)}% Similarity
+              </button>
+            )}
+            {conceptResults.top_match && (
+              <div className="text-left p-3 bg-muted rounded-lg">
+                <div className="text-xs text-muted-foreground mb-1">Top match:</div>
+                <div className="font-medium">{conceptResults.top_match.label}</div>
+                <div className="text-sm text-muted-foreground mt-1">
+                  {(conceptResults.top_match.score * 100).toFixed(0)}% similarity
+                </div>
+              </div>
+            )}
+          </div>
+        ) : (
+          <div className="text-muted-foreground">No results found</div>
+        )}
+      </div>
+    </div>
+  );
+
+  // Similarity slider shorthand
+  const similaritySlider = (
+    <SliderControl
+      label="Similarity:"
+      value={Math.round(similarity * 100)}
+      min={0}
+      max={100}
+      onChange={(v) => setSimilarity(v / 100)}
+      displayValue={`${(similarity * 100).toFixed(0)}%`}
+    />
+  );
+
   return (
     <div className="relative space-y-4">
       {/* Header with Mode Info and Dial */}
       <div className="flex items-start justify-between gap-4">
-        {/* Mode Description Panel */}
         <div className="flex gap-3 flex-1">
           <div className="flex-shrink-0">
             <div className="w-12 h-12 rounded-lg bg-primary/10 flex items-center justify-center">
@@ -414,8 +409,6 @@ LIMIT 50`);
             </p>
           </div>
         </div>
-
-        {/* Mode Dial */}
         <ModeDial mode={queryMode} onChange={setQueryMode} />
       </div>
 
@@ -442,623 +435,268 @@ LIMIT 50`);
             <>
               {/* Sub-mode Selector (Pill Buttons) */}
               <div className="flex gap-1 p-1 bg-muted rounded-lg">
-            <button
-              onClick={() => setSmartSearchMode('concept')}
-              className={`flex-1 flex items-center justify-center gap-2 px-4 py-2 rounded-md text-sm font-medium transition-colors ${
-                smartSearchMode === 'concept'
-                  ? 'bg-background text-foreground shadow-sm'
-                  : 'text-muted-foreground hover:text-foreground'
-              }`}
-            >
-              <Search className="w-4 h-4" />
-              Concept
-            </button>
-            <button
-              onClick={() => setSmartSearchMode('neighborhood')}
-              className={`flex-1 flex items-center justify-center gap-2 px-4 py-2 rounded-md text-sm font-medium transition-colors ${
-                smartSearchMode === 'neighborhood'
-                  ? 'bg-background text-foreground shadow-sm'
-                  : 'text-muted-foreground hover:text-foreground'
-              }`}
-            >
-              <Network className="w-4 h-4" />
-              Neighborhood
-            </button>
-            <button
-              onClick={() => setSmartSearchMode('path')}
-              className={`flex-1 flex items-center justify-center gap-2 px-4 py-2 rounded-md text-sm font-medium transition-colors ${
-                smartSearchMode === 'path'
-                  ? 'bg-background text-foreground shadow-sm'
-                  : 'text-muted-foreground hover:text-foreground'
-              }`}
-            >
-              <GitBranch className="w-4 h-4" />
-              Path
-            </button>
-          </div>
-
-          {/* Concept Search */}
-          {smartSearchMode === 'concept' && (
-            <div className="space-y-3">
-              {/* Collapsible Header */}
-              <button
-                onClick={() => toggleSection('concept')}
-                className="w-full flex items-center justify-between p-2 rounded-lg hover:bg-muted/50 transition-colors"
-              >
-                <div className="flex items-center gap-2">
-                  <Search className="w-4 h-4 text-muted-foreground" />
-                  <span className="text-sm font-medium">Search for Concept</span>
-                </div>
-                {expandedSections.concept ? (
-                  <ChevronDown className="w-4 h-4 text-muted-foreground" />
-                ) : (
-                  <ChevronRight className="w-4 h-4 text-muted-foreground" />
-                )}
-              </button>
-
-              {expandedSections.concept && (
-                <>
-                  {!selectedConcept ? (
-                <div className="relative space-y-3">
-                  <div className="relative">
-                    <Search className="absolute left-3 top-1/2 transform -translate-y-1/2 w-5 h-5 text-muted-foreground" />
-                    <input
-                      type="text"
-                      value={conceptQuery}
-                      onChange={(e) => setConceptQuery(e.target.value)}
-                      placeholder="Search for a concept..."
-                      className="w-full pl-10 pr-10 py-2 rounded-lg border border-input bg-background focus:outline-none focus:ring-2 focus:ring-ring"
-                    />
-                    {isLoadingConcepts && (
-                      <LoadingSpinner className="absolute right-3 top-1/2 transform -translate-y-1/2 text-muted-foreground" />
-                    )}
-                  </div>
-
-                  {/* Similarity Slider */}
-                  <div className="flex items-center gap-3 px-1">
-                    <label className="text-sm text-muted-foreground whitespace-nowrap">
-                      Similarity:
-                    </label>
-                    <input
-                      type="range"
-                      min="0"
-                      max="100"
-                      value={similarity * 100}
-                      onChange={(e) => setSimilarity(parseInt(e.target.value) / 100)}
-                      className="flex-1 h-2 bg-muted rounded-lg appearance-none cursor-pointer
-                                 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-4 [&::-webkit-slider-thumb]:h-4
-                                 [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-primary
-                                 [&::-moz-range-thumb]:w-4 [&::-moz-range-thumb]:h-4
-                                 [&::-moz-range-thumb]:rounded-full [&::-moz-range-thumb]:bg-primary [&::-moz-range-thumb]:border-0"
-                    />
-                    <span className="text-sm font-medium min-w-[3ch] text-right">
-                      {(similarity * 100).toFixed(0)}%
-                    </span>
-                  </div>
-
-                  {/* Search Results */}
-                  {debouncedConceptQuery && conceptResults && conceptResults.results && conceptResults.results.length > 0 && (
-                    <SearchResultsDropdown
-                      results={conceptResults.results}
-                      onSelect={handleSelectConcept}
-                    />
-                  )}
+                <button
+                  onClick={() => setSmartSearchMode('concept')}
+                  className={`flex-1 flex items-center justify-center gap-2 px-4 py-2 rounded-md text-sm font-medium transition-colors ${
+                    smartSearchMode === 'concept'
+                      ? 'bg-background text-foreground shadow-sm'
+                      : 'text-muted-foreground hover:text-foreground'
+                  }`}
+                >
+                  <Search className="w-4 h-4" />
+                  Concept
+                </button>
+                <button
+                  onClick={() => setSmartSearchMode('neighborhood')}
+                  className={`flex-1 flex items-center justify-center gap-2 px-4 py-2 rounded-md text-sm font-medium transition-colors ${
+                    smartSearchMode === 'neighborhood'
+                      ? 'bg-background text-foreground shadow-sm'
+                      : 'text-muted-foreground hover:text-foreground'
+                  }`}
+                >
+                  <Network className="w-4 h-4" />
+                  Neighborhood
+                </button>
+                <button
+                  onClick={() => setSmartSearchMode('path')}
+                  className={`flex-1 flex items-center justify-center gap-2 px-4 py-2 rounded-md text-sm font-medium transition-colors ${
+                    smartSearchMode === 'path'
+                      ? 'bg-background text-foreground shadow-sm'
+                      : 'text-muted-foreground hover:text-foreground'
+                  }`}
+                >
+                  <GitBranch className="w-4 h-4" />
+                  Path
+                </button>
+              </div>
 
-                  {/* No Results with Smart Recommendations */}
-                  {debouncedConceptQuery && conceptResults && conceptResults.results && conceptResults.results.length === 0 && (
-                    <div className="absolute top-full left-0 right-0 mt-2 bg-card border border-border rounded-lg shadow-lg p-4 z-50">
-                      <div className="text-center">
-                        {conceptResults.below_threshold_count ? (
-                          <div className="space-y-3">
-                            <div className="text-muted-foreground">
-                              <div className="font-medium mb-2">No results at {(similarity * 100).toFixed(0)}% similarity</div>
-                              <div className="text-sm">
-                                Found {conceptResults.below_threshold_count} concept{conceptResults.below_threshold_count > 1 ? 's' : ''} at lower similarity
-                              </div>
-                            </div>
-                            {conceptResults.suggested_threshold && (
-                              <button
-                                onClick={() => setSimilarity(conceptResults.suggested_threshold)}
-                                className="px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium"
-                              >
-                                Try {(conceptResults.suggested_threshold * 100).toFixed(0)}% Similarity
-                              </button>
-                            )}
-                            {conceptResults.top_match && (
-                              <div className="text-left p-3 bg-muted rounded-lg">
-                                <div className="text-xs text-muted-foreground mb-1">Top match:</div>
-                                <div className="font-medium">{conceptResults.top_match.label}</div>
-                                <div className="text-sm text-muted-foreground mt-1">
-                                  {(conceptResults.top_match.score * 100).toFixed(0)}% similarity
-                                </div>
-                              </div>
-                            )}
-                          </div>
-                        ) : (
-                          <div className="text-muted-foreground">No results found</div>
-                        )}
-                      </div>
-                    </div>
-                  )}
-                </div>
-              ) : (
+              {/* ===== CONCEPT MODE ===== */}
+              {smartSearchMode === 'concept' && (
                 <div className="space-y-3">
-                  {/* Selected Concept */}
-                  <div className="p-3 bg-muted rounded-lg">
-                    <div className="flex items-start justify-between">
-                      <div>
-                        <div className="text-xs text-muted-foreground mb-1">Selected concept:</div>
-                        <div className="font-medium">{selectedConcept.label}</div>
-                      </div>
-                      <button
-                        onClick={() => setSelectedConcept(null)}
-                        className="text-sm text-muted-foreground hover:text-foreground"
-                      >
-                        Change
-                      </button>
+                  <button
+                    onClick={() => toggleSection('concept')}
+                    className="w-full flex items-center justify-between p-2 rounded-lg hover:bg-muted/50 transition-colors"
+                  >
+                    <div className="flex items-center gap-2">
+                      <Search className="w-4 h-4 text-muted-foreground" />
+                      <span className="text-sm font-medium">Search for Concept</span>
                     </div>
-                  </div>
-
-                  {/* Similarity Slider */}
-                  <div className="flex items-center gap-3 px-1">
-                    <label className="text-sm text-muted-foreground whitespace-nowrap">
-                      Similarity:
-                    </label>
-                    <input
-                      type="range"
-                      min="0"
-                      max="100"
-                      value={similarity * 100}
-                      onChange={(e) => setSimilarity(parseInt(e.target.value) / 100)}
-                      className="flex-1 h-2 bg-muted rounded-lg appearance-none cursor-pointer
-                                 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-4 [&::-webkit-slider-thumb]:h-4
-                                 [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-primary
-                                 [&::-moz-range-thumb]:w-4 [&::-moz-range-thumb]:h-4
-                                 [&::-moz-range-thumb]:rounded-full [&::-moz-range-thumb]:bg-primary [&::-moz-range-thumb]:border-0"
-                    />
-                    <span className="text-sm font-medium min-w-[3ch] text-right">
-                      {(similarity * 100).toFixed(0)}%
-                    </span>
-                  </div>
-
-                  {/* Load Buttons */}
-                  <div className="flex gap-2">
-                    <button
-                      onClick={() => handleLoadConcept('clean')}
-                      className="flex-1 px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium"
-                    >
-                      Load into Clean Graph
-                    </button>
-                    <button
-                      onClick={() => handleLoadConcept('add')}
-                      className="flex-1 px-4 py-2 bg-secondary text-secondary-foreground rounded-lg hover:bg-secondary/80 transition-colors text-sm font-medium"
-                    >
-                      Add to Existing Graph
-                    </button>
-                  </div>
-                </div>
-              )}
-                </>
-              )}
-            </div>
-          )}
-
-          {/* Neighborhood Search */}
-          {smartSearchMode === 'neighborhood' && (
-            <div className="space-y-3">
-              {/* Collapsible Header */}
-              <button
-                onClick={() => toggleSection('neighborhood')}
-                className="w-full flex items-center justify-between p-2 rounded-lg hover:bg-muted/50 transition-colors"
-              >
-                <div className="flex items-center gap-2">
-                  <Network className="w-4 h-4 text-muted-foreground" />
-                  <span className="text-sm font-medium">Explore Neighborhood</span>
-                </div>
-                {expandedSections.neighborhood ? (
-                  <ChevronDown className="w-4 h-4 text-muted-foreground" />
-                ) : (
-                  <ChevronRight className="w-4 h-4 text-muted-foreground" />
-                )}
-              </button>
-
-              {expandedSections.neighborhood && (
-                <>
-                  {!selectedCenterConcept ? (
-                <div className="relative space-y-3">
-                  <div className="relative">
-                    <Network className="absolute left-3 top-1/2 transform -translate-y-1/2 w-5 h-5 text-muted-foreground" />
-                    <input
-                      type="text"
-                      value={neighborhoodQuery}
-                      onChange={(e) => setNeighborhoodQuery(e.target.value)}
-                      placeholder="Search for center concept..."
-                      className="w-full pl-10 pr-10 py-2 rounded-lg border border-input bg-background focus:outline-none focus:ring-2 focus:ring-ring"
-                    />
-                    {isLoadingNeighborhoodSearch && (
-                      <LoadingSpinner className="absolute right-3 top-1/2 transform -translate-y-1/2 text-muted-foreground" />
+                    {expandedSections.concept ? (
+                      <ChevronDown className="w-4 h-4 text-muted-foreground" />
+                    ) : (
+                      <ChevronRight className="w-4 h-4 text-muted-foreground" />
                     )}
-                  </div>
-
-                  {/* Similarity Slider */}
-                  <div className="flex items-center gap-3 px-1">
-                    <label className="text-sm text-muted-foreground whitespace-nowrap">
-                      Similarity:
-                    </label>
-                    <input
-                      type="range"
-                      min="0"
-                      max="100"
-                      value={similarity * 100}
-                      onChange={(e) => setSimilarity(parseInt(e.target.value) / 100)}
-                      className="flex-1 h-2 bg-muted rounded-lg appearance-none cursor-pointer
-                                 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-4 [&::-webkit-slider-thumb]:h-4
-                                 [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-primary
-                                 [&::-moz-range-thumb]:w-4 [&::-moz-range-thumb]:h-4
-                                 [&::-moz-range-thumb]:rounded-full [&::-moz-range-thumb]:bg-primary [&::-moz-range-thumb]:border-0"
-                    />
-                    <span className="text-sm font-medium min-w-[3ch] text-right">
-                      {(similarity * 100).toFixed(0)}%
-                    </span>
-                  </div>
+                  </button>
 
-                  {/* Search Results */}
-                  {debouncedNeighborhoodQuery && neighborhoodSearchResults && neighborhoodSearchResults.results && neighborhoodSearchResults.results.length > 0 && (
-                    <SearchResultsDropdown
-                      results={neighborhoodSearchResults.results}
-                      onSelect={handleSelectCenterConcept}
-                    />
+                  {expandedSections.concept && (
+                    <>
+                      {!selectedConcept ? (
+                        <div className="space-y-3">
+                          <ConceptSearchInput
+                            query={conceptQuery}
+                            onQueryChange={setConceptQuery}
+                            placeholder="Search for a concept..."
+                            icon={Search}
+                            isLoading={isLoadingConcepts}
+                            results={conceptResults?.results}
+                            debouncedQuery={debouncedConceptQuery}
+                            onSelect={handleSelectConcept}
+                            noResultsContent={conceptNoResults}
+                          />
+                          {similaritySlider}
+                        </div>
+                      ) : (
+                        <div className="space-y-3">
+                          <SelectedConceptChip
+                            label="Selected concept:"
+                            conceptLabel={selectedConcept.label}
+                            onClear={() => setSelectedConcept(null)}
+                          />
+                          {similaritySlider}
+                          <LoadButtons
+                            onLoadClean={() => handleLoadConcept('clean')}
+                            onLoadAdd={() => handleLoadConcept('add')}
+                          />
+                        </div>
+                      )}
+                    </>
                   )}
                 </div>
-              ) : (
-                <div className="space-y-3">
-                  {/* Selected Center Concept */}
-                  <div className="p-3 bg-muted rounded-lg">
-                    <div className="flex items-start justify-between">
-                      <div>
-                        <div className="text-xs text-muted-foreground mb-1">Center concept:</div>
-                        <div className="font-medium">{selectedCenterConcept.label}</div>
-                      </div>
-                      <button
-                        onClick={() => setSelectedCenterConcept(null)}
-                        className="text-sm text-muted-foreground hover:text-foreground"
-                      >
-                        Change
-                      </button>
-                    </div>
-                  </div>
-
-                  {/* Depth Slider */}
-                  <div className="flex items-center gap-3 px-1">
-                    <label className="text-sm text-muted-foreground whitespace-nowrap">
-                      Depth:
-                    </label>
-                    <input
-                      type="range"
-                      min="1"
-                      max="5"
-                      value={neighborhoodDepth}
-                      onChange={(e) => setNeighborhoodDepth(parseInt(e.target.value))}
-                      className="flex-1 h-2 bg-muted rounded-lg appearance-none cursor-pointer
-                                 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-4 [&::-webkit-slider-thumb]:h-4
-                                 [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-primary
-                                 [&::-moz-range-thumb]:w-4 [&::-moz-range-thumb]:h-4
-                                 [&::-moz-range-thumb]:rounded-full [&::-moz-range-thumb]:bg-primary [&::-moz-range-thumb]:border-0"
-                    />
-                    <span className="text-sm font-medium min-w-[1ch] text-right">
-                      {neighborhoodDepth}
-                    </span>
-                    <span className="text-xs text-muted-foreground whitespace-nowrap">
-                      hop{neighborhoodDepth > 1 ? 's' : ''}
-                    </span>
-                  </div>
-
-                  {/* Load Buttons */}
-                  <div className="flex gap-2">
-                    <button
-                      onClick={() => handleLoadNeighborhood('clean')}
-                      className="flex-1 px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium"
-                    >
-                      Load into Clean Graph
-                    </button>
-                    <button
-                      onClick={() => handleLoadNeighborhood('add')}
-                      className="flex-1 px-4 py-2 bg-secondary text-secondary-foreground rounded-lg hover:bg-secondary/80 transition-colors text-sm font-medium"
-                    >
-                      Add to Existing Graph
-                    </button>
-                  </div>
-                </div>
-              )}
-                </>
               )}
-            </div>
-          )}
-
-          {/* Path Search */}
-          {smartSearchMode === 'path' && (
-            <div className="space-y-3">
-              {/* Collapsible Header */}
-              <button
-                onClick={() => toggleSection('path')}
-                className="w-full flex items-center justify-between p-2 rounded-lg hover:bg-muted/50 transition-colors"
-              >
-                <div className="flex items-center gap-2">
-                  <GitBranch className="w-4 h-4 text-muted-foreground" />
-                  <span className="text-sm font-medium">Find Paths Between Concepts</span>
-                </div>
-                {expandedSections.path ? (
-                  <ChevronDown className="w-4 h-4 text-muted-foreground" />
-                ) : (
-                  <ChevronRight className="w-4 h-4 text-muted-foreground" />
-                )}
-              </button>
-
-              {expandedSections.path && (
-                <>
-                  {/* Step 1: Search for From concept */}
-                  {!selectedFromConcept ? (
-                <div className="relative space-y-3">
-                  <div className="relative">
-                    <GitBranch className="absolute left-3 top-1/2 transform -translate-y-1/2 w-5 h-5 text-muted-foreground" />
-                    <input
-                      type="text"
-                      value={pathFromQuery}
-                      onChange={(e) => setPathFromQuery(e.target.value)}
-                      placeholder="Search for starting concept..."
-                      className="w-full pl-10 pr-10 py-2 rounded-lg border border-input bg-background focus:outline-none focus:ring-2 focus:ring-ring"
-                    />
-                    {isLoadingPathFromSearch && (
-                      <LoadingSpinner className="absolute right-3 top-1/2 transform -translate-y-1/2 text-muted-foreground" />
-                    )}
-                  </div>
-
-                  {/* Similarity Slider */}
-                  <div className="flex items-center gap-3 px-1">
-                    <label className="text-sm text-muted-foreground whitespace-nowrap">
-                      Similarity:
-                    </label>
-                    <input
-                      type="range"
-                      min="0"
-                      max="100"
-                      value={similarity * 100}
-                      onChange={(e) => setSimilarity(parseInt(e.target.value) / 100)}
-                      className="flex-1 h-2 bg-muted rounded-lg appearance-none cursor-pointer
-                                 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-4 [&::-webkit-slider-thumb]:h-4
-                                 [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-primary
-                                 [&::-moz-range-thumb]:w-4 [&::-moz-range-thumb]:h-4
-                                 [&::-moz-range-thumb]:rounded-full [&::-moz-range-thumb]:bg-primary [&::-moz-range-thumb]:border-0"
-                    />
-                    <span className="text-sm font-medium min-w-[3ch] text-right">
-                      {(similarity * 100).toFixed(0)}%
-                    </span>
-                  </div>
 
-                  {/* From Search Results */}
-                  {debouncedPathFromQuery && pathFromSearchResults && pathFromSearchResults.results && pathFromSearchResults.results.length > 0 && (
-                    <SearchResultsDropdown
-                      results={pathFromSearchResults.results}
-                      onSelect={handleSelectFromConcept}
-                    />
-                  )}
-                </div>
-              ) : !selectedToConcept ? (
+              {/* ===== NEIGHBORHOOD MODE ===== */}
+              {smartSearchMode === 'neighborhood' && (
                 <div className="space-y-3">
-                  {/* Selected From Concept */}
-                  <div className="p-3 bg-muted rounded-lg">
-                    <div className="flex items-start justify-between">
-                      <div>
-                        <div className="text-xs text-muted-foreground mb-1">From concept:</div>
-                        <div className="font-medium">{selectedFromConcept.label}</div>
-                      </div>
-                      <button
-                        onClick={() => setSelectedFromConcept(null)}
-                        className="text-sm text-muted-foreground hover:text-foreground"
-                      >
-                        Change
-                      </button>
-                    </div>
-                  </div>
-
-                  {/* Step 2: Search for To concept */}
-                  <div className="relative space-y-3">
-                    <div className="relative">
-                      <GitBranch className="absolute left-3 top-1/2 transform -translate-y-1/2 w-5 h-5 text-muted-foreground rotate-180" />
-                      <input
-                        type="text"
-                        value={pathToQuery}
-                        onChange={(e) => setPathToQuery(e.target.value)}
-                        placeholder="Search for target concept..."
-                        className="w-full pl-10 pr-10 py-2 rounded-lg border border-input bg-background focus:outline-none focus:ring-2 focus:ring-ring"
-                      />
-                      {isLoadingPathToSearch && (
-                        <LoadingSpinner className="absolute right-3 top-1/2 transform -translate-y-1/2 text-muted-foreground" />
-                      )}
+                  <button
+                    onClick={() => toggleSection('neighborhood')}
+                    className="w-full flex items-center justify-between p-2 rounded-lg hover:bg-muted/50 transition-colors"
+                  >
+                    <div className="flex items-center gap-2">
+                      <Network className="w-4 h-4 text-muted-foreground" />
+                      <span className="text-sm font-medium">Explore Neighborhood</span>
                     </div>
-
-                    {/* To Search Results */}
-                    {debouncedPathToQuery && pathToSearchResults && pathToSearchResults.results && pathToSearchResults.results.length > 0 && (
-                      <SearchResultsDropdown
-                        results={pathToSearchResults.results}
-                        onSelect={handleSelectToConcept}
-                      />
+                    {expandedSections.neighborhood ? (
+                      <ChevronDown className="w-4 h-4 text-muted-foreground" />
+                    ) : (
+                      <ChevronRight className="w-4 h-4 text-muted-foreground" />
                     )}
-                  </div>
-                </div>
-              ) : (
-                <div className="space-y-3">
-                  {/* Selected From and To Concepts */}
-                  <div className="space-y-2">
-                    <div className="p-3 bg-muted rounded-lg">
-                      <div className="flex items-start justify-between">
-                        <div>
-                          <div className="text-xs text-muted-foreground mb-1">From concept:</div>
-                          <div className="font-medium">{selectedFromConcept.label}</div>
+                  </button>
+
+                  {expandedSections.neighborhood && (
+                    <>
+                      {!selectedCenterConcept ? (
+                        <div className="space-y-3">
+                          <ConceptSearchInput
+                            query={neighborhoodQuery}
+                            onQueryChange={setNeighborhoodQuery}
+                            placeholder="Search for center concept..."
+                            icon={Network}
+                            isLoading={isLoadingNeighborhoodSearch}
+                            results={neighborhoodSearchResults?.results}
+                            debouncedQuery={debouncedNeighborhoodQuery}
+                            onSelect={handleSelectCenterConcept}
+                          />
+                          {similaritySlider}
                         </div>
-                        <button
-                          onClick={() => {
-                            setSelectedFromConcept(null);
-                            setSelectedToConcept(null);
-                          }}
-                          className="text-sm text-muted-foreground hover:text-foreground"
-                        >
-                          Change
-                        </button>
-                      </div>
-                    </div>
-                    <div className="p-3 bg-muted rounded-lg">
-                      <div className="flex items-start justify-between">
-                        <div>
-                          <div className="text-xs text-muted-foreground mb-1">To concept:</div>
-                          <div className="font-medium">{selectedToConcept.label}</div>
+                      ) : (
+                        <div className="space-y-3">
+                          <SelectedConceptChip
+                            label="Center concept:"
+                            conceptLabel={selectedCenterConcept.label}
+                            onClear={() => setSelectedCenterConcept(null)}
+                          />
+                          <SliderControl
+                            label="Depth:"
+                            value={neighborhoodDepth}
+                            min={1}
+                            max={5}
+                            onChange={setNeighborhoodDepth}
+                            unit={`hop${neighborhoodDepth > 1 ? 's' : ''}`}
+                          />
+                          <LoadButtons
+                            onLoadClean={() => handleLoadNeighborhood('clean')}
+                            onLoadAdd={() => handleLoadNeighborhood('add')}
+                          />
                         </div>
-                        <button
-                          onClick={() => setSelectedToConcept(null)}
-                          className="text-sm text-muted-foreground hover:text-foreground"
-                        >
-                          Change
-                        </button>
-                      </div>
-                    </div>
-                  </div>
-
-                  {/* Similarity Slider */}
-                  <div className="flex items-center gap-3 px-1">
-                    <label className="text-sm text-muted-foreground whitespace-nowrap">
-                      Similarity:
-                    </label>
-                    <input
-                      type="range"
-                      min="0"
-                      max="100"
-                      value={similarity * 100}
-                      onChange={(e) => setSimilarity(parseInt(e.target.value) / 100)}
-                      className="flex-1 h-2 bg-muted rounded-lg appearance-none cursor-pointer
-                                 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-4 [&::-webkit-slider-thumb]:h-4
-                                 [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-primary
-                                 [&::-moz-range-thumb]:w-4 [&::-moz-range-thumb]:h-4
-                                 [&::-moz-range-thumb]:rounded-full [&::-moz-range-thumb]:bg-primary [&::-moz-range-thumb]:border-0"
-                    />
-                    <span className="text-sm font-medium min-w-[3ch] text-right">
-                      {(similarity * 100).toFixed(0)}%
-                    </span>
-                  </div>
-
-                  {/* Max Hops Slider */}
-                  <div className="flex items-center gap-3 px-1">
-                    <label className="text-sm text-muted-foreground whitespace-nowrap">
-                      Max Hops:
-                    </label>
-                    <input
-                      type="range"
-                      min="1"
-                      max="10"
-                      value={maxHops}
-                      onChange={(e) => setMaxHops(parseInt(e.target.value))}
-                      className="flex-1 h-2 bg-muted rounded-lg appearance-none cursor-pointer
-                                 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-4 [&::-webkit-slider-thumb]:h-4
-                                 [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-primary
-                                 [&::-moz-range-thumb]:w-4 [&::-moz-range-thumb]:h-4
-                                 [&::-moz-range-thumb]:rounded-full [&::-moz-range-thumb]:bg-primary [&::-moz-range-thumb]:border-0"
-                    />
-                    <span className="text-sm font-medium min-w-[2ch] text-right">
-                      {maxHops}
-                    </span>
-                  </div>
+                      )}
+                    </>
+                  )}
+                </div>
+              )}
 
-                  {/* Find Paths Button */}
+              {/* ===== PATH MODE ===== */}
+              {smartSearchMode === 'path' && (
+                <div className="space-y-3">
                   <button
-                    onClick={handleFindPaths}
-                    disabled={isLoadingPath}
-                    className="w-full px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed flex items-center justify-center gap-2"
+                    onClick={() => toggleSection('path')}
+                    className="w-full flex items-center justify-between p-2 rounded-lg hover:bg-muted/50 transition-colors"
                   >
-                    {isLoadingPath ? (
-                      <>
-                        <LoadingSpinner className="text-primary-foreground" />
-                        Searching...
-                      </>
+                    <div className="flex items-center gap-2">
+                      <GitBranch className="w-4 h-4 text-muted-foreground" />
+                      <span className="text-sm font-medium">Find Paths Between Concepts</span>
+                    </div>
+                    {expandedSections.path ? (
+                      <ChevronDown className="w-4 h-4 text-muted-foreground" />
                     ) : (
-                      'Find Paths'
+                      <ChevronRight className="w-4 h-4 text-muted-foreground" />
                     )}
                   </button>
 
-                  {/* Path Results */}
-                  {pathResults && !isLoadingPath && (
-                    <div className="space-y-3">
-                      {pathResults.error ? (
-                        <div className="p-4 bg-destructive/10 border border-destructive/20 rounded-lg text-center text-destructive text-sm">
-                          {pathResults.error}
+                  {expandedSections.path && (
+                    <>
+                      {/* Step 1: Select From concept */}
+                      {!selectedFromConcept ? (
+                        <div className="space-y-3">
+                          <ConceptSearchInput
+                            query={pathFromQuery}
+                            onQueryChange={setPathFromQuery}
+                            placeholder="Search for starting concept..."
+                            icon={GitBranch}
+                            isLoading={isLoadingPathFromSearch}
+                            results={pathFromSearchResults?.results}
+                            debouncedQuery={debouncedPathFromQuery}
+                            onSelect={handleSelectFromConcept}
+                          />
+                          {similaritySlider}
                         </div>
-                      ) : pathResults.count > 0 ? (
-                        <>
-                          <div className="text-sm text-muted-foreground">
-                            Found {pathResults.count} path{pathResults.count > 1 ? 's' : ''} ({pathResults.paths[0].hops} hop{pathResults.paths[0].hops > 1 ? 's' : ''})
-                          </div>
-
-                          {/* Path Selection */}
+                      ) : !selectedToConcept ? (
+                        /* Step 2: Select To concept */
+                        <div className="space-y-3">
+                          <SelectedConceptChip
+                            label="From concept:"
+                            conceptLabel={selectedFromConcept.label}
+                            onClear={() => setSelectedFromConcept(null)}
+                          />
+                          <ConceptSearchInput
+                            query={pathToQuery}
+                            onQueryChange={setPathToQuery}
+                            placeholder="Search for target concept..."
+                            icon={GitBranch}
+                            isLoading={isLoadingPathToSearch}
+                            results={pathToSearchResults?.results}
+                            debouncedQuery={debouncedPathToQuery}
+                            onSelect={handleSelectToConcept}
+                          />
+                        </div>
+                      ) : (
+                        /* Step 3: Both selected — configure and search */
+                        <div className="space-y-3">
                           <div className="space-y-2">
-                            <div className="text-xs text-muted-foreground uppercase tracking-wide">Select a path:</div>
-                            {pathResults.paths.map((path: any, index: number) => (
-                              <button
-                                key={index}
-                                onClick={() => setSelectedPath(path)}
-                                className={`w-full text-left p-3 rounded-lg border transition-colors ${
-                                  selectedPath === path
-                                    ? 'border-primary bg-primary/10'
-                                    : 'border-border bg-muted hover:border-primary/50'
-                                }`}
-                              >
-                                <div className="text-sm font-mono">
-                                  {path.nodes
-                                    .filter((node: any) => node.id && node.id !== '')
-                                    .map((node: any, i: number) => (
-                                      <span key={i}>
-                                        {i > 0 && <span className="text-muted-foreground"> → </span>}
-                                        <span className="font-medium">{node.label}</span>
-                                      </span>
-                                    ))}
-                                </div>
-                                {path.score && (
-                                  <div className="text-xs text-muted-foreground mt-1">
-                                    Score: {(path.score * 100).toFixed(1)}%
-                                  </div>
-                                )}
-                              </button>
-                            ))}
+                            <SelectedConceptChip
+                              label="From concept:"
+                              conceptLabel={selectedFromConcept.label}
+                              onClear={() => {
+                                setSelectedFromConcept(null);
+                                setSelectedToConcept(null);
+                              }}
+                            />
+                            <SelectedConceptChip
+                              label="To concept:"
+                              conceptLabel={selectedToConcept.label}
+                              onClear={() => setSelectedToConcept(null)}
+                            />
                           </div>
 
-                          {/* Load Buttons (only if path selected) */}
-                          {selectedPath && (
-                            <div className="flex gap-2">
-                              <button
-                                onClick={() => handleLoadPath('clean')}
-                                className="flex-1 px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium"
-                              >
-                                Load into Clean Graph
-                              </button>
-                              <button
-                                onClick={() => handleLoadPath('add')}
-                                className="flex-1 px-4 py-2 bg-secondary text-secondary-foreground rounded-lg hover:bg-secondary/80 transition-colors text-sm font-medium"
-                              >
-                                Add to Existing Graph
-                              </button>
-                            </div>
-                          )}
-                        </>
-                      ) : (
-                        <div className="p-4 bg-muted rounded-lg text-center text-muted-foreground text-sm">
-                          No paths found. Try lowering similarity or increasing max hops.
+                          {similaritySlider}
+
+                          <SliderControl
+                            label="Max Hops:"
+                            value={maxHops}
+                            min={1}
+                            max={10}
+                            onChange={setMaxHops}
+                          />
+
+                          {/* Find Paths Button */}
+                          <button
+                            onClick={handleFindPaths}
+                            disabled={isLoadingPath}
+                            className="w-full px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed flex items-center justify-center gap-2"
+                          >
+                            {isLoadingPath ? (
+                              <>
+                                <LoadingSpinner className="text-primary-foreground" />
+                                Searching...
+                              </>
+                            ) : (
+                              'Find Paths'
+                            )}
+                          </button>
+
+                          <PathResults
+                            pathResults={pathResults}
+                            selectedPath={selectedPath}
+                            isLoading={false}
+                            onSelectPath={setSelectedPath}
+                            onLoadClean={() => handleLoadPath('clean')}
+                            onLoadAdd={() => handleLoadPath('add')}
+                          />
                         </div>
                       )}
-                    </div>
+                    </>
                   )}
                 </div>
               )}
-                </>
-              )}
-            </div>
-          )}
             </>
           )}
         </div>
@@ -1067,7 +705,6 @@ LIMIT 50`);
       {/* Block Builder Mode */}
       {queryMode === 'block-builder' && (
         <div className="space-y-3">
-          {/* Collapsible Header */}
           <button
             onClick={toggleBlockBuilder}
             className="w-full flex items-center justify-between p-2 rounded-lg hover:bg-muted/50 transition-colors"
@@ -1094,7 +731,6 @@ LIMIT 50`);
       {/* openCypher Editor Mode */}
       {queryMode === 'cypher-editor' && (
         <div className="space-y-3">
-          {/* Collapsible Header */}
           <button
             onClick={toggleCypherEditor}
             className="w-full flex items-center justify-between p-2 rounded-lg hover:bg-muted/50 transition-colors"
@@ -1112,54 +748,50 @@ LIMIT 50`);
 
           {cypherEditorExpanded && (
             <>
-              {/* Query Editor (Textarea for now, can upgrade to Monaco later) */}
               <div className="space-y-2">
-            <textarea
-              value={cypherQuery}
-              onChange={(e) => setCypherQuery(e.target.value)}
-              placeholder="Enter openCypher query..."
-              className="w-full h-48 px-3 py-2 font-mono text-sm rounded-lg border border-input bg-background focus:outline-none focus:ring-2 focus:ring-ring resize-y"
-              spellCheck={false}
-            />
-
-            {/* Error Display */}
-            {cypherError && (
-              <div className="p-3 bg-destructive/10 border border-destructive/20 rounded-lg text-sm text-destructive">
-                {cypherError}
-              </div>
-            )}
+                <textarea
+                  value={cypherQuery}
+                  onChange={(e) => setCypherQuery(e.target.value)}
+                  placeholder="Enter openCypher query..."
+                  className="w-full h-48 px-3 py-2 font-mono text-sm rounded-lg border border-input bg-background focus:outline-none focus:ring-2 focus:ring-ring resize-y"
+                  spellCheck={false}
+                />
+
+                {cypherError && (
+                  <div className="p-3 bg-destructive/10 border border-destructive/20 rounded-lg text-sm text-destructive">
+                    {cypherError}
+                  </div>
+                )}
 
-            {/* Execute Button */}
-            <button
-              onClick={handleExecuteCypher}
-              disabled={isExecutingCypher || !cypherQuery.trim()}
-              className="w-full px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed flex items-center justify-center gap-2"
-            >
-              {isExecutingCypher ? (
-                <>
-                  <LoadingSpinner className="text-primary-foreground" />
-                  Executing Query...
-                </>
-              ) : (
-                <>
-                  <Code className="w-4 h-4" />
-                  Execute Query
-                </>
-              )}
-            </button>
-
-            {/* Help Text */}
-            <div className="text-xs text-muted-foreground space-y-1">
-              <div className="font-medium">Example queries:</div>
-              <div className="font-mono bg-muted p-2 rounded">
-                <div>MATCH (c:Concept) WHERE c.label CONTAINS 'organizational' RETURN c LIMIT 10</div>
-                <div className="mt-1">{'MATCH (c:Concept)-[r:IMPLIES]->(n:Concept) RETURN c, r, n LIMIT 50'}</div>
-              </div>
-              <div className="text-muted-foreground/70 mt-2">
-                Results are automatically loaded into the graph visualization.
+                <button
+                  onClick={handleExecuteCypher}
+                  disabled={isExecutingCypher || !cypherQuery.trim()}
+                  className="w-full px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed flex items-center justify-center gap-2"
+                >
+                  {isExecutingCypher ? (
+                    <>
+                      <LoadingSpinner className="text-primary-foreground" />
+                      Executing Query...
+                    </>
+                  ) : (
+                    <>
+                      <Code className="w-4 h-4" />
+                      Execute Query
+                    </>
+                  )}
+                </button>
+
+                <div className="text-xs text-muted-foreground space-y-1">
+                  <div className="font-medium">Example queries:</div>
+                  <div className="font-mono bg-muted p-2 rounded">
+                    <div>MATCH (c:Concept) WHERE c.label CONTAINS 'organizational' RETURN c LIMIT 10</div>
+                    <div className="mt-1">{'MATCH (c:Concept)-[r:IMPLIES]->(n:Concept) RETURN c, r, n LIMIT 50'}</div>
+                  </div>
+                  <div className="text-muted-foreground/70 mt-2">
+                    Results are automatically loaded into the graph visualization.
+                  </div>
+                </div>
               </div>
-            </div>
-          </div>
             </>
           )}
         </div>
diff --git a/web/src/components/shared/search/ConceptSearchInput.tsx b/web/src/components/shared/search/ConceptSearchInput.tsx
new file mode 100644
index 00000000..f56ea6a5
--- /dev/null
+++ b/web/src/components/shared/search/ConceptSearchInput.tsx
@@ -0,0 +1,52 @@
+import React from 'react';
+import { LoadingSpinner } from '../LoadingSpinner';
+import { SearchResultsDropdown } from '../SearchResultsDropdown';
+
+interface ConceptSearchInputProps {
+  query: string;
+  onQueryChange: (query: string) => void;
+  placeholder: string;
+  icon: React.ComponentType<{ className?: string }>;
+  isLoading: boolean;
+  results: any[] | undefined;
+  debouncedQuery: string;
+  onSelect: (concept: any) => void;
+  noResultsContent?: React.ReactNode;
+}
+
+export const ConceptSearchInput: React.FC<ConceptSearchInputProps> = ({
+  query,
+  onQueryChange,
+  placeholder,
+  icon: Icon,
+  isLoading,
+  results,
+  debouncedQuery,
+  onSelect,
+  noResultsContent,
+}) => (
+  <div className="relative space-y-3">
+    <div className="relative">
+      <Icon className="absolute left-3 top-1/2 transform -translate-y-1/2 w-5 h-5 text-muted-foreground" />
+      <input
+        type="text"
+        value={query}
+        onChange={(e) => onQueryChange(e.target.value)}
+        placeholder={placeholder}
+        className="w-full pl-10 pr-10 py-2 rounded-lg border border-input bg-background focus:outline-none focus:ring-2 focus:ring-ring"
+      />
+      {isLoading && (
+        <LoadingSpinner className="absolute right-3 top-1/2 transform -translate-y-1/2 text-muted-foreground" />
+      )}
+    </div>
+
+    {debouncedQuery && results && results.length > 0 && (
+      <SearchResultsDropdown
+        results={results}
+        onSelect={onSelect}
+      />
+    )}
+
+    {debouncedQuery && results && results.length === 0 && noResultsContent}
+  </div>
+);
diff --git a/web/src/components/shared/search/LoadButtons.tsx b/web/src/components/shared/search/LoadButtons.tsx
new file mode 100644
index 00000000..e609a77d
--- /dev/null
+++ b/web/src/components/shared/search/LoadButtons.tsx
@@ -0,0 +1,30 @@
+import React from 'react';
+
+interface LoadButtonsProps {
+  onLoadClean: () => void;
+  onLoadAdd: () => void;
+  disabled?: boolean;
+}
+
+export const LoadButtons: React.FC<LoadButtonsProps> = ({
+  onLoadClean,
+  onLoadAdd,
+  disabled = false,
+}) => (
+  <div className="flex gap-2">
+    <button
+      onClick={onLoadClean}
+      disabled={disabled}
+      className="flex-1 px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed"
+    >
+      Load into Clean Graph
+    </button>
+    <button
+      onClick={onLoadAdd}
+      disabled={disabled}
+      className="flex-1 px-4 py-2 bg-secondary text-secondary-foreground rounded-lg hover:bg-secondary/80 transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed"
+    >
+      Add to Existing Graph
+    </button>
+  </div>
+);
diff --git a/web/src/components/shared/search/PathResults.tsx b/web/src/components/shared/search/PathResults.tsx
new file mode 100644
index 00000000..a66f9cbc
--- /dev/null
+++ b/web/src/components/shared/search/PathResults.tsx
@@ -0,0 +1,103 @@
+import React from 'react';
+import { LoadingSpinner } from '../LoadingSpinner';
+
+interface PathResultsProps {
+  pathResults: any;
+  selectedPath: any;
+  isLoading: boolean;
+  onSelectPath: (path: any) => void;
+  onLoadClean: () => void;
+  onLoadAdd: () => void;
+}
+
+export const PathResults: React.FC<PathResultsProps> = ({
+  pathResults,
+  selectedPath,
+  isLoading,
+  onSelectPath,
+  onLoadClean,
+  onLoadAdd,
+}) => {
+  if (isLoading) {
+    return (
+      <div className="flex items-center justify-center gap-2 py-4 text-sm text-muted-foreground">
+        <LoadingSpinner />
+        Searching...
+      </div>
+    );
+  }
+
+  if (!pathResults) return null;
+
+  if (pathResults.error) {
+    return (
+      <div className="p-4 bg-destructive/10 border border-destructive/20 rounded-lg text-center text-destructive text-sm">
+        {pathResults.error}
+      </div>
+    );
+  }
+
+  if (pathResults.count === 0) {
+    return (
+      <div className="p-4 bg-muted rounded-lg text-center text-muted-foreground text-sm">
+        No paths found. Try lowering similarity or increasing max hops.
+      </div>
+    );
+  }
+
+  return (
+    <div className="space-y-3">
+      <div className="text-sm text-muted-foreground">
+        Found {pathResults.count} path{pathResults.count > 1 ? 's' : ''} ({pathResults.paths[0].hops} hop{pathResults.paths[0].hops > 1 ? 's' : ''})
+      </div>
+
+      <div className="space-y-2">
+        <div className="text-xs text-muted-foreground uppercase tracking-wide">Select a path:</div>
+        {pathResults.paths.map((path: any, index: number) => (
+          <button
+            key={index}
+            onClick={() => onSelectPath(path)}
+            className={`w-full text-left p-3 rounded-lg border transition-colors ${
+              selectedPath === path
+                ? 'border-primary bg-primary/10'
+                : 'border-border bg-muted hover:border-primary/50'
+            }`}
+          >
+            <div className="text-sm font-mono">
+              {path.nodes
+                .filter((node: any) => node.id && node.id !== '')
+                .map((node: any, i: number) => (
+                  <span key={i}>
+                    {i > 0 && <span className="text-muted-foreground"> &rarr; </span>}
+                    <span className="font-medium">{node.label}</span>
+                  </span>
+                ))}
+            </div>
+            {path.score && (
+              <div className="text-xs text-muted-foreground mt-1">
+                Score: {(path.score * 100).toFixed(1)}%
+              </div>
+            )}
+          </button>
+        ))}
+      </div>
+
+      {selectedPath && (
+        <div className="flex gap-2">
+          <button
+            onClick={onLoadClean}
+            className="flex-1 px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium"
+          >
+            Load into Clean Graph
+          </button>
+          <button
+            onClick={onLoadAdd}
+            className="flex-1 px-4 py-2 bg-secondary text-secondary-foreground rounded-lg hover:bg-secondary/80 transition-colors text-sm font-medium"
+          >
+            Add to Existing Graph
+          </button>
+        </div>
+      )}
+    </div>
+  );
+};
diff --git a/web/src/components/shared/search/SelectedConceptChip.tsx b/web/src/components/shared/search/SelectedConceptChip.tsx
new file mode 100644
index 00000000..71264e70
--- /dev/null
+++ b/web/src/components/shared/search/SelectedConceptChip.tsx
@@ -0,0 +1,28 @@
+import React from 'react';
+
+interface SelectedConceptChipProps {
+  label: string;
+  conceptLabel: string;
+  onClear: () => void;
+}
+
+export const SelectedConceptChip: React.FC<SelectedConceptChipProps> = ({
+  label,
+  conceptLabel,
+  onClear,
+}) => (
+  <div className="p-3 bg-muted rounded-lg">
+    <div className="flex items-start justify-between">
+      <div>
+        <div className="text-xs text-muted-foreground mb-1">{label}</div>
+        <div className="font-medium">{conceptLabel}</div>
+      </div>
+      <button
+        onClick={onClear}
+        className="text-sm text-muted-foreground hover:text-foreground"
+      >
+        Change
+      </button>
+    </div>
+  </div>
+);
diff --git a/web/src/components/shared/search/SliderControl.tsx b/web/src/components/shared/search/SliderControl.tsx
new file mode 100644
index 00000000..8192c5fc
--- /dev/null
+++ b/web/src/components/shared/search/SliderControl.tsx
@@ -0,0 +1,47 @@
+import React from 'react';
+
+interface SliderControlProps {
+  label: string;
+  value: number;
+  min: number;
+  max: number;
+  onChange: (value: number) => void;
+  displayValue?: string;
+  unit?: string;
+}
+
+export const SliderControl: React.FC<SliderControlProps> = ({
+  label,
+  value,
+  min,
+  max,
+  onChange,
+  displayValue,
+  unit,
+}) => (
+  <div className="flex items-center gap-3 px-1">
+    <label className="text-sm text-muted-foreground whitespace-nowrap">
+      {label}
+    </label>
+    <input
+      type="range"
+      min={min}
+      max={max}
+      value={value}
+      onChange={(e) => onChange(parseInt(e.target.value))}
+      className="flex-1 h-2 bg-muted rounded-lg appearance-none cursor-pointer
+                 [&::-webkit-slider-thumb]:appearance-none [&::-webkit-slider-thumb]:w-4 [&::-webkit-slider-thumb]:h-4
+                 [&::-webkit-slider-thumb]:rounded-full [&::-webkit-slider-thumb]:bg-primary
+                 [&::-moz-range-thumb]:w-4 [&::-moz-range-thumb]:h-4
+                 [&::-moz-range-thumb]:rounded-full [&::-moz-range-thumb]:bg-primary [&::-moz-range-thumb]:border-0"
+    />
+    <span className="text-sm font-medium min-w-[3ch] text-right">
+      {displayValue ?? value}
+    </span>
+    {unit && (
+      <span className="text-xs text-muted-foreground whitespace-nowrap">
+        {unit}
+      </span>
+    )}
+  </div>
+);
diff --git a/web/src/components/shared/search/index.ts b/web/src/components/shared/search/index.ts
new file mode 100644
index 00000000..140fe2e0
--- /dev/null
+++ b/web/src/components/shared/search/index.ts
@@ -0,0 +1,5 @@
+export { ConceptSearchInput } from './ConceptSearchInput';
+export { SelectedConceptChip } from './SelectedConceptChip';
+export { SliderControl } from './SliderControl';
+export { LoadButtons } from './LoadButtons';
+export { PathResults } from './PathResults';

From e2355096c55d036ec2a7431454c74573e2d92917 Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 15:31:50 -0600
Subject: [PATCH 02/23] refactor: unify SearchParams with parameter-presence
 model
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace mode-discriminated SearchParams (mode: concept|neighborhood|path)
with parameter-presence model where mode is derived:
- primaryConceptId only → explore (covers old concept + neighborhood)
- primaryConceptId + destinationConceptId → path
- depth controls neighborhood expansion (1=concept, >1=neighborhood)

Add deriveMode() helper function. Collapse ExplorerView from 3 React
Query hooks to 2 (explore + path). Update URL sync with short params
(c, to, d, h, s) and backward-compatible legacy URL parsing.

SearchBar still uses three tabs but maps to the new param shape.
---
 web/src/components/shared/SearchBar.tsx |  11 +-
 web/src/store/graphStore.ts             |  41 +++--
 web/src/views/ExplorerView.tsx          | 202 ++++++++++--------------
 3 files changed, 119 insertions(+), 135 deletions(-)

diff --git a/web/src/components/shared/SearchBar.tsx b/web/src/components/shared/SearchBar.tsx
index 0e84fab1..2c1f6224 100644
--- a/web/src/components/shared/SearchBar.tsx
+++ b/web/src/components/shared/SearchBar.tsx
@@ -168,8 +168,10 @@ LIMIT 50`);
   const handleLoadConcept = (loadMode: 'clean' | 'add') => {
     if (!selectedConcept) return;
     setSearchParams({
-      mode: 'concept',
-      conceptId: selectedConcept.concept_id,
+      primaryConceptId: selectedConcept.concept_id,
+      primaryConceptLabel: selectedConcept.label,
+      depth: 1,
+      maxHops: 5,
       loadMode,
     });
   };
@@ -177,9 +179,10 @@ LIMIT 50`);
   const handleLoadNeighborhood = (loadMode: 'clean' | 'add') => {
     if (!selectedCenterConcept) return;
     setSearchParams({
-      mode: 'neighborhood',
-      centerConceptId: selectedCenterConcept.concept_id,
+      primaryConceptId: selectedCenterConcept.concept_id,
+      primaryConceptLabel: selectedCenterConcept.label,
       depth: neighborhoodDepth,
+      maxHops: 5,
       loadMode,
     });
   };
diff --git a/web/src/store/graphStore.ts b/web/src/store/graphStore.ts
index 4bd57ea4..d817caaf 100644
--- a/web/src/store/graphStore.ts
+++ b/web/src/store/graphStore.ts
@@ -26,28 +26,36 @@ interface UISettings {
   highlightNeighbors: boolean;
 }
 
-// Search parameters - describes WHAT to query, not HOW to query it
-// SearchBar sets these, App.tsx reacts to them
-export type SearchMode = 'concept' | 'neighborhood' | 'path' | null;
+// Search parameters — parameter-presence model where mode is derived, not declared.
+// SearchBar sets these, ExplorerView reacts to them.
 export type QueryMode = 'smart-search' | 'block-builder' | 'cypher-editor';
 
 export interface SearchParams {
-  mode: SearchMode;
+  // Primary concept (always present for any search)
+  primaryConceptId?: string;
+  primaryConceptLabel?: string;
 
-  // Concept mode
-  conceptId?: string;
+  // Neighborhood depth (1 = immediate neighbors, >1 = deeper expansion)
+  depth: number;
 
-  // Neighborhood mode
-  centerConceptId?: string;
-  depth?: number;
+  // Destination concept (presence triggers path mode)
+  destinationConceptId?: string;
+  destinationConceptLabel?: string;
 
-  // Path mode
-  fromConceptId?: string;
-  toConceptId?: string;
-  maxHops?: number;
+  // Path parameters (only relevant when destination is set)
+  maxHops: number;
 
-  // Shared parameters
-  loadMode?: 'clean' | 'add'; // Replace graph or add to existing
+  // Load behavior
+  loadMode: 'clean' | 'add';
+}
+
+// Derived from which parameters are populated — never stored explicitly
+export type DerivedMode = 'idle' | 'explore' | 'path';
+
+export function deriveMode(params: SearchParams): DerivedMode {
+  if (!params.primaryConceptId) return 'idle';
+  if (params.destinationConceptId) return 'path';
+  return 'explore';
 }
 
 interface GraphStore {
@@ -159,7 +167,8 @@ const defaultUISettings: UISettings = {
 };
 
 const defaultSearchParams: SearchParams = {
-  mode: null,
+  depth: 1,
+  maxHops: 5,
   loadMode: 'clean',
 };
 
diff --git a/web/src/views/ExplorerView.tsx b/web/src/views/ExplorerView.tsx
index df97952d..68e5f8a4 100644
--- a/web/src/views/ExplorerView.tsx
+++ b/web/src/views/ExplorerView.tsx
@@ -13,7 +13,7 @@ import { useSearchParams, useNavigate } from 'react-router-dom';
 import { History, Settings, Trash2 } from 'lucide-react';
 import { SearchBar } from '../components/shared/SearchBar';
 import { IconRailPanel } from '../components/shared/IconRailPanel';
-import { useGraphStore } from '../store/graphStore';
+import { useGraphStore, deriveMode } from '../store/graphStore';
 import { useReportStore } from '../store/reportStore';
 import { useQueryDefinitionStore } from '../store/queryDefinitionStore';
 import type { GraphReportData } from '../store/reportStore';
@@ -59,6 +59,9 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
   // Track if we're initializing from URL to prevent loops
   const initializingFromUrl = React.useRef(false);
 
+  // Derive mode from current params
+  const mode = deriveMode(searchParams);
+
   // Load saved queries on mount
   useEffect(() => {
     loadSavedQueries();
@@ -69,138 +72,101 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     setSelectedExplorer(explorerType);
   }, [explorerType, setSelectedExplorer]);
 
-  // Initialize from URL parameters on mount
+  // Initialize from URL parameters on mount (supports both new and legacy URL formats)
   useEffect(() => {
-    const conceptId = urlParams.get('conceptId');
-    const mode = urlParams.get('mode') as 'concept' | 'neighborhood' | 'path' | null;
-    const similarity = urlParams.get('similarity');
-    const depth = urlParams.get('depth');
-    const fromConceptId = urlParams.get('fromConceptId');
-    const toConceptId = urlParams.get('toConceptId');
-    const maxHops = urlParams.get('maxHops');
-
-    if (conceptId && mode) {
+    // New format: c=conceptId, to=destId, d=depth, h=maxHops, s=similarity
+    // Legacy format: mode=concept|neighborhood|path, conceptId=X, fromConceptId=X, etc.
+    const primaryId = urlParams.get('c') || urlParams.get('conceptId');
+    const destId = urlParams.get('to') || urlParams.get('toConceptId');
+    const depth = parseInt(urlParams.get('d') || urlParams.get('depth') || '0');
+    const maxHops = parseInt(urlParams.get('h') || urlParams.get('maxHops') || '5');
+    const similarity = urlParams.get('s') || urlParams.get('similarity');
+
+    // Legacy path mode used fromConceptId instead of conceptId
+    const legacyMode = urlParams.get('mode');
+    const legacyFromId = urlParams.get('fromConceptId');
+
+    if (legacyMode === 'path' && legacyFromId) {
+      // Legacy path URL
       initializingFromUrl.current = true;
-
-      if (mode === 'concept') {
-        // Concept mode: load single concept with similar concepts
-        setSearchParams({
-          mode: 'concept',
-          conceptId: conceptId,
-          loadMode: 'clean',
-        });
-        if (similarity) {
-          setSimilarityThreshold(parseFloat(similarity));
-        }
-      } else if (mode === 'neighborhood') {
-        // Neighborhood mode: load subgraph around concept
-        setSearchParams({
-          mode: 'neighborhood',
-          centerConceptId: conceptId,
-          depth: depth ? parseInt(depth) : 2,
-          loadMode: 'clean',
-        });
-      }
-
-      // Reset flag after a tick to allow URL sync to run
-      setTimeout(() => {
-        initializingFromUrl.current = false;
-      }, 100);
-    } else if (mode === 'path' && fromConceptId && toConceptId) {
+      setSearchParams({
+        primaryConceptId: legacyFromId,
+        destinationConceptId: destId || undefined,
+        depth: depth || 1,
+        maxHops,
+        loadMode: 'clean',
+      });
+      setTimeout(() => { initializingFromUrl.current = false; }, 100);
+    } else if (primaryId) {
+      // New format or legacy concept/neighborhood URL
       initializingFromUrl.current = true;
 
-      // Path mode: find connection between concepts
+      const effectiveDepth = depth || (legacyMode === 'neighborhood' ? 2 : 1);
+
       setSearchParams({
-        mode: 'path',
-        fromConceptId: fromConceptId,
-        toConceptId: toConceptId,
-        maxHops: maxHops ? parseInt(maxHops) : 5,
-        depth: depth ? parseInt(depth) : undefined,
+        primaryConceptId: primaryId,
+        destinationConceptId: destId || undefined,
+        depth: effectiveDepth,
+        maxHops,
         loadMode: 'clean',
       });
 
-      setTimeout(() => {
-        initializingFromUrl.current = false;
-      }, 100);
+      if (similarity) {
+        setSimilarityThreshold(parseFloat(similarity));
+      }
+
+      setTimeout(() => { initializingFromUrl.current = false; }, 100);
     }
   }, [urlParams, setSearchParams, setSimilarityThreshold]);
 
-  // Sync store state → URL parameters (bidirectional)
+  // Sync store state → URL parameters
   useEffect(() => {
-    // Don't update URL if we're initializing from URL
     if (initializingFromUrl.current) return;
-
-    // Don't update URL if no search params set
-    if (!searchParams.mode) return;
+    if (mode === 'idle') return;
 
     const newParams = new URLSearchParams();
 
-    if (searchParams.mode === 'concept' && searchParams.conceptId) {
-      newParams.set('conceptId', searchParams.conceptId);
-      newParams.set('mode', 'concept');
-      newParams.set('similarity', similarityThreshold.toString());
-    } else if (searchParams.mode === 'neighborhood' && searchParams.centerConceptId) {
-      newParams.set('conceptId', searchParams.centerConceptId);
-      newParams.set('mode', 'neighborhood');
-      newParams.set('depth', (searchParams.depth || 2).toString());
-    } else if (searchParams.mode === 'path' && searchParams.fromConceptId && searchParams.toConceptId) {
-      newParams.set('mode', 'path');
-      newParams.set('fromConceptId', searchParams.fromConceptId);
-      newParams.set('toConceptId', searchParams.toConceptId);
-      newParams.set('maxHops', (searchParams.maxHops || 5).toString());
-      if (searchParams.depth) {
-        newParams.set('depth', searchParams.depth.toString());
+    if (searchParams.primaryConceptId) {
+      newParams.set('c', searchParams.primaryConceptId);
+      newParams.set('d', searchParams.depth.toString());
+
+      if (searchParams.destinationConceptId) {
+        newParams.set('to', searchParams.destinationConceptId);
+        newParams.set('h', searchParams.maxHops.toString());
       }
+
+      newParams.set('s', similarityThreshold.toString());
     }
 
-    // Only update URL if params have changed
     const currentParams = urlParams.toString();
     const updatedParams = newParams.toString();
     if (currentParams !== updatedParams) {
-      setUrlParams(newParams, { replace: true }); // Use replace to avoid cluttering history
-    }
-  }, [searchParams, similarityThreshold, urlParams, setUrlParams]);
-
-  // React to searchParams - fetch data based on mode
-  // Concept mode: load single concept with neighbors
-  const { data: conceptData, isLoading: isLoadingConcept } = useSubgraph(
-    searchParams.mode === 'concept' ? searchParams.conceptId || null : null,
-    {
-      depth: 1,
-      enabled: searchParams.mode === 'concept' && !!searchParams.conceptId,
+      setUrlParams(newParams, { replace: true });
     }
-  );
+  }, [searchParams, similarityThreshold, mode, urlParams, setUrlParams]);
 
-  // Neighborhood mode: load subgraph with specified depth
-  const { data: neighborhoodData, isLoading: isLoadingNeighborhood } = useSubgraph(
-    searchParams.mode === 'neighborhood' ? searchParams.centerConceptId || null : null,
+  // Explore mode: subgraph around primary concept (covers old concept + neighborhood)
+  const { data: exploreData, isLoading: isLoadingExplore } = useSubgraph(
+    mode === 'explore' ? searchParams.primaryConceptId || null : null,
     {
-      depth: searchParams.depth || 2,
-      enabled: searchParams.mode === 'neighborhood' && !!searchParams.centerConceptId,
+      depth: searchParams.depth,
+      enabled: mode === 'explore' && !!searchParams.primaryConceptId,
     }
   );
 
-  // Path mode: find paths between two concepts
+  // Path mode: find paths between primary and destination
   const { data: pathData, isLoading: isLoadingPath, error: pathError } = useFindConnection(
-    searchParams.mode === 'path' ? searchParams.fromConceptId || null : null,
-    searchParams.mode === 'path' ? searchParams.toConceptId || null : null,
+    mode === 'path' ? searchParams.primaryConceptId || null : null,
+    mode === 'path' ? searchParams.destinationConceptId || null : null,
     {
-      maxHops: searchParams.maxHops || 5,
-      enabled: searchParams.mode === 'path' && !!searchParams.fromConceptId && !!searchParams.toConceptId,
+      maxHops: searchParams.maxHops,
+      enabled: mode === 'path' && !!searchParams.primaryConceptId && !!searchParams.destinationConceptId,
     }
   );
 
-  // Update rawGraphData when query results come back (cache API data)
+  // Update rawGraphData when query results come back
   useEffect(() => {
-    // Mode-aware data selection: use data from the active query mode only
-    // (prevents stale cached data from a previous mode shadowing new results)
-    let newData;
-    switch (searchParams.mode) {
-      case 'concept': newData = conceptData; break;
-      case 'neighborhood': newData = neighborhoodData; break;
-      case 'path': newData = pathData; break;
-      default: newData = conceptData || neighborhoodData || pathData;
-    }
+    const newData = mode === 'path' ? pathData : exploreData;
     if (!newData) return;
 
     const graphPayload = { nodes: newData.nodes || [], links: newData.links || [] };
@@ -211,9 +177,9 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     } else if (searchParams.loadMode === 'add') {
       mergeRawGraphData(graphPayload);
     }
-  }, [conceptData, neighborhoodData, pathData, searchParams.loadMode, searchParams.mode]);
+  }, [exploreData, pathData, searchParams.loadMode, mode]);
 
-  const isLoading = isLoadingConcept || isLoadingNeighborhood || isLoadingPath;
+  const isLoading = isLoadingExplore || isLoadingPath;
   const error = pathError;
   const graphData = storeGraphData;
 
@@ -255,16 +221,22 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
 
   const ExplorerComponent = explorerPlugin.component;
 
-  // Stable callback for node clicks to prevent simulation restarts
+  // Follow Concept: load clicked node's neighborhood
   const handleNodeClick = useCallback((nodeId: string) => {
-    // Follow Concept: Load clicked node's neighborhood
     const store = useGraphStore.getState();
+
+    // Resolve label from current graph data for SearchBar display
+    const nodeLabel = store.rawGraphData?.nodes?.find(
+      (n: any) => (n.concept_id || n.id) === nodeId
+    )?.label;
+
     store.setFocusedNodeId(nodeId);
     store.setSearchParams({
-      mode: 'neighborhood',
-      centerConceptId: nodeId,
-      depth: 2, // Default depth for Follow Concept
-      loadMode: 'add', // Add to existing graph
+      primaryConceptId: nodeId,
+      primaryConceptLabel: nodeLabel,
+      depth: 2,
+      maxHops: 5,
+      loadMode: 'add',
     });
   }, []);
 
@@ -290,21 +262,21 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
         grounding_strength: l.grounding_strength,
       })),
       searchParams: {
-        mode: searchParams.mode || 'unknown',
-        conceptId: searchParams.conceptId || searchParams.centerConceptId,
+        mode: mode === 'idle' ? 'unknown' : mode,
+        conceptId: searchParams.primaryConceptId,
         depth: searchParams.depth,
       },
     };
 
     await addReport({
-      name: '', // Will auto-generate name based on content
+      name: '',
       type: 'graph',
       data: reportData,
       sourceExplorer: explorerType === 'force-3d' ? '3d' : '2d',
     });
 
     navigate('/report');
-  }, [rawGraphData, searchParams, explorerType, addReport, navigate]);
+  }, [rawGraphData, searchParams, mode, explorerType, addReport, navigate]);
 
   // Load a saved query
   const handleLoadQuery = useCallback((query: any) => {
@@ -461,10 +433,10 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
                 <div className="text-sm text-muted-foreground">
                   <p>Tips:</p>
                   <ul className="mt-2 space-y-1 text-left">
-                    <li>• Use the search bar above to find concepts</li>
-                    <li>• Click nodes to explore connections</li>
-                    <li>• Use the sidebar for saved queries and settings</li>
-                    <li>• Drag nodes to reposition them</li>
+                    <li>Search for a concept above to find concepts</li>
+                    <li>Click nodes to explore connections</li>
+                    <li>Use the sidebar for saved queries and settings</li>
+                    <li>Drag nodes to reposition them</li>
                   </ul>
                 </div>
               </div>

From baf17dcf84536137814591d325f84308c19cb91f Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 15:35:34 -0600
Subject: [PATCH 03/23] refactor: replace three search tabs with unified
 progressive interface
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Remove SmartSearchSubMode pill selector and per-mode state. Single search
flow progressively reveals controls as parameters are populated: search →
concept chip + depth slider + load buttons → optional destination →
path controls. Mode is derived from parameter presence, matching the
store's deriveMode() pattern.
---
 web/src/components/shared/SearchBar.tsx | 644 +++++++++---------------
 1 file changed, 239 insertions(+), 405 deletions(-)

diff --git a/web/src/components/shared/SearchBar.tsx b/web/src/components/shared/SearchBar.tsx
index 2c1f6224..019941c4 100644
--- a/web/src/components/shared/SearchBar.tsx
+++ b/web/src/components/shared/SearchBar.tsx
@@ -1,14 +1,20 @@
 /**
- * Multi-Mode Smart Search Component
+ * Multi-Mode Search Component
  *
  * Top-level: Query mode selection via radio dial
- * - Smart Search (with sub-modes: Concept/Neighborhood/Path)
+ * - Smart Search (unified progressive interface)
  * - Block Builder
  * - openCypher Editor
+ *
+ * Smart Search is a single progressive flow:
+ * 1. Search for a concept → select it
+ * 2. Depth slider appears (1 = immediate, >1 = neighborhood)
+ * 3. Optional: add destination concept for path finding
+ * 4. Path mode: max hops + find paths + select + load
  */
 
-import React, { useState } from 'react';
-import { Search, Network, GitBranch, Blocks, Code, ChevronDown, ChevronRight } from 'lucide-react';
+import React, { useState, useEffect } from 'react';
+import { Search, GitBranch, Blocks, Code, ChevronDown, ChevronRight, Plus, X } from 'lucide-react';
 import { LoadingSpinner } from './LoadingSpinner';
 import { useSearchConcepts } from '../../hooks/useGraphData';
 import { useDebouncedValue } from '../../hooks/useDebouncedValue';
@@ -16,7 +22,6 @@ import { useGraphStore } from '../../store/graphStore';
 import { ModeDial } from './ModeDial';
 import { apiClient } from '../../api/client';
 import { BlockBuilder } from '../blocks/BlockBuilder';
-import { getZIndexClass } from '../../config/zIndex';
 import {
   ConceptSearchInput,
   SelectedConceptChip,
@@ -25,66 +30,40 @@ import {
   PathResults,
 } from './search';
 
-type SmartSearchSubMode = 'concept' | 'neighborhood' | 'path';
-
 export const SearchBar: React.FC = () => {
-  // Top-level mode (dial): smart-search, block-builder, cypher-editor - use store
+  // Top-level mode (dial)
   const { queryMode, setQueryMode, blockBuilderExpanded, setBlockBuilderExpanded } = useGraphStore();
 
-  // Smart Search sub-mode (pills)
-  const [smartSearchMode, setSmartSearchMode] = useState<SmartSearchSubMode>('concept');
-
-  // Collapsible sections state
-  const [expandedSections, setExpandedSections] = useState<Record<SmartSearchSubMode, boolean>>({
-    concept: true,
-    neighborhood: true,
-    path: true,
-  });
-
-  // Collapsible state for Smart Search
+  // Collapsible state
   const [smartSearchExpanded, setSmartSearchExpanded] = useState(true);
-
-  // Collapsible state for openCypher editor
   const [cypherEditorExpanded, setCypherEditorExpanded] = useState(true);
 
-  const toggleSmartSearch = () => {
-    setSmartSearchExpanded(!smartSearchExpanded);
-    setTimeout(() => window.dispatchEvent(new Event('resize')), 100);
-  };
-
-  const toggleSection = (mode: SmartSearchSubMode) => {
-    setExpandedSections(prev => ({ ...prev, [mode]: !prev[mode] }));
-    setTimeout(() => window.dispatchEvent(new Event('resize')), 100);
-  };
-
-  const toggleCypherEditor = () => {
-    setCypherEditorExpanded(!cypherEditorExpanded);
-    setTimeout(() => window.dispatchEvent(new Event('resize')), 100);
-  };
-
-  const toggleBlockBuilder = () => {
-    setBlockBuilderExpanded(!blockBuilderExpanded);
-    setTimeout(() => window.dispatchEvent(new Event('resize')), 100);
-  };
-
-  // Shared controls - use global similarity threshold from store
-  const { similarityThreshold: similarity, setSimilarityThreshold: setSimilarity } = useGraphStore();
-
-  // Concept mode state
-  const [conceptQuery, setConceptQuery] = useState('');
-  const [selectedConcept, setSelectedConcept] = useState<any>(null);
-
-  // Neighborhood mode state
-  const [neighborhoodQuery, setNeighborhoodQuery] = useState('');
-  const [selectedCenterConcept, setSelectedCenterConcept] = useState<any>(null);
-  const [neighborhoodDepth, setNeighborhoodDepth] = useState(2);
-
-  // Path mode state
-  const [pathFromQuery, setPathFromQuery] = useState('');
-  const [pathToQuery, setPathToQuery] = useState('');
-  const [selectedFromConcept, setSelectedFromConcept] = useState<any>(null);
-  const [selectedToConcept, setSelectedToConcept] = useState<any>(null);
+  const triggerResize = () => setTimeout(() => window.dispatchEvent(new Event('resize')), 100);
+
+  // Shared controls from store
+  const {
+    similarityThreshold: similarity,
+    setSimilarityThreshold: setSimilarity,
+    searchParams,
+    setSearchParams,
+    setRawGraphData,
+    mergeRawGraphData,
+    setGraphData,
+  } = useGraphStore();
+
+  // === UNIFIED SEARCH STATE ===
+  // Primary concept (the starting point for any search)
+  const [primaryQuery, setPrimaryQuery] = useState('');
+  const [selectedPrimary, setSelectedPrimary] = useState<any>(null);
+  const [depth, setDepth] = useState(1);
+
+  // Destination concept (optional — triggers path mode)
+  const [destinationQuery, setDestinationQuery] = useState('');
+  const [selectedDestination, setSelectedDestination] = useState<any>(null);
+  const [showDestination, setShowDestination] = useState(false);
   const [maxHops, setMaxHops] = useState(5);
+
+  // Path search state
   const [pathResults, setPathResults] = useState<any>(null);
   const [selectedPath, setSelectedPath] = useState<any>(null);
   const [isLoadingPath, setIsLoadingPath] = useState(false);
@@ -97,99 +76,95 @@ LIMIT 50`);
   const [isExecutingCypher, setIsExecutingCypher] = useState(false);
   const [cypherError, setCypherError] = useState<string | null>(null);
 
-  const { setSearchParams, setRawGraphData, mergeRawGraphData, setGraphData } = useGraphStore();
-
-  // Debounce values to prevent excessive API calls
-  const debouncedConceptQuery = useDebouncedValue(conceptQuery, 800);
-  const debouncedNeighborhoodQuery = useDebouncedValue(neighborhoodQuery, 800);
-  const debouncedPathFromQuery = useDebouncedValue(pathFromQuery, 800);
-  const debouncedPathToQuery = useDebouncedValue(pathToQuery, 800);
+  // Debounce values
+  const debouncedPrimaryQuery = useDebouncedValue(primaryQuery, 800);
+  const debouncedDestinationQuery = useDebouncedValue(destinationQuery, 800);
   const debouncedSimilarity = useDebouncedValue(similarity, 500);
 
-  // Search hooks (gated by mode + selection state)
-  const { data: conceptResults, isLoading: isLoadingConcepts } = useSearchConcepts(
-    debouncedConceptQuery,
+  // Search hooks
+  const { data: primaryResults, isLoading: isLoadingPrimary } = useSearchConcepts(
+    debouncedPrimaryQuery,
     {
       limit: 10,
       minSimilarity: debouncedSimilarity,
-      enabled: queryMode === 'smart-search' && smartSearchMode === 'concept' && !selectedConcept,
+      enabled: queryMode === 'smart-search' && !selectedPrimary,
     }
   );
 
-  const { data: neighborhoodSearchResults, isLoading: isLoadingNeighborhoodSearch } = useSearchConcepts(
-    debouncedNeighborhoodQuery,
+  const { data: destinationResults, isLoading: isLoadingDestination } = useSearchConcepts(
+    debouncedDestinationQuery,
     {
       limit: 10,
       minSimilarity: debouncedSimilarity,
-      enabled: queryMode === 'smart-search' && smartSearchMode === 'neighborhood' && !selectedCenterConcept,
+      enabled: queryMode === 'smart-search' && showDestination && !selectedDestination,
     }
   );
 
-  const { data: pathFromSearchResults, isLoading: isLoadingPathFromSearch } = useSearchConcepts(
-    debouncedPathFromQuery,
-    {
-      limit: 10,
-      minSimilarity: debouncedSimilarity,
-      enabled: queryMode === 'smart-search' && smartSearchMode === 'path' && !selectedFromConcept,
+  // Sync from store → local state when Follow Concept updates searchParams externally
+  useEffect(() => {
+    if (searchParams.primaryConceptId && searchParams.primaryConceptLabel) {
+      // External update (e.g., node click) — sync to local state
+      if (!selectedPrimary || selectedPrimary.concept_id !== searchParams.primaryConceptId) {
+        setSelectedPrimary({
+          concept_id: searchParams.primaryConceptId,
+          label: searchParams.primaryConceptLabel,
+        });
+        setPrimaryQuery('');
+        setDepth(searchParams.depth);
+      }
     }
-  );
+  }, [searchParams.primaryConceptId, searchParams.primaryConceptLabel]);
 
-  const { data: pathToSearchResults, isLoading: isLoadingPathToSearch } = useSearchConcepts(
-    debouncedPathToQuery,
-    {
-      limit: 10,
-      minSimilarity: debouncedSimilarity,
-      enabled: queryMode === 'smart-search' && smartSearchMode === 'path' && !selectedToConcept,
-    }
-  );
+  // === HANDLERS ===
 
-  // Selection handlers
-  const handleSelectConcept = (concept: any) => {
-    setSelectedConcept(concept);
-    setConceptQuery('');
+  const handleSelectPrimary = (concept: any) => {
+    setSelectedPrimary(concept);
+    setPrimaryQuery('');
   };
 
-  const handleSelectCenterConcept = (concept: any) => {
-    setSelectedCenterConcept(concept);
-    setNeighborhoodQuery('');
+  const handleClearPrimary = () => {
+    setSelectedPrimary(null);
+    setSelectedDestination(null);
+    setShowDestination(false);
+    setPathResults(null);
+    setSelectedPath(null);
+    setDepth(1);
   };
 
-  const handleSelectFromConcept = (concept: any) => {
-    setSelectedFromConcept(concept);
-    setPathFromQuery('');
+  const handleSelectDestination = (concept: any) => {
+    setSelectedDestination(concept);
+    setDestinationQuery('');
   };
 
-  const handleSelectToConcept = (concept: any) => {
-    setSelectedToConcept(concept);
-    setPathToQuery('');
+  const handleClearDestination = () => {
+    setSelectedDestination(null);
+    setPathResults(null);
+    setSelectedPath(null);
   };
 
-  // Load handlers
-  const handleLoadConcept = (loadMode: 'clean' | 'add') => {
-    if (!selectedConcept) return;
-    setSearchParams({
-      primaryConceptId: selectedConcept.concept_id,
-      primaryConceptLabel: selectedConcept.label,
-      depth: 1,
-      maxHops: 5,
-      loadMode,
-    });
+  const handleRemoveDestination = () => {
+    setShowDestination(false);
+    setSelectedDestination(null);
+    setDestinationQuery('');
+    setPathResults(null);
+    setSelectedPath(null);
   };
 
-  const handleLoadNeighborhood = (loadMode: 'clean' | 'add') => {
-    if (!selectedCenterConcept) return;
+  // Load explore (concept or neighborhood depending on depth)
+  const handleLoadExplore = (loadMode: 'clean' | 'add') => {
+    if (!selectedPrimary) return;
     setSearchParams({
-      primaryConceptId: selectedCenterConcept.concept_id,
-      primaryConceptLabel: selectedCenterConcept.label,
-      depth: neighborhoodDepth,
+      primaryConceptId: selectedPrimary.concept_id,
+      primaryConceptLabel: selectedPrimary.label,
+      depth,
       maxHops: 5,
       loadMode,
     });
   };
 
-  // Path search (manual, not auto)
+  // Path search (manual)
   const handleFindPaths = async () => {
-    if (!selectedFromConcept || !selectedToConcept) return;
+    if (!selectedPrimary || !selectedDestination) return;
 
     setIsLoadingPath(true);
     setPathResults(null);
@@ -197,8 +172,8 @@ LIMIT 50`);
 
     try {
       const result = await apiClient.findConnection({
-        from_id: selectedFromConcept.concept_id,
-        to_id: selectedToConcept.concept_id,
+        from_id: selectedPrimary.concept_id,
+        to_id: selectedDestination.concept_id,
         max_hops: maxHops,
       });
       setPathResults(result);
@@ -224,7 +199,6 @@ LIMIT 50`);
   const handleLoadPath = (loadMode: 'clean' | 'add') => {
     if (!selectedPath) return;
 
-    // Extract Concept nodes only (skip Source/Ontology with empty IDs)
     const conceptNodes: any[] = [];
     const conceptRelTypes: string[][] = [];
     let pendingRels: string[] = [];
@@ -285,18 +259,18 @@ LIMIT 50`);
       });
 
       const { transformForD3 } = await import('../../utils/graphTransform');
-      const nodes = result.nodes.map((n: any) => ({
+      const graphNodes = result.nodes.map((n: any) => ({
         concept_id: n.id,
         label: n.label,
         ontology: n.properties?.ontology || 'default',
       }));
-      const links = result.relationships.map((r: any) => ({
+      const graphLinks = result.relationships.map((r: any) => ({
         from_id: r.from_id,
         to_id: r.to_id,
         relationship_type: r.type,
       }));
 
-      const graphData = transformForD3(nodes, links);
+      const graphData = transformForD3(graphNodes, graphLinks);
       useGraphStore.getState().setGraphData(graphData);
     } catch (error: any) {
       console.error('Failed to execute Cypher query:', error);
@@ -308,10 +282,9 @@ LIMIT 50`);
 
   // Block builder → Cypher editor
   const handleSendToEditor = (compiledCypher: string) => {
-    const hasExistingCode = cypherQuery.trim().length > 0;
-    if (hasExistingCode) {
+    if (cypherQuery.trim().length > 0) {
       const confirmed = window.confirm(
-        'The openCypher editor already has code. Do you want to overwrite it with the compiled query from the block builder?'
+        'The openCypher editor already has code. Do you want to overwrite it?'
       );
       if (!confirmed) return;
     }
@@ -326,7 +299,7 @@ LIMIT 50`);
         return {
           icon: Search,
           title: 'Smart Search',
-          description: 'Find concepts using semantic similarity, explore neighborhoods, and discover paths between ideas',
+          description: 'Find concepts, explore neighborhoods, and discover paths between ideas',
         };
       case 'block-builder':
         return {
@@ -346,32 +319,32 @@ LIMIT 50`);
   const modeInfo = getModeInfo();
   const ModeIcon = modeInfo.icon;
 
-  // "No results" content for concept search (with below-threshold suggestions)
-  const conceptNoResults = conceptResults && conceptResults.results && conceptResults.results.length === 0 && (
+  // No-results content with below-threshold suggestions
+  const noResultsContent = primaryResults && primaryResults.results && primaryResults.results.length === 0 && (
     <div className="absolute top-full left-0 right-0 mt-2 bg-card border border-border rounded-lg shadow-lg p-4 z-50">
       <div className="text-center">
-        {conceptResults.below_threshold_count ? (
+        {primaryResults.below_threshold_count ? (
           <div className="space-y-3">
             <div className="text-muted-foreground">
               <div className="font-medium mb-2">No results at {(similarity * 100).toFixed(0)}% similarity</div>
               <div className="text-sm">
-                Found {conceptResults.below_threshold_count} concept{conceptResults.below_threshold_count > 1 ? 's' : ''} at lower similarity
+                Found {primaryResults.below_threshold_count} concept{primaryResults.below_threshold_count > 1 ? 's' : ''} at lower similarity
               </div>
             </div>
-            {conceptResults.suggested_threshold && (
+            {primaryResults.suggested_threshold && (
               <button
-                onClick={() => setSimilarity(conceptResults.suggested_threshold)}
+                onClick={() => setSimilarity(primaryResults.suggested_threshold)}
                 className="px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium"
               >
-                Try {(conceptResults.suggested_threshold * 100).toFixed(0)}% Similarity
+                Try {(primaryResults.suggested_threshold * 100).toFixed(0)}% Similarity
               </button>
             )}
-            {conceptResults.top_match && (
+            {primaryResults.top_match && (
               <div className="text-left p-3 bg-muted rounded-lg">
                 <div className="text-xs text-muted-foreground mb-1">Top match:</div>
-                <div className="font-medium">{conceptResults.top_match.label}</div>
+                <div className="font-medium">{primaryResults.top_match.label}</div>
                 <div className="text-sm text-muted-foreground mt-1">
-                  {(conceptResults.top_match.score * 100).toFixed(0)}% similarity
+                  {(primaryResults.top_match.score * 100).toFixed(0)}% similarity
                 </div>
               </div>
             )}
@@ -383,7 +356,7 @@ LIMIT 50`);
     </div>
   );
 
-  // Similarity slider shorthand
+  // Reusable similarity slider
   const similaritySlider = (
     <SliderControl
       label="Similarity:"
@@ -415,12 +388,11 @@ LIMIT 50`);
         <ModeDial mode={queryMode} onChange={setQueryMode} />
       </div>
 
-      {/* Smart Search Mode */}
+      {/* ===== SMART SEARCH (Unified Progressive) ===== */}
       {queryMode === 'smart-search' && (
         <div className="space-y-3">
-          {/* Collapsible Header */}
           <button
-            onClick={toggleSmartSearch}
+            onClick={() => { setSmartSearchExpanded(!smartSearchExpanded); triggerResize(); }}
             className="w-full flex items-center justify-between p-2 rounded-lg hover:bg-muted/50 transition-colors"
           >
             <div className="flex items-center gap-2">
@@ -435,232 +407,97 @@ LIMIT 50`);
           </button>
 
           {smartSearchExpanded && (
-            <>
-              {/* Sub-mode Selector (Pill Buttons) */}
-              <div className="flex gap-1 p-1 bg-muted rounded-lg">
-                <button
-                  onClick={() => setSmartSearchMode('concept')}
-                  className={`flex-1 flex items-center justify-center gap-2 px-4 py-2 rounded-md text-sm font-medium transition-colors ${
-                    smartSearchMode === 'concept'
-                      ? 'bg-background text-foreground shadow-sm'
-                      : 'text-muted-foreground hover:text-foreground'
-                  }`}
-                >
-                  <Search className="w-4 h-4" />
-                  Concept
-                </button>
-                <button
-                  onClick={() => setSmartSearchMode('neighborhood')}
-                  className={`flex-1 flex items-center justify-center gap-2 px-4 py-2 rounded-md text-sm font-medium transition-colors ${
-                    smartSearchMode === 'neighborhood'
-                      ? 'bg-background text-foreground shadow-sm'
-                      : 'text-muted-foreground hover:text-foreground'
-                  }`}
-                >
-                  <Network className="w-4 h-4" />
-                  Neighborhood
-                </button>
-                <button
-                  onClick={() => setSmartSearchMode('path')}
-                  className={`flex-1 flex items-center justify-center gap-2 px-4 py-2 rounded-md text-sm font-medium transition-colors ${
-                    smartSearchMode === 'path'
-                      ? 'bg-background text-foreground shadow-sm'
-                      : 'text-muted-foreground hover:text-foreground'
-                  }`}
-                >
-                  <GitBranch className="w-4 h-4" />
-                  Path
-                </button>
-              </div>
-
-              {/* ===== CONCEPT MODE ===== */}
-              {smartSearchMode === 'concept' && (
+            <div className="space-y-3">
+              {/* Stage 1: Search for primary concept */}
+              {!selectedPrimary ? (
                 <div className="space-y-3">
-                  <button
-                    onClick={() => toggleSection('concept')}
-                    className="w-full flex items-center justify-between p-2 rounded-lg hover:bg-muted/50 transition-colors"
-                  >
-                    <div className="flex items-center gap-2">
-                      <Search className="w-4 h-4 text-muted-foreground" />
-                      <span className="text-sm font-medium">Search for Concept</span>
-                    </div>
-                    {expandedSections.concept ? (
-                      <ChevronDown className="w-4 h-4 text-muted-foreground" />
-                    ) : (
-                      <ChevronRight className="w-4 h-4 text-muted-foreground" />
-                    )}
-                  </button>
-
-                  {expandedSections.concept && (
-                    <>
-                      {!selectedConcept ? (
-                        <div className="space-y-3">
-                          <ConceptSearchInput
-                            query={conceptQuery}
-                            onQueryChange={setConceptQuery}
-                            placeholder="Search for a concept..."
-                            icon={Search}
-                            isLoading={isLoadingConcepts}
-                            results={conceptResults?.results}
-                            debouncedQuery={debouncedConceptQuery}
-                            onSelect={handleSelectConcept}
-                            noResultsContent={conceptNoResults}
-                          />
-                          {similaritySlider}
-                        </div>
-                      ) : (
-                        <div className="space-y-3">
-                          <SelectedConceptChip
-                            label="Selected concept:"
-                            conceptLabel={selectedConcept.label}
-                            onClear={() => setSelectedConcept(null)}
-                          />
-                          {similaritySlider}
-                          <LoadButtons
-                            onLoadClean={() => handleLoadConcept('clean')}
-                            onLoadAdd={() => handleLoadConcept('add')}
-                          />
-                        </div>
-                      )}
-                    </>
-                  )}
+                  <ConceptSearchInput
+                    query={primaryQuery}
+                    onQueryChange={setPrimaryQuery}
+                    placeholder="Search for a concept..."
+                    icon={Search}
+                    isLoading={isLoadingPrimary}
+                    results={primaryResults?.results}
+                    debouncedQuery={debouncedPrimaryQuery}
+                    onSelect={handleSelectPrimary}
+                    noResultsContent={noResultsContent}
+                  />
+                  {similaritySlider}
                 </div>
-              )}
-
-              {/* ===== NEIGHBORHOOD MODE ===== */}
-              {smartSearchMode === 'neighborhood' && (
+              ) : (
+                /* Stage 2+: Primary selected — show controls */
                 <div className="space-y-3">
-                  <button
-                    onClick={() => toggleSection('neighborhood')}
-                    className="w-full flex items-center justify-between p-2 rounded-lg hover:bg-muted/50 transition-colors"
-                  >
-                    <div className="flex items-center gap-2">
-                      <Network className="w-4 h-4 text-muted-foreground" />
-                      <span className="text-sm font-medium">Explore Neighborhood</span>
-                    </div>
-                    {expandedSections.neighborhood ? (
-                      <ChevronDown className="w-4 h-4 text-muted-foreground" />
-                    ) : (
-                      <ChevronRight className="w-4 h-4 text-muted-foreground" />
-                    )}
-                  </button>
-
-                  {expandedSections.neighborhood && (
-                    <>
-                      {!selectedCenterConcept ? (
-                        <div className="space-y-3">
-                          <ConceptSearchInput
-                            query={neighborhoodQuery}
-                            onQueryChange={setNeighborhoodQuery}
-                            placeholder="Search for center concept..."
-                            icon={Network}
-                            isLoading={isLoadingNeighborhoodSearch}
-                            results={neighborhoodSearchResults?.results}
-                            debouncedQuery={debouncedNeighborhoodQuery}
-                            onSelect={handleSelectCenterConcept}
-                          />
-                          {similaritySlider}
-                        </div>
-                      ) : (
-                        <div className="space-y-3">
-                          <SelectedConceptChip
-                            label="Center concept:"
-                            conceptLabel={selectedCenterConcept.label}
-                            onClear={() => setSelectedCenterConcept(null)}
-                          />
-                          <SliderControl
-                            label="Depth:"
-                            value={neighborhoodDepth}
-                            min={1}
-                            max={5}
-                            onChange={setNeighborhoodDepth}
-                            unit={`hop${neighborhoodDepth > 1 ? 's' : ''}`}
-                          />
-                          <LoadButtons
-                            onLoadClean={() => handleLoadNeighborhood('clean')}
-                            onLoadAdd={() => handleLoadNeighborhood('add')}
-                          />
-                        </div>
-                      )}
-                    </>
+                  <SelectedConceptChip
+                    label="Concept:"
+                    conceptLabel={selectedPrimary.label}
+                    onClear={handleClearPrimary}
+                  />
+
+                  {similaritySlider}
+
+                  <SliderControl
+                    label="Depth:"
+                    value={depth}
+                    min={1}
+                    max={5}
+                    onChange={setDepth}
+                    unit={`hop${depth > 1 ? 's' : ''}`}
+                  />
+
+                  {/* Load buttons (explore mode — no destination) */}
+                  {!showDestination && (
+                    <LoadButtons
+                      onLoadClean={() => handleLoadExplore('clean')}
+                      onLoadAdd={() => handleLoadExplore('add')}
+                    />
                   )}
-                </div>
-              )}
 
-              {/* ===== PATH MODE ===== */}
-              {smartSearchMode === 'path' && (
-                <div className="space-y-3">
-                  <button
-                    onClick={() => toggleSection('path')}
-                    className="w-full flex items-center justify-between p-2 rounded-lg hover:bg-muted/50 transition-colors"
-                  >
-                    <div className="flex items-center gap-2">
-                      <GitBranch className="w-4 h-4 text-muted-foreground" />
-                      <span className="text-sm font-medium">Find Paths Between Concepts</span>
-                    </div>
-                    {expandedSections.path ? (
-                      <ChevronDown className="w-4 h-4 text-muted-foreground" />
-                    ) : (
-                      <ChevronRight className="w-4 h-4 text-muted-foreground" />
-                    )}
-                  </button>
-
-                  {expandedSections.path && (
-                    <>
-                      {/* Step 1: Select From concept */}
-                      {!selectedFromConcept ? (
-                        <div className="space-y-3">
-                          <ConceptSearchInput
-                            query={pathFromQuery}
-                            onQueryChange={setPathFromQuery}
-                            placeholder="Search for starting concept..."
-                            icon={GitBranch}
-                            isLoading={isLoadingPathFromSearch}
-                            results={pathFromSearchResults?.results}
-                            debouncedQuery={debouncedPathFromQuery}
-                            onSelect={handleSelectFromConcept}
-                          />
-                          {similaritySlider}
+                  {/* Destination toggle / search */}
+                  {!showDestination ? (
+                    <button
+                      onClick={() => setShowDestination(true)}
+                      className="w-full flex items-center justify-center gap-2 px-3 py-2 text-sm text-muted-foreground hover:text-foreground border border-dashed border-border rounded-lg hover:border-primary/50 transition-colors"
+                    >
+                      <Plus className="w-4 h-4" />
+                      Find path to another concept
+                    </button>
+                  ) : (
+                    <div className="space-y-3 pt-2 border-t border-border">
+                      {/* Destination header with close button */}
+                      <div className="flex items-center justify-between">
+                        <div className="flex items-center gap-2 text-sm text-muted-foreground">
+                          <GitBranch className="w-4 h-4" />
+                          <span className="font-medium">Path Destination</span>
                         </div>
-                      ) : !selectedToConcept ? (
-                        /* Step 2: Select To concept */
+                        <button
+                          onClick={handleRemoveDestination}
+                          className="text-muted-foreground hover:text-foreground p-1"
+                          title="Remove destination"
+                        >
+                          <X className="w-4 h-4" />
+                        </button>
+                      </div>
+
+                      {!selectedDestination ? (
+                        /* Search for destination */
+                        <ConceptSearchInput
+                          query={destinationQuery}
+                          onQueryChange={setDestinationQuery}
+                          placeholder="Search for destination concept..."
+                          icon={GitBranch}
+                          isLoading={isLoadingDestination}
+                          results={destinationResults?.results}
+                          debouncedQuery={debouncedDestinationQuery}
+                          onSelect={handleSelectDestination}
+                        />
+                      ) : (
+                        /* Both selected — path controls */
                         <div className="space-y-3">
                           <SelectedConceptChip
-                            label="From concept:"
-                            conceptLabel={selectedFromConcept.label}
-                            onClear={() => setSelectedFromConcept(null)}
-                          />
-                          <ConceptSearchInput
-                            query={pathToQuery}
-                            onQueryChange={setPathToQuery}
-                            placeholder="Search for target concept..."
-                            icon={GitBranch}
-                            isLoading={isLoadingPathToSearch}
-                            results={pathToSearchResults?.results}
-                            debouncedQuery={debouncedPathToQuery}
-                            onSelect={handleSelectToConcept}
+                            label="Destination:"
+                            conceptLabel={selectedDestination.label}
+                            onClear={handleClearDestination}
                           />
-                        </div>
-                      ) : (
-                        /* Step 3: Both selected — configure and search */
-                        <div className="space-y-3">
-                          <div className="space-y-2">
-                            <SelectedConceptChip
-                              label="From concept:"
-                              conceptLabel={selectedFromConcept.label}
-                              onClear={() => {
-                                setSelectedFromConcept(null);
-                                setSelectedToConcept(null);
-                              }}
-                            />
-                            <SelectedConceptChip
-                              label="To concept:"
-                              conceptLabel={selectedToConcept.label}
-                              onClear={() => setSelectedToConcept(null)}
-                            />
-                          </div>
-
-                          {similaritySlider}
 
                           <SliderControl
                             label="Max Hops:"
@@ -670,7 +507,6 @@ LIMIT 50`);
                             onChange={setMaxHops}
                           />
 
-                          {/* Find Paths Button */}
                           <button
                             onClick={handleFindPaths}
                             disabled={isLoadingPath}
@@ -696,11 +532,11 @@ LIMIT 50`);
                           />
                         </div>
                       )}
-                    </>
+                    </div>
                   )}
                 </div>
               )}
-            </>
+            </div>
           )}
         </div>
       )}
@@ -709,7 +545,7 @@ LIMIT 50`);
       {queryMode === 'block-builder' && (
         <div className="space-y-3">
           <button
-            onClick={toggleBlockBuilder}
+            onClick={() => { setBlockBuilderExpanded(!blockBuilderExpanded); triggerResize(); }}
             className="w-full flex items-center justify-between p-2 rounded-lg hover:bg-muted/50 transition-colors"
           >
             <div className="flex items-center gap-2">
@@ -735,7 +571,7 @@ LIMIT 50`);
       {queryMode === 'cypher-editor' && (
         <div className="space-y-3">
           <button
-            onClick={toggleCypherEditor}
+            onClick={() => { setCypherEditorExpanded(!cypherEditorExpanded); triggerResize(); }}
             className="w-full flex items-center justify-between p-2 rounded-lg hover:bg-muted/50 transition-colors"
           >
             <div className="flex items-center gap-2">
@@ -750,52 +586,50 @@ LIMIT 50`);
           </button>
 
           {cypherEditorExpanded && (
-            <>
-              <div className="space-y-2">
-                <textarea
-                  value={cypherQuery}
-                  onChange={(e) => setCypherQuery(e.target.value)}
-                  placeholder="Enter openCypher query..."
-                  className="w-full h-48 px-3 py-2 font-mono text-sm rounded-lg border border-input bg-background focus:outline-none focus:ring-2 focus:ring-ring resize-y"
-                  spellCheck={false}
-                />
-
-                {cypherError && (
-                  <div className="p-3 bg-destructive/10 border border-destructive/20 rounded-lg text-sm text-destructive">
-                    {cypherError}
-                  </div>
+            <div className="space-y-2">
+              <textarea
+                value={cypherQuery}
+                onChange={(e) => setCypherQuery(e.target.value)}
+                placeholder="Enter openCypher query..."
+                className="w-full h-48 px-3 py-2 font-mono text-sm rounded-lg border border-input bg-background focus:outline-none focus:ring-2 focus:ring-ring resize-y"
+                spellCheck={false}
+              />
+
+              {cypherError && (
+                <div className="p-3 bg-destructive/10 border border-destructive/20 rounded-lg text-sm text-destructive">
+                  {cypherError}
+                </div>
+              )}
+
+              <button
+                onClick={handleExecuteCypher}
+                disabled={isExecutingCypher || !cypherQuery.trim()}
+                className="w-full px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed flex items-center justify-center gap-2"
+              >
+                {isExecutingCypher ? (
+                  <>
+                    <LoadingSpinner className="text-primary-foreground" />
+                    Executing Query...
+                  </>
+                ) : (
+                  <>
+                    <Code className="w-4 h-4" />
+                    Execute Query
+                  </>
                 )}
+              </button>
 
-                <button
-                  onClick={handleExecuteCypher}
-                  disabled={isExecutingCypher || !cypherQuery.trim()}
-                  className="w-full px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed flex items-center justify-center gap-2"
-                >
-                  {isExecutingCypher ? (
-                    <>
-                      <LoadingSpinner className="text-primary-foreground" />
-                      Executing Query...
-                    </>
-                  ) : (
-                    <>
-                      <Code className="w-4 h-4" />
-                      Execute Query
-                    </>
-                  )}
-                </button>
-
-                <div className="text-xs text-muted-foreground space-y-1">
-                  <div className="font-medium">Example queries:</div>
-                  <div className="font-mono bg-muted p-2 rounded">
-                    <div>MATCH (c:Concept) WHERE c.label CONTAINS 'organizational' RETURN c LIMIT 10</div>
-                    <div className="mt-1">{'MATCH (c:Concept)-[r:IMPLIES]->(n:Concept) RETURN c, r, n LIMIT 50'}</div>
-                  </div>
-                  <div className="text-muted-foreground/70 mt-2">
-                    Results are automatically loaded into the graph visualization.
-                  </div>
+              <div className="text-xs text-muted-foreground space-y-1">
+                <div className="font-medium">Example queries:</div>
+                <div className="font-mono bg-muted p-2 rounded">
+                  <div>MATCH (c:Concept) WHERE c.label CONTAINS 'organizational' RETURN c LIMIT 10</div>
+                  <div className="mt-1">{'MATCH (c:Concept)-[r:IMPLIES]->(n:Concept) RETURN c, r, n LIMIT 50'}</div>
+                </div>
+                <div className="text-muted-foreground/70 mt-2">
+                  Results are automatically loaded into the graph visualization.
                 </div>
               </div>
-            </>
+            </div>
           )}
         </div>
       )}

From 4e48c247b5e58cc8c298184b77f7593ae70feba1 Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 15:40:40 -0600
Subject: [PATCH 04/23] feat: add path enrichment for neighborhood context
 around path nodes

New usePathEnrichment hook uses React Query useQueries to fetch subgraph
neighborhoods around each path node in parallel. Performance guards cap
enrichment depth at 2 and skip enrichment for paths with >50 nodes.

In path mode, the depth slider becomes "Context" (range 0-2, default 0).
Setting context > 0 expands neighborhoods around each path node,
providing richer graph context for the discovered connections.
---
 web/src/components/shared/SearchBar.tsx | 35 ++++++++---
 web/src/hooks/useGraphData.ts           | 81 ++++++++++++++++++++++++-
 web/src/views/ExplorerView.tsx          | 26 +++++++-
 3 files changed, 131 insertions(+), 11 deletions(-)

diff --git a/web/src/components/shared/SearchBar.tsx b/web/src/components/shared/SearchBar.tsx
index 019941c4..c9eec7a0 100644
--- a/web/src/components/shared/SearchBar.tsx
+++ b/web/src/components/shared/SearchBar.tsx
@@ -148,6 +148,7 @@ LIMIT 50`);
     setDestinationQuery('');
     setPathResults(null);
     setSelectedPath(null);
+    setDepth(1); // Reset to explore default
   };
 
   // Load explore (concept or neighborhood depending on depth)
@@ -195,8 +196,8 @@ LIMIT 50`);
     }
   };
 
-  // Load selected path directly into graph
-  const handleLoadPath = (loadMode: 'clean' | 'add') => {
+  // Load selected path directly into graph, with optional neighborhood enrichment
+  const handleLoadPath = async (loadMode: 'clean' | 'add') => {
     if (!selectedPath) return;
 
     const conceptNodes: any[] = [];
@@ -241,6 +242,26 @@ LIMIT 50`);
       mergeRawGraphData({ nodes, links });
     }
 
+    // Enrich path nodes with neighborhood context
+    if (depth > 0 && conceptNodes.length <= 50) {
+      const enrichDepth = Math.min(depth, 2);
+      const idsToEnrich = conceptNodes.map((n) => n.id).filter(Boolean);
+      if (idsToEnrich.length > 0) {
+        try {
+          const enrichments = await Promise.all(
+            idsToEnrich.map((id: string) =>
+              apiClient.getSubgraph({ center_concept_id: id, depth: enrichDepth })
+            )
+          );
+          for (const data of enrichments) {
+            mergeRawGraphData({ nodes: data.nodes, links: data.links });
+          }
+        } catch (error) {
+          console.error('Path enrichment failed:', error);
+        }
+      }
+    }
+
     setPathResults(null);
     setSelectedPath(null);
   };
@@ -436,12 +457,12 @@ LIMIT 50`);
                   {similaritySlider}
 
                   <SliderControl
-                    label="Depth:"
+                    label={showDestination ? "Context:" : "Depth:"}
                     value={depth}
-                    min={1}
-                    max={5}
+                    min={showDestination ? 0 : 1}
+                    max={showDestination ? 2 : 5}
                     onChange={setDepth}
-                    unit={`hop${depth > 1 ? 's' : ''}`}
+                    unit={showDestination && depth === 0 ? 'none' : `hop${depth !== 1 ? 's' : ''}`}
                   />
 
                   {/* Load buttons (explore mode — no destination) */}
@@ -455,7 +476,7 @@ LIMIT 50`);
                   {/* Destination toggle / search */}
                   {!showDestination ? (
                     <button
-                      onClick={() => setShowDestination(true)}
+                      onClick={() => { setShowDestination(true); setDepth(0); }}
                       className="w-full flex items-center justify-center gap-2 px-3 py-2 text-sm text-muted-foreground hover:text-foreground border border-dashed border-border rounded-lg hover:border-primary/50 transition-colors"
                     >
                       <Plus className="w-4 h-4" />
diff --git a/web/src/hooks/useGraphData.ts b/web/src/hooks/useGraphData.ts
index 3ccb6210..3fcfab38 100644
--- a/web/src/hooks/useGraphData.ts
+++ b/web/src/hooks/useGraphData.ts
@@ -5,7 +5,8 @@
  * loading states, and automatic refetching.
  */
 
-import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { useMemo } from 'react';
+import { useQuery, useQueries, useQueryClient } from '@tanstack/react-query';
 import { apiClient } from '../api/client';
 import { transformForD3 } from '../utils/graphTransform';
 
@@ -303,6 +304,84 @@ export function useTimeline(
   });
 }
 
+/**
+ * Enrich path nodes with neighborhood context.
+ * Fetches subgraphs around each node in parallel and merges results.
+ *
+ * Performance guards:
+ * - Enrichment depth capped at 2
+ * - Skipped if more than 50 nodes
+ */
+export function usePathEnrichment(
+  nodeIds: string[],
+  depth: number,
+  options?: { enabled?: boolean }
+) {
+  const enrichDepth = Math.min(depth, 2);
+  const shouldEnrich =
+    options?.enabled !== false &&
+    enrichDepth > 0 &&
+    nodeIds.length > 0 &&
+    nodeIds.length <= 50;
+
+  const queries = useQueries({
+    queries: shouldEnrich
+      ? nodeIds.map((id) => ({
+          queryKey: ['subgraph', id, enrichDepth],
+          queryFn: async () => {
+            const response = await apiClient.getSubgraph({
+              center_concept_id: id,
+              depth: enrichDepth,
+            });
+            return { nodes: response.nodes, links: response.links };
+          },
+          staleTime: 5 * 60 * 1000,
+        }))
+      : [],
+  });
+
+  const isLoading = queries.some((q) => q.isLoading);
+  const isSuccess = queries.length > 0 && queries.every((q) => q.isSuccess);
+
+  // Use dataUpdatedAt timestamps to create a stable memo dependency
+  const dataVersion = queries.map((q) => q.dataUpdatedAt).join(',');
+
+  const data = useMemo(() => {
+    if (!isSuccess) return null;
+
+    const allNodes = new Map<string, any>();
+    const linkKeys = new Set<string>();
+    const allLinks: any[] = [];
+
+    queries.forEach((q) => {
+      if (q.data) {
+        const result = q.data as { nodes: any[]; links: any[] };
+        result.nodes.forEach((n: any) => {
+          const id = n.concept_id || n.id;
+          if (id && !allNodes.has(id)) allNodes.set(id, n);
+        });
+        result.links.forEach((l: any) => {
+          const from = l.from_id || l.source;
+          const to = l.to_id || l.target;
+          const type = l.relationship_type || l.type || '';
+          const key = `${from}-${type}-${to}`;
+          if (!linkKeys.has(key)) {
+            linkKeys.add(key);
+            allLinks.push(l);
+          }
+        });
+      }
+    });
+
+    return allNodes.size > 0
+      ? { nodes: Array.from(allNodes.values()), links: allLinks }
+      : null;
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [isSuccess, dataVersion]);
+
+  return { data, isLoading };
+}
+
 /**
  * Prefetch subgraph for a concept
  * Useful for preloading data when hovering over nodes
diff --git a/web/src/views/ExplorerView.tsx b/web/src/views/ExplorerView.tsx
index 68e5f8a4..c45553d8 100644
--- a/web/src/views/ExplorerView.tsx
+++ b/web/src/views/ExplorerView.tsx
@@ -8,7 +8,7 @@
  * - Saved queries management (ADR-083)
  */
 
-import React, { useState, useEffect, useCallback } from 'react';
+import React, { useState, useEffect, useCallback, useMemo } from 'react';
 import { useSearchParams, useNavigate } from 'react-router-dom';
 import { History, Settings, Trash2 } from 'lucide-react';
 import { SearchBar } from '../components/shared/SearchBar';
@@ -17,7 +17,7 @@ import { useGraphStore, deriveMode } from '../store/graphStore';
 import { useReportStore } from '../store/reportStore';
 import { useQueryDefinitionStore } from '../store/queryDefinitionStore';
 import type { GraphReportData } from '../store/reportStore';
-import { useSubgraph, useFindConnection } from '../hooks/useGraphData';
+import { useSubgraph, useFindConnection, usePathEnrichment } from '../hooks/useGraphData';
 import { getExplorer } from '../explorers';
 import { getZIndexValue } from '../config/zIndex';
 import type { VisualizationType } from '../types/explorer';
@@ -164,6 +164,20 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     }
   );
 
+  // Path enrichment: expand neighborhoods around path nodes when depth > 0
+  const pathNodeIds = useMemo(() => {
+    if (mode !== 'path' || !pathData?.nodes) return [];
+    return pathData.nodes
+      .map((n: any) => n.concept_id || n.id)
+      .filter(Boolean);
+  }, [mode, pathData]);
+
+  const { data: enrichmentData, isLoading: isLoadingEnrichment } = usePathEnrichment(
+    pathNodeIds,
+    searchParams.depth,
+    { enabled: mode === 'path' && pathNodeIds.length > 0 }
+  );
+
   // Update rawGraphData when query results come back
   useEffect(() => {
     const newData = mode === 'path' ? pathData : exploreData;
@@ -179,7 +193,13 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     }
   }, [exploreData, pathData, searchParams.loadMode, mode]);
 
-  const isLoading = isLoadingExplore || isLoadingPath;
+  // Merge path enrichment data when it arrives
+  useEffect(() => {
+    if (!enrichmentData) return;
+    mergeRawGraphData(enrichmentData);
+  }, [enrichmentData]);
+
+  const isLoading = isLoadingExplore || isLoadingPath || isLoadingEnrichment;
   const error = pathError;
   const graphData = storeGraphData;
 

From d5ca9498202729c2aadce6b5fa7697e2a9271d45 Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 16:16:50 -0600
Subject: [PATCH 05/23] fix: make SearchBar controls responsive at narrow
 widths

Add min-w-0 and overflow-hidden through the flex chain so controls
shrink gracefully instead of clipping off-screen. Concept labels
in SelectedConceptChip now truncate with ellipsis.
---
 web/src/components/shared/SearchBar.tsx                  | 2 +-
 web/src/components/shared/search/SelectedConceptChip.tsx | 8 ++++----
 web/src/components/shared/search/SliderControl.tsx       | 2 +-
 web/src/views/ExplorerView.tsx                           | 2 +-
 4 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/web/src/components/shared/SearchBar.tsx b/web/src/components/shared/SearchBar.tsx
index c9eec7a0..c82c3f89 100644
--- a/web/src/components/shared/SearchBar.tsx
+++ b/web/src/components/shared/SearchBar.tsx
@@ -390,7 +390,7 @@ LIMIT 50`);
   );
 
   return (
-    <div className="relative space-y-4">
+    <div className="relative space-y-4 min-w-0 overflow-hidden">
       {/* Header with Mode Info and Dial */}
       <div className="flex items-start justify-between gap-4">
         <div className="flex gap-3 flex-1">
diff --git a/web/src/components/shared/search/SelectedConceptChip.tsx b/web/src/components/shared/search/SelectedConceptChip.tsx
index 71264e70..8dd0f985 100644
--- a/web/src/components/shared/search/SelectedConceptChip.tsx
+++ b/web/src/components/shared/search/SelectedConceptChip.tsx
@@ -11,11 +11,11 @@ export const SelectedConceptChip: React.FC<SelectedConceptChipProps> = ({
   conceptLabel,
   onClear,
 }) => (
-  <div className="p-3 bg-muted rounded-lg">
-    <div className="flex items-start justify-between">
-      <div>
+  <div className="p-3 bg-muted rounded-lg overflow-hidden">
+    <div className="flex items-start justify-between gap-2 min-w-0">
+      <div className="min-w-0">
         <div className="text-xs text-muted-foreground mb-1">{label}</div>
-        <div className="font-medium">{conceptLabel}</div>
+        <div className="font-medium truncate">{conceptLabel}</div>
       </div>
       <button
         onClick={onClear}
diff --git a/web/src/components/shared/search/SliderControl.tsx b/web/src/components/shared/search/SliderControl.tsx
index 8192c5fc..68ef3174 100644
--- a/web/src/components/shared/search/SliderControl.tsx
+++ b/web/src/components/shared/search/SliderControl.tsx
@@ -19,7 +19,7 @@ export const SliderControl: React.FC<SliderControlProps> = ({
   displayValue,
   unit,
 }) => (
-  <div className="flex items-center gap-3 px-1">
+  <div className="flex items-center gap-3 px-1 min-w-0">
     <label className="text-sm text-muted-foreground whitespace-nowrap">
       {label}
     </label>
diff --git a/web/src/views/ExplorerView.tsx b/web/src/views/ExplorerView.tsx
index c45553d8..bc2c4e32 100644
--- a/web/src/views/ExplorerView.tsx
+++ b/web/src/views/ExplorerView.tsx
@@ -415,7 +415,7 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
           className="border-b border-border bg-card"
           style={{ zIndex: getZIndexValue('searchBar') }}
         >
-          <div className="p-4">
+          <div className="p-4 min-w-0 overflow-hidden">
             <SearchBar />
           </div>
         </div>

From ab73d55b56509ac136c54cc430ef3ca5222665db Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 16:19:05 -0600
Subject: [PATCH 06/23] refactor: move graph settings to sidebar, remove
 duplicate similarity slider
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move GraphSettingsPanel and Settings3DPanel from floating PanelStack
overlays into the sidebar Settings tab. Add embedded prop to both panels
to strip floating-card chrome when rendered inside the sidebar.

Remove the duplicate similarity threshold slider from the sidebar —
SearchBar owns it as part of the search workflow. The graph canvas now
only shows Legend and StatsPanel overlays.
---
 .../explorers/ForceGraph2D/ForceGraph2D.tsx   |  8 ----
 .../explorers/ForceGraph3D/ForceGraph3D.tsx   | 16 -------
 web/src/explorers/common/3DSettingsPanel.tsx  | 11 +++--
 .../explorers/common/GraphSettingsPanel.tsx   | 11 +++--
 web/src/views/ExplorerView.tsx                | 48 ++++++++++++-------
 5 files changed, 46 insertions(+), 48 deletions(-)

diff --git a/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx b/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx
index 0a856d41..d9a802ec 100644
--- a/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx
+++ b/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx
@@ -20,7 +20,6 @@ import {
   NodeInfoBox,
   EdgeInfoBox,
   StatsPanel,
-  GraphSettingsPanel,
   Legend,
   PanelStack,
   useGraphNavigation,
@@ -1750,13 +1749,6 @@ export const ForceGraph2D: React.FC<
           )}
         </div>
 
-        {onSettingsChange && (
-          <GraphSettingsPanel
-            settings={settings}
-            onChange={onSettingsChange}
-            sliderRanges={SLIDER_RANGES}
-          />
-        )}
       </PanelStack>
 
       {/* Unified Context Menu (context-aware for node vs background) */}
diff --git a/web/src/explorers/ForceGraph3D/ForceGraph3D.tsx b/web/src/explorers/ForceGraph3D/ForceGraph3D.tsx
index d50f3744..9c8cf0e1 100644
--- a/web/src/explorers/ForceGraph3D/ForceGraph3D.tsx
+++ b/web/src/explorers/ForceGraph3D/ForceGraph3D.tsx
@@ -26,8 +26,6 @@ import {
   NodeInfoBox,
   EdgeInfoBox,
   StatsPanel,
-  Settings3DPanel,
-  GraphSettingsPanel,
   Legend,
   PanelStack,
   useGraphNavigation,
@@ -1946,20 +1944,6 @@ export const ForceGraph3D: React.FC<
           )}
         </div>
 
-        {onSettingsChange && (
-          <GraphSettingsPanel
-            settings={settings}
-            onChange={onSettingsChange}
-            sliderRanges={SLIDER_RANGES}
-          />
-        )}
-
-        {onSettingsChange && (
-          <Settings3DPanel
-            camera={settings.camera}
-            onCameraChange={(camera) => onSettingsChange({ ...settings, camera })}
-          />
-        )}
       </PanelStack>
 
       {/* Unified Context Menu (context-aware for node vs background) */}
diff --git a/web/src/explorers/common/3DSettingsPanel.tsx b/web/src/explorers/common/3DSettingsPanel.tsx
index c1d8bd5f..fd59cbc9 100644
--- a/web/src/explorers/common/3DSettingsPanel.tsx
+++ b/web/src/explorers/common/3DSettingsPanel.tsx
@@ -18,11 +18,13 @@ interface Camera3DSettings {
 interface Settings3DPanelProps {
   camera: Camera3DSettings;
   onCameraChange: (camera: Camera3DSettings) => void;
+  embedded?: boolean;
 }
 
 export const Settings3DPanel: React.FC<Settings3DPanelProps> = ({
   camera,
   onCameraChange,
+  embedded = false,
 }) => {
   const [expandedSections, setExpandedSections] = useState<Set<string>>(new Set(['camera']));
 
@@ -55,11 +57,14 @@ export const Settings3DPanel: React.FC<Settings3DPanelProps> = ({
 
   return (
     <div
-      className="bg-card/95 border border-border rounded-lg shadow-xl flex flex-col"
-      style={{ width: '280px', maxHeight: '95vh' }}
+      className={embedded
+        ? "flex flex-col"
+        : "bg-card/95 border border-border rounded-lg shadow-xl flex flex-col"
+      }
+      style={embedded ? undefined : { width: '280px', maxHeight: '95vh' }}
     >
       {/* Content */}
-      <div className="overflow-y-auto overflow-x-hidden p-3 space-y-3">
+      <div className={`overflow-y-auto overflow-x-hidden ${embedded ? '' : 'p-3'} space-y-3`}>
         {/* Camera Section */}
         <div>
           <button
diff --git a/web/src/explorers/common/GraphSettingsPanel.tsx b/web/src/explorers/common/GraphSettingsPanel.tsx
index 6ce97d17..3a28aa26 100644
--- a/web/src/explorers/common/GraphSettingsPanel.tsx
+++ b/web/src/explorers/common/GraphSettingsPanel.tsx
@@ -57,12 +57,14 @@ interface GraphSettingsPanelProps<T extends GraphSettings> {
   settings: T;
   onChange: (settings: T) => void;
   sliderRanges: SliderRanges;
+  embedded?: boolean;
 }
 
 export const GraphSettingsPanel = <T extends GraphSettings>({
   settings,
   onChange,
   sliderRanges,
+  embedded = false,
 }: GraphSettingsPanelProps<T>) => {
   const [expandedSections, setExpandedSections] = useState<Set<string>>(new Set());
 
@@ -101,11 +103,14 @@ export const GraphSettingsPanel = <T extends GraphSettings>({
 
   return (
     <div
-      className="bg-card/95 border border-border rounded-lg shadow-xl flex flex-col"
-      style={{ width: '280px', maxHeight: '95vh' }}
+      className={embedded
+        ? "flex flex-col"
+        : "bg-card/95 border border-border rounded-lg shadow-xl flex flex-col"
+      }
+      style={embedded ? undefined : { width: '280px', maxHeight: '95vh' }}
     >
       {/* Content */}
-      <div className="overflow-y-auto overflow-x-hidden p-3 space-y-3">
+      <div className={`overflow-y-auto overflow-x-hidden ${embedded ? '' : 'p-3'} space-y-3`}>
         {/* Physics Section */}
         <div className="border-b border-border pb-3">
           <button
diff --git a/web/src/views/ExplorerView.tsx b/web/src/views/ExplorerView.tsx
index bc2c4e32..2b111506 100644
--- a/web/src/views/ExplorerView.tsx
+++ b/web/src/views/ExplorerView.tsx
@@ -19,6 +19,10 @@ import { useQueryDefinitionStore } from '../store/queryDefinitionStore';
 import type { GraphReportData } from '../store/reportStore';
 import { useSubgraph, useFindConnection, usePathEnrichment } from '../hooks/useGraphData';
 import { getExplorer } from '../explorers';
+import { GraphSettingsPanel } from '../explorers/common/GraphSettingsPanel';
+import { Settings3DPanel } from '../explorers/common/3DSettingsPanel';
+import { SLIDER_RANGES as SLIDER_RANGES_2D } from '../explorers/ForceGraph2D/types';
+import { SLIDER_RANGES as SLIDER_RANGES_3D } from '../explorers/ForceGraph3D/types';
 import { getZIndexValue } from '../config/zIndex';
 import type { VisualizationType } from '../types/explorer';
 
@@ -228,6 +232,9 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     }
   }, [explorerPlugin, explorerType]);
 
+  // Slider ranges for the current explorer's settings panel
+  const sliderRanges = explorerType === 'force-3d' ? SLIDER_RANGES_3D : SLIDER_RANGES_2D;
+
   if (!explorerPlugin) {
     return (
       <div className="flex items-center justify-center h-full">
@@ -358,27 +365,32 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     </div>
   );
 
-  // Settings panel content
+  // Settings panel content — graph settings (physics, visual, interaction)
   const settingsPanelContent = (
     <div className="p-3 space-y-4">
-      <div>
-        <div className="flex items-center justify-between mb-2">
-          <label className="text-sm font-medium">Similarity Threshold</label>
-          <span className="text-sm font-mono text-primary">{Math.round(similarityThreshold * 100)}%</span>
+      {explorerSettings?.physics ? (
+        <>
+          <GraphSettingsPanel
+            settings={explorerSettings}
+            onChange={setExplorerSettings}
+            sliderRanges={sliderRanges}
+            embedded
+          />
+          {explorerType === 'force-3d' && explorerSettings.camera && (
+            <Settings3DPanel
+              camera={explorerSettings.camera}
+              onCameraChange={(camera) =>
+                setExplorerSettings({ ...explorerSettings, camera })
+              }
+              embedded
+            />
+          )}
+        </>
+      ) : (
+        <div className="text-center text-muted-foreground text-sm py-4">
+          <p>No settings for this explorer</p>
         </div>
-        <input
-          type="range"
-          min="0.3"
-          max="0.95"
-          step="0.05"
-          value={similarityThreshold}
-          onChange={(e) => setSimilarityThreshold(parseFloat(e.target.value))}
-          className="w-full"
-        />
-        <p className="text-xs text-muted-foreground mt-1">
-          Minimum similarity for concept search
-        </p>
-      </div>
+      )}
     </div>
   );
 

From e4b9ff9c2e77a53442a2b61eef48adb50bb8faa6 Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 16:38:35 -0600
Subject: [PATCH 07/23] fix: remove overflow-hidden that clipped search results
 dropdown

The overflow-hidden added for responsive layout was preventing the
absolutely-positioned SearchResultsDropdown from escaping its container
to overlay the graph canvas. min-w-0 alone handles flex shrinking.
---
 web/src/components/shared/SearchBar.tsx | 2 +-
 web/src/views/ExplorerView.tsx          | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/web/src/components/shared/SearchBar.tsx b/web/src/components/shared/SearchBar.tsx
index c82c3f89..68da5880 100644
--- a/web/src/components/shared/SearchBar.tsx
+++ b/web/src/components/shared/SearchBar.tsx
@@ -390,7 +390,7 @@ LIMIT 50`);
   );
 
   return (
-    <div className="relative space-y-4 min-w-0 overflow-hidden">
+    <div className="relative space-y-4 min-w-0">
       {/* Header with Mode Info and Dial */}
       <div className="flex items-start justify-between gap-4">
         <div className="flex gap-3 flex-1">
diff --git a/web/src/views/ExplorerView.tsx b/web/src/views/ExplorerView.tsx
index 2b111506..2e663113 100644
--- a/web/src/views/ExplorerView.tsx
+++ b/web/src/views/ExplorerView.tsx
@@ -427,7 +427,7 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
           className="border-b border-border bg-card"
           style={{ zIndex: getZIndexValue('searchBar') }}
         >
-          <div className="p-4 min-w-0 overflow-hidden">
+          <div className="p-4 min-w-0">
             <SearchBar />
           </div>
         </div>

From ed58ef02f35690ecfe518462ac2135da15e9cc18 Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 16:40:25 -0600
Subject: [PATCH 08/23] fix: theme scrollbars to match harmony color system

Add scrollbar styling using CSS custom properties so scrollbar thumb
and track colors adapt to light, dark, and twilight modes. Uses both
standard scrollbar-color property and WebKit pseudo-elements.
---
 web/src/index.css | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/web/src/index.css b/web/src/index.css
index dc1f7ce1..28a48e58 100644
--- a/web/src/index.css
+++ b/web/src/index.css
@@ -135,6 +135,34 @@
     font-family: var(--font-mono);
   }
 
+  /* Themed scrollbars - inherit from harmony color system */
+  * {
+    scrollbar-color: hsl(var(--border)) transparent;
+    scrollbar-width: thin;
+  }
+
+  *::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+  }
+
+  *::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  *::-webkit-scrollbar-thumb {
+    background: hsl(var(--border));
+    border-radius: var(--radius);
+  }
+
+  *::-webkit-scrollbar-thumb:hover {
+    background: hsl(var(--muted-foreground));
+  }
+
+  *::-webkit-scrollbar-corner {
+    background: transparent;
+  }
+
   /* Form element accent colors - use primary (warm amber) */
   input[type="checkbox"],
   input[type="radio"],

From 5e30a7ee0d3fb2b5d10750375bdf7d988df5932f Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 16:45:56 -0600
Subject: [PATCH 09/23] fix: add-to-existing-graph now merges instead of
 resetting

The URL init effect was re-triggering on every URL change (caused by
store-to-URL sync), overwriting loadMode back to 'clean'. Fixed by
running URL initialization only once per mount using a ref guard.

Also give both load buttons equal visual weight (both secondary) and
highlight the last-clicked button with primary color for feedback.
---
 .../components/shared/search/LoadButtons.tsx  | 46 +++++++++++--------
 web/src/views/ExplorerView.tsx                | 22 ++++-----
 2 files changed, 38 insertions(+), 30 deletions(-)

diff --git a/web/src/components/shared/search/LoadButtons.tsx b/web/src/components/shared/search/LoadButtons.tsx
index e609a77d..108f894d 100644
--- a/web/src/components/shared/search/LoadButtons.tsx
+++ b/web/src/components/shared/search/LoadButtons.tsx
@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { useState } from 'react';
 
 interface LoadButtonsProps {
   onLoadClean: () => void;
@@ -10,21 +10,29 @@ export const LoadButtons: React.FC<LoadButtonsProps> = ({
   onLoadClean,
   onLoadAdd,
   disabled = false,
-}) => (
-  <div className="flex gap-2">
-    <button
-      onClick={onLoadClean}
-      disabled={disabled}
-      className="flex-1 px-4 py-2 bg-primary text-primary-foreground rounded-lg hover:bg-primary/90 transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed"
-    >
-      Load into Clean Graph
-    </button>
-    <button
-      onClick={onLoadAdd}
-      disabled={disabled}
-      className="flex-1 px-4 py-2 bg-secondary text-secondary-foreground rounded-lg hover:bg-secondary/80 transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed"
-    >
-      Add to Existing Graph
-    </button>
-  </div>
-);
+}) => {
+  const [lastUsed, setLastUsed] = useState<'clean' | 'add' | null>(null);
+
+  const base = "flex-1 px-4 py-2 rounded-lg transition-colors text-sm font-medium disabled:opacity-50 disabled:cursor-not-allowed";
+  const active = "bg-primary text-primary-foreground hover:bg-primary/90";
+  const inactive = "bg-secondary text-secondary-foreground hover:bg-secondary/80";
+
+  return (
+    <div className="flex gap-2">
+      <button
+        onClick={() => { setLastUsed('clean'); onLoadClean(); }}
+        disabled={disabled}
+        className={`${base} ${lastUsed === 'clean' ? active : inactive}`}
+      >
+        Load into Clean Graph
+      </button>
+      <button
+        onClick={() => { setLastUsed('add'); onLoadAdd(); }}
+        disabled={disabled}
+        className={`${base} ${lastUsed === 'add' ? active : inactive}`}
+      >
+        Add to Existing Graph
+      </button>
+    </div>
+  );
+};
diff --git a/web/src/views/ExplorerView.tsx b/web/src/views/ExplorerView.tsx
index 2e663113..0a433681 100644
--- a/web/src/views/ExplorerView.tsx
+++ b/web/src/views/ExplorerView.tsx
@@ -60,8 +60,8 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
   // UI state for IconRailPanel
   const [activeTab, setActiveTab] = useState('history');
 
-  // Track if we're initializing from URL to prevent loops
-  const initializingFromUrl = React.useRef(false);
+  // Track if we've already initialized from URL (run once on mount)
+  const hasInitializedFromUrl = React.useRef(false);
 
   // Derive mode from current params
   const mode = deriveMode(searchParams);
@@ -76,8 +76,10 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     setSelectedExplorer(explorerType);
   }, [explorerType, setSelectedExplorer]);
 
-  // Initialize from URL parameters on mount (supports both new and legacy URL formats)
+  // Initialize from URL parameters once on mount
   useEffect(() => {
+    if (hasInitializedFromUrl.current) return;
+
     // New format: c=conceptId, to=destId, d=depth, h=maxHops, s=similarity
     // Legacy format: mode=concept|neighborhood|path, conceptId=X, fromConceptId=X, etc.
     const primaryId = urlParams.get('c') || urlParams.get('conceptId');
@@ -91,8 +93,7 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     const legacyFromId = urlParams.get('fromConceptId');
 
     if (legacyMode === 'path' && legacyFromId) {
-      // Legacy path URL
-      initializingFromUrl.current = true;
+      hasInitializedFromUrl.current = true;
       setSearchParams({
         primaryConceptId: legacyFromId,
         destinationConceptId: destId || undefined,
@@ -100,10 +101,8 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
         maxHops,
         loadMode: 'clean',
       });
-      setTimeout(() => { initializingFromUrl.current = false; }, 100);
     } else if (primaryId) {
-      // New format or legacy concept/neighborhood URL
-      initializingFromUrl.current = true;
+      hasInitializedFromUrl.current = true;
 
       const effectiveDepth = depth || (legacyMode === 'neighborhood' ? 2 : 1);
 
@@ -118,14 +117,15 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
       if (similarity) {
         setSimilarityThreshold(parseFloat(similarity));
       }
-
-      setTimeout(() => { initializingFromUrl.current = false; }, 100);
     }
   }, [urlParams, setSearchParams, setSimilarityThreshold]);
 
   // Sync store state → URL parameters
   useEffect(() => {
-    if (initializingFromUrl.current) return;
+    if (!hasInitializedFromUrl.current && mode !== 'idle') {
+      // First store change — mark as initialized to prevent URL→store loop
+      hasInitializedFromUrl.current = true;
+    }
     if (mode === 'idle') return;
 
     const newParams = new URLSearchParams();

From 15de805399c20ba806d865c556523e302b961f8e Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 21:48:07 -0600
Subject: [PATCH 10/23] fix: additive graph loading, simplified search UX,
 warmth control

- Fix add-to-existing-graph: use ref-based loadMode tracking so data
  effect reads intended mode when data arrives, not stale closure value.
  Initialize lastProcessedData ref to current query data on mount so
  cached React Query results don't re-process on view switches.
- Fix isolated nodes filtered out: filterByEdgeCategory now preserves
  nodes with no connections (from additive loading) instead of dropping
  them when edge category filters are active.
- Simplify search UX: remove SelectedConceptChip toggle for both primary
  and destination searches. Input stays visible with concept label after
  selection; typing clears selection and restarts search.
- Context menu: rename "Add X to Graph" to "Add Adjacent Nodes", route
  both follow and add-adjacent through rawGraphData store (persists
  across view switches).
- Add warmth physics control (0.1-1.0) for D3 force simulation initial
  energy. Lower values = gentler settle on load/merge.
---
 web/src/components/shared/SearchBar.tsx       | 112 ++++++++----------
 .../explorers/ForceGraph2D/ForceGraph2D.tsx   |   8 +-
 web/src/explorers/ForceGraph2D/types.ts       |   3 +
 .../explorers/common/GraphSettingsPanel.tsx   |  19 +++
 .../explorers/common/useGraphContextMenu.ts   |  21 ++--
 web/src/utils/graphTransform.ts               |  25 +++-
 web/src/views/ExplorerView.tsx                |  38 +++++-
 7 files changed, 137 insertions(+), 89 deletions(-)

diff --git a/web/src/components/shared/SearchBar.tsx b/web/src/components/shared/SearchBar.tsx
index 68da5880..eb273018 100644
--- a/web/src/components/shared/SearchBar.tsx
+++ b/web/src/components/shared/SearchBar.tsx
@@ -24,7 +24,6 @@ import { apiClient } from '../../api/client';
 import { BlockBuilder } from '../blocks/BlockBuilder';
 import {
   ConceptSearchInput,
-  SelectedConceptChip,
   SliderControl,
   LoadButtons,
   PathResults,
@@ -109,7 +108,7 @@ LIMIT 50`);
           concept_id: searchParams.primaryConceptId,
           label: searchParams.primaryConceptLabel,
         });
-        setPrimaryQuery('');
+        setPrimaryQuery(searchParams.primaryConceptLabel);
         setDepth(searchParams.depth);
       }
     }
@@ -119,27 +118,12 @@ LIMIT 50`);
 
   const handleSelectPrimary = (concept: any) => {
     setSelectedPrimary(concept);
-    setPrimaryQuery('');
-  };
-
-  const handleClearPrimary = () => {
-    setSelectedPrimary(null);
-    setSelectedDestination(null);
-    setShowDestination(false);
-    setPathResults(null);
-    setSelectedPath(null);
-    setDepth(1);
+    setPrimaryQuery(concept.label);
   };
 
   const handleSelectDestination = (concept: any) => {
     setSelectedDestination(concept);
-    setDestinationQuery('');
-  };
-
-  const handleClearDestination = () => {
-    setSelectedDestination(null);
-    setPathResults(null);
-    setSelectedPath(null);
+    setDestinationQuery(concept.label);
   };
 
   const handleRemoveDestination = () => {
@@ -429,33 +413,34 @@ LIMIT 50`);
 
           {smartSearchExpanded && (
             <div className="space-y-3">
-              {/* Stage 1: Search for primary concept */}
-              {!selectedPrimary ? (
-                <div className="space-y-3">
-                  <ConceptSearchInput
-                    query={primaryQuery}
-                    onQueryChange={setPrimaryQuery}
-                    placeholder="Search for a concept..."
-                    icon={Search}
-                    isLoading={isLoadingPrimary}
-                    results={primaryResults?.results}
-                    debouncedQuery={debouncedPrimaryQuery}
-                    onSelect={handleSelectPrimary}
-                    noResultsContent={noResultsContent}
-                  />
-                  {similaritySlider}
-                </div>
-              ) : (
-                /* Stage 2+: Primary selected — show controls */
-                <div className="space-y-3">
-                  <SelectedConceptChip
-                    label="Concept:"
-                    conceptLabel={selectedPrimary.label}
-                    onClear={handleClearPrimary}
-                  />
+              {/* Search input — always visible */}
+              <ConceptSearchInput
+                query={primaryQuery}
+                onQueryChange={(q) => {
+                  setPrimaryQuery(q);
+                  if (selectedPrimary) {
+                    // User is typing — clear selection to restart search
+                    setSelectedPrimary(null);
+                    setSelectedDestination(null);
+                    setShowDestination(false);
+                    setPathResults(null);
+                    setSelectedPath(null);
+                  }
+                }}
+                placeholder="Search for a concept..."
+                icon={Search}
+                isLoading={isLoadingPrimary}
+                results={primaryResults?.results}
+                debouncedQuery={debouncedPrimaryQuery}
+                onSelect={handleSelectPrimary}
+                noResultsContent={noResultsContent}
+              />
 
-                  {similaritySlider}
+              {similaritySlider}
 
+              {/* Controls appear when a concept is selected */}
+              {selectedPrimary && (
+                <div className="space-y-3">
                   <SliderControl
                     label={showDestination ? "Context:" : "Depth:"}
                     value={depth}
@@ -499,27 +484,26 @@ LIMIT 50`);
                         </button>
                       </div>
 
-                      {!selectedDestination ? (
-                        /* Search for destination */
-                        <ConceptSearchInput
-                          query={destinationQuery}
-                          onQueryChange={setDestinationQuery}
-                          placeholder="Search for destination concept..."
-                          icon={GitBranch}
-                          isLoading={isLoadingDestination}
-                          results={destinationResults?.results}
-                          debouncedQuery={debouncedDestinationQuery}
-                          onSelect={handleSelectDestination}
-                        />
-                      ) : (
-                        /* Both selected — path controls */
+                      <ConceptSearchInput
+                        query={destinationQuery}
+                        onQueryChange={(q) => {
+                          setDestinationQuery(q);
+                          if (selectedDestination) {
+                            setSelectedDestination(null);
+                            setPathResults(null);
+                            setSelectedPath(null);
+                          }
+                        }}
+                        placeholder="Search for destination concept..."
+                        icon={GitBranch}
+                        isLoading={isLoadingDestination}
+                        results={destinationResults?.results}
+                        debouncedQuery={debouncedDestinationQuery}
+                        onSelect={handleSelectDestination}
+                      />
+
+                      {selectedDestination && (
                         <div className="space-y-3">
-                          <SelectedConceptChip
-                            label="Destination:"
-                            conceptLabel={selectedDestination.label}
-                            onClear={handleClearDestination}
-                          />
-
                           <SliderControl
                             label="Max Hops:"
                             value={maxHops}
diff --git a/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx b/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx
index d9a802ec..246f20fb 100644
--- a/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx
+++ b/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx
@@ -545,10 +545,12 @@ export const ForceGraph2D: React.FC<
       .force('collision', d3.forceCollide().radius((d) => ((d as D3Node).size || 10) * settings.visual.nodeSize + 5))
       .velocityDecay(1 - settings.physics.friction);
 
-    // If nodes already have positions (merged graph), start with lower alpha
-    // to avoid explosive force effects
+    // Control initial simulation energy — lower warmth = less scatter on load
+    const warmth = settings.physics.warmth ?? 0.3;
     if (hasExistingPositions) {
-      simulation.alpha(0.3).alphaDecay(0.05);
+      simulation.alpha(warmth).alphaDecay(0.05);
+    } else {
+      simulation.alpha(warmth);
     }
 
     simulationRef.current = simulation;
diff --git a/web/src/explorers/ForceGraph2D/types.ts b/web/src/explorers/ForceGraph2D/types.ts
index 09f66e99..9c40523c 100644
--- a/web/src/explorers/ForceGraph2D/types.ts
+++ b/web/src/explorers/ForceGraph2D/types.ts
@@ -16,6 +16,7 @@ export interface ForceGraph2DSettings {
     linkDistance: number; // Target link distance (10-400)
     gravity: number; // Center gravity (0-1)
     friction: number; // Velocity decay (0-1)
+    warmth: number; // Initial simulation energy (0.1-1.0, lower = less scatter)
   };
 
   // Visual appearance
@@ -63,6 +64,7 @@ export const DEFAULT_SETTINGS: ForceGraph2DSettings = {
     linkDistance: 200,   // Longer links for better graph layout
     gravity: 0.1,
     friction: 0.9,
+    warmth: 0.3,        // Lower = gentler settle, higher = more scatter
   },
   visual: {
     nodeColorBy: 'ontology',
@@ -97,6 +99,7 @@ export const SLIDER_RANGES = {
     charge: { min: -1000, max: -100, step: 50 },
     linkDistance: { min: 10, max: 400, step: 10 },  // Extended range for larger graphs
     gravity: { min: 0, max: 1, step: 0.05 },
+    warmth: { min: 0.1, max: 1, step: 0.05 },
   },
   visual: {
     nodeSize: { min: 0.5, max: 3, step: 0.1 },
diff --git a/web/src/explorers/common/GraphSettingsPanel.tsx b/web/src/explorers/common/GraphSettingsPanel.tsx
index 3a28aa26..68a8005f 100644
--- a/web/src/explorers/common/GraphSettingsPanel.tsx
+++ b/web/src/explorers/common/GraphSettingsPanel.tsx
@@ -17,6 +17,7 @@ interface GraphSettings {
     linkDistance: number;
     gravity: number;
     friction: number;
+    warmth?: number;
   };
   visual: {
     nodeColorBy: string;
@@ -44,6 +45,7 @@ interface SliderRanges {
     charge: { min: number; max: number; step: number };
     linkDistance: { min: number; max: number; step: number };
     gravity: { min: number; max: number; step: number };
+    warmth?: { min: number; max: number; step: number };
   };
   visual: {
     nodeSize: { min: number; max: number; step: number };
@@ -182,6 +184,23 @@ export const GraphSettingsPanel = <T extends GraphSettings>({
                       className="w-full"
                     />
                   </div>
+
+                  {settings.physics.warmth !== undefined && sliderRanges.physics.warmth && (
+                    <div>
+                      <label className="block text-xs text-foreground mb-1">
+                        Warmth: {settings.physics.warmth.toFixed(2)}
+                      </label>
+                      <input
+                        type="range"
+                        min={sliderRanges.physics.warmth.min}
+                        max={sliderRanges.physics.warmth.max}
+                        step={sliderRanges.physics.warmth.step}
+                        value={settings.physics.warmth}
+                        onChange={(e) => updatePhysics('warmth', parseFloat(e.target.value))}
+                        className="w-full"
+                      />
+                    </div>
+                  )}
                 </>
               )}
             </div>
diff --git a/web/src/explorers/common/useGraphContextMenu.ts b/web/src/explorers/common/useGraphContextMenu.ts
index 813367b8..617b7b8e 100644
--- a/web/src/explorers/common/useGraphContextMenu.ts
+++ b/web/src/explorers/common/useGraphContextMenu.ts
@@ -66,7 +66,7 @@ export interface GraphContextMenuCallbacks {
  * Hook providing generic graph navigation actions
  */
 export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
-  const { setGraphData, setFocusedNodeId } = useGraphStore();
+  const { setGraphData, setRawGraphData, mergeRawGraphData, setFocusedNodeId } = useGraphStore();
 
   // Handler: Follow concept (replace graph)
   const handleFollowConcept = useCallback(async (nodeId: string) => {
@@ -76,16 +76,16 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
         depth: 1, // Load immediate neighbors
       });
 
-      const transformedData = transformForD3(response.nodes, response.links);
-      setGraphData(transformedData);
+      setGraphData(null);
+      setRawGraphData({ nodes: response.nodes, links: response.links });
       setFocusedNodeId(nodeId);
     } catch (error: any) {
       console.error('Failed to follow concept:', error);
       alert(`Failed to follow concept: ${error.message || 'Unknown error'}`);
     }
-  }, [setGraphData, setFocusedNodeId]);
+  }, [setGraphData, setRawGraphData, setFocusedNodeId]);
 
-  // Handler: Add concept to graph (merge)
+  // Handler: Add adjacent nodes to graph (merge neighbors)
   const handleAddToGraph = useCallback(async (nodeId: string) => {
     try {
       const response = await apiClient.getSubgraph({
@@ -93,14 +93,13 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
         depth: 1, // Load immediate neighbors
       });
 
-      const transformedData = transformForD3(response.nodes, response.links);
-      setGraphData(mergeGraphData(transformedData));
+      mergeRawGraphData({ nodes: response.nodes, links: response.links });
       setFocusedNodeId(nodeId);
     } catch (error: any) {
-      console.error('Failed to add concept to graph:', error);
-      alert(`Failed to add concept to graph: ${error.message || 'Unknown error'}`);
+      console.error('Failed to add adjacent nodes:', error);
+      alert(`Failed to add adjacent nodes: ${error.message || 'Unknown error'}`);
     }
-  }, [mergeGraphData, setGraphData, setFocusedNodeId]);
+  }, [mergeRawGraphData, setFocusedNodeId]);
 
   return { handleFollowConcept, handleAddToGraph };
 }
@@ -340,7 +339,7 @@ export function buildContextMenuItems(
     });
 
     items.push({
-      label: `Add "${nodeLabel}" to Graph`,
+      label: `Add Adjacent Nodes`,
       icon: Plus,
       onClick: () => {
         handleAddToGraph(nodeId);
diff --git a/web/src/utils/graphTransform.ts b/web/src/utils/graphTransform.ts
index 68bee9b9..d82bd637 100644
--- a/web/src/utils/graphTransform.ts
+++ b/web/src/utils/graphTransform.ts
@@ -167,17 +167,30 @@ export function filterByEdgeCategory(
     visibleCategories.has(link.category || 'default')
   );
 
-  // Get all node IDs that have visible connections
-  const connectedNodeIds = new Set<string>();
+  // Get all node IDs that have ANY connections (visible or not)
+  const allConnectedNodeIds = new Set<string>();
+  data.links.forEach(link => {
+    const sourceId = typeof link.source === 'string' ? link.source : link.source.id;
+    const targetId = typeof link.target === 'string' ? link.target : link.target.id;
+    allConnectedNodeIds.add(sourceId);
+    allConnectedNodeIds.add(targetId);
+  });
+
+  // Get node IDs that have visible connections
+  const visiblyConnectedNodeIds = new Set<string>();
   filteredLinks.forEach(link => {
     const sourceId = typeof link.source === 'string' ? link.source : link.source.id;
     const targetId = typeof link.target === 'string' ? link.target : link.target.id;
-    connectedNodeIds.add(sourceId);
-    connectedNodeIds.add(targetId);
+    visiblyConnectedNodeIds.add(sourceId);
+    visiblyConnectedNodeIds.add(targetId);
   });
 
-  // Filter nodes to only include those with visible connections
-  const filteredNodes = data.nodes.filter(node => connectedNodeIds.has(node.id));
+  // Keep nodes that either:
+  // 1. Have visible connections, or
+  // 2. Have no connections at all (isolated nodes from additive loading)
+  const filteredNodes = data.nodes.filter(node =>
+    visiblyConnectedNodeIds.has(node.id) || !allConnectedNodeIds.has(node.id)
+  );
 
   return {
     nodes: filteredNodes,
diff --git a/web/src/views/ExplorerView.tsx b/web/src/views/ExplorerView.tsx
index 0a433681..935b6193 100644
--- a/web/src/views/ExplorerView.tsx
+++ b/web/src/views/ExplorerView.tsx
@@ -182,20 +182,46 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     { enabled: mode === 'path' && pathNodeIds.length > 0 }
   );
 
+  // Track loadMode via ref so the data effect reads the intended mode
+  // without re-running when loadMode changes independently of data.
+  const loadModeRef = React.useRef(searchParams.loadMode);
+  useEffect(() => {
+    console.log('[loadMode-ref] updated to:', searchParams.loadMode);
+    loadModeRef.current = searchParams.loadMode;
+  }, [searchParams.loadMode]);
+
+  // Track last-processed data to avoid re-processing on remount or unrelated rerenders.
+  // Initialize to current query data so cached results from a previous mount are skipped —
+  // this preserves rawGraphData in Zustand when toggling between 2D/3D/analysis views.
+  const lastProcessedData = React.useRef<any>(mode === 'path' ? pathData : exploreData);
+
   // Update rawGraphData when query results come back
   useEffect(() => {
     const newData = mode === 'path' ? pathData : exploreData;
-    if (!newData) return;
+    console.log('[data-effect] fired', {
+      mode,
+      hasNewData: !!newData,
+      isSameRef: newData === lastProcessedData.current,
+      loadMode: loadModeRef.current,
+      newDataNodes: newData?.nodes?.length,
+      newDataLinks: newData?.links?.length,
+      currentRawNodes: useGraphStore.getState().rawGraphData?.nodes?.length,
+    });
+    if (!newData || newData === lastProcessedData.current) return;
+    lastProcessedData.current = newData;
 
     const graphPayload = { nodes: newData.nodes || [], links: newData.links || [] };
 
-    if (searchParams.loadMode === 'clean') {
+    if (loadModeRef.current === 'add') {
+      console.log('[data-effect] MERGE', graphPayload.nodes.length, 'nodes', graphPayload.links.length, 'links');
+      mergeRawGraphData(graphPayload);
+      console.log('[data-effect] after merge, rawGraphData:', useGraphStore.getState().rawGraphData?.nodes?.length, 'nodes');
+    } else {
+      console.log('[data-effect] CLEAN SET', graphPayload.nodes.length, 'nodes', graphPayload.links.length, 'links');
       setGraphData(null);
       setRawGraphData(graphPayload);
-    } else if (searchParams.loadMode === 'add') {
-      mergeRawGraphData(graphPayload);
     }
-  }, [exploreData, pathData, searchParams.loadMode, mode]);
+  }, [exploreData, pathData, mode]);
 
   // Merge path enrichment data when it arrives
   useEffect(() => {
@@ -212,11 +238,13 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
 
   // Transform rawGraphData using current explorer's dataTransformer
   useEffect(() => {
+    console.log('[transform] rawGraphData changed:', rawGraphData?.nodes?.length, 'nodes', rawGraphData?.links?.length, 'links');
     if (!rawGraphData || !explorerPlugin) {
       return;
     }
 
     const transformedData = explorerPlugin.dataTransformer(rawGraphData);
+    console.log('[transform] graphData set:', transformedData?.nodes?.length, 'nodes', transformedData?.links?.length, 'links');
     setGraphData(transformedData);
   }, [rawGraphData, explorerPlugin, explorerType]);
 

From f4ba04938e0890837decdf71dd5da93725128506 Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 21:48:48 -0600
Subject: [PATCH 11/23] chore: remove debug console.log statements from
 ExplorerView

---
 web/src/views/ExplorerView.tsx | 15 ---------------
 1 file changed, 15 deletions(-)

diff --git a/web/src/views/ExplorerView.tsx b/web/src/views/ExplorerView.tsx
index 935b6193..72079b6e 100644
--- a/web/src/views/ExplorerView.tsx
+++ b/web/src/views/ExplorerView.tsx
@@ -186,7 +186,6 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
   // without re-running when loadMode changes independently of data.
   const loadModeRef = React.useRef(searchParams.loadMode);
   useEffect(() => {
-    console.log('[loadMode-ref] updated to:', searchParams.loadMode);
     loadModeRef.current = searchParams.loadMode;
   }, [searchParams.loadMode]);
 
@@ -198,26 +197,14 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
   // Update rawGraphData when query results come back
   useEffect(() => {
     const newData = mode === 'path' ? pathData : exploreData;
-    console.log('[data-effect] fired', {
-      mode,
-      hasNewData: !!newData,
-      isSameRef: newData === lastProcessedData.current,
-      loadMode: loadModeRef.current,
-      newDataNodes: newData?.nodes?.length,
-      newDataLinks: newData?.links?.length,
-      currentRawNodes: useGraphStore.getState().rawGraphData?.nodes?.length,
-    });
     if (!newData || newData === lastProcessedData.current) return;
     lastProcessedData.current = newData;
 
     const graphPayload = { nodes: newData.nodes || [], links: newData.links || [] };
 
     if (loadModeRef.current === 'add') {
-      console.log('[data-effect] MERGE', graphPayload.nodes.length, 'nodes', graphPayload.links.length, 'links');
       mergeRawGraphData(graphPayload);
-      console.log('[data-effect] after merge, rawGraphData:', useGraphStore.getState().rawGraphData?.nodes?.length, 'nodes');
     } else {
-      console.log('[data-effect] CLEAN SET', graphPayload.nodes.length, 'nodes', graphPayload.links.length, 'links');
       setGraphData(null);
       setRawGraphData(graphPayload);
     }
@@ -238,13 +225,11 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
 
   // Transform rawGraphData using current explorer's dataTransformer
   useEffect(() => {
-    console.log('[transform] rawGraphData changed:', rawGraphData?.nodes?.length, 'nodes', rawGraphData?.links?.length, 'links');
     if (!rawGraphData || !explorerPlugin) {
       return;
     }
 
     const transformedData = explorerPlugin.dataTransformer(rawGraphData);
-    console.log('[transform] graphData set:', transformedData?.nodes?.length, 'nodes', transformedData?.links?.length, 'links');
     setGraphData(transformedData);
   }, [rawGraphData, explorerPlugin, explorerType]);
 

From e1fda7a58a41eb56b12b3673893829c55e91d364 Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 22:09:39 -0600
Subject: [PATCH 12/23] feat: exploration tracking with Cypher generation
 (Phase 1)

Track graph exploration as ordered +/- Cypher statements that can be
saved, exported, and replayed. Each action (explore, follow, add-adjacent,
load-path) records a step with its equivalent openCypher statement.

- Add ExplorationStep/Session types and actions to graphStore
- Wrap store with Zustand persist middleware (localStorage)
- Add subtractRawGraphData for future subtractive operations
- Create cypherGenerator.ts (stepToCypher, generateCypher, parse)
- Instrument SearchBar, context menu, and ExplorerView action points
---
 .claude/todo-unified-query-exploration.md     |  78 ++++++++
 web/src/components/shared/SearchBar.tsx       |  43 +++-
 .../explorers/common/useGraphContextMenu.ts   |  37 +++-
 web/src/store/graphStore.ts                   | 186 +++++++++++++++++-
 web/src/utils/cypherGenerator.ts              | 178 +++++++++++++++++
 web/src/views/ExplorerView.tsx                |  15 +-
 6 files changed, 523 insertions(+), 14 deletions(-)
 create mode 100644 .claude/todo-unified-query-exploration.md
 create mode 100644 web/src/utils/cypherGenerator.ts

diff --git a/.claude/todo-unified-query-exploration.md b/.claude/todo-unified-query-exploration.md
new file mode 100644
index 00000000..cbd40201
--- /dev/null
+++ b/.claude/todo-unified-query-exploration.md
@@ -0,0 +1,78 @@
+# Unified Query Exploration System
+
+## Vision
+
+The saved query is the universal unit of work across all explorer views. A query is an ordered list of Cypher statements with additive/subtractive operators, built interactively or by hand, that flows through every explorer identically.
+
+### Core Concept
+
+```
+{ name: string, statements: { op: '+' | '-', cypher: string }[] }
+```
+
+Each statement represents one intentional action — a discrete thought in an exploration sequence. The order mirrors how the user actually explored. Replay executes them in order, merging (+) or removing (-) each result.
+
+### Entry Points (all produce the same saved artifact)
+
+- **Smart Search** — interactive clicks, add-to-existing, add-adjacent → generates Cypher per action
+- **Block Builder** — visual composition → compiles to Cypher
+- **Cypher Editor** — hand-written or pasted from a friend
+- **Saved query recall** — load a previously saved exploration
+
+### Explorer Views (all consume the same saved query)
+
+| Explorer | What it shows |
+|----------|---------------|
+| 2D Graph | Force-directed visualization, primary interactive builder |
+| 3D Graph | Same graph, spatial perspective |
+| Cypher Editor | The statements as editable text, copy/pasteable |
+| Vocabulary Analysis | Relationship type introspection on the query's result set |
+| Document Explorer | Source documents contributing to the query's concepts |
+| Polarity Explorer | Pick edges from the query's graph for polarity axis analysis |
+
+### Sidebar Consistency
+
+Folder icon in the nav rail across all explorer views. Same saved queries list, different lens on the data. Switching views preserves the graph.
+
+## Implementation Phases
+
+### Phase 1: Exploration Tracking & Cypher Generation
+- [ ] Add `ExplorationStep` type and `explorationSession` to graphStore
+- [ ] Add `addExplorationStep()`, `clearExploration()` store actions
+- [ ] Record steps at action points: handleLoadExplore, handleLoadPath, handleFollowConcept, handleAddToGraph
+- [ ] Create `cypherGenerator.ts` — convert steps to ordered Cypher statements with +/- operators
+- [ ] Persist `rawGraphData` + `explorationSession` to localStorage (survive refresh)
+
+### Phase 2: Saved Queries Folder
+- [ ] Unify sidebar folder icon across all explorer views (consistent with report explorer pattern)
+- [ ] Saved query data model: `{ name, statements: { op, cypher }[] }`
+- [ ] Save exploration → creates QueryDefinition with `definition_type: 'exploration'`
+- [ ] Load saved query → executes statements in order with +/- semantics
+- [ ] Delete saved query
+
+### Phase 3: Editor Integration
+- [ ] "Export as Cypher" sends ordered statements to the Cypher editor
+- [ ] Cypher editor displays +/- prefixed statements
+- [ ] Execute from editor replays the statement sequence
+- [ ] Subtractive operator: context menu "Remove from Graph" option
+
+### Phase 4: Cross-Explorer Flow
+- [ ] Vocabulary explorer reads same saved queries from folder
+- [ ] Document explorer reads same saved queries
+- [ ] Polarity explorer loads graph from saved query
+- [ ] Verify all explorers share the same folder state
+
+### Phase 5: Documentation & Docstrings
+- [ ] Add JSDoc docstrings to new exploration tracking code
+- [ ] Add JSDoc docstrings to graphStore (actions, types)
+- [ ] Add JSDoc docstrings to cypherGenerator
+- [ ] Add JSDoc docstrings to SearchBar handlers
+- [ ] Add JSDoc docstrings to useGraphContextMenu handlers
+- [ ] Document the unified query exploration workflow in user manual
+- [ ] Document the +/- operator algebra concept
+
+## Notes
+
+- Block builder compiles TO Cypher but we don't decompose Cypher back to blocks (existing ADR)
+- Graph accelerator makes this practical — path finding is now fast enough for interactive multi-step exploration
+- The +/- algebra on statements is like set operations: union then difference, letting users sculpt their graph
diff --git a/web/src/components/shared/SearchBar.tsx b/web/src/components/shared/SearchBar.tsx
index eb273018..96e5c635 100644
--- a/web/src/components/shared/SearchBar.tsx
+++ b/web/src/components/shared/SearchBar.tsx
@@ -22,6 +22,7 @@ import { useGraphStore } from '../../store/graphStore';
 import { ModeDial } from './ModeDial';
 import { apiClient } from '../../api/client';
 import { BlockBuilder } from '../blocks/BlockBuilder';
+import { stepToCypher } from '../../utils/cypherGenerator';
 import {
   ConceptSearchInput,
   SliderControl,
@@ -135,9 +136,25 @@ LIMIT 50`);
     setDepth(1); // Reset to explore default
   };
 
-  // Load explore (concept or neighborhood depending on depth)
+  /** Load explore — fetch subgraph around selected concept and record the step */
   const handleLoadExplore = (loadMode: 'clean' | 'add') => {
     if (!selectedPrimary) return;
+
+    const stepParams = {
+      action: 'explore' as const,
+      conceptLabel: selectedPrimary.label,
+      depth,
+    };
+
+    useGraphStore.getState().addExplorationStep({
+      action: 'explore',
+      op: loadMode === 'add' ? '+' : '+',
+      cypher: stepToCypher(stepParams),
+      conceptId: selectedPrimary.concept_id,
+      conceptLabel: selectedPrimary.label,
+      depth,
+    });
+
     setSearchParams({
       primaryConceptId: selectedPrimary.concept_id,
       primaryConceptLabel: selectedPrimary.label,
@@ -180,9 +197,29 @@ LIMIT 50`);
     }
   };
 
-  // Load selected path directly into graph, with optional neighborhood enrichment
+  /** Load selected path into graph and record the step */
   const handleLoadPath = async (loadMode: 'clean' | 'add') => {
-    if (!selectedPath) return;
+    if (!selectedPath || !selectedPrimary || !selectedDestination) return;
+
+    const stepParams = {
+      action: 'load-path' as const,
+      conceptLabel: selectedPrimary.label,
+      depth,
+      destinationConceptLabel: selectedDestination.label,
+      maxHops,
+    };
+
+    useGraphStore.getState().addExplorationStep({
+      action: 'load-path',
+      op: '+',
+      cypher: stepToCypher(stepParams),
+      conceptId: selectedPrimary.concept_id,
+      conceptLabel: selectedPrimary.label,
+      depth,
+      destinationConceptId: selectedDestination.concept_id,
+      destinationConceptLabel: selectedDestination.label,
+      maxHops,
+    });
 
     const conceptNodes: any[] = [];
     const conceptRelTypes: string[][] = [];
diff --git a/web/src/explorers/common/useGraphContextMenu.ts b/web/src/explorers/common/useGraphContextMenu.ts
index 617b7b8e..ffabb61b 100644
--- a/web/src/explorers/common/useGraphContextMenu.ts
+++ b/web/src/explorers/common/useGraphContextMenu.ts
@@ -12,6 +12,7 @@
 import { useCallback } from 'react';
 import { apiClient } from '../../api/client';
 import { transformForD3 } from '../../utils/graphTransform';
+import { stepToCypher } from '../../utils/cypherGenerator';
 import { useGraphStore } from '../../store/graphStore';
 import type { ContextMenuItem } from '../../components/shared/ContextMenu';
 import {
@@ -68,12 +69,26 @@ export interface GraphContextMenuCallbacks {
 export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
   const { setGraphData, setRawGraphData, mergeRawGraphData, setFocusedNodeId } = useGraphStore();
 
-  // Handler: Follow concept (replace graph)
+  /** Follow concept — replace graph with this node's neighborhood and record the step */
   const handleFollowConcept = useCallback(async (nodeId: string) => {
     try {
+      const store = useGraphStore.getState();
+      const nodeLabel = store.rawGraphData?.nodes?.find(
+        (n: any) => (n.concept_id || n.id) === nodeId
+      )?.label || nodeId;
+
+      store.addExplorationStep({
+        action: 'follow',
+        op: '+',
+        cypher: stepToCypher({ action: 'follow', conceptLabel: nodeLabel, depth: 1 }),
+        conceptId: nodeId,
+        conceptLabel: nodeLabel,
+        depth: 1,
+      });
+
       const response = await apiClient.getSubgraph({
         center_concept_id: nodeId,
-        depth: 1, // Load immediate neighbors
+        depth: 1,
       });
 
       setGraphData(null);
@@ -85,12 +100,26 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
     }
   }, [setGraphData, setRawGraphData, setFocusedNodeId]);
 
-  // Handler: Add adjacent nodes to graph (merge neighbors)
+  /** Add adjacent nodes — merge this node's neighbors into the graph and record the step */
   const handleAddToGraph = useCallback(async (nodeId: string) => {
     try {
+      const store = useGraphStore.getState();
+      const nodeLabel = store.rawGraphData?.nodes?.find(
+        (n: any) => (n.concept_id || n.id) === nodeId
+      )?.label || nodeId;
+
+      store.addExplorationStep({
+        action: 'add-adjacent',
+        op: '+',
+        cypher: stepToCypher({ action: 'add-adjacent', conceptLabel: nodeLabel, depth: 1 }),
+        conceptId: nodeId,
+        conceptLabel: nodeLabel,
+        depth: 1,
+      });
+
       const response = await apiClient.getSubgraph({
         center_concept_id: nodeId,
-        depth: 1, // Load immediate neighbors
+        depth: 1,
       });
 
       mergeRawGraphData({ nodes: response.nodes, links: response.links });
diff --git a/web/src/store/graphStore.ts b/web/src/store/graphStore.ts
index d817caaf..b353a1be 100644
--- a/web/src/store/graphStore.ts
+++ b/web/src/store/graphStore.ts
@@ -6,9 +6,18 @@
  * - Graph data and filters
  * - UI settings
  * - Node/edge selection
+ * - Exploration session tracking (ordered Cypher statement log)
+ *
+ * The exploration session records each graph action as a step with an additive (+)
+ * or subtractive (-) operator and its equivalent Cypher statement. This enables:
+ * - Persistence across refresh (localStorage)
+ * - Saving named explorations as replayable query sets
+ * - Exporting to the Cypher editor for viewing/editing
+ * - Sharing explorations as copy/pasteable Cypher
  */
 
 import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
 import type { VisualizationType } from '../types/explorer';
 import type { GraphData } from '../types/graph';
 
@@ -58,16 +67,84 @@ export function deriveMode(params: SearchParams): DerivedMode {
   return 'explore';
 }
 
+// --- Exploration Session Types ---
+
+/** The type of graph action performed */
+export type ExplorationAction = 'explore' | 'follow' | 'add-adjacent' | 'load-path';
+
+/** Set algebra operator: additive (+) merges results, subtractive (-) removes them */
+export type ExplorationOp = '+' | '-';
+
+/**
+ * A single step in an exploration session.
+ *
+ * Each step records one intentional graph action — a discrete thought in the
+ * user's exploration sequence. The step includes both the semantic description
+ * (action, concept, depth) and the equivalent Cypher statement for replay.
+ */
+export interface ExplorationStep {
+  /** Unique step identifier */
+  id: string;
+  /** When this step was performed */
+  timestamp: number;
+  /** What kind of action was taken */
+  action: ExplorationAction;
+  /** Whether this step adds to or removes from the graph */
+  op: ExplorationOp;
+  /** The equivalent Cypher statement for this action */
+  cypher: string;
+
+  /** Primary concept ID */
+  conceptId: string;
+  /** Human-readable concept label */
+  conceptLabel: string;
+  /** Neighborhood traversal depth */
+  depth: number;
+
+  /** Destination concept ID (path mode only) */
+  destinationConceptId?: string;
+  /** Destination concept label (path mode only) */
+  destinationConceptLabel?: string;
+  /** Maximum hops for path search (path mode only) */
+  maxHops?: number;
+}
+
+/**
+ * An exploration session — an ordered list of steps that together define
+ * a graph query. The sequence mirrors how the user actually explored.
+ * Replay executes steps in order, applying +/- operators.
+ */
+export interface ExplorationSession {
+  /** Unique session identifier */
+  id: string;
+  /** User-provided name (null until saved) */
+  name: string | null;
+  /** When the session started */
+  createdAt: number;
+  /** Ordered list of exploration steps */
+  steps: ExplorationStep[];
+}
+
+const createEmptySession = (): ExplorationSession => ({
+  id: crypto.randomUUID(),
+  name: null,
+  createdAt: Date.now(),
+  steps: [],
+});
+
 interface GraphStore {
   // Explorer selection
   selectedExplorer: VisualizationType;
   setSelectedExplorer: (type: VisualizationType) => void;
 
-  // Graph data (raw API format - cached to avoid re-fetching)
+  // Graph data (raw API format - cached to avoid re-fetching, persisted to localStorage)
   rawGraphData: { nodes: any[]; links: any[] } | null;
+  /** Replace raw graph data entirely (clean load) */
   setRawGraphData: (data: { nodes: any[]; links: any[] } | null) => void;
-  // Merge new data into existing graph (deduplicating nodes by concept_id, links by from+type+to)
+  /** Merge new data into existing graph, deduplicating by concept_id / link key */
   mergeRawGraphData: (data: { nodes: any[]; links: any[] }) => void;
+  /** Remove matching nodes and their connected links from the graph (subtractive operator) */
+  subtractRawGraphData: (data: { nodes: any[]; links: any[] }) => void;
 
   // Graph data (transformed for current explorer)
   graphData: GraphData | null;
@@ -150,6 +227,18 @@ interface GraphStore {
   addPolarityAnalysis: (analysis: GraphStore['polarityState']['analysisHistory'][0]) => void;
   removePolarityAnalysis: (id: string) => void;
   clearPolarityHistory: () => void;
+
+  // Exploration session — ordered list of graph actions with +/- operators
+  /** Current exploration session (persisted to localStorage) */
+  explorationSession: ExplorationSession;
+  /** Record a new step in the exploration session */
+  addExplorationStep: (step: Omit<ExplorationStep, 'id' | 'timestamp'>) => void;
+  /** Remove the last step from the session */
+  undoLastStep: () => void;
+  /** Clear the session and graph data, starting fresh */
+  clearExploration: () => void;
+  /** Set a name for the current exploration (for saving) */
+  setExplorationName: (name: string) => void;
 }
 
 const defaultFilters: GraphFilters = {
@@ -172,7 +261,9 @@ const defaultSearchParams: SearchParams = {
   loadMode: 'clean',
 };
 
-export const useGraphStore = create<GraphStore>((set) => ({
+export const useGraphStore = create<GraphStore>()(
+  persist(
+    (set) => ({
   // Explorer selection
   selectedExplorer: 'force-2d',
   setSelectedExplorer: (type) => set({ selectedExplorer: type }),
@@ -215,6 +306,41 @@ export const useGraphStore = create<GraphStore>((set) => ({
       };
     }),
 
+  subtractRawGraphData: (data) =>
+    set((state) => {
+      const current = state.rawGraphData;
+      if (!current || !current.nodes || current.nodes.length === 0) {
+        return {};
+      }
+
+      // Build set of node IDs to remove
+      const removeNodeIds = new Set(
+        (data.nodes || []).map((n: any) => n.id || n.concept_id)
+      );
+
+      // Remove matching nodes
+      const remainingNodes = current.nodes.filter(
+        (n: any) => !removeNodeIds.has(n.id || n.concept_id)
+      );
+
+      // Remove links that reference removed nodes
+      const remainingNodeIds = new Set(
+        remainingNodes.map((n: any) => n.id || n.concept_id)
+      );
+      const remainingLinks = current.links.filter((l: any) => {
+        const from = l.from_id || l.source?.id || l.source;
+        const to = l.to_id || l.target?.id || l.target;
+        return remainingNodeIds.has(from) && remainingNodeIds.has(to);
+      });
+
+      return {
+        rawGraphData: {
+          nodes: remainingNodes,
+          links: remainingLinks,
+        },
+      };
+    }),
+
   // Graph data (transformed)
   graphData: null,
   setGraphData: (data) => set({ graphData: data }),
@@ -393,4 +519,56 @@ export const useGraphStore = create<GraphStore>((set) => ({
         selectedAnalysisId: null,
       },
     })),
-}));
+
+  // Exploration session
+  explorationSession: createEmptySession(),
+
+  addExplorationStep: (stepData) =>
+    set((state) => ({
+      explorationSession: {
+        ...state.explorationSession,
+        steps: [
+          ...state.explorationSession.steps,
+          {
+            ...stepData,
+            id: crypto.randomUUID(),
+            timestamp: Date.now(),
+          },
+        ],
+      },
+    })),
+
+  undoLastStep: () =>
+    set((state) => ({
+      explorationSession: {
+        ...state.explorationSession,
+        steps: state.explorationSession.steps.slice(0, -1),
+      },
+    })),
+
+  clearExploration: () =>
+    set({
+      explorationSession: createEmptySession(),
+      rawGraphData: null,
+      graphData: null,
+    }),
+
+  setExplorationName: (name) =>
+    set((state) => ({
+      explorationSession: {
+        ...state.explorationSession,
+        name,
+      },
+    })),
+    }),
+    {
+      name: 'kg-graph-exploration',
+      partialize: (state) => ({
+        rawGraphData: state.rawGraphData,
+        explorationSession: state.explorationSession,
+        searchParams: state.searchParams,
+        similarityThreshold: state.similarityThreshold,
+      }),
+    }
+  )
+);
diff --git a/web/src/utils/cypherGenerator.ts b/web/src/utils/cypherGenerator.ts
new file mode 100644
index 00000000..d235dd32
--- /dev/null
+++ b/web/src/utils/cypherGenerator.ts
@@ -0,0 +1,178 @@
+/**
+ * Cypher Generator — converts exploration sessions to ordered Cypher statements.
+ *
+ * Each exploration step maps to an equivalent Apache AGE openCypher statement.
+ * Steps are prefixed with +/- operators indicating whether the result should
+ * be merged into or subtracted from the graph.
+ *
+ * The generated output is human-readable, editable, and executable in the
+ * openCypher editor. It preserves the user's exploration narrative — each
+ * statement is a discrete thought in the sequence.
+ *
+ * @example
+ * ```
+ * -- Exploration: My Graph Query
+ * -- Step 1: explore "Way"
+ * + MATCH (c:Concept)-[r]-(n:Concept) WHERE c.label = 'Way' RETURN c, r, n
+ * -- Step 2: add-adjacent "Enterprise Operating Model"
+ * + MATCH (c:Concept)-[r]-(n:Concept) WHERE c.label = 'Enterprise Operating Model' RETURN c, r, n
+ * -- Step 3: subtract "Noise"
+ * - MATCH (c:Concept)-[r]-(n:Concept) WHERE c.label = 'Noise' RETURN c, r, n
+ * ```
+ */
+
+import type { ExplorationStep, ExplorationSession, ExplorationAction } from '../store/graphStore';
+
+/**
+ * Escape a string for safe use in Cypher WHERE clauses.
+ * Handles single quotes which would break string literals.
+ */
+function escapeCypher(label: string): string {
+  return label.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+
+/**
+ * Generate a Cypher statement for a single exploration step.
+ *
+ * Maps each action type to its equivalent Cypher pattern:
+ * - explore/follow/add-adjacent: MATCH neighborhood at given depth
+ * - load-path: MATCH variable-length path between two concepts
+ *
+ * @param step - The exploration step to convert
+ * @returns A Cypher MATCH...RETURN statement
+ */
+export function stepToCypher(step: {
+  action: ExplorationAction;
+  conceptLabel: string;
+  depth: number;
+  destinationConceptLabel?: string;
+  maxHops?: number;
+}): string {
+  switch (step.action) {
+    case 'explore':
+    case 'follow':
+    case 'add-adjacent': {
+      if (step.depth <= 1) {
+        return [
+          `MATCH (c:Concept)-[r]-(n:Concept)`,
+          `WHERE c.label = '${escapeCypher(step.conceptLabel)}'`,
+          `RETURN c, r, n`,
+        ].join('\n');
+      }
+      return [
+        `MATCH (c:Concept)-[r*1..${step.depth}]-(n:Concept)`,
+        `WHERE c.label = '${escapeCypher(step.conceptLabel)}'`,
+        `RETURN c, r, n`,
+      ].join('\n');
+    }
+
+    case 'load-path': {
+      const hops = step.maxHops || 5;
+      return [
+        `MATCH path = (a:Concept)-[*..${hops}]-(b:Concept)`,
+        `WHERE a.label = '${escapeCypher(step.conceptLabel)}'`,
+        `  AND b.label = '${escapeCypher(step.destinationConceptLabel || '')}'`,
+        `RETURN path`,
+      ].join('\n');
+    }
+
+    default:
+      return `-- Unknown action: ${step.action}`;
+  }
+}
+
+/**
+ * Generate a complete Cypher script from an exploration session.
+ *
+ * Each step becomes a +/- prefixed statement. The output is formatted
+ * as a semicolon-delimited script with comments showing the exploration
+ * narrative (action type, concept name, timestamp).
+ *
+ * @param session - The exploration session to convert
+ * @returns A multi-statement Cypher script with +/- operator prefixes
+ */
+export function generateCypher(session: ExplorationSession): string {
+  const { steps } = session;
+  if (steps.length === 0) return '-- No exploration steps recorded';
+
+  const lines: string[] = [];
+
+  // Header
+  lines.push(`-- Exploration: ${session.name || 'Untitled'}`);
+  lines.push(`-- Generated: ${new Date().toISOString()}`);
+  lines.push(`-- Steps: ${steps.length}`);
+  lines.push('');
+
+  // Each step as an operator-prefixed statement
+  steps.forEach((step, idx) => {
+    const actionLabel = step.action === 'load-path'
+      ? `${step.action} "${step.conceptLabel}" → "${step.destinationConceptLabel}"`
+      : `${step.action} "${step.conceptLabel}"`;
+
+    lines.push(`-- Step ${idx + 1}: ${actionLabel}`);
+    lines.push(`${step.op} ${step.cypher};`);
+    lines.push('');
+  });
+
+  return lines.join('\n').trimEnd();
+}
+
+/**
+ * Parse a +/- prefixed Cypher script back into individual statements.
+ *
+ * This is the inverse of generateCypher — it takes the editor text and
+ * extracts the operator and Cypher for each statement. Comments are ignored.
+ *
+ * @param script - The Cypher script text (from the editor)
+ * @returns Array of { op, cypher } pairs
+ */
+export function parseCypherStatements(
+  script: string
+): Array<{ op: '+' | '-'; cypher: string }> {
+  const results: Array<{ op: '+' | '-'; cypher: string }> = [];
+  const lines = script.split('\n');
+
+  let currentOp: '+' | '-' | null = null;
+  let currentLines: string[] = [];
+
+  const flush = () => {
+    if (currentOp && currentLines.length > 0) {
+      const cypher = currentLines.join('\n').replace(/;\s*$/, '').trim();
+      if (cypher) {
+        results.push({ op: currentOp, cypher });
+      }
+    }
+    currentOp = null;
+    currentLines = [];
+  };
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    // Skip comments and blank lines between statements
+    if (trimmed.startsWith('--') || trimmed === '') {
+      // If we're accumulating a statement and hit a blank line, flush
+      if (currentOp && currentLines.length > 0 && trimmed === '') {
+        flush();
+      }
+      continue;
+    }
+
+    // Check for operator prefix at start of a new statement
+    if (trimmed.startsWith('+ ') || trimmed.startsWith('- ')) {
+      flush();
+      currentOp = trimmed[0] as '+' | '-';
+      currentLines.push(trimmed.slice(2));
+    } else if (currentOp) {
+      // Continuation of current statement
+      currentLines.push(trimmed);
+    } else {
+      // No operator prefix — treat as additive by default
+      currentOp = '+';
+      currentLines.push(trimmed);
+    }
+  }
+
+  flush();
+  return results;
+}
diff --git a/web/src/views/ExplorerView.tsx b/web/src/views/ExplorerView.tsx
index 72079b6e..25c87ec7 100644
--- a/web/src/views/ExplorerView.tsx
+++ b/web/src/views/ExplorerView.tsx
@@ -24,6 +24,7 @@ import { Settings3DPanel } from '../explorers/common/3DSettingsPanel';
 import { SLIDER_RANGES as SLIDER_RANGES_2D } from '../explorers/ForceGraph2D/types';
 import { SLIDER_RANGES as SLIDER_RANGES_3D } from '../explorers/ForceGraph3D/types';
 import { getZIndexValue } from '../config/zIndex';
+import { stepToCypher } from '../utils/cypherGenerator';
 import type { VisualizationType } from '../types/explorer';
 
 interface ExplorerViewProps {
@@ -261,14 +262,22 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
 
   const ExplorerComponent = explorerPlugin.component;
 
-  // Follow Concept: load clicked node's neighborhood
+  /** Follow Concept: load clicked node's neighborhood and record the step */
   const handleNodeClick = useCallback((nodeId: string) => {
     const store = useGraphStore.getState();
 
-    // Resolve label from current graph data for SearchBar display
     const nodeLabel = store.rawGraphData?.nodes?.find(
       (n: any) => (n.concept_id || n.id) === nodeId
-    )?.label;
+    )?.label || nodeId;
+
+    store.addExplorationStep({
+      action: 'add-adjacent',
+      op: '+',
+      cypher: stepToCypher({ action: 'add-adjacent', conceptLabel: nodeLabel, depth: 2 }),
+      conceptId: nodeId,
+      conceptLabel: nodeLabel,
+      depth: 2,
+    });
 
     store.setFocusedNodeId(nodeId);
     store.setSearchParams({

From 95c26d16fb26a1926f6c031bfa0bb198f758f467 Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 22:10:48 -0600
Subject: [PATCH 13/23] feat: add "Remove from Graph" context menu with
 subtractive tracking

Right-clicking a node now shows "Remove from Graph" which removes the
node and its connections via subtractRawGraphData, recording a step
with op: '-' for the exploration session's Cypher trail.
---
 .../explorers/ForceGraph2D/ForceGraph2D.tsx   |  3 +-
 .../explorers/ForceGraph3D/ForceGraph3D.tsx   |  3 +-
 .../explorers/common/useGraphContextMenu.ts   | 37 ++++++++++++++++++-
 3 files changed, 40 insertions(+), 3 deletions(-)

diff --git a/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx b/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx
index 246f20fb..6886fd1c 100644
--- a/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx
+++ b/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx
@@ -1524,7 +1524,7 @@ export const ForceGraph2D: React.FC<
   }, [graphData]);
 
   // Use common graph navigation hook
-  const { handleFollowConcept, handleAddToGraph } = useGraphNavigation(mergeGraphData);
+  const { handleFollowConcept, handleAddToGraph, handleRemoveFromGraph } = useGraphNavigation(mergeGraphData);
 
   // Pin/Unpin node functionality
   const isPinned = useCallback((nodeId: string): boolean => {
@@ -1640,6 +1640,7 @@ export const ForceGraph2D: React.FC<
         {
           handleFollowConcept,
           handleAddToGraph,
+          handleRemoveFromGraph,
           setOriginNode: setOriginNodeId,
           setDestinationNode: setDestinationNodeId,
           travelToOrigin,
diff --git a/web/src/explorers/ForceGraph3D/ForceGraph3D.tsx b/web/src/explorers/ForceGraph3D/ForceGraph3D.tsx
index 9c8cf0e1..861e9cd4 100644
--- a/web/src/explorers/ForceGraph3D/ForceGraph3D.tsx
+++ b/web/src/explorers/ForceGraph3D/ForceGraph3D.tsx
@@ -944,7 +944,7 @@ export const ForceGraph3D: React.FC<
   }, [graphData]);
 
   // Use common graph navigation hook
-  const { handleFollowConcept, handleAddToGraph } = useGraphNavigation(mergeGraphData);
+  const { handleFollowConcept, handleAddToGraph, handleRemoveFromGraph } = useGraphNavigation(mergeGraphData);
 
   // Pin/Unpin node functionality for 3D
   const isPinned = useCallback((nodeId: string): boolean => {
@@ -1319,6 +1319,7 @@ export const ForceGraph3D: React.FC<
         {
           handleFollowConcept,
           handleAddToGraph,
+          handleRemoveFromGraph,
           setOriginNode: setOriginNodeId,
           setDestinationNode: setDestinationNodeId,
           travelToOrigin,
diff --git a/web/src/explorers/common/useGraphContextMenu.ts b/web/src/explorers/common/useGraphContextMenu.ts
index ffabb61b..06ec5009 100644
--- a/web/src/explorers/common/useGraphContextMenu.ts
+++ b/web/src/explorers/common/useGraphContextMenu.ts
@@ -18,6 +18,7 @@ import type { ContextMenuItem } from '../../components/shared/ContextMenu';
 import {
   ArrowRight,
   Plus,
+  Minus,
   MapPin,
   MapPinOff,
   Pin,
@@ -41,6 +42,7 @@ export interface GraphContextMenuHandlers {
   // Generic handlers (provided by hook)
   handleFollowConcept: (nodeId: string) => Promise<void>;
   handleAddToGraph: (nodeId: string) => Promise<void>;
+  handleRemoveFromGraph: (nodeId: string) => void;
   setOriginNode: (nodeId: string | null) => void;
   setDestinationNode: (nodeId: string | null) => void;
   travelToOrigin?: () => void;  // Optional navigation to origin node
@@ -130,7 +132,30 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
     }
   }, [mergeRawGraphData, setFocusedNodeId]);
 
-  return { handleFollowConcept, handleAddToGraph };
+  /** Remove node and its connections from the graph, recording a subtractive step */
+  const handleRemoveFromGraph = useCallback((nodeId: string) => {
+    const store = useGraphStore.getState();
+    const node = store.rawGraphData?.nodes?.find(
+      (n: any) => (n.concept_id || n.id) === nodeId
+    );
+    const nodeLabel = node?.label || nodeId;
+
+    store.addExplorationStep({
+      action: 'add-adjacent',
+      op: '-',
+      cypher: stepToCypher({ action: 'add-adjacent', conceptLabel: nodeLabel, depth: 1 }),
+      conceptId: nodeId,
+      conceptLabel: nodeLabel,
+      depth: 1,
+    });
+
+    store.subtractRawGraphData({
+      nodes: [{ id: nodeId, concept_id: nodeId }],
+      links: [],
+    });
+  }, []);
+
+  return { handleFollowConcept, handleAddToGraph, handleRemoveFromGraph };
 }
 
 /**
@@ -152,6 +177,7 @@ export function buildContextMenuItems(
     applyDestinationMarker,
     handleFollowConcept,
     handleAddToGraph,
+    handleRemoveFromGraph,
     setOriginNode,
     setDestinationNode,
     travelToOrigin,
@@ -376,6 +402,15 @@ export function buildContextMenuItems(
       },
     });
 
+    items.push({
+      label: `Remove from Graph`,
+      icon: Minus,
+      onClick: () => {
+        handleRemoveFromGraph(nodeId);
+        onClose();
+      },
+    });
+
     // Focus on Node (only if not already focused)
     if (focusedNodeId !== nodeId) {
       items.push({

From 34f0cd3ea36fa9a953bd6ff647f4e1d4c90f346a Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 22:43:33 -0600
Subject: [PATCH 14/23] refactor: D3Node/D3Link extend API types, store is
 source of truth

D3Node now extends APIGraphNode and D3Link extends APIGraphLink.
The transform spreads all API fields through instead of stripping
them, so the full payload (search_terms, grounding_display,
confidence_level, etc.) is available on graph nodes without
re-fetching from the API.
---
 .claude/todo-unified-query-exploration.md | 15 +++++----
 web/src/types/graph.ts                    | 40 ++++++++++-------------
 web/src/utils/graphTransform.ts           | 11 ++++---
 3 files changed, 31 insertions(+), 35 deletions(-)

diff --git a/.claude/todo-unified-query-exploration.md b/.claude/todo-unified-query-exploration.md
index cbd40201..91b729cc 100644
--- a/.claude/todo-unified-query-exploration.md
+++ b/.claude/todo-unified-query-exploration.md
@@ -36,12 +36,13 @@ Folder icon in the nav rail across all explorer views. Same saved queries list,
 
 ## Implementation Phases
 
-### Phase 1: Exploration Tracking & Cypher Generation
-- [ ] Add `ExplorationStep` type and `explorationSession` to graphStore
-- [ ] Add `addExplorationStep()`, `clearExploration()` store actions
-- [ ] Record steps at action points: handleLoadExplore, handleLoadPath, handleFollowConcept, handleAddToGraph
-- [ ] Create `cypherGenerator.ts` — convert steps to ordered Cypher statements with +/- operators
-- [ ] Persist `rawGraphData` + `explorationSession` to localStorage (survive refresh)
+### Phase 1: Exploration Tracking & Cypher Generation ✓
+- [x] Add `ExplorationStep` type and `explorationSession` to graphStore
+- [x] Add `addExplorationStep()`, `clearExploration()` store actions
+- [x] Record steps at action points: handleLoadExplore, handleLoadPath, handleFollowConcept, handleAddToGraph
+- [x] Create `cypherGenerator.ts` — convert steps to ordered Cypher statements with +/- operators
+- [x] Persist `rawGraphData` + `explorationSession` to localStorage (survive refresh)
+- [x] Add `subtractRawGraphData` and "Remove from Graph" context menu (op: '-')
 
 ### Phase 2: Saved Queries Folder
 - [ ] Unify sidebar folder icon across all explorer views (consistent with report explorer pattern)
@@ -54,7 +55,7 @@ Folder icon in the nav rail across all explorer views. Same saved queries list,
 - [ ] "Export as Cypher" sends ordered statements to the Cypher editor
 - [ ] Cypher editor displays +/- prefixed statements
 - [ ] Execute from editor replays the statement sequence
-- [ ] Subtractive operator: context menu "Remove from Graph" option
+- [x] Subtractive operator: context menu "Remove from Graph" option
 
 ### Phase 4: Cross-Explorer Flow
 - [ ] Vocabulary explorer reads same saved queries from folder
diff --git a/web/src/types/graph.ts b/web/src/types/graph.ts
index 6bffca54..b457fcd8 100644
--- a/web/src/types/graph.ts
+++ b/web/src/types/graph.ts
@@ -37,33 +37,27 @@ export interface SubgraphResponse {
 }
 
 // D3 Visualization Types
-export interface D3Node {
-  id: string;
-  label: string;
-  group: string; // ontology
-  size: number; // node size (degree-based)
-  color: string;
-  grounding?: number; // grounding strength (-1.0 to +1.0)
-  centrality?: number; // centrality measure for graph analysis
-  fx?: number; // fixed position X
-  fy?: number; // fixed position Y
-  fz?: number; // fixed position Z (for 3D)
-  x?: number; // computed position X
-  y?: number; // computed position Y
-  z?: number; // computed position Z (for 3D)
-  vx?: number; // velocity X
-  vy?: number; // velocity Y
-  vz?: number; // velocity Z (for 3D)
+// Extend API types so the full API payload flows through to the renderer.
+// D3 only needs `id` for node identity — everything else is carried along
+// so UI components can read from the store without re-fetching.
+export interface D3Node extends APIGraphNode {
+  id: string;           // alias for concept_id (D3 requires `id`)
+  group: string;        // alias for ontology
+  grounding?: number;   // alias for grounding_strength
+  size: number;         // calculated from degree
+  color: string;        // calculated from ontology
+  centrality?: number;
+  fx?: number; fy?: number; fz?: number;  // fixed positions
+  x?: number;  y?: number;  z?: number;   // computed positions
+  vx?: number; vy?: number; vz?: number;  // velocities
 }
 
-export interface D3Link {
+export interface D3Link extends APIGraphLink {
   source: string | D3Node;
   target: string | D3Node;
-  type: string;
-  value: number; // category confidence or weight
-  color: string;
-  confidence?: number; // edge confidence score
-  category?: string; // relationship category from vocabulary
+  type: string;    // alias for relationship_type
+  value: number;   // category confidence for rendering
+  color: string;   // category color
 }
 
 export interface GraphData {
diff --git a/web/src/utils/graphTransform.ts b/web/src/utils/graphTransform.ts
index d82bd637..53cb0595 100644
--- a/web/src/utils/graphTransform.ts
+++ b/web/src/utils/graphTransform.ts
@@ -40,14 +40,14 @@ export function transformForD3(
       return d3.interpolateTurbo(t);
     }));
 
-  // Transform nodes (with grounding strength)
+  // Transform nodes — spread all API fields, add visualization aliases
   const nodes: D3Node[] = apiNodes.map(node => ({
+    ...node,
     id: node.concept_id,
-    label: node.label,
     group: node.ontology,
+    grounding: node.grounding_strength,
     size: 10, // Will be updated with degree
     color: colorScale(node.ontology),
-    grounding: node.grounding_strength, // -1.0 to +1.0
   }));
 
   // Transform links - enrich with vocabulary data from store
@@ -69,12 +69,13 @@ export function transformForD3(
     const categoryConfidence = vocabStore.getConfidence(link.relationship_type) || 1.0;
 
     return {
+      ...link,
       source: link.from_id,
       target: link.to_id,
       type: link.relationship_type,
-      value: categoryConfidence, // Use category confidence for visualization
+      value: categoryConfidence,
       color: getCategoryColor(category),
-      category, // Store category for info boxes
+      category,
     };
   });
 

From 7383f3bf9623f688a70498fe7646f203e03264f2 Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 22:48:57 -0600
Subject: [PATCH 15/23] fix: getSubgraph hydrates relationship targets missed
 by traversal
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The /query/related BFS can miss neighbors (stale accelerator, edge
type gaps). Now getSubgraph discovers relationship targets from
concept details and fetches any missing ones, so the subgraph is
complete even when traversal is incomplete.

Also fixes duplicate edges: normalizes dedup key to treat A→B and
B→A with same type as one edge.
---
 web/src/api/client.ts | 34 +++++++++++++++++++++++++++++++---
 1 file changed, 31 insertions(+), 3 deletions(-)

diff --git a/web/src/api/client.ts b/web/src/api/client.ts
index ce78f195..b8cdfd51 100644
--- a/web/src/api/client.ts
+++ b/web/src/api/client.ts
@@ -98,7 +98,33 @@ class APIClient {
       }).then(r => r.data).catch(() => null)
     );
 
-    const allConceptDetails = (await Promise.all(conceptDetailsPromises)).filter(Boolean);
+    let allConceptDetails = (await Promise.all(conceptDetailsPromises)).filter(Boolean);
+
+    // Step 3b: Discover relationship targets missing from our set and fetch them.
+    // The /query/related traversal can miss neighbors (stale accelerator, etc.),
+    // but concept details include the actual relationships. Hydrate any targets
+    // we don't already have so the subgraph is complete.
+    const fetchedIds = new Set(allConceptIds);
+    const missingIds: string[] = [];
+    allConceptDetails.forEach((concept: any) => {
+      (concept.relationships || []).forEach((rel: any) => {
+        if (rel.to_id && !fetchedIds.has(rel.to_id)) {
+          fetchedIds.add(rel.to_id);
+          missingIds.push(rel.to_id);
+        }
+      });
+    });
+
+    if (missingIds.length > 0) {
+      const extraDetails = (await Promise.all(
+        missingIds.map(id =>
+          this.client.get(`/query/concept/${id}`, {
+            params: { include_grounding: false }
+          }).then(r => r.data).catch(() => null)
+        )
+      )).filter(Boolean);
+      allConceptDetails = [...allConceptDetails, ...extraDetails];
+    }
 
     // Step 4: Build nodes array (with grounding strength)
     const nodes = allConceptDetails.map((concept: any) => ({
@@ -111,7 +137,7 @@ class APIClient {
 
     // Step 5: Build links array from ALL concepts' relationships
     // Only include links where both source and target are in our node set
-    const nodeIdSet = new Set(allConceptIds);
+    const nodeIdSet = new Set(allConceptDetails.map((c: any) => c.concept_id));
     const links: any[] = [];
     const seenEdges = new Set<string>(); // Deduplicate edges
 
@@ -120,7 +146,9 @@ class APIClient {
         concept.relationships.forEach((rel: any) => {
           // Only include if target is in our subgraph
           if (nodeIdSet.has(rel.to_id)) {
-            const edgeKey = `${concept.concept_id}->${rel.to_id}-${rel.rel_type}`;
+            // Deduplicate: normalize edge key to treat A→B and B→A same-type as one edge
+            const [lo, hi] = [concept.concept_id, rel.to_id].sort();
+            const edgeKey = `${lo}<>${hi}-${rel.rel_type}`;
             if (!seenEdges.has(edgeKey)) {
               seenEdges.add(edgeKey);
               links.push({

From f3e6aa72a4d5727d09114e39675cdf4f2159fafd Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 23:07:39 -0600
Subject: [PATCH 16/23] feat: saved queries folder with save/load/delete (Phase
 2)

- FolderOpen icon in sidebar nav rail (consistent with report explorer)
- Save button appears when exploration has steps, stores as
  QueryDefinition with definition_type 'exploration'
- Load replays +/- Cypher statements sequentially via executeCypherQuery
- Query list shows step count and date for exploration queries
- Delete uses existing queryDefinitionStore infrastructure
---
 .claude/todo-unified-query-exploration.md | 12 ++--
 web/src/views/ExplorerView.tsx            | 88 +++++++++++++++++++++--
 2 files changed, 88 insertions(+), 12 deletions(-)

diff --git a/.claude/todo-unified-query-exploration.md b/.claude/todo-unified-query-exploration.md
index 91b729cc..fac44375 100644
--- a/.claude/todo-unified-query-exploration.md
+++ b/.claude/todo-unified-query-exploration.md
@@ -44,12 +44,12 @@ Folder icon in the nav rail across all explorer views. Same saved queries list,
 - [x] Persist `rawGraphData` + `explorationSession` to localStorage (survive refresh)
 - [x] Add `subtractRawGraphData` and "Remove from Graph" context menu (op: '-')
 
-### Phase 2: Saved Queries Folder
-- [ ] Unify sidebar folder icon across all explorer views (consistent with report explorer pattern)
-- [ ] Saved query data model: `{ name, statements: { op, cypher }[] }`
-- [ ] Save exploration → creates QueryDefinition with `definition_type: 'exploration'`
-- [ ] Load saved query → executes statements in order with +/- semantics
-- [ ] Delete saved query
+### Phase 2: Saved Queries Folder ✓
+- [x] Unify sidebar folder icon across all explorer views (FolderOpen, consistent with report explorer)
+- [x] Saved query data model: `{ name, statements: { op, cypher }[] }` via QueryDefinition
+- [x] Save exploration → creates QueryDefinition with `definition_type: 'exploration'`
+- [x] Load saved query → replays statements in order with +/- semantics via executeCypherQuery
+- [x] Delete saved query (already worked via queryDefinitionStore)
 
 ### Phase 3: Editor Integration
 - [ ] "Export as Cypher" sends ordered statements to the Cypher editor
diff --git a/web/src/views/ExplorerView.tsx b/web/src/views/ExplorerView.tsx
index 25c87ec7..deb696ad 100644
--- a/web/src/views/ExplorerView.tsx
+++ b/web/src/views/ExplorerView.tsx
@@ -10,7 +10,7 @@
 
 import React, { useState, useEffect, useCallback, useMemo } from 'react';
 import { useSearchParams, useNavigate } from 'react-router-dom';
-import { History, Settings, Trash2 } from 'lucide-react';
+import { FolderOpen, Save, Settings, Trash2 } from 'lucide-react';
 import { SearchBar } from '../components/shared/SearchBar';
 import { IconRailPanel } from '../components/shared/IconRailPanel';
 import { useGraphStore, deriveMode } from '../store/graphStore';
@@ -24,7 +24,8 @@ import { Settings3DPanel } from '../explorers/common/3DSettingsPanel';
 import { SLIDER_RANGES as SLIDER_RANGES_2D } from '../explorers/ForceGraph2D/types';
 import { SLIDER_RANGES as SLIDER_RANGES_3D } from '../explorers/ForceGraph3D/types';
 import { getZIndexValue } from '../config/zIndex';
-import { stepToCypher } from '../utils/cypherGenerator';
+import { apiClient } from '../api/client';
+import { stepToCypher, generateCypher, parseCypherStatements } from '../utils/cypherGenerator';
 import type { VisualizationType } from '../types/explorer';
 
 interface ExplorerViewProps {
@@ -45,12 +46,15 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     setSelectedExplorer,
     setSearchParams,
     setSimilarityThreshold,
+    explorationSession,
+    subtractRawGraphData,
   } = useGraphStore();
   const { addReport } = useReportStore();
   const {
     definitions: savedQueriesMap,
     definitionIds: savedQueryIds,
     loadDefinitions: loadSavedQueries,
+    createDefinition: createSavedQuery,
     deleteDefinition: deleteSavedQuery,
     isLoading: isLoadingQueries,
   } = useQueryDefinitionStore();
@@ -327,16 +331,73 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     navigate('/report');
   }, [rawGraphData, searchParams, mode, explorerType, addReport, navigate]);
 
+  // Save current exploration as a query definition
+  const handleSaveExploration = useCallback(async () => {
+    if (!explorationSession || explorationSession.steps.length === 0) return;
+
+    const cypherScript = generateCypher(explorationSession);
+    const statements = parseCypherStatements(cypherScript);
+
+    const name = explorationSession.name
+      || `Exploration ${new Date().toLocaleDateString()} ${new Date().toLocaleTimeString()}`;
+
+    await createSavedQuery({
+      name,
+      definition_type: 'exploration',
+      definition: { statements },
+      metadata: {
+        stepCount: explorationSession.steps.length,
+        createdFrom: explorerType,
+      },
+    });
+  }, [explorationSession, createSavedQuery, explorerType]);
+
   // Load a saved query
-  const handleLoadQuery = useCallback((query: any) => {
+  const handleLoadQuery = useCallback(async (query: any) => {
     const definition = query.definition;
+
+    // Exploration-type: replay +/- Cypher statements
+    if (query.definition_type === 'exploration' && definition?.statements) {
+      setGraphData(null);
+      setRawGraphData(null);
+
+      for (const stmt of definition.statements as Array<{ op: '+' | '-'; cypher: string }>) {
+        try {
+          const result = await apiClient.executeCypherQuery({ query: stmt.cypher, limit: 500 });
+          const nodes = (result.nodes || []).map((n: any) => ({
+            concept_id: n.id,
+            label: n.label,
+            ontology: n.properties?.ontology || 'default',
+            search_terms: n.properties?.search_terms || [],
+            grounding_strength: n.properties?.grounding_strength,
+          }));
+          const links = (result.relationships || []).map((r: any) => ({
+            from_id: r.from_id,
+            to_id: r.to_id,
+            relationship_type: r.type,
+            confidence: r.confidence,
+          }));
+
+          if (stmt.op === '+') {
+            mergeRawGraphData({ nodes, links });
+          } else {
+            subtractRawGraphData({ nodes, links });
+          }
+        } catch (error) {
+          console.error('Failed to replay statement:', stmt.cypher, error);
+        }
+      }
+      return;
+    }
+
+    // Legacy: searchParams-based queries
     if (definition?.searchParams) {
       setSearchParams(definition.searchParams);
       if (definition.similarityThreshold) {
         setSimilarityThreshold(definition.similarityThreshold);
       }
     }
-  }, [setSearchParams, setSimilarityThreshold]);
+  }, [setGraphData, setRawGraphData, mergeRawGraphData, subtractRawGraphData, setSearchParams, setSimilarityThreshold]);
 
   // Delete a saved query
   const handleDeleteQuery = useCallback(async (id: number, e: React.MouseEvent) => {
@@ -344,16 +405,27 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     await deleteSavedQuery(id);
   }, [deleteSavedQuery]);
 
+  const hasExploration = explorationSession && explorationSession.steps.length > 0;
+
   // Saved queries panel content
   const savedQueriesPanelContent = (
     <div className="p-3">
+      {hasExploration && (
+        <button
+          onClick={handleSaveExploration}
+          className="w-full flex items-center gap-2 px-3 py-2 mb-3 text-sm font-medium rounded-lg border border-primary/30 bg-primary/5 hover:bg-primary/10 text-primary transition-colors"
+        >
+          <Save className="w-4 h-4" />
+          Save Current Exploration ({explorationSession.steps.length} steps)
+        </button>
+      )}
       {isLoadingQueries ? (
         <div className="text-center text-muted-foreground text-sm py-4">
           Loading...
         </div>
       ) : savedQueries.length === 0 ? (
         <div className="text-center text-muted-foreground text-sm py-4">
-          <History className="w-8 h-8 mx-auto mb-2 opacity-50" />
+          <FolderOpen className="w-8 h-8 mx-auto mb-2 opacity-50" />
           <p>No saved queries</p>
           <p className="text-xs mt-1">Save queries from the search panel</p>
         </div>
@@ -369,6 +441,10 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
                 <div className="flex-1 min-w-0">
                   <div className="font-medium text-sm truncate">{query.name}</div>
                   <div className="text-xs text-muted-foreground mt-1">
+                    {query.definition_type === 'exploration'
+                      ? `${(query.definition as any)?.statements?.length || 0} steps`
+                      : query.definition_type}
+                    {' \u00b7 '}
                     {new Date(query.created_at).toLocaleDateString()}
                   </div>
                 </div>
@@ -421,7 +497,7 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     {
       id: 'history',
       label: 'Saved Queries',
-      icon: History,
+      icon: FolderOpen,
       content: savedQueriesPanelContent,
     },
     {

From b571a43146fdc1aa8888088bedd50d3ea0c0155f Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 23:15:04 -0600
Subject: [PATCH 17/23] feat: add 'exploration' definition type for saved
 queries

Migration 050 adds 'exploration' to the query_definitions CHECK
constraint and Pydantic model, enabling graph explorations to be
saved as ordered +/- Cypher statement sequences.
---
 api/app/models/query_definition.py            |  5 ++-
 .../050_exploration_definition_type.sql       | 41 +++++++++++++++++++
 2 files changed, 44 insertions(+), 2 deletions(-)
 create mode 100644 schema/migrations/050_exploration_definition_type.sql

diff --git a/api/app/models/query_definition.py b/api/app/models/query_definition.py
index 56901aae..2875b373 100644
--- a/api/app/models/query_definition.py
+++ b/api/app/models/query_definition.py
@@ -15,10 +15,11 @@
     'cypher',
     'search',
     'polarity',
-    'connection'
+    'connection',
+    'exploration'
 ]
 
-DefinitionType = Literal['block_diagram', 'cypher', 'search', 'polarity', 'connection']
+DefinitionType = Literal['block_diagram', 'cypher', 'search', 'polarity', 'connection', 'exploration']
 
 
 class QueryDefinitionCreate(BaseModel):
diff --git a/schema/migrations/050_exploration_definition_type.sql b/schema/migrations/050_exploration_definition_type.sql
new file mode 100644
index 00000000..5fb476be
--- /dev/null
+++ b/schema/migrations/050_exploration_definition_type.sql
@@ -0,0 +1,41 @@
+-- Migration 050: Add 'exploration' to query_definitions definition_type
+--
+-- Supports saving graph explorations as ordered +/- Cypher statement sequences.
+-- Each exploration is a replayable series of additive/subtractive graph operations.
+-- ===========================================================================
+
+-- Skip if already applied
+DO $$
+BEGIN
+    IF EXISTS (SELECT 1 FROM public.schema_migrations WHERE version = 50) THEN
+        RAISE NOTICE 'Migration 050 already applied, skipping';
+        RETURN;
+    END IF;
+
+    -- Drop and recreate CHECK constraint to include 'exploration'
+    ALTER TABLE kg_api.query_definitions
+        DROP CONSTRAINT IF EXISTS valid_definition_type;
+
+    ALTER TABLE kg_api.query_definitions
+        ADD CONSTRAINT valid_definition_type CHECK (definition_type IN (
+            'block_diagram',
+            'cypher',
+            'search',
+            'polarity',
+            'connection',
+            'exploration'
+        ));
+
+    COMMENT ON COLUMN kg_api.query_definitions.definition_type IS
+        'Type of query: block_diagram, cypher, search, polarity, connection, exploration';
+
+    RAISE NOTICE 'Migration 050: Added exploration definition type';
+END $$;
+
+-- ===========================================================================
+-- Record Migration
+-- ===========================================================================
+
+INSERT INTO public.schema_migrations (version, name)
+VALUES (50, 'exploration_definition_type')
+ON CONFLICT (version) DO NOTHING;

From 81b0080bac4f8f6cfab03b517a891c45830de1ba Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Mon, 2 Feb 2026 23:18:47 -0600
Subject: [PATCH 18/23] fix: merge request data into cached definition after
 create

API's QueryDefinitionCreateResponse omits `definition` and `metadata`
fields, so saved queries showed "0 steps" until the next full fetch.
---
 web/src/store/queryDefinitionStore.ts | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/web/src/store/queryDefinitionStore.ts b/web/src/store/queryDefinitionStore.ts
index 79affc1a..0bfebe85 100644
--- a/web/src/store/queryDefinitionStore.ts
+++ b/web/src/store/queryDefinitionStore.ts
@@ -138,17 +138,24 @@ export const useQueryDefinitionStore = create<QueryDefinitionStore>()(
           const created = await apiClient.createQueryDefinition(definition);
 
           // Add to store (prepend to show newest first)
+          // The create response omits `definition` and `metadata` — merge from the request
           const existing = get().definitions;
           const existingIds = get().definitionIds;
+          const full = {
+            ...created,
+            definition: definition.definition,
+            metadata: definition.metadata || null,
+            owner_id: null,
+          };
 
           set({
-            definitions: { ...existing, [created.id]: created },
+            definitions: { ...existing, [created.id]: full },
             definitionIds: [created.id, ...existingIds],
             total: get().total + 1,
             isLoading: false,
           });
 
-          return created;
+          return full as any;
         } catch (e: unknown) {
           const message = e instanceof Error ? e.message : 'Failed to create query definition';
           set({ isLoading: false, error: message });

From 81b4fdfc200bf347feb765c8b710fa0bb18a238e Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Tue, 3 Feb 2026 09:37:41 -0600
Subject: [PATCH 19/23] fix: Cypher endpoint misidentified edges as nodes,
 breaking saved query replay

Server: individual edges returned from RETURN c, r, n have both `id` and
`start_id`/`end_id`. The parser checked `id` first, so edges were silently
captured as nodes and `result.relationships` was empty.

Client: replay mapped AGE internal vertex IDs as concept_ids. Added
internalToConceptId translation map (matching BlockBuilder's pattern).
---
 api/app/routes/queries.py      | 14 ++++++++++++--
 web/src/views/ExplorerView.tsx | 15 ++++++++++++---
 2 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/api/app/routes/queries.py b/api/app/routes/queries.py
index a8a3a803..96da5a41 100644
--- a/api/app/routes/queries.py
+++ b/api/app/routes/queries.py
@@ -1643,8 +1643,18 @@ async def execute_cypher_query(
             # Extract nodes and relationships from each record
             for key, value in record.items():
                 if isinstance(value, dict):
-                    # Check if it's a node (has 'id' and typically 'label')
-                    if 'id' in value:
+                    # Check for relationship first (AGE edges have start_id/end_id)
+                    start_id = value.get('start_id') or value.get('start')
+                    end_id = value.get('end_id') or value.get('end')
+
+                    if start_id and end_id:
+                        relationships.append(CypherRelationship(
+                            from_id=str(start_id),
+                            to_id=str(end_id),
+                            type=value.get('label', value.get('type', 'RELATED')),
+                            properties=value.get('properties', {})
+                        ))
+                    elif 'id' in value:
                         node_id = str(value['id'])
                         if node_id not in nodes_map:
                             # Prefer properties.label (actual name) over AGE label (node type like "Concept")
diff --git a/web/src/views/ExplorerView.tsx b/web/src/views/ExplorerView.tsx
index deb696ad..e6331289 100644
--- a/web/src/views/ExplorerView.tsx
+++ b/web/src/views/ExplorerView.tsx
@@ -364,17 +364,26 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
       for (const stmt of definition.statements as Array<{ op: '+' | '-'; cypher: string }>) {
         try {
           const result = await apiClient.executeCypherQuery({ query: stmt.cypher, limit: 500 });
+
+          // Build AGE internal ID → concept_id map
+          const internalToConceptId = new Map<string, string>();
+          (result.nodes || []).forEach((n: any) => {
+            const conceptId = n.properties?.concept_id || n.id;
+            internalToConceptId.set(n.id, conceptId);
+          });
+
           const nodes = (result.nodes || []).map((n: any) => ({
-            concept_id: n.id,
+            concept_id: n.properties?.concept_id || n.id,
             label: n.label,
             ontology: n.properties?.ontology || 'default',
             search_terms: n.properties?.search_terms || [],
             grounding_strength: n.properties?.grounding_strength,
           }));
           const links = (result.relationships || []).map((r: any) => ({
-            from_id: r.from_id,
-            to_id: r.to_id,
+            from_id: internalToConceptId.get(r.from_id) || r.from_id,
+            to_id: internalToConceptId.get(r.to_id) || r.to_id,
             relationship_type: r.type,
+            category: r.properties?.category,
             confidence: r.confidence,
           }));
 

From ce303a14b2ce59b5727173ce7976c655148261bc Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Tue, 3 Feb 2026 11:02:30 -0600
Subject: [PATCH 20/23] feat: add Travel path animation, Send to Polarity, and
 traversal reports

Context menu gains three new actions when origin+destination are set:
- Travel submenu (From Origin / From Destination) finds path, merges
  nodes into graph, and animates camera through each node sequentially
- Send to Polarity Explorer sets origin/destination as poles
- Send Path to Reports creates a traversal report with per-path tables

Traversal report type added to reportStore with rendering, CSV export,
and Markdown export in ReportWorkspace.
---
 web/src/components/report/ReportWorkspace.tsx | 158 ++++++++++
 .../explorers/ForceGraph2D/ForceGraph2D.tsx   |  44 ++-
 .../explorers/ForceGraph3D/ForceGraph3D.tsx   |  73 ++++-
 .../explorers/common/useGraphContextMenu.ts   | 297 ++++++++++++++++--
 web/src/store/reportStore.ts                  |  39 ++-
 5 files changed, 576 insertions(+), 35 deletions(-)

diff --git a/web/src/components/report/ReportWorkspace.tsx b/web/src/components/report/ReportWorkspace.tsx
index 2953400e..6fdea160 100644
--- a/web/src/components/report/ReportWorkspace.tsx
+++ b/web/src/components/report/ReportWorkspace.tsx
@@ -27,6 +27,7 @@ import {
   Save,
   Eye,
   X,
+  Route,
 } from 'lucide-react';
 import * as d3 from 'd3';
 import { IconRailPanel } from '../shared/IconRailPanel';
@@ -39,6 +40,7 @@ import {
   type GraphReportData,
   type PolarityReportData,
   type DocumentReportData,
+  type TraversalReportData,
   type PreviousValues,
 } from '../../store/reportStore';
 
@@ -269,6 +271,36 @@ const documentToCSV = (data: DocumentReportData): string => {
   return lines.join('\n');
 };
 
+// Convert traversal report to CSV
+const traversalToCSV = (data: TraversalReportData): string => {
+  const lines: string[] = [];
+
+  lines.push(`# Traversal`);
+  lines.push(`Origin,${data.origin.label}`);
+  lines.push(`Destination,${data.destination.label}`);
+  lines.push(`Max Hops,${data.maxHops}`);
+  lines.push(`Paths Found,${data.pathCount}`);
+
+  data.paths.forEach((path, i) => {
+    lines.push('');
+    lines.push(`# Path ${i + 1} (${path.hops} hops)`);
+    lines.push('Step,Label,Description,Grounding,Diversity,Relationship');
+    path.nodes.forEach((n, j) => {
+      const relAfter = j < path.relationships.length ? path.relationships[j] : '';
+      lines.push([
+        j + 1,
+        `"${(n.label || '').replace(/"/g, '""')}"`,
+        `"${(n.description || '').replace(/"/g, '""')}"`,
+        n.grounding_strength?.toFixed(3) || '',
+        n.diversity_score?.toFixed(3) || '',
+        relAfter,
+      ].join(','));
+    });
+  });
+
+  return lines.join('\n');
+};
+
 // Convert to Markdown
 const toMarkdown = (report: Report): string => {
   const lines: string[] = [];
@@ -319,6 +351,25 @@ const toMarkdown = (report: Report): string => {
     data.concepts.forEach(c => {
       lines.push(`| ${c.label} | ${c.position.toFixed(3)} | ${c.grounding_strength?.toFixed(2) || '-'} |`);
     });
+  } else if (report.type === 'traversal') {
+    const data = report.data as TraversalReportData;
+
+    lines.push('## Traversal');
+    lines.push(`- **Origin:** ${data.origin.label}`);
+    lines.push(`- **Destination:** ${data.destination.label}`);
+    lines.push(`- **Paths Found:** ${data.pathCount}`);
+
+    data.paths.forEach((path, i) => {
+      lines.push('');
+      lines.push(`### Path ${i + 1} (${path.hops} hops)`);
+      lines.push('');
+      path.nodes.forEach((n, j) => {
+        lines.push(`${j + 1}. **${n.label}**${n.grounding_strength != null ? ` (grounding: ${n.grounding_strength.toFixed(2)})` : ''}`);
+        if (j < path.relationships.length) {
+          lines.push(`   *${path.relationships[j]}* ↓`);
+        }
+      });
+    });
   } else {
     const data = report.data as DocumentReportData;
 
@@ -651,6 +702,7 @@ export const ReportWorkspace: React.FC = () => {
   const getReportIcon = (report: Report) => {
     if (report.type === 'polarity') return Compass;
     if (report.type === 'document') return FileText;
+    if (report.type === 'traversal') return Route;
     return GitBranch;
   };
 
@@ -678,6 +730,8 @@ export const ReportWorkspace: React.FC = () => {
               ? (report.data as GraphReportData).nodes.length
               : report.type === 'polarity'
               ? (report.data as PolarityReportData).concepts.length
+              : report.type === 'traversal'
+              ? (report.data as TraversalReportData).pathCount
               : (report.data as DocumentReportData).documents.length;
 
             return (
@@ -1149,6 +1203,106 @@ export const ReportWorkspace: React.FC = () => {
     );
   };
 
+  // Render table for traversal report
+  const renderTraversalTable = (data: TraversalReportData) => {
+    return (
+      <div className="space-y-6">
+        {/* Origin → Destination header */}
+        <div className="grid grid-cols-3 gap-3">
+          <div className="p-3 bg-muted/30 rounded-lg border text-center">
+            <div className="text-xs text-muted-foreground mb-1">Origin</div>
+            <div className="font-semibold text-sm">{data.origin.label}</div>
+          </div>
+          <div className="p-3 bg-muted/30 rounded-lg border text-center flex items-center justify-center">
+            <div>
+              <div className="text-xs text-muted-foreground mb-1">Paths</div>
+              <div className="font-semibold text-lg">{data.pathCount}</div>
+            </div>
+          </div>
+          <div className="p-3 bg-muted/30 rounded-lg border text-center">
+            <div className="text-xs text-muted-foreground mb-1">Destination</div>
+            <div className="font-semibold text-sm">{data.destination.label}</div>
+          </div>
+        </div>
+
+        {/* Paths */}
+        {data.paths.map((path, pathIdx) => (
+          <div key={pathIdx}>
+            <h3 className="text-sm font-semibold mb-2 flex items-center gap-2">
+              <Route className="w-4 h-4" />
+              Path {pathIdx + 1} ({path.hops} hops)
+            </h3>
+            <div className="border rounded-lg overflow-hidden">
+              <div className="overflow-x-auto">
+                <table className="w-full text-sm">
+                  <thead className="bg-muted/50">
+                    <tr>
+                      <th className="px-3 py-2 text-left text-xs font-medium text-muted-foreground w-12">#</th>
+                      <th className="px-3 py-2 text-left text-xs font-medium text-muted-foreground">Concept</th>
+                      <th className="px-3 py-2 text-left text-xs font-medium text-muted-foreground">Description</th>
+                      <th className="px-3 py-2 text-right text-xs font-medium text-muted-foreground">Grounding</th>
+                      <th className="px-3 py-2 text-right text-xs font-medium text-muted-foreground">Diversity</th>
+                      <th className="px-3 py-2 text-left text-xs font-medium text-muted-foreground w-32">Relationship</th>
+                    </tr>
+                  </thead>
+                  <tbody className="divide-y divide-border">
+                    {path.nodes.map((node, nodeIdx) => (
+                      <tr key={node.id} className="hover:bg-muted/30">
+                        <td className="px-3 py-2 text-muted-foreground font-mono text-xs">
+                          {nodeIdx + 1}
+                        </td>
+                        <td className="px-3 py-2 font-medium">
+                          {node.label}
+                        </td>
+                        <td className="px-3 py-2 text-muted-foreground text-xs max-w-xs truncate" title={node.description}>
+                          {node.description || '-'}
+                        </td>
+                        <td className="px-3 py-2 text-right">
+                          {node.grounding_strength != null ? (
+                            <span className={`font-mono text-xs px-1.5 py-0.5 rounded ${
+                              node.grounding_strength >= 0.7
+                                ? 'bg-green-500/20 text-green-600'
+                                : node.grounding_strength >= 0.3
+                                ? 'bg-yellow-500/20 text-yellow-600'
+                                : 'bg-red-500/20 text-red-600'
+                            }`}>
+                              {(node.grounding_strength * 100).toFixed(0)}%
+                            </span>
+                          ) : '-'}
+                        </td>
+                        <td className="px-3 py-2 text-right font-mono text-xs">
+                          {node.diversity_score?.toFixed(2) || '-'}
+                        </td>
+                        <td className="px-3 py-2">
+                          {nodeIdx < path.relationships.length ? (
+                            <span className="text-xs px-1.5 py-0.5 rounded"
+                              style={{
+                                backgroundColor: `${getCategoryColor(path.relationships[nodeIdx])}30`,
+                                color: getCategoryColor(path.relationships[nodeIdx]),
+                              }}
+                            >
+                              {path.relationships[nodeIdx]} ↓
+                            </span>
+                          ) : null}
+                        </td>
+                      </tr>
+                    ))}
+                  </tbody>
+                </table>
+              </div>
+            </div>
+          </div>
+        ))}
+
+        {data.pathCount === 0 && (
+          <div className="text-center text-muted-foreground py-8">
+            No paths found between origin and destination.
+          </div>
+        )}
+      </div>
+    );
+  };
+
   // Render table for document report
   const renderDocumentTable = (data: DocumentReportData) => {
     // Get all unique ontologies for color calculation
@@ -1335,6 +1489,8 @@ export const ReportWorkspace: React.FC = () => {
                     ? graphToCSV(selectedReport.data as GraphReportData)
                     : selectedReport.type === 'polarity'
                     ? polarityToCSV(selectedReport.data as PolarityReportData)
+                    : selectedReport.type === 'traversal'
+                    ? traversalToCSV(selectedReport.data as TraversalReportData)
                     : documentToCSV(selectedReport.data as DocumentReportData);
                   copyToClipboard(csv, 'csv', setCopiedFormat);
                 }}
@@ -1381,6 +1537,8 @@ export const ReportWorkspace: React.FC = () => {
               ? renderGraphTable(selectedReport.data as GraphReportData, selectedReport)
               : selectedReport.type === 'polarity'
               ? renderPolarityTable(selectedReport.data as PolarityReportData)
+              : selectedReport.type === 'traversal'
+              ? renderTraversalTable(selectedReport.data as TraversalReportData)
               : renderDocumentTable(selectedReport.data as DocumentReportData)
           ) : (
             <div className="h-full flex items-center justify-center">
diff --git a/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx b/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx
index 6886fd1c..3e3af3ec 100644
--- a/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx
+++ b/web/src/explorers/ForceGraph2D/ForceGraph2D.tsx
@@ -1524,7 +1524,7 @@ export const ForceGraph2D: React.FC<
   }, [graphData]);
 
   // Use common graph navigation hook
-  const { handleFollowConcept, handleAddToGraph, handleRemoveFromGraph } = useGraphNavigation(mergeGraphData);
+  const { handleFollowConcept, handleAddToGraph, handleRemoveFromGraph, handleTravelPath, handleSendToPolarity, handleSendPathToReports } = useGraphNavigation(mergeGraphData);
 
   // Pin/Unpin node functionality
   const isPinned = useCallback((nodeId: string): boolean => {
@@ -1630,6 +1630,44 @@ export const ForceGraph2D: React.FC<
       );
   }, [destinationNodeId, data.nodes, dimensions]);
 
+  // Travel along a path — sequentially animate camera through each node
+  const travelAlongPath = useCallback((nodeIds: string[], reverse = false) => {
+    if (!svgRef.current || !zoomBehaviorRef.current || nodeIds.length === 0) return;
+
+    const orderedIds = reverse ? [...nodeIds].reverse() : nodeIds;
+    const svg = d3.select(svgRef.current);
+    const { width, height } = dimensions;
+    const scale = 1.5;
+
+    let step = 0;
+    const visitNext = () => {
+      if (step >= orderedIds.length) return;
+      const node = data.nodes.find(n => n.id === orderedIds[step]);
+      if (!node || node.x === undefined || node.y === undefined) {
+        step++;
+        visitNext();
+        return;
+      }
+
+      const x = width / 2 - node.x * scale;
+      const y = height / 2 - node.y * scale;
+
+      svg.transition()
+        .duration(750)
+        .ease(d3.easeCubicInOut)
+        .call(
+          zoomBehaviorRef.current!.transform,
+          d3.zoomIdentity.translate(x, y).scale(scale)
+        )
+        .on('end', () => {
+          step++;
+          setTimeout(visitNext, 400);
+        });
+    };
+
+    visitNext();
+  }, [data.nodes, dimensions]);
+
   // Build unified context menu items (context-aware for node vs background)
   const contextMenuItems: ContextMenuItem[] = contextMenu
     ? buildContextMenuItems(
@@ -1645,6 +1683,7 @@ export const ForceGraph2D: React.FC<
           setDestinationNode: setDestinationNodeId,
           travelToOrigin,
           travelToDestination,
+          travelAlongPath,
           setFocusedNode,
           focusedNodeId: focusedNode,
           isPinned,
@@ -1655,7 +1694,8 @@ export const ForceGraph2D: React.FC<
         },
         { onClose: () => setContextMenu(null) },
         originNodeId,
-        destinationNodeId
+        destinationNodeId,
+        { handleTravelPath, handleSendToPolarity, handleSendPathToReports }
       )
     : [];
 
diff --git a/web/src/explorers/ForceGraph3D/ForceGraph3D.tsx b/web/src/explorers/ForceGraph3D/ForceGraph3D.tsx
index 861e9cd4..b3118a39 100644
--- a/web/src/explorers/ForceGraph3D/ForceGraph3D.tsx
+++ b/web/src/explorers/ForceGraph3D/ForceGraph3D.tsx
@@ -944,7 +944,7 @@ export const ForceGraph3D: React.FC<
   }, [graphData]);
 
   // Use common graph navigation hook
-  const { handleFollowConcept, handleAddToGraph, handleRemoveFromGraph } = useGraphNavigation(mergeGraphData);
+  const { handleFollowConcept, handleAddToGraph, handleRemoveFromGraph, handleTravelPath, handleSendToPolarity, handleSendPathToReports } = useGraphNavigation(mergeGraphData);
 
   // Pin/Unpin node functionality for 3D
   const isPinned = useCallback((nodeId: string): boolean => {
@@ -1299,6 +1299,73 @@ export const ForceGraph3D: React.FC<
     animate();
   }, [destinationNodeId, data.nodes]);
 
+  // Travel along a path — sequentially animate camera through each node
+  const travelAlongPath = useCallback((nodeIds: string[], reverse = false) => {
+    if (!fgRef.current || nodeIds.length === 0) return;
+
+    const orderedIds = reverse ? [...nodeIds].reverse() : nodeIds;
+
+    const easeInOutCubic = (t: number): number => {
+      return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+    };
+
+    const travelToNode = (nodeId: string): Promise<void> => {
+      return new Promise(resolve => {
+        const node = data.nodes.find(n => n.id === nodeId);
+        if (!node || node.x === undefined || node.y === undefined || node.z === undefined) {
+          resolve();
+          return;
+        }
+
+        const camera = fgRef.current!.camera();
+        const startPos = { x: camera.position.x, y: camera.position.y, z: camera.position.z };
+
+        const distance = 200;
+        const angle = Math.atan2(startPos.z - node.z!, startPos.x - node.x!);
+        const targetPos = {
+          x: node.x! + Math.cos(angle) * distance,
+          y: node.y! + 50,
+          z: node.z! + Math.sin(angle) * distance,
+        };
+
+        const duration = 750;
+        const startTime = Date.now();
+
+        const animate = () => {
+          const elapsed = Date.now() - startTime;
+          const progress = Math.min(elapsed / duration, 1);
+          const eased = easeInOutCubic(progress);
+
+          const currentPos = {
+            x: startPos.x + (targetPos.x - startPos.x) * eased,
+            y: startPos.y + (targetPos.y - startPos.y) * eased,
+            z: startPos.z + (targetPos.z - startPos.z) * eased,
+          };
+
+          fgRef.current?.cameraPosition(
+            currentPos,
+            { x: node.x!, y: node.y!, z: node.z! },
+            0
+          );
+
+          if (progress < 1) {
+            requestAnimationFrame(animate);
+          } else {
+            setTimeout(resolve, 400);
+          }
+        };
+
+        animate();
+      });
+    };
+
+    (async () => {
+      for (const id of orderedIds) {
+        await travelToNode(id);
+      }
+    })();
+  }, [data.nodes]);
+
   // Dismiss node info box
   const handleDismissNodeInfo = useCallback((nodeId: string) => {
     setActiveNodeInfos(prev => prev.filter(info => info.nodeId !== nodeId));
@@ -1324,6 +1391,7 @@ export const ForceGraph3D: React.FC<
           setDestinationNode: setDestinationNodeId,
           travelToOrigin,
           travelToDestination,
+          travelAlongPath,
           setFocusedNode,
           focusedNodeId: focusedNode,
           isPinned,
@@ -1334,7 +1402,8 @@ export const ForceGraph3D: React.FC<
         },
         { onClose: () => setContextMenu(null) },
         originNodeId,
-        destinationNodeId
+        destinationNodeId,
+        { handleTravelPath, handleSendToPolarity, handleSendPathToReports }
       )
     : [];
 
diff --git a/web/src/explorers/common/useGraphContextMenu.ts b/web/src/explorers/common/useGraphContextMenu.ts
index 06ec5009..5c299e62 100644
--- a/web/src/explorers/common/useGraphContextMenu.ts
+++ b/web/src/explorers/common/useGraphContextMenu.ts
@@ -3,17 +3,18 @@
  *
  * Provides common context menu functionality for both 2D and 3D explorers:
  * - Node context menu actions (follow, add, mark location)
- * - Canvas context menu actions (show/hide grid)
+ * - Canvas context menu actions (travel path, send to polarity)
  * - Generic navigation and graph manipulation
  *
  * Explorer-specific actions (pin/unpin for 2D vs 3D) are passed as callbacks.
  */
 
 import { useCallback } from 'react';
+import { useNavigate } from 'react-router-dom';
 import { apiClient } from '../../api/client';
-import { transformForD3 } from '../../utils/graphTransform';
 import { stepToCypher } from '../../utils/cypherGenerator';
 import { useGraphStore } from '../../store/graphStore';
+import { useReportStore, type TraversalReportData } from '../../store/reportStore';
 import type { ContextMenuItem } from '../../components/shared/ContextMenu';
 import {
   ArrowRight,
@@ -24,13 +25,15 @@ import {
   Pin,
   PinOff,
   Circle,
-  Grid3x3,
   Eye,
   EyeOff,
   Navigation,
   Target,
   Flag,
   FlagOff,
+  GitBranch,
+  Route,
+  FileSpreadsheet,
 } from 'lucide-react';
 
 export interface NodeContextMenuParams {
@@ -45,8 +48,11 @@ export interface GraphContextMenuHandlers {
   handleRemoveFromGraph: (nodeId: string) => void;
   setOriginNode: (nodeId: string | null) => void;
   setDestinationNode: (nodeId: string | null) => void;
-  travelToOrigin?: () => void;  // Optional navigation to origin node
-  travelToDestination?: () => void;  // Optional navigation to destination node
+  travelToOrigin?: () => void;
+  travelToDestination?: () => void;
+
+  // Path travel — explorer-provided camera animation through ordered node list
+  travelAlongPath?: (nodeIds: string[], reverse?: boolean) => void;
 
   // Focus handlers
   setFocusedNode: (nodeId: string | null) => void;
@@ -56,8 +62,8 @@ export interface GraphContextMenuHandlers {
   isPinned: (nodeId: string) => boolean;
   togglePinNode: (nodeId: string) => void;
   unpinAllNodes: () => void;
-  applyOriginMarker?: (nodeId: string) => void;  // Optional visual marker (e.g., gold ring)
-  applyDestinationMarker?: (nodeId: string) => void;  // Optional visual marker (e.g., blue flag)
+  applyOriginMarker?: (nodeId: string) => void;
+  applyDestinationMarker?: (nodeId: string) => void;
 }
 
 export interface GraphContextMenuCallbacks {
@@ -70,6 +76,7 @@ export interface GraphContextMenuCallbacks {
  */
 export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
   const { setGraphData, setRawGraphData, mergeRawGraphData, setFocusedNodeId } = useGraphStore();
+  const navigate = useNavigate();
 
   /** Follow concept — replace graph with this node's neighborhood and record the step */
   const handleFollowConcept = useCallback(async (nodeId: string) => {
@@ -155,7 +162,194 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
     });
   }, []);
 
-  return { handleFollowConcept, handleAddToGraph, handleRemoveFromGraph };
+  /** Find path between origin/destination, merge into graph, then animate camera */
+  const handleTravelPath = useCallback(async (
+    originId: string,
+    destinationId: string,
+    travelAlongPath: (nodeIds: string[], reverse?: boolean) => void,
+    reverse: boolean
+  ) => {
+    try {
+      const store = useGraphStore.getState();
+      const rawNodes = store.rawGraphData?.nodes || [];
+      const originLabel = rawNodes.find(
+        (n: any) => (n.concept_id || n.id) === originId
+      )?.label || originId;
+      const destLabel = rawNodes.find(
+        (n: any) => (n.concept_id || n.id) === destinationId
+      )?.label || destinationId;
+
+      const result = await apiClient.findConnection({
+        from_id: originId,
+        to_id: destinationId,
+        max_hops: 5,
+      });
+
+      if (!result.paths?.length) {
+        console.warn('No path found between origin and destination');
+        return;
+      }
+
+      const path = result.paths[0];
+
+      // Extract concept nodes (skip empty relationship placeholders)
+      const conceptNodes: any[] = [];
+      const conceptRelTypes: string[][] = [];
+      let pendingRels: string[] = [];
+
+      for (let i = 0; i < path.nodes.length; i++) {
+        const node = path.nodes[i];
+        if (node.id && node.id !== '') {
+          conceptNodes.push(node);
+          conceptRelTypes.push(pendingRels);
+          pendingRels = [];
+        }
+        if (i < path.relationships.length) {
+          pendingRels.push(path.relationships[i]);
+        }
+      }
+
+      const nodes = conceptNodes.map((node: any) => ({
+        concept_id: node.id,
+        label: node.label,
+        description: node.description,
+        ontology: 'default',
+        grounding_strength: node.grounding_strength,
+      }));
+
+      const links: any[] = [];
+      for (let i = 0; i < conceptNodes.length - 1; i++) {
+        const rels = conceptRelTypes[i + 1];
+        const relType = rels.find(r => r !== 'APPEARS' && r !== 'SCOPED_BY') || rels[0] || 'CONNECTED';
+        links.push({
+          from_id: conceptNodes[i].id,
+          to_id: conceptNodes[i + 1].id,
+          relationship_type: relType,
+        });
+      }
+
+      // Record exploration step
+      store.addExplorationStep({
+        action: 'load-path',
+        op: '+',
+        cypher: stepToCypher({
+          action: 'load-path',
+          conceptLabel: originLabel,
+          depth: 1,
+          destinationConceptLabel: destLabel,
+          maxHops: 5,
+        }),
+        conceptId: originId,
+        conceptLabel: originLabel,
+        depth: 1,
+        destinationConceptId: destinationId,
+        destinationConceptLabel: destLabel,
+        maxHops: 5,
+      });
+
+      // Merge path into graph
+      mergeRawGraphData({ nodes, links });
+
+      // Wait for graph to re-render with new nodes, then animate
+      requestAnimationFrame(() => {
+        requestAnimationFrame(() => {
+          const nodeIds = conceptNodes.map((n: any) => n.id);
+          travelAlongPath(nodeIds, reverse);
+        });
+      });
+    } catch (error: any) {
+      console.error('Failed to travel path:', error);
+    }
+  }, [mergeRawGraphData]);
+
+  /** Set polarity poles from origin/destination and navigate to polarity explorer */
+  const handleSendToPolarity = useCallback((originId: string, destinationId: string) => {
+    const store = useGraphStore.getState();
+    const rawNodes = store.rawGraphData?.nodes || [];
+
+    const originNode = rawNodes.find((n: any) => (n.concept_id || n.id) === originId);
+    const destNode = rawNodes.find((n: any) => (n.concept_id || n.id) === destinationId);
+
+    if (!originNode || !destNode) return;
+
+    store.setPolarityState({
+      selectedPositivePole: {
+        concept_id: originId,
+        label: originNode.label,
+      },
+      selectedNegativePole: {
+        concept_id: destinationId,
+        label: destNode.label,
+      },
+    });
+
+    navigate('/polarity');
+  }, [navigate]);
+
+  /** Find path between origin/destination and create a traversal report */
+  const handleSendPathToReports = useCallback(async (originId: string, destinationId: string) => {
+    try {
+      const store = useGraphStore.getState();
+      const rawNodes = store.rawGraphData?.nodes || [];
+
+      const originNode = rawNodes.find((n: any) => (n.concept_id || n.id) === originId);
+      const destNode = rawNodes.find((n: any) => (n.concept_id || n.id) === destinationId);
+
+      if (!originNode || !destNode) return;
+
+      const result = await apiClient.findConnection({
+        from_id: originId,
+        to_id: destinationId,
+        max_hops: 5,
+      });
+
+      const reportData: TraversalReportData = {
+        type: 'traversal',
+        origin: { concept_id: originId, label: originNode.label },
+        destination: { concept_id: destinationId, label: destNode.label },
+        maxHops: 5,
+        pathCount: result.count || result.paths?.length || 0,
+        paths: (result.paths || []).map((p: any) => {
+          const nodes = (p.nodes || [])
+            .filter((n: any) => n.id && n.id !== '')
+            .map((n: any) => ({
+              id: n.id,
+              label: n.label,
+              description: n.description,
+              grounding_strength: n.grounding_strength,
+              confidence_level: n.confidence_level,
+              diversity_score: n.diversity_score,
+            }));
+          return {
+            hops: p.hops || nodes.length - 1,
+            nodes,
+            relationships: p.relationships || [],
+          };
+        }),
+      };
+
+      const { addReport } = useReportStore.getState();
+      await addReport({
+        type: 'traversal',
+        data: reportData,
+        name: '',
+        sourceExplorer: 'traversal',
+      });
+
+      navigate('/report');
+    } catch (error: any) {
+      console.error('Failed to create traversal report:', error);
+    }
+  }, [navigate]);
+
+  return {
+    handleFollowConcept,
+    handleAddToGraph,
+    handleRemoveFromGraph,
+    handleTravelPath,
+    handleSendToPolarity,
+    handleSendPathToReports,
+  };
 }
 
 /**
@@ -167,7 +361,17 @@ export function buildContextMenuItems(
   handlers: GraphContextMenuHandlers,
   callbacks: GraphContextMenuCallbacks,
   originNodeId: string | null,
-  destinationNodeId: string | null
+  destinationNodeId: string | null,
+  extraHandlers?: {
+    handleTravelPath?: (
+      originId: string,
+      destinationId: string,
+      travelAlongPath: (nodeIds: string[], reverse?: boolean) => void,
+      reverse: boolean
+    ) => Promise<void>;
+    handleSendToPolarity?: (originId: string, destinationId: string) => void;
+    handleSendPathToReports?: (originId: string, destinationId: string) => Promise<void>;
+  }
 ): ContextMenuItem[] {
   const {
     isPinned,
@@ -182,6 +386,7 @@ export function buildContextMenuItems(
     setDestinationNode,
     travelToOrigin,
     travelToDestination,
+    travelAlongPath,
     setFocusedNode,
     focusedNodeId,
   } = handlers;
@@ -193,11 +398,9 @@ export function buildContextMenuItems(
   const originSubmenu: ContextMenuItem[] = [];
 
   if (nodeContext) {
-    // Right-clicked on a node
     const { nodeId } = nodeContext;
 
     if (originNodeId === nodeId) {
-      // This node IS the origin - show Clear
       originSubmenu.push({
         label: 'Clear Origin',
         icon: MapPinOff,
@@ -207,7 +410,6 @@ export function buildContextMenuItems(
         },
       });
     } else {
-      // This node is NOT the origin - show Set
       originSubmenu.push({
         label: 'Set Origin',
         icon: MapPin,
@@ -220,10 +422,9 @@ export function buildContextMenuItems(
         },
       });
 
-      // Travel to origin if origin exists
       if (originNodeId && travelToOrigin) {
         originSubmenu.push({
-          label: 'Travel to Origin',
+          label: 'Go to Origin',
           icon: Navigation,
           onClick: () => {
             travelToOrigin();
@@ -233,9 +434,7 @@ export function buildContextMenuItems(
       }
     }
   } else {
-    // Right-clicked on background
     if (originNodeId) {
-      // Origin is set - show Clear and Travel
       originSubmenu.push({
         label: 'Clear Origin',
         icon: MapPinOff,
@@ -247,7 +446,7 @@ export function buildContextMenuItems(
 
       if (travelToOrigin) {
         originSubmenu.push({
-          label: 'Travel to Origin',
+          label: 'Go to Origin',
           icon: Navigation,
           onClick: () => {
             travelToOrigin();
@@ -262,11 +461,9 @@ export function buildContextMenuItems(
   const destinationSubmenu: ContextMenuItem[] = [];
 
   if (nodeContext) {
-    // Right-clicked on a node
     const { nodeId } = nodeContext;
 
     if (destinationNodeId === nodeId) {
-      // This node IS the destination - show Clear
       destinationSubmenu.push({
         label: 'Clear Destination',
         icon: FlagOff,
@@ -276,7 +473,6 @@ export function buildContextMenuItems(
         },
       });
     } else {
-      // This node is NOT the destination - show Set
       destinationSubmenu.push({
         label: 'Set Destination',
         icon: Flag,
@@ -289,10 +485,9 @@ export function buildContextMenuItems(
         },
       });
 
-      // Travel to destination if destination exists
       if (destinationNodeId && travelToDestination) {
         destinationSubmenu.push({
-          label: 'Travel to Destination',
+          label: 'Go to Destination',
           icon: Navigation,
           onClick: () => {
             travelToDestination();
@@ -302,9 +497,7 @@ export function buildContextMenuItems(
       }
     }
   } else {
-    // Right-clicked on background
     if (destinationNodeId) {
-      // Destination is set - show Clear and Travel
       destinationSubmenu.push({
         label: 'Clear Destination',
         icon: FlagOff,
@@ -316,7 +509,7 @@ export function buildContextMenuItems(
 
       if (travelToDestination) {
         destinationSubmenu.push({
-          label: 'Travel to Destination',
+          label: 'Go to Destination',
           icon: Navigation,
           onClick: () => {
             travelToDestination();
@@ -345,6 +538,59 @@ export function buildContextMenuItems(
     });
   }
 
+  // Travel submenu — find path between origin and destination, animate camera through nodes
+  if (originNodeId && destinationNodeId && travelAlongPath && extraHandlers?.handleTravelPath) {
+    const { handleTravelPath } = extraHandlers;
+    items.push({
+      label: 'Travel',
+      icon: Route,
+      submenu: [
+        {
+          label: 'From Origin',
+          icon: MapPin,
+          onClick: () => {
+            onClose();
+            handleTravelPath(originNodeId, destinationNodeId, travelAlongPath, false);
+          },
+        },
+        {
+          label: 'From Destination',
+          icon: Flag,
+          onClick: () => {
+            onClose();
+            handleTravelPath(originNodeId, destinationNodeId, travelAlongPath, true);
+          },
+        },
+      ],
+    });
+  }
+
+  // Send to Polarity Explorer — use origin/destination as poles
+  if (originNodeId && destinationNodeId && extraHandlers?.handleSendToPolarity) {
+    const { handleSendToPolarity } = extraHandlers;
+    items.push({
+      label: 'Send to Polarity Explorer',
+      icon: GitBranch,
+      onClick: () => {
+        onClose();
+        handleSendToPolarity(originNodeId, destinationNodeId);
+      },
+    });
+  }
+
+  // Send Path to Reports — create traversal report from origin/destination
+  if (originNodeId && destinationNodeId && extraHandlers?.handleSendPathToReports) {
+    const { handleSendPathToReports } = extraHandlers;
+    items.push({
+      label: 'Send Path to Reports',
+      icon: FileSpreadsheet,
+      onClick: () => {
+        onClose();
+        handleSendPathToReports(originNodeId, destinationNodeId);
+      },
+    });
+  }
+
   // Node-specific actions (only when right-clicking on a node)
   if (nodeContext) {
     const { nodeId, nodeLabel } = nodeContext;
@@ -354,7 +600,6 @@ export function buildContextMenuItems(
       label: 'Node',
       icon: Circle,
       submenu: [
-        // Contextual pin/unpin node
         isPinned(nodeId)
           ? {
               label: 'Unpin Node',
diff --git a/web/src/store/reportStore.ts b/web/src/store/reportStore.ts
index da0c9b3c..9d233c30 100644
--- a/web/src/store/reportStore.ts
+++ b/web/src/store/reportStore.ts
@@ -12,7 +12,7 @@ import { apiClient } from '../api/client';
 import type { Representation } from '../types/artifacts';
 
 // Report types
-export type ReportType = 'graph' | 'polarity' | 'document';
+export type ReportType = 'graph' | 'polarity' | 'document' | 'traversal';
 
 // Graph report data (from 2D/3D explorers)
 export interface GraphReportData {
@@ -83,7 +83,28 @@ export interface DocumentReportData {
   };
 }
 
-export type ReportData = GraphReportData | PolarityReportData | DocumentReportData;
+// Traversal report data (path between origin and destination)
+export interface TraversalReportData {
+  type: 'traversal';
+  origin: { concept_id: string; label: string };
+  destination: { concept_id: string; label: string };
+  maxHops: number;
+  pathCount: number;
+  paths: Array<{
+    hops: number;
+    nodes: Array<{
+      id: string;
+      label: string;
+      description?: string;
+      grounding_strength?: number;
+      confidence_level?: string;
+      diversity_score?: number;
+    }>;
+    relationships: string[];
+  }>;
+}
+
+export type ReportData = GraphReportData | PolarityReportData | DocumentReportData | TraversalReportData;
 
 // Previous values for delta comparison (keyed by concept_id)
 export interface PreviousValues {
@@ -101,7 +122,7 @@ export interface Report {
   type: ReportType;
   data: ReportData;
   createdAt: string;
-  sourceExplorer: '2d' | '3d' | 'polarity' | 'document';
+  sourceExplorer: '2d' | '3d' | 'polarity' | 'document' | 'traversal';
   // Recalculation tracking
   lastCalculatedAt?: string;
   previousValues?: PreviousValues;
@@ -170,6 +191,9 @@ const generateDefaultName = (type: ReportType, data: ReportData): string => {
   } else if (type === 'polarity') {
     const polarityData = data as PolarityReportData;
     return `${polarityData.positivePole.label} ↔ ${polarityData.negativePole.label} - ${timestamp}`;
+  } else if (type === 'traversal') {
+    const travData = data as TraversalReportData;
+    return `${travData.origin.label} → ${travData.destination.label} - ${timestamp}`;
   } else {
     const docData = data as DocumentReportData;
     const docCount = docData.documents.length;
@@ -184,6 +208,11 @@ const getConceptIds = (data: ReportData): string[] => {
     return (data as GraphReportData).nodes.map(n => n.id);
   } else if (data.type === 'polarity') {
     return (data as PolarityReportData).concepts.map(c => c.concept_id);
+  } else if (data.type === 'traversal') {
+    const travData = data as TraversalReportData;
+    const ids = new Set<string>();
+    travData.paths.forEach(p => p.nodes.forEach(n => ids.add(n.id)));
+    return Array.from(ids);
   } else {
     // Document reports don't have concept IDs at the report level
     return [];
@@ -191,7 +220,7 @@ const getConceptIds = (data: ReportData): string[] => {
 };
 
 // Map source explorer to representation
-const getRepresentation = (source: '2d' | '3d' | 'polarity' | 'document'): Representation => {
+const getRepresentation = (source: '2d' | '3d' | 'polarity' | 'document' | 'traversal'): Representation => {
   switch (source) {
     case '2d': return 'force_graph_2d';
     case '3d': return 'force_graph_3d';
@@ -375,7 +404,7 @@ export const useReportStore = create<ReportStore>()(
                 type: (params.reportType as ReportType) || (data.type as ReportType) || 'graph',
                 data,
                 createdAt: artifact.created_at,
-                sourceExplorer: (params.sourceExplorer as '2d' | '3d' | 'polarity') || '2d',
+                sourceExplorer: (params.sourceExplorer as Report['sourceExplorer']) || '2d',
                 artifactId: artifact.id,
                 isSynced: true,
                 isFresh: artifact.is_fresh,

From 860d571c15600b85fdf470b22de7089d08b8db0b Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Tue, 3 Feb 2026 11:02:45 -0600
Subject: [PATCH 21/23] =?UTF-8?q?feat:=20unified=20query=20program=20?=
 =?UTF-8?q?=E2=80=94=20Cypher=20editor=20round-trips=20with=20smart=20sear?=
 =?UTF-8?q?ch?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All three query modes now compile to the same IR: { op, cypher }[].
Smart search generates it from UI actions, Cypher editor lets users
write +/- prefixed statements directly, and saved queries store it.

Fixes in the Cypher editor:
- Routes through rawGraphData pipeline (was bypassing with setGraphData)
- Correct AGE internal ID → concept_id mapping via shared mapper
- Multi-statement execution with +/- set algebra operators
- Records exploration steps so Save/Export work after execution

New capabilities:
- Export to Editor button pushes exploration session as Cypher text
- Loading saved queries reconstructs the exploration session
- Clear Graph eraser icon in the icon rail (clears graph + search state)
- Navigating to explorer without URL params no longer replays stale queries
---
 web/src/components/shared/IconRailPanel.tsx | 26 ++++++
 web/src/components/shared/SearchBar.tsx     | 91 ++++++++++++++------
 web/src/store/graphStore.ts                 | 33 +++++--
 web/src/utils/cypherGenerator.ts            | 40 ++++++---
 web/src/utils/cypherResultMapper.ts         | 89 +++++++++++++++++++
 web/src/views/ExplorerView.tsx              | 95 +++++++++++++--------
 6 files changed, 295 insertions(+), 79 deletions(-)
 create mode 100644 web/src/utils/cypherResultMapper.ts

diff --git a/web/src/components/shared/IconRailPanel.tsx b/web/src/components/shared/IconRailPanel.tsx
index 187c7439..1e18cf76 100644
--- a/web/src/components/shared/IconRailPanel.tsx
+++ b/web/src/components/shared/IconRailPanel.tsx
@@ -15,6 +15,13 @@ interface PanelTab {
   content: React.ReactNode;
 }
 
+interface RailAction {
+  id: string;
+  icon: React.ComponentType<{ className?: string }>;
+  label: string;
+  onClick: () => void;
+}
+
 interface IconRailPanelProps {
   tabs: PanelTab[];
   activeTab: string;
@@ -22,6 +29,8 @@ interface IconRailPanelProps {
   defaultExpanded?: boolean;
   expandedWidth?: string;
   position?: 'left' | 'right';
+  /** Standalone action buttons rendered above tabs in the icon rail */
+  actions?: RailAction[];
 }
 
 export const IconRailPanel: React.FC<IconRailPanelProps> = ({
@@ -31,6 +40,7 @@ export const IconRailPanel: React.FC<IconRailPanelProps> = ({
   defaultExpanded = false,
   expandedWidth = 'w-72',
   position = 'left',
+  actions = [],
 }) => {
   const [isExpanded, setIsExpanded] = useState(defaultExpanded);
 
@@ -52,6 +62,22 @@ export const IconRailPanel: React.FC<IconRailPanelProps> = ({
     <div className={`${borderClass} border-border bg-card flex h-full`}>
       {/* Icon Rail - always visible */}
       <div className="w-12 flex flex-col border-r border-border">
+        {actions.map((action) => {
+          const Icon = action.icon;
+          return (
+            <button
+              key={action.id}
+              onClick={action.onClick}
+              className="p-3 transition-colors text-muted-foreground hover:text-foreground hover:bg-accent border-l-2 border-transparent"
+              title={action.label}
+            >
+              <Icon className="w-5 h-5" />
+            </button>
+          );
+        })}
+        {actions.length > 0 && (
+          <div className="mx-2 border-b border-border" />
+        )}
         {tabs.map((tab) => {
           const Icon = tab.icon;
           const isActive = activeTab === tab.id && isExpanded;
diff --git a/web/src/components/shared/SearchBar.tsx b/web/src/components/shared/SearchBar.tsx
index 96e5c635..88caeda9 100644
--- a/web/src/components/shared/SearchBar.tsx
+++ b/web/src/components/shared/SearchBar.tsx
@@ -22,7 +22,8 @@ import { useGraphStore } from '../../store/graphStore';
 import { ModeDial } from './ModeDial';
 import { apiClient } from '../../api/client';
 import { BlockBuilder } from '../blocks/BlockBuilder';
-import { stepToCypher } from '../../utils/cypherGenerator';
+import { stepToCypher, parseCypherStatements } from '../../utils/cypherGenerator';
+import { mapCypherResultToRawGraph } from '../../utils/cypherResultMapper';
 import {
   ConceptSearchInput,
   SliderControl,
@@ -32,7 +33,7 @@ import {
 
 export const SearchBar: React.FC = () => {
   // Top-level mode (dial)
-  const { queryMode, setQueryMode, blockBuilderExpanded, setBlockBuilderExpanded } = useGraphStore();
+  const { queryMode, setQueryMode, blockBuilderExpanded, setBlockBuilderExpanded, cypherEditorContent, setCypherEditorContent } = useGraphStore();
 
   // Collapsible state
   const [smartSearchExpanded, setSmartSearchExpanded] = useState(true);
@@ -115,6 +116,16 @@ LIMIT 50`);
     }
   }, [searchParams.primaryConceptId, searchParams.primaryConceptLabel]);
 
+  // Consume exported Cypher from ExplorerView "Export to Editor" action
+  useEffect(() => {
+    if (cypherEditorContent !== null) {
+      setCypherQuery(cypherEditorContent);
+      setCypherEditorContent(null);
+      setQueryMode('cypher-editor');
+      setCypherEditorExpanded(true);
+    }
+  }, [cypherEditorContent, setCypherEditorContent, setQueryMode]);
+
   // === HANDLERS ===
 
   const handleSelectPrimary = (concept: any) => {
@@ -287,7 +298,10 @@ LIMIT 50`);
     setSelectedPath(null);
   };
 
-  // Cypher execution
+  // Execute Cypher program — parses +/- prefixed multi-statement scripts,
+  // routes results through the rawGraphData pipeline (not setGraphData directly),
+  // and records each statement as an exploration step for save/export round-trip.
+  // Plain Cypher without operators is treated as a single additive statement.
   const handleExecuteCypher = async () => {
     if (!cypherQuery.trim()) return;
 
@@ -295,25 +309,47 @@ LIMIT 50`);
     setCypherError(null);
 
     try {
-      const result = await apiClient.executeCypherQuery({
-        query: cypherQuery,
-        limit: 100,
-      });
+      let statements = parseCypherStatements(cypherQuery);
+
+      // Plain Cypher without +/- operators → treat as single additive statement
+      if (statements.length === 0) {
+        const cypher = cypherQuery.trim().replace(/;\s*$/, '');
+        if (cypher) {
+          statements = [{ op: '+', cypher }];
+        }
+      }
+
+      if (statements.length === 0) return;
+
+      const store = useGraphStore.getState();
 
-      const { transformForD3 } = await import('../../utils/graphTransform');
-      const graphNodes = result.nodes.map((n: any) => ({
-        concept_id: n.id,
-        label: n.label,
-        ontology: n.properties?.ontology || 'default',
-      }));
-      const graphLinks = result.relationships.map((r: any) => ({
-        from_id: r.from_id,
-        to_id: r.to_id,
-        relationship_type: r.type,
-      }));
-
-      const graphData = transformForD3(graphNodes, graphLinks);
-      useGraphStore.getState().setGraphData(graphData);
+      // Start fresh — clear graph and reset exploration session
+      setGraphData(null);
+      setRawGraphData(null);
+      store.resetExplorationSession();
+
+      for (const stmt of statements) {
+        const result = await apiClient.executeCypherQuery({
+          query: stmt.cypher,
+          limit: 500,
+        });
+
+        const mapped = mapCypherResultToRawGraph(result);
+
+        // Record exploration step
+        store.addExplorationStep({
+          action: 'cypher',
+          op: stmt.op,
+          cypher: stmt.cypher,
+        });
+
+        // Apply through rawGraphData pipeline
+        if (stmt.op === '+') {
+          mergeRawGraphData(mapped);
+        } else {
+          store.subtractRawGraphData(mapped);
+        }
+      }
     } catch (error: any) {
       console.error('Failed to execute Cypher query:', error);
       setCypherError(error.response?.data?.detail || error.message || 'Query execution failed');
@@ -662,13 +698,16 @@ LIMIT 50`);
               </button>
 
               <div className="text-xs text-muted-foreground space-y-1">
-                <div className="font-medium">Example queries:</div>
-                <div className="font-mono bg-muted p-2 rounded">
-                  <div>MATCH (c:Concept) WHERE c.label CONTAINS 'organizational' RETURN c LIMIT 10</div>
-                  <div className="mt-1">{'MATCH (c:Concept)-[r:IMPLIES]->(n:Concept) RETURN c, r, n LIMIT 50'}</div>
+                <div className="font-medium">Syntax:</div>
+                <div className="font-mono bg-muted p-2 rounded space-y-1">
+                  <div className="text-muted-foreground/70">{'-- Single query (plain Cypher):'}</div>
+                  <div>{'MATCH (c:Concept)-[r]->(n) RETURN c, r, n LIMIT 50'}</div>
+                  <div className="text-muted-foreground/70 mt-2">{'-- Multi-statement with set operators:'}</div>
+                  <div>{'+ MATCH (c:Concept)-[r]-(n) WHERE c.label = \'X\' RETURN c, r, n;'}</div>
+                  <div>{'- MATCH (c:Concept) WHERE c.label = \'Noise\' RETURN c;'}</div>
                 </div>
                 <div className="text-muted-foreground/70 mt-2">
-                  Results are automatically loaded into the graph visualization.
+                  Prefix lines with <code className="bg-muted px-1 rounded">+</code> (add) or <code className="bg-muted px-1 rounded">-</code> (subtract) for set algebra. Statements execute in order.
                 </div>
               </div>
             </div>
diff --git a/web/src/store/graphStore.ts b/web/src/store/graphStore.ts
index b353a1be..42f08cf3 100644
--- a/web/src/store/graphStore.ts
+++ b/web/src/store/graphStore.ts
@@ -68,9 +68,18 @@ export function deriveMode(params: SearchParams): DerivedMode {
 }
 
 // --- Exploration Session Types ---
+//
+// All query modes (smart search, block editor, Cypher editor) compile to the
+// same intermediate representation: an ordered array of { op, cypher } pairs.
+// This is the "query program" — saved, loaded, and replayed uniformly.
+//
+// Smart search generates steps automatically from UI actions.
+// Block editor compiles visual blocks into steps.
+// Cypher editor lets the user write +/- prefixed statements directly.
+// generateCypher() serializes a session to text; parseCypherStatements() parses it back.
 
 /** The type of graph action performed */
-export type ExplorationAction = 'explore' | 'follow' | 'add-adjacent' | 'load-path';
+export type ExplorationAction = 'explore' | 'follow' | 'add-adjacent' | 'load-path' | 'cypher';
 
 /** Set algebra operator: additive (+) merges results, subtractive (-) removes them */
 export type ExplorationOp = '+' | '-';
@@ -94,12 +103,12 @@ export interface ExplorationStep {
   /** The equivalent Cypher statement for this action */
   cypher: string;
 
-  /** Primary concept ID */
-  conceptId: string;
-  /** Human-readable concept label */
-  conceptLabel: string;
+  /** Primary concept ID (not applicable for raw cypher steps) */
+  conceptId?: string;
+  /** Human-readable concept label (or Cypher snippet for raw cypher steps) */
+  conceptLabel?: string;
   /** Neighborhood traversal depth */
-  depth: number;
+  depth?: number;
 
   /** Destination concept ID (path mode only) */
   destinationConceptId?: string;
@@ -237,8 +246,14 @@ interface GraphStore {
   undoLastStep: () => void;
   /** Clear the session and graph data, starting fresh */
   clearExploration: () => void;
+  /** Reset session only (keeps graph data intact) — used when loading saved queries */
+  resetExplorationSession: () => void;
   /** Set a name for the current exploration (for saving) */
   setExplorationName: (name: string) => void;
+
+  /** Bridge for pushing generated Cypher scripts to the editor (consumed by SearchBar) */
+  cypherEditorContent: string | null;
+  setCypherEditorContent: (content: string | null) => void;
 }
 
 const defaultFilters: GraphFilters = {
@@ -553,6 +568,12 @@ export const useGraphStore = create<GraphStore>()(
       graphData: null,
     }),
 
+  resetExplorationSession: () =>
+    set({ explorationSession: createEmptySession() }),
+
+  cypherEditorContent: null,
+  setCypherEditorContent: (content) => set({ cypherEditorContent: content }),
+
   setExplorationName: (name) =>
     set((state) => ({
       explorationSession: {
diff --git a/web/src/utils/cypherGenerator.ts b/web/src/utils/cypherGenerator.ts
index d235dd32..1eb64576 100644
--- a/web/src/utils/cypherGenerator.ts
+++ b/web/src/utils/cypherGenerator.ts
@@ -1,23 +1,30 @@
 /**
- * Cypher Generator — converts exploration sessions to ordered Cypher statements.
+ * Cypher Generator — serializer/deserializer for the unified query program.
  *
- * Each exploration step maps to an equivalent Apache AGE openCypher statement.
- * Steps are prefixed with +/- operators indicating whether the result should
- * be merged into or subtracted from the graph.
+ * All three query modes (smart search, block editor, Cypher editor) compile
+ * to the same intermediate representation: { op: '+' | '-', cypher: string }[].
+ * This module converts between that IR and the human-readable text format.
  *
- * The generated output is human-readable, editable, and executable in the
- * openCypher editor. It preserves the user's exploration narrative — each
- * statement is a discrete thought in the sequence.
+ * Text format:
+ *   - Each statement is prefixed with + (add to graph) or - (subtract from graph)
+ *   - Statements execute in order, applying set algebra to the graph
+ *   - Comments (--) and blank lines are ignored during parsing
+ *   - Unprefixed statements default to + (additive)
+ *
+ * Functions:
+ *   - stepToCypher()            — single semantic action → Cypher statement
+ *   - generateCypher(session)   — exploration session → text script (serializer)
+ *   - parseCypherStatements(text) — text script → { op, cypher }[] (deserializer)
  *
  * @example
  * ```
  * -- Exploration: My Graph Query
  * -- Step 1: explore "Way"
- * + MATCH (c:Concept)-[r]-(n:Concept) WHERE c.label = 'Way' RETURN c, r, n
+ * + MATCH (c:Concept)-[r]-(n:Concept) WHERE c.label = 'Way' RETURN c, r, n;
  * -- Step 2: add-adjacent "Enterprise Operating Model"
- * + MATCH (c:Concept)-[r]-(n:Concept) WHERE c.label = 'Enterprise Operating Model' RETURN c, r, n
+ * + MATCH (c:Concept)-[r]-(n:Concept) WHERE c.label = 'Enterprise Operating Model' RETURN c, r, n;
  * -- Step 3: subtract "Noise"
- * - MATCH (c:Concept)-[r]-(n:Concept) WHERE c.label = 'Noise' RETURN c, r, n
+ * - MATCH (c:Concept)-[r]-(n:Concept) WHERE c.label = 'Noise' RETURN c, r, n;
  * ```
  */
 
@@ -105,9 +112,16 @@ export function generateCypher(session: ExplorationSession): string {
 
   // Each step as an operator-prefixed statement
   steps.forEach((step, idx) => {
-    const actionLabel = step.action === 'load-path'
-      ? `${step.action} "${step.conceptLabel}" → "${step.destinationConceptLabel}"`
-      : `${step.action} "${step.conceptLabel}"`;
+    let actionLabel: string;
+    if (step.action === 'cypher') {
+      // Raw cypher steps — show truncated query as label
+      const snippet = step.cypher.replace(/\n/g, ' ').substring(0, 60);
+      actionLabel = `cypher "${snippet}${step.cypher.length > 60 ? '...' : ''}"`;
+    } else if (step.action === 'load-path') {
+      actionLabel = `${step.action} "${step.conceptLabel}" → "${step.destinationConceptLabel}"`;
+    } else {
+      actionLabel = `${step.action} "${step.conceptLabel}"`;
+    }
 
     lines.push(`-- Step ${idx + 1}: ${actionLabel}`);
     lines.push(`${step.op} ${step.cypher};`);
diff --git a/web/src/utils/cypherResultMapper.ts b/web/src/utils/cypherResultMapper.ts
new file mode 100644
index 00000000..7dc1446c
--- /dev/null
+++ b/web/src/utils/cypherResultMapper.ts
@@ -0,0 +1,89 @@
+/**
+ * Cypher Result Mapper
+ *
+ * Maps Apache AGE Cypher query results to the canonical raw graph format
+ * used by the store (rawGraphData). Handles the AGE internal ID → concept_id
+ * mapping that's required because AGE returns its own vertex IDs, not
+ * the concept_ids stored in node properties.
+ *
+ * Used by both the Cypher editor (SearchBar) and saved query replay (ExplorerView).
+ */
+
+export interface CypherResultNode {
+  id: string;
+  label: string;
+  properties?: {
+    concept_id?: string;
+    ontology?: string;
+    search_terms?: string[];
+    grounding_strength?: number;
+    [key: string]: unknown;
+  };
+}
+
+export interface CypherResultRelationship {
+  from_id: string;
+  to_id: string;
+  type: string;
+  properties?: {
+    category?: string;
+    [key: string]: unknown;
+  };
+  confidence?: number;
+}
+
+export interface CypherQueryResult {
+  nodes?: CypherResultNode[];
+  relationships?: CypherResultRelationship[];
+  row_count?: number;
+}
+
+export interface RawGraphNode {
+  concept_id: string;
+  label: string;
+  ontology: string;
+  search_terms: string[];
+  grounding_strength?: number;
+}
+
+export interface RawGraphLink {
+  from_id: string;
+  to_id: string;
+  relationship_type: string;
+  category?: string;
+  confidence?: number;
+}
+
+/**
+ * Map a Cypher query result (with AGE internal IDs) to the canonical
+ * raw graph format expected by mergeRawGraphData / subtractRawGraphData.
+ */
+export function mapCypherResultToRawGraph(result: CypherQueryResult): {
+  nodes: RawGraphNode[];
+  links: RawGraphLink[];
+} {
+  // Build AGE internal ID → concept_id map
+  const internalToConceptId = new Map<string, string>();
+  (result.nodes || []).forEach((n) => {
+    const conceptId = n.properties?.concept_id || n.id;
+    internalToConceptId.set(n.id, conceptId);
+  });
+
+  const nodes: RawGraphNode[] = (result.nodes || []).map((n) => ({
+    concept_id: n.properties?.concept_id || n.id,
+    label: n.label,
+    ontology: n.properties?.ontology || 'default',
+    search_terms: n.properties?.search_terms || [],
+    grounding_strength: n.properties?.grounding_strength,
+  }));
+
+  const links: RawGraphLink[] = (result.relationships || []).map((r) => ({
+    from_id: internalToConceptId.get(r.from_id) || r.from_id,
+    to_id: internalToConceptId.get(r.to_id) || r.to_id,
+    relationship_type: r.type,
+    category: r.properties?.category,
+    confidence: r.confidence,
+  }));
+
+  return { nodes, links };
+}
diff --git a/web/src/views/ExplorerView.tsx b/web/src/views/ExplorerView.tsx
index e6331289..58dc2fa8 100644
--- a/web/src/views/ExplorerView.tsx
+++ b/web/src/views/ExplorerView.tsx
@@ -10,7 +10,7 @@
 
 import React, { useState, useEffect, useCallback, useMemo } from 'react';
 import { useSearchParams, useNavigate } from 'react-router-dom';
-import { FolderOpen, Save, Settings, Trash2 } from 'lucide-react';
+import { FolderOpen, Save, Settings, Trash2, Eraser, Code } from 'lucide-react';
 import { SearchBar } from '../components/shared/SearchBar';
 import { IconRailPanel } from '../components/shared/IconRailPanel';
 import { useGraphStore, deriveMode } from '../store/graphStore';
@@ -26,6 +26,7 @@ import { SLIDER_RANGES as SLIDER_RANGES_3D } from '../explorers/ForceGraph3D/typ
 import { getZIndexValue } from '../config/zIndex';
 import { apiClient } from '../api/client';
 import { stepToCypher, generateCypher, parseCypherStatements } from '../utils/cypherGenerator';
+import { mapCypherResultToRawGraph } from '../utils/cypherResultMapper';
 import type { VisualizationType } from '../types/explorer';
 
 interface ExplorerViewProps {
@@ -45,9 +46,12 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     mergeRawGraphData,
     setSelectedExplorer,
     setSearchParams,
+    clearSearchParams,
     setSimilarityThreshold,
     explorationSession,
     subtractRawGraphData,
+    clearExploration,
+    resetExplorationSession,
   } = useGraphStore();
   const { addReport } = useReportStore();
   const {
@@ -122,8 +126,13 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
       if (similarity) {
         setSimilarityThreshold(parseFloat(similarity));
       }
+    } else {
+      // No URL params — clear any persisted searchParams so stale queries
+      // don't re-fire. The graph data stays visible until the next search.
+      hasInitializedFromUrl.current = true;
+      clearSearchParams();
     }
-  }, [urlParams, setSearchParams, setSimilarityThreshold]);
+  }, [urlParams, setSearchParams, setSimilarityThreshold, clearSearchParams]);
 
   // Sync store state → URL parameters
   useEffect(() => {
@@ -352,6 +361,13 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     });
   }, [explorationSession, createSavedQuery, explorerType]);
 
+  // Export current exploration to Cypher editor
+  const handleExportToEditor = useCallback(() => {
+    if (!explorationSession || explorationSession.steps.length === 0) return;
+    const script = generateCypher(explorationSession);
+    useGraphStore.getState().setCypherEditorContent(script);
+  }, [explorationSession]);
+
   // Load a saved query
   const handleLoadQuery = useCallback(async (query: any) => {
     const definition = query.definition;
@@ -360,38 +376,25 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     if (query.definition_type === 'exploration' && definition?.statements) {
       setGraphData(null);
       setRawGraphData(null);
+      resetExplorationSession();
 
       for (const stmt of definition.statements as Array<{ op: '+' | '-'; cypher: string }>) {
         try {
           const result = await apiClient.executeCypherQuery({ query: stmt.cypher, limit: 500 });
-
-          // Build AGE internal ID → concept_id map
-          const internalToConceptId = new Map<string, string>();
-          (result.nodes || []).forEach((n: any) => {
-            const conceptId = n.properties?.concept_id || n.id;
-            internalToConceptId.set(n.id, conceptId);
-          });
-
-          const nodes = (result.nodes || []).map((n: any) => ({
-            concept_id: n.properties?.concept_id || n.id,
-            label: n.label,
-            ontology: n.properties?.ontology || 'default',
-            search_terms: n.properties?.search_terms || [],
-            grounding_strength: n.properties?.grounding_strength,
-          }));
-          const links = (result.relationships || []).map((r: any) => ({
-            from_id: internalToConceptId.get(r.from_id) || r.from_id,
-            to_id: internalToConceptId.get(r.to_id) || r.to_id,
-            relationship_type: r.type,
-            category: r.properties?.category,
-            confidence: r.confidence,
-          }));
+          const mapped = mapCypherResultToRawGraph(result);
 
           if (stmt.op === '+') {
-            mergeRawGraphData({ nodes, links });
+            mergeRawGraphData(mapped);
           } else {
-            subtractRawGraphData({ nodes, links });
+            subtractRawGraphData(mapped);
           }
+
+          // Reconstruct exploration session so Save/Export work after load
+          useGraphStore.getState().addExplorationStep({
+            action: 'cypher',
+            op: stmt.op,
+            cypher: stmt.cypher,
+          });
         } catch (error) {
           console.error('Failed to replay statement:', stmt.cypher, error);
         }
@@ -406,7 +409,7 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
         setSimilarityThreshold(definition.similarityThreshold);
       }
     }
-  }, [setGraphData, setRawGraphData, mergeRawGraphData, subtractRawGraphData, setSearchParams, setSimilarityThreshold]);
+  }, [setGraphData, setRawGraphData, mergeRawGraphData, subtractRawGraphData, resetExplorationSession, setSearchParams, setSimilarityThreshold]);
 
   // Delete a saved query
   const handleDeleteQuery = useCallback(async (id: number, e: React.MouseEvent) => {
@@ -420,13 +423,22 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
   const savedQueriesPanelContent = (
     <div className="p-3">
       {hasExploration && (
-        <button
-          onClick={handleSaveExploration}
-          className="w-full flex items-center gap-2 px-3 py-2 mb-3 text-sm font-medium rounded-lg border border-primary/30 bg-primary/5 hover:bg-primary/10 text-primary transition-colors"
-        >
-          <Save className="w-4 h-4" />
-          Save Current Exploration ({explorationSession.steps.length} steps)
-        </button>
+        <div className="flex gap-2 mb-3">
+          <button
+            onClick={handleSaveExploration}
+            className="flex-1 flex items-center gap-2 px-3 py-2 text-sm font-medium rounded-lg border border-primary/30 bg-primary/5 hover:bg-primary/10 text-primary transition-colors"
+          >
+            <Save className="w-4 h-4" />
+            Save ({explorationSession.steps.length} steps)
+          </button>
+          <button
+            onClick={handleExportToEditor}
+            className="flex items-center gap-1.5 px-3 py-2 text-sm font-medium rounded-lg border border-border hover:bg-accent text-muted-foreground hover:text-foreground transition-colors"
+            title="Export to Cypher Editor"
+          >
+            <Code className="w-4 h-4" />
+          </button>
+        </div>
       )}
       {isLoadingQueries ? (
         <div className="text-center text-muted-foreground text-sm py-4">
@@ -501,6 +513,13 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     </div>
   );
 
+  // Clear graph and search state
+  const handleClearGraph = useCallback(() => {
+    clearExploration();
+    clearSearchParams();
+    setUrlParams(new URLSearchParams(), { replace: true });
+  }, [clearExploration, clearSearchParams, setUrlParams]);
+
   // Tab definitions for IconRailPanel
   const tabs = [
     {
@@ -525,6 +544,14 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
         activeTab={activeTab}
         onTabChange={setActiveTab}
         defaultExpanded={false}
+        actions={[
+          {
+            id: 'clear',
+            icon: Eraser,
+            label: 'Clear Graph',
+            onClick: handleClearGraph,
+          },
+        ]}
       />
 
       {/* Main visualization area */}

From 2a020dc0df6954cad1848cf767bd731ca562e1f3 Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Tue, 3 Feb 2026 11:18:56 -0600
Subject: [PATCH 22/23] fix: address code review findings from PR #285

- Remove dead ternary that always resolved to '+' (SearchBar.tsx)
- Move addExplorationStep after API success to prevent phantom steps
  on failure (useGraphContextMenu.ts)
- Use 'cypher' action type for remove operations so exported Cypher
  comments correctly reflect subtraction (useGraphContextMenu.ts)
---
 web/src/components/shared/SearchBar.tsx       |  2 +-
 .../explorers/common/useGraphContextMenu.ts   | 24 +++++++++----------
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/web/src/components/shared/SearchBar.tsx b/web/src/components/shared/SearchBar.tsx
index 88caeda9..9e5a187e 100644
--- a/web/src/components/shared/SearchBar.tsx
+++ b/web/src/components/shared/SearchBar.tsx
@@ -159,7 +159,7 @@ LIMIT 50`);
 
     useGraphStore.getState().addExplorationStep({
       action: 'explore',
-      op: loadMode === 'add' ? '+' : '+',
+      op: '+',
       cypher: stepToCypher(stepParams),
       conceptId: selectedPrimary.concept_id,
       conceptLabel: selectedPrimary.label,
diff --git a/web/src/explorers/common/useGraphContextMenu.ts b/web/src/explorers/common/useGraphContextMenu.ts
index 5c299e62..6b0dd4ce 100644
--- a/web/src/explorers/common/useGraphContextMenu.ts
+++ b/web/src/explorers/common/useGraphContextMenu.ts
@@ -86,6 +86,11 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
         (n: any) => (n.concept_id || n.id) === nodeId
       )?.label || nodeId;
 
+      const response = await apiClient.getSubgraph({
+        center_concept_id: nodeId,
+        depth: 1,
+      });
+
       store.addExplorationStep({
         action: 'follow',
         op: '+',
@@ -95,11 +100,6 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
         depth: 1,
       });
 
-      const response = await apiClient.getSubgraph({
-        center_concept_id: nodeId,
-        depth: 1,
-      });
-
       setGraphData(null);
       setRawGraphData({ nodes: response.nodes, links: response.links });
       setFocusedNodeId(nodeId);
@@ -117,6 +117,11 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
         (n: any) => (n.concept_id || n.id) === nodeId
       )?.label || nodeId;
 
+      const response = await apiClient.getSubgraph({
+        center_concept_id: nodeId,
+        depth: 1,
+      });
+
       store.addExplorationStep({
         action: 'add-adjacent',
         op: '+',
@@ -126,11 +131,6 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
         depth: 1,
       });
 
-      const response = await apiClient.getSubgraph({
-        center_concept_id: nodeId,
-        depth: 1,
-      });
-
       mergeRawGraphData({ nodes: response.nodes, links: response.links });
       setFocusedNodeId(nodeId);
     } catch (error: any) {
@@ -148,9 +148,9 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
     const nodeLabel = node?.label || nodeId;
 
     store.addExplorationStep({
-      action: 'add-adjacent',
+      action: 'cypher',
       op: '-',
-      cypher: stepToCypher({ action: 'add-adjacent', conceptLabel: nodeLabel, depth: 1 }),
+      cypher: `MATCH (c:Concept)-[r]-(n:Concept)\nWHERE c.label = '${nodeLabel}'\nRETURN c, r, n`,
       conceptId: nodeId,
       conceptLabel: nodeLabel,
       depth: 1,

From 74a523872d979d4864ec3cae79cf7889fe947aff Mon Sep 17 00:00:00 2001
From: Aaron Bockelie <aaronsb@gmail.com>
Date: Tue, 3 Feb 2026 12:46:05 -0600
Subject: [PATCH 23/23] refactor: extract path utility, replace pervasive any
 types

- Extract duplicated AGE path extraction logic (SearchBar + context
  menu) into shared extractGraphFromPath() in cypherResultMapper.ts
- Add RawGraphData, PathResult, PathResultNode types to cypherResultMapper
- Type graphStore rawGraphData interface with RawGraphData instead of
  { nodes: any[]; links: any[] }
- Replace ~28 any annotations across store, context menu, SearchBar,
  and ExplorerView with RawGraphNode, RawGraphLink, and proper types
- Change catch (error: any) to catch (error: unknown) with narrowing
- Simplify store merge/subtract to use concept_id directly (canonical
  field) instead of defensive n.id || n.concept_id fallbacks
---
 web/src/components/shared/SearchBar.tsx       | 75 +++++-----------
 .../explorers/common/useGraphContextMenu.ts   | 81 +++++-------------
 web/src/store/graphStore.ts                   | 39 ++++-----
 web/src/utils/cypherResultMapper.ts           | 85 ++++++++++++++++++-
 web/src/views/ExplorerView.tsx                | 21 ++---
 5 files changed, 154 insertions(+), 147 deletions(-)

diff --git a/web/src/components/shared/SearchBar.tsx b/web/src/components/shared/SearchBar.tsx
index 9e5a187e..ba1eccca 100644
--- a/web/src/components/shared/SearchBar.tsx
+++ b/web/src/components/shared/SearchBar.tsx
@@ -23,7 +23,8 @@ import { ModeDial } from './ModeDial';
 import { apiClient } from '../../api/client';
 import { BlockBuilder } from '../blocks/BlockBuilder';
 import { stepToCypher, parseCypherStatements } from '../../utils/cypherGenerator';
-import { mapCypherResultToRawGraph } from '../../utils/cypherResultMapper';
+import { mapCypherResultToRawGraph, extractGraphFromPath } from '../../utils/cypherResultMapper';
+import type { PathResult } from '../../utils/cypherResultMapper';
 import {
   ConceptSearchInput,
   SliderControl,
@@ -55,18 +56,18 @@ export const SearchBar: React.FC = () => {
   // === UNIFIED SEARCH STATE ===
   // Primary concept (the starting point for any search)
   const [primaryQuery, setPrimaryQuery] = useState('');
-  const [selectedPrimary, setSelectedPrimary] = useState<any>(null);
+  const [selectedPrimary, setSelectedPrimary] = useState<{ concept_id: string; label: string } | null>(null);
   const [depth, setDepth] = useState(1);
 
   // Destination concept (optional — triggers path mode)
   const [destinationQuery, setDestinationQuery] = useState('');
-  const [selectedDestination, setSelectedDestination] = useState<any>(null);
+  const [selectedDestination, setSelectedDestination] = useState<{ concept_id: string; label: string } | null>(null);
   const [showDestination, setShowDestination] = useState(false);
   const [maxHops, setMaxHops] = useState(5);
 
   // Path search state
-  const [pathResults, setPathResults] = useState<any>(null);
-  const [selectedPath, setSelectedPath] = useState<any>(null);
+  const [pathResults, setPathResults] = useState<{ paths: PathResult[]; count: number; error?: string } | null>(null);
+  const [selectedPath, setSelectedPath] = useState<PathResult | null>(null);
   const [isLoadingPath, setIsLoadingPath] = useState(false);
 
   // Cypher editor state
@@ -128,12 +129,12 @@ LIMIT 50`);
 
   // === HANDLERS ===
 
-  const handleSelectPrimary = (concept: any) => {
+  const handleSelectPrimary = (concept: { concept_id: string; label: string }) => {
     setSelectedPrimary(concept);
     setPrimaryQuery(concept.label);
   };
 
-  const handleSelectDestination = (concept: any) => {
+  const handleSelectDestination = (concept: { concept_id: string; label: string }) => {
     setSelectedDestination(concept);
     setDestinationQuery(concept.label);
   };
@@ -190,16 +191,17 @@ LIMIT 50`);
         max_hops: maxHops,
       });
       setPathResults(result);
-    } catch (error: any) {
+    } catch (error: unknown) {
       console.error('Failed to find paths:', error);
 
+      const err = error as { code?: string; response?: { data?: { detail?: string } }; message?: string };
       let errorMessage = 'Failed to find paths';
-      if (error.code === 'ECONNABORTED') {
+      if (err.code === 'ECONNABORTED') {
         errorMessage = `Search timed out. Try reducing max hops.`;
-      } else if (error.response?.data?.detail) {
-        errorMessage = error.response.data.detail;
-      } else if (error.message) {
-        errorMessage = error.message;
+      } else if (err.response?.data?.detail) {
+        errorMessage = err.response.data.detail;
+      } else if (err.message) {
+        errorMessage = err.message;
       }
 
       setPathResults({ error: errorMessage, count: 0, paths: [] });
@@ -232,40 +234,7 @@ LIMIT 50`);
       maxHops,
     });
 
-    const conceptNodes: any[] = [];
-    const conceptRelTypes: string[][] = [];
-    let pendingRels: string[] = [];
-
-    for (let i = 0; i < selectedPath.nodes.length; i++) {
-      const node = selectedPath.nodes[i];
-      if (node.id && node.id !== '') {
-        conceptNodes.push(node);
-        conceptRelTypes.push(pendingRels);
-        pendingRels = [];
-      }
-      if (i < selectedPath.relationships.length) {
-        pendingRels.push(selectedPath.relationships[i]);
-      }
-    }
-
-    const nodes = conceptNodes.map((node: any) => ({
-      concept_id: node.id,
-      label: node.label,
-      description: node.description,
-      ontology: 'default',
-      grounding_strength: node.grounding_strength,
-    }));
-
-    const links: any[] = [];
-    for (let i = 0; i < conceptNodes.length - 1; i++) {
-      const rels = conceptRelTypes[i + 1];
-      const relType = rels.find(r => r !== 'APPEARS' && r !== 'SCOPED_BY') || rels[0] || 'CONNECTED';
-      links.push({
-        from_id: conceptNodes[i].id,
-        to_id: conceptNodes[i + 1].id,
-        relationship_type: relType,
-      });
-    }
+    const { nodes, links, conceptNodeIds } = extractGraphFromPath(selectedPath);
 
     if (loadMode === 'clean') {
       setGraphData(null);
@@ -275,13 +244,12 @@ LIMIT 50`);
     }
 
     // Enrich path nodes with neighborhood context
-    if (depth > 0 && conceptNodes.length <= 50) {
+    if (depth > 0 && conceptNodeIds.length <= 50) {
       const enrichDepth = Math.min(depth, 2);
-      const idsToEnrich = conceptNodes.map((n) => n.id).filter(Boolean);
-      if (idsToEnrich.length > 0) {
+      if (conceptNodeIds.length > 0) {
         try {
           const enrichments = await Promise.all(
-            idsToEnrich.map((id: string) =>
+            conceptNodeIds.map((id) =>
               apiClient.getSubgraph({ center_concept_id: id, depth: enrichDepth })
             )
           );
@@ -350,9 +318,10 @@ LIMIT 50`);
           store.subtractRawGraphData(mapped);
         }
       }
-    } catch (error: any) {
+    } catch (error: unknown) {
       console.error('Failed to execute Cypher query:', error);
-      setCypherError(error.response?.data?.detail || error.message || 'Query execution failed');
+      const err = error as { response?: { data?: { detail?: string } }; message?: string };
+      setCypherError(err.response?.data?.detail || err.message || 'Query execution failed');
     } finally {
       setIsExecutingCypher(false);
     }
diff --git a/web/src/explorers/common/useGraphContextMenu.ts b/web/src/explorers/common/useGraphContextMenu.ts
index 6b0dd4ce..7a6d91ce 100644
--- a/web/src/explorers/common/useGraphContextMenu.ts
+++ b/web/src/explorers/common/useGraphContextMenu.ts
@@ -13,6 +13,8 @@ import { useCallback } from 'react';
 import { useNavigate } from 'react-router-dom';
 import { apiClient } from '../../api/client';
 import { stepToCypher } from '../../utils/cypherGenerator';
+import { extractGraphFromPath } from '../../utils/cypherResultMapper';
+import type { RawGraphNode, RawGraphData, PathResult } from '../../utils/cypherResultMapper';
 import { useGraphStore } from '../../store/graphStore';
 import { useReportStore, type TraversalReportData } from '../../store/reportStore';
 import type { ContextMenuItem } from '../../components/shared/ContextMenu';
@@ -74,7 +76,7 @@ export interface GraphContextMenuCallbacks {
 /**
  * Hook providing generic graph navigation actions
  */
-export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
+export function useGraphNavigation(mergeGraphData: (newData: RawGraphData) => void) {
   const { setGraphData, setRawGraphData, mergeRawGraphData, setFocusedNodeId } = useGraphStore();
   const navigate = useNavigate();
 
@@ -83,7 +85,7 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
     try {
       const store = useGraphStore.getState();
       const nodeLabel = store.rawGraphData?.nodes?.find(
-        (n: any) => (n.concept_id || n.id) === nodeId
+        (n: RawGraphNode) => n.concept_id === nodeId
       )?.label || nodeId;
 
       const response = await apiClient.getSubgraph({
@@ -103,9 +105,9 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
       setGraphData(null);
       setRawGraphData({ nodes: response.nodes, links: response.links });
       setFocusedNodeId(nodeId);
-    } catch (error: any) {
+    } catch (error: unknown) {
       console.error('Failed to follow concept:', error);
-      alert(`Failed to follow concept: ${error.message || 'Unknown error'}`);
+      alert(`Failed to follow concept: ${error instanceof Error ? error.message : 'Unknown error'}`);
     }
   }, [setGraphData, setRawGraphData, setFocusedNodeId]);
 
@@ -114,7 +116,7 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
     try {
       const store = useGraphStore.getState();
       const nodeLabel = store.rawGraphData?.nodes?.find(
-        (n: any) => (n.concept_id || n.id) === nodeId
+        (n: RawGraphNode) => n.concept_id === nodeId
       )?.label || nodeId;
 
       const response = await apiClient.getSubgraph({
@@ -133,9 +135,9 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
 
       mergeRawGraphData({ nodes: response.nodes, links: response.links });
       setFocusedNodeId(nodeId);
-    } catch (error: any) {
+    } catch (error: unknown) {
       console.error('Failed to add adjacent nodes:', error);
-      alert(`Failed to add adjacent nodes: ${error.message || 'Unknown error'}`);
+      alert(`Failed to add adjacent nodes: ${error instanceof Error ? error.message : 'Unknown error'}`);
     }
   }, [mergeRawGraphData, setFocusedNodeId]);
 
@@ -143,7 +145,7 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
   const handleRemoveFromGraph = useCallback((nodeId: string) => {
     const store = useGraphStore.getState();
     const node = store.rawGraphData?.nodes?.find(
-      (n: any) => (n.concept_id || n.id) === nodeId
+      (n: RawGraphNode) => n.concept_id === nodeId
     );
     const nodeLabel = node?.label || nodeId;
 
@@ -173,10 +175,10 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
       const store = useGraphStore.getState();
       const rawNodes = store.rawGraphData?.nodes || [];
       const originLabel = rawNodes.find(
-        (n: any) => (n.concept_id || n.id) === originId
+        (n: RawGraphNode) => n.concept_id === originId
       )?.label || originId;
       const destLabel = rawNodes.find(
-        (n: any) => (n.concept_id || n.id) === destinationId
+        (n: RawGraphNode) => n.concept_id === destinationId
       )?.label || destinationId;
 
       const result = await apiClient.findConnection({
@@ -190,43 +192,7 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
         return;
       }
 
-      const path = result.paths[0];
-
-      // Extract concept nodes (skip empty relationship placeholders)
-      const conceptNodes: any[] = [];
-      const conceptRelTypes: string[][] = [];
-      let pendingRels: string[] = [];
-
-      for (let i = 0; i < path.nodes.length; i++) {
-        const node = path.nodes[i];
-        if (node.id && node.id !== '') {
-          conceptNodes.push(node);
-          conceptRelTypes.push(pendingRels);
-          pendingRels = [];
-        }
-        if (i < path.relationships.length) {
-          pendingRels.push(path.relationships[i]);
-        }
-      }
-
-      const nodes = conceptNodes.map((node: any) => ({
-        concept_id: node.id,
-        label: node.label,
-        description: node.description,
-        ontology: 'default',
-        grounding_strength: node.grounding_strength,
-      }));
-
-      const links: any[] = [];
-      for (let i = 0; i < conceptNodes.length - 1; i++) {
-        const rels = conceptRelTypes[i + 1];
-        const relType = rels.find(r => r !== 'APPEARS' && r !== 'SCOPED_BY') || rels[0] || 'CONNECTED';
-        links.push({
-          from_id: conceptNodes[i].id,
-          to_id: conceptNodes[i + 1].id,
-          relationship_type: relType,
-        });
-      }
+      const { nodes, links, conceptNodeIds } = extractGraphFromPath(result.paths[0]);
 
       // Record exploration step
       store.addExplorationStep({
@@ -253,11 +219,10 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
       // Wait for graph to re-render with new nodes, then animate
       requestAnimationFrame(() => {
         requestAnimationFrame(() => {
-          const nodeIds = conceptNodes.map((n: any) => n.id);
-          travelAlongPath(nodeIds, reverse);
+          travelAlongPath(conceptNodeIds, reverse);
         });
       });
-    } catch (error: any) {
+    } catch (error: unknown) {
       console.error('Failed to travel path:', error);
     }
   }, [mergeRawGraphData]);
@@ -267,8 +232,8 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
     const store = useGraphStore.getState();
     const rawNodes = store.rawGraphData?.nodes || [];
 
-    const originNode = rawNodes.find((n: any) => (n.concept_id || n.id) === originId);
-    const destNode = rawNodes.find((n: any) => (n.concept_id || n.id) === destinationId);
+    const originNode = rawNodes.find((n: RawGraphNode) => n.concept_id === originId);
+    const destNode = rawNodes.find((n: RawGraphNode) => n.concept_id === destinationId);
 
     if (!originNode || !destNode) return;
 
@@ -292,8 +257,8 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
       const store = useGraphStore.getState();
       const rawNodes = store.rawGraphData?.nodes || [];
 
-      const originNode = rawNodes.find((n: any) => (n.concept_id || n.id) === originId);
-      const destNode = rawNodes.find((n: any) => (n.concept_id || n.id) === destinationId);
+      const originNode = rawNodes.find((n: RawGraphNode) => n.concept_id === originId);
+      const destNode = rawNodes.find((n: RawGraphNode) => n.concept_id === destinationId);
 
       if (!originNode || !destNode) return;
 
@@ -309,10 +274,10 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
         destination: { concept_id: destinationId, label: destNode.label },
         maxHops: 5,
         pathCount: result.count || result.paths?.length || 0,
-        paths: (result.paths || []).map((p: any) => {
+        paths: (result.paths || []).map((p: PathResult) => {
           const nodes = (p.nodes || [])
-            .filter((n: any) => n.id && n.id !== '')
-            .map((n: any) => ({
+            .filter((n) => n.id && n.id !== '')
+            .map((n) => ({
               id: n.id,
               label: n.label,
               description: n.description,
@@ -337,7 +302,7 @@ export function useGraphNavigation(mergeGraphData: (newData: any) => any) {
       });
 
       navigate('/report');
-    } catch (error: any) {
+    } catch (error: unknown) {
       console.error('Failed to create traversal report:', error);
     }
   }, [navigate]);
diff --git a/web/src/store/graphStore.ts b/web/src/store/graphStore.ts
index 42f08cf3..6890cbe9 100644
--- a/web/src/store/graphStore.ts
+++ b/web/src/store/graphStore.ts
@@ -20,6 +20,7 @@ import { create } from 'zustand';
 import { persist } from 'zustand/middleware';
 import type { VisualizationType } from '../types/explorer';
 import type { GraphData } from '../types/graph';
+import type { RawGraphData, RawGraphNode, RawGraphLink } from '../utils/cypherResultMapper';
 
 interface GraphFilters {
   relationshipTypes: string[];
@@ -147,13 +148,13 @@ interface GraphStore {
   setSelectedExplorer: (type: VisualizationType) => void;
 
   // Graph data (raw API format - cached to avoid re-fetching, persisted to localStorage)
-  rawGraphData: { nodes: any[]; links: any[] } | null;
+  rawGraphData: RawGraphData | null;
   /** Replace raw graph data entirely (clean load) */
-  setRawGraphData: (data: { nodes: any[]; links: any[] } | null) => void;
+  setRawGraphData: (data: RawGraphData | null) => void;
   /** Merge new data into existing graph, deduplicating by concept_id / link key */
-  mergeRawGraphData: (data: { nodes: any[]; links: any[] }) => void;
+  mergeRawGraphData: (data: RawGraphData) => void;
   /** Remove matching nodes and their connected links from the graph (subtractive operator) */
-  subtractRawGraphData: (data: { nodes: any[]; links: any[] }) => void;
+  subtractRawGraphData: (data: RawGraphData) => void;
 
   // Graph data (transformed for current explorer)
   graphData: GraphData | null;
@@ -293,24 +294,16 @@ export const useGraphStore = create<GraphStore>()(
         return { rawGraphData: data };
       }
 
-      const existingNodeIds = new Set(current.nodes.map((n: any) => n.id || n.concept_id));
+      const existingNodeIds = new Set(current.nodes.map((n) => n.concept_id));
       const newNodes = (data.nodes || []).filter(
-        (n: any) => !existingNodeIds.has(n.id || n.concept_id)
+        (n) => !existingNodeIds.has(n.concept_id)
       );
 
       const existingLinkKeys = new Set(
-        current.links.map((l: any) => {
-          const from = l.from_id || l.source?.id || l.source;
-          const to = l.to_id || l.target?.id || l.target;
-          const type = l.relationship_type || l.type || '';
-          return `${from}-${type}-${to}`;
-        })
+        current.links.map((l) => `${l.from_id}-${l.relationship_type}-${l.to_id}`)
       );
-      const newLinks = (data.links || []).filter((l: any) => {
-        const from = l.from_id || l.source?.id || l.source;
-        const to = l.to_id || l.target?.id || l.target;
-        const type = l.relationship_type || l.type || '';
-        return !existingLinkKeys.has(`${from}-${type}-${to}`);
+      const newLinks = (data.links || []).filter((l) => {
+        return !existingLinkKeys.has(`${l.from_id}-${l.relationship_type}-${l.to_id}`);
       });
 
       return {
@@ -330,22 +323,20 @@ export const useGraphStore = create<GraphStore>()(
 
       // Build set of node IDs to remove
       const removeNodeIds = new Set(
-        (data.nodes || []).map((n: any) => n.id || n.concept_id)
+        (data.nodes || []).map((n) => n.concept_id)
       );
 
       // Remove matching nodes
       const remainingNodes = current.nodes.filter(
-        (n: any) => !removeNodeIds.has(n.id || n.concept_id)
+        (n) => !removeNodeIds.has(n.concept_id)
       );
 
       // Remove links that reference removed nodes
       const remainingNodeIds = new Set(
-        remainingNodes.map((n: any) => n.id || n.concept_id)
+        remainingNodes.map((n) => n.concept_id)
       );
-      const remainingLinks = current.links.filter((l: any) => {
-        const from = l.from_id || l.source?.id || l.source;
-        const to = l.to_id || l.target?.id || l.target;
-        return remainingNodeIds.has(from) && remainingNodeIds.has(to);
+      const remainingLinks = current.links.filter((l) => {
+        return remainingNodeIds.has(l.from_id) && remainingNodeIds.has(l.to_id);
       });
 
       return {
diff --git a/web/src/utils/cypherResultMapper.ts b/web/src/utils/cypherResultMapper.ts
index 7dc1446c..8d78f298 100644
--- a/web/src/utils/cypherResultMapper.ts
+++ b/web/src/utils/cypherResultMapper.ts
@@ -41,9 +41,12 @@ export interface CypherQueryResult {
 export interface RawGraphNode {
   concept_id: string;
   label: string;
-  ontology: string;
-  search_terms: string[];
+  ontology?: string;
+  description?: string;
+  search_terms?: string[];
   grounding_strength?: number;
+  diversity_score?: number;
+  evidence_count?: number;
 }
 
 export interface RawGraphLink {
@@ -52,6 +55,32 @@ export interface RawGraphLink {
   relationship_type: string;
   category?: string;
   confidence?: number;
+  grounding_strength?: number;
+}
+
+/** Canonical shape for raw graph data throughout the store and pipeline */
+export interface RawGraphData {
+  nodes: RawGraphNode[];
+  links: RawGraphLink[];
+}
+
+// --- AGE Path Result Types ---
+
+/** A node in an AGE path result (concept or empty relationship placeholder) */
+export interface PathResultNode {
+  id: string;
+  label: string;
+  description?: string;
+  grounding_strength?: number;
+  confidence_level?: string;
+  diversity_score?: number;
+}
+
+/** AGE path result with interleaved nodes and relationship type strings */
+export interface PathResult {
+  nodes: PathResultNode[];
+  relationships: string[];
+  hops?: number;
 }
 
 /**
@@ -87,3 +116,55 @@ export function mapCypherResultToRawGraph(result: CypherQueryResult): {
 
   return { nodes, links };
 }
+
+/**
+ * Extract graph data from an AGE path result.
+ *
+ * AGE path results interleave concept nodes with empty placeholder nodes
+ * (relationship slots). This function filters to real concept nodes,
+ * infers the relationship type between consecutive nodes, and returns
+ * canonical raw graph format plus the ordered concept node IDs (useful
+ * for path animation and enrichment).
+ */
+export function extractGraphFromPath(path: PathResult): {
+  nodes: RawGraphNode[];
+  links: RawGraphLink[];
+  conceptNodeIds: string[];
+} {
+  const conceptNodes: PathResultNode[] = [];
+  const conceptRelTypes: string[][] = [];
+  let pendingRels: string[] = [];
+
+  for (let i = 0; i < path.nodes.length; i++) {
+    const node = path.nodes[i];
+    if (node.id && node.id !== '') {
+      conceptNodes.push(node);
+      conceptRelTypes.push(pendingRels);
+      pendingRels = [];
+    }
+    if (i < path.relationships.length) {
+      pendingRels.push(path.relationships[i]);
+    }
+  }
+
+  const nodes: RawGraphNode[] = conceptNodes.map((node) => ({
+    concept_id: node.id,
+    label: node.label,
+    description: node.description,
+    ontology: 'default',
+    grounding_strength: node.grounding_strength,
+  }));
+
+  const links: RawGraphLink[] = [];
+  for (let i = 0; i < conceptNodes.length - 1; i++) {
+    const rels = conceptRelTypes[i + 1];
+    const relType = rels.find(r => r !== 'APPEARS' && r !== 'SCOPED_BY') || rels[0] || 'CONNECTED';
+    links.push({
+      from_id: conceptNodes[i].id,
+      to_id: conceptNodes[i + 1].id,
+      relationship_type: relType,
+    });
+  }
+
+  return { nodes, links, conceptNodeIds: conceptNodes.map(n => n.id) };
+}
diff --git a/web/src/views/ExplorerView.tsx b/web/src/views/ExplorerView.tsx
index 58dc2fa8..f90a81df 100644
--- a/web/src/views/ExplorerView.tsx
+++ b/web/src/views/ExplorerView.tsx
@@ -27,6 +27,7 @@ import { getZIndexValue } from '../config/zIndex';
 import { apiClient } from '../api/client';
 import { stepToCypher, generateCypher, parseCypherStatements } from '../utils/cypherGenerator';
 import { mapCypherResultToRawGraph } from '../utils/cypherResultMapper';
+import type { RawGraphNode, RawGraphLink } from '../utils/cypherResultMapper';
 import type { VisualizationType } from '../types/explorer';
 
 interface ExplorerViewProps {
@@ -186,7 +187,7 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
   const pathNodeIds = useMemo(() => {
     if (mode !== 'path' || !pathData?.nodes) return [];
     return pathData.nodes
-      .map((n: any) => n.concept_id || n.id)
+      .map((n: RawGraphNode) => n.concept_id)
       .filter(Boolean);
   }, [mode, pathData]);
 
@@ -206,7 +207,7 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
   // Track last-processed data to avoid re-processing on remount or unrelated rerenders.
   // Initialize to current query data so cached results from a previous mount are skipped —
   // this preserves rawGraphData in Zustand when toggling between 2D/3D/analysis views.
-  const lastProcessedData = React.useRef<any>(mode === 'path' ? pathData : exploreData);
+  const lastProcessedData = React.useRef<{ nodes?: unknown[]; links?: unknown[] } | undefined>(mode === 'path' ? pathData : exploreData);
 
   // Update rawGraphData when query results come back
   useEffect(() => {
@@ -280,7 +281,7 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
     const store = useGraphStore.getState();
 
     const nodeLabel = store.rawGraphData?.nodes?.find(
-      (n: any) => (n.concept_id || n.id) === nodeId
+      (n: RawGraphNode) => n.concept_id === nodeId
     )?.label || nodeId;
 
     store.addExplorationStep({
@@ -308,8 +309,8 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
 
     const reportData: GraphReportData = {
       type: 'graph',
-      nodes: rawGraphData.nodes.map((n: any) => ({
-        id: n.concept_id || n.id,
+      nodes: rawGraphData.nodes.map((n: RawGraphNode) => ({
+        id: n.concept_id,
         label: n.label,
         description: n.description,
         ontology: n.ontology,
@@ -317,10 +318,10 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
         diversity_score: n.diversity_score,
         evidence_count: n.evidence_count,
       })),
-      links: rawGraphData.links.map((l: any) => ({
-        source: l.from_id || l.source,
-        target: l.to_id || l.target,
-        type: l.relationship_type || l.type || 'RELATED',
+      links: rawGraphData.links.map((l: RawGraphLink) => ({
+        source: l.from_id,
+        target: l.to_id,
+        type: l.relationship_type || 'RELATED',
         grounding_strength: l.grounding_strength,
       })),
       searchParams: {
@@ -369,7 +370,7 @@ export const ExplorerView: React.FC<ExplorerViewProps> = ({ explorerType }) => {
   }, [explorationSession]);
 
   // Load a saved query
-  const handleLoadQuery = useCallback(async (query: any) => {
+  const handleLoadQuery = useCallback(async (query: { definition_type: string; definition: Record<string, unknown> }) => {
     const definition = query.definition;
 
     // Exploration-type: replay +/- Cypher statements