Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

70.7 KB
Raw Blame
"use client";

import {
  useCallback,
  useMemo,
  useState,
  useEffect,
  useRef,
  type ReactNode,
} from "react";
import { useTheme } from "next-themes";
import { HelpCircle } from "lucide-react";
import { Skeleton } from "../ui/skeleton";
import { EmptyState } from "../shared/empty-state";
import { type Signal } from "./context";
import { type FileNodeData, type ModuleNodeData } from "./elk-layout";

// Resting zoom when easing the camera onto a constellation hub. Looser than the
// default file-node focus (0.15) so the hub *and* its surrounding cluster stay
// visible instead of the disc filling the whole viewport.
const HUB_FOCUS_RATIO = 0.45;
// Below this node count file graphs build synchronously; at or above it we
// build in chunks off the critical path (see sigmaGraph below).
const ASYNC_BUILD_THRESHOLD = 1000;

import { usePrefersReducedMotion } from "../hooks/use-prefers-reduced-motion";
import { GraphScopeBreadcrumb } from "./graph-scope-breadcrumb";
import { traceToEdgeKeys, traceToFileTrace } from "./graph-flow-helpers";
import { useGraphContextMenu } from "./use-graph-context-menu";
import { useGraphSearch } from "./use-graph-search";
import { useCommunityFilter } from "./use-community-filter";
import { useModuleFilter, filterGraphToModule } from "./use-module-filter";
import { useGraphKeyboardShortcuts } from "./use-graph-keyboard-shortcuts";
import {
  GraphToolbar,
  type ColorMode,
  type ViewMode,
  type GraphTheme,
  type GraphToolbarCopy,
  type GraphNodeFilterCopy,
} from "./graph-toolbar";
import { GraphLegend, type GraphLegendCopy } from "./graph-legend";
import { GraphNodeFilter } from "./graph-toolbar";
import { GraphCanvasShell } from "./graph-canvas-shell";
import { GraphContextMenu } from "./graph-context-menu";
import { GraphInspectionPanel } from "./graph-inspection-panel";
import { GraphFlowPanel } from "./graph-flow-panel";
import { GraphShortcutHelp } from "./graph-shortcut-help";
import {
  GraphPopulationControl,
  type GraphPopulationControlCopy,
} from "./graph-population-control";
import { GraphUnclusteredPanel } from "./graph-unclustered-panel";
import type {
  GraphExport,
  ExecutionFlows,
  CommunitySummaryItem,
  ArchitectureGraph,
  CommunitySlice,
  GraphPopulation,
} from "@repowise-dev/types/graph";
import { SigmaCanvas, type SigmaCanvasHandle } from "./sigma/sigma-canvas";
import {
  fileGraphToGraphology,
  fileGraphToGraphologyAsync,
} from "./sigma/graphology-adapter";
import {
  architectureToGraphology,
  hubNodeId,
  UNCLUSTERED_COMMUNITY_ID,
} from "./sigma/constellation-adapter";
import { computeRadialLayout } from "./sigma/radial-layout";
import type { SigmaNodeAttributes, SigmaEdgeAttributes } from "./sigma/types";
import type GraphologyGraph from "graphology";
import { useEgoFilter } from "./sigma/use-ego-filter";
import { filterOverviewData, getOverviewMeta, layoutFilesOverview } from "./sigma/files-overview";
import { CommunityColorContext, communityColorSlots } from "./community-colors";

export interface GraphFlowCopy {
  toolbar?: Partial<GraphToolbarCopy> | undefined;
  nodeFilter?: Partial<GraphNodeFilterCopy> | undefined;
  legend?: Partial<GraphLegendCopy> | undefined;
  population?: Partial<GraphPopulationControlCopy> | undefined;
  /** Breadcrumb root when the host gives no repo name. */
  allCommunities: string;
  /** Description inside one community. */
  insideCommunity: string;
  /** Appended to {@link insideCommunity} when files open on double-click. */
  openFileHint: string;
  communityFallback: (id: number) => string;
}

export const GRAPH_FLOW_COPY: GraphFlowCopy = {
  allCommunities: "All communities",
  insideCommunity: "How the files in this group depend on each other.",
  openFileHint: "Double-click a file to open it.",
  communityFallback: (id) => `Community ${id}`,
};

export interface GraphFlowProps {
  fullGraph: GraphExport | undefined;
  isLoadingFullGraph: boolean;
  /** @deprecated Unread. The "architecture" scope draws the constellation from
   *  {@link constellationGraph}, not a file-graph export. Kept optional so an
   *  out-of-tree host compiles while it drops them. */
  architectureGraph?: GraphExport | undefined;
  /** @deprecated Unread. See {@link architectureGraph}. */
  isLoadingArchitectureGraph?: boolean | undefined;
  /** Community super-graph for the constellation (radial Knowledge Graph) scope. */
  constellationGraph?: ArchitectureGraph | undefined;
  isLoadingConstellationGraph?: boolean;
  /** @deprecated Unread. Hubs no longer blossom satellites in place: a
   *  double-click *enters* the community and draws its own file graph. See
   *  {@link communitySlice}. Kept optional so a host compiles while it drops it. */
  constellationSlices?: Map<number, CommunitySlice> | undefined;
  /** @deprecated Unread. See {@link onActiveCommunityChange}. */
  onExpandedHubsChange?: (expanded: number[]) => void;
  /** The community currently being drilled into, or null for the whole scope.
   *  Controlled by the host, which URL-syncs it as `?community=`. */
  activeCommunity?: number | null | undefined;
  /** Fired when the reader enters or leaves a community (hub double-click, the
   *  panel's Enter action, the breadcrumb, Escape). The host writes `?community=`
   *  and, on entry, switches the scope to files. */
  onActiveCommunityChange?: ((communityId: number | null) => void) | undefined;
  /** The entered community's own sub-graph: its members plus one-hop boundary
   *  stubs. Fetched by the host in response to {@link onActiveCommunityChange}. */
  communitySlice?: CommunitySlice | undefined;
  isLoadingCommunitySlice?: boolean | undefined;
  /** Which non-production files the community views count. Controlled by the
   *  host, which fetches with it. The control renders only when both are
   *  supplied. */
  population?: GraphPopulation | undefined;
  onPopulationChange?: ((next: GraphPopulation) => void) | undefined;
  /** Whether the whole-repo Files view draws third-party (`external:` /
   *  `framework:`) nodes. Off by default: on this repo they are a tenth of the
   *  drawn nodes and touch 40% of the drawn edges, none of it the repo's own
   *  structure. Controlled when supplied (a host URL-syncs it); otherwise the
   *  component tracks it. The key always says how many are hidden. */
  showExternal?: boolean | undefined;
  onShowExternalChange?: ((next: boolean) => void) | undefined;
  /** Repo name for the constellation core label. */
  repoName?: string;
  deadCodeGraph: GraphExport | undefined;
  isLoadingDeadCodeGraph: boolean;
  hotFilesGraph: GraphExport | undefined;
  isLoadingHotFilesGraph: boolean;
  communities?: CommunitySummaryItem[];
  executionFlows?: ExecutionFlows;
  /** Fired when the flows panel opens or closes, so a host can defer fetching
   *  {@link executionFlows} until someone asks. Optional; ignoring it keeps the
   *  eager behaviour. */
  onFlowsVisibilityChange?: ((visible: boolean) => void) | undefined;
  initialViewMode?: ViewMode;
  /** Controlled scope. Scope is now steered from the page's section header
   *  (`GraphScopeSwitcher`) rather than from a pill cluster on the canvas, so
   *  the host owns the value and URL-syncs it. Omit to let the component track
   *  its own, seeded by {@link initialViewMode}. */
  viewMode?: ViewMode;
  /** The module filter's current selection (a path prefix from
   *  `moduleGroupFor`), or null for "all modules". Controlled by the host so
   *  the control can live in the section header beside the scope switcher. */
  activeModule?: string | null;
  /** Fired with the module groups present in the rendered graph, so the host
   *  can populate its filter control. Counts are of nodes actually drawn. */
  onModuleGroupsChange?: (groups: { id: string; fileCount: number }[]) => void;
  /** Initial node color mode (uncontrolled seed). Hosts derive this from their
   *  URL state instead of the component reading window.location. Ignored when
   *  {@link colorMode} is supplied. */
  initialColorMode?: ColorMode;
  /** Controlled node color mode. When supplied, the host owns the value (and
   *  typically URL-syncs it); the component reflects it directly and reports
   *  user changes via {@link onColorModeChange}. Omit to let the component
   *  track its own color mode seeded by {@link initialColorMode}. */
  colorMode?: ColorMode;
  initialSelectedNode?: string | null;
  onViewModeChange?: (mode: ViewMode) => void;
  /** Fired when the node color mode changes (toolbar or 1/2/3 shortcut) so
   *  hosts can sync it to the URL. */
  onColorModeChange?: (mode: ColorMode) => void;
  onNodeClick?: (nodeId: string, nodeType: string) => void | Promise<void>;
  onNodeViewDocs?: (nodeId: string) => void;
  /** "Symbols" action in the inspection panel — jump to the symbols view
   *  filtered to the selected file. */
  onNodeViewSymbols?: (nodeId: string) => void;
  /** Canonical file-page href for a file node — renders an "Open file page"
   *  action in the inspection panel. */
  fileHrefFor?: (nodeId: string) => string;
  /** Per-file destinations for the inspector's outbound actions: where this
   *  file's health, git history and decisions live. Optional; each action is
   *  hidden when the host does not supply it. */
  fileHealthHrefFor?: ((nodeId: string) => string) | undefined;
  fileHistoryHrefFor?: ((nodeId: string) => string) | undefined;
  fileDecisionsHrefFor?: ((nodeId: string) => string) | undefined;
  /** The repo's dead-code findings. Offered only on a node flagged dead. */
  deadCodeHref?: string | undefined;
  renderPathFinder?: (props: {
    initialFrom: string;
    initialTo: string;
    onPathFound: (pathNodes: string[]) => void;
    onClear: () => void;
    onClose: () => void;
  }) => ReactNode;
  renderCommunityPanel?: (props: {
    communityId: number;
    onClose: () => void;
    /** Draw this community's own scoped file graph (the drill-down). */
    onEnterCommunity: () => void;
    /** Open a neighbouring community's panel, without leaving the canvas. */
    onNeighborSelect: (communityId: number) => void;
  }) => ReactNode;
  /** Fired when the community detail panel transitions to open. */
  onCommunityPanelOpen?: (communityId: number) => void;
  /** Fired when canvas selection changes. A host owning `rail` content tied to
   *  a node (a doc panel) uses this to drop it once a different node is
   *  selected, instead of masking the inspector indefinitely. */
  onSelectedNodeChange?: ((nodeId: string | null) => void) | undefined;
  /** One-line explanation of the current scope, shown in the header row. */
  description?: string;
  /** Host controls placed left of the toolbar (scope switcher, narrowing
   *  control). */
  headerActions?: ReactNode;
  /** Full-width notice above the canvas (e.g. the truncation banner). */
  banner?: ReactNode;
  /** Host-owned rail content, e.g. a documentation panel. Takes the rail over
   *  the community and inspection panels; see the precedence in the render. */
  rail?: ReactNode;
  copy?: Partial<GraphFlowCopy> | undefined;
}

