project-graph-mcp 2.3.0 → 2.3.2

package/web/components/follow-ribbon.js

@@ -0,0 +1,134 @@
+// @ctx .context/web/components/follow-ribbon.ctx
+/**
+ * FollowRibbon — Floating status bar that shows current agent action.
+ * Appears at the bottom of the screen during Follow Mode.
+ * Auto-fades after 4 seconds of inactivity.
+ */
+import Symbiote from '@symbiotejs/symbiote';
+import { events } from '../app.js';
+
+export class FollowRibbon extends Symbiote {
+  init$ = {
+    statusText: '',
+    visible: false,
+  };
+
+  _fadeTimer = null;
+
+  initCallback() {
+    // Event subscriptions are in renderCallback (after template mount)
+  }
+
+  renderCallback() {
+    this.sub('visible', (v) => {
+      this.toggleAttribute('visible', v);
+    });
+
+    events.addEventListener('follow-status-changed', (e) => {
+      const text = e.detail?.text || '';
+      if (!text) {
+        this.$.visible = false;
+        return;
+      }
+      this.$.statusText = text;
+      this.$.visible = true;
+
+      // Auto-fade after 4 seconds
+      if (this._fadeTimer) clearTimeout(this._fadeTimer);
+      this._fadeTimer = setTimeout(() => {
+        this.$.visible = false;
+      }, 4000);
+    });
+
+    events.addEventListener('follow-state-changed', (e) => {
+      if (!e.detail?.enabled) {
+        this.$.visible = false;
+        this.$.statusText = '';
+        if (this._fadeTimer) {
+          clearTimeout(this._fadeTimer);
+          this._fadeTimer = null;
+        }
+      }
+    });
+  }
+}
+
+FollowRibbon.template = `
+<div class="fr-inner">
+  <span class="fr-icon">smart_toy</span>
+  <span class="fr-text" bind="textContent: statusText"></span>
+  <span class="fr-dots"></span>
+</div>
+`;
+
+FollowRibbon.rootStyles = `
+  follow-ribbon {
+    position: fixed;
+    bottom: 20px;
+    left: 50%;
+    transform: translateX(-50%) translateY(20px);
+    z-index: 9999;
+    pointer-events: none;
+    opacity: 0;
+    transition: opacity 0.4s ease, transform 0.4s ease;
+  }
+
+  follow-ribbon[visible] {
+    opacity: 1;
+    transform: translateX(-50%) translateY(0);
+  }
+
+  .fr-inner {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 8px 20px;
+    border-radius: 24px;
+    background: rgba(20, 20, 25, 0.85);
+    backdrop-filter: blur(16px);
+    -webkit-backdrop-filter: blur(16px);
+    border: 1px solid rgba(76, 139, 245, 0.25);
+    box-shadow: 0 8px 32px rgba(0, 0, 0, 0.4), 0 0 16px rgba(76, 139, 245, 0.1);
+    font-family: 'Inter', -apple-system, sans-serif;
+    font-size: 12px;
+    font-weight: 500;
+    color: rgba(255, 255, 255, 0.9);
+    white-space: nowrap;
+    max-width: 500px;
+  }
+
+  .fr-icon {
+    font-family: 'Material Symbols Outlined';
+    font-size: 16px;
+    color: #4c8bf5;
+    animation: fr-pulse 2s ease-in-out infinite;
+  }
+
+  .fr-text {
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  .fr-dots::after {
+    content: '...';
+    animation: fr-dots 1.5s steps(3) infinite;
+    display: inline-block;
+    width: 16px;
+    text-align: left;
+    color: rgba(255, 255, 255, 0.4);
+  }
+
+  @keyframes fr-pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.5; }
+  }
+
+  @keyframes fr-dots {
+    0% { content: ''; }
+    33% { content: '.'; }
+    66% { content: '..'; }
+    100% { content: '...'; }
+  }
+`;
+
+FollowRibbon.reg('follow-ribbon');

