beads-map 0.3.1 → 0.3.4

package/components/BeadsGraph.tsx

@@ -12,7 +12,7 @@ import React, {
 import { forceCollide, forceRadial, forceX, forceY } from "d3-force";
 import type { GraphNode, GraphLink, ColorMode } from "@/lib/types";
 import {
-  STATUS_COLORS, STATUS_LABELS,
+  STATUS_COLORS, STATUS_LABELS, PRIORITY_COLORS, PRIORITY_LABELS,
   COLOR_MODE_LABELS, getPersonColor, getCatppuccinPrefixColor, getPrefixLabel,
 } from "@/lib/types";
 
@@ -52,6 +52,20 @@ interface BeadsGraphProps {
   colorMode?: ColorMode;
   /** Callback to change color mode (from legend selector) */
   onColorModeChange?: (mode: ColorMode) => void;
+  /** Whether to auto-zoom to fit all nodes after data updates and layout changes */
+  autoFit?: boolean;
+  /** Callback to toggle auto-fit */
+  onAutoFitToggle?: () => void;
+  /** Node ID to show a pulsing ripple on (most recently active node) */
+  pulseNodeId?: string | null;
+  /** Whether pulse animation is enabled */
+  showPulse?: boolean;
+  /** Callback to toggle pulse animation */
+  onShowPulseToggle?: () => void;
+  /** When set, only show this epic and its connected subgraph */
+  focusedEpicId?: string | null;
+  /** Callback to exit focused epic mode */
+  onExitFocusedEpic?: () => void;
 }
 
 // Node size calculation
@@ -75,6 +89,8 @@ let _currentColorMode: ColorMode = "status";
 // Get color based on current color mode
 function getNodeColor(node: GraphNode): string {
   switch (_currentColorMode) {
+    case "priority":
+      return PRIORITY_COLORS[node.priority] || PRIORITY_COLORS[2];
     case "owner":
       return getPersonColor(node.createdBy);
     case "assignee":
@@ -237,6 +253,13 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
   onExpandAll,
   colorMode = "status",
   onColorModeChange,
+  autoFit = true,
+  onAutoFitToggle,
+  pulseNodeId,
+  showPulse = true,
+  onShowPulseToggle,
+  focusedEpicId,
+  onExitFocusedEpic,
 }, ref) {
   const graphRef = useRef<any>(null);
   const containerRef = useRef<HTMLDivElement>(null);
@@ -293,6 +316,9 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
   );
   // Color mode ref for paintNode (which has [] deps) to read current color mode
   const colorModeRef = useRef<ColorMode>(colorMode);
+  // Pulse node ref: which node to show ripple animation on
+  const pulseNodeIdRef = useRef<string | null>(pulseNodeId || null);
+  const showPulseRef = useRef<boolean>(showPulse);
 
   // Callback ref for refreshing graph when avatar images finish loading
   const avatarRefreshRef = useRef<() => void>(() => {});
@@ -327,11 +353,64 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
   // then removes child nodes and remaps their links to the parent epic.
   // Must be declared BEFORE effects that reference viewNodes/viewLinks.
   const { viewNodes, viewLinks } = useMemo(() => {
-    if (!collapsedEpicIds || collapsedEpicIds.size === 0) return { viewNodes: nodes, viewLinks: links };
+    let currentNodes = nodes;
+    let currentLinks = links;
+
+    // === PHASE 1: Epic focus mode ===
+    // When focused on an epic, filter to only the epic's subgraph
+    if (focusedEpicId) {
+      // Build child->parent map
+      const childToParent = new Map<string, string>();
+      for (const link of currentLinks) {
+        const src = typeof link.source === "object" ? (link.source as any).id : link.source;
+        const tgt = typeof link.target === "object" ? (link.target as any).id : link.target;
+        if (link.type === "parent-child") {
+          childToParent.set(tgt, src);
+        }
+      }
+      const nodeIdSet = new Set(currentNodes.map((n) => n.id));
+      for (const node of currentNodes) {
+        if (!childToParent.has(node.id) && node.id.includes(".")) {
+          const parentId = node.id.split(".")[0];
+          if (nodeIdSet.has(parentId)) {
+            childToParent.set(node.id, parentId);
+          }
+        }
+      }
+
+      // Collect epic + direct children
+      const subgraphIds = new Set<string>();
+      subgraphIds.add(focusedEpicId);
+      for (const [childId, parentId] of childToParent) {
+        if (parentId === focusedEpicId) {
+          subgraphIds.add(childId);
+        }
+      }
+
+      // Add 1-hop neighbors connected via blocks/relates_to links
+      for (const link of currentLinks) {
+        const src = typeof link.source === "object" ? (link.source as any).id : link.source;
+        const tgt = typeof link.target === "object" ? (link.target as any).id : link.target;
+        if (link.type !== "parent-child") {
+          if (subgraphIds.has(src) && nodeIdSet.has(tgt)) subgraphIds.add(tgt);
+          if (subgraphIds.has(tgt) && nodeIdSet.has(src)) subgraphIds.add(src);
+        }
+      }
+
+      currentNodes = currentNodes.filter((n) => subgraphIds.has(n.id));
+      currentLinks = currentLinks.filter((link) => {
+        const src = typeof link.source === "object" ? (link.source as any).id : link.source;
+        const tgt = typeof link.target === "object" ? (link.target as any).id : link.target;
+        return subgraphIds.has(src) && subgraphIds.has(tgt);
+      });
+    }
+
+    // === PHASE 2: Collapse mode ===
+    if (!collapsedEpicIds || collapsedEpicIds.size === 0) return { viewNodes: currentNodes, viewLinks: currentLinks };
 
     // Build child->parent map from parent-child links
     const childToParent = new Map<string, string>();
-    for (const link of links) {
+    for (const link of currentLinks) {
       const src = typeof link.source === "object" ? (link.source as any).id : link.source;
       const tgt = typeof link.target === "object" ? (link.target as any).id : link.target;
       if (link.type === "parent-child") {
@@ -340,8 +419,8 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
       }
     }
     // Fallback: infer from hierarchical IDs (e.g., "beads-map-3r3.1" -> parent "beads-map-3r3")
-    const nodeIds = new Set(nodes.map((n) => n.id));
-    for (const node of nodes) {
+    const nodeIds = new Set(currentNodes.map((n) => n.id));
+    for (const node of currentNodes) {
       if (!childToParent.has(node.id) && node.id.includes(".")) {
         const parentId = node.id.split(".")[0];
         if (nodeIds.has(parentId)) {
@@ -358,7 +437,7 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
       }
     }
 
-    if (childIds.size === 0) return { viewNodes: nodes, viewLinks: links };
+    if (childIds.size === 0) return { viewNodes: currentNodes, viewLinks: currentLinks };
 
     // Also build a filtered childToParent for only the collapsed children (for link remapping)
     const collapsedChildToParent = new Map<string, string>();
@@ -372,7 +451,7 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
     const extraDependentCount = new Map<string, number>();
     for (const [childId, parentId] of collapsedChildToParent) {
       collapsedCounts.set(parentId, (collapsedCounts.get(parentId) || 0) + 1);
-      const child = nodes.find((n) => n.id === childId);
+      const child = currentNodes.find((n) => n.id === childId);
       if (child) {
         extraBlockerCount.set(parentId, (extraBlockerCount.get(parentId) || 0) + child.blockerCount);
         extraDependentCount.set(parentId, (extraDependentCount.get(parentId) || 0) + child.dependentCount);
@@ -380,7 +459,7 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
     }
 
     // Filter nodes: remove collapsed children, augment their parents
-    const filteredNodes: GraphNode[] = nodes
+    const filteredNodes: GraphNode[] = currentNodes
       .filter((n) => !childIds.has(n.id))
       .map((n) => ({
         ...n,
@@ -392,7 +471,7 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
     // Remap links: replace collapsed child IDs with parent IDs, drop internal parent-child links
     const remappedLinks: GraphLink[] = [];
     const linkSeen = new Set<string>();
-    for (const link of links) {
+    for (const link of currentLinks) {
       let src = typeof link.source === "object" ? (link.source as any).id : link.source;
       let tgt = typeof link.target === "object" ? (link.target as any).id : link.target;
       // Drop parent-child links where the child is collapsed
@@ -408,7 +487,7 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
     }
 
     return { viewNodes: filteredNodes, viewLinks: remappedLinks };
-  }, [nodes, links, collapsedEpicIds]);
+  }, [nodes, links, collapsedEpicIds, focusedEpicId]);
 
   // Keep viewNodesRef in sync for mousemove avatar hit-testing
   viewNodesRef.current = viewNodes;
@@ -463,7 +542,7 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
 
   // Compute dynamic legend items based on color mode and visible nodes
   const legendItems = useMemo(() => {
-    if (colorMode === "status") return []; // handled by static STATUS_COLORS rendering
+    if (colorMode === "status" || colorMode === "priority") return []; // handled by static rendering
 
     const items = new Map<string, string>(); // label -> color
 
@@ -552,6 +631,13 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
     minimapRafRef.current = requestAnimationFrame(() => redrawMinimapRef.current());
   }, [colorMode]);
 
+  // Sync pulse node ref
+  useEffect(() => {
+    pulseNodeIdRef.current = pulseNodeId || null;
+    showPulseRef.current = showPulse;
+    refreshGraph(graphRef);
+  }, [pulseNodeId, showPulse]);
+
   // Avatar hover detection: mousemove on container, hit-test against avatar positions
   useEffect(() => {
     const container = containerRef.current;
@@ -830,16 +916,19 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
     // Re-heat simulation so new forces take effect immediately
     fg.d3ReheatSimulation();
 
-    // Fit to view after layout settles
-    const delay = initialLayoutApplied.current ? 600 : 1000;
-    const timer = setTimeout(() => {
-      if (graphRef.current) graphRef.current.zoomToFit(400, 60);
-    }, delay);
+    // Fit to view after layout settles (only if auto-fit is enabled)
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    if (autoFit) {
+      const delay = initialLayoutApplied.current ? 600 : 1000;
+      timer = setTimeout(() => {
+        if (graphRef.current) graphRef.current.zoomToFit(400, 60);
+      }, delay);
+    }
 
     initialLayoutApplied.current = true;
 
-    return () => clearTimeout(timer);
-  }, [layoutMode, viewNodes, viewLinks]);
+    return () => { if (timer) clearTimeout(timer); };
+  }, [layoutMode, viewNodes, viewLinks, autoFit]);
 
   // Bootstrap trick: start in DAG to spread nodes into good positions,
   // then auto-switch to Force mode. This replicates the exact code path
@@ -855,16 +944,35 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
     return () => clearTimeout(timer);
   }, [ForceGraph2D, nodes.length]);
 
-  // Fit to view on initial load (skip during timeline replay)
+  // Fit to view on initial load (skip during timeline replay or when auto-fit disabled)
   useEffect(() => {
     if (timelineActive) return;
+    if (!autoFit) return;
     if (graphRef.current && nodes.length > 0) {
       const timer = setTimeout(() => {
         graphRef.current.zoomToFit(400, 60);
       }, 800);
       return () => clearTimeout(timer);
     }
-  }, [nodes.length, timelineActive]);
+  }, [nodes.length, timelineActive, autoFit]);
+
+  // Auto zoom-to-fit when entering/exiting epic focus mode (unconditional)
+  const prevFocusedEpicIdRef = useRef<string | null | undefined>(undefined);
+  useEffect(() => {
+    // Skip on mount (initial render)
+    if (prevFocusedEpicIdRef.current === undefined) {
+      prevFocusedEpicIdRef.current = focusedEpicId ?? null;
+      return;
+    }
+    prevFocusedEpicIdRef.current = focusedEpicId ?? null;
+    const graph = graphRef.current;
+    if (!graph) return;
+    // Small delay to let the force graph process the new node set
+    const timer = setTimeout(() => {
+      graph.zoomToFit(400, 60);
+    }, 100);
+    return () => clearTimeout(timer);
+  }, [focusedEpicId]);
 
   // Memoize graphData so the object reference stays stable across renders.
   // This prevents react-force-graph from treating it as "new data" and
@@ -938,23 +1046,13 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
 
       const animatedSize = size * animScale;
 
-      // Semantic zoom: fade out individual nodes when zoomed out
-      // Transition zone: globalScale 0.1 (invisible) → 0.2 (fully visible)
-      const FADE_OUT_MIN = 0.1;
-      const FADE_OUT_MAX = 0.2;
-      const zoomFade = globalScale <= FADE_OUT_MIN
-        ? 0
-        : globalScale >= FADE_OUT_MAX
-          ? 1
-          : (globalScale - FADE_OUT_MIN) / (FADE_OUT_MAX - FADE_OUT_MIN);
-
       // Opacity: dim non-connected nodes when highlighting
       const opacity =
         (hasHighlight && !isConnected
           ? 0.15
           : graphNode.status === "closed"
             ? 0.5
-            : 1) * removeOpacity * zoomFade;
+            : 1) * removeOpacity;
       
       if (opacity <= 0.01) return; // skip fully faded nodes
 
