beads-map 0.3.4 → 0.3.6

package/components/DescriptionModal.tsx

@@ -1,29 +1,211 @@
 "use client";
 
-import { useState } from "react";
+import { useState, useCallback, useEffect, useRef } from "react";
 import { createPortal } from "react-dom";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import type { GraphNode } from "@/lib/types";
 import { buildDescriptionCopyText } from "@/lib/utils";
+import {
+  speakWithElevenLabs,
+  speakSelection,
+  stopTts,
+  pauseTts,
+  resumeTts,
+  stripMarkdown,
+  setTtsPlaybackRate,
+  type TtsState,
+} from "@/lib/tts";
+import { hasApiKey } from "@/lib/settings";
+
+const SPEED_PRESETS = [
+  { label: "Normal", value: 1 },
+  { label: "1.25x", value: 1.25 },
+  { label: "1.5x", value: 1.5 },
+  { label: "1.75x", value: 1.75 },
+  { label: "2x", value: 2 },
+];
 
 interface DescriptionModalProps {
   node: GraphNode;
   onClose: () => void;
   repoUrl?: string;
+  onOpenSettings?: () => void;
 }
 
-export function DescriptionModal({ node, onClose, repoUrl }: DescriptionModalProps) {
+export function DescriptionModal({
+  node,
+  onClose,
+  repoUrl,
+  onOpenSettings,
+}: DescriptionModalProps) {
   const [copied, setCopied] = useState(false);
+  const [ttsState, setTtsState] = useState<TtsState>("idle");
+  const [ttsError, setTtsError] = useState<string | null>(null);
+  const [ttsSpeed, setTtsSpeedState] = useState(1);
+  const [speedMenuOpen, setSpeedMenuOpen] = useState(false);
+  const [customSpeedInput, setCustomSpeedInput] = useState("");
+  const [showCustomInput, setShowCustomInput] = useState(false);
+  const speedBtnRef = useRef<HTMLButtonElement>(null);
+  const speedMenuRef = useRef<HTMLDivElement>(null);
+
+  // Selection tooltip state
+  const [selectionTooltip, setSelectionTooltip] = useState<{
+    text: string;
+    x: number;
+    y: number;
+  } | null>(null);
+  const selectionTooltipRef = useRef<HTMLDivElement>(null);
+  // Guard: when true, selectionchange listener won't clear the tooltip
+  // (prevents race where clicking the tooltip clears browser selection before handler runs)
+  const ttsStartingRef = useRef(false);
 
   const handleCopy = () => {
     if (!node.description) return;
-    navigator.clipboard.writeText(buildDescriptionCopyText(node, repoUrl)).then(() => {
-      setCopied(true);
-      setTimeout(() => setCopied(false), 1500);
-    });
+    navigator.clipboard
+      .writeText(buildDescriptionCopyText(node, repoUrl))
+      .then(() => {
+        setCopied(true);
+        setTimeout(() => setCopied(false), 1500);
+      });
   };
 
+  // --- TTS handlers -------------------------------------------------------
+
+  const ttsStateChange = useCallback((state: TtsState, error?: string) => {
+    setTtsState(state);
+    if (error) setTtsError(error);
+  }, []);
+
+  const handleTts = useCallback(() => {
+    if (!hasApiKey()) {
+      onOpenSettings?.();
+      return;
+    }
+    const plainText = stripMarkdown(node.description || "");
+    if (!plainText) return;
+    setTtsError(null);
+    speakWithElevenLabs(plainText, ttsStateChange);
+  }, [node.description, onOpenSettings, ttsStateChange]);
+
+  const handleStopTts = useCallback(() => {
+    stopTts();
+    setTtsState("idle");
+    setSpeedMenuOpen(false);
+    setShowCustomInput(false);
+  }, []);
+
+  const handlePauseTts = useCallback(() => {
+    pauseTts();
+    setTtsState("paused");
+  }, []);
+
+  const handleResumeTts = useCallback(() => {
+    resumeTts();
+    setTtsState("playing");
+  }, []);
+
+  const handleSpeedChange = useCallback((speed: number) => {
+    const clamped = Math.max(0.25, Math.min(4, speed));
+    setTtsSpeedState(clamped);
+    setTtsPlaybackRate(clamped);
+    setSpeedMenuOpen(false);
+    setShowCustomInput(false);
+  }, []);
+
+  // Apply speed when playback starts (carries over from previous session)
+  useEffect(() => {
+    if (ttsState === "playing") {
+      setTtsPlaybackRate(ttsSpeed);
+    }
+  }, [ttsState, ttsSpeed]);
+
+  // Click-outside handler for speed menu
+  useEffect(() => {
+    if (!speedMenuOpen) return;
+    const handler = (e: MouseEvent) => {
+      if (
+        speedMenuRef.current && !speedMenuRef.current.contains(e.target as Node) &&
+        speedBtnRef.current && !speedBtnRef.current.contains(e.target as Node)
+      ) {
+        setSpeedMenuOpen(false);
+        setShowCustomInput(false);
+      }
+    };
+    const timer = setTimeout(() => window.addEventListener("mousedown", handler), 50);
+    return () => {
+      clearTimeout(timer);
+      window.removeEventListener("mousedown", handler);
+    };
+  }, [speedMenuOpen]);
+
+  // --- Selection tooltip handlers -----------------------------------------
+
+  const handleSelectionMouseUp = useCallback(() => {
+    // Small delay to let the browser finalize the selection
+    setTimeout(() => {
+      const sel = window.getSelection();
+      if (!sel || sel.isCollapsed) return;
+      const selectedText = sel.toString().trim();
+      if (selectedText.length < 3) return;
+      try {
+        const range = sel.getRangeAt(0);
+        const rect = range.getBoundingClientRect();
+        setSelectionTooltip({
+          text: selectedText,
+          x: rect.left + rect.width / 2,
+          y: rect.top - 8,
+        });
+      } catch {
+        // getRangeAt can throw if selection is weird
+      }
+    }, 10);
+  }, []);
+
+  // Clear tooltip when selection is lost (guarded during TTS initiation)
+  useEffect(() => {
+    const handler = () => {
+      if (ttsStartingRef.current) return;
+      const sel = window.getSelection();
+      if (!sel || sel.isCollapsed || !sel.toString().trim()) {
+        setSelectionTooltip(null);
+      }
+    };
+    document.addEventListener("selectionchange", handler);
+    return () => document.removeEventListener("selectionchange", handler);
+  }, []);
+
+  const handleSelectionTts = useCallback(() => {
+    if (!selectionTooltip) return;
+    const text = selectionTooltip.text;
+    if (!text.trim()) return;
+
+    if (!hasApiKey()) {
+      onOpenSettings?.();
+      setSelectionTooltip(null);
+      return;
+    }
+
+    ttsStartingRef.current = true; // Guard against selectionchange race
+    setTtsError(null);
+    setSelectionTooltip(null);
+
+    // speakSelection() checks cache first — zero API call if full text was played
+    speakSelection(text, ttsStateChange);
+
+    // Release guard after a tick (React state updates are batched)
+    setTimeout(() => { ttsStartingRef.current = false; }, 100);
+  }, [selectionTooltip, onOpenSettings, ttsStateChange]);
+
+  // Stop TTS on unmount / modal close
+  useEffect(() => {
+    return () => {
+      stopTts();
+      setSpeedMenuOpen(false);
+      setSelectionTooltip(null);
+    };
+  }, []);
+
   if (!node.description) return null;
 
   return createPortal(
@@ -46,21 +228,270 @@ export function DescriptionModal({ node, onClose, repoUrl }: DescriptionModalPro
             </span>
           </div>
           <div className="flex items-center gap-1 shrink-0">
+            {/* Copy button */}
             <button
               onClick={handleCopy}
               className="p-1 text-zinc-400 hover:text-zinc-600 transition-colors"
               title="Copy description"
             >
               {copied ? (
-                <svg className="w-4 h-4 text-emerald-500" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={2}>
-                  <path strokeLinecap="round" strokeLinejoin="round" d="M4.5 12.75l6 6 9-13.5" />
+                <svg
+                  className="w-4 h-4 text-emerald-500"
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                  strokeWidth={2}
+                >
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    d="M4.5 12.75l6 6 9-13.5"
+                  />
                 </svg>
               ) : (
-                <svg className="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24" strokeWidth={2}>
-                  <path strokeLinecap="round" strokeLinejoin="round" d="M15.666 3.888A2.25 2.25 0 0 0 13.5 2.25h-3c-1.03 0-1.9.693-2.166 1.638m7.332 0c.055.194.084.4.084.612v0a.75.75 0 0 1-.75.75H9.75a.75.75 0 0 1-.75-.75v0c0-.212.03-.418.084-.612m7.332 0c.646.049 1.288.11 1.927.184 1.1.128 1.907 1.077 1.907 2.185V19.5a2.25 2.25 0 0 1-2.25 2.25H6.75A2.25 2.25 0 0 1 4.5 19.5V6.257c0-1.108.806-2.057 1.907-2.185a48.208 48.208 0 0 1 1.927-.184" />
+                <svg
+                  className="w-4 h-4"
+                  fill="none"
+                  stroke="currentColor"
+                  viewBox="0 0 24 24"
+                  strokeWidth={2}
+                >
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    d="M15.666 3.888A2.25 2.25 0 0 0 13.5 2.25h-3c-1.03 0-1.9.693-2.166 1.638m7.332 0c.055.194.084.4.084.612v0a.75.75 0 0 1-.75.75H9.75a.75.75 0 0 1-.75-.75v0c0-.212.03-.418.084-.612m7.332 0c.646.049 1.288.11 1.927.184 1.1.128 1.907 1.077 1.907 2.185V19.5a2.25 2.25 0 0 1-2.25 2.25H6.75A2.25 2.25 0 0 1 4.5 19.5V6.257c0-1.108.806-2.057 1.907-2.185a48.208 48.208 0 0 1 1.927-.184"
+                  />
                 </svg>
               )}
             </button>
+
+            {/* TTS buttons — 4 states: idle, loading, playing, paused */}
+            {ttsState === "loading" ? (
+              <button
+                disabled
+                className="p-1 text-zinc-300 cursor-wait"
+                title="Loading audio..."
+              >
+                <svg
+                  className="w-4 h-4 animate-spin"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                >
+                  <circle
+                    className="opacity-25"
+                    cx="12"
+                    cy="12"
+                    r="10"
+                    stroke="currentColor"
+                    strokeWidth={4}
+                  />
+                  <path
+                    className="opacity-75"
+                    fill="currentColor"
+                    d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+                  />
+                </svg>
+              </button>
+            ) : ttsState === "playing" ? (
+              <>
+                {/* Pause button */}
+                <button
+                  onClick={handlePauseTts}
+                  className="p-1 text-emerald-500 hover:text-amber-500 hover:bg-amber-50 rounded transition-colors"
+                  title="Pause"
+                >
+                  <svg
+                    className="w-4 h-4"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    strokeWidth={1.5}
+                    stroke="currentColor"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      d="M15.75 5.25v13.5m-7.5-13.5v13.5"
+                    />
+                  </svg>
+                </button>
+                {/* Stop button */}
+                <button
+                  onClick={handleStopTts}
+                  className="p-1 text-zinc-400 hover:text-red-500 hover:bg-red-50 rounded transition-colors"
+                  title="Stop"
+                >
+                  <svg
+                    className="w-4 h-4"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    strokeWidth={1.5}
+                    stroke="currentColor"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      d="M5.25 7.5A2.25 2.25 0 017.5 5.25h9a2.25 2.25 0 012.25 2.25v9a2.25 2.25 0 01-2.25 2.25h-9a2.25 2.25 0 01-2.25-2.25v-9z"
+                    />
+                  </svg>
+                </button>
+              </>
+            ) : ttsState === "paused" ? (
+              <>
+                {/* Resume button */}
+                <button
+                  onClick={handleResumeTts}
+                  className="p-1 text-amber-500 hover:text-emerald-500 hover:bg-emerald-50 rounded transition-colors"
+                  title="Resume"
+                >
+                  <svg
+                    className="w-4 h-4"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    strokeWidth={1.5}
+                    stroke="currentColor"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      d="M5.25 5.653c0-.856.917-1.398 1.667-.986l11.54 6.347a1.125 1.125 0 010 1.972l-11.54 6.347a1.125 1.125 0 01-1.667-.986V5.653z"
+                    />
+                  </svg>
+                </button>
+                {/* Stop button */}
+                <button
+                  onClick={handleStopTts}
+                  className="p-1 text-zinc-400 hover:text-red-500 hover:bg-red-50 rounded transition-colors"
+                  title="Stop"
+                >
+                  <svg
+                    className="w-4 h-4"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    strokeWidth={1.5}
+                    stroke="currentColor"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      d="M5.25 7.5A2.25 2.25 0 017.5 5.25h9a2.25 2.25 0 012.25 2.25v9a2.25 2.25 0 01-2.25 2.25h-9a2.25 2.25 0 01-2.25-2.25v-9z"
+                    />
+                  </svg>
+                </button>
+              </>
+            ) : (
+              /* Idle — play/speaker button */
+              <button
+                onClick={handleTts}
+                className="p-1 text-zinc-400 hover:text-zinc-600 transition-colors"
+                title="Read aloud"
+              >
+                <svg
+                  className="w-4 h-4"
+                  fill="none"
+                  viewBox="0 0 24 24"
+                  strokeWidth={1.5}
+                  stroke="currentColor"
+                >
+                  <path
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                    d="M19.114 5.636a9 9 0 010 12.728M16.463 8.288a5.25 5.25 0 010 7.424M6.75 8.25l4.72-4.72a.75.75 0 011.28.53v15.88a.75.75 0 01-1.28.53l-4.72-4.72H4.51c-.88 0-1.704-.507-1.938-1.354A9.009 9.009 0 012.25 12c0-.83.112-1.633.322-2.396C2.806 8.756 3.63 8.25 4.51 8.25H6.75z"
+                  />
+                </svg>
+              </button>
+            )}
+
+            {/* Speed selector — visible during playback/loading/paused */}
+            {(ttsState === "playing" || ttsState === "loading" || ttsState === "paused") && (
+              <div className="relative">
+                <button
+                  ref={speedBtnRef}
+                  onClick={() => setSpeedMenuOpen((v) => !v)}
+                  className="px-1.5 py-0.5 text-[11px] font-mono font-medium rounded text-zinc-500 hover:text-zinc-700 hover:bg-zinc-100 transition-colors"
+                  title="Playback speed"
+                >
+                  {ttsSpeed === 1 ? "1x" : `${ttsSpeed}x`}
+                </button>
+
+                {speedMenuOpen && (
+                  <div
+                    ref={speedMenuRef}
+                    className="absolute right-0 top-full mt-1 bg-white border border-zinc-200 rounded-lg shadow-lg overflow-hidden z-[110]"
+                    style={{ minWidth: 150 }}
+                    onClick={(e) => e.stopPropagation()}
+                  >
+                    {SPEED_PRESETS.map((preset) => (
+                      <button
+                        key={preset.value}
+                        onClick={() => handleSpeedChange(preset.value)}
+                        className={`w-full px-3 py-2 text-xs text-left flex items-center justify-between hover:bg-zinc-50 transition-colors ${
+                          ttsSpeed === preset.value ? "text-emerald-600 font-medium" : "text-zinc-700"
+                        }`}
+                      >
+                        <span>{preset.label}</span>
+                        {ttsSpeed === preset.value && (
+                          <svg className="w-3.5 h-3.5 text-emerald-500" fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
+                            <path strokeLinecap="round" strokeLinejoin="round" d="M4.5 12.75l6 6 9-13.5" />
+                          </svg>
+                        )}
+                      </button>
+                    ))}
+
+                    <div className="border-t border-zinc-100" />
+
+                    {!showCustomInput ? (
+                      <button
+                        onClick={() => {
+                          setShowCustomInput(true);
+                          setCustomSpeedInput(String(ttsSpeed));
+                        }}
+                        className={`w-full px-3 py-2 text-xs text-left flex items-center justify-between hover:bg-zinc-50 transition-colors ${
+                          !SPEED_PRESETS.some((p) => p.value === ttsSpeed) ? "text-emerald-600 font-medium" : "text-zinc-700"
+                        }`}
+                      >
+                        <span>Custom{!SPEED_PRESETS.some((p) => p.value === ttsSpeed) ? ` (${ttsSpeed}x)` : "..."}</span>
+                        {!SPEED_PRESETS.some((p) => p.value === ttsSpeed) && (
+                          <svg className="w-3.5 h-3.5 text-emerald-500" fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
+                            <path strokeLinecap="round" strokeLinejoin="round" d="M4.5 12.75l6 6 9-13.5" />
+                          </svg>
+                        )}
+                      </button>
+                    ) : (
+                      <div className="px-3 py-2 flex items-center gap-2">
+                        <input
+                          type="number"
+                          min={0.25}
+                          max={4}
+                          step={0.25}
+                          value={customSpeedInput}
+                          onChange={(e) => setCustomSpeedInput(e.target.value)}
+                          onKeyDown={(e) => {
+                            if (e.key === "Enter") {
+                              const val = parseFloat(customSpeedInput);
+                              if (!isNaN(val) && val >= 0.25 && val <= 4) handleSpeedChange(val);
+                            }
+                            if (e.key === "Escape") {
+                              setShowCustomInput(false);
+                              setSpeedMenuOpen(false);
+                            }
+                          }}
+                          onBlur={() => {
+                            const val = parseFloat(customSpeedInput);
+                            if (!isNaN(val) && val >= 0.25 && val <= 4) handleSpeedChange(val);
+                            else setShowCustomInput(false);
+                          }}
+                          autoFocus
+                          className="w-16 rounded border border-zinc-200 bg-zinc-50 px-2 py-1 text-xs text-zinc-900 focus:outline-none focus:ring-1 focus:ring-emerald-500"
+                        />
+                        <span className="text-[11px] text-zinc-400">x</span>
+                      </div>
+                    )}
+                  </div>
+                )}
+              </div>
+            )}
+
+            {/* Close button */}
             <button
               onClick={onClose}
               className="p-1 text-zinc-400 hover:text-zinc-600 transition-colors"
@@ -81,13 +512,78 @@ export function DescriptionModal({ node, onClose, repoUrl }: DescriptionModalPro
             </button>
           </div>
         </div>
+
+        {/* TTS error banner */}
+        {ttsError && (
+          <div className="px-5 py-2 text-xs text-red-500 bg-red-50 border-b border-red-100 flex items-center justify-between">
+            <span>{ttsError}</span>
+            <button
+              onClick={() => setTtsError(null)}
+              className="text-red-400 hover:text-red-600 ml-2"
+            >
+              <svg
+                className="w-3 h-3"
+                fill="none"
+                viewBox="0 0 24 24"
+                strokeWidth={2}
+                stroke="currentColor"
+              >
+                <path
+                  strokeLinecap="round"
+                  strokeLinejoin="round"
+                  d="M6 18L18 6M6 6l12 12"
+                />
+              </svg>
+            </button>
+          </div>
+        )}
+
         {/* Modal body */}
-        <div className="flex-1 overflow-y-auto px-5 py-4 custom-scrollbar description-markdown text-sm text-zinc-700 leading-relaxed">
+        <div
+          className="flex-1 overflow-y-auto px-5 py-4 custom-scrollbar description-markdown text-sm text-zinc-700 leading-relaxed"
+          onMouseUp={handleSelectionMouseUp}
+        >
           <ReactMarkdown remarkPlugins={[remarkGfm]}>
             {node.description}
           </ReactMarkdown>
         </div>
       </div>
+
+      {/* Selection TTS tooltip — outside modal card, inside portal backdrop */}
+      {selectionTooltip && (
+        <div
+          ref={selectionTooltipRef}
+          className="fixed z-[110] flex items-center gap-1.5 px-2.5 py-1.5 bg-zinc-800 text-white text-xs rounded-lg shadow-lg select-none"
+          style={{
+            left: selectionTooltip.x,
+            top: selectionTooltip.y,
+            transform: "translate(-50%, -100%)",
+            pointerEvents: "auto",
+          }}
+          onMouseDown={(e) => e.stopPropagation()}
+          onClick={(e) => e.stopPropagation()}
+        >
+          <button
+            onClick={handleSelectionTts}
+            className="flex items-center gap-1 hover:text-emerald-300 transition-colors"
+          >
+            <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="M19.114 5.636a9 9 0 010 12.728M16.463 8.288a5.25 5.25 0 010 7.424M6.75 8.25l4.72-4.72a.75.75 0 011.28.53v15.88a.75.75 0 01-1.28.53l-4.72-4.72H4.51c-.88 0-1.704-.507-1.938-1.354A9.009 9.009 0 012.25 12c0-.83.112-1.633.322-2.396C2.806 8.756 3.63 8.25 4.51 8.25H6.75z"
+              />
+            </svg>
+            <span>Read aloud</span>
+          </button>
+        </div>
+      )}
     </div>,
     document.body
   );

package/components/HelpPanel.tsx

@@ -268,7 +268,7 @@ function HelpContent({ onStartTutorial }: { onStartTutorial?: () => void }) {
       <ul className="space-y-1.5 mb-3">
         <Bullet color={CAT.blue}><strong>Click</strong> a node to open its details</Bullet>
         <Bullet color={CAT.blue}><strong>Hover</strong> for a quick summary</Bullet>
-        <Bullet color={CAT.blue}><strong>Right-click</strong> for actions &mdash; descriptions, comments, claims, collapse</Bullet>
+        <Bullet color={CAT.blue}><strong>Right-click</strong> for actions &mdash; descriptions, comments, claims, collapse, or focus on an epic</Bullet>
         <Bullet color={CAT.blue}><strong>Scroll</strong> to zoom, <strong>drag</strong> to pan</Bullet>
         <Bullet color={CAT.blue}><strong>Cmd/Ctrl+F</strong> to search by name, ID, owner, or commenter</Bullet>
       </ul>
@@ -300,12 +300,15 @@ function HelpContent({ onStartTutorial }: { onStartTutorial?: () => void }) {
       <SectionTitle color={CAT.mauve}>More</SectionTitle>
       <ul className="space-y-1.5 mb-3">
         <Bullet color={CAT.mauve}><strong>Collapse/Expand</strong> &mdash; tidy up epics into single nodes</Bullet>
+        <Bullet color={CAT.mauve}><strong>Focus on epic</strong> &mdash; right-click an epic to isolate its subgraph (children + dependencies). Click the banner or right-click again to return</Bullet>
         <Bullet color={CAT.mauve}><strong>Clusters</strong> &mdash; dashed circles grouping projects when zoomed out</Bullet>
         <Bullet color={CAT.mauve}><strong>Replay</strong> &mdash; step through your project&apos;s history</Bullet>
         <Bullet color={CAT.mauve}><strong>Comments</strong> &mdash; leave notes on tasks (sign in first)</Bullet>
+        <Bullet color={CAT.mauve}><strong>Activity feed</strong> &mdash; real-time feed filtered to only your local beads, not global</Bullet>
         <Bullet color={CAT.mauve}><strong>Claim tasks</strong> &mdash; right-click to mark as yours</Bullet>
         <Bullet color={CAT.mauve}><strong>Minimap</strong> &mdash; click to jump, drag edges to resize</Bullet>
         <Bullet color={CAT.mauve}><strong>Auto-fit</strong> &mdash; top-left toggle to lock/unlock automatic camera reframing</Bullet>
+        <Bullet color={CAT.mauve}><strong>Pulse</strong> &mdash; the most recently active node pulses with emerald ripples. Toggle it on/off in view controls</Bullet>
         <Bullet color={CAT.mauve}><strong>Copy</strong> &mdash; clipboard icon copies task with project info</Bullet>
       </ul>
 

package/components/NodeDetail.tsx

@@ -30,6 +30,7 @@ interface NodeDetailProps {
   isAuthenticated?: boolean;
   currentDid?: string;
   repoUrls?: Record<string, string>;
+  onOpenSettings?: () => void;
 }
 
 export default function NodeDetail({
@@ -44,6 +45,7 @@ export default function NodeDetail({
   isAuthenticated,
   currentDid,
   repoUrls,
+  onOpenSettings,
 }: NodeDetailProps) {
   // Reply state — managed here so it's shared across the comment tree
   const [replyingToUri, setReplyingToUri] = useState<string | null>(null);
@@ -356,7 +358,7 @@ export default function NodeDetail({
 
       {/* Description expanded modal */}
       {descriptionExpanded && node.description && (
-        <DescriptionModal node={node} onClose={() => setDescriptionExpanded(false)} repoUrl={repoUrls?.[node.prefix]} />
+        <DescriptionModal node={node} onClose={() => setDescriptionExpanded(false)} repoUrl={repoUrls?.[node.prefix]} onOpenSettings={onOpenSettings} />
       )}
 
       {/* Blocks (issues this blocks) */}