package/web/follow-controller.js

@@ -0,0 +1,241 @@
+// @ctx .context/web/follow-controller.ctx
+/**
+ * FollowController — Central orchestrator for Follow Mode.
+ *
+ * Classifies incoming tool-events and dispatches debounced focus-change
+ * signals to subscribed panels (graph, code-viewer, monitor).
+ * Also manages the status ribbon text shown during active follow.
+ *
+ * NOTE: Does NOT import from app.js to avoid circular dependency.
+ * Call init(events, emit) before enable().
+ */
+
+/** Debounce delay for heavy visual updates (camera, code loading) */
+const HEAVY_DEBOUNCE = 800;
+
+class FollowController {
+  /** @type {boolean} */
+  enabled = false;
+  /** @type {{type: string, target: any, action?: string, meta?: object}|null} */
+  currentFocus = null;
+  /** @type {string} */
+  statusText = '';
+  /** @type {number|null} */
+  _debounceTimer = null;
+  /** @type {string|null} Previous hash before entering follow mode */
+  _previousHash = null;
+  /** @type {Function|null} */
+  _boundHandler = null;
+  /** @type {EventTarget|null} */
+  _events = null;
+  /** @type {Function|null} */
+  _emit = null;
+
+  /**
+   * Late-bind events bus and emit function (breaks circular import).
+   * Must be called once before enable().
+   * @param {EventTarget} events
+   * @param {Function} emit
+   */
+  init(events, emit) {
+    this._events = events;
+    this._emit = emit;
+  }
+
+  enable() {
+    if (this.enabled) return;
+    this.enabled = true;
+
+    // Save current location for restoring later
+    this._previousHash = location.hash;
+
+    // Bind tool-event listener
+    this._boundHandler = (e) => this._onToolEvent(e.detail);
+    this._events.addEventListener('tool-event', this._boundHandler);
+
+    this._emit('follow-state-changed', { enabled: true });
+  }
+
+  disable() {
+    if (!this.enabled) return;
+    this.enabled = false;
+
+    // Clean up
+    if (this._boundHandler) {
+      this._events.removeEventListener('tool-event', this._boundHandler);
+      this._boundHandler = null;
+    }
+    if (this._debounceTimer) {
+      clearTimeout(this._debounceTimer);
+      this._debounceTimer = null;
+    }
+
+    this.currentFocus = null;
+    this._emitStatus('');
+
+    this._emit('follow-state-changed', { enabled: false });
+  }
+
+  /** @returns {string|null} */
+  getPreviousHash() {
+    return this._previousHash;
+  }
+
+  /**
+   * Main tool-event dispatcher. Classifies the event and routes to appropriate action.
+   * @param {object} event - Tool event from WebSocket
+   */
+  _onToolEvent(event) {
+    if (!this.enabled) return;
+
+    const toolName = event.tool || event.name || '';
+    const args = event.args || {};
+    const isCall = event.type === 'tool_call';
+    const isResult = event.type === 'tool_result';
+
+    // Extract short tool name (strip prefixes like 'default_api:', 'mcp_project-graph_')
+    const shortName = this._shortName(toolName);
+
+    // Status ribbon — update immediately on call
+    if (isCall) {
+      const statusText = this._buildStatusText(shortName, args);
+      if (statusText) this._emitStatus(statusText);
+    }
+
+    // Visual focus — classify and dispatch (debounced for heavy ops)
+    const action = this._classify(shortName, args, isCall, isResult, event);
+    if (action) {
+      if (action.immediate) {
+        this._emitFocusNow(action.focus);
+      } else {
+        this._emitFocusDebounced(action.focus, action.debounce || HEAVY_DEBOUNCE);
+      }
+    }
+  }
+
+  /**
+   * Classify tool event into a visual action.
+   * Only handles tools emitted by our MCP server (navigate, get_skeleton, etc.).
+   * IDE-local tools (view_file, grep_search) never arrive over WebSocket.
+   * @returns {{focus: object, debounce?: number, immediate?: boolean}|null}
+   */
+  _classify(tool, args, isCall, isResult, raw) {
+    if (!isCall) return null;
+
+    // === Graph navigation ===
+    if (tool === 'navigate') {
+      if (args.action === 'expand' && args.symbol) {
+        return { focus: { type: 'graph', target: args.symbol, action: 'focus' }, debounce: HEAVY_DEBOUNCE };
+      }
+      if (args.action === 'deps' && args.symbol) {
+        return { focus: { type: 'graph', target: args.symbol, action: 'deps' }, debounce: HEAVY_DEBOUNCE };
+      }
+      if (args.action === 'usages' && args.symbol) {
+        return { focus: { type: 'graph', target: args.symbol, action: 'deps' }, debounce: HEAVY_DEBOUNCE };
+      }
+      if (args.action === 'call_chain' && args.from && args.to) {
+        return { focus: { type: 'graph', target: { from: args.from, to: args.to }, action: 'chain' }, immediate: true };
+      }
+    }
+
+    // === Skeleton / Overview ===
+    if (tool === 'get_skeleton' || tool === 'get_ai_context') {
+      return { focus: { type: 'graph', action: 'fit' }, immediate: true };
+    }
+
+    // === Code compaction (compact_file action has a file path) ===
+    if (tool === 'compact' && args.path) {
+      return { focus: { type: 'file', target: args.path }, debounce: HEAVY_DEBOUNCE };
+    }
+
+    // === Analysis ===
+    if (tool === 'analyze') {
+      return { focus: { type: 'analysis' }, immediate: true };
+    }
+
+    return null;
+  }
+
+  /**
+   * Build human-readable status text for the ribbon.
+   * Only MCP-server tools arrive here (navigate, get_skeleton, compact, analyze, docs, etc.).
+   * @param {string} tool
+   * @param {object} args
+   * @returns {string}
+   */
+  _buildStatusText(tool, args) {
+    const file = args.path || '';
+    const short = file ? file.split('/').slice(-2).join('/') : '';
+
+    switch (tool) {
+      case 'navigate': {
+        if (args.action === 'expand') return `Expanding ${args.symbol}`;
+        if (args.action === 'deps') return `Tracing deps of ${args.symbol}`;
+        if (args.action === 'usages') return `Finding usages of ${args.symbol}`;
+        if (args.action === 'call_chain') return `Tracing ${args.from} → ${args.to}`;
+        if (args.action === 'sub_projects') return `Scanning sub-projects`;
+        return `Navigating graph`;
+      }
+      case 'get_skeleton': return `Scanning project structure`;
+      case 'get_ai_context': return `Loading AI context`;
+      case 'compact': return `Compacting ${short}`;
+      case 'analyze': return `Analyzing: ${args.action || ''}`;
+      case 'docs': return `Documentation: ${args.action || ''}`;
+      case 'jsdoc': return `JSDoc: ${args.action || ''}`;
+      case 'db': return `Database: ${args.action || ''}`;
+      case 'testing': return `Tests: ${args.action || ''}`;
+      case 'filters': return `Filters: ${args.action || ''}`;
+      default: return tool ? `Running ${tool}` : '';
+    }
+  }
+
+  /**
+   * Extract short tool name from full prefixed name.
+   * 'default_api:view_file' → 'view_file'
+   * 'mcp_project-graph_navigate' → 'navigate'
+   */
+  _shortName(full) {
+    // Strip 'default_api:' prefix
+    let name = full.replace(/^default_api:/, '');
+    // Strip 'mcp_project-graph_' prefix
+    name = name.replace(/^mcp_project-graph_/, '');
+    return name;
+  }
+
+  /**
+   * Emit focus change immediately (for urgent actions like call_chain).
+   */
+  _emitFocusNow(focus) {
+    if (this._debounceTimer) {
+      clearTimeout(this._debounceTimer);
+      this._debounceTimer = null;
+    }
+    this.currentFocus = focus;
+    this._emit('follow-focus-changed', focus);
+  }
+
+  /**
+   * Emit focus change with debounce (for rapid file reads, etc.).
+   */
+  _emitFocusDebounced(focus, delay) {
+    if (this._debounceTimer) {
+      clearTimeout(this._debounceTimer);
+    }
+    this._debounceTimer = setTimeout(() => {
+      this._debounceTimer = null;
+      this.currentFocus = focus;
+      this._emit('follow-focus-changed', focus);
+    }, delay);
+  }
+
+  /**
+   * Emit status text for the ribbon.
+   */
+  _emitStatus(text) {
+    this.statusText = text;
+    this._emit('follow-status-changed', { text });
+  }
+}
+
+/** Singleton instance */
+export const followController = new FollowController();