@@ -1014,6 +1112,30 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
         }
       }
 
+      // --- Activity pulse ripple (continuous, on most-recently-active node) ---
+      if (showPulseRef.current && pulseNodeIdRef.current === graphNode.id) {
+        const RIPPLE_PERIOD = 2000; // full cycle in ms
+        const RIPPLE_COUNT = 3;
+        const RIPPLE_STAGGER = 500; // ms between each ring
+        // Scale ripple to ~30 screen pixels regardless of zoom level
+        const maxExpand = Math.max(25, 30 / globalScale);
+        const MAX_RIPPLE_RADIUS = animatedSize + maxExpand;
+
+        for (let i = 0; i < RIPPLE_COUNT; i++) {
+          const phase = ((now + i * RIPPLE_STAGGER) % RIPPLE_PERIOD) / RIPPLE_PERIOD;
+          const rippleRadius = animatedSize + 2 / globalScale + phase * (MAX_RIPPLE_RADIUS - animatedSize);
+          const rippleOpacity = (1 - phase) * 0.6;
+
+          ctx.beginPath();
+          ctx.arc(node.x, node.y, rippleRadius, 0, Math.PI * 2);
+          ctx.strokeStyle = "#10b981"; // emerald-500
+          ctx.lineWidth = Math.max(1.5 / globalScale, 0.5);
+          ctx.globalAlpha = rippleOpacity * opacity;
+          ctx.stroke();
+        }
+        ctx.globalAlpha = opacity; // reset
+      }
+
       // --- Spawn glow ---
       if (spawnTime) {
         const elapsed = now - spawnTime;
@@ -1223,15 +1345,6 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
       const isConnectedLink =
         hasHighlight && connected.has(srcId) && connected.has(tgtId);
 
-      // Semantic zoom: fade out links when zoomed out (same range as nodes)
-      const LINK_FADE_OUT_MIN = 0.1;
-      const LINK_FADE_OUT_MAX = 0.2;
-      const linkZoomFade = globalScale <= LINK_FADE_OUT_MIN
-        ? 0
-        : globalScale >= LINK_FADE_OUT_MAX
-          ? 1
-          : (globalScale - LINK_FADE_OUT_MIN) / (LINK_FADE_OUT_MAX - LINK_FADE_OUT_MIN);
-
       // Parent-child links are more subtle
       const opacity = (isParentChild
         ? hasHighlight
@@ -1239,7 +1352,7 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
           : 0.2
         : hasHighlight
           ? isConnectedLink ? 0.8 : 0.08
-          : 0.35) * linkAnimAlpha * linkZoomFade;
+          : 0.35) * linkAnimAlpha;
       
       if (opacity <= 0.01) return; // skip fully faded links
 
