ui/src/components/ExploreView.jsx

/**
 * ExploreView.jsx — Interactive Codebase Tour.
 *
 * ═══════════════════════════════════════════════════════════════
 * WHAT THIS SHOWS
 * ═══════════════════════════════════════════════════════════════
 *
 * Instead of a raw scatter plot of files, this view teaches a student
 * HOW to approach a new codebase. The LLM generates 6-8 key concepts —
 * the ideas a student must understand — and their dependencies, then
 * renders them as an interactive node diagram:
 *
 *   [Value class] → [Forward Pass] → [Backward Pass] → [Loss + SGD]
 *                ↘ [MLP layer]   ↗
 *
 * Each node = a card you can click to expand. Arrows mean "you need
 * to understand X before Y". Reading order is encoded as numbered badges.
 *
 * ═══════════════════════════════════════════════════════════════
 * LAYOUT ALGORITHM
 * ═══════════════════════════════════════════════════════════════
 *
 * 1. Topological sort: assign each concept a column depth
 *    (longest dependency chain from a root node).
 * 2. Within each column, sort by reading_order.
 * 3. Center columns vertically relative to the tallest column.
 * 4. Draw bezier arrows between connected cards.
 *
 * ═══════════════════════════════════════════════════════════════
 * INTERACTIONS
 * ═══════════════════════════════════════════════════════════════
 *
 *   Click card  → expand description + key methods
 *   Hover card  → highlight its edges + connected nodes, dim others
 *   Ask button  → pre-fills chat with a targeted question
 *   Scroll      → zoom (non-passive wheel so preventDefault works)
 *   Drag        → pan the canvas
 */

import { useEffect, useRef, useState, useCallback } from "react";
import { streamTour } from "../api";
import TourStory from "./TourStory";

// Module-level cache — survives tab switches because ExploreView is unmounted
// when the user navigates to Architecture/Class tabs and remounted on return.
// Without this, switching to Explore re-fetches (and re-generates) every time.
// Key: repo slug → tour data object
const tourCache = {};

// localStorage key for a given repo's tour.
// We persist tour data across page refreshes so the backend (and LLM quota)
// is only hit once per repo, not on every refresh.
function tourLsKey(repo) { return `ghrc_tour_${repo.replace(/\//g, "_")}`; }

// ── Type → visual token ───────────────────────────────────────────────────────
// Each concept type maps to a hue from a different part of the spectrum so
// they're immediately legible even at small sizes. Four clearly-distinct hues:
// blue (class), amber (function), violet (module), emerald (algorithm).
const TYPE_STYLE = {
  class:     { border: "#5B8FF9", glow: "rgba(91,143,249,0.38)",  dot: "#7DABFF", tag: "class"  }, // blue   240°
  function:  { border: "#FBBF24", glow: "rgba(251,191,36,0.32)",  dot: "#FCD34D", tag: "fn"     }, // amber   45°
  module:    { border: "#A78BFA", glow: "rgba(167,139,250,0.32)", dot: "#C4B5FD", tag: "module" }, // violet 270°
  algorithm: { border: "#34D399", glow: "rgba(52,211,153,0.32)",  dot: "#6EE7B7", tag: "algo"   }, // emerald 160°
};
const FALLBACK_STYLE = { border: "#4E5E80", glow: "rgba(78,94,128,0.30)", dot: "#8896B8", tag: "?" };

function styleFor(type) {
  return TYPE_STYLE[type] || FALLBACK_STYLE;
}

// ── Card geometry ─────────────────────────────────────────────────────────────
// Cards no longer grow on click (description moved to Story mode). The
// at-rest size covers name + subtitle + file + ask button only — key
// items and the "Builds on" row are revealed on hover via CSS max-height
// transitions. Hovering a card expands it AND its dependency neighbours
// (so context shows up alongside the focal concept). The lower rows are
// pushed down by EXPANSION_H below to keep the expansion from clipping
// into them.
const CARD_W      = 220;  // card width in canvas px
const CARD_H      = 142;  // at-rest card height
const COL_GAP     = 100;  // horizontal gap between cards in the same row
const ROW_GAP     = 72;   // vertical gap between rows
// Approximate height the card grows when hovered (key items row + builds-on
// row + paddings). Used to offset rows below a hovered card so the expansion
// has room to land. Slightly conservative — under-shooting causes overlap,
// over-shooting wastes a bit of vertical canvas during the hover.
const EXPANSION_H = 180;

// How many concepts appear in each horizontal row.
// With 12 concepts and PER_ROW=4: 3 rows of 4, reads like a book.
const PER_ROW = 4;

// ── Layout: row-major reading order ───────────────────────────────────────────
// Concepts are placed left-to-right by reading_order, wrapping to the next row
// after PER_ROW concepts — exactly like reading text.
//
//   1 → 2 → 3 → 4
//   ↓
//   5 → 6 → 7 → 8
//   ↓
//   9 → 10 → 11 → 12
//
// This avoids the "spreadsheet" feel of column-major layouts where the eye
// must scan down a column then jump back to the top of the next column.
function computeLayout(concepts) {
  if (!concepts.length) return {};

  const sorted = [...concepts].sort((a, b) =>
    (a.reading_order ?? 999) - (b.reading_order ?? 999)
  );

  const positions = {};
  sorted.forEach((c, i) => {
    const row = Math.floor(i / PER_ROW);
    const col = i % PER_ROW;
    positions[c.id] = {
      x: col * (CARD_W + COL_GAP) + 48,
      y: row * (CARD_H + ROW_GAP) + 48,
    };
  });
  return positions;
}

