Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(architecture): move map chrome off the canvas and give it a ground (#2102)
Raghav Chamadiyaad94390b0ea4
diff --git a/packages/ui/__tests__/graph/graph-flow.test.tsx b/packages/ui/__tests__/graph/graph-flow.test.tsxindex 00bdc0056..5755bff18 100644--- a/packages/ui/__tests__/graph/graph-flow.test.tsx+++ b/packages/ui/__tests__/graph/graph-flow.test.tsx@@ -58,14 +58,14 @@ describe("GraphFlow shell", () => {});// Uses "language" as the controlled value because it is the one that is not- // the default. This was "risk" until that lens was removed for painting- // `pagerank * 3` through unreachable thresholds; the assertion is about- // control flow, not about which lens, so it survives the swap unchanged.+ // the default. Rendered in the file scope: the constellation colours hubs by+ // family whatever colorMode says, so the control is not offered there.it("reflects a controlled colorMode and reports changes without self-updating", () => {const onColorModeChange = vi.fn();render(<GraphFlow{...baseProps}+ initialViewMode="full"colorMode="language"onColorModeChange={onColorModeChange}/>,@@ -88,7 +88,9 @@ describe("GraphFlow shell", () => {});it("tracks its own colorMode when uncontrolled (seeded by initialColorMode)", () => {- render(<GraphFlow {...baseProps} initialColorMode="language" />);+ render(+ <GraphFlow {...baseProps} initialViewMode="full" initialColorMode="language" />,+ );expect(screen.getByRole("button", { name: "Language" }).getAttribute("aria-pressed"),diff --git a/packages/ui/src/graph/graph-canvas-shell.tsx b/packages/ui/src/graph/graph-canvas-shell.tsxindex 9e7d67eac..595a86763 100644--- a/packages/ui/src/graph/graph-canvas-shell.tsx+++ b/packages/ui/src/graph/graph-canvas-shell.tsx@@ -5,26 +5,41 @@ import { cn } from "../lib/cn";export interface GraphCanvasShellProps {/** Optional one-line title rendered above the canvas (no second header band). */- title?: string;+ title?: string | undefined;/** Optional one-line description under the title. */- description?: string;- /** Right-aligned slot in the title row (e.g. a hint or a single action). */- titleActions?: React.ReactNode;+ description?: string | undefined;+ /** Right-aligned slot in the title row. Scope controls and the toolbar live+ * here rather than floating over the diagram. */+ titleActions?: React.ReactNode | undefined;/** A full-width banner slot above the canvas (e.g. truncation notice). */- banner?: React.ReactNode;+ banner?: React.ReactNode | undefined;/** The canvas itself (Sigma / ReactFlow host). Fills the remaining height. */children: React.ReactNode;- /** Overlays drawn on top of the canvas (panels, doc rails, modals). */- overlay?: React.ReactNode;- className?: string;+ /**+ * Inspector content. A grid peer of the canvas from `lg` up, so a panel can+ * never land on the map; below `lg` it becomes a bottom sheet over the canvas+ * rather than starving it of height. Render nothing when there is no+ * selection to explain and the canvas takes the full width.+ */+ rail?: React.ReactNode | undefined;+ /** Legend / key row, rendered as a caption under the canvas. */+ footer?: React.ReactNode | undefined;+ /**+ * Drawn on top of the canvas. Reserved for pointer-bound things: context+ * menus, hover cards, modals. Persistent chrome belongs in `titleActions`,+ * `footer` or `rail`.+ */+ overlay?: React.ReactNode | undefined;+ className?: string | undefined;}/**- * The single airy canvas container for every graph surface (Communities,- * Explore, the Knowledge Graph layers route, and Coupling). Replaces the- * per-view `rounded-lg border` frame and the double-header pattern: it owns at- * most ONE thin title row and lets the diagram breathe with no box outline or- * background fill behind it.+ * The single canvas container for every graph surface.+ *+ * Chrome goes around the map, not on it: controls in the title row, key+ * underneath, inspector as a grid peer. This mirrors `SystemMap`, the Code+ * Health triage view and the Knowledge Graph page, which all converged on the+ * same arrangement.*/export function GraphCanvasShell({title,@@ -32,6 +47,8 @@ export function GraphCanvasShell({titleActions,banner,children,+ rail,+ footer,overlay,className,}: GraphCanvasShellProps) {@@ -39,7 +56,7 @@ export function GraphCanvasShell({<div className={cn("flex h-full flex-col", className)}>{(title || description || titleActions) && (<div className="flex shrink-0 flex-wrap items-start justify-between gap-2 px-4 pt-3 sm:px-6">- <div className="min-w-0">+ <div className="min-w-0 max-w-2xl">{title && (<h2 className="text-sm font-semibold text-[var(--color-text-primary)]">{title}@@ -52,15 +69,42 @@ export function GraphCanvasShell({)}</div>{titleActions && (- <div className="flex shrink-0 items-center gap-2">{titleActions}</div>+ <div className="flex min-w-0 flex-wrap items-center justify-end gap-2">+ {titleActions}+ </div>)}</div>)}{banner && <div className="shrink-0 px-4 pt-3 sm:px-6">{banner}</div>}- <div className="relative min-h-0 flex-1 overflow-hidden">- {children}- {overlay}++ <div+ className={cn(+ "relative mt-3 grid min-h-0 flex-1",+ rail ? "lg:grid-cols-[minmax(0,1fr)_340px]" : "grid-cols-1",+ )}+ >+ {/* A floor, so a tall header or key row cannot squeeze the subject to+ nothing; the page scrolls instead. */}+ <div className="relative min-h-0 overflow-hidden max-lg:min-h-[22rem]">+ {children}+ {overlay}+ </div>+ {rail && (+ <aside+ className={cn(+ // Bottom sheet under lg so the canvas keeps its height on a+ // phone; a real grid column from lg up.+ "absolute inset-x-0 bottom-0 z-20 flex max-h-[70%] flex-col overflow-hidden",+ "rounded-t-xl border-t border-[var(--color-border-default)] bg-[var(--color-bg-surface)] shadow-xl shadow-black/20",+ "lg:static lg:max-h-none lg:rounded-none lg:border-t-0 lg:border-l lg:shadow-none",+ )}+ >+ {rail}+ </aside>+ )}</div>++ {footer && <div className="shrink-0 px-4 pb-3 pt-2 sm:px-6">{footer}</div>}</div>);}diff --git a/packages/ui/src/graph/graph-community-panel.tsx b/packages/ui/src/graph/graph-community-panel.tsxindex bb051c17c..db768934e 100644--- a/packages/ui/src/graph/graph-community-panel.tsx+++ b/packages/ui/src/graph/graph-community-panel.tsx@@ -32,7 +32,7 @@ export function GraphCommunityPanel({memberHref,}: GraphCommunityPanelProps) {return (- <div className="absolute right-0 top-0 bottom-0 w-full sm:w-[360px] border-l border-[var(--color-border-default)] bg-[var(--color-bg-surface)] z-20 flex flex-col shadow-lg shadow-black/20">+ <div className="flex h-full min-h-0 flex-col">{/* Header */}<div className="flex items-center justify-between px-4 py-3 border-b border-[var(--color-border-default)]"><div className="min-w-0">@@ -47,6 +47,7 @@ export function GraphCommunityPanel({</div><buttononClick={onClose}+ aria-label="Close community details"className="p-1 rounded hover:bg-[var(--color-bg-elevated)] transition-colors"><X className="h-4 w-4 text-[var(--color-text-tertiary)]" />diff --git a/packages/ui/src/graph/graph-doc-panel.tsx b/packages/ui/src/graph/graph-doc-panel.tsxindex 1a541a11d..a4a582635 100644--- a/packages/ui/src/graph/graph-doc-panel.tsx+++ b/packages/ui/src/graph/graph-doc-panel.tsx@@ -49,7 +49,7 @@ export function GraphDocPanel({}, [nodeId]);return (- <div className="absolute top-0 right-0 z-20 h-full w-[min(400px,calc(100vw-1.5rem))] flex flex-col bg-[var(--color-bg-surface)] border-l border-[var(--color-border-default)] shadow-2xl shadow-black/30">+ <div className="flex h-full min-h-0 flex-col">{/* Header */}<div className="flex items-center gap-2 px-4 py-3 border-b border-[var(--color-border-default)] shrink-0"><FileText className="h-4 w-4 text-[var(--color-accent-primary)] shrink-0" />@@ -75,6 +75,7 @@ export function GraphDocPanel({size="sm"variant="ghost"onClick={onClose}+ aria-label="Close documentation"className="h-6 w-6 p-0"><X className="h-3.5 w-3.5" />diff --git a/packages/ui/src/graph/graph-flow.tsx b/packages/ui/src/graph/graph-flow.tsxindex 4749831ea..cf28f78be 100644--- a/packages/ui/src/graph/graph-flow.tsx+++ b/packages/ui/src/graph/graph-flow.tsx@@ -32,6 +32,7 @@ import { useModuleFilter } from "./use-module-filter";import { useGraphKeyboardShortcuts } from "./use-graph-keyboard-shortcuts";import { GraphToolbar, type ColorMode, type ViewMode, type LayoutMode, type GraphTheme } from "./graph-toolbar";import { GraphLegend } from "./graph-legend";+import { GraphCanvasShell } from "./graph-canvas-shell";import { GraphContextMenu } from "./graph-context-menu";import { GraphInspectionPanel } from "./graph-inspection-panel";import { GraphFlowPanel } from "./graph-flow-panel";@@ -62,8 +63,12 @@ import { useEgoFilter } from "./sigma/use-ego-filter";export interface GraphFlowProps {fullGraph: GraphExport | undefined;isLoadingFullGraph: boolean;- architectureGraph: GraphExport | undefined;- isLoadingArchitectureGraph: 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;@@ -81,6 +86,10 @@ export interface GraphFlowProps {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@@ -129,10 +138,21 @@ export interface GraphFlowProps {/** Blossom this community's files on the canvas (expand affordance). */onExpandOnCanvas: () => void;}) => ReactNode;- /** Fired when the community detail panel transitions to open. Lets the- * hosting page dismiss any competing right-rail panel (doc panel etc.)- * so the right side is a single sidebar. */+ /** 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, module filter). */+ 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;}export function GraphFlow(props: GraphFlowProps) {@@ -150,6 +170,7 @@ export function GraphFlow(props: GraphFlowProps) {isLoadingHotFilesGraph,communities,executionFlows,+ onFlowsVisibilityChange,initialViewMode,viewMode: controlledViewMode,activeModule: controlledActiveModule,@@ -166,6 +187,11 @@ export function GraphFlow(props: GraphFlowProps) {renderPathFinder,renderCommunityPanel,onCommunityPanelOpen,+ onSelectedNodeChange,+ description,+ headerActions,+ banner,+ rail,} = props;const sigmaRef = useRef<SigmaCanvasHandle>(null);@@ -263,6 +289,15 @@ export function GraphFlow(props: GraphFlowProps) {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);@@ -749,6 +784,9 @@ export function GraphFlow(props: GraphFlowProps) {}}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, sigmaGraph, openCommunityPanel],);@@ -959,23 +997,233 @@ export function GraphFlow(props: GraphFlowProps) {if (isLoading || isAwaitingAsyncBuild || (isBuildingGraph && !sigmaGraph))return <Skeleton className="h-full w-full rounded-lg" />;- // What the top-left status panel has to say, if anything. It is one bordered- // panel now, so it must not render when every row inside it is empty — an- // empty box is worse than the four separate chips it replaced.const showOverlayCounts =!!sigmaGraph && sigmaGraph.order > 0 && (isDeadView || isHotView);const hasCanvasStatus =(isEgoActive && !!selectedNodeId) || (showOverlayCounts && !!overlayStats);- // The canvas is what the reader came for, so it sits on the page plane- // rather than below it (rule 8). Dark mode used to paint- // `--color-bg-inset`, which the July ramp move took a full step darker than- // the `--color-bg-root` page around it, so the graph read as a hole cut in- // the app. Light mode never painted anything and has always looked right;- // this makes dark do what light already did. Same call the knowledge-graph- // canvas made in `zoom/theme.ts`.+ 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),+ })+ : 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 !== null && renderCommunityPanel+ ? renderCommunityPanel({+ communityId: communityPanelId,+ onClose: () => setCommunityPanelId(null),+ onExpandOnCanvas: () => handleConstellationHubToggle(communityPanelId),+ })+ : selectedNodeId && inspectedNode+ ? (+ <GraphInspectionPanel+ nodeId={selectedNodeId}+ data={inspectedNode}+ graph={sigmaGraph}+ 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}+ onFindPath={handleInspectFindPath}+ isModuleExpanded={false}+ egoDepth={egoDepth}+ onEgoDepthChange={setEgoDepth}+ egoVisibleCount={egoVisibleCount}+ />+ )+ : undefined;+return (- <div className="relative w-full h-full" style={{ touchAction: "none", ...(graphTheme === "dark" ? { background: "var(--color-bg-root)" } : {}) }} aria-label="Dependency graph">+ <GraphCanvasShell+ description={description}+ titleActions={+ <div className="flex flex-wrap items-center justify-end gap-2">+ {headerActions}+ <GraphToolbar+ viewMode={viewMode}+ onViewChange={handleViewChange}+ colorMode={colorMode}+ onColorModeChange={setColorMode}+ hideTests={hideTests}+ onHideTestsChange={(v) => {+ setActiveSignals(prev => {+ const next = new Set(prev);+ if (v) next.add("hideTests");+ else next.delete("hideTests");+ return next;+ });+ }}+ onFitView={handleFitView}+ 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={sigmaGraph?.order ?? 0}+ onSearchKeyDown={handleSearchKeyDown}+ layoutMode={layoutMode}+ onLayoutModeChange={handleLayoutModeChange}+ onToggleHelp={handleToggleShortcutHelp}+ hierarchicalDisabledReason={+ sigmaGraph && sigmaGraph.order > ELK_MAX_NODES+ ? elkSkipReason(sigmaGraph.order)+ : undefined+ }+ />+ </div>+ }+ banner={+ banner || layoutNotice ? (+ <div className="space-y-2">+ {banner}+ {layoutNotice && (+ <div+ role="status"+ aria-live="polite"+ className="flex items-center gap-2 rounded-lg border border-[var(--color-warning)]/40 bg-[var(--color-bg-elevated)] px-3 py-1.5"+ >+ <span className="text-[11px] text-[var(--color-text-primary)]">{layoutNotice}</span>+ <button+ onClick={() => setLayoutNotice(null)}+ aria-label="Dismiss layout notice"+ className="shrink-0 text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)]"+ >+ <X className="w-3 h-3" />+ </button>+ </div>+ )}+ </div>+ ) : undefined+ }+ rail={railContent}+ footer={+ <div className="flex flex-wrap items-center justify-between gap-x-4 gap-y-2">+ <GraphLegend+ nodeCount={sigmaGraph?.order ?? 0}+ edgeCount={sigmaGraph?.size ?? 0}+ colorMode={colorMode}+ viewMode={viewMode}+ {...(communityLabels ? { communityLabels } : {})}+ onCommunityClick={openCommunityPanel}+ activeCommunities={activeCommunities ?? undefined}+ onCommunityToggle={handleCommunityToggle}+ onToggleAllCommunities={handleToggleAllCommunities}+ visibleEdgeTypes={isConstellation ? undefined : visibleEdgeTypes}+ onEdgeTypeToggle={isConstellation ? undefined : handleEdgeTypeToggle}+ graphTheme={graphTheme}+ constellationEntries={isConstellation ? constellationLegend : undefined}+ onConstellationHubClick={handleConstellationHubClick}+ />+ {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"+ >{sigmaGraph && sigmaGraph.order > 0 ? (<SigmaCanvasref={sigmaRef}@@ -1013,247 +1261,13 @@ export function GraphFlow(props: GraphFlowProps) {/></div>) : null}-- {/* Canvas status, top-left. One panel with hairline rows, matching the- toolbar, the legend and the zoom controls — this corner could- otherwise stack four independently-bordered, independently-shadowed- chips (breadcrumb, expanded-modules, loading, tip, overlay counts)- over the diagram at once. Rendered only when it has something to- say, so an idle canvas carries no chrome here at all (rule 10). */}- {hasCanvasStatus && (- <div className={`absolute top-3 left-3 z-10 flex flex-col items-stretch overflow-hidden ${canvasPanelClass}`}>- {isEgoActive && selectedNodeId ? (- <div>- <div className={canvasRowClass}>- <span className="text-[10px] text-[var(--color-accent-primary)]">- 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="text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)] text-[10px]"- >- Clear- </button>- </div>- </div>- ) : null}-- {/* Overlay coverage: how many flagged files are actually in view. The- totals come from the backend when it provides them; without totals- we still report the in-view count so the overlay never reads as- silently doing nothing. */}- {showOverlayCounts && overlayStats && (- <>- {isDeadView && (- <OverlayCountChip- kind="dead"- inView={overlayStats.deadInView}- total={deadTotal}- />- )}- {isHotView && (- <OverlayCountChip- kind="hot"- inView={overlayStats.hotInView}- total={hotTotal}- />- )}- </>- )}- </div>- )}-- {/* Layout-skipped notice: the hierarchical toggle must never look- active while silently doing nothing. */}- {layoutNotice && (- <div- role="status"- aria-live="polite"- className="absolute top-3 left-1/2 -translate-x-1/2 z-10 flex max-w-[min(28rem,calc(100vw-6rem))] items-center gap-2 rounded-lg border border-[var(--color-warning)]/40 bg-[var(--color-bg-elevated)]/95 backdrop-blur-sm px-3 py-1.5 shadow-sm"- >- <span className="text-[11px] text-[var(--color-text-primary)]">{layoutNotice}</span>- <button- onClick={() => setLayoutNotice(null)}- aria-label="Dismiss layout notice"- className="shrink-0 text-[var(--color-text-tertiary)] hover:text-[var(--color-text-primary)]"- >- <X className="w-3 h-3" />- </button>- </div>- )}-- {/* Toolbar */}- <div className="absolute top-3 right-3 z-10">- <GraphToolbar- viewMode={viewMode}- onViewChange={handleViewChange}- colorMode={colorMode}- onColorModeChange={setColorMode}- hideTests={hideTests}- onHideTestsChange={(v) => {- setActiveSignals(prev => {- const next = new Set(prev);- v ? next.add("hideTests") : next.delete("hideTests");- return next;- });- }}- onFitView={handleFitView}- showPathFinder={showPathFinder}- pathFinderAvailable={Boolean(renderPathFinder)}- onTogglePathFinder={() => {- // Path finder and flows share the same overlay slot — opening- // one always closes the other.- 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={sigmaGraph?.order ?? 0}- onSearchKeyDown={handleSearchKeyDown}- layoutMode={layoutMode}- onLayoutModeChange={handleLayoutModeChange}- onToggleHelp={handleToggleShortcutHelp}- hierarchicalDisabledReason={- sigmaGraph && sigmaGraph.order > ELK_MAX_NODES- ? elkSkipReason(sigmaGraph.order)- : undefined- }- />- </div>-- {/* Path Finder. Carries the same viewport clamp as the flows panel below;- without it the panel runs off the side of a phone. */}- {showPathFinder && renderPathFinder && (- <div className="absolute top-14 right-3 z-10 w-[min(20rem,calc(100vw-1.5rem))]">- {renderPathFinder({- initialFrom: pathFrom,- initialTo: pathTo,- onPathFound: handlePathFound,- onClear: handlePathClear,- onClose: () => setShowPathFinder(false),- })}- </div>- )}-- {/* Execution Flows Panel */}- {showFlows && executionFlows && executionFlows.flows.length > 0 && (- <div className="absolute top-14 right-3 z-10 w-[min(16rem,calc(100vw-1.5rem))]">- <GraphFlowPanel- flows={executionFlows}- activeFlowIdx={activeFlowIdx}- onSelect={handleFlowSelect}- onClose={handleFlowsClose}- missingCount={activeFlowMissingCount}- />- </div>- )}-- {/* Legend — on phones the inspection bottom sheet covers this corner,- so yield to it instead of stacking underneath. */}- <div className={`absolute bottom-3 left-3 z-10 ${selectedNodeId ? "hidden sm:block" : ""}`}>- <GraphLegend- nodeCount={sigmaGraph?.order ?? 0}- edgeCount={sigmaGraph?.size ?? 0}- colorMode={colorMode}- viewMode={viewMode}- {...(communityLabels ? { communityLabels } : {})}- onCommunityClick={openCommunityPanel}- activeCommunities={activeCommunities ?? undefined}- onCommunityToggle={handleCommunityToggle}- onToggleAllCommunities={handleToggleAllCommunities}- visibleEdgeTypes={isConstellation ? undefined : visibleEdgeTypes}- onEdgeTypeToggle={isConstellation ? undefined : handleEdgeTypeToggle}- graphTheme={graphTheme}- constellationEntries={isConstellation ? constellationLegend : undefined}- onConstellationHubClick={handleConstellationHubClick}- /></div>-- {/* Keyboard shortcut help (toggled with ?) */}- {showShortcutHelp && (- <GraphShortcutHelp onClose={() => setShowShortcutHelp(false)} />- )}-- {/* Context menu */}- {ctxMenu && (- <GraphContextMenu- x={ctxMenu.x}- y={ctxMenu.y}- nodeId={ctxMenu.nodeId}- isModule={ctxMenu.nodeType === "moduleGroup"}- onViewDocs={handleCtxViewDocs}- onExplore={handleCtxExplore}- onPathFrom={handleCtxPathFrom}- onPathTo={handleCtxPathTo}- />- )}-- {/* Community detail panel */}- {communityPanelId !== null && renderCommunityPanel &&- renderCommunityPanel({- communityId: communityPanelId,- onClose: () => setCommunityPanelId(null),- onExpandOnCanvas: () => handleConstellationHubToggle(communityPanelId),- })}-- {/* Inspection panel — works for both file and module nodes */}- {selectedNodeId && (() => {- const fileNd = effectiveNodeDataMap.get(selectedNodeId);- const modNd = effectiveModuleDataMap.get(selectedNodeId);- const nd = fileNd ?? modNd;- if (!nd) return null;- return (- <GraphInspectionPanel- nodeId={selectedNodeId}- data={nd}- graph={sigmaGraph}- allNodes={effectiveNodeDataMap}- communityLabel={fileNd ? communityLabels?.get(fileNd.communityId) : undefined}- onClose={() => { setSelectedNodeId(null); }}- onNavigateToNode={handleInspectNavigate}- onViewDocs={() => { onNodeViewDocs?.(selectedNodeId); }}- onViewSymbols={- fileNd && onNodeViewSymbols- ? () => { onNodeViewSymbols(selectedNodeId); }- : undefined- }- filePageHref={fileNd ? fileHrefFor?.(selectedNodeId) : undefined}- onFindPath={handleInspectFindPath}- isModuleExpanded={false}- egoDepth={egoDepth}- onEgoDepthChange={setEgoDepth}- egoVisibleCount={egoVisibleCount}- />- );- })()}- </div>+ </GraphCanvasShell>);}-/**- * Chrome for the top-left status panel. Shares the toolbar / legend / zoom- * treatment so every corner of the canvas reads as one system: one border, one- * shadow, one blur, and hairline dividers instead of gaps between boxes.- */-const canvasPanelClass =- "rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)]/85 shadow-sm backdrop-blur-sm";--/** One row inside that panel. `first:border-t-0` keeps the top edge clean. */-const canvasRowClass =- "flex items-center gap-2 border-t border-[var(--color-border-default)] px-2.5 py-1.5 first:border-t-0";--/** Small status chip captioning 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 doesn't. */+/** 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,@@ -1266,15 +1280,13 @@ function OverlayCountChip({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`;+ 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`;}- return (- <div role="status" className={canvasRowClass}>- <span className="text-[10px] text-[var(--color-text-secondary)]">{text}</span>- </div>- );+ // 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>;}diff --git a/packages/ui/src/graph/graph-inspection-panel.tsx b/packages/ui/src/graph/graph-inspection-panel.tsxindex 00af5a680..c831c1fcb 100644--- a/packages/ui/src/graph/graph-inspection-panel.tsx+++ b/packages/ui/src/graph/graph-inspection-panel.tsx@@ -146,21 +146,24 @@ export const GraphInspectionPanel = memo(function GraphInspectionPanel({return (<div- // Right panel on sm+; bottom sheet (drag handle + swipe-dismiss) below.- className="absolute inset-x-0 bottom-0 top-auto max-h-[70%] rounded-t-xl border-t border-[var(--color-border-default)] bg-[var(--color-bg-surface)] z-20 flex flex-col shadow-xl shadow-black/20 animate-in slide-in-from-bottom sm:slide-in-from-bottom-0 sm:slide-in-from-right duration-200 sm:inset-x-auto sm:right-0 sm:top-0 sm:bottom-0 sm:left-auto sm:w-[300px] sm:max-h-none sm:rounded-none sm:border-t-0 sm:border-l"+ // Fills the shell's rail slot, which owns placement (sheet under lg,+ // grid column above). Keeps the swipe-to-dismiss gesture for the sheet.+ className="flex h-full min-h-0 flex-col"onTouchStart={(e) => {touchStartY.current = e.touches[0]?.clientY ?? null;}}onTouchEnd={(e) => {const start = touchStartY.current;touchStartY.current = null;- if (start == null || window.innerWidth >= 640) return;+ // Matches the shell's rail breakpoint: above lg this is a grid column,+ // not a sheet, so there is nothing to swipe away.+ if (start == null || window.innerWidth >= 1024) return;const end = e.changedTouches[0]?.clientY ?? start;if (end - start > 80) onClose();}}>{/* Drag handle (mobile sheet only) */}- <div className="flex justify-center py-1.5 sm:hidden" aria-hidden>+ <div className="flex justify-center py-1.5 lg:hidden" aria-hidden><span className="h-1 w-9 rounded-full bg-[var(--color-border-default)]" /></div>{/* Header */}@@ -176,6 +179,7 @@ export const GraphInspectionPanel = memo(function GraphInspectionPanel({</div><buttononClick={onClose}+ aria-label="Close inspector"className="p-1 rounded hover:bg-[var(--color-bg-elevated)] transition-colors shrink-0"><X className="h-4 w-4 text-[var(--color-text-tertiary)]" />diff --git a/packages/ui/src/graph/graph-legend.tsx b/packages/ui/src/graph/graph-legend.tsxindex a06a142e6..44bae78af 100644--- a/packages/ui/src/graph/graph-legend.tsx+++ b/packages/ui/src/graph/graph-legend.tsx@@ -7,6 +7,9 @@ import { edgeColorsForTheme } from "./sigma/constants";import { useCommunityFamilies } from "../shared/use-theme-tokens";import type { ColorMode, ViewMode } from "./graph-toolbar";+/** Community rows shown before the key folds into a "+N" line. */+const COMMUNITY_ROWS = 8;+const LANGUAGE_LEGEND = [{ lang: "python", color: LANGUAGE_COLORS.python, label: "Python" },{ lang: "typescript", color: LANGUAGE_COLORS.typescript, label: "TypeScript" },@@ -29,19 +32,19 @@ const LANGUAGE_LEGEND = [* large fraction of its content, it wants merging".*/const shellClass =- "overflow-hidden rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)]/85 text-xs shadow-sm backdrop-blur-sm";+ "flex w-full flex-wrap items-center gap-x-4 gap-y-1.5 border-t border-[var(--color-border-default)] pt-2 text-xs";const headerClass =- "flex w-full items-center justify-between gap-2 px-2.5 py-1.5 text-[var(--color-text-secondary)] transition-colors hover:text-[var(--color-text-primary)]";+ "inline-flex shrink-0 items-center gap-1 rounded py-1.5 text-[var(--color-text-secondary)] transition-colors hover:text-[var(--color-text-primary)] sm:py-0";const countClass = "font-mono text-[10px] tabular-nums tracking-[0.04em]";const rowClass =- "flex w-full items-center gap-2 rounded px-1.5 py-1 text-left text-[11px] text-[var(--color-text-secondary)] transition-colors hover:bg-[var(--color-bg-wash-hover)] hover:text-[var(--color-text-primary)]";+ "inline-flex items-center gap-1.5 rounded px-1.5 py-1.5 text-left text-[11px] text-[var(--color-text-secondary)] transition-colors hover:bg-[var(--color-bg-wash-hover)] hover:text-[var(--color-text-primary)] sm:py-0.5";/** Section label inside the key. Mono micro-label, no rule above it. */const groupClass =- "px-1.5 pt-1.5 pb-0.5 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]";+ "shrink-0 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)]";function Chevron({ expanded }: { expanded: boolean }) {const Icon = expanded ? ChevronDown : ChevronUp;@@ -124,10 +127,8 @@ export const GraphLegend = memo(function GraphLegend({constellationEntries,onConstellationHubClick,}: GraphLegendProps) {- // Open by default. Every node on the canvas is painted from this key, so- // collapsing it ships a field of coloured circles with no way to read them- // until the reader thinks to click a counter. The key is the cheapest thing- // on screen and the only one that makes the rest mean anything.+ // Open by default: every node is painted from this key, so a collapsed one+ // ships a field of coloured circles with no way to read them.const [expanded, setExpanded] = useState(true);const communityFamily = useCommunityFamilies();const edgeColors = edgeColorsForTheme(graphTheme);@@ -147,9 +148,9 @@ export const GraphLegend = memo(function GraphLegend({<Chevron expanded={expanded} /></button>{expanded && (- <div className="space-y-px px-1.5 pb-1.5">+ <div className="flex flex-wrap items-center gap-x-3 gap-y-1">{entries.length === 0 && (- <p className="px-1.5 py-1 text-[11px] text-[var(--color-text-tertiary)]">+ <p className="text-[11px] text-[var(--color-text-tertiary)]">No communities detected</p>)}@@ -162,7 +163,7 @@ export const GraphLegend = memo(function GraphLegend({className={rowClass}><Swatch color={color} />- <span className="min-w-0 flex-1 truncate">{e.label}</span>+ <span className="truncate max-w-[12rem]">{e.label}</span><span className="shrink-0 tabular-nums text-[10px] text-[var(--color-text-tertiary)]">{e.memberCount}</span>@@ -170,13 +171,10 @@ export const GraphLegend = memo(function GraphLegend({);})}{overflow > 0 && (- <p className="px-1.5 pt-1 text-[10px] text-[var(--color-text-tertiary)]">+ <p className="text-[10px] text-[var(--color-text-tertiary)]">+{overflow} smaller not listed</p>)}- <p className="px-1.5 pt-1.5 text-[10px] text-[var(--color-text-tertiary)]">- Inner ring = entry surface- </p></div>)}</div>@@ -184,7 +182,7 @@ export const GraphLegend = memo(function GraphLegend({}return (- <div className={`${shellClass} min-w-[148px] max-w-[190px]`}>+ <div className={shellClass}><button onClick={() => setExpanded((s) => !s)} className={headerClass}><span className={countClass}>{nodeCount} nodes · {edgeCount} edges@@ -193,7 +191,7 @@ export const GraphLegend = memo(function GraphLegend({</button>{expanded && (- <div className="space-y-px px-1.5 pb-1.5">+ <div className="flex flex-wrap items-center gap-x-3 gap-y-1"><p className={groupClass}>{colorMode === "language" ? "Language" : "Community"}</p>@@ -202,7 +200,7 @@ export const GraphLegend = memo(function GraphLegend({LANGUAGE_LEGEND.map((l) => (<divkey={l.lang}- className="flex items-center gap-2 px-1.5 py-0.5 text-[11px] text-[var(--color-text-secondary)]"+ className="inline-flex items-center gap-1.5 text-[11px] text-[var(--color-text-secondary)]"><Swatch color={l.color} /><span className="truncate">{l.label}</span>@@ -210,9 +208,11 @@ export const GraphLegend = memo(function GraphLegend({))}{colorMode === "community" && (() => {- const entries = communityLabels && communityLabels.size > 0- ? Array.from(communityLabels.entries()).slice(0, 8)+ const all = communityLabels && communityLabels.size > 0+ ? Array.from(communityLabels.entries()): null;+ const entries = all ? all.slice(0, COMMUNITY_ROWS) : null;+ const overflow = all ? all.length - entries!.length : 0;const allSelected = !activeCommunities || (entries? entries.every(([cid]) => activeCommunities.has(cid)): true);@@ -221,7 +221,7 @@ export const GraphLegend = memo(function GraphLegend({{onToggleAllCommunities && entries && (<buttononClick={() => onToggleAllCommunities(!allSelected)}- className="px-1.5 pb-0.5 text-[10px] font-medium text-[var(--color-accent-primary)] hover:underline"+ className="shrink-0 text-[10px] font-medium text-[var(--color-accent-primary)] hover:underline">{allSelected ? "Deselect all" : "Select all"}</button>@@ -242,24 +242,34 @@ export const GraphLegend = memo(function GraphLegend({) : (<Swatch color={color} />)}- <span- className="min-w-0 flex-1 truncate"- onClick={() => onCommunityClick?.(cid)}- >- {label}- </span>+ {onCommunityClick ? (+ <button+ type="button"+ onClick={() => onCommunityClick(cid)}+ className="max-w-[12rem] truncate rounded hover:text-[var(--color-text-primary)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-accent-primary)]"+ >+ {label}+ </button>+ ) : (+ <span className="max-w-[12rem] truncate">{label}</span>+ )}</div>);}): Array.from({ length: 6 }, (_, i) => (<divkey={i}- className="flex items-center gap-2 px-1.5 py-0.5 text-[11px] text-[var(--color-text-secondary)]"+ className="inline-flex items-center gap-1.5 text-[11px] text-[var(--color-text-secondary)]"><Swatch color={communityFamily(i).hub} /><span className="truncate">Community {i + 1}</span></div>))}+ {overflow > 0 && (+ <p className="text-[10px] text-[var(--color-text-tertiary)]">+ +{overflow} smaller not listed+ </p>+ )}</>);})()}@@ -283,9 +293,7 @@ export const GraphLegend = memo(function GraphLegend({label={`Toggle ${et.label} edges`}onToggle={() => onEdgeTypeToggle(et.type)}/>- <span- className={`min-w-0 flex-1 truncate ${checked ? "" : "opacity-45"}`}- >+ <span className={`truncate ${checked ? "" : "opacity-45"}`}>{et.label}</span></div>@@ -295,10 +303,10 @@ export const GraphLegend = memo(function GraphLegend({)}{viewMode !== "full" && (- <p className="px-1.5 pt-1.5 text-[10px] text-[var(--color-text-tertiary)]">+ <p className="text-[10px] text-[var(--color-text-tertiary)]">{viewMode === "dead" && "Showing unreachable files"}{viewMode === "hotfiles" && "Most-committed files (30d)"}- {viewMode === "unified" && "Unified: community + risk signals"}+ {viewMode === "unified" && "Dead and high-churn files"}</p>)}</div>diff --git a/packages/ui/src/graph/graph-shortcut-help.tsx b/packages/ui/src/graph/graph-shortcut-help.tsxindex c8cf66f91..bb93cce03 100644--- a/packages/ui/src/graph/graph-shortcut-help.tsx+++ b/packages/ui/src/graph/graph-shortcut-help.tsx@@ -8,7 +8,8 @@ const SHORTCUTS: { keys: string[]; action: string }[] = [{ keys: ["⌘K"], action: "Focus search" },{ keys: ["1"], action: "Color by language" },{ keys: ["2"], action: "Color by community" },- { keys: ["3"], action: "Color by risk" },+ { keys: ["↑", "↓"], action: "Step through search results" },+ { keys: ["Enter"], action: "Select the highlighted search result" },{ keys: ["Esc"], action: "Dismiss top layer (panel, selection, blossom…)" },{ keys: ["?"], action: "Toggle this help" },];@@ -22,7 +23,7 @@ const GESTURES: { gesture: string; action: string }[] = [/** Keyboard + gesture cheatsheet, toggled with `?`. */export function GraphShortcutHelp({ onClose }: { onClose: () => void }) {return (- <div className="absolute inset-0 z-20 flex items-center justify-center bg-black/40 p-4" onClick={onClose}>+ <div className="absolute inset-0 z-30 flex items-center justify-center bg-black/40 p-4" onClick={onClose}><divclassName="w-full max-w-sm rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)] p-4 shadow-xl shadow-black/30"onClick={(e) => e.stopPropagation()}diff --git a/packages/ui/src/graph/graph-toolbar.tsx b/packages/ui/src/graph/graph-toolbar.tsxindex 1ad96fd93..a669832b0 100644--- a/packages/ui/src/graph/graph-toolbar.tsx+++ b/packages/ui/src/graph/graph-toolbar.tsx@@ -6,7 +6,6 @@ import {EyeOff,Maximize,Route,- GitFork,Skull,Flame,Workflow,@@ -142,31 +141,17 @@ const LAYOUT_MODES: { id: LayoutMode; icon: typeof GitBranch; label: string }[]{ id: "hierarchical", icon: GitBranch, label: "Hierarchical" },];-// The constellation (Knowledge Graph) scope is always radial — a single-// disabled-looking indicator replaces the Force/Hierarchical toggle there.-const RADIAL_LAYOUT: { id: LayoutMode; icon: typeof GitFork; label: string } = {- id: "radial",- icon: GitFork,- label: "Radial",-};-/**- * One panel, not four.- *- * Scope, node filter, the layout/colour/action row and search each used to be- * their own rounded box with its own border, its own `shadow-sm` and its own- * `backdrop-blur-sm`, stacked down the same edge with 6px of canvas showing- * between them. Four frames and four shadows for one control surface, over a- * diagram the reader is trying to look past (rule 13). They are now one shell- * with hairline dividers, sharing the legend's chrome so the two corners of- * the canvas read as the same system.+ * One control surface in the section header. Translucency, blur and a shadow+ * are how chrome sits over a diagram; this lives on the page plane now, so it+ * takes a plain hairline frame instead.*/const panelClass =- "overflow-hidden rounded-lg border border-[var(--color-border-default)] bg-[var(--color-bg-elevated)]/85 shadow-sm backdrop-blur-sm";+ "overflow-hidden rounded-lg border border-[var(--color-border-default)]";/** A divider row inside the panel. The first group omits the top hairline. */const groupClass =- "flex items-center gap-0.5 p-1 border-t border-[var(--color-border-default)] first:border-t-0";+ "flex flex-wrap items-center gap-0.5 p-1 border-t border-[var(--color-border-default)] first:border-t-0";const itemActiveClass ="bg-[var(--color-accent-primary)]/15 text-[var(--color-accent-primary)]";@@ -273,22 +258,9 @@ export const GraphToolbar = memo(function GraphToolbar({{/* Layout · colour · actions. */}<div className={`${clusterVisibility} ${groupClass}`}>+ {!isConstellation && (<div className="flex gap-0.5">- {isConstellation ? (- // Constellation is locked to the radial layout; show a single- // active indicator instead of the Force/Hierarchical toggle.- <button- key={RADIAL_LAYOUT.id}- disabled- className={`${itemClass} ${itemActiveClass} cursor-default`}- title={`${RADIAL_LAYOUT.label} (fixed for Communities)`}- aria-label={RADIAL_LAYOUT.label}- aria-pressed- >- <RADIAL_LAYOUT.icon className="w-3 h-3" />- </button>- ) : (- LAYOUT_MODES.map((m) => {+ {LAYOUT_MODES.map((m) => {const Icon = m.icon;const isActive = layoutMode === m.id;const disabledReason =@@ -309,18 +281,15 @@ export const GraphToolbar = memo(function GraphToolbar({<Icon className="w-3 h-3" /></button>);- })- )}+ })}</div>+ )}- {/* Colour-by. This control decides what every circle on the canvas- means, and it used to be three unlabelled icons — a palette, a- network and a shield — so there was no way to know whether you were- looking at languages, communities or risk without hovering each- one. Worse, Risk paints green/amber/red and Community paints- families that include green, amber and red: same marks, two- vocabularies, switched by a mystery glyph. The active mode now- always carries its word. */}+ {/* Colour-by. The active mode always carries its word: unlabelled+ glyphs gave no way to tell which vocabulary the circles were in.+ Hidden in the constellation, where hubs are family-coloured+ regardless of this setting. */}+ {!isConstellation && (<div className="flex items-center gap-0.5 border-l border-[var(--color-border-default)] pl-1"><span className="hidden pl-1 pr-0.5 font-mono text-[10px] uppercase tracking-[0.12em] text-[var(--color-text-tertiary)] lg:inline">Colour@@ -343,6 +312,7 @@ export const GraphToolbar = memo(function GraphToolbar({);})}</div>+ )}{/* No theme control here. It set the *global* theme, so it did exactlywhat the app's own toggle in the header does, a few hundred pixelsdiff --git a/packages/ui/src/graph/sigma/canvas-ground.tsx b/packages/ui/src/graph/sigma/canvas-ground.tsxnew file mode 100644index 000000000..241f3b83a--- /dev/null+++ b/packages/ui/src/graph/sigma/canvas-ground.tsx@@ -0,0 +1,90 @@+"use client";++import { useEffect, useRef, useState } from "react";+import type Sigma from "sigma";++/** Dot spacing in graph units before the octave clamp below. */+const BASE_SPACING = 40;+/** Screen-pixel band the spacing is kept inside by doubling / halving. */+const MIN_PX = 22;+const MAX_PX = 88;+const DOT_RADIUS = 1.1;++/** `useId` output is not safe inside `url(#...)`: React 19 emits non-ASCII+ * delimiters, which percent-encode before the SVG fragment lookup and leave+ * the fill unresolved. A counter keeps the id ASCII and unique. */+let groundSeq = 0;++/**+ * Graph-paper ground under the canvas.+ *+ * Dark mode painted `--color-bg-root`, which is also the page body colour, so+ * canvas and page were the same value and the map read as a void. The plane is+ * right (the canvas is the subject); it just had nothing on it. Light mode gets+ * its ground for free from the warm paper root.+ *+ * Spacing doubles or halves to stay inside a screen-pixel band, so density+ * holds steady while the step itself gives the zoom feedback the canvas+ * otherwise has none of. An SVG pattern moved by one `patternTransform` write+ * per frame; the tile is only resized when the octave actually steps.+ */+export function CanvasGround({ sigma }: { sigma: Sigma | null }) {+ const patternRef = useRef<SVGPatternElement>(null);+ const circleRef = useRef<SVGCircleElement>(null);+ const [patternId] = useState(() => `canvas-ground-${(groundSeq += 1)}`);++ useEffect(() => {+ if (!sigma) return;+ const pattern = patternRef.current;+ const circle = circleRef.current;+ if (!pattern || !circle) return;++ let lastSpacing = 0;+ const draw = () => {+ const origin = sigma.graphToViewport({ x: 0, y: 0 });+ const unit = sigma.graphToViewport({ x: BASE_SPACING, y: 0 });+ let spacing = Math.hypot(unit.x - origin.x, unit.y - origin.y);+ if (!Number.isFinite(spacing) || spacing <= 0) return;+ while (spacing < MIN_PX) spacing *= 2;+ while (spacing > MAX_PX) spacing /= 2;++ // Panning only moves the lattice. Resizing the tile invalidates it and+ // re-rasterises the full-viewport fill, so only do that when the octave+ // actually steps.+ if (spacing !== lastSpacing) {+ lastSpacing = spacing;+ pattern.setAttribute("width", String(spacing));+ pattern.setAttribute("height", String(spacing));+ circle.setAttribute("cx", String(spacing / 2));+ circle.setAttribute("cy", String(spacing / 2));+ }+ pattern.setAttribute(+ "patternTransform",+ `translate(${origin.x % spacing},${origin.y % spacing})`,+ );+ };++ sigma.on("afterRender", draw);+ draw();+ return () => {+ sigma.off("afterRender", draw);+ };+ }, [sigma]);++ return (+ <svg className="pointer-events-none absolute inset-0 z-0 h-full w-full" aria-hidden="true">+ <defs>+ <pattern ref={patternRef} id={patternId} patternUnits="userSpaceOnUse" width={40} height={40}>+ <circle+ ref={circleRef}+ r={DOT_RADIUS}+ cx={20}+ cy={20}+ fill="var(--color-canvas-grid, rgba(128,128,128,0.1))"+ />+ </pattern>+ </defs>+ <rect width="100%" height="100%" fill={`url(#${patternId})`} />+ </svg>+ );+}diff --git a/packages/ui/src/graph/sigma/depth-rings.tsx b/packages/ui/src/graph/sigma/depth-rings.tsxindex e4a090f9d..857835a9b 100644--- a/packages/ui/src/graph/sigma/depth-rings.tsx+++ b/packages/ui/src/graph/sigma/depth-rings.tsx@@ -14,8 +14,9 @@ interface DepthRingsProps {* Faint concentric "depth" rings drawn behind the constellation. An SVG* underlay synced to the Sigma camera: we project the graph origin and a* point one radius out into viewport pixels every frame, so the rings track- * zoom/pan smoothly with transform-only updates (no re-layout). Captioned- * only in the legend ("inner = entry surface"), never on-canvas.+ * zoom/pan smoothly with transform-only updates (no re-layout). What they mean+ * is stated in the host's scope description, not on the canvas, so a host that+ * renders its own copy must say it there.*/export function DepthRings({ sigma, ringRadii }: DepthRingsProps) {const svgRef = useRef<SVGSVGElement>(null);@@ -27,7 +28,7 @@ export function DepthRings({ sigma, ringRadii }: DepthRingsProps) {const svg = svgRef.current;if (!svg) return;- const stroke = resolveToken("--color-canvas-dot", "rgba(128,128,128,0.08)");+ const stroke = resolveToken("--color-canvas-grid", "rgba(128,128,128,0.1)");const draw = () => {const center = sigma.graphToViewport({ x: 0, y: 0 });diff --git a/packages/ui/src/graph/sigma/sigma-canvas.tsx b/packages/ui/src/graph/sigma/sigma-canvas.tsxindex d96143a5b..0291ec321 100644--- a/packages/ui/src/graph/sigma/sigma-canvas.tsx+++ b/packages/ui/src/graph/sigma/sigma-canvas.tsx@@ -22,6 +22,7 @@ import { useFA2Layout } from "./use-fa2-layout";import { useElkSigmaLayout } from "./use-elk-sigma-layout";import { SigmaControls } from "./sigma-controls";import { DepthRings } from "./depth-rings";+import { CanvasGround } from "./canvas-ground";export interface SigmaCanvasProps {graph: Graph<SigmaNodeAttributes, SigmaEdgeAttributes> | null;@@ -90,7 +91,7 @@ export const SigmaCanvas = forwardRef<SigmaCanvasHandle, SigmaCanvasProps>(visibleEdgeTypes: props.visibleEdgeTypes,});- const { isRunning: isLayoutRunning, toggle: toggleLayout } = useFA2Layout({+ const { isRunning: isLayoutRunning } = useFA2Layout({graph: props.graph,sigma,enabled: props.layoutMode === "force",@@ -186,6 +187,18 @@ export const SigmaCanvas = forwardRef<SigmaCanvasHandle, SigmaCanvasProps>(};}, [sigma, container]);+ // Sigma 3 re-measures only inside its own render, and only listens on+ // window resize. The canvas cell now changes size without the window+ // doing so: the rail toggles the grid, the key row collapses, a banner+ // appears. On a settled graph nothing would trigger a render, leaving+ // stale dimensions behind the ground and the rings too.+ useEffect(() => {+ if (!sigma || !container || typeof ResizeObserver === "undefined") return;+ const observer = new ResizeObserver(() => sigma.refresh());+ observer.observe(container);+ return () => observer.disconnect();+ }, [sigma, container]);+useImperativeHandle(ref, () => ({focusNode,fitView,@@ -198,31 +211,22 @@ export const SigmaCanvas = forwardRef<SigmaCanvasHandle, SigmaCanvasProps>(<divclassName="relative w-full h-full"style={- // For the constellation, paint the dark canvas on the wrapper and keep- // the sigma container transparent so the depth-ring underlay shows.- hasDepthRings && props.graphTheme === "dark"- ? { background: "var(--color-bg-root)" }- : undefined+ // The plane is painted here, under the ground, so the underlays show+ // through a transparent Sigma container. Rule 8: the canvas is the+ // subject, so it takes the page plane rather than a well below it.+ props.graphTheme === "dark" ? { background: "var(--color-bg-root)" } : undefined}>+ {/* Every scope gets a ground. The rings were constellation-only, which+ left the file graph drawing nodes on a flat plane. */}+ <CanvasGround sigma={sigma} />{hasDepthRings && props.depthRingRadii && (<DepthRings sigma={sigma} ringRadii={props.depthRingRadii} />)}<divref={containerCallback}className="w-full h-full relative z-[1]"- style={{- // `--color-bg-canvas` aliases `--color-bg-inset`, which the July- // ramp move took to #0a0a0b — darker than the page. The canvas is- // the subject, so it takes the page plane (rule 8), matching the- // knowledge-graph canvas. Light mode is unchanged: it was already- // transparent, which is why only dark looked wrong.- background:- !hasDepthRings && props.graphTheme === "dark"- ? "var(--color-bg-root)"- : "transparent",- cursor: "grab",- }}+ style={{ background: "transparent", cursor: "grab" }}/><SigmaControlsonZoomIn={zoomIn}@@ -234,7 +238,6 @@ export const SigmaCanvas = forwardRef<SigmaCanvasHandle, SigmaCanvasProps>(: undefined}isLayoutRunning={props.layoutMode === "force" ? isLayoutRunning : isElkComputing}- onToggleLayout={props.layoutMode === "force" ? toggleLayout : undefined}/></div>);diff --git a/packages/ui/src/graph/sigma/sigma-controls.tsx b/packages/ui/src/graph/sigma/sigma-controls.tsxindex 98e65dc4d..281e3afe1 100644--- a/packages/ui/src/graph/sigma/sigma-controls.tsx+++ b/packages/ui/src/graph/sigma/sigma-controls.tsx@@ -1,6 +1,6 @@"use client";-import { ZoomIn, ZoomOut, Maximize, Focus, Play, Pause } from "lucide-react";+import { ZoomIn, ZoomOut, Maximize, Focus } from "lucide-react";import { ActivityDot } from "../../ui/activity-dot";interface SigmaControlsProps {@@ -8,8 +8,11 @@ interface SigmaControlsProps {onZoomOut: () => void;onFitView: () => void;onFocusSelected?: (() => void) | undefined;+ /** Drives the "Arranging…" activity chip only. There is no start/stop+ * control: re-running FA2 measurably *worsens* this layout (cluster+ * separation 23.2 seeded, 7.7 after 1200 iterations), and the golden-angle+ * community seed is the layout. */isLayoutRunning: boolean;- onToggleLayout?: (() => void) | undefined;}export function SigmaControls({@@ -18,20 +21,10 @@ export function SigmaControls({onFitView,onFocusSelected,isLayoutRunning,- onToggleLayout,}: SigmaControlsProps) {- // One panel with hairline dividers, matching the toolbar and the legend, so- // all three corners of the canvas read as the same system. Each button used- // to be its own bordered, `shadow-lg` pill; five of them stacked down the- // right edge was five frames and five shadows for one control.- //- // Dark mode also painted a hardcoded `#1a1a2e` navy that belongs to no- // palette in this app — the same class of drift as `--color-bg-glass`, and- // it survived for the same reason: it only ever renders on top of a diagram,- // where a plane one step off reads as deliberate.- // Mobile-first sizing, matching graph-toolbar's buttons: 36px is a usable- // touch target on a phone, and the compact 28px returns from `sm` up where a- // pointer is doing the aiming.+ // Direct manipulation of the camera, so this is one of the few things that+ // stays on the drawing plane. Mobile-first sizing: 36px is a usable touch+ // target, compact 28px from `sm` up where a pointer is aiming.const btnClass ="flex h-9 w-9 sm:h-7 sm:w-7 items-center justify-center rounded-md text-[var(--color-text-tertiary)] transition-colors hover:bg-[var(--color-bg-wash-hover)] hover:text-[var(--color-text-primary)]";@@ -82,24 +75,6 @@ export function SigmaControls({<Focus className="h-3.5 w-3.5" /></button>)}- {onToggleLayout && (- <button- type="button"- onClick={onToggleLayout}- className={`${btnClass} mt-1 border-t border-[var(--color-border-default)] pt-1 ${- isLayoutRunning ? "text-[var(--color-accent-primary)]" : ""- }`}- title={isLayoutRunning ? "Stop arranging" : "Re-arrange nodes"}- aria-label={isLayoutRunning ? "Stop arranging" : "Re-arrange nodes"}- aria-pressed={isLayoutRunning}- >- {isLayoutRunning ? (- <Pause className="h-3.5 w-3.5" />- ) : (- <Play className="h-3.5 w-3.5" />- )}- </button>- )}</div></div>);diff --git a/packages/ui/src/shared/view-tabs.tsx b/packages/ui/src/shared/view-tabs.tsxindex 1544375d5..fabcde5d0 100644--- a/packages/ui/src/shared/view-tabs.tsx+++ b/packages/ui/src/shared/view-tabs.tsx@@ -22,6 +22,12 @@ export interface ViewTabsProps {onValueChange: (id: string) => void;/** The active panel, rendered below the tab row. */children?: React.ReactNode;+ /** Id of a panel the host renders itself, for layouts where the panel cannot+ * be a child (a full-height canvas that must be a flex sibling). The host+ * puts `role="tabpanel"`, this id and `tabIndex={0}` on that container, and+ * labels it `aria-labelledby={`${panelId}-tab-${activeTabId}`}` — tab ids are+ * derived from this value so the host can name them without a callback. */+ panelId?: string;className?: string;}@@ -35,13 +41,20 @@ export function ViewTabs({value,onValueChange,children,+ panelId: externalPanelId,className,}: ViewTabsProps) {// Stable id base so each tab can be aria-labelled to the shared panel and// the panel can point back at the active tab.const baseId = React.useId();- const tabId = (id: string) => `${baseId}-tab-${id}`;- const panelId = `${baseId}-panel`;+ // Derived from the host's panelId when it owns the panel, so the two sides+ // agree on ids without threading a callback.+ const tabId = (id: string) => `${externalPanelId ?? baseId}-tab-${id}`;+ // Only claim a panel we can actually point at: an internal one when children+ // were given, otherwise the host's. With neither, `aria-controls` is dropped+ // rather than left dangling on an element that does not exist.+ const ownsPanel = children != null;+ const panelId = ownsPanel ? `${baseId}-panel` : externalPanelId;const tabRefs = React.useRef<Record<string, HTMLButtonElement | null>>({});// Keep the active tab in view even though the scrollbar is hidden — it can@@ -87,7 +100,7 @@ export function ViewTabs({type="button"role="tab"aria-selected={active}- aria-controls={panelId}+ {...(panelId ? { "aria-controls": panelId } : {})}tabIndex={active ? 0 : -1}onClick={() => onValueChange(tab.id)}className={cn(@@ -115,9 +128,11 @@ export function ViewTabs({);})}</div>- <div id={panelId} role="tabpanel" aria-labelledby={tabId(value)} tabIndex={0}>- {children}- </div>+ {ownsPanel && (+ <div id={panelId} role="tabpanel" aria-labelledby={tabId(value)} tabIndex={0}>+ {children}+ </div>+ )}</div>);}diff --git a/packages/ui/styles/globals.css b/packages/ui/styles/globals.cssindex 69b943821..39d6eeacd 100644--- a/packages/ui/styles/globals.css+++ b/packages/ui/styles/globals.css@@ -275,6 +275,9 @@BOTH themes; aliasing them to theme-aware surfaces fixes light mode. */--color-bg-canvas: var(--color-bg-inset);--color-canvas-dot: rgba(36, 27, 44, 0.08);+ /* Graph-paper ground under a node-link canvas. Stronger than canvas-dot,+ which is a scatter mark: a 1px ring at that alpha is below threshold. */+ --color-canvas-grid: rgba(36, 27, 44, 0.10);--color-bg-glass: rgba(255, 255, 255, 0.72);/* Neutral hover washes for canvas-adjacent chrome (rows, chips, stubs) —plum-alpha on paper, lavender-alpha on dark (same idiom as canvas-dot). */@@ -549,6 +552,7 @@/* C4 / graph canvas surfaces — dark variants (the var()-derived aliasesflip on their own; only the explicit rgbas need a dark override). */--color-canvas-dot: rgba(255, 255, 255, 0.05);+ --color-canvas-grid: rgba(255, 255, 255, 0.10);/* Tracks --color-bg-surface. It was rgba(35,35,37,.72) — the #232325 thatbg-surface used to be, left behind when the dark ramp moved in July 2026 —so every glass chip on every canvas was painting a graphite that existsdiff --git a/packages/web/src/app/repos/[id]/architecture/page.tsx b/packages/web/src/app/repos/[id]/architecture/page.tsxindex 335ee1330..73bcb4f91 100644--- a/packages/web/src/app/repos/[id]/architecture/page.tsx+++ b/packages/web/src/app/repos/[id]/architecture/page.tsx@@ -93,6 +93,8 @@ const TAB_FOR_VIEW: Record<CanonicalView, string> = {symbols: "symbols",};+const TAB_PANEL_ID = "architecture-tab-panel";+const TABS: { id: string; label: string }[] = [{ id: "map", label: "Map" },{ id: "coupling", label: "Coupling" },@@ -124,6 +126,7 @@ export default function ArchitecturePage({const [, setSignal] = useQueryState("signal");const [, setModule] = useQueryState("module");const [, setFocus] = useQueryState("focus");+ const [, setNode] = useQueryState("node");// The curated layers view now lives at /knowledge-graph. `?view=layers`// redirects there so shared links keep working.@@ -155,13 +158,17 @@ export default function ArchitecturePage({const handleTabChange = useCallback((id: string) => {void setView(DEFAULT_VIEW_FOR_TAB[id] ?? "communities");- if (id !== "coupling") void setFocus(null);+ // `?focus=` means a file path in Coupling and the literal "relationships"+ // in Third-party, so carrying it across pins one tab's value in the+ // other's vocabulary. Cleared on every change, not just when leaving.+ void setFocus(null);if (id !== "map") {void setSignal(null);void setModule(null);+ void setNode(null);}},- [setView, setFocus, setSignal, setModule],+ [setView, setFocus, setSignal, setModule, setNode],);const handleScopeChange = useCallback(@@ -178,10 +185,23 @@ export default function ArchitecturePage({return (<div className="flex h-full flex-col"><div className="shrink-0 px-4 pt-3 sm:px-6">- <ViewTabs tabs={TABS} value={activeTab} onValueChange={handleTabChange} />+ <ViewTabs+ tabs={TABS}+ value={activeTab}+ onValueChange={handleTabChange}+ panelId={TAB_PANEL_ID}+ /></div>- <div className="min-h-0 flex-1 overflow-auto">+ {/* The panel is a flex sibling, not a ViewTabs child: the Map is a+ full-height canvas that sizes itself from this box. */}+ <div+ id={TAB_PANEL_ID}+ role="tabpanel"+ aria-labelledby={`${TAB_PANEL_ID}-tab-${activeTab}`}+ tabIndex={0}+ className="min-h-0 flex-1 overflow-auto"+ >{activeTab === "map" && (<GraphViewrepoId={repoId}diff --git a/packages/web/src/app/repos/[id]/refactoring/page.tsx b/packages/web/src/app/repos/[id]/refactoring/page.tsxindex ea93028df..1f2f3d702 100644--- a/packages/web/src/app/repos/[id]/refactoring/page.tsx+++ b/packages/web/src/app/repos/[id]/refactoring/page.tsx@@ -19,6 +19,8 @@ import { parseAsString, parseAsStringLiteral, useQueryState } from "nuqs";import { Wrench, RotateCw } from "lucide-react";import { PageShell } from "@repowise-dev/ui/shared/page-shell";import { ViewTabs } from "@repowise-dev/ui/shared/view-tabs";++const REFACTORING_PANEL_ID = "refactoring-tab-panel";import { fileEntityPath } from "@repowise-dev/ui/shared/entity";import { Skeleton, SkeletonRegion } from "@repowise-dev/ui/ui/skeleton";import {@@ -250,12 +252,19 @@ export default function RefactoringPage({ params }: { params: Promise<{ id: stri<ViewTabstabs={tabs}value={type}+ panelId={REFACTORING_PANEL_ID}onValueChange={(id) => {setOffset(0);void setType(id as TypeFilter);}}/>+ <div+ id={REFACTORING_PANEL_ID}+ role="tabpanel"+ aria-labelledby={`${REFACTORING_PANEL_ID}-tab-${type}`}+ tabIndex={0}+ >{error ? (<div className="rounded-2xl border border-[var(--color-error)]/30 bg-[var(--color-error)]/5 p-6 text-sm text-[var(--color-text-secondary)]">Couldn't load refactoring opportunities. The repo may not be indexed yet, or the@@ -308,6 +317,7 @@ export default function RefactoringPage({ params }: { params: Promise<{ id: stri}/>)}+ </div></div><OpportunityDrawerdiff --git a/packages/web/src/components/architecture/graph-view.tsx b/packages/web/src/components/architecture/graph-view.tsxindex 871726491..a31846dff 100644--- a/packages/web/src/components/architecture/graph-view.tsx+++ b/packages/web/src/components/architecture/graph-view.tsx@@ -6,7 +6,6 @@ import { useQueryState } from "nuqs";import { useSearchParams } from "next/navigation";import { GraphFlow } from "@/components/graph/graph-flow";import { GraphDocPanel } from "@/components/graph/graph-doc-panel";-import { GraphCanvasShell } from "@repowise-dev/ui/graph/graph-canvas-shell";import { GraphTruncationBanner } from "@repowise-dev/ui/graph/graph-truncation-banner";import {GraphScopeSwitcher,@@ -97,8 +96,14 @@ export function GraphView({[setSelectedNode],);- // When the community panel opens from the legend, dismiss the doc panel- // so the two never stack on the right rail. Single-sidebar UX.+ // The rail holds one panel, and the doc panel outranks the inspector, so a+ // doc left open would mask every later selection. Drop it once the selection+ // moves elsewhere.+ const handleSelectedNodeChange = useCallback((nodeId: string | null) => {+ setDocNodeId((prev) => (prev !== null && prev !== nodeId ? null : prev));+ }, []);++ // Opening a community also replaces the doc panel.const handleCommunityPanelOpen = useCallback(() => {setDocNodeId(null);}, []);@@ -155,22 +160,18 @@ export function GraphView({);return (- <GraphCanvasShell- // No title. The tab above already says "Map", and the scope switcher on- // the right says which zoom you are at — a heading that repeats the- // control you just clicked spends a band of chrome saying nothing. What- // is left is the one line that adds something neither can: what to do- // with the thing you are looking at.+ <GraphFlow+ repoId={repoId}+ // No title. The tab above says "Map" and the scope switcher says which+ // zoom you are at; the one line left is what to do with what you see.description={isCommunities- ? "Each circle is a detected community, sized by how much code it holds. Double-click one to open it up."+ ? "Files that depend on each other more than on the rest of the repo, detected automatically. Circle size is how much code a group holds, and the nearer the centre, the nearer an entry point. Double-click a group to see the files inside it and what they depend on.": "Every file and how it depends on the others. Pick two files to trace a path between them."}- titleActions={headerControls}+ headerActions={headerControls}banner={- // Shown only when the file scope actually got capped. This line is the- // one place the node count is stated, and it only became true when the- // export stopped counting symbol nodes as files.+ // Only when the file scope actually got capped.usesFullGraph && graphData?.truncated && graphData.total_node_count != null ? (<GraphTruncationBannershown={graphData.nodes.length}@@ -181,7 +182,7 @@ export function GraphView({/>) : undefined}- overlay={+ rail={docNodeId ? (<GraphDocPanelrepoId={repoId}@@ -190,25 +191,22 @@ export function GraphView({/>) : undefined}- >- <GraphFlow- repoId={repoId}- // Scope is controlled: `?view=` is the single source of truth, so- // back/forward and shared links restore it without a remount.- viewMode={viewMode}- activeModule={activeModule}- // Same value the banner reports, so the caption and the canvas can- // never disagree about how many files are drawn.- graphLimit={graphLimit}- onModuleGroupsChange={setModuleGroups}- colorMode={initialColorMode ?? "community"}- initialSelectedNode={initialNode}- onNodeClick={handleNodeClick}- onNodeViewDocs={handleNodeViewDocs}- onCommunityPanelOpen={handleCommunityPanelOpen}- onViewModeChange={handleViewModeChange}- onColorModeChange={handleColorModeChange}- />- </GraphCanvasShell>+ // Scope is controlled: `?view=` is the single source of truth, so+ // back/forward and shared links restore it without a remount.+ viewMode={viewMode}+ activeModule={activeModule}+ // Same value the banner reports, so the caption and the canvas can+ // never disagree about how many files are drawn.+ graphLimit={graphLimit}+ onModuleGroupsChange={setModuleGroups}+ colorMode={initialColorMode ?? "community"}+ initialSelectedNode={initialNode}+ onNodeClick={handleNodeClick}+ onNodeViewDocs={handleNodeViewDocs}+ onCommunityPanelOpen={handleCommunityPanelOpen}+ onSelectedNodeChange={handleSelectedNodeChange}+ onViewModeChange={handleViewModeChange}+ onColorModeChange={handleColorModeChange}+ />);}diff --git a/packages/web/src/components/graph/graph-flow.tsx b/packages/web/src/components/graph/graph-flow.tsxindex 16b52c449..2e701d1af 100644--- a/packages/web/src/components/graph/graph-flow.tsx+++ b/packages/web/src/components/graph/graph-flow.tsx@@ -1,6 +1,6 @@"use client";-import { useState } from "react";+import { useCallback, useState } from "react";import { useRouter } from "next/navigation";import { fileEntityPath } from "@repowise-dev/ui/shared/entity";import {@@ -9,7 +9,6 @@ import {} from "@repowise-dev/ui/graph/graph-flow";import {useGraph,- useArchitectureGraph,useArchitectureCommunityGraph,useDeadCodeGraph,useHotFilesGraph,@@ -56,12 +55,18 @@ export interface GraphFlowProps {* Page uses this to dismiss the doc panel so the right rail stays* to a single surface. */onCommunityPanelOpen?: (communityId: number) => void;+ onSelectedNodeChange?: GraphFlowShellProps["onSelectedNodeChange"];/** Fired whenever the live scope (viewMode) changes. The page uses this to* track the current scope so it can conditionally fetch the capped full* graph (and gate the truncation banner) only for scopes that render it. */onViewModeChange?: (mode: ViewMode) => void;/** Fired when the node color mode changes so the page can sync the URL. */onColorModeChange?: GraphFlowShellProps["onColorModeChange"];+ /** Header/rail slots, forwarded to the shared shell. */+ description?: GraphFlowShellProps["description"];+ headerActions?: GraphFlowShellProps["headerActions"];+ banner?: GraphFlowShellProps["banner"];+ rail?: GraphFlowShellProps["rail"];}export function GraphFlow({@@ -78,8 +83,13 @@ export function GraphFlow({onNodeClick,onNodeViewDocs,onCommunityPanelOpen,+ onSelectedNodeChange,onViewModeChange,onColorModeChange,+ description,+ headerActions,+ banner,+ rail,}: GraphFlowProps) {const router = useRouter();// Constellation (Knowledge Graph) is the default scope.@@ -90,13 +100,18 @@ export function GraphFlow({// Currently-expanded constellation hubs (community ids). Drives the slice// fetch; the shell owns the actual expand/collapse interaction state.const [expandedHubs, setExpandedHubs] = useState<number[]>([]);+ // Latched on first open of the flows panel. It starts closed, so this keeps a+ // trace fetch nobody asked for off every file-scope render.+ const [flowsRequested, setFlowsRequested] = useState(false);+ const handleFlowsVisibilityChange = useCallback((visible: boolean) => {+ if (visible) setFlowsRequested(true);+ }, []);const needsFullGraph = viewMode === "full" || viewMode === "unified";const { graph: fullGraph, isLoading: fullLoading } = useGraph(needsFullGraph ? repoId : null,graphLimit,);- const { graph: archGraph, isLoading: archLoading } = useArchitectureGraph(null);// Constellation community super-graph — only fetched for the radial scope.const { graph: constellationGraph, isLoading: constellationLoading } =useArchitectureCommunityGraph(viewMode === "architecture" ? repoId : null);@@ -115,10 +130,10 @@ export function GraphFlow({const { repo } = useRepo(repoId);const resolvedRepoName = repoName ?? repo?.name;const { communities } = useCommunities(repoId);- // Flow traces highlight file-level nodes; the constellation has none, so it- // skips the fetch. Dead/hot render file graphs, so flows work there too.+ // File-level only (the constellation has no file nodes), and only once the+ // panel that reads them has been opened.const { flows: executionFlowsData } = useExecutionFlows(- viewMode !== "architecture" ? repoId : null,+ flowsRequested && viewMode !== "architecture" ? repoId : null,{top_n: 10,max_depth: 6,@@ -127,10 +142,12 @@ export function GraphFlow({return (<GraphFlowShell+ description={description}+ headerActions={headerActions}+ banner={banner}+ rail={rail}fullGraph={fullGraph as GraphExport | undefined}isLoadingFullGraph={fullLoading}- architectureGraph={archGraph as GraphExport | undefined}- isLoadingArchitectureGraph={archLoading}constellationGraph={constellationGraph as ArchitectureGraph | undefined}isLoadingConstellationGraph={constellationLoading}constellationSlices={constellationSlices as Map<number, CommunitySlice> | undefined}@@ -142,6 +159,7 @@ export function GraphFlow({isLoadingHotFilesGraph={hotLoading}communities={communities as CommunitySummaryItem[] | undefined}executionFlows={executionFlowsData as ExecutionFlows | undefined}+ onFlowsVisibilityChange={handleFlowsVisibilityChange}initialViewMode={initialViewMode}viewMode={controlledViewMode}activeModule={activeModule}@@ -163,6 +181,7 @@ export function GraphFlow({}fileHrefFor={(nodeId) => fileEntityPath(`/repos/${repoId}`, nodeId)}onCommunityPanelOpen={onCommunityPanelOpen}+ onSelectedNodeChange={onSelectedNodeChange}renderPathFinder={(props) => (<PathFinderPanelrepoId={repoId}