export function GraphFlow(props: GraphFlowProps) {
  const {
    fullGraph,
    isLoadingFullGraph,
    constellationGraph,
    isLoadingConstellationGraph,
    activeCommunity: controlledActiveCommunity,
    population,
    onPopulationChange,
    showExternal: controlledShowExternal,
    onShowExternalChange,
    onActiveCommunityChange,
    communitySlice,
    isLoadingCommunitySlice,
    repoName,
    deadCodeGraph,
    isLoadingDeadCodeGraph,
    hotFilesGraph,
    isLoadingHotFilesGraph,
    communities,
    executionFlows,
    onFlowsVisibilityChange,
    initialViewMode,
    viewMode: controlledViewMode,
    activeModule: controlledActiveModule,
    onModuleGroupsChange,
    initialColorMode,
    colorMode: controlledColorMode,
    initialSelectedNode,
    onViewModeChange,
    onColorModeChange,
    onNodeClick,
    onNodeViewDocs,
    onNodeViewSymbols,
    fileHrefFor,
    fileHealthHrefFor,
    fileHistoryHrefFor,
    fileDecisionsHrefFor,
    deadCodeHref,
    renderPathFinder,
    renderCommunityPanel,
    onCommunityPanelOpen,
    onSelectedNodeChange,
    description,
    headerActions,
    banner,
    rail,
  } = props;
  const copy = { ...GRAPH_FLOW_COPY, ...props.copy };

  const sigmaRef = useRef<SigmaCanvasHandle>(null);
  const focusTimerRef = useRef<ReturnType<typeof setTimeout>>(undefined);

  // ---- Core state ----
  // Default scope is the constellation (radial Knowledge Graph). Controlled by
  // the host when `viewMode` is supplied — the scope switcher lives in the
  // page's section header now, so the URL is the source of truth.
  const [viewModeState, setViewModeState] = useState<ViewMode>(
    initialViewMode ?? "architecture",
  );
  const viewMode = controlledViewMode ?? viewModeState;
  // Color mode is controlled by the host when `colorMode` is supplied
  // (URL-synced); otherwise the component tracks it locally, seeded by
  // `initialColorMode`. The wrapped setter routes through the host callback in
  // controlled mode and falls back to local state in uncontrolled mode.
  const [colorModeState, setColorModeState] = useState<ColorMode>(
    initialColorMode ?? "community",
  );
  const colorMode = controlledColorMode ?? colorModeState;
  const setColorMode = useCallback(
    (next: ColorMode) => {
      if (onColorModeChange) onColorModeChange(next);
      else setColorModeState(next);
    },
    [onColorModeChange],
  );
  const [highlightedPath, setHighlightedPath] = useState<Set<string>>(new Set());
  const [highlightedEdges, setHighlightedEdges] = useState<Set<string>>(new Set());
  const [showPathFinder, setShowPathFinder] = useState(false);
  const [showShortcutHelp, setShowShortcutHelp] = useState(false);
  // Third-party nodes in the Files overview. See `showExternal`.
  const [showExternalState, setShowExternalState] = useState(false);
  const showExternal = controlledShowExternal ?? showExternalState;
  const setShowExternal = useCallback(
    (next: boolean) => {
      if (onShowExternalChange) onShowExternalChange(next);
      else setShowExternalState(next);
    },
    [onShowExternalChange],
  );

  // The dependency graph follows the global app theme rather than a separate
  // local toggle. Sigma needs a concrete "light"/"dark" (never "system"), so
  // resolve it. The toolbar used to carry its own Sun/Moon that just called
  // `setTheme` — a duplicate of the app's header toggle — and it is gone.
  const { resolvedTheme } = useTheme();
  const graphTheme: GraphTheme = resolvedTheme === "dark" ? "dark" : "light";

  const [egoDepth, setEgoDepth] = useState(0);

  // How much of a found path this view cannot draw. See `handlePathFound`.
  const [pathNotice, setPathNotice] = useState<string | null>(null);

  // Both structural kinds, because the description under every file-scope
  // reading promises "how they depend on each other". The old default was
  // `["import", "crossCommunity"]`, and `"import"` was an unreachable
  // classification — `classifyEdge` returned it only for an edge whose
  // endpoint was missing from the graph, and those are dropped before they are
  // drawn. So the default meant "cross-community only", and inside a community
  // that hid the entire internal structure and drew only the exits.
  //
  // This raises the whole-repo default too, deliberately: measured on this
  // repo's own 1,500-node graph it goes from 1,052 to 5,027 drawn edges, an
  // average degree of 3.35, well short of a hairball and the difference
  // between drawing 21% of the structure and all of it.
  const [visibleEdgeTypes, setVisibleEdgeTypes] = useState<Set<string>>(
    () => new Set(["crossCommunity", "internal"]),
  );

  // Signal overlays (replaces separate view modes for dead/hot/arch).
  // Derived from the host-provided initial view mode — no URL reads here.
  const activeSignals = useMemo<Set<Signal>>(() => {
    if (initialViewMode === "dead") return new Set<Signal>(["dead"]);
    if (initialViewMode === "hotfiles") return new Set<Signal>(["hot"]);
    if (initialViewMode === "unified") return new Set<Signal>(["dead", "hot"]);
    return new Set<Signal>();
  }, [initialViewMode]);
  const hideTests = activeSignals.has("hideTests");

  // Drill-down: the community whose own file graph is drawn.
  // (reconciliation effect lives below, once the panel state exists) The host owns it
  // (`?community=`); the local fallback keeps an uncontrolled host working.
  const [activeCommunityState, setActiveCommunityState] = useState<number | null>(null);
  const activeCommunity =
    controlledActiveCommunity !== undefined
      ? controlledActiveCommunity
      : activeCommunityState;
  const setActiveCommunity = useCallback(
    (next: number | null) => {
      if (onActiveCommunityChange) onActiveCommunityChange(next);
      else setActiveCommunityState(next);
    },
    [onActiveCommunityChange],
  );

  const prefersReducedMotion = usePrefersReducedMotion();

  // Context menu (state + dismiss-on-click/Escape lifecycle)
  const { ctxMenu, setCtxMenu } = useGraphContextMenu();

  // Path finder pre-fill
  const [pathFrom, setPathFrom] = useState("");
  const [pathTo, setPathTo] = useState("");

  // Selection. There is deliberately no hover state: Sigma draws its own hover
  // highlight on the canvas, so mirroring it into React only re-rendered this
  // whole shell on every hover transition for nothing.
  const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null);

  // Execution flows
  const [activeFlowIdx, setActiveFlowIdx] = useState<number | null>(null);
  const [showFlows, setShowFlows] = useState(false);
  // Stable, so the memoised panel does not re-render with the canvas.
  const handleFlowSelect = useCallback(
    (idx: number) => setActiveFlowIdx((cur) => (cur === idx ? null : idx)),
    [],
  );
  const handleFlowsClose = useCallback(() => {
    setShowFlows(false);
    setActiveFlowIdx(null);
  }, []);

  // Reported from one place, not from each of the six setters that close it.
  useEffect(() => {
    onFlowsVisibilityChange?.(showFlows);
  }, [showFlows, onFlowsVisibilityChange]);

  useEffect(() => {
    onSelectedNodeChange?.(selectedNodeId);
  }, [selectedNodeId, onSelectedNodeChange]);

  // Community detail panel (the filter state itself lives in useCommunityFilter)
  const [communityPanelId, setCommunityPanelId] = useState<number | null>(null);

  // Wrap the setter so legend-driven opens notify the host page; this lets
  // the page dismiss competing right-rail panels (doc panel) and keep the
  // right side a single coordinated surface.
  const openCommunityPanel = useCallback(
    (cid: number) => {
      setCommunityPanelId(cid);
      onCommunityPanelOpen?.(cid);
    },
    [onCommunityPanelOpen],
  );

  // Legend click in the constellation: select the hub, ease the camera onto it,
  // and surface the community in the detail panel — NO expand. This mirrors the
  // unified single-click grammar (expansion is reserved for double-click).
  const handleConstellationHubClick = useCallback(
    (cid: number) => {
      if (cid === UNCLUSTERED_COMMUNITY_ID) {
        // Not a community: the host is not told, so it never fetches one.
        setCommunityPanelId(cid);
        return;
      }
      const nodeId = hubNodeId(cid);
      setSelectedNodeId(nodeId);
      sigmaRef.current?.focusNode(nodeId, HUB_FOCUS_RATIO);
      openCommunityPanel(cid);
    },
    [openCommunityPanel],
  );

  // Scope changes arrive from the toolbar, the host's switcher, and the
  // drill-down below, so it lives above all three.
  const handleViewChange = useCallback((v: ViewMode) => {
    setViewModeState(v);
    onViewModeChange?.(v);
  }, [onViewModeChange]);

  // Hub double-click ENTERS the community: the canvas swaps to that community's
  // own file graph, scoped, with its one-hop neighbours as the edge of the
  // world. The hub used to blossom satellites in place, which showed you the
  // files without ever letting you work on them.
  //
  // Camera continuity is what makes this read as one movement. The hub's
  // position is handed to the renderer as the point the *next* graph opens
  // from, so the scoped layout eases outward from where the disc was rather
  // than cutting to a fresh frame. `prefers-reduced-motion` skips the travel.
  const enterCommunity = useCallback(
    (cid: number) => {
      const nodeId = hubNodeId(cid);
      if (!prefersReducedMotion) {
        // Tighter than HUB_FOCUS_RATIO: the movement opens *out* of the hub.
        sigmaRef.current?.setEntryCamera(sigmaRef.current.nodeCamera(nodeId, 0.08));
      }
      setSelectedNodeId(null);
      setPathNotice(null);
      setActiveCommunity(cid);
      openCommunityPanel(cid);
      // Files scope, since a community's members are files. A controlled host
      // reflects this back through `viewMode`.
      handleViewChange("full");
    },
    [prefersReducedMotion, setActiveCommunity, openCommunityPanel, handleViewChange],
  );

  /** Back out of a community to the constellation it came from. */
  const leaveCommunity = useCallback(() => {
    // Drop any entry camera that was armed but never consumed (an entry whose
    // slice failed to arrive), so it cannot seed an unrelated later swap.
    sigmaRef.current?.setEntryCamera(null);
    setSelectedNodeId(null);
    setCommunityPanelId(null);
    setActiveCommunity(null);
    handleViewChange("architecture");
  }, [setActiveCommunity, handleViewChange]);

  // The community can also change from outside this component: the narrowing
  // control writes `?community=` directly, the scope switcher clears it, and a
  // shared link arrives with one already set. Those routes never run
  // `enterCommunity`/`leaveCommunity`, so a panel describing the community you
  // just left would stay in the rail, and an armed entry camera would survive
  // to seed an unrelated later graph swap.
  const appliedCommunityRef = useRef(activeCommunity);
  useEffect(() => {
    const previous = appliedCommunityRef.current;
    if (previous === activeCommunity) return;
    appliedCommunityRef.current = activeCommunity;
    // Only the panel for the community being left; `enterCommunity` has already
    // pointed it at the new one by the time this runs.
    setCommunityPanelId((open) => (open !== null && open === previous ? null : open));
    if (activeCommunity === null) sigmaRef.current?.setEntryCamera(null);
  }, [activeCommunity]);

  // ---- Derived state ----
  const isUnified = viewMode === "unified";
  // The "architecture" scope renders the radial community constellation.
  const isConstellation = viewMode === "architecture";

  // Constellation graph: one hub per community + repo-core, radial positions.
  const constellationSigmaGraph = useMemo(() => {
    if (!isConstellation || !constellationGraph) return null;
    return architectureToGraphology(
      constellationGraph,
      repoName ? { repoName } : {},
    );
  }, [isConstellation, constellationGraph, repoName]);

  // Ring radii for the depth-ring underlay (graph coordinates).
  const constellationRingRadii = useMemo(() => {
    // Not gated on the scope: the held frame during a drill-down is still the
    // constellation, and rings that vanish out from under it read as a glitch.
    if (!constellationGraph) return null;
    return computeRadialLayout(
      constellationGraph.nodes.map((n) => ({
        community_id: n.community_id,
        member_count: n.member_count,
        avg_pagerank: n.avg_pagerank,
      })),
    ).ringRadii;
  }, [constellationGraph]);

  const communityLabels = useMemo(() => {
    if (!communities) return undefined;
    const m = new Map<number, string>();
    for (const c of communities) m.set(c.community_id, c.label);
    return m;
  }, [communities]);

  // Constellation legend data: label + member count per community, ranked by
  // size, sourced from the architecture payload (independent of /communities).
  const constellationLegend = useMemo(() => {
    if (!constellationGraph) return undefined;
    return [...constellationGraph.nodes]
      .sort((a, b) => b.member_count - a.member_count)
      .map((n) => ({
        communityId: n.community_id,
        label: (n.label || `Community ${n.community_id}`),
        memberCount: n.member_count,
      }));
  }, [constellationGraph]);

  // Whether a community is actually being drawn: `?community=` only means
  // anything on a file-level scope, so a stale one carried into the
  // constellation is ignored rather than half-applied.
  const isInsideCommunity = !isConstellation && activeCommunity !== null;

  // "This community talks to that one; take me there." From the constellation
  // that means selecting the neighbour hub and framing it; from inside a
  // community it means entering the neighbour, because that is the altitude
  // the reader is already at.
  const handleNeighborSelect = useCallback(
    (cid: number) => {
      if (isInsideCommunity) enterCommunity(cid);
      else handleConstellationHubClick(cid);
    },
    [isInsideCommunity, enterCommunity, handleConstellationHubClick],
  );

  // The file-level payload *before* narrowing. The module group list is derived
  // from this, so choosing a module never empties the menu it came from.
  const scopeGraphData = useMemo(() => {
    switch (viewMode) {
      case "full":
      case "unified":
        return fullGraph ? { nodes: fullGraph.nodes, links: fullGraph.links } : undefined;
      // "architecture" renders the radial constellation, not a file graph.
      case "dead":
        return deadCodeGraph
          ? { nodes: deadCodeGraph.nodes, links: deadCodeGraph.links }
          : undefined;
      case "hotfiles":
        return hotFilesGraph
          ? { nodes: hotFilesGraph.nodes, links: hotFilesGraph.links }
          : undefined;
      default:
        return undefined;
    }
  }, [viewMode, fullGraph, deadCodeGraph, hotFilesGraph]);

  // Boundary stubs of the entered community: one-hop neighbours the slice
  // carries as context. Drawn smaller and desaturated, so the scoped graph has
  // an edge instead of trailing off into nothing.
  const sliceBoundaryIds = useMemo(() => {
    if (!isInsideCommunity || !communitySlice) return undefined;
    const ids = new Set<string>();
    for (const n of communitySlice.nodes) if (n.is_boundary) ids.add(n.node_id);
    return ids.size > 0 ? ids : undefined;
  }, [isInsideCommunity, communitySlice]);

  // What actually gets built and drawn. A community replaces the payload
  // outright (it is its own graph, not a view of the capped one); a module
  // narrows it. They are one axis and never both apply.
  const fileGraphData = useMemo(() => {
    if (isInsideCommunity) {
      return communitySlice
        ? { nodes: communitySlice.nodes, links: communitySlice.links }
        : undefined;
    }
    if (!scopeGraphData) return undefined;
    return filterGraphToModule(scopeGraphData, controlledActiveModule ?? null);
  }, [isInsideCommunity, communitySlice, scopeGraphData, controlledActiveModule]);

  // The whole-repo Files view is the overview: clusters, bands, and a file's
  // own edges on hover (see `sigma/files-overview.ts`). The dead/hot signals
  // keep the plain reading: their payloads are sparse by design, and dropping
  // unlinked files would drop most of a dead-code view.
  const isFilesOverview = viewMode === "full" && !isInsideCommunity;
  const overviewData = useMemo(
    () =>
      isFilesOverview && fileGraphData
        ? filterOverviewData(fileGraphData, { showExternal, pinned: initialSelectedNode })
        : undefined,
    [isFilesOverview, fileGraphData, showExternal, initialSelectedNode],
  );
  // What is built and drawn: the overview's filtered set, or the payload.
  const drawData = overviewData ?? fileGraphData;
  // The overview speaks community: clusters, bands, names and the key are all
  // community hues, so a Language reading (key 1, `?colorMode=language`) would
  // repaint the files alone and leave the rest unkeyed. It applies to the
  // other file readings; the Communities view never read it.
  const drawnColorMode: ColorMode = isFilesOverview ? "community" : colorMode;

  // Loading state
  const isLoading =
    isInsideCommunity ? !!isLoadingCommunitySlice :
    viewMode === "full" || viewMode === "unified" ? isLoadingFullGraph :
    viewMode === "architecture" ? !!isLoadingConstellationGraph :
    viewMode === "dead" ? isLoadingDeadCodeGraph :
    viewMode === "hotfiles" ? isLoadingHotFilesGraph : false;

  // Signal overlay node sets
  const hotNodeIds = useMemo(() => {
    if (!hotFilesGraph) return new Set<string>();
    return new Set(hotFilesGraph.nodes.map((n) => n.node_id));
  }, [hotFilesGraph]);

  const deadNodeIds = useMemo(() => {
    if (!deadCodeGraph) return new Set<string>();
    return new Set(deadCodeGraph.nodes.map((n) => n.node_id));
  }, [deadCodeGraph]);

  const hasDeadSignal = activeSignals.has("dead");
  const hasHotSignal = activeSignals.has("hot");

  // Repo-wide signal totals, when the backend provides them (the overlay's
  // own payload wins over the capped full graph). Distinguishes "the repo has
  // none" from "none survived the node cap" in the empty states below.
  const deadTotal =
    deadCodeGraph?.dead_total ?? fullGraph?.dead_total ?? null;
  const hotTotal = hotFilesGraph?.hot_total ?? fullGraph?.hot_total ?? null;

  // Build Graphology graph for Sigma rendering.
  //
  // Small file graphs build synchronously here. Large ones
  // (>= ASYNC_BUILD_THRESHOLD) are deferred off the critical path: this memo
  // returns null and the effect below constructs them in chunks, keeping the
  // loading state up until the first frame is ready.
  const syncSigmaGraph = useMemo(() => {
    const graphData = drawData;
    if (!graphData) return null;

    // Defer large file graphs to the async effect below.
    if (graphData.nodes.length >= ASYNC_BUILD_THRESHOLD) return null;

    const signals: { hotNodeIds?: Set<string>; deadNodeIds?: Set<string> } = {};
    if (hasHotSignal || isUnified) signals.hotNodeIds = hotNodeIds;
    if (hasDeadSignal || isUnified) signals.deadNodeIds = deadNodeIds;

    return fileGraphToGraphology(
      { nodes: graphData.nodes, links: graphData.links },
      { signals, ...(sliceBoundaryIds ? { boundaryNodeIds: sliceBoundaryIds } : {}) },
    );
  }, [drawData, hasHotSignal, hasDeadSignal, isUnified, hotNodeIds, deadNodeIds, sliceBoundaryIds]);

  // Async-built file graph for large graphs (built in chunks off the main
  // thread critical path). Null while building / when the sync path applies.
  const [asyncSigmaGraph, setAsyncSigmaGraph] = useState<GraphologyGraph<
    SigmaNodeAttributes,
    SigmaEdgeAttributes
  > | null>(null);
  const [isBuildingGraph, setIsBuildingGraph] = useState(false);

  const needsAsyncBuild =
    !!drawData && drawData.nodes.length >= ASYNC_BUILD_THRESHOLD;

  // `isBuildingGraph` is only raised *inside* the effect below, which React
  // runs after it has already painted. So on the commit where an async build
  // first becomes necessary — the fetch has landed, the build has not started
  // — every loading flag reads false while `sigmaGraph` is still null, and the
  // canvas paints its "No graph data" empty state for a frame. Deriving the
  // wait during render closes the gap: any repo above ASYNC_BUILD_THRESHOLD
  // (1,000 nodes) hit this on every full / dead / hot load.
  const isAwaitingAsyncBuild = needsAsyncBuild && !asyncSigmaGraph;

  useEffect(() => {
    if (!needsAsyncBuild || !drawData) {
      setAsyncSigmaGraph(null);
      setIsBuildingGraph(false);
      return;
    }

    let cancelled = false;
    setIsBuildingGraph(true);

    const signals: { hotNodeIds?: Set<string>; deadNodeIds?: Set<string> } = {};
    if (hasHotSignal || isUnified) signals.hotNodeIds = hotNodeIds;
    if (hasDeadSignal || isUnified) signals.deadNodeIds = deadNodeIds;

    void fileGraphToGraphologyAsync(
      { nodes: drawData.nodes, links: drawData.links },
      { signals, ...(sliceBoundaryIds ? { boundaryNodeIds: sliceBoundaryIds } : {}) },
    ).then((graph) => {
      if (cancelled) return;
      setAsyncSigmaGraph(graph);
      setIsBuildingGraph(false);
    });

    return () => {
      cancelled = true;
    };
  }, [needsAsyncBuild, drawData, hasHotSignal, hasDeadSignal, isUnified, hotNodeIds, deadNodeIds, sliceBoundaryIds]);

  const builtFileGraph = syncSigmaGraph ?? asyncSigmaGraph;
  // The overview lays out the graph it was built from, once per build. It
  // mutates positions in place and is idempotent (React may run this twice),
  // and it runs before Sigma is handed the graph, so no frame shows the seed.
  const sigmaGraph = useMemo(() => {
    if (isConstellation) return constellationSigmaGraph;
    if (builtFileGraph && isFilesOverview) layoutFilesOverview(builtFileGraph);
    return builtFileGraph;
  }, [isConstellation, constellationSigmaGraph, builtFileGraph, isFilesOverview]);

  // Entering a community swaps the payload, and the slice is a round trip.
  // Blanking to a skeleton in between would unmount the renderer, and with it
  // the camera that makes the drill-down read as one movement rather than two
  // pages. So the last frame is held until the slice lands, and only for that
  // transition — every other empty graph still reports itself honestly.
  const heldGraphRef = useRef<GraphologyGraph<
    SigmaNodeAttributes,
    SigmaEdgeAttributes
  > | null>(null);
  if (sigmaGraph) heldGraphRef.current = sigmaGraph;
  // Gated on the fetch actually being in flight. Holding on `!communitySlice`
  // alone meant a *failed* slice pinned the previous frame forever: SWR leaves
  // `data` undefined and `isLoading` false between retries, so the constellation
  // stayed drawn under a breadcrumb and a description both asserting a scoped
  // file graph, with no error and no empty state anywhere.
  const isEnteringCommunity =
    isInsideCommunity && !communitySlice && !!isLoadingCommunitySlice;
  const displayGraph =
    sigmaGraph ?? (isEnteringCommunity ? heldGraphRef.current : null);

  // Community colours keyed by label rather than by id, which is a size rank
  // and renumbers between indexes. See `community-colors.ts`. The summary list
  // covers both scopes and the constellation payload fills in what it lacks.
  // The drawn graph fills in the rest: a community on the canvas that neither
  // lists (below the summary's floor, or before it has loaded) is keyed by its
  // best-connected drawn file, so it still takes a free family instead of
  // falling back to `id % 12` on top of one a listed community holds.
  const colorSlots = useMemo(() => {
    const entries: { communityId: number; label: string; size: number }[] = [];
    const seen = new Set<number>();
    for (const c of communities ?? []) {
      seen.add(c.community_id);
      entries.push({ communityId: c.community_id, label: c.label, size: c.member_count });
    }
    for (const n of constellationGraph?.nodes ?? []) {
      if (seen.has(n.community_id)) continue;
      seen.add(n.community_id);
      entries.push({ communityId: n.community_id, label: n.label ?? "", size: n.member_count });
    }
    if (displayGraph && !isConstellation) {
      const drawn = new Map<number, { top: string; rank: number; size: number }>();
      displayGraph.forEachNode((node, a) => {
        if (a.nodeType !== "file" || seen.has(a.communityId)) return;
        const d = drawn.get(a.communityId);
        if (!d) drawn.set(a.communityId, { top: node, rank: a.pagerank, size: 1 });
        else {
          d.size++;
          if (a.pagerank > d.rank) {
            d.top = node;
            d.rank = a.pagerank;
          }
        }
      });
      for (const [communityId, d] of drawn) {
        entries.push({ communityId, label: d.top, size: d.size });
      }
    }
    return entries.length > 0 ? communityColorSlots(entries) : null;
  }, [communities, constellationGraph, displayGraph, isConstellation]);

  const { hiddenNodes, isActive: isEgoActive, visibleCount: egoVisibleCount } = useEgoFilter({
    graph: displayGraph,
    selectedNodeId,
    depth: egoDepth,
  });

  // Node data maps (sorted metrics moved into GraphInspectionPanel)
  const sigmaNodeMaps = useMemo(() => {
    if (!displayGraph) return null;

    const fileMap = new Map<string, FileNodeData>();
    const modMap = new Map<string, ModuleNodeData>();

    displayGraph.forEachNode((nodeId, attrs) => {
      if (attrs.nodeType === "file") {
        const fileData: FileNodeData = {
          nodeType: "file",
          label: attrs.label,
          fullPath: attrs.fullPath,
          language: attrs.language,
          symbolCount: attrs.symbolCount,
          pagerank: attrs.pagerank,
          betweenness: attrs.betweenness,
          communityId: attrs.communityId,
          isTest: attrs.isTest,
          isEntryPoint: attrs.isEntryPoint,
          hasDoc: attrs.hasDoc,
        };
        if (attrs.isHotspot) fileData.isHotspot = true;
        if (attrs.isDead) fileData.isDead = true;
        if (attrs.hasDecision) fileData.hasDecision = true;
        fileMap.set(nodeId, fileData);
      } else if (attrs.nodeType === "module") {
        modMap.set(nodeId, {
          nodeType: "module",
          label: attrs.label,
          fullPath: attrs.fullPath,
          fileCount: attrs.fileCount ?? 0,
          symbolCount: attrs.symbolCount,
          avgPagerank: attrs.avgPagerank ?? 0,
          docCoveragePct: attrs.docCoveragePct ?? 0,
          hotspotCount: attrs.hotspotCount ?? 0,
          deadCount: attrs.deadCount ?? 0,
          hasDecision: attrs.hasDecision ?? false,
          primaryOwner: attrs.primaryOwner ?? null,
          dominantCommunityId: attrs.dominantCommunityId,
        });
      }
    });

    return { fileMap, modMap };
  }, [displayGraph]);

  const effectiveNodeDataMap = sigmaNodeMaps?.fileMap ?? new Map<string, FileNodeData>();
  const effectiveModuleDataMap = sigmaNodeMaps?.modMap ?? new Map<string, ModuleNodeData>();

  // How many flagged nodes actually made it into the rendered graph — paired
  // with the repo-wide totals to caption the dead/hot views honestly.
  const overlayStats = useMemo(() => {
    if (!displayGraph) return null;
    let deadInView = 0;
    let hotInView = 0;
    displayGraph.forEachNode((_, attrs) => {
      if (attrs.isDead) deadInView++;
      if (attrs.isHotspot) hotInView++;
    });
    return { deadInView, hotInView };
  }, [displayGraph]);

  // A community slice is its own payload and was never filtered to dead or hot
  // files, so the signal captions must not describe it. Reachable from
  // `?view=files&signal=dead` plus a community pick.
  const isDeadView =
    !isInsideCommunity && (viewMode === "dead" || viewMode === "unified");
  const isHotView =
    !isInsideCommunity && (viewMode === "hotfiles" || viewMode === "unified");

  // Trace nodes of the selected execution flow that fell outside the loaded
  // node set — highlighting/focus silently no-op for them, so tell the user.
  const activeFlowMissingCount = useMemo(() => {
    if (activeFlowIdx === null || !executionFlows || !displayGraph) return 0;
    const flow = executionFlows.flows[activeFlowIdx];
    if (!flow) return 0;
    return traceToFileTrace(flow.trace).filter((id) => !displayGraph.hasNode(id)).length;
  }, [activeFlowIdx, executionFlows, displayGraph]);

  // Empty-state copy for a dead/hot view that resolved to zero nodes. Two
  // different failure modes deserve two different messages: the repo really
  // has no flagged files, vs the flagged files exist but fell outside the
  // capped node selection.
  const overlayEmptyState = (() => {
    if (!isDeadView && !isHotView) return null;
    const kind = isDeadView && isHotView ? "dead or hot" : isDeadView ? "dead" : "hot";
    const total = isDeadView && isHotView ? null : isDeadView ? deadTotal : hotTotal;
    if (total === 0) {
      return {
        title: `No ${kind} files in this repo`,
        description:
          kind === "dead"
            ? "No open dead-code findings — nothing to overlay."
            : "No files are flagged as hotspots — nothing to overlay.",
      };
    }
    if (total != null && total > 0) {
      return {
        title: `${kind === "dead" ? "Dead" : "Hot"} files are outside the loaded view`,
        description: `None of the ${total} ${kind} files are in the loaded node set. Load more nodes from the banner, or narrow the scope to bring them in.`,
      };
    }
    return {
      title: `No ${kind} files in this view`,
      description:
        "The repo may have none, or they may fall outside the loaded node set.",
    };
  })();

  const panToNode = useCallback((nodeId: string) => {
    sigmaRef.current?.focusNode(nodeId);
  }, []);

  // Search (Fuse index + debounced query + result navigation)
  const { searchQuery, setSearchQuery, searchResults, searchDimmedNodes, handleSearchKeyDown } =
    useGraphSearch({ sigmaGraph: displayGraph, hideTests, panToNode, setSelectedNodeId });

  // Community filter (active communities + dimming + legend toggles)
  const {
    activeCommunities,
    communityDimmedNodes,
    drawnCommunityIds,
    handleCommunityToggle,
    handleToggleAllCommunities,
  } = useCommunityFilter(displayGraph);

  // Module groups, offered to the host's narrowing control. Derived from the
  // scope's *unfiltered* payload: the filter now removes nodes rather than
  // dimming them, so deriving the menu from the drawn graph would leave one
  // option in it the moment you used it.
  const { moduleGroups } = useModuleFilter(
    isInsideCommunity ? undefined : scopeGraphData?.nodes,
    controlledActiveModule ?? null,
  );
  useEffect(() => {
    onModuleGroupsChange?.(moduleGroups);
  }, [moduleGroups, onModuleGroupsChange]);

  // Flow index whose trace head has already been focused, so the deferred
  // re-focus below fires at most once per selection and never re-steers the
  // camera on later graph changes while the same flow stays active.
  const flowFocusedRef = useRef<number | null>(null);
  // Live graph handle for the focus timer (the effect below deliberately
  // keeps displayGraph out of its deps).
  const drawnGraphRef = useRef(displayGraph);
  drawnGraphRef.current = displayGraph;

  // Execution flow highlighting
  useEffect(() => {
    if (activeFlowIdx === null || !executionFlows) {
      if (activeFlowIdx === null && showFlows) {
        setHighlightedPath(new Set());
        setHighlightedEdges(new Set());
      }
      return;
    }
    const flow = executionFlows.flows[activeFlowIdx];
    if (!flow) return;
    const fileTrace = traceToFileTrace(flow.trace);
    setHighlightedPath(new Set(fileTrace));
    setHighlightedEdges(traceToEdgeKeys(fileTrace));

    clearTimeout(focusTimerRef.current);
    focusTimerRef.current = setTimeout(() => {
      focusTimerRef.current = undefined;
      const firstNode = fileTrace[0];
      if (!firstNode) return;
      if (drawnGraphRef.current?.hasNode(firstNode)) {
        flowFocusedRef.current = activeFlowIdx;
        sigmaRef.current?.focusNode(firstNode);
      }
      // Node not loaded yet (module → full jump still fetching): the
      // deferred-focus effect below picks it up once the graph gains it.
    }, 800);
    return () => clearTimeout(focusTimerRef.current);
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [activeFlowIdx, executionFlows]);

  // Deferred flow focus: selecting a flow from the module overview kicks off
  // the full-graph fetch, which can land after the 800ms timer above already
  // fired against a graph without the trace head. Focus once when the graph
  // gains the node; while the timer is still pending it stays the fast path.
  useEffect(() => {
    if (activeFlowIdx === null) {
      flowFocusedRef.current = null;
      return;
    }
    if (flowFocusedRef.current === activeFlowIdx) return;
    if (focusTimerRef.current !== undefined) return;
    const trace = executionFlows?.flows[activeFlowIdx]?.trace;
    const firstNode = trace ? traceToFileTrace(trace)[0] : undefined;
    if (!firstNode || !displayGraph?.hasNode(firstNode)) return;
    flowFocusedRef.current = activeFlowIdx;
    sigmaRef.current?.focusNode(firstNode);
  }, [activeFlowIdx, executionFlows, displayGraph]);

  // ---- Handlers ----

  // Unified grammar — DOUBLE CLICK = drill deeper (all views):
  //   hub       → toggle the radial blossom (expand eases the camera onto it)
  //   file/sat. → open the doc panel
  //   core      → no-op (Sigma's default camera zoom is allowed)
  // Returns true when an action ran so the canvas suppresses Sigma's default
  // double-click zoom; core returns void so the zoom-jump is kept.
  const handleSigmaDoubleClick = useCallback(
    (nodeId: string, nodeType: string): boolean | void => {
      if (nodeType === "hub" && displayGraph?.hasNode(nodeId)) {
        const cid = displayGraph.getNodeAttribute(nodeId, "communityId");
        if (typeof cid === "number" && cid >= 0) {
          enterCommunity(cid);
          return true;
        }
        return;
      }
      if (nodeType === "core") return;
      onNodeViewDocs?.(nodeId);
      return true;
    },
    [onNodeViewDocs, displayGraph, enterCommunity],
  );

  // Unified grammar — SINGLE CLICK = select + inspect (never structural):
  //   file/module → select (no expansion; drill-down moved to double-click)
  //   hub         → select + focus + open the community panel (NO expand)
  //   core        → no-op
  // Clicking an already-selected node is a no-op (keeps it selected); the two
  // pre-clicks Sigma fires before a double-click therefore can't churn the
  // selection. Deselection happens via stage click or Esc.
  const handleSigmaNodeClick = useCallback(
    (nodeId: string, nodeType: string) => {
      if (nodeType === "core") return;
      if (selectedNodeId === nodeId) return;
      if (nodeType === "hub" && displayGraph?.hasNode(nodeId)) {
        const cid = displayGraph.getNodeAttribute(nodeId, "communityId");
        // The "not grouped" disc is a list, not a community: it opens its panel
        // without being selected, since selection dims everything it does not
        // link to, which is everything.
        if (cid === UNCLUSTERED_COMMUNITY_ID) {
          setCommunityPanelId(cid);
          return;
        }
        if (typeof cid === "number" && cid >= 0) {
          setSelectedNodeId(nodeId);
          sigmaRef.current?.focusNode(nodeId, HUB_FOCUS_RATIO);
          openCommunityPanel(cid);
          return;
        }
      }
      setSelectedNodeId(nodeId);
      // The community panel describes a hub; selecting a file replaces it in
      // the rail rather than outranking the inspector forever.
      setCommunityPanelId(null);
    },
    [selectedNodeId, displayGraph, openCommunityPanel],
  );

  const handleSigmaNodeContextMenu = useCallback(
    (event: MouseEvent, nodeId: string, nodeType: string) => {
      setCtxMenu({
        x: event.clientX,
        y: event.clientY,
        nodeId,
        nodeType: nodeType === "module" ? "moduleGroup" : "fileNode",
      });
    },
    [setCtxMenu],
  );

  // Esc dismisses the top UI layer first (unified grammar): clear an open
  // selection/panel before collapsing a constellation hub. Each press peels one
  // layer; the keyboard hook's default clear only runs once nothing is open.
  //   1. node selected OR community panel open → clear selection + panel + ego
  //   2. else any hub expanded → collapse the most recent
  //   3. else → fall through to the default clear (search, ctx menu, …)
  const handleEscapeCollapse = useCallback((): boolean => {
    if (showShortcutHelp) {
      setShowShortcutHelp(false);
      return true;
    }
    if (showFlows) {
      setShowFlows(false);
      setActiveFlowIdx(null);
      return true;
    }
    if (selectedNodeId !== null || communityPanelId !== null) {
      setSelectedNodeId(null);
      setCommunityPanelId(null);
      setEgoDepth(0);
      return true;
    }
    if (isInsideCommunity) {
      leaveCommunity();
      return true;
    }
    return false;
  }, [showShortcutHelp, selectedNodeId, communityPanelId, isInsideCommunity, leaveCommunity]);

  const handleToggleShortcutHelp = useCallback(() => {
    setShowShortcutHelp((s) => !s);
  }, []);

  // Global keyboard shortcuts (f/Escape/1-3//, cmd+k, ?)
  useGraphKeyboardShortcuts({
    sigmaRef,
    setSelectedNodeId,
    setEgoDepth,
    setSearchQuery,
    setCtxMenu,
    setCommunityPanelId,
    setColorMode,
    onEscape: handleEscapeCollapse,
    onToggleHelp: handleToggleShortcutHelp,
  });

  const handlePathFound = useCallback(
    (pathNodes: string[]) => {
      setHighlightedPath(new Set(pathNodes));
      setHighlightedEdges(traceToEdgeKeys(pathNodes));
      // The path endpoint is repo-wide while the canvas may be a module filter
      // or one community, so a path can legitimately run through files this
      // view does not draw. `focusNode` no-ops on those, which read as the
      // control doing nothing. Focus the first file that IS here, and say how
      // many are not — the same courtesy the flows panel already extends.
      const graph = drawnGraphRef.current;
      const drawn = graph ? pathNodes.filter((id) => graph.hasNode(id)) : pathNodes;
      const missing = pathNodes.length - drawn.length;
      setPathNotice(
        missing > 0
          ? `${missing} of ${pathNodes.length} files on this path are outside the current view.`
          : null,
      );
      clearTimeout(focusTimerRef.current);
      focusTimerRef.current = setTimeout(() => {
        if (drawn.length > 0) {
          sigmaRef.current?.focusNode(drawn[0]!);
        }
      }, 800);
    },
    [],
  );

  const handlePathClear = useCallback(() => {
    setHighlightedPath(new Set());
    setHighlightedEdges(new Set());
    setPathNotice(null);
  }, []);

  // Everything a scope change has to clear, in one place. Scope can now arrive
  // from the host (the section-header switcher, URL-synced) as well as from the
  // toolbar's overlay buttons, so this reacts to the resolved value rather than
  // hanging off one of the two call sites — hooking it to the click handler
  // alone would leave a stale selection and a stale layout mode behind whenever
  // the host drove the change.
  const appliedViewModeRef = useRef(viewMode);
  useEffect(() => {
    if (appliedViewModeRef.current === viewMode) return;
    appliedViewModeRef.current = viewMode;
    setHighlightedPath(new Set());
    setHighlightedEdges(new Set());
    // Measured against the graph being replaced, so it retires with it.
    setPathNotice(null);
    setSelectedNodeId(null);
    // Back to the constellation by any route (the switcher, a legacy link):
    // the drill-down is a file-scope state and does not survive leaving it.
    if (viewMode === "architecture") setActiveCommunity(null);
  }, [viewMode, setActiveCommunity]);

  const handleEdgeTypeToggle = useCallback((edgeType: string) => {
    setVisibleEdgeTypes((prev) => {
      const next = new Set(prev);
      if (next.has(edgeType)) {
        if (next.size > 1) next.delete(edgeType);
      } else {
        next.add(edgeType);
      }
      return next;
    });
  }, []);

  // A rebuild can drop the selected node (module expanded into files) — clear
  // the selection then, or the reducer dims the whole canvas around a ghost.
  useEffect(() => {
    if (selectedNodeId && displayGraph && !displayGraph.hasNode(selectedNodeId)) {
      setSelectedNodeId(null);
    }
  }, [displayGraph, selectedNodeId]);

  const initialNodeApplied = useRef(false);
  useEffect(() => {
    if (initialNodeApplied.current || !initialSelectedNode || !displayGraph) return;
    if (displayGraph.hasNode(initialSelectedNode)) {
      initialNodeApplied.current = true;
      setSelectedNodeId(initialSelectedNode);
      setTimeout(() => panToNode(initialSelectedNode), 300);
    }
  }, [initialSelectedNode, displayGraph, panToNode]);

  const handleInspectNavigate = useCallback((nodeId: string) => {
    setSelectedNodeId(nodeId);
    panToNode(nodeId);
  }, [panToNode]);

  const handleInspectFindPath = useCallback(() => {
    if (selectedNodeId) {
      setPathFrom(selectedNodeId);
      setShowPathFinder(true);
      setShowFlows(false);
      setActiveFlowIdx(null);
    }
  }, [selectedNodeId]);

  // Context menu actions
  const handleCtxViewDocs = useCallback(() => {
    if (ctxMenu) onNodeViewDocs?.(ctxMenu.nodeId);
    setCtxMenu(null);
  }, [ctxMenu, onNodeViewDocs, setCtxMenu]);

  const handleCtxExplore = useCallback(() => {
    if (ctxMenu) onNodeClick?.(ctxMenu.nodeId, ctxMenu.nodeType);
    setCtxMenu(null);
  }, [ctxMenu, onNodeClick, setCtxMenu]);

  const handleCtxPathFrom = useCallback(() => {
    if (ctxMenu) {
      setPathFrom(ctxMenu.nodeId);
      setShowPathFinder(true);
      setShowFlows(false);
      setActiveFlowIdx(null);
    }
    setCtxMenu(null);
  }, [ctxMenu, setCtxMenu]);

  const handleCtxPathTo = useCallback(() => {
    if (ctxMenu) {
      setPathTo(ctxMenu.nodeId);
      setShowPathFinder(true);
      setShowFlows(false);
      setActiveFlowIdx(null);
    }
    setCtxMenu(null);
  }, [ctxMenu, setCtxMenu]);

  // Both of these are read far below, next to the key they feed. They are
  // declared here because the skeleton branch that follows returns early, and a
  // hook after it does not run on the loading pass — which changes the hook
  // count between renders and takes the whole canvas down.

  // What the key reports. `displayGraph.size` counts every edge in the graph
  // including the kinds the edge filter is hiding, which is how a slice showing
  // only its exits could still claim 553 edges. Reconciles the edge filter
  // only: the ego filter hides nodes at the canvas rather than in the graph,
  // and reports its own count in the status row beside this.
  const visibleEdgeCount = useMemo(() => {
    if (!displayGraph) return 0;
    let n = 0;
    displayGraph.forEachEdge((_, attrs) => {
      if (visibleEdgeTypes.has(attrs.edgeKind)) n++;
    });
    return n;
  }, [displayGraph, visibleEdgeTypes]);

  // The overview's key. Memoized with the trailing button so the memoized
  // legend does not re-render with every render of this shell.
  const overviewLegend = useMemo(() => {
    if (!overviewData || !displayGraph) return undefined;
    // Dependencies only: co-change and low-confidence edges are revealed on a
    // focused file, never counted as the map's structure.
    let dependencies = 0;
    displayGraph.forEachEdge((_, attrs) => {
      if (
        (attrs.edgeKind === "internal" || attrs.edgeKind === "crossCommunity") &&
        visibleEdgeTypes.has(attrs.edgeKind)
      ) {
        dependencies++;
      }
    });
    return {
      hiddenExternal: overviewData.hiddenExternal,
      shownExternal: overviewData.shownExternal,
      hiddenUnlinked: overviewData.hiddenUnlinked,
      omittedLinks: getOverviewMeta(displayGraph)?.omittedPairs ?? 0,
      dependencies,
      showExternal,
      onShowExternalChange: setShowExternal,
    };
  }, [overviewData, displayGraph, visibleEdgeTypes, showExternal, setShowExternal]);

  // Moved out of the header row, which now carries only what changes the
  // picture. `?` still opens it from anywhere.
  const shortcutsButton = useMemo(
    () => (
      <button
        type="button"
        onClick={handleToggleShortcutHelp}
        title="Keyboard shortcuts (?)"
        aria-label="Keyboard shortcuts"
        className="flex h-7 w-7 items-center justify-center rounded-md text-[var(--color-text-secondary)] transition-colors hover:bg-[var(--color-bg-wash-hover)] hover:text-[var(--color-text-primary)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-focus-ring)]"
      >
        <HelpCircle className="h-3.5 w-3.5" />
      </button>
    ),
    [handleToggleShortcutHelp],
  );

  // Members vs the one-hop stubs around them, from the same payload the banner
  // counts, so the two figures on screen cannot disagree.
  const sliceCounts = useMemo(() => {
    if (!communitySlice) return undefined;
    const members = communitySlice.nodes.filter((n) => !n.is_boundary).length;
    return { members, boundary: communitySlice.nodes.length - members };
  }, [communitySlice]);

  // No hooks below this line.
  if (
    (isLoading || isAwaitingAsyncBuild || isBuildingGraph) &&
    !displayGraph
  )
    return <Skeleton className="h-full w-full rounded-lg" />;

  const showOverlayCounts =
    !!displayGraph && displayGraph.order > 0 && (isDeadView || isHotView);
  const hasCanvasStatus =
    (isEgoActive && !!selectedNodeId) || (showOverlayCounts && !!overlayStats);

  const inspectedFile = selectedNodeId
    ? effectiveNodeDataMap.get(selectedNodeId)
    : undefined;
  const inspectedNode = selectedNodeId
    ? (inspectedFile ?? effectiveModuleDataMap.get(selectedNodeId))
    : undefined;

  // One rail, most-explicit intent first. Path finder and flows are opened by
  // hand, docs are asked for by name, a community panel follows a hub click,
  // and the inspector is merely a selection. Three panels used to stack on the
  // same edge with a host callback arbitrating between them.
  const railContent = showPathFinder && renderPathFinder
    ? renderPathFinder({
        initialFrom: pathFrom,
        initialTo: pathTo,
        onPathFound: handlePathFound,
        onClear: handlePathClear,
        onClose: () => {
          setShowPathFinder(false);
          setPathNotice(null);
        },
      })
    : showFlows
      ? executionFlows && executionFlows.flows.length > 0
        ? (
          <GraphFlowPanel
            flows={executionFlows}
            activeFlowIdx={activeFlowIdx}
            onSelect={handleFlowSelect}
            onClose={handleFlowsClose}
            missingCount={activeFlowMissingCount}
          />
        )
        : (
          // The trace fetch is deferred until this panel opens, so the first
          // open has nothing yet. Saying so beats an empty rail.
          <div className="p-4 text-xs text-[var(--color-text-secondary)]">
            {executionFlows ? "No execution flows for this scope." : "Loading execution flows…"}
          </div>
        )
      : rail
        ? rail
        : communityPanelId === UNCLUSTERED_COMMUNITY_ID && constellationGraph?.unclustered
          ? (
            <GraphUnclusteredPanel
              unclustered={constellationGraph.unclustered}
              onClose={() => setCommunityPanelId(null)}
              fileHrefFor={fileHrefFor}
            />
          )
        : communityPanelId !== null &&
            communityPanelId !== UNCLUSTERED_COMMUNITY_ID &&
            renderCommunityPanel
          ? renderCommunityPanel({
              communityId: communityPanelId,
              onClose: () => setCommunityPanelId(null),
              onEnterCommunity: () => enterCommunity(communityPanelId),
              onNeighborSelect: handleNeighborSelect,
            })
          : selectedNodeId && inspectedNode
            ? (
              <GraphInspectionPanel
                nodeId={selectedNodeId}
                data={inspectedNode}
                graph={displayGraph}
                allNodes={effectiveNodeDataMap}
                communityLabel={
                  inspectedFile
                    ? communityLabels?.get(inspectedFile.communityId)
                    : undefined
                }
                onClose={() => { setSelectedNodeId(null); }}
                onNavigateToNode={handleInspectNavigate}
                onViewDocs={() => { onNodeViewDocs?.(selectedNodeId); }}
                onViewSymbols={
                  inspectedFile && onNodeViewSymbols
                    ? () => { onNodeViewSymbols(selectedNodeId); }
                    : undefined
                }
                filePageHref={inspectedFile ? fileHrefFor?.(selectedNodeId) : undefined}
                healthHref={inspectedFile ? fileHealthHrefFor?.(selectedNodeId) : undefined}
                historyHref={inspectedFile ? fileHistoryHrefFor?.(selectedNodeId) : undefined}
                decisionsHref={
                  inspectedFile ? fileDecisionsHrefFor?.(selectedNodeId) : undefined
                }
                deadCodeHref={deadCodeHref}
                onFindPath={handleInspectFindPath}
                isModuleExpanded={false}
                egoDepth={egoDepth}
                onEgoDepthChange={setEgoDepth}
                egoVisibleCount={egoVisibleCount}
              />
            )
            : undefined;

  // Inside a community the host's own description describes the wrong thing:
  // it was written for "every file in the repo". The scoped one is stated here
  // because only this component knows the drill-down happened.
  // The slice is capped server-side (SLICE_MEMBER_CAP), and the boundary stubs
  // are drawn but are not members. Both make the drawn node count disagree with
  // "the files in X", and the repo-wide truncation banner is deliberately off
  // in this scope, so the honest sentence has to come from here.
  const sliceNotice = (() => {
    if (!isInsideCommunity || !communitySlice) return null;
    const drawn = communitySlice.nodes.filter((n) => !n.is_boundary).length;
    const stubs = communitySlice.nodes.length - drawn;
    const parts: string[] = [];
    if (communitySlice.truncated && communitySlice.member_count > drawn) {
      parts.push(
        `Showing the ${drawn} most connected of ${communitySlice.member_count} files in this group`,
      );
    } else {
      parts.push(`Showing all ${drawn} files in this group`);
    }
    if (stubs > 0) {
      // Where the faded ring is explained. It used to be said twice: here as a
      // count and again in the description as prose about "faded nodes".
      parts.push(
        `plus ${stubs} faded file${stubs === 1 ? "" : "s"} outside it that they reach`,
      );
    }
    const hidden = communitySlice.hidden_member_count ?? 0;
    if (hidden > 0) {
      parts.push(`${hidden} more hidden by the file filter`);
    }
    return `${parts.join(", ")}.`;
  })();

  const activeCommunityLabel =
    activeCommunity !== null
      ? (communityLabels?.get(activeCommunity) ?? copy.communityFallback(activeCommunity))
      : null;

  return (
    <CommunityColorContext.Provider value={colorSlots}>
    <GraphCanvasShell
      breadcrumb={
        isInsideCommunity && activeCommunityLabel ? (
          <GraphScopeBreadcrumb
            rootLabel={repoName ?? copy.allCommunities}
            leafLabel={activeCommunityLabel}
            onRoot={leaveCommunity}
          />
        ) : undefined
      }
      description={
        // The breadcrumb above already names the community and carries the way
        // out, and the narrowing select names it a third time. Prose repeating
        // it is noise, so this says what the picture is, not what it is called.
        isInsideCommunity
          ? `${copy.insideCommunity}${onNodeViewDocs ? ` ${copy.openFileHint}` : ""}`
          : description
      }
      titleActions={
        <div className="flex flex-wrap items-center justify-end gap-2">
          {headerActions}
          {population && onPopulationChange && (isConstellation || isInsideCommunity) && (
            <GraphPopulationControl
              population={population}
              breakdown={constellationGraph?.population}
              onChange={onPopulationChange}
              copy={copy.population}
            />
          )}
          <GraphToolbar
            viewMode={viewMode}
            showPathFinder={showPathFinder}
            pathFinderAvailable={Boolean(renderPathFinder)}
            onTogglePathFinder={() => {
              setShowPathFinder((s) => !s);
              setShowFlows(false);
              setActiveFlowIdx(null);
            }}
            showFlows={showFlows}
            onToggleFlows={() => {
              setShowFlows((s) => !s);
              setActiveFlowIdx(null);
              setShowPathFinder(false);
            }}
            searchQuery={searchQuery}
            onSearchChange={setSearchQuery}
            searchMatchCount={searchResults.length}
            searchTotalCount={displayGraph?.order ?? 0}
            onSearchKeyDown={handleSearchKeyDown}
            copy={copy.toolbar}
          />
        </div>
      }
      banner={
        banner || sliceNotice || pathNotice ? (
          <div className="space-y-2">
            {banner}
            {(sliceNotice || pathNotice) && (
              <p
                role="status"
                aria-live="polite"
                className="text-[11px] text-[var(--color-text-secondary)]"
              >
                {[sliceNotice, pathNotice].filter(Boolean).join(" ")}
              </p>
            )}
          </div>
        ) : undefined
      }
      rail={railContent}
      footer={
        <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2">
          <GraphLegend
            nodeCount={displayGraph?.order ?? 0}
            edgeCount={displayGraph?.size ?? 0}
            visibleEdgeCount={visibleEdgeCount}
            colorMode={drawnColorMode}
            viewMode={viewMode}
            {...(isInsideCommunity && activeCommunityLabel
              ? {
                  scopeLabel: activeCommunityLabel,
                  scopeCommunityId: activeCommunity ?? undefined,
                  sliceCounts,
                }
              : {})}
            nodeFilter={
              // Withdrawn inside a community: the slice endpoint returns the
              // whole community whatever the signal says, so the pill lit, the
              // URL changed and the canvas did not.
              isConstellation || isInsideCommunity ? undefined : (
                <GraphNodeFilter
                  viewMode={viewMode}
                  onViewChange={handleViewChange}
                  copy={copy.nodeFilter}
                />
              )
            }
            {...(communityLabels ? { communityLabels } : {})}
            onCommunityClick={openCommunityPanel}
            activeCommunities={activeCommunities ?? undefined}
            drawnCommunityIds={drawnCommunityIds}
            onCommunityToggle={handleCommunityToggle}
            onToggleAllCommunities={handleToggleAllCommunities}
            visibleEdgeTypes={isConstellation ? undefined : visibleEdgeTypes}
            onEdgeTypeToggle={isConstellation ? undefined : handleEdgeTypeToggle}
            graphTheme={graphTheme}
            constellationEntries={isConstellation ? constellationLegend : undefined}
            onConstellationHubClick={handleConstellationHubClick}
            constellationUnclustered={
              isConstellation && constellationGraph?.unclustered
                ? {
                    count: constellationGraph.unclustered.file_count,
                    onClick: () => handleConstellationHubClick(UNCLUSTERED_COMMUNITY_ID),
                  }
                : undefined
            }
            overview={overviewLegend}
            trailing={shortcutsButton}
            copy={copy.legend}
          />
          {hasCanvasStatus && (
            <div className="flex flex-wrap items-center gap-x-3 gap-y-1">
              {isEgoActive && selectedNodeId ? (
                <span className="flex items-center gap-2 text-[11px] text-[var(--color-accent-primary)]">
                  <span role="status" aria-live="polite">
                    Showing {egoVisibleCount} nodes within {egoDepth} hop{egoDepth === 1 ? "" : "s"} of{" "}
                    <span className="font-mono font-medium">{selectedNodeId.split("/").pop()}</span>
                  </span>
                  <button
                    onClick={() => setEgoDepth(0)}
                    className="rounded px-1 py-0.5 text-[var(--color-text-tertiary)] underline hover:text-[var(--color-text-primary)]"
                  >
                    Clear
                  </button>
                </span>
              ) : null}
              {showOverlayCounts && overlayStats && (
                <span role="status" aria-live="polite" className="flex flex-wrap items-center gap-x-3">
                  {isDeadView && (
                    <OverlayCountChip kind="dead" inView={overlayStats.deadInView} total={deadTotal} />
                  )}
                  {isHotView && (
                    <OverlayCountChip kind="hot" inView={overlayStats.hotInView} total={hotTotal} />
                  )}
                </span>
              )}
            </div>
          )}
        </div>
      }
      overlay={
        <>
          {ctxMenu && (
            <GraphContextMenu
              x={ctxMenu.x}
              y={ctxMenu.y}
              nodeId={ctxMenu.nodeId}
              isModule={ctxMenu.nodeType === "moduleGroup"}
              onViewDocs={handleCtxViewDocs}
              onExplore={handleCtxExplore}
              onPathFrom={handleCtxPathFrom}
              onPathTo={handleCtxPathTo}
            />
          )}
          {showShortcutHelp && (
            <GraphShortcutHelp onClose={() => setShowShortcutHelp(false)} />
          )}
        </>
      }
    >
      <div
        className="relative h-full w-full"
        style={{ touchAction: "none", ...(graphTheme === "dark" ? { background: "var(--color-bg-root)" } : {}) }}
        aria-label="Dependency graph"
      >
      {displayGraph && displayGraph.order > 0 ? (
        <SigmaCanvas
          ref={sigmaRef}
          graph={displayGraph}
          // The seed is the layout (see `buildFileGraph`): "force" only means
          // "not the constellation", and FA2 skips a presettled graph.
          layoutMode={isConstellation || isEnteringCommunity ? "radial" : "force"}
          viewMode={viewMode}
          selectedNodeId={selectedNodeId}
          highlightedPath={highlightedPath}
          highlightedEdges={highlightedEdges}
          searchDimmedNodes={searchDimmedNodes}
          communityDimmedNodes={communityDimmedNodes}
          colorMode={drawnColorMode}
          activeSignals={activeSignals}
          graphTheme={graphTheme}
          onNodeClick={handleSigmaNodeClick}
          onNodeDoubleClick={handleSigmaDoubleClick}
          onNodeContextMenu={handleSigmaNodeContextMenu}
          onStageClick={() => setSelectedNodeId(null)}
          reducedMotion={prefersReducedMotion}
          hiddenNodes={isEgoActive ? hiddenNodes : undefined}
          visibleEdgeTypes={visibleEdgeTypes}
          depthRingRadii={
            isConstellation || isEnteringCommunity ? constellationRingRadii : null
          }
          communityLabels={communityLabels}
          activeCommunities={activeCommunities}
        />
      ) : !isLoading ? (
        <div className="flex items-center justify-center h-full">
          <EmptyState
            title={overlayEmptyState?.title ?? "No graph data"}
            description={
              overlayEmptyState?.description ??
              "This scope came back with nothing to draw. Try another scope, or re-index the repo if it was added recently."
            }
          />
        </div>
      ) : null}
      </div>
    </GraphCanvasShell>
    </CommunityColorContext.Provider>
  );
}

/** Caption for a dead/hot view: "12 of 37 dead files in view" when the backend
 *  supplies repo-wide totals, or just the in-view count when it does not. */
function OverlayCountChip({
  kind,
  inView,
  total,
}: {
  kind: "dead" | "hot";
  inView: number;
  total: number | null;
}) {
  const noun = kind === "dead" ? "dead files" : "hot files";
  let text: string;
  if (total != null && inView < total) {
    text = `${inView} of ${total} ${noun} in view; the rest are outside the loaded node set`;
  } else if (total != null) {
    text = `Showing all ${total} ${noun}`;
  } else {
    text = `${inView} ${noun} in view`;
  }
  // No role here: the footer wrapper is already the live region, and nesting
  // one inside another gets the text announced twice.
  return <span className="text-[11px] text-[var(--color-text-secondary)]">{text}</span>;
}