// ── Arrow: cubic bezier between source and target ─────────────────────────────
// Normally left-to-right (right edge → left edge). If the dependency arrow
// goes backwards (prerequisite placed to the right due to reading_order layout),
// flip to exit from the left edge and enter the right edge instead.
function bezierPath(fromPos, toPos) {
  const fromCenterX = fromPos.x + CARD_W / 2;
  const toCenterX   = toPos.x   + CARD_W / 2;
  const leftToRight = toCenterX >= fromCenterX;

  const x1 = leftToRight ? fromPos.x + CARD_W : fromPos.x;
  const y1 = fromPos.y + CARD_H / 2;
  const x2 = leftToRight ? toPos.x             : toPos.x + CARD_W;
  const y2 = toPos.y + CARD_H / 2;

  const tension = Math.max(Math.abs(x2 - x1) * 0.55, 60);
  const dir = leftToRight ? 1 : -1;
  return `M ${x1} ${y1} C ${x1 + dir * tension} ${y1}, ${x2 - dir * tension} ${y2}, ${x2} ${y2}`;
}

// ── ConceptCard ────────────────────────────────────────────────────────────────
//
// Canvas cards used to embed the full description here when selected, which
// duplicated content with Story mode. The split now is:
//   • Canvas cards = relational view: name, file, key items, what this
//     depends on. A clicked card jumps the viewer to Story mode for the
//     deeper read.
//   • Story mode = the reader: long-form description, code link, depends-on
//     pills with cross-references.
// Each view does one job well; we no longer maintain the same prose in two
// places.
function ConceptCard({
  concept, visualNum, isEntry, isHovered, isDimmed, pos,
  onOpenStory, onHover, onAsk, onDragStart, wasDragged,
  dependsOnNames,  // [{id, name}] — resolved neighbours for the "Connects to" row
}) {
  const s = styleFor(concept.type);

  return (
    <div
      className={`ec-card${isHovered ? " ec-hover" : ""}${isDimmed ? " ec-dimmed" : ""}`}
      style={{
        position: "absolute",
        zIndex: isHovered ? 10 : 1,
        left: pos.x,
        top: pos.y,
        width: CARD_W,
        cursor: "grab",
        borderColor: isHovered ? s.border : undefined,
        boxShadow: isHovered
          ? `0 0 0 2px ${s.border}, 0 0 20px ${s.glow.replace(/[\d.]+\)$/, '0.60)')}, 0 20px 60px ${s.glow.replace(/[\d.]+\)$/, '0.45)')}`
          : undefined,
      }}
      onMouseDown={(e) => onDragStart?.(e, concept, pos)}
      onClick={() => { if (!wasDragged?.current) onOpenStory(concept.id); }}
      onMouseEnter={() => onHover(concept.id)}
      onMouseLeave={() => onHover(null)}
    >
      {/* Top row: reading order badge + type tag */}
      <div className="ec-card-top">
        <div style={{ display: "flex", alignItems: "center", gap: 6 }}>
          <span className="ec-order">{visualNum ?? concept.reading_order}</span>
          {isEntry && <span className="ec-entry-tag">Start here</span>}
        </div>
        <span className="ec-type-tag" style={{ color: s.dot, borderColor: `${s.dot}44` }}>
          {s.tag}
        </span>
      </div>

      {/* Name + subtitle */}
      <div className="ec-name">{concept.name}</div>
      <div className="ec-subtitle">{concept.subtitle}</div>

      {/* File pill */}
      <div className="ec-file">
        <svg width="10" height="10" viewBox="0 0 16 16" fill="currentColor" style={{ opacity: 0.5, flexShrink: 0 }}>
          <path d="M2 1.75C2 .784 2.784 0 3.75 0h6.586c.464 0 .909.184 1.237.513l2.914 2.914c.329.328.513.773.513 1.237v9.586A1.75 1.75 0 0 1 13.25 16h-9.5A1.75 1.75 0 0 1 2 14.25Zm1.75-.25a.25.25 0 0 0-.25.25v12.5c0 .138.112.25.25.25h9.5a.25.25 0 0 0 .25-.25V6h-2.75A1.75 1.75 0 0 1 8.75 4.25V1.5Zm6.75.56v2.19c0 .138.112.25.25.25h2.19Z"/>
        </svg>
        {concept.file}
      </div>

      {/* Key items — always visible. These are the named methods/functions
          inside the concept, the relational hook readers care about most
          when scanning the canvas ("what's IN this thing?"). */}
      {concept.key_items?.length > 0 && (
        <div className="ec-items">
          {concept.key_items.slice(0, 4).map(item => (
            <code key={item} className="ec-item">{item}</code>
          ))}
          {concept.key_items.length > 4 && (
            <span className="ec-item-more">+{concept.key_items.length - 4}</span>
          )}
        </div>
      )}

      {/* Connects to — surfaces the dependency edges as readable text so
          users can scan a card and see where exploration leads next without
          tracing arrows visually. Mirrors the depends_on data already used
          to draw the blue connection arrows on the canvas. */}
      {dependsOnNames?.length > 0 && (
        <div className="ec-connects">
          <span className="ec-connects-label">Builds on</span>
          <div className="ec-connects-list">
            {dependsOnNames.slice(0, 3).map(d => (
              <span key={d.id} className="ec-connects-item">{d.name}</span>
            ))}
            {dependsOnNames.length > 3 && (
              <span className="ec-connects-more">+{dependsOnNames.length - 3}</span>
            )}
          </div>
        </div>
      )}

      {/* Ask button — separate path from "Read in Story" (card body click).
          Story = read; Ask = converse. Two intents, two affordances. */}
      <button
        className="ec-ask"
        onClick={e => { e.stopPropagation(); onAsk(concept); }}
      >
        Ask about this →
      </button>
    </div>
  );
}