package/web/panels/code-viewer.js

@@ -29,7 +29,7 @@ export class CodeViewer extends e{init$={filename:"Select a file",hasFile:!1,vie
   // Toggle between source and the transformation
   this.$.viewMode=this.$.viewMode==="source"?"transformed":"source";
   this._showCurrentMode();
-}};_fileData=null;_isReadable=!1;_transformCache=null;_loadingTransform=!1;_currentPath=null;initCallback(){t.addEventListener("file-selected",e=>this._loadFile(e.detail.path));if(o.activeFile)requestAnimationFrame(()=>this._loadFile(o.activeFile))}renderCallback(){this.sub("hasFile",e=>{this.toggleAttribute("has-file",e)}),this.sub("viewMode",e=>{
+}};_fileData=null;_isReadable=!1;_transformCache=null;_loadingTransform=!1;_currentPath=null;initCallback(){t.addEventListener("file-selected",e=>this._loadFile(e.detail.path));t.addEventListener("follow-focus-changed",e=>{const d=e.detail;if(d.type==="file"&&d.target){this._loadFile(d.target);if(d.meta?.startLine){setTimeout(()=>{const c=this._getCodeBlock();if(c&&c.scrollToLine)c.scrollToLine(d.meta.startLine)},200)}}});if(o.activeFile)requestAnimationFrame(()=>this._loadFile(o.activeFile))}renderCallback(){this.sub("hasFile",e=>{this.toggleAttribute("has-file",e)}),this.sub("viewMode",e=>{
   const lang=_getLang(this._currentPath);
   this.toggleAttribute("mode-raw","source"!==e);
   if(lang==='md'){

package/web/panels/dep-graph.js

@@ -687,8 +687,6 @@ export class DepGraph extends Symbiote {
   _wasDragged = false;
   /** @type {Map<string, string>} */
   _fileMap = new Map();
-  /** @type {boolean} */
-  _autopilot = false;
   /** @type {HTMLElement|null} */
   _canvas = null;
   /** @type {object|null} Skeleton data for resolving pin names */
@@ -851,11 +849,6 @@ export class DepGraph extends Symbiote {
         this._restoreFlatFocus();
       }
     });
-    
-    // Follow mode: listen for global state (set from topbar)
-    events.addEventListener('follow-mode-changed', (e) => {
-      this._autopilot = e.detail.enabled;
-    });
 
     // Label Mode controls
     const labelBtns = this.querySelectorAll('.label-mode-btn');
@@ -983,17 +976,14 @@ export class DepGraph extends Symbiote {
     ro.observe(this);
     this._resizeObserver = ro;
 
-    // Bind and save global listener functions for clean up
     this._onSkeletonLoaded = (e) => {
       if (this._graphBuilt || this.style.display === 'none' || this.offsetWidth === 0) return;
       requestAnimationFrame(() => this._buildGraph(e.detail));
     };
     
-    this._onToolEvent = (e) => {
+    this._onFollowFocusChanged = (e) => {
       if (this.style.display === 'none' || this.offsetWidth === 0) return;
-      if (this._autopilot) {
-        this._handleAutopilot(e.detail);
-      }
+      this._handleFollowFocus(e.detail);
     };
     
     this._onFileSelected = (e) => {
@@ -1026,8 +1016,8 @@ export class DepGraph extends Symbiote {
       }).catch(() => {});
     }
 
-    // Autopilot: listen for agent tool events
-    events.addEventListener('tool-event', this._onToolEvent);
+    // Autopilot: listen for orchestrator events
+    events.addEventListener('follow-focus-changed', this._onFollowFocusChanged);
 
     // Update route within graph section
     // On node click → save file path (just focusing)
@@ -1165,7 +1155,7 @@ export class DepGraph extends Symbiote {
   disconnectedCallback() {
     super.disconnectedCallback?.();
     if (this._onSkeletonLoaded) events.removeEventListener('skeleton-loaded', this._onSkeletonLoaded);
-    if (this._onToolEvent) events.removeEventListener('tool-event', this._onToolEvent);
+    if (this._onFollowFocusChanged) events.removeEventListener('follow-focus-changed', this._onFollowFocusChanged);
     if (this._onFileSelected) events.removeEventListener('file-selected', this._onFileSelected);
     if (this._onHashChange) window.removeEventListener('hashchange', this._onHashChange);
     if (this._resizeObserver) {
@@ -2498,37 +2488,26 @@ export class DepGraph extends Symbiote {
   }
 
   /**
-   * Handle agent tool events for autopilot mode
-   * @param {object} event
+   * Handle orchestrated visual focus from FollowController
+   * @param {object} detail 
    */
-  _handleAutopilot(event) {
+  _handleFollowFocus({ type, target, action }) {
     if (!this._editor || !this._canvas) return;
-
-    const toolName = event.tool || event.name || '';
-    const args = event.args || {};
-
-    // tool:call events
-    if (event.phase === 'call' || event.type === 'tool:call') {
-      if (toolName === 'navigate' && args.action === 'expand' && args.symbol) {
-        this._focusSymbol(args.symbol);
-      } else if (toolName === 'navigate' && args.action === 'deps' && args.symbol) {
-        this._highlightDeps(args.symbol);
-      } else if (toolName === 'navigate' && args.action === 'call_chain') {
-        // Phase 4: animate call chain when agent traces a path
-        if (args.from && args.to) {
-          this._highlightCallChain(args.from, args.to);
-        }
-      } else if (toolName === 'navigate' && args.action === 'usages' && args.symbol) {
-        this._highlightDeps(args.symbol);
-      } else if (toolName === 'get_skeleton') {
+    if (type !== 'graph' && type !== 'file') return; // React to graph and file actions
+
+    if (type === 'graph') {
+      if (action === 'focus' && target) {
+        this._focusSymbol(target);
+      } else if (action === 'deps' && target) {
+        this._highlightDeps(target);
+      } else if (action === 'chain' && target.from && target.to) {
+        this._highlightCallChain(target.from, target.to);
+      } else if (action === 'fit') {
         this._canvas.fitView();
-      } else if (toolName === 'compact' && args.path) {
-        this._pulseFile(args.path);
-      } else if (toolName === 'view_file' && args.path) {
-        // Agent opened a file — focus it on the board
-        this._focusFile(args.path);
-        this._pulseFile(args.path);
       }
+    } else if (type === 'file' && target) {
+      this._focusFile(target);
+      this._pulseFile(target);
     }
   }
 

package/web/style.css

@@ -123,6 +123,12 @@ html, body {
   background: rgba(76, 139, 245, 0.15);
   color: #4c8bf5;
   border-color: rgba(76, 139, 245, 0.3);
+  animation: follow-btn-glow 2s ease-in-out infinite;
+}
+
+@keyframes follow-btn-glow {
+  0%, 100% { box-shadow: 0 0 4px rgba(76, 139, 245, 0.1); }
+  50% { box-shadow: 0 0 12px rgba(76, 139, 245, 0.4); }
 }
 
 /* Agent badge */