@@ -1330,7 +1443,6 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
 
   // Semantic zoom: draw epic/cluster labels when zoomed out far.
   // Computes centroids from live node positions and draws titles.
-  // Appears as nodes fade out (inverse of node fade).
   const paintClusterLabels = useCallback(
     (ctx: CanvasRenderingContext2D, globalScale: number) => {
       if (!showClusters) return;
@@ -1786,230 +1898,293 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
   );
 
   return (
-    <div ref={containerRef} className="w-full h-full relative">
+    <div ref={containerRef} className="w-full h-full relative" data-tutorial="graph">
       {/* Top-left controls */}
-      <div className="absolute top-3 left-3 sm:top-4 sm:left-4 z-10 flex items-start gap-1.5 sm:gap-2">
-        {/* Layout mode toggle */}
-        <div className="flex bg-white/90 backdrop-blur-sm rounded-lg border border-zinc-200 shadow-sm overflow-hidden">
-          <button
-            onClick={() => setLayoutMode("force")}
-            className={`px-3 py-1.5 text-xs font-medium transition-colors ${
-              layoutMode === "force"
-                ? "bg-emerald-500 text-white"
-                : "text-zinc-500 hover:text-zinc-700 hover:bg-zinc-50"
-            }`}
-          >
-            <span className="flex items-center gap-1.5">
-              <svg
-                className="w-3.5 h-3.5"
-                viewBox="0 0 16 16"
-                fill="none"
-                stroke="currentColor"
-                strokeWidth="1.5"
-              >
-                {/* Spring/force icon: scattered dots with connections */}
-                <circle cx="4" cy="4" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="12" cy="3" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="8" cy="8" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="3" cy="12" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="13" cy="11" r="1.5" fill="currentColor" stroke="none" />
-                <line x1="4" y1="4" x2="8" y2="8" strokeOpacity="0.5" />
-                <line x1="12" y1="3" x2="8" y2="8" strokeOpacity="0.5" />
-                <line x1="3" y1="12" x2="8" y2="8" strokeOpacity="0.5" />
-                <line x1="13" y1="11" x2="8" y2="8" strokeOpacity="0.5" />
-              </svg>
-              <span className="hidden sm:inline">Force</span>
-            </span>
-          </button>
-          <div className="w-px bg-zinc-200" />
-          <button
-            onClick={() => setLayoutMode("dag")}
-            className={`px-3 py-1.5 text-xs font-medium transition-colors ${
-              layoutMode === "dag"
-                ? "bg-emerald-500 text-white"
-                : "text-zinc-500 hover:text-zinc-700 hover:bg-zinc-50"
-            }`}
-          >
-            <span className="flex items-center gap-1.5">
-              <svg
-                className="w-3.5 h-3.5"
-                viewBox="0 0 16 16"
-                fill="none"
-                stroke="currentColor"
-                strokeWidth="1.5"
-              >
-                {/* Tree/DAG icon: top-down hierarchy */}
-                <circle cx="8" cy="2.5" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="4" cy="8" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="12" cy="8" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="2" cy="13.5" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="6" cy="13.5" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="12" cy="13.5" r="1.5" fill="currentColor" stroke="none" />
-                <line x1="8" y1="4" x2="4" y2="6.5" strokeOpacity="0.5" />
-                <line x1="8" y1="4" x2="12" y2="6.5" strokeOpacity="0.5" />
-                <line x1="4" y1="9.5" x2="2" y2="12" strokeOpacity="0.5" />
-                <line x1="4" y1="9.5" x2="6" y2="12" strokeOpacity="0.5" />
-                <line x1="12" y1="9.5" x2="12" y2="12" strokeOpacity="0.5" />
-              </svg>
-              <span className="hidden sm:inline">DAG</span>
-            </span>
-          </button>
-          <div className="w-px bg-zinc-200" />
-          <button
-            onClick={() => setLayoutMode("radial")}
-            className={`px-3 py-1.5 text-xs font-medium transition-colors ${
-              layoutMode === "radial"
-                ? "bg-emerald-500 text-white"
-                : "text-zinc-500 hover:text-zinc-700 hover:bg-zinc-50"
-            }`}
-          >
-            <span className="flex items-center gap-1.5">
-              <svg
-                className="w-3.5 h-3.5"
-                viewBox="0 0 16 16"
-                fill="none"
-                stroke="currentColor"
-                strokeWidth="1.5"
-              >
-                {/* Radial icon: concentric rings with center dot */}
-                <circle cx="8" cy="8" r="2" fill="currentColor" stroke="none" />
-                <circle cx="8" cy="8" r="5" fill="none" strokeOpacity="0.5" />
-                <circle cx="8" cy="8" r="7.5" fill="none" strokeOpacity="0.3" />
-              </svg>
-              <span className="hidden sm:inline">Radial</span>
-            </span>
-          </button>
-          <div className="w-px bg-zinc-200" />
-          <button
-            onClick={() => setLayoutMode("cluster")}
-            className={`px-3 py-1.5 text-xs font-medium transition-colors ${
-              layoutMode === "cluster"
-                ? "bg-emerald-500 text-white"
-                : "text-zinc-500 hover:text-zinc-700 hover:bg-zinc-50"
-            }`}
-          >
-            <span className="flex items-center gap-1.5">
-              <svg
-                className="w-3.5 h-3.5"
-                viewBox="0 0 16 16"
-                fill="none"
-                stroke="currentColor"
-                strokeWidth="1.5"
-              >
-                {/* Cluster icon: two groups of dots */}
-                <circle cx="3.5" cy="4" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="6" cy="6" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="3" cy="7" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="11" cy="10" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="13.5" cy="11.5" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="11" cy="13" r="1.5" fill="currentColor" stroke="none" />
-              </svg>
-              <span className="hidden sm:inline">Cluster</span>
+      <div className="absolute top-3 left-3 sm:top-4 sm:left-4 z-10 flex flex-col gap-1.5 sm:gap-2">
+        {/* Focus mode banner */}
+        {focusedEpicId && onExitFocusedEpic && (
+          <div className="flex items-center gap-2 px-3 py-1.5 text-xs font-medium bg-emerald-50/90 backdrop-blur-sm rounded-lg border border-emerald-200 shadow-sm text-emerald-700">
+            <svg className="w-3.5 h-3.5 text-emerald-500 flex-shrink-0" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" d="M7.5 3.75H6A2.25 2.25 0 003.75 6v1.5M16.5 3.75H18A2.25 2.25 0 0120.25 6v1.5M16.5 20.25H18A2.25 2.25 0 0020.25 18v-1.5M7.5 20.25H6A2.25 2.25 0 013.75 18v-1.5" />
+            </svg>
+            <span className="truncate max-w-[180px]">
+              Focused: <span className="font-semibold">{nodes.find((n) => n.id === focusedEpicId)?.title || focusedEpicId}</span>
             </span>
-          </button>
-          <div className="w-px bg-zinc-200" />
-          <button
-            onClick={() => setLayoutMode("spread")}
-            className={`px-3 py-1.5 text-xs font-medium transition-colors ${
-              layoutMode === "spread"
-                ? "bg-emerald-500 text-white"
-                : "text-zinc-500 hover:text-zinc-700 hover:bg-zinc-50"
-            }`}
-          >
-            <span className="flex items-center gap-1.5">
-              <svg
-                className="w-3.5 h-3.5"
-                viewBox="0 0 16 16"
-                fill="none"
-                stroke="currentColor"
-                strokeWidth="1.5"
-              >
-                {/* Spread icon: dots spread far apart */}
-                <circle cx="2" cy="2" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="14" cy="3" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="8" cy="8" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="3" cy="14" r="1.5" fill="currentColor" stroke="none" />
-                <circle cx="13" cy="13" r="1.5" fill="currentColor" stroke="none" />
+            <button
+              onClick={onExitFocusedEpic}
+              className="ml-auto p-0.5 rounded hover:bg-emerald-200/50 transition-colors flex-shrink-0"
+              title="Show full graph"
+            >
+              <svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+                <path strokeLinecap="round" strokeLinejoin="round" d="M6 18L18 6M6 6l12 12" />
               </svg>
-              <span className="hidden sm:inline">Spread</span>
-            </span>
-          </button>
-        </div>
+            </button>
+          </div>
+        )}
 
-        {/* Collapse / Expand all toggle */}
-        {(onCollapseAll || onExpandAll) && (
-          <button
-            onClick={collapsedEpicIds && collapsedEpicIds.size > 0 ? onExpandAll : onCollapseAll}
-            className="flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium bg-white/90 backdrop-blur-sm rounded-lg border border-zinc-200 shadow-sm text-zinc-500 hover:text-zinc-700 hover:bg-zinc-50 transition-colors"
-          >
-            {collapsedEpicIds && collapsedEpicIds.size > 0 ? (
-              <>
+        {/* Row 1: Layout shape controls */}
+        <div className="flex items-start gap-1.5 sm:gap-2">
+          {/* Layout mode toggle */}
+          <div className="flex bg-white/90 backdrop-blur-sm rounded-lg border border-zinc-200 shadow-sm overflow-hidden" data-tutorial="layouts">
+            <button
+              onClick={() => setLayoutMode("force")}
+              className={`px-3 py-1.5 text-xs font-medium transition-colors ${
+                layoutMode === "force"
+                  ? "bg-emerald-500 text-white"
+                  : "text-zinc-500 hover:text-zinc-700 hover:bg-zinc-50"
+              }`}
+            >
+              <span className="flex items-center gap-1.5">
                 <svg
                   className="w-3.5 h-3.5"
-                  viewBox="0 0 24 24"
+                  viewBox="0 0 16 16"
                   fill="none"
-                  strokeWidth={1.5}
                   stroke="currentColor"
+                  strokeWidth="1.5"
                 >
-                  <path
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    d="M3.75 3.75v4.5m0-4.5h4.5m-4.5 0L9 9M3.75 20.25v-4.5m0 4.5h4.5m-4.5 0L9 15M20.25 3.75h-4.5m4.5 0v4.5m0-4.5L15 9m5.25 11.25h-4.5m4.5 0v-4.5m0 4.5L15 15"
-                  />
+                  {/* Spring/force icon: scattered dots with connections */}
+                  <circle cx="4" cy="4" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="12" cy="3" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="8" cy="8" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="3" cy="12" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="13" cy="11" r="1.5" fill="currentColor" stroke="none" />
+                  <line x1="4" y1="4" x2="8" y2="8" strokeOpacity="0.5" />
+                  <line x1="12" y1="3" x2="8" y2="8" strokeOpacity="0.5" />
+                  <line x1="3" y1="12" x2="8" y2="8" strokeOpacity="0.5" />
+                  <line x1="13" y1="11" x2="8" y2="8" strokeOpacity="0.5" />
                 </svg>
-                <span className="hidden sm:inline">Expand all</span>
-              </>
-            ) : (
-              <>
+                <span className="hidden sm:inline">Force</span>
+              </span>
+            </button>
+            <div className="w-px bg-zinc-200" />
+            <button
+              onClick={() => setLayoutMode("dag")}
+              className={`px-3 py-1.5 text-xs font-medium transition-colors ${
+                layoutMode === "dag"
+                  ? "bg-emerald-500 text-white"
+                  : "text-zinc-500 hover:text-zinc-700 hover:bg-zinc-50"
+              }`}
+            >
+              <span className="flex items-center gap-1.5">
                 <svg
                   className="w-3.5 h-3.5"
-                  viewBox="0 0 24 24"
+                  viewBox="0 0 16 16"
                   fill="none"
-                  strokeWidth={1.5}
                   stroke="currentColor"
+                  strokeWidth="1.5"
                 >
-                  <path
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    d="M9 9V4.5M9 9H4.5M9 9 3.75 3.75M9 15v4.5M9 15H4.5M9 15l-5.25 5.25M15 9h4.5M15 9V4.5M15 9l5.25-5.25M15 15h4.5M15 15v4.5m0-4.5 5.25 5.25"
-                  />
+                  {/* Tree/DAG icon: top-down hierarchy */}
+                  <circle cx="8" cy="2.5" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="4" cy="8" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="12" cy="8" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="2" cy="13.5" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="6" cy="13.5" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="12" cy="13.5" r="1.5" fill="currentColor" stroke="none" />
+                  <line x1="8" y1="4" x2="4" y2="6.5" strokeOpacity="0.5" />
+                  <line x1="8" y1="4" x2="12" y2="6.5" strokeOpacity="0.5" />
+                  <line x1="4" y1="9.5" x2="2" y2="12" strokeOpacity="0.5" />
+                  <line x1="4" y1="9.5" x2="6" y2="12" strokeOpacity="0.5" />
+                  <line x1="12" y1="9.5" x2="12" y2="12" strokeOpacity="0.5" />
                 </svg>
-                <span className="hidden sm:inline">Collapse all</span>
-              </>
-            )}
+                <span className="hidden sm:inline">DAG</span>
+              </span>
+            </button>
+            <div className="w-px bg-zinc-200" />
+            <button
+              onClick={() => setLayoutMode("radial")}
+              className={`px-3 py-1.5 text-xs font-medium transition-colors ${
+                layoutMode === "radial"
+                  ? "bg-emerald-500 text-white"
+                  : "text-zinc-500 hover:text-zinc-700 hover:bg-zinc-50"
+              }`}
+            >
+              <span className="flex items-center gap-1.5">
+                <svg
+                  className="w-3.5 h-3.5"
+                  viewBox="0 0 16 16"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="1.5"
+                >
+                  {/* Radial icon: concentric rings with center dot */}
+                  <circle cx="8" cy="8" r="2" fill="currentColor" stroke="none" />
+                  <circle cx="8" cy="8" r="5" fill="none" strokeOpacity="0.5" />
+                  <circle cx="8" cy="8" r="7.5" fill="none" strokeOpacity="0.3" />
+                </svg>
+                <span className="hidden sm:inline">Radial</span>
+              </span>
+            </button>
+            <div className="w-px bg-zinc-200" />
+            <button
+              onClick={() => setLayoutMode("cluster")}
+              className={`px-3 py-1.5 text-xs font-medium transition-colors ${
+                layoutMode === "cluster"
+                  ? "bg-emerald-500 text-white"
+                  : "text-zinc-500 hover:text-zinc-700 hover:bg-zinc-50"
+              }`}
+            >
+              <span className="flex items-center gap-1.5">
+                <svg
+                  className="w-3.5 h-3.5"
+                  viewBox="0 0 16 16"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="1.5"
+                >
+                  {/* Cluster icon: two groups of dots */}
+                  <circle cx="3.5" cy="4" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="6" cy="6" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="3" cy="7" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="11" cy="10" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="13.5" cy="11.5" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="11" cy="13" r="1.5" fill="currentColor" stroke="none" />
+                </svg>
+                <span className="hidden sm:inline">Cluster</span>
+              </span>
+            </button>
+            <div className="w-px bg-zinc-200" />
+            <button
+              onClick={() => setLayoutMode("spread")}
+              className={`px-3 py-1.5 text-xs font-medium transition-colors ${
+                layoutMode === "spread"
+                  ? "bg-emerald-500 text-white"
+                  : "text-zinc-500 hover:text-zinc-700 hover:bg-zinc-50"
+              }`}
+            >
+              <span className="flex items-center gap-1.5">
+                <svg
+                  className="w-3.5 h-3.5"
+                  viewBox="0 0 16 16"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeWidth="1.5"
+                >
+                  {/* Spread icon: dots spread far apart */}
+                  <circle cx="2" cy="2" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="14" cy="3" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="8" cy="8" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="3" cy="14" r="1.5" fill="currentColor" stroke="none" />
+                  <circle cx="13" cy="13" r="1.5" fill="currentColor" stroke="none" />
+                </svg>
+                <span className="hidden sm:inline">Spread</span>
+              </span>
+            </button>
+          </div>
+        </div>
+
+        {/* Row 2: View toggles */}
+        <div className="flex items-start gap-1.5 sm:gap-2" data-tutorial="view-controls">
+          {/* Collapse / Expand all toggle */}
+          {(onCollapseAll || onExpandAll) && (
+            <button
+              onClick={collapsedEpicIds && collapsedEpicIds.size > 0 ? onExpandAll : onCollapseAll}
+              className="flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium bg-white/90 backdrop-blur-sm rounded-lg border border-zinc-200 shadow-sm text-zinc-500 hover:text-zinc-700 hover:bg-zinc-50 transition-colors"
+            >
+              {collapsedEpicIds && collapsedEpicIds.size > 0 ? (
+                <>
+                  <svg
+                    className="w-3.5 h-3.5"
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    strokeWidth={1.5}
+                    stroke="currentColor"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      d="M3.75 3.75v4.5m0-4.5h4.5m-4.5 0L9 9M3.75 20.25v-4.5m0 4.5h4.5m-4.5 0L9 15M20.25 3.75h-4.5m4.5 0v4.5m0-4.5L15 9m5.25 11.25h-4.5m4.5 0v-4.5m0 4.5L15 15"
+                    />
+                  </svg>
+                  <span className="hidden sm:inline">Expand all</span>
+                </>
+              ) : (
+                <>
+                  <svg
+                    className="w-3.5 h-3.5"
+                    viewBox="0 0 24 24"
+                    fill="none"
+                    strokeWidth={1.5}
+                    stroke="currentColor"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      d="M9 9V4.5M9 9H4.5M9 9 3.75 3.75M9 15v4.5M9 15H4.5M9 15l-5.25 5.25M15 9h4.5M15 9V4.5M15 9l5.25-5.25M15 15h4.5M15 15v4.5m0-4.5 5.25 5.25"
+                    />
+                  </svg>
+                  <span className="hidden sm:inline">Collapse all</span>
+                </>
+              )}
+            </button>
+          )}
+
+          {/* Show/hide cluster labels toggle */}
+          <button
+            onClick={() => setShowClusters((v) => !v)}
+            className={`flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium backdrop-blur-sm rounded-lg border shadow-sm transition-colors ${
+              showClusters
+                ? "bg-emerald-500 text-white border-emerald-500"
+                : "bg-white/90 text-zinc-500 border-zinc-200 hover:text-zinc-700 hover:bg-zinc-50"
+            }`}
+            title={showClusters ? "Hide cluster labels" : "Show cluster labels"}
+          >
+            <svg
+              className="w-3.5 h-3.5"
+              viewBox="0 0 16 16"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="1.5"
+            >
+              {/* Dashed circle with label lines — cluster overlay icon */}
+              <circle cx="8" cy="8" r="6" strokeDasharray="2.5 2" strokeOpacity={showClusters ? 1 : 0.5} />
+              <line x1="5" y1="8" x2="11" y2="8" strokeOpacity={showClusters ? 1 : 0.4} />
+              <line x1="6" y1="10" x2="10" y2="10" strokeOpacity={showClusters ? 0.6 : 0.25} strokeWidth="1" />
+            </svg>
+            <span className="hidden sm:inline">Clusters</span>
           </button>
-        )}
 
-        {/* Show/hide cluster labels toggle */}
-        <button
-          onClick={() => setShowClusters((v) => !v)}
-          className={`flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium backdrop-blur-sm rounded-lg border shadow-sm transition-colors ${
-            showClusters
-              ? "bg-emerald-500 text-white border-emerald-500"
-              : "bg-white/90 text-zinc-500 border-zinc-200 hover:text-zinc-700 hover:bg-zinc-50"
-          }`}
-          title={showClusters ? "Hide cluster labels" : "Show cluster labels"}
-        >
-          <svg
-            className="w-3.5 h-3.5"
-            viewBox="0 0 16 16"
-            fill="none"
-            stroke="currentColor"
-            strokeWidth="1.5"
+          {/* Auto-fit: lock/unlock automatic camera reframing */}
+          <button
+            onClick={() => onAutoFitToggle?.()}
+            className={`flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium backdrop-blur-sm rounded-lg border shadow-sm transition-colors ${
+              autoFit
+                ? "bg-emerald-500 text-white border-emerald-500"
+                : "bg-white/90 text-zinc-500 border-zinc-200 hover:text-zinc-700 hover:bg-zinc-50"
+            }`}
+            title={autoFit ? "Auto-fit enabled: camera adjusts after updates" : "Auto-fit disabled: camera stays fixed"}
           >
-            {/* Dashed circle with label lines — cluster overlay icon */}
-            <circle cx="8" cy="8" r="6" strokeDasharray="2.5 2" strokeOpacity={showClusters ? 1 : 0.5} />
-            <line x1="5" y1="8" x2="11" y2="8" strokeOpacity={showClusters ? 1 : 0.4} />
-            <line x1="6" y1="10" x2="10" y2="10" strokeOpacity={showClusters ? 0.6 : 0.25} strokeWidth="1" />
-          </svg>
-          <span className="hidden sm:inline">Clusters</span>
-        </button>
+            <svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
+              <path strokeLinecap="round" strokeLinejoin="round" d="M7.5 3.75H6A2.25 2.25 0 003.75 6v1.5M16.5 3.75H18A2.25 2.25 0 0120.25 6v1.5M20.25 16.5V18A2.25 2.25 0 0118 20.25h-1.5M3.75 16.5V18A2.25 2.25 0 006 20.25h1.5" />
+              <circle cx="12" cy="12" r="3" />
+            </svg>
+            <span className="hidden sm:inline">Auto-fit</span>
+          </button>
+
+          {/* Pulse: highlight most recently active node */}
+          <button
+            onClick={() => onShowPulseToggle?.()}
+            className={`flex items-center gap-1.5 px-3 py-1.5 text-xs font-medium backdrop-blur-sm rounded-lg border shadow-sm transition-colors ${
+              showPulse
+                ? "bg-emerald-500 text-white border-emerald-500"
+                : "bg-white/90 text-zinc-500 border-zinc-200 hover:text-zinc-700 hover:bg-zinc-50"
+            }`}
+            title={showPulse ? "Pulse enabled: ripple highlights most recent activity" : "Pulse disabled: no activity highlight"}
+          >
+            <svg className="w-3.5 h-3.5" fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
+              <circle cx="12" cy="12" r="3" />
+              <path strokeLinecap="round" strokeLinejoin="round" d="M19.07 4.93A10 10 0 014.93 19.07M4.93 4.93a10 10 0 0114.14 14.14" strokeOpacity="0.5" />
+              <path strokeLinecap="round" strokeLinejoin="round" d="M16.24 7.76a6 6 0 01.01 8.49M7.76 7.76a6 6 0 000 8.49" strokeOpacity="0.7" />
+            </svg>
+            <span className="hidden sm:inline">Pulse</span>
+          </button>
+        </div>
       </div>
 
       {/* Bottom-right info panel: stats + color mode selector + legend (hidden when timeline active) */}
       {!timelineActive && (
         <div
           className="absolute bottom-4 z-10 bg-white/90 backdrop-blur-sm rounded-lg border border-zinc-200 shadow-sm px-3 py-2 text-xs text-zinc-400 transition-[right] duration-300 ease-out"
+          data-tutorial="legend"
           style={{ right: sidebarOpen ? "calc(360px + 1rem)" : "1rem", maxWidth: 320 }}
         >
           {stats && (
@@ -2024,7 +2199,7 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
           )}
           {/* Color mode segmented control */}
           <div className="hidden sm:flex bg-zinc-100 rounded-md overflow-hidden mb-1.5">
-            {(["status", "owner", "assignee", "prefix"] as ColorMode[]).map((mode) => (
+            {(["status", "priority", "owner", "assignee", "prefix"] as ColorMode[]).map((mode) => (
               <button
                 key={mode}
                 onClick={() => onColorModeChange?.(mode)}
@@ -2038,7 +2213,7 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
               </button>
             ))}
           </div>
-          {/* Dynamic legend: status dots or person/prefix dots */}
+          {/* Dynamic legend: status/priority dots or person/prefix dots */}
           <div className="hidden sm:flex flex-wrap gap-x-3 gap-y-1 mb-1.5">
             {colorMode === "status" ? (
               <>
@@ -2052,6 +2227,18 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
                   </span>
                 ))}
               </>
+            ) : colorMode === "priority" ? (
+              <>
+                {[0, 1, 2, 3, 4].map((p) => (
+                  <span key={p} className="flex items-center gap-1">
+                    <span
+                      className="w-2 h-2 rounded-full"
+                      style={{ backgroundColor: PRIORITY_COLORS[p] }}
+                    />
+                    <span className="text-zinc-500">{PRIORITY_LABELS[p]}</span>
+                  </span>
+                ))}
+              </>
             ) : (
               <>
                 {legendItems.map(({ label, color }) => (
@@ -2079,6 +2266,7 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
       {/* Minimap — bottom-left, hidden on mobile, resizable */}
       <div
         className="hidden sm:block absolute bottom-4 left-4 z-10"
+        data-tutorial="minimap"
         style={{ width: MINIMAP_W, height: MINIMAP_H }}
       >
         <canvas
@@ -2220,6 +2408,8 @@ const BeadsGraph = forwardRef<BeadsGraphHandle, BeadsGraphProps>(function BeadsG
           onZoom={handleZoom}
           // Background
           backgroundColor="transparent"
+          // Disable auto-pause when pulse is active so canvas redraws every frame
+          autoPauseRedraw={!(showPulse && pulseNodeId)}
         />
       ) : (
         <div className="flex items-center justify-center h-full">