// ── TracePanel — live log of agent investigation steps ─────────────────────────
// Each entry in `log` is the "trace" payload from a TourAgent SSE event:
//   { type: "info"|"thinking"|"found"|"file"|"finding"|"react", text, name?, stages? }
//
// "react" entries come from the agentic Phase 1 ReAct loop — they show the
// THINK → TOOL → RESULT cycle that the agent uses to explore the codebase.
// Showing this live demonstrates how agentic AI works: the model reasons about
// what to read next, calls a tool, reads the result, and decides where to go.
//
// WHY SHOW THIS: transparency builds trust. When users see "Investigating:
// retrieval/hybrid_search.py" they understand WHY that concept appears in
// the tour — it was specifically investigated, not guessed from a keyword scan.
function TracePanel({ log, open, onToggle }) {
  const bodyRef = useRef(null);

  // Auto-scroll to bottom as new lines arrive
  useEffect(() => {
    if (open && bodyRef.current) {
      bodyRef.current.scrollTop = bodyRef.current.scrollHeight;
    }
  }, [log, open]);

  const ICONS = {
    // ReAct loop step — tool icon (wrench) to distinguish from investigation steps
    react: (
      <svg viewBox="0 0 16 16" fill="currentColor" width="12" height="12">
        <path d="M13.371 2.629a3.5 3.5 0 0 0-4.849 4.274L2.78 12.745a1.5 1.5 0 1 0 2.121 2.121l5.842-5.742a3.5 3.5 0 0 0 2.628-6.495zm-1.414 3.536a1.5 1.5 0 1 1-2.121-2.122 1.5 1.5 0 0 1 2.121 2.122z"/>
      </svg>
    ),
    thinking: (
      <svg viewBox="0 0 16 16" fill="currentColor" width="12" height="12">
        <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0zm.93 6.588-2.29.287-.082.38.45.083c.294.07.352.176.288.469l-.738 3.468c-.194.897.105 1.319.808 1.319.545 0 1.178-.252 1.465-.598l.088-.416c-.2.176-.492.246-.686.246-.275 0-.375-.193-.304-.533zM8 5.5a1 1 0 1 0 0-2 1 1 0 0 0 0 2z"/>
      </svg>
    ),
    found: (
      <svg viewBox="0 0 16 16" fill="currentColor" width="12" height="12">
        <path d="M13.854 3.646a.5.5 0 0 1 0 .708l-7 7a.5.5 0 0 1-.708 0l-3.5-3.5a.5.5 0 1 1 .708-.708L6.5 10.293l6.646-6.647a.5.5 0 0 1 .708 0z"/>
      </svg>
    ),
    file: (
      <svg viewBox="0 0 16 16" fill="currentColor" width="12" height="12">
        <path d="M4 0a2 2 0 0 0-2 2v12a2 2 0 0 0 2 2h8a2 2 0 0 0 2-2V4.707A1 1 0 0 0 13.707 4L10 .293A1 1 0 0 0 9.293 0H4zm5.5 1.5v2a1 1 0 0 0 1 1h2l-3-3z"/>
      </svg>
    ),
    finding: (
      <svg viewBox="0 0 16 16" fill="currentColor" width="12" height="12">
        <path d="M11.742 10.344a6.5 6.5 0 1 0-1.397 1.398h-.001c.03.04.062.078.098.115l3.85 3.85a1 1 0 0 0 1.415-1.414l-3.85-3.85a1.007 1.007 0 0 0-.115-.099zm-5.242 1.656a5.5 5.5 0 1 1 0-11 5.5 5.5 0 0 1 0 11z"/>
      </svg>
    ),
    info: (
      <svg viewBox="0 0 16 16" fill="currentColor" width="12" height="12">
        <path d="M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16zm.93-9.412-1 4.705c-.07.34.029.533.304.533.194 0 .487-.07.686-.246l-.088.416c-.287.346-.92.598-1.465.598-.703 0-1.002-.422-.808-1.319l.738-3.468c.064-.293.006-.399-.287-.47l-.451-.081.082-.381 2.29-.287zM8 5.5a1 1 0 1 1 0-2 1 1 0 0 1 0 2z"/>
      </svg>
    ),
  };

  return (
    <div className="ec-trace-panel">
      <div className="ec-trace-header" onClick={onToggle}>
        <svg viewBox="0 0 16 16" fill="currentColor" width="12" height="12">
          <path d="M5 3.5h6A1.5 1.5 0 0 1 12.5 5v5.034a.5.5 0 0 1-.276.447l-1.5.75-.448-.894.776-.388V5a.5.5 0 0 0-.5-.5H5a.5.5 0 0 0-.5.5v7a.5.5 0 0 0 .5.5h3.5v1H5A1.5 1.5 0 0 1 3.5 12V5A1.5 1.5 0 0 1 5 3.5z"/>
          <path d="M11.854 11.146a.5.5 0 0 0-.707.708L12.293 13H9.5a.5.5 0 0 0 0 1h2.793l-1.147 1.146a.5.5 0 0 0 .708.708l2-2a.5.5 0 0 0 0-.708l-2-2z"/>
        </svg>
        Agent trace — {log.length} steps
        <svg viewBox="0 0 16 16" fill="currentColor" width="10" height="10"
          style={{ marginLeft: "auto", transform: open ? "rotate(180deg)" : undefined, transition: "transform 0.2s" }}>
          <path d="M1.646 4.646a.5.5 0 0 1 .708 0L8 10.293l5.646-5.647a.5.5 0 0 1 .708.708l-6 6a.5.5 0 0 1-.708 0l-6-6a.5.5 0 0 1 0-.708z"/>
        </svg>
      </div>
      {open && (
        <div className="ec-trace-body" ref={bodyRef}>
          {log.map((entry, i) => (
            <div key={i} className="ec-trace-line">
              <span className={`ec-trace-icon ${entry.type}`}>
                {ICONS[entry.type] || ICONS.info}
              </span>
              <div className="ec-trace-text">
                {entry.type === "react" ? (
                  // ReAct entries: show tool call prominently, THINK text faint + truncated.
                  // entry.tool = "read_file("backend/services/agent.py")"
                  // entry.think = full reasoning sentence (can be 200+ chars)
                  <>
                    {entry.tool && <span className="ec-trace-react-tool">{entry.tool}</span>}
                    {entry.think && (
                      <span className="ec-trace-react-think">
                        {entry.think.length > 90 ? entry.think.slice(0, 90) + "…" : entry.think}
                      </span>
                    )}
                  </>
                ) : (
                  <>
                    {entry.name && <span className="ec-trace-name">{entry.name} </span>}
                    {entry.text && <span className="ec-trace-sub">{entry.text}</span>}
                    {entry.stages && (
                      <div className="ec-trace-stages">
                        {entry.stages.map((s, j) => (
                          <span key={j} className="ec-trace-stage-pill">{s}</span>
                        ))}
                      </div>
                    )}
                  </>
                )}
              </div>
            </div>
          ))}
        </div>
      )}
    </div>
  );
}

// ── ExploreView ────────────────────────────────────────────────────────────────
export default function ExploreView({ repo, onAskAbout, onRegenerateRef }) {
  const [data, setData]         = useState(null);
  const [loading, setLoading]   = useState(false);
  const [loadStage, setStage]   = useState(null);   // { stage, progress, message }
  const [traceLog, setTrace]    = useState([]);      // agent investigation steps
  const [traceOpen, setTrOpen]  = useState(true);   // trace panel expanded?
  const [error, setError]       = useState(null);
  const [hoveredId, setHovered]   = useState(null);
  // Tracks which concept Story mode should jump to when launched from a
  // Canvas card click. Bumped each click so TourStory remounts to that
  // concept; null means "open Story at the start" (e.g. via the mode tab).
  const [storyInitialId, setStoryInitialId] = useState(null);
  // "canvas" = scatter of cards + arrows; "story" = focused one-at-a-time reading.
  // Persist so the user's chosen mode survives page reloads.
  const [mode, setMode] = useState(
    () => localStorage.getItem("ghrc_tourMode") === "story" ? "story" : "canvas"
  );
  useEffect(() => { localStorage.setItem("ghrc_tourMode", mode); }, [mode]);

  // Open Story mode focused on a specific concept. Used by Canvas card
  // clicks: the card is the entry point, Story is the reader. Resetting
  // storyInitialId before bumping ensures the same-concept second click
  // still triggers a remount via the React key on TourStory below.
  function openStoryFor(conceptId) {
    setStoryInitialId(conceptId);
    setMode("story");
  }
  const [xform, setXform]       = useState({ x: 0, y: 0, scale: window.innerWidth < 768 ? 0.5 : 0.85 });
  const dragging   = useRef(false);
  const drag0      = useRef({});
  const wrapRef    = useRef(null);

  // Per-node drag — same pattern as GraphDiagram
  const [nodePos, setNodePos]  = useState({});  // id → {x,y} overrides
  const dragNode   = useRef(null);              // active node drag state
  const wasDragged = useRef(false);            // suppress click-after-drag
  const scaleRef   = useRef(xform.scale);      // current scale for doc-level handlers
  useEffect(() => { scaleRef.current = xform.scale; }, [xform.scale]);

  // ── Fetch ─────────────────────────────────────────────────────────────────
  const load = useCallback((force = false) => {
    if (!repo) return;
    // 1. In-memory cache: survives tab switches within the same page session.
    if (!force && tourCache[repo]) {
      setData(tourCache[repo]);
      setLoading(false);
      setError(null);
      return;
    }
    // 2. localStorage cache: survives page refreshes. Avoids re-generating
    //    expensive LLM calls just because the user hit F5.
    if (!force) {
      try {
        const stored = localStorage.getItem(tourLsKey(repo));
        if (stored) {
          const parsed = JSON.parse(stored);
          tourCache[repo] = parsed;
          setData(parsed);
          setLoading(false);
          setError(null);
          return;
        }
      } catch { /* corrupt entry — fall through to fetch */ }
    }
    setLoading(true);
    setStage(null);
    setTrace([]);
    setTrOpen(true);
    setError(null);
    setData(null);
    setXform({ x: 0, y: 0, scale: window.innerWidth < 768 ? 0.5 : 0.85 });
    const cancel = streamTour(repo, {
      force,
      onProgress: (ev) => {
        setStage(ev);
        // Accumulate trace events for the live-log panel
        if (ev.trace) setTrace(prev => [...prev, ev.trace]);
      },
      onDone:     (d)  => {
        tourCache[repo] = d;
        try { localStorage.setItem(tourLsKey(repo), JSON.stringify(d)); } catch { /* quota full */ }
        setLoading(false);
        setStage(null);
        setData(d);
      },
      onError:    (e)  => { setLoading(false); setStage(null); setError(e); },
    });
    return cancel;
  }, [repo]);

  useEffect(() => { load(); }, [load]);

  // Reset dragged positions whenever a new tour loads
  useEffect(() => { setNodePos({}); }, [data]);

  // Expose a force-reload function to DiagramView via a ref so the header
  // "Regenerate" button can bust the cache without prop-drilling a callback.
  useEffect(() => {
    if (onRegenerateRef) {
      onRegenerateRef.current = () => {
        delete tourCache[repo];
        try { localStorage.removeItem(tourLsKey(repo)); } catch {}
        load(true);  // force=true → api passes ?force=true → backend busts disk cache
      };
    }
  }, [onRegenerateRef, repo, load]);

  // ── Non-passive wheel zoom ─────────────────────────────────────────────────
  useEffect(() => {
    const el = wrapRef.current;
    if (!el) return;
    function onWheel(e) {
      e.preventDefault();
      const f = Math.exp(-e.deltaY * 0.001);
      const rect = el.getBoundingClientRect();
      const mx = e.clientX - rect.left;
      const my = e.clientY - rect.top;
      setXform(t => {
        const newScale = Math.min(Math.max(t.scale * f, 0.3), 3);
        const ratio = newScale / t.scale;
        return { x: mx - (mx - t.x) * ratio, y: my - (my - t.y) * ratio, scale: newScale };
      });
    }
    el.addEventListener("wheel", onWheel, { passive: false });
    return () => el.removeEventListener("wheel", onWheel);
  // !!data as dep: ExploreView has early returns for loading/error/null states,
  // so wrapRef.current is null on first mount. Re-run once data arrives and the
  // canvas wrapper is actually in the DOM. Cleanup removes the old listener
  // before reattaching, so there's no double-registration risk.
  }, [!!data]);

  // Touch pan (1 finger) + pinch-to-zoom (2 fingers) — same logic as GraphDiagram
  useEffect(() => {
    const el = wrapRef.current;
    if (!el) return;
    let lastTouch = null;
    let lastPinch = null;
    function pinchDist(t) { return Math.hypot(t[1].clientX - t[0].clientX, t[1].clientY - t[0].clientY); }
    function pinchMid(t, rect) {
      return { x: (t[0].clientX + t[1].clientX) / 2 - rect.left,
               y: (t[0].clientY + t[1].clientY) / 2 - rect.top };
    }
    function onTouchStart(e) {
      if (e.touches.length === 1) {
        lastTouch = { x: e.touches[0].clientX, y: e.touches[0].clientY };
        lastPinch = null;
      } else if (e.touches.length === 2) {
        const t = [...e.touches];
        lastPinch = { dist: pinchDist(t), mid: pinchMid(t, el.getBoundingClientRect()) };
        lastTouch = null;
      }
    }
    function onTouchMove(e) {
      e.preventDefault();
      if (e.touches.length === 1 && lastTouch) {
        const dx = e.touches[0].clientX - lastTouch.x;
        const dy = e.touches[0].clientY - lastTouch.y;
        lastTouch = { x: e.touches[0].clientX, y: e.touches[0].clientY };
        setXform(t => ({ ...t, x: t.x + dx, y: t.y + dy }));
      } else if (e.touches.length === 2 && lastPinch) {
        const t   = [...e.touches];
        const rect = el.getBoundingClientRect();
        const d   = pinchDist(t);
        const mid = pinchMid(t, rect);
        const f   = d / lastPinch.dist;
        lastPinch = { dist: d, mid };
        setXform(s => {
          const newScale = Math.min(Math.max(s.scale * f, 0.3), 3);
          const ratio = newScale / s.scale;
          return { x: mid.x - (mid.x - s.x) * ratio, y: mid.y - (mid.y - s.y) * ratio, scale: newScale };
        });
      }
    }
    function onTouchEnd() { lastTouch = null; lastPinch = null; }
    el.addEventListener("touchstart", onTouchStart, { passive: true });
    el.addEventListener("touchmove",  onTouchMove,  { passive: false });
    el.addEventListener("touchend",   onTouchEnd);
    return () => {
      el.removeEventListener("touchstart", onTouchStart);
      el.removeEventListener("touchmove",  onTouchMove);
      el.removeEventListener("touchend",   onTouchEnd);
    };
  }, [!!data]);

  // ── Pan handlers ──────────────────────────────────────────────────────────
  // We attach mousemove/mouseup to the DOCUMENT rather than the wrapper div.
  //
  // Why: React synthetic events on the wrapper only fire when the pointer is
  // directly over the wrapper element. The moment it moves over a child card
  // the wrapper's onMouseMove stops firing, breaking the drag mid-gesture.
  //
  // Document-level listeners receive every mouse event regardless of which
  // element the cursor is currently over — the standard pattern for drag.
  useEffect(() => {
    function onDocMove(e) {
      // Node drag takes priority over canvas pan
      if (dragNode.current) {
        const dx = (e.clientX - dragNode.current.startMouse.x) / scaleRef.current;
        const dy = (e.clientY - dragNode.current.startMouse.y) / scaleRef.current;
        if (Math.abs(dx) > 4 || Math.abs(dy) > 4) wasDragged.current = true;
        const id   = dragNode.current.id;
        const newX = dragNode.current.startPos.x + dx;
        const newY = dragNode.current.startPos.y + dy;
        setNodePos(prev => ({ ...prev, [id]: { x: newX, y: newY } }));
        return;
      }
      if (!dragging.current) return;
      setXform(t => ({
        ...t,
        x: drag0.current.tx + (e.clientX - drag0.current.mx),
        y: drag0.current.ty + (e.clientY - drag0.current.my),
      }));
    }
    function onDocUp() {
      dragNode.current = null;
      dragging.current = false;
      if (wrapRef.current) wrapRef.current.style.cursor = "grab";
      setTimeout(() => { wasDragged.current = false; }, 0);
    }
    document.addEventListener("mousemove", onDocMove);
    document.addEventListener("mouseup",   onDocUp);
    return () => {
      document.removeEventListener("mousemove", onDocMove);
      document.removeEventListener("mouseup",   onDocUp);
    };
  }, []); // empty deps — only refs + stable setters used inside

  function onMouseDown(e) {
    if (e.button !== 0) return;
    dragging.current = true;
    drag0.current = { mx: e.clientX, my: e.clientY, tx: xform.x, ty: xform.y };
    if (wrapRef.current) wrapRef.current.style.cursor = "grabbing";
  }

  function onNodeDragStart(e, concept, currentPos) {
    if (e.button !== 0) return;
    e.stopPropagation(); // prevent canvas pan from activating
    dragNode.current = {
      id:         concept.id,
      startPos:   currentPos,
      startMouse: { x: e.clientX, y: e.clientY },
    };
  }

  function handleAsk(concept) {
    onAskAbout?.(
      concept.ask ||
      `Explain "${concept.name}" in ${repo} in detail — what does it do, how does it work, and what are the key methods or functions involved?`
    );
  }

  // ── Loading / error states ─────────────────────────────────────────────────
  if (loading) {
    const pct   = loadStage ? Math.round(loadStage.progress * 100) : 0;
    const rawLabel = loadStage?.message || "Building your guided tour…";
    // Cap the progress label — long THINK strings must not overflow this area
    const label = rawLabel.length > 72 ? rawLabel.slice(0, 72) + "…" : rawLabel;
    return (
      <div className="ec-loading" style={{ flexDirection: "column", alignItems: "stretch", gap: 16, maxWidth: 480, margin: "auto" }}>
        {/* Progress row */}
        <div style={{ display: "flex", alignItems: "center", gap: 12 }}>
          <span className="spinner" />
          <div style={{ flex: 1 }}>
            <div style={{ fontWeight: 600, marginBottom: 6, fontSize: 13 }}>{label}</div>
            <div style={{ height: 3, background: "var(--border)", borderRadius: 2, overflow: "hidden" }}>
              <div style={{
                height: "100%", width: `${pct}%`,
                background: "var(--accent)", borderRadius: 2, transition: "width 0.5s ease",
              }} />
            </div>
            {pct > 0 && (
              <div style={{ fontSize: 11, color: "var(--muted)", marginTop: 4 }}>{pct}%</div>
            )}
          </div>
        </div>
        {/* Live agent trace log */}
        {traceLog.length > 0 && (
          <TracePanel log={traceLog} open={traceOpen} onToggle={() => setTrOpen(v => !v)} />
        )}
      </div>
    );
  }

  if (error) {
    return (
      <div className="ec-error">
        <div style={{ fontSize: 13, color: "var(--red)" }}>{error}</div>
        <button className="diagram-retry-btn" onClick={() => load(true)}>Retry</button>
      </div>
    );
  }

  if (!data) return null;

  const concepts      = data.concepts || [];
  const basePositions = computeLayout(concepts);

  // Visual sequence numbers: row-first then column — matches the left-to-right,
  // top-to-bottom reading order of the row-major layout.
  const visualNumber = {};
  Object.entries(basePositions)
    .sort(([, a], [, b]) => a.y !== b.y ? a.y - b.y : a.x - b.x)
    .forEach(([id], i) => { visualNumber[Number(id)] = i + 1; });

  // When a card is hovered, push every card in a row strictly BELOW the
  // hovered card's row down by EXPANSION_H so the expansion has room. The
  // lower rows reflow smoothly because positions feed into a CSS transform
  // with a transition on the `top` property — visually the lower rows
  // glide down rather than jumping.
  //
  // We use the HOVERED row, not the connected-set row: the connected
  // neighbours are usually in the same row as the hovered card (left/right
  // of it), so pushing only the hovered row's lower neighbours is correct.
  // If a connected neighbour is in a different row, the offset still
  // applies via the hovered card's row check below.
  const yOffsets = (() => {
    if (hoveredId === null) return {};
    const hoverPos = basePositions[hoveredId];
    if (!hoverPos) return {};
    const offsets = {};
    concepts.forEach(c => {
      const p = basePositions[c.id];
      if (p && p.y > hoverPos.y) offsets[c.id] = EXPANSION_H;
    });
    return offsets;
  })();
  const positions = Object.fromEntries(
    Object.entries(basePositions).map(([id, pos]) => [
      id,
      { x: pos.x, y: pos.y + (yOffsets[id] ?? 0) },
    ])
  );

  // Dragged position overrides static layout — falls back to positions[id]
  const getPosFor = (id) => nodePos[id] ?? positions[id];

  // Canvas bounding box — accounts for the maximum offset that any card
  // could pick up if a top-row card is hovered (push amount = EXPANSION_H).
  const allX = Object.values(positions).map(p => p.x + CARD_W + 80);
  const allY = Object.values(positions).map(p => p.y + CARD_H + EXPANSION_H + 80);
  const canvasW = Math.max(...allX, 700);
  const canvasH = Math.max(...allY, 500);

  // Connected set for hover dimming: hovered node + its direct neighbors
  // (concepts that depend on it AND concepts it depends on). Other cards
  // get the .ec-dimmed class so the relational structure pops on hover.
  const connectedIds = hoveredId !== null
    ? new Set([
        hoveredId,
        ...concepts.filter(c => c.depends_on?.includes(hoveredId)).map(c => c.id),
        ...(concepts.find(c => c.id === hoveredId)?.depends_on ?? []),
      ])
    : null;

  // Resolve depends_on ids → concept names for the "Builds on" row on each
  // card. Done once per render so cards don't each re-walk the concepts
  // array. Missing ids are filtered out (the LLM occasionally references
  // concepts that didn't make the final cut).
  const conceptById = Object.fromEntries(concepts.map(c => [c.id, c]));
  const dependsOnByCard = Object.fromEntries(
    concepts.map(c => [
      c.id,
      (c.depends_on ?? [])
        .map(depId => conceptById[depId])
        .filter(Boolean)
        .map(dep => ({ id: dep.id, name: dep.name })),
    ])
  );

  return (
    <div className="ec-container">
      {/* ── Summary header ── */}
      <div className="ec-header">
        <div className="ec-summary">{data.summary}</div>
        <div className="ec-controls">
        <div className="ec-mode-toggle" role="tablist" aria-label="Tour view mode">
          <button
            role="tab"
            aria-selected={mode === "canvas"}
            className={`ec-mode-btn${mode === "canvas" ? " is-active" : ""}`}
            onClick={() => setMode("canvas")}
            title="See all concepts at once"
          >
            <svg width="12" height="12" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
              <rect x="1.5" y="1.5" width="5.5" height="5.5" rx="1"/>
              <rect x="9" y="1.5" width="5.5" height="5.5" rx="1"/>
              <rect x="1.5" y="9" width="5.5" height="5.5" rx="1"/>
              <rect x="9" y="9" width="5.5" height="5.5" rx="1"/>
            </svg>
            Canvas
          </button>
          <button
            role="tab"
            aria-selected={mode === "story"}
            className={`ec-mode-btn${mode === "story" ? " is-active" : ""}`}
            onClick={() => setMode("story")}
            title="Read one concept at a time"
          >
            <svg width="12" height="12" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
              <path d="M2 3.25C2 2.56 2.56 2 3.25 2h9.5c.69 0 1.25.56 1.25 1.25v9.5c0 .69-.56 1.25-1.25 1.25h-9.5C2.56 14 2 13.44 2 12.75v-9.5ZM3.5 3.5v9h9v-9h-9Z"/>
              <path d="M5 6h6v1.2H5V6Zm0 2.4h6v1.2H5V8.4Z"/>
            </svg>
            Story
          </button>
        </div>
        {data.entry_point && (
          <div className="ec-entry-hint">
            <svg width="11" height="11" viewBox="0 0 16 16" fill="currentColor" style={{ opacity: 0.6 }}>
              <path d="M8 0a8 8 0 1 1 0 16A8 8 0 0 1 8 0ZM1.5 8a6.5 6.5 0 1 0 13 0 6.5 6.5 0 0 0-13 0Zm4.879-2.773 4.264 2.559a.25.25 0 0 1 0 .428l-4.264 2.559A.25.25 0 0 1 6 10.559V5.442a.25.25 0 0 1 .379-.215Z"/>
            </svg>
            Start reading: <code>{data.entry_point}</code>
          </div>
        )}
        </div>
      </div>

      {/* Keyed flex wrapper — remounts on mode change so .view-switch-in replays.
          display:flex + flex:1 so Canvas/Story still fill the container. */}
      <div
        key={mode}
        className="view-switch-in"
        style={{ flex: 1, display: "flex", flexDirection: "column", minHeight: 0 }}
      >
      {mode === "story" ? (
        // Key on storyInitialId so opening Story for a new concept remounts
        // and re-runs the initializer that picks the starting index. Without
        // the key, a second card click while already in Story mode wouldn't
        // jump to the new concept (useState initializer fires once).
        <TourStory
          key={`story-${storyInitialId ?? "start"}`}
          data={data}
          repo={repo}
          onAskAbout={onAskAbout}
          initialConceptId={storyInitialId}
        />
      ) : (
      <>
      {/* ── Canvas ── */}
      <div
        ref={wrapRef}
        className="ec-canvas-wrapper has-cursor-glow"
        onMouseDown={onMouseDown}
        // Feed --mx / --my for the cursor-glow primitive.
        // Pan drag uses onMouseDown + document mousemove, so this local
        // handler doesn't interfere with drag gesture state.
        onMouseMove={(e) => {
          const r = e.currentTarget.getBoundingClientRect();
          e.currentTarget.style.setProperty("--mx", `${e.clientX - r.left}px`);
          e.currentTarget.style.setProperty("--my", `${e.clientY - r.top}px`);
        }}
        style={{ "--glow-size": "520px", "--glow-intensity": "8%" }}
      >
        <div
          className="ec-canvas"
          style={{
            width: canvasW,
            height: canvasH,
            transform: `translate(${xform.x}px, ${xform.y}px) scale(${xform.scale})`,
            transformOrigin: "0 0",
          }}
        >
          {/* ── SVG arrow layer ── */}
          {/* Each arrow has two layers:
              1. Base path — solid thin line + arrowhead (always visible)
              2. Traveling dot — small glowing circle that animates from source to target
                 using <animateMotion> + <mpath>. This communicates DIRECTION: you can
                 instantly see which way concepts depend on each other. The dot fades in
                 after 10% of the journey and fades out before 90% so it never looks
                 abrupt at the endpoints. Highlighted arrows skip the dot — the glow
                 filter communicates selection state instead. */}
          <svg
            width={canvasW}
            height={canvasH}
            style={{ position: "absolute", inset: 0, pointerEvents: "none", overflow: "visible" }}
            aria-hidden="true"
          >
            <defs>
              <marker id="ec-arrow" markerWidth="7" markerHeight="5" refX="7" refY="2.5" orient="auto">
                <polygon points="0 0, 7 2.5, 0 5" fill="rgba(91,143,249,0.4)" />
              </marker>
              <marker id="ec-arrow-hi" markerWidth="7" markerHeight="5" refX="7" refY="2.5" orient="auto">
                <polygon points="0 0, 7 2.5, 0 5" fill="#7DABFF" />
              </marker>
              {/* Amber arrowhead for sequential reading-path arrows */}
              <marker id="ec-arrow-seq" markerWidth="7" markerHeight="5" refX="7" refY="2.5" orient="auto">
                <polygon points="0 0, 7 2.5, 0 5" fill="rgba(245,158,11,0.75)" />
              </marker>
            </defs>

            {/* ── Sequential reading-path arrows (amber) ──────────────────
                 Connect concept N → N+1 in reading order so the learning
                 path is visually explicit. These are the primary navigation
                 guide; dependency arrows (blue) are supporting context. */}
            {(() => {
              const seq = [...concepts].sort((a, b) =>
                (a.reading_order ?? 999) - (b.reading_order ?? 999)
              );
              return seq.slice(0, -1).map((c, i) => {
                const next = seq[i + 1];
                const from = getPosFor(c.id);
                const to   = getPosFor(next.id);
                if (!from || !to) return null;
                const d = bezierPath(from, to);
                const isDim = connectedIds && !connectedIds.has(c.id) && !connectedIds.has(next.id);
                return (
                  <path
                    key={`seq-${c.id}→${next.id}`}
                    d={d}
                    stroke="rgba(245,158,11,0.50)"
                    strokeWidth="1.5"
                    fill="none"
                    markerEnd="url(#ec-arrow-seq)"
                    strokeDasharray="5 3"
                    style={{ opacity: isDim ? 0.06 : 1, transition: "opacity 0.15s" }}
                  />
                );
              });
            })()}

            {/* ── Dependency arrows (blue) — prerequisite relationships ── */}
            {concepts.map(c =>
              (c.depends_on ?? []).map(depId => {
                const from = getPosFor(depId);
                const to   = getPosFor(c.id);
                if (!from || !to) return null;

                const isHi  = connectedIds?.has(c.id) && connectedIds?.has(depId);
                const isDim = connectedIds && !isHi;
                const pathId = `ec-path-${depId}-${c.id}`;
                // Stagger dot travel per connection so all dots don't move in sync
                const stagger = `${((depId * 3 + c.id * 7) % 40) / 10}s`;
                const d = bezierPath(from, to);

                return (
                  <g key={`${depId}→${c.id}`} style={{ opacity: isDim ? 0.08 : 1, transition: "opacity 0.15s" }}>
                    {/* Base arrow path */}
                    <path
                      id={pathId}
                      d={d}
                      stroke={isHi ? "#7DABFF" : "rgba(91,143,249,0.35)"}
                      strokeWidth={isHi ? 2 : 1.2}
                      fill="none"
                      markerEnd={isHi ? "url(#ec-arrow-hi)" : "url(#ec-arrow)"}
                      style={{
                        filter: isHi ? "drop-shadow(0 0 3px rgba(125,171,255,0.6))" : undefined,
                        transition: "stroke 0.15s, stroke-width 0.15s, filter 0.15s",
                      }}
                    />
                    {/* Traveling dot — communicates flow direction.
                        Hidden on highlighted arrows (glow covers it) and dimmed arrows. */}
                    {!isHi && !isDim && (
                      <circle r="2.5" fill="#7DABFF">
                        {/* Fade in at 10%, full at 20%, full at 80%, fade out at 90% */}
                        <animate attributeName="opacity"
                          values="0;0;1;1;0;0" keyTimes="0;0.1;0.2;0.8;0.9;1"
                          dur="4s" begin={stagger} repeatCount="indefinite" />
                        <animateMotion dur="4s" begin={stagger} repeatCount="indefinite" rotate="auto">
                          <mpath href={`#${pathId}`} />
                        </animateMotion>
                      </circle>
                    )}
                  </g>
                );
              })
            )}
          </svg>

          {/* ── Concept cards ── */}
          {concepts.map(c => {
            const pos = getPosFor(c.id);
            if (!pos) return null;
            // isEntry = the leftmost card (visual number 1) — always the pipeline overview
            const isEntry = visualNumber[c.id] === 1;
            return (
              <ConceptCard
                key={c.id}
                concept={c}
                visualNum={visualNumber[c.id]}
                isEntry={isEntry}
                isHovered={hoveredId === c.id || (!!connectedIds && connectedIds.has(c.id))}
                isDimmed={!!connectedIds && !connectedIds.has(c.id)}
                pos={pos}
                dependsOnNames={dependsOnByCard[c.id]}
                onOpenStory={openStoryFor}
                onHover={setHovered}
                onAsk={handleAsk}
                onDragStart={onNodeDragStart}
                wasDragged={wasDragged}
              />
            );
          })}
        </div>
      </div>

      {/* ── Legend + hint ── */}
      <div className="ec-legend">
        {Object.entries(TYPE_STYLE).map(([type, s]) => (
          <span key={type} className="ec-legend-item">
            <span className="ec-legend-dot" style={{ background: s.dot }} />
            {type}
          </span>
        ))}
        <span className="ec-legend-hint">
          {concepts.length} concepts · scroll to zoom · drag to pan · hover for detail · click to read
        </span>
      </div>
      </>
      )}
      </div>
    </div>
  );
}