From c276cbab296167661b84dced62dc4e6e61f2e6c0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Elberte=20Pl=C3=ADnio?= <elberte.dev@gmail.com>
Date: Mon, 24 Aug 2026 20:33:38 -0300
Subject: [PATCH] feat(review-tutor): add the Structure graph

Add a List | Graph switch inside the Structure view with a
deterministic layered SVG of changed files and their evidence-backed
connections, routed around intermediate nodes, reusing the list's
evidence rows and Open in Diff for the selected node or edge, with an
honest size bound and List as the default everywhere.
---
 packages/review-tutor/src/page-script.ts | 462 ++++++++++++++++++++---
 packages/review-tutor/src/page-styles.ts |  34 ++
 packages/review-tutor/src/page.ts        |   2 +-
 packages/review-tutor/test/page.test.ts  | 442 +++++++++++++++++++++-
 4 files changed, 890 insertions(+), 50 deletions(-)

diff --git a/packages/review-tutor/src/page-script.ts b/packages/review-tutor/src/page-script.ts
index fcb5413..66111fa 100644
--- a/packages/review-tutor/src/page-script.ts
+++ b/packages/review-tutor/src/page-script.ts
@@ -73,7 +73,9 @@ export const pageScript = String.raw`
     structureInputId = null,
     structureStatus = "idle",
     structureRequestSequence = 0,
-    selectedConnection = null;
+    structureMode = readStructureMode(),
+    selectedConnection = null,
+    graphSelection = null;
   const learningBadgeGroups = new Map();
   const foreignActiveIds = new Set();
   let railCollapsed = sessionStorage.getItem("reviewTutorRailCollapsed") === "1";
@@ -379,6 +381,13 @@ export const pageScript = String.raw`
   function structureStatusLabel(status) {
     return status === "modified" ? "edited" : status;
   }
+  function readStructureMode() {
+    try {
+      return sessionStorage.getItem("reviewTutorStructureMode") === "graph" ? "graph" : "list";
+    } catch {
+      return "list";
+    }
+  }
   function structureKindLabel(kind) {
     return kind === "reexport" ? "re-export" : kind === "dynamic-import" ? "dynamic" : kind;
   }
@@ -389,7 +398,12 @@ export const pageScript = String.raw`
     structureInputId = null;
     structureStatus = "idle";
     selectedConnection = null;
+    graphSelection = null;
+    element("structure-mode-switch").hidden = true;
+    element("structure-shared").replaceChildren();
     element("structure-content").replaceChildren();
+    element("structure-graph").replaceChildren();
+    element("structure-graph-evidence")?.remove();
   }
   function clearStructureLanding() {
     document.querySelector(".diff-row.structure-landing")?.classList.remove("structure-landing");
@@ -437,10 +451,371 @@ export const pageScript = String.raw`
     row?.scrollIntoView({ block: "center" });
     control?.focus({ preventScroll: true });
   }
+  function createConnectionRow(edge, key, options = {}) {
+    const evidenceId = "connection-evidence-" + key;
+    const row = document.createElement("button");
+    row.type = "button";
+    row.className = "connection-row";
+    row.dataset.status = edge.status;
+    row.setAttribute("aria-expanded", String(!!options.expanded));
+    row.setAttribute("aria-controls", evidenceId);
+    row.append(
+      makeSpan("connection-kind", structureKindLabel(edge.kind)),
+      makeSpan("connection-target", edge.to),
+    );
+    if (edge.typeOnly) row.append(makeSpan("connection-type", "type"));
+    row.append(makeSpan("connection-status status-chip status-" + edge.status, structureStatusLabel(edge.status)));
+    const evidenceList = document.createElement("ul");
+    evidenceList.id = evidenceId;
+    evidenceList.className = "connection-evidence";
+    evidenceList.hidden = !options.expanded;
+    edge.evidence.forEach((evidence, evidenceIndex) => {
+      const item = document.createElement("li");
+      const code = document.createElement("span");
+      code.className = "evidence-code";
+      code.textContent = evidence.line + "  " + evidence.text;
+      const open = document.createElement("button");
+      open.type = "button";
+      open.className = "ghost open-in-diff";
+      open.textContent = "Open in Diff";
+      open.addEventListener("click", () => jumpToEvidence(evidence, edge.status, evidenceIndex, edge.evidence));
+      item.append(code, open);
+      evidenceList.append(item);
+    });
+    row.addEventListener("click", () => {
+      const expanded = row.getAttribute("aria-expanded") === "true";
+      if (options.listSelection) {
+        if (selectedConnection && selectedConnection !== row) {
+          selectedConnection.classList.remove("selected");
+          selectedConnection.setAttribute("aria-expanded", "false");
+          element(selectedConnection.getAttribute("aria-controls")).hidden = true;
+        }
+        selectedConnection = row;
+        row.classList.add("selected");
+      }
+      row.setAttribute("aria-expanded", String(!expanded));
+      evidenceList.hidden = expanded;
+    });
+    return { row, evidenceList };
+  }
+  function graphTextOrder(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+  }
+  function graphPathOrder(left, right) {
+    const leftSlash = left.lastIndexOf("/");
+    const rightSlash = right.lastIndexOf("/");
+    const directory = graphTextOrder(left.slice(0, Math.max(0, leftSlash)), right.slice(0, Math.max(0, rightSlash)));
+    return directory || graphTextOrder(left, right);
+  }
+  function graphLabel(path) {
+    return path.length <= 40 ? path : path.slice(0, 19) + "…" + path.slice(-20);
+  }
+  function graphNumber(value) {
+    return String(Math.round(value * 100) / 100);
+  }
+  function graphPath(points) {
+    return points.map((point, index) => (index ? "L" : "M") + graphNumber(point.x) + " " + graphNumber(point.y)).join(" ");
+  }
+  function layoutStructureGraph(snapshot) {
+    const endpoints = new Set(snapshot.edges.flatMap((edge) => [edge.from, edge.to]));
+    const filesByPath = new Map(snapshot.files.filter((file) => file.analyzed && endpoints.has(file.path)).map((file) => [file.path, file]));
+    const paths = [...filesByPath.keys()].sort(graphPathOrder);
+    const edges = snapshot.edges
+      .filter((edge) => filesByPath.has(edge.from) && filesByPath.has(edge.to))
+      .map((edge, index) => ({ ...edge, graphIndex: index }))
+      .sort((left, right) => graphTextOrder(left.from, right.from) || graphTextOrder(left.to, right.to) || graphTextOrder(left.kind, right.kind) || left.graphIndex - right.graphIndex);
+    if (!paths.length) return { nodes: [], edges, width: 0, height: 0, coordinates: "" };
+    const adjacency = new Map(paths.map((path) => [path, []]));
+    const retained = [];
+    function reaches(start, target) {
+      const pending = [start], seen = new Set();
+      while (pending.length) {
+        const path = pending.pop();
+        if (path === target) return true;
+        if (seen.has(path)) continue;
+        seen.add(path);
+        pending.push(...adjacency.get(path));
+      }
+      return false;
+    }
+    // Layout edges are considered by path order; rejecting an edge that closes a cycle removes the back-edge whose from path is lexicographically later.
+    for (const edge of edges) {
+      if (reaches(edge.to, edge.from)) continue;
+      adjacency.get(edge.from).push(edge.to);
+      adjacency.get(edge.from).sort(graphTextOrder);
+      retained.push(edge);
+    }
+    const incoming = new Map(paths.map((path) => [path, 0]));
+    for (const edge of retained) incoming.set(edge.to, incoming.get(edge.to) + 1);
+    const layers = new Map(paths.map((path) => [path, 0]));
+    const pending = paths.filter((path) => incoming.get(path) === 0).sort(graphTextOrder);
+    while (pending.length) {
+      const path = pending.shift();
+      for (const target of adjacency.get(path)) {
+        layers.set(target, Math.max(layers.get(target), layers.get(path) + 1));
+        incoming.set(target, incoming.get(target) - 1);
+        if (incoming.get(target) === 0) {
+          pending.push(target);
+          pending.sort(graphTextOrder);
+        }
+      }
+    }
+    const NODE_HEIGHT = 28, COLUMN_GAP = 72, ROW_GAP = 12, CH_WIDTH = 7.2, HORIZONTAL_PADDING = 20, OUTER_PADDING = 12;
+    const layerPaths = [];
+    for (const path of paths) {
+      const layer = layers.get(path);
+      if (!layerPaths[layer]) layerPaths[layer] = [];
+      layerPaths[layer].push(path);
+    }
+    layerPaths.forEach((items) => items.sort(graphPathOrder));
+    const positions = new Map();
+    let x = OUTER_PADDING;
+    for (let layer = 0; layer < layerPaths.length; layer++) {
+      const items = layerPaths[layer] || [];
+      const widths = items.map((path) => Math.round((graphLabel(path).length * CH_WIDTH + HORIZONTAL_PADDING) * 10) / 10);
+      const columnWidth = Math.max(...widths);
+      items.forEach((path, row) => positions.set(path, {
+        path,
+        file: filesByPath.get(path),
+        label: graphLabel(path),
+        layer,
+        x,
+        y: OUTER_PADDING + row * (NODE_HEIGHT + ROW_GAP),
+        width: widths[row],
+        height: NODE_HEIGHT,
+      }));
+      x += columnWidth + COLUMN_GAP;
+    }
+    const nodes = [...positions.values()].sort((left, right) => left.layer - right.layer || graphPathOrder(left.path, right.path));
+    const drawingBottom = Math.max(...nodes.map((node) => node.y + node.height)) + OUTER_PADDING;
+    const layerBounds = new Map();
+    for (const node of nodes) {
+      const bounds = layerBounds.get(node.layer) || { x: node.x, right: node.x + node.width, bottom: 0 };
+      bounds.x = Math.min(bounds.x, node.x);
+      bounds.right = Math.max(bounds.right, node.x + node.width);
+      bounds.bottom = Math.max(bounds.bottom, node.y + node.height);
+      layerBounds.set(node.layer, bounds);
+    }
+    const routeKinds = new Map(), portGroups = new Map(), ports = new Map();
+    function addPort(key, edge, endpoint) {
+      const group = portGroups.get(key) || [];
+      group.push({ edge, endpoint });
+      portGroups.set(key, group);
+    }
+    for (const edge of edges) {
+      const from = positions.get(edge.from), to = positions.get(edge.to);
+      const route = to.layer <= from.layer ? "back" : to.layer - from.layer > 1 ? "long" : "adjacent";
+      routeKinds.set(edge, route);
+      addPort("out:right:" + edge.from, edge, "from");
+      addPort("in:" + (route === "back" ? "right:" : "left:") + edge.to, edge, "to");
+    }
+    for (const group of portGroups.values())
+      group.forEach(({ edge, endpoint }, index) => {
+        const port = ports.get(edge) || { from: 0, to: 0 };
+        port[endpoint] = (index - (group.length - 1) / 2) * 6;
+        ports.set(edge, port);
+      });
+    const longEdgeLanes = new Map(), backEdges = [];
+    const routedEdges = edges.map((edge) => {
+      const from = positions.get(edge.from), to = positions.get(edge.to), port = ports.get(edge), route = routeKinds.get(edge);
+      const fromY = from.y + from.height / 2 + port.from, toY = to.y + to.height / 2 + port.to;
+      if (route === "long") {
+        const points = [{ x: from.x + from.width, y: fromY }];
+        for (let layer = from.layer + 1; layer < to.layer; layer++) {
+          const bounds = layerBounds.get(layer), lane = longEdgeLanes.get(layer) || 0;
+          const y = bounds.bottom + ROW_GAP / 2 + lane * ROW_GAP;
+          longEdgeLanes.set(layer, lane + 1);
+          points.push({ x: bounds.x, y }, { x: bounds.right, y });
+        }
+        points.push({ x: to.x, y: toY });
+        return { ...edge, route, points };
+      }
+      if (route === "back") {
+        const lane = backEdges.length;
+        backEdges.push(edge);
+        const y = drawingBottom + ROW_GAP * (1 + lane);
+        const fromGutter = layerBounds.get(from.layer).right + COLUMN_GAP / 2;
+        const toGutter = layerBounds.get(to.layer).right + COLUMN_GAP / 2;
+        return { ...edge, route, points: [
+          { x: from.x + from.width, y: fromY },
+          { x: fromGutter, y: fromY },
+          { x: fromGutter, y },
+          { x: toGutter, y },
+          { x: toGutter, y: toY },
+          { x: to.x + to.width, y: toY },
+        ] };
+      }
+      return { ...edge, route, points: [
+        { x: from.x + from.width, y: fromY },
+        { x: to.x, y: toY },
+      ] };
+    });
+    const width = Math.max(
+      ...nodes.map((node) => node.x + node.width),
+      ...layerBounds.values().map((bounds) => bounds.right + COLUMN_GAP / 2),
+    ) + OUTER_PADDING;
+    const routeBottom = Math.max(drawingBottom, ...routedEdges.flatMap((edge) => edge.points.map((point) => point.y)));
+    const height = routeBottom + OUTER_PADDING;
+    const coordinates = nodes.map((node) => [node.path, node.layer, node.x, node.y, node.width, node.height].join("@")).join("|");
+    return { nodes, edges: routedEdges, width, height, coordinates };
+  }
+  function renderGraphEvidence(edges, expand) {
+    const graph = element("structure-graph");
+    element("structure-graph-evidence")?.remove();
+    if (!edges.length) return;
+    const panel = document.createElement("div");
+    panel.id = "structure-graph-evidence";
+    panel.className = "connection-list structure-graph-evidence";
+    edges.forEach((edge, index) => {
+      const rendered = createConnectionRow(edge, "graph-" + index, { expanded: expand });
+      panel.append(rendered.row, rendered.evidenceList);
+    });
+    graph.after(panel);
+  }
+  function clearGraphSelection(restoreFocus = false) {
+    graphSelection = null;
+    element("structure-graph")?.querySelectorAll(".structure-graph-edge.graph-selected .structure-graph-line").forEach((path) =>
+      path.setAttribute("marker-end", "url(#structure-arrow-" + path.dataset.marker + ")"));
+    element("structure-graph")?.querySelectorAll(".graph-selected").forEach((node) => node.classList.remove("graph-selected"));
+    element("structure-graph-evidence")?.remove();
+    if (restoreFocus) element("structure-mode-graph").focus();
+  }
+  function selectGraphItem(type, item, control) {
+    clearGraphSelection();
+    graphSelection = { type, item };
+    control.classList.add("graph-selected");
+    if (type === "edge") {
+      control.querySelector(".structure-graph-line").setAttribute("marker-end", "url(#structure-arrow-selected)");
+      renderGraphEvidence([item], true);
+      announce(item.from + " to " + item.to + " connection selected.");
+    } else {
+      const outgoing = structureSnapshot.edges.filter((edge) => edge.from === item.path).sort((left, right) => graphTextOrder(left.to, right.to) || graphTextOrder(left.kind, right.kind));
+      renderGraphEvidence(outgoing, false);
+      announce(item.path + ", " + structureStatusLabel(item.file.status) + " selected.");
+    }
+  }
+  function graphControlEvents(control, type, item) {
+    control.addEventListener("click", () => selectGraphItem(type, item, control));
+    control.addEventListener("keydown", (event) => {
+      if (event.key === "Escape") {
+        clearGraphSelection(true);
+        announce("Selection cleared.");
+        event.preventDefault();
+      } else if (event.key === "Enter" || event.key === " ") {
+        selectGraphItem(type, item, control);
+        event.preventDefault();
+      }
+    });
+  }
+  function renderStructureGraph(snapshot) {
+    const container = element("structure-graph");
+    container.replaceChildren();
+    const layout = layoutStructureGraph(snapshot);
+    if (layout.nodes.length > 60 || layout.edges.length > 200) {
+      const note = document.createElement("p");
+      note.className = "empty";
+      note.textContent = "Graph is too large for this view (" + layout.nodes.length + " files, " + layout.edges.length + " connections). Use the list.";
+      container.append(note);
+      return;
+    }
+    if (!layout.nodes.length) {
+      const empty = document.createElement("p");
+      empty.className = "empty";
+      empty.textContent = "No connections to draw.";
+      container.append(empty);
+      return;
+    }
+    const NS = "http://www.w3.org/2000/svg";
+    const svg = document.createElementNS(NS, "svg");
+    svg.classList.add("structure-graph-svg");
+    svg.setAttribute("role", "group");
+    svg.setAttribute("aria-label", "Structure graph, " + layout.nodes.length + " files, " + layout.edges.length + " connections");
+    svg.setAttribute("viewBox", "0 0 " + layout.width + " " + layout.height);
+    svg.setAttribute("width", String(layout.width));
+    svg.setAttribute("height", String(layout.height));
+    svg.dataset.layout = layout.coordinates;
+    const defs = document.createElementNS(NS, "defs");
+    for (const status of ["added", "removed", "modified", "unchanged", "selected"]) {
+      const marker = document.createElementNS(NS, "marker");
+      marker.id = "structure-arrow-" + status;
+      marker.classList.add("structure-graph-marker", "status-" + status);
+      marker.setAttribute("viewBox", "0 0 6 6");
+      marker.setAttribute("refX", "5");
+      marker.setAttribute("refY", "3");
+      marker.setAttribute("markerWidth", "5");
+      marker.setAttribute("markerHeight", "5");
+      marker.setAttribute("orient", "auto");
+      const arrow = document.createElementNS(NS, "path");
+      arrow.setAttribute("d", "M0 0 L6 3 L0 6 Z");
+      marker.append(arrow);
+      defs.append(marker);
+    }
+    svg.append(defs);
+    for (const node of layout.nodes) {
+      const group = document.createElementNS(NS, "g");
+      group.classList.add("structure-graph-node", "status-" + node.file.status);
+      group.dataset.path = node.path;
+      group.dataset.layer = String(node.layer);
+      group.setAttribute("tabindex", "0");
+      group.setAttribute("role", "button");
+      group.setAttribute("aria-label", node.path + ", " + structureStatusLabel(node.file.status));
+      const rect = document.createElementNS(NS, "rect");
+      rect.setAttribute("x", String(node.x));
+      rect.setAttribute("y", String(node.y));
+      rect.setAttribute("width", String(node.width));
+      rect.setAttribute("height", String(node.height));
+      rect.setAttribute("rx", "5");
+      const label = document.createElementNS(NS, "text");
+      label.setAttribute("x", String(node.x + 10));
+      label.setAttribute("y", String(node.y + 18));
+      label.textContent = node.label;
+      if (node.path.length > 40) {
+        const title = document.createElementNS(NS, "title");
+        title.textContent = node.path;
+        group.append(title);
+      }
+      group.append(rect, label);
+      graphControlEvents(group, "node", node);
+      svg.append(group);
+    }
+    for (const edge of layout.edges) {
+      const group = document.createElementNS(NS, "g");
+      group.classList.add("structure-graph-edge", "status-" + edge.status);
+      if (edge.typeOnly) group.classList.add("type-only");
+      group.dataset.from = edge.from;
+      group.dataset.to = edge.to;
+      group.dataset.status = edge.status;
+      group.setAttribute("tabindex", "0");
+      group.setAttribute("role", "button");
+      group.setAttribute("aria-label", edge.from + " → " + edge.to + ", " + structureKindLabel(edge.kind) + ", " + structureStatusLabel(edge.status));
+      const d = graphPath(edge.points);
+      const hit = document.createElementNS(NS, "path");
+      hit.classList.add("structure-graph-hit");
+      hit.setAttribute("d", d);
+      hit.setAttribute("style", "fill:none;stroke:transparent;stroke-width:14;pointer-events:stroke");
+      const path = document.createElementNS(NS, "path");
+      path.classList.add("structure-graph-line");
+      path.dataset.marker = edge.status;
+      path.setAttribute("d", d);
+      path.setAttribute("fill", "none");
+      path.setAttribute("marker-end", "url(#structure-arrow-" + edge.status + ")");
+      group.append(hit, path);
+      graphControlEvents(group, "edge", edge);
+      svg.append(group);
+    }
+    container.append(svg);
+  }
   function renderStructure() {
     selectedConnection = null;
-    const container = element("structure-content");
+    graphSelection = null;
+    const shared = element("structure-shared"), container = element("structure-content"), graph = element("structure-graph"), modeSwitch = element("structure-mode-switch");
+    shared.replaceChildren();
     container.replaceChildren();
+    graph.replaceChildren();
+    element("structure-graph-evidence")?.remove();
+    modeSwitch.hidden = true;
+    container.hidden = false;
+    graph.hidden = true;
     if (!currentSource || structureStatus === "loading") {
       const empty = document.createElement("p");
       empty.className = "empty";
@@ -470,11 +845,17 @@ export const pageScript = String.raw`
     }
     if (!structureSnapshot) return;
     const snapshot = structureSnapshot;
+    modeSwitch.hidden = false;
+    for (const mode of ["list", "graph"]) {
+      const tab = element("structure-mode-" + mode), selected = mode === structureMode;
+      tab.setAttribute("aria-selected", String(selected));
+      tab.tabIndex = selected ? 0 : -1;
+    }
     const comparison = document.createElement("p");
     comparison.id = "structure-comparison";
     comparison.className = "structure-comparison";
     comparison.textContent = snapshot.comparison.from + " → " + snapshot.comparison.to;
-    container.append(comparison);
+    shared.append(comparison);
     const disclosureItems = [
       ...snapshot.comparison.reasons.map((reason) => ({ reason })),
       ...snapshot.limits.omitted,
@@ -496,7 +877,7 @@ export const pageScript = String.raw`
       }
       details.append(summary, reasons);
       notice.append(sentence, details);
-      container.append(notice);
+      shared.append(notice);
     }
     if (!snapshot.edges.length)
       container.append(makeSpan("structure-zero", "No connections among changed files. Unchanged neighbours are outside this view."));
@@ -524,54 +905,17 @@ export const pageScript = String.raw`
       const list = document.createElement("div");
       list.className = "connection-list";
       connections.forEach((edge, edgeIndex) => {
-        const key = fileIndex + "-" + edgeIndex;
-        const evidenceId = "connection-evidence-" + key;
-        const row = document.createElement("button");
-        row.type = "button";
-        row.className = "connection-row";
-        row.dataset.status = edge.status;
-        row.setAttribute("aria-expanded", "false");
-        row.setAttribute("aria-controls", evidenceId);
-        row.append(
-          makeSpan("connection-kind", structureKindLabel(edge.kind)),
-          makeSpan("connection-target", edge.to),
-        );
-        if (edge.typeOnly) row.append(makeSpan("connection-type", "type"));
-        row.append(makeSpan("connection-status status-chip status-" + edge.status, structureStatusLabel(edge.status)));
-        const evidenceList = document.createElement("ul");
-        evidenceList.id = evidenceId;
-        evidenceList.className = "connection-evidence";
-        evidenceList.hidden = true;
-        edge.evidence.forEach((evidence, evidenceIndex) => {
-          const item = document.createElement("li");
-          const code = document.createElement("span");
-          code.className = "evidence-code";
-          code.textContent = evidence.line + "  " + evidence.text;
-          const open = document.createElement("button");
-          open.type = "button";
-          open.className = "ghost open-in-diff";
-          open.textContent = "Open in Diff";
-          open.addEventListener("click", () => jumpToEvidence(evidence, edge.status, evidenceIndex, edge.evidence));
-          item.append(code, open);
-          evidenceList.append(item);
-        });
-        row.addEventListener("click", () => {
-          const expanded = row.getAttribute("aria-expanded") === "true";
-          if (selectedConnection && selectedConnection !== row) {
-            selectedConnection.classList.remove("selected");
-            selectedConnection.setAttribute("aria-expanded", "false");
-            element(selectedConnection.getAttribute("aria-controls")).hidden = true;
-          }
-          selectedConnection = row;
-          row.classList.add("selected");
-          row.setAttribute("aria-expanded", String(!expanded));
-          evidenceList.hidden = expanded;
-        });
-        list.append(row, evidenceList);
+        const rendered = createConnectionRow(edge, fileIndex + "-" + edgeIndex, { listSelection: true });
+        list.append(rendered.row, rendered.evidenceList);
       });
       if (connections.length) group.append(list);
       container.append(group);
     });
+    if (structureMode === "graph") {
+      container.hidden = true;
+      graph.hidden = false;
+      renderStructureGraph(snapshot);
+    }
   }
   function ensureStructure() {
     if (!currentSource) {
@@ -609,6 +953,23 @@ export const pageScript = String.raw`
       announce("Structure analysis failed: " + structureError);
     });
   }
+  function setStructureMode(mode) {
+    structureMode = mode === "graph" ? "graph" : "list";
+    try { sessionStorage.setItem("reviewTutorStructureMode", structureMode); } catch {}
+    renderStructure();
+    announce(structureMode === "graph" ? "Structure graph mode." : "Structure list mode.");
+  }
+  function handleStructureModeKey(event) {
+    if (!["ArrowLeft", "ArrowRight", "Home", "End", "Enter", " "].includes(event.key)) return;
+    const tabs = [element("structure-mode-list"), element("structure-mode-graph")];
+    if (event.key === "Enter" || event.key === " ") setStructureMode(event.currentTarget.id.endsWith("graph") ? "graph" : "list");
+    else {
+      const target = event.key === "ArrowLeft" || event.key === "Home" ? tabs[0] : tabs[1];
+      tabs.forEach((tab) => { tab.tabIndex = tab === target ? 0 : -1; });
+      target.focus();
+    }
+    event.preventDefault();
+  }
   function setView(view, focusPanel = false) {
     activeView = ["diff", "structure", "log"].includes(view) ? view : "diff";
     if (activeView !== "diff") hideInlineComposer();
@@ -1779,6 +2140,11 @@ export const pageScript = String.raw`
     element(id).addEventListener("click", () => setView(id.replace("view-", "")));
     element(id).addEventListener("keydown", handleViewKey);
   }
+  for (const mode of ["list", "graph"]) {
+    const tab = element("structure-mode-" + mode);
+    tab.addEventListener("click", () => setStructureMode(mode));
+    tab.addEventListener("keydown", handleStructureModeKey);
+  }
   element("history-previous").addEventListener("click", () => renderHistoryEntry(Math.max(0, historyIndex - 1)));
   element("history-next").addEventListener("click", () => renderHistoryEntry(Math.min(historyEntries.length - 1, historyIndex + 1)));
   element("question").addEventListener("input", updateActions);
diff --git a/packages/review-tutor/src/page-styles.ts b/packages/review-tutor/src/page-styles.ts
index 58d3440..72e83d0 100644
--- a/packages/review-tutor/src/page-styles.ts
+++ b/packages/review-tutor/src/page-styles.ts
@@ -290,6 +290,40 @@ position:fixed;top:calc(var(--topbar-h) + 10px);left:50%;translate:-50% 0;z-inde
 display:none}
 .structure-section {
 contain:layout;min-width:0;padding:14px 14px 100px;overflow-x:hidden}
+.structure-mode-switch {
+width:max-content;margin:0 0 10px}
+#structure-graph {
+max-width:100%;overflow-x:auto;overflow-y:hidden}
+.structure-graph-svg {
+display:block;max-width:none}
+.structure-graph-node,.structure-graph-edge {
+cursor:pointer}
+.structure-graph-node rect {
+fill:var(--surface-1);stroke:var(--hairline);stroke-width:1}
+.structure-graph-node text {
+fill:currentColor;font:12px var(--font-mono)}
+.structure-graph-node.status-added,.structure-graph-edge.status-added,.structure-graph-marker.status-added {
+color:var(--green)}
+.structure-graph-node.status-removed,.structure-graph-edge.status-removed,.structure-graph-marker.status-removed {
+color:var(--rose)}
+.structure-graph-node.status-modified,.structure-graph-edge.status-modified,.structure-graph-marker.status-modified {
+color:var(--amber)}
+.structure-graph-node.status-unchanged,.structure-graph-node.status-renamed,.structure-graph-edge.status-unchanged,.structure-graph-marker.status-unchanged {
+color:var(--muted)}
+.structure-graph-marker.status-selected {
+color:var(--ember)}
+.structure-graph-edge .structure-graph-line {
+stroke:currentColor;stroke-width:1;vector-effect:non-scaling-stroke}
+.structure-graph-edge.status-removed .structure-graph-line {
+stroke-dasharray:4 3}
+.structure-graph-edge.type-only {
+opacity:.7}
+.structure-graph-marker path {
+fill:currentColor}
+.structure-graph-node.graph-selected rect,.structure-graph-edge.graph-selected .structure-graph-line {
+stroke:var(--ember);stroke-width:2}
+.structure-graph-evidence {
+margin-top:12px;border-top:1px solid var(--hairline)}
 .structure-comparison {
 margin:0 0 10px;color:var(--subtle);font:12px var(--font-mono)}
 .structure-partial {
diff --git a/packages/review-tutor/src/page.ts b/packages/review-tutor/src/page.ts
index 0af82c4..5944b8b 100644
--- a/packages/review-tutor/src/page.ts
+++ b/packages/review-tutor/src/page.ts
@@ -41,7 +41,7 @@ export const pageHtml = `<!doctype html>
 <div id="selection-card" class="selection-card"><div class="selection-head"><strong id="selection-summary" class="selection-meta">No code selected</strong><button id="clear-selection" class="ghost" hidden>Clear</button></div><div id="selection-preview" class="selection-preview"></div><p id="selection-helper" class="helper" hidden>Shift-click line numbers to extend the selection. Select + to ask.</p></div>
 <label class="field"><span>Mode</span><select id="mode"><option value="explain">Explain</option><option value="quiz">Quiz me</option></select></label><label class="field"><span>Question</span><textarea id="question" class="question" maxlength="4096" placeholder="What does this change do?"></textarea></label>
 <div class="ask-row"><button id="ask" class="primary" aria-busy="false" disabled>Ask</button><button id="cancel" class="ghost" disabled>Cancel</button><span id="question-state" hidden></span></div><p id="ask-helper" class="ask-helper">Load a source and enter a question.</p><div id="answer" class="answer" hidden><div class="answer-head"><span class="answer-label" aria-hidden="true">Answer</span><div id="history-pager" class="history-pager" hidden><button id="history-previous" class="ghost" aria-label="Newer saved answer">‹</button><span id="history-position"></span><button id="history-next" class="ghost" aria-label="Older saved answer">›</button></div></div><div id="answer-text" class="answer-text"></div><div id="answer-tail" class="helper"></div></div></section>
-<div id="diff-scroll" class="diff-scroll"><div id="diff" role="tabpanel" aria-labelledby="view-diff"><p class="empty">Load a source to begin reviewing.</p></div><section id="structure-section" class="structure-section" role="tabpanel" aria-labelledby="view-structure structure-title" hidden><h2 id="structure-title" class="sr-only" tabindex="-1">Connections</h2><div id="structure-content"></div></section><section id="log-section" class="log-section" role="tabpanel" aria-labelledby="view-log log-title" hidden><div class="log-head"><h2 id="log-title" class="eyebrow" tabindex="-1">Learning log</h2><label class="sr-only" for="log-filter">Filter</label><select id="log-filter"><option value="all">All</option><option value="later">Review later</option></select><button id="refresh" class="ghost">Refresh</button><button id="export" class="ghost">Export HTML</button></div><div id="log"></div></section></div>
+<div id="diff-scroll" class="diff-scroll"><div id="diff" role="tabpanel" aria-labelledby="view-diff"><p class="empty">Load a source to begin reviewing.</p></div><section id="structure-section" class="structure-section" role="tabpanel" aria-labelledby="view-structure structure-title" hidden><h2 id="structure-title" class="sr-only" tabindex="-1">Connections</h2><div id="structure-mode-switch" class="view-switch structure-mode-switch" role="tablist" aria-label="Structure mode" hidden><button id="structure-mode-list" class="view-tab" role="tab" aria-selected="true" aria-controls="structure-content" tabindex="0">List</button><button id="structure-mode-graph" class="view-tab" role="tab" aria-selected="false" aria-controls="structure-graph" tabindex="-1">Graph</button></div><div id="structure-shared"></div><div id="structure-content" role="tabpanel" aria-labelledby="structure-mode-list" tabindex="0"></div><div id="structure-graph" role="tabpanel" aria-labelledby="structure-mode-graph" tabindex="0" hidden></div></section><section id="log-section" class="log-section" role="tabpanel" aria-labelledby="view-log log-title" hidden><div class="log-head"><h2 id="log-title" class="eyebrow" tabindex="-1">Learning log</h2><label class="sr-only" for="log-filter">Filter</label><select id="log-filter"><option value="all">All</option><option value="later">Review later</option></select><button id="refresh" class="ghost">Refresh</button><button id="export" class="ghost">Export HTML</button></div><div id="log"></div></section></div>
 </section>
 <aside id="config-dialog" class="rail" aria-label="Configuration" tabindex="-1"><div class="rail-head"><span id="config-title" class="eyebrow rail-eyebrow">Configuration</span><button id="toggle-rail" class="ghost rail-toggle" aria-expanded="true" aria-controls="config-section" aria-label="Collapse configuration">›</button></div><section id="config-section" class="config-section"><label class="field"><span>Harness</span><select id="harness"><option value="pi">Pi</option></select></label><p class="helper">Pi is the only connected harness.</p><div class="two"><label class="field"><span>Model</span><select id="model"></select></label><label class="field"><span>Thinking</span><select id="thinking"></select></label></div><label class="field"><span>Explanation language</span><select id="language"></select></label><fieldset class="matches"><legend class="group-label">Closest matches</legend><p class="helper">Up to three languages you already know.</p><div class="three"><label class="field"><span>Match 1</span><select id="match-1" class="match"></select></label><label class="field"><span>Match 2</span><select id="match-2" class="match"></select></label><label class="field"><span>Match 3</span><select id="match-3" class="match"></select></label></div></fieldset><div class="config-actions"><button id="jump-log" class="ghost">Learning log</button></div></section></aside></main><button id="mobile-ask" class="mobile-ask">Ask the tutor</button>
 <script>${pageScript}</script></body></html>`;
diff --git a/packages/review-tutor/test/page.test.ts b/packages/review-tutor/test/page.test.ts
index 86dec8c..88bd871 100644
--- a/packages/review-tutor/test/page.test.ts
+++ b/packages/review-tutor/test/page.test.ts
@@ -119,6 +119,8 @@ async function boot(options: {
   source?: typeof source;
   storedPageId?: string;
   storedQuizIds?: string;
+  storedStructureMode?: string;
+  throwStructureModeRead?: boolean;
   stateResponses?: unknown[];
   structureResponses?: Array<Promise<Response> | Response | unknown | Error>;
   failHeartbeat?: boolean;
@@ -129,7 +131,15 @@ async function boot(options: {
   Object.defineProperty(window, "innerWidth", { value: options.width ?? 1440, writable: true, configurable: true });
   if (options.storedPageId !== undefined) window.sessionStorage.setItem("reviewTutorPageId", options.storedPageId);
   if (options.storedQuizIds !== undefined) window.sessionStorage.setItem("reviewTutorQuizEntryIds", options.storedQuizIds);
+  if (options.storedStructureMode !== undefined) window.sessionStorage.setItem("reviewTutorStructureMode", options.storedStructureMode);
   if (options.railCollapsed) window.sessionStorage.setItem("reviewTutorRailCollapsed", "1");
+  if (options.throwStructureModeRead) {
+    const getItem = window.sessionStorage.getItem.bind(window.sessionStorage);
+    window.sessionStorage.getItem = vi.fn((key: string) => {
+      if (key === "reviewTutorStructureMode") throw new Error("storage blocked");
+      return getItem(key);
+    });
+  }
   const script = pageHtml.match(/<script>([\s\S]*?)<\/script>/)?.[1];
   if (!script) throw new Error("Inline page script was not composed");
   window.document.documentElement.innerHTML = pageHtml
@@ -214,6 +224,54 @@ function input(document: TestDocument, id: string, value: string) {
   return node;
 }
 
+type GraphPoint = { x: number; y: number };
+type GraphRect = GraphPoint & { width: number; height: number };
+
+function graphPathPoints(path: any): GraphPoint[] {
+  const values = (path.getAttribute("d")?.match(/-?\d+(?:\.\d+)?/g) ?? []).map(Number);
+  return Array.from({ length: values.length / 2 }, (_, index) => ({ x: values[index * 2], y: values[index * 2 + 1] }));
+}
+
+function segmentIntersectsRect(start: GraphPoint, end: GraphPoint, rect: GraphRect) {
+  const inset = 0.001;
+  const left = rect.x + inset, right = rect.x + rect.width - inset;
+  const top = rect.y + inset, bottom = rect.y + rect.height - inset;
+  let near = 0, far = 1;
+  const dimensions: Array<[number, number, number, number]> = [
+    [start.x, end.x - start.x, left, right],
+    [start.y, end.y - start.y, top, bottom],
+  ];
+  for (const [origin, delta, minimum, maximum] of dimensions) {
+    if (Math.abs(delta) < inset) {
+      if (origin < minimum || origin > maximum) return false;
+      continue;
+    }
+    const first = (minimum - origin) / delta, second = (maximum - origin) / delta;
+    near = Math.max(near, Math.min(first, second));
+    far = Math.min(far, Math.max(first, second));
+    if (near > far) return false;
+  }
+  return true;
+}
+
+function graphNodeRects(document: TestDocument): GraphRect[] {
+  return Array.from(document.querySelectorAll(".structure-graph-node rect")).map((rect: any) => ({
+    x: Number(rect.getAttribute("x")),
+    y: Number(rect.getAttribute("y")),
+    width: Number(rect.getAttribute("width")),
+    height: Number(rect.getAttribute("height")),
+  }));
+}
+
+function expectGraphPathsClearNodes(document: TestDocument) {
+  const rects = graphNodeRects(document);
+  for (const path of Array.from(document.querySelectorAll(".structure-graph-edge .structure-graph-line")) as any[]) {
+    const points = graphPathPoints(path);
+    for (let index = 1; index < points.length; index++)
+      expect(rects.some((rect) => segmentIntersectsRect(points[index - 1]!, points[index]!, rect)), path.getAttribute("d")).toBe(false);
+  }
+}
+
 describe("Review Tutor composed page", () => {
   it("contains safe local assets and an executable raw inline script", () => {
     expect(() => new Function(pageHtml.match(/<script>([\s\S]*?)<\/script>/)?.[1] ?? "")).not.toThrow();
@@ -326,6 +384,12 @@ describe("Review Tutor composed page", () => {
     expect(byId(document, "log-section").previousElementSibling).toBe(byId(document, "structure-section"));
     expect(byId(document, "diff").getAttribute("role")).toBe("tabpanel");
     expect(byId(document, "structure-section").getAttribute("role")).toBe("tabpanel");
+    expect(byId(document, "structure-content").getAttribute("role")).toBe("tabpanel");
+    expect(byId(document, "structure-content").getAttribute("aria-labelledby")).toBe("structure-mode-list");
+    expect(byId(document, "structure-content").tabIndex).toBe(0);
+    expect(byId(document, "structure-graph").getAttribute("role")).toBe("tabpanel");
+    expect(byId(document, "structure-graph").getAttribute("aria-labelledby")).toBe("structure-mode-graph");
+    expect(byId(document, "structure-graph").tabIndex).toBe(0);
     expect(byId(document, "log-section").getAttribute("role")).toBe("tabpanel");
     expect(byId(document, "log-section").hidden).toBe(true);
     expect(byId(document, "view-diff").getAttribute("aria-selected")).toBe("true");
@@ -342,12 +406,388 @@ describe("Review Tutor composed page", () => {
     byId(document, "view-diff").dispatchEvent(new window.KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true }));
     expect(document.activeElement).toBe(byId(document, "view-structure"));
     expect(tabs.map((tab) => tab.tabIndex)).toEqual([-1, 0, -1]);
-    expect(Array.from(document.querySelectorAll('.view-tab[tabindex="0"]'))).toEqual([byId(document, "view-structure")]);
+    expect(Array.from(byId(document, "view-switch").querySelectorAll('.view-tab[tabindex="0"]'))).toEqual([byId(document, "view-structure")]);
     byId(document, "view-structure").dispatchEvent(new window.KeyboardEvent("keydown", { key: "End", bubbles: true }));
     expect(document.activeElement).toBe(byId(document, "view-log"));
     expect(tabs.map((tab) => tab.tabIndex)).toEqual([-1, -1, 0]);
   });
 
+  it("defaults the Structure switch to List and persists Graph per tab without refetching", async () => {
+    const loaded = await boot({ width: 860 });
+    byId(loaded.document, "view-structure").click();
+    await flush();
+
+    expect(byId(loaded.document, "structure-mode-list").getAttribute("aria-selected")).toBe("true");
+    expect(byId(loaded.document, "structure-content").hidden).toBe(false);
+    expect(loaded.window.sessionStorage.getItem("reviewTutorStructureMode")).toBeNull();
+    byId(loaded.document, "structure-mode-graph").click();
+    expect(loaded.window.sessionStorage.getItem("reviewTutorStructureMode")).toBe("graph");
+    expect(byId(loaded.document, "structure-content").hidden).toBe(true);
+    expect(byId(loaded.document, "structure-graph").hidden).toBe(false);
+    expect(byId(loaded.document, "structure-shared").contains(byId(loaded.document, "structure-partial"))).toBe(true);
+    expect(loaded.requests.filter((request) => request.path === "/api/structure")).toHaveLength(1);
+    expect(byId(loaded.document, "lifecycle").textContent).toBe("Structure graph mode.");
+
+    const restored = await boot({ storedStructureMode: "graph" });
+    byId(restored.document, "view-structure").click();
+    await flush();
+    expect(byId(restored.document, "structure-mode-graph").getAttribute("aria-selected")).toBe("true");
+    expect(byId(restored.document, "structure-graph").hidden).toBe(false);
+
+    const invalid = await boot({ storedStructureMode: "invalid" });
+    byId(invalid.document, "view-structure").click();
+    await flush();
+    expect(byId(invalid.document, "structure-mode-list").getAttribute("aria-selected")).toBe("true");
+
+    const readFailure = await boot({ throwStructureModeRead: true });
+    byId(readFailure.document, "view-structure").click();
+    await flush();
+    expect(byId(readFailure.document, "structure-mode-list").getAttribute("aria-selected")).toBe("true");
+
+    const writeFailure = await boot();
+    byId(writeFailure.document, "view-structure").click();
+    await flush();
+    const setItem = writeFailure.window.sessionStorage.setItem.bind(writeFailure.window.sessionStorage);
+    writeFailure.window.sessionStorage.setItem = vi.fn(() => { throw new Error("storage blocked"); });
+    expect(() => byId(writeFailure.document, "structure-mode-graph").click()).not.toThrow();
+    expect(byId(writeFailure.document, "structure-graph").hidden).toBe(false);
+    writeFailure.window.sessionStorage.setItem = setItem;
+  });
+
+  it("lays out DAGs and cycles deterministically with directory ordering", async () => {
+    const dag = {
+      ...structure,
+      comparison: { ...structure.comparison, partial: false, reasons: [] },
+      files: [
+        { path: "z/a.ts", status: "added", analyzed: true },
+        { path: "a/z.ts", status: "modified", analyzed: true },
+        { path: "mid/b.ts", status: "modified", analyzed: true },
+        { path: "end/d.ts", status: "unchanged", analyzed: true },
+      ],
+      edges: [
+        { from: "z/a.ts", to: "mid/b.ts", kind: "import", typeOnly: false, status: "added", evidence: [] },
+        { from: "a/z.ts", to: "mid/b.ts", kind: "import", typeOnly: false, status: "modified", evidence: [] },
+        { from: "mid/b.ts", to: "end/d.ts", kind: "import", typeOnly: false, status: "unchanged", evidence: [] },
+      ],
+      limits: { ...structure.limits, truncated: false, omitted: [] },
+    };
+    const first = await boot({ structureResponses: [dag] });
+    byId(first.document, "view-structure").click();
+    await flush();
+    byId(first.document, "structure-mode-graph").click();
+    const firstSvg = first.document.querySelector(".structure-graph-svg") as any;
+    const firstPaths = Array.from(firstSvg.querySelectorAll(".structure-graph-edge .structure-graph-line")).map((path: any) => path.getAttribute("d"));
+    expect(firstSvg.dataset.layout).toBeTruthy();
+    expect(firstPaths.every((path) => path?.startsWith("M") && path.includes("L") && !path.includes("Q"))).toBe(true);
+    expect(Array.from(first.document.querySelectorAll(".structure-graph-node")).map((node: any) => [node.dataset.path, node.dataset.layer])).toEqual([
+      ["a/z.ts", "0"],
+      ["z/a.ts", "0"],
+      ["mid/b.ts", "1"],
+      ["end/d.ts", "2"],
+    ]);
+
+    const second = await boot({ structureResponses: [dag] });
+    byId(second.document, "view-structure").click();
+    await flush();
+    byId(second.document, "structure-mode-graph").click();
+    const secondSvg = second.document.querySelector(".structure-graph-svg") as any;
+    expect(secondSvg.dataset.layout).toBe(firstSvg.dataset.layout);
+    expect(Array.from(secondSvg.querySelectorAll(".structure-graph-edge .structure-graph-line")).map((path: any) => path.getAttribute("d"))).toEqual(firstPaths);
+
+    const cycle = {
+      ...dag,
+      files: ["a.ts", "b.ts", "c.ts"].map((path) => ({ path, status: "modified", analyzed: true })),
+      edges: [
+        { from: "a.ts", to: "b.ts", kind: "import", typeOnly: false, status: "modified", evidence: [] },
+        { from: "b.ts", to: "c.ts", kind: "import", typeOnly: false, status: "modified", evidence: [] },
+        { from: "c.ts", to: "a.ts", kind: "import", typeOnly: false, status: "modified", evidence: [] },
+      ],
+    };
+    const cycled = await boot({ structureResponses: [cycle] });
+    byId(cycled.document, "view-structure").click();
+    await flush();
+    byId(cycled.document, "structure-mode-graph").click();
+    expect(Array.from(cycled.document.querySelectorAll(".structure-graph-node")).map((node: any) => [node.dataset.path, node.dataset.layer])).toEqual([
+      ["a.ts", "0"],
+      ["b.ts", "1"],
+      ["c.ts", "2"],
+    ]);
+  });
+
+  it("routes long edges below every intermediate layer without crossing node boxes", async () => {
+    const paths = ["src/a.ts", "src/b.ts", "src/c.ts"];
+    const longEdgeGraph = {
+      ...structure,
+      comparison: { ...structure.comparison, partial: false, reasons: [] },
+      files: paths.map((path) => ({ path, status: "modified", analyzed: true })),
+      edges: [
+        { from: paths[0], to: paths[1], kind: "import", typeOnly: false, status: "modified", evidence: [] },
+        { from: paths[1], to: paths[2], kind: "import", typeOnly: false, status: "modified", evidence: [] },
+        { from: paths[0], to: paths[2], kind: "import", typeOnly: false, status: "added", evidence: [] },
+      ],
+      limits: { ...structure.limits, truncated: false, omitted: [] },
+    };
+    const { document } = await boot({ structureResponses: [longEdgeGraph] });
+    byId(document, "view-structure").click();
+    await flush();
+    byId(document, "structure-mode-graph").click();
+
+    const middleRect = document.querySelector('.structure-graph-node[data-path="src/b.ts"] rect') as any;
+    const longPath = document.querySelector('.structure-graph-edge[data-from="src/a.ts"][data-to="src/c.ts"] path') as any;
+    expect(longPath).toBeTruthy();
+    expect(Math.max(...graphPathPoints(longPath).map((point) => point.y))).toBeGreaterThan(Number(middleRect.getAttribute("y")) + Number(middleRect.getAttribute("height")));
+    expectGraphPathsClearNodes(document);
+  });
+
+  it("routes back edges through layer gutters without crossing crowded endpoint layers", async () => {
+    const layer0 = ["a/0.ts", "a/1.ts", "a/2.ts"];
+    const layer1 = ["b/0.ts", "b/1.ts", "b/2.ts"];
+    const layer2 = ["c/0.ts", "c/1.ts", "c/2.ts"];
+    const paths = [...layer0, ...layer1, ...layer2];
+    const cycle = {
+      ...structure,
+      comparison: { ...structure.comparison, partial: false, reasons: [] },
+      files: paths.map((path) => ({ path, status: "modified", analyzed: true })),
+      edges: [
+        ...layer0.map((from, index) => ({ from, to: layer1[index], kind: "import", typeOnly: false, status: "modified", evidence: [] })),
+        ...layer1.map((from, index) => ({ from, to: layer2[index], kind: "import", typeOnly: false, status: "modified", evidence: [] })),
+        { from: layer2[1], to: layer0[1], kind: "import", typeOnly: false, status: "removed", evidence: [] },
+      ],
+      limits: { ...structure.limits, truncated: false, omitted: [] },
+    };
+    const { document } = await boot({ structureResponses: [cycle] });
+    byId(document, "view-structure").click();
+    await flush();
+    byId(document, "structure-mode-graph").click();
+
+    const svg = document.querySelector(".structure-graph-svg") as any;
+    const backPath = document.querySelector('.structure-graph-edge[data-from="c/1.ts"][data-to="a/1.ts"] .structure-graph-line') as any;
+    const points = graphPathPoints(backPath);
+    const sourceRect = document.querySelector('.structure-graph-node[data-path="c/1.ts"] rect') as any;
+    const targetRect = document.querySelector('.structure-graph-node[data-path="a/1.ts"] rect') as any;
+    expect(points[0]!.x).toBeCloseTo(Number(sourceRect.getAttribute("x")) + Number(sourceRect.getAttribute("width")));
+    expect(points.at(-1)?.x).toBeCloseTo(Number(targetRect.getAttribute("x")) + Number(targetRect.getAttribute("width")));
+    expect(Number(svg.getAttribute("viewBox").split(" ")[2])).toBeGreaterThan(Math.max(...points.map((point) => point.x)));
+    expectGraphPathsClearNodes(document);
+  });
+
+  it("routes back edges below the drawing and extends the SVG viewBox", async () => {
+    const paths = ["src/a.ts", "src/b.ts", "src/c.ts"];
+    const cycle = {
+      ...structure,
+      comparison: { ...structure.comparison, partial: false, reasons: [] },
+      files: paths.map((path) => ({ path, status: "modified", analyzed: true })),
+      edges: [
+        { from: paths[0], to: paths[1], kind: "import", typeOnly: false, status: "modified", evidence: [] },
+        { from: paths[1], to: paths[2], kind: "import", typeOnly: false, status: "modified", evidence: [] },
+        { from: paths[2], to: paths[0], kind: "import", typeOnly: false, status: "removed", evidence: [] },
+      ],
+      limits: { ...structure.limits, truncated: false, omitted: [] },
+    };
+    const { document } = await boot({ structureResponses: [cycle] });
+    byId(document, "view-structure").click();
+    await flush();
+    byId(document, "structure-mode-graph").click();
+
+    const svg = document.querySelector(".structure-graph-svg") as any;
+    const backPath = document.querySelector('.structure-graph-edge[data-from="src/c.ts"][data-to="src/a.ts"] .structure-graph-line') as any;
+    const drawingBottom = Math.max(...graphNodeRects(document).map((rect) => rect.y + rect.height));
+    const laneBottom = Math.max(...graphPathPoints(backPath).map((point) => point.y));
+    expect(laneBottom).toBeGreaterThan(drawingBottom);
+    expect(Number(svg.getAttribute("viewBox").split(" ")[3])).toBeGreaterThan(laneBottom);
+    expectGraphPathsClearNodes(document);
+  });
+
+  it("offsets parallel and shared back-edge ports deterministically", async () => {
+    const parallel = {
+      ...structure,
+      comparison: { ...structure.comparison, partial: false, reasons: [] },
+      files: ["a.ts", "b.ts"].map((path) => ({ path, status: "modified", analyzed: true })),
+      edges: ["dynamic-import", "import", "require"].map((kind) => ({ from: "a.ts", to: "b.ts", kind, typeOnly: false, status: "modified", evidence: [] })),
+      limits: { ...structure.limits, truncated: false, omitted: [] },
+    };
+    const parallelPage = await boot({ structureResponses: [parallel] });
+    byId(parallelPage.document, "view-structure").click();
+    await flush();
+    byId(parallelPage.document, "structure-mode-graph").click();
+    const parallelPaths = Array.from(parallelPage.document.querySelectorAll(".structure-graph-line"), (path: any) => path.getAttribute("d"));
+    expect(new Set(parallelPaths).size).toBe(3);
+
+    const sharedBack = {
+      ...structure,
+      comparison: { ...structure.comparison, partial: false, reasons: [] },
+      files: ["a.ts", "b.ts", "c.ts", "d.ts"].map((path) => ({ path, status: "modified", analyzed: true })),
+      edges: [
+        { from: "a.ts", to: "b.ts", kind: "import", typeOnly: false, status: "modified", evidence: [] },
+        { from: "b.ts", to: "c.ts", kind: "import", typeOnly: false, status: "modified", evidence: [] },
+        { from: "c.ts", to: "a.ts", kind: "import", typeOnly: false, status: "removed", evidence: [] },
+        { from: "c.ts", to: "a.ts", kind: "require", typeOnly: false, status: "removed", evidence: [] },
+      ],
+      limits: { ...structure.limits, truncated: false, omitted: [] },
+    };
+    const backPage = await boot({ structureResponses: [sharedBack] });
+    byId(backPage.document, "view-structure").click();
+    await flush();
+    byId(backPage.document, "structure-mode-graph").click();
+    const stems = Array.from(backPage.document.querySelectorAll('.structure-graph-edge[data-from="c.ts"][data-to="a.ts"] .structure-graph-line'), (path: any) => graphPathPoints(path)[0]!.y);
+    expect(new Set(stems).size).toBe(2);
+  });
+
+  it("enforces inclusive graph size bounds and the zero-drawable copy", async () => {
+    const inclusivePaths = Array.from({ length: 60 }, (_, index) => `src/i${String(index).padStart(2, "0")}.ts`);
+    const inclusive = {
+      ...structure,
+      files: inclusivePaths.map((path) => ({ path, status: "modified", analyzed: true })),
+      edges: Array.from({ length: 200 }, (_, index) => ({ from: inclusivePaths[index % 59], to: inclusivePaths[(index % 59) + 1], kind: "import", typeOnly: false, status: "modified", evidence: [] })),
+    };
+    const inclusivePage = await boot({ structureResponses: [inclusive] });
+    byId(inclusivePage.document, "view-structure").click();
+    await flush();
+    byId(inclusivePage.document, "structure-mode-graph").click();
+    expect(inclusivePage.document.querySelector(".structure-graph-svg")).not.toBeNull();
+
+    const nodePaths = Array.from({ length: 61 }, (_, index) => `src/n${String(index).padStart(2, "0")}.ts`);
+    const tooManyNodes = {
+      ...structure,
+      files: nodePaths.map((path) => ({ path, status: "modified", analyzed: true })),
+      edges: nodePaths.slice(1).map((path, index) => ({ from: nodePaths[index], to: path, kind: "import", typeOnly: false, status: "modified", evidence: [] })),
+    };
+    const nodePage = await boot({ structureResponses: [tooManyNodes] });
+    byId(nodePage.document, "view-structure").click();
+    await flush();
+    byId(nodePage.document, "structure-mode-graph").click();
+    expect(byId(nodePage.document, "structure-graph").textContent).toBe("Graph is too large for this view (61 files, 60 connections). Use the list.");
+    expect(nodePage.document.querySelector(".structure-graph-svg")).toBeNull();
+
+    const tooManyEdges = {
+      ...structure,
+      files: [
+        { path: "a.ts", status: "modified", analyzed: true },
+        { path: "b.ts", status: "modified", analyzed: true },
+      ],
+      edges: Array.from({ length: 201 }, () => ({ from: "a.ts", to: "b.ts", kind: "import", typeOnly: false, status: "modified", evidence: [] })),
+    };
+    const edgePage = await boot({ structureResponses: [tooManyEdges] });
+    byId(edgePage.document, "view-structure").click();
+    await flush();
+    byId(edgePage.document, "structure-mode-graph").click();
+    expect(byId(edgePage.document, "structure-graph").textContent).toBe("Graph is too large for this view (2 files, 201 connections). Use the list.");
+
+    const zero = await boot({ structureResponses: [{ ...structure, files: structure.files.map((file) => ({ ...file, analyzed: false })), edges: [] }] });
+    byId(zero.document, "view-structure").click();
+    await flush();
+    byId(zero.document, "structure-mode-graph").click();
+    expect(byId(zero.document, "structure-graph").textContent).toBe("No connections to draw.");
+  });
+
+  it("keeps graph selection exclusive, keyboard ordered, labelled, and Escape-restorable", async () => {
+    const { window, document } = await boot();
+    byId(document, "view-structure").click();
+    await flush();
+    byId(document, "structure-mode-graph").click();
+    const svg = document.querySelector(".structure-graph-svg") as any;
+    expect(svg.getAttribute("role")).toBe("group");
+    expect(svg.getAttribute("aria-label")).toBe("Structure graph, 4 files, 4 connections");
+    expect(Array.from(svg.querySelectorAll("defs marker")).map((marker: any) => marker.id)).toEqual([
+      "structure-arrow-added",
+      "structure-arrow-removed",
+      "structure-arrow-modified",
+      "structure-arrow-unchanged",
+      "structure-arrow-selected",
+    ]);
+    const controls = Array.from(svg.querySelectorAll('g[role="button"]')) as any[];
+    const nodes = controls.filter((control) => control.classList.contains("structure-graph-node"));
+    const edges = controls.filter((control) => control.classList.contains("structure-graph-edge"));
+    expect(controls.slice(0, nodes.length)).toEqual(nodes);
+    expect(edges.map((edge) => edge.getAttribute("aria-label"))).toEqual([
+      "src/a.ts → src/new.ts, re-export, edited",
+      "src/b.ts → src/a.ts, import, added",
+      "src/new.ts → src/a.ts, dynamic, unchanged",
+      "src/old.ts → src/a.ts, require, removed",
+    ]);
+    expect(nodes.map((node) => node.getAttribute("aria-label"))).toContain("src/a.ts, edited");
+    expect(nodes.every((node) => node.tabIndex === 0 && node.getAttribute("aria-label"))).toBe(true);
+    expect(svg.querySelector('.structure-graph-node[data-path="src/a.ts"] title')).toBeNull();
+    expect(edges.every((edge) => edge.tabIndex === 0)).toBe(true);
+    for (const edge of edges) {
+      const hit = edge.querySelector(".structure-graph-hit"), line = edge.querySelector(".structure-graph-line");
+      expect(hit).toBe(edge.firstElementChild);
+      expect(hit.getAttribute("d")).toBe(line.getAttribute("d"));
+      expect(hit.getAttribute("style")).toBe("fill:none;stroke:transparent;stroke-width:14;pointer-events:stroke");
+    }
+    expect(pageHtml).toContain(".structure-graph-edge.type-only {\nopacity:.7}");
+    expect(pageHtml).not.toContain("graph-focus-visible");
+    expect(pageHtml).not.toContain("graph-endpoint");
+    expect(pageHtml).not.toContain(".structure-mode-switch .view-tab");
+
+    const editedNode = svg.querySelector('.structure-graph-node[data-path="src/a.ts"]') as any;
+    editedNode.dispatchEvent(new window.KeyboardEvent("keydown", { key: "Enter", bubbles: true }));
+    expect(svg.querySelectorAll(".graph-selected")).toHaveLength(1);
+    expect(byId(document, "lifecycle").textContent).toBe("src/a.ts, edited selected.");
+    expect(Array.from(byId(document, "structure-graph-evidence").querySelectorAll(".connection-target"), (target: any) => target.textContent)).toEqual(["src/new.ts"]);
+    editedNode.dispatchEvent(new window.KeyboardEvent("keydown", { key: " ", bubbles: true, cancelable: true }));
+    expect(byId(document, "lifecycle").textContent).toBe("src/a.ts, edited selected.");
+    edges[0].dispatchEvent(new window.KeyboardEvent("keydown", { key: " ", bubbles: true, cancelable: true }));
+    expect(svg.querySelectorAll(".graph-selected")).toHaveLength(1);
+    expect(edges[0].classList.contains("graph-selected")).toBe(true);
+    expect(edges[0].querySelector(".structure-graph-line")?.getAttribute("marker-end")).toBe("url(#structure-arrow-selected)");
+    expect(svg.querySelectorAll(".graph-endpoint,.graph-focus-visible")).toHaveLength(0);
+    edges[0].focus();
+    edges[0].dispatchEvent(new window.KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+    expect(svg.querySelectorAll(".graph-selected,.graph-endpoint")).toHaveLength(0);
+    expect(edges[0].querySelector(".structure-graph-line")?.getAttribute("marker-end")).toBe("url(#structure-arrow-modified)");
+    expect(byId(document, "lifecycle").textContent).toBe("Selection cleared.");
+    expect(document.activeElement).toBe(byId(document, "structure-mode-graph"));
+  });
+
+  it("adds node titles only for ellipsised labels", async () => {
+    const longPath = "src/" + "deep/".repeat(8) + "file.ts";
+    const snapshot = {
+      ...structure,
+      files: [
+        { path: "short.ts", status: "modified", analyzed: true },
+        { path: longPath, status: "added", analyzed: true },
+      ],
+      edges: [{ from: "short.ts", to: longPath, kind: "import", typeOnly: false, status: "added", evidence: [] }],
+    };
+    const { document } = await boot({ structureResponses: [snapshot] });
+    byId(document, "view-structure").click();
+    await flush();
+    byId(document, "structure-mode-graph").click();
+    expect(document.querySelector('.structure-graph-node[data-path="short.ts"] title')).toBeNull();
+    expect(document.querySelector('.structure-graph-node[data-path="' + longPath + '"] title')?.textContent).toBe(longPath);
+  });
+
+  it("reuses graph evidence rendering and lands Open in Diff on the list's exact row", async () => {
+    const graphPage = await boot();
+    byId(graphPage.document, "view-structure").click();
+    await flush();
+    byId(graphPage.document, "structure-mode-graph").click();
+    const graphEdge = Array.from(graphPage.document.querySelectorAll(".structure-graph-edge") as any).find((edge: any) => edge.dataset.from === "src/b.ts" && edge.dataset.to === "src/a.ts") as any;
+    graphEdge.dispatchEvent(new graphPage.window.MouseEvent("click", { bubbles: true }));
+    const graphPanel = byId(graphPage.document, "structure-graph-evidence");
+    expect(graphPanel.previousElementSibling).toBe(byId(graphPage.document, "structure-graph"));
+    expect(graphPanel.parentElement).toBe(byId(graphPage.document, "structure-section"));
+    expect(graphPanel.querySelector(".connection-row")?.getAttribute("aria-expanded")).toBe("true");
+    expect(graphPanel.querySelector(".evidence-code")?.textContent).toContain("import type");
+    (graphPanel.querySelector(".open-in-diff") as any).click();
+    const graphLanding = graphPage.document.querySelector(".diff-row.structure-landing") as any;
+
+    const listPage = await boot();
+    byId(listPage.document, "view-structure").click();
+    await flush();
+    const listRow = Array.from(listPage.document.querySelectorAll(".connection-row") as any).find((row: any) => row.textContent.includes("src/a.ts") && row.textContent.includes("import")) as any;
+    listRow.click();
+    (listRow.nextElementSibling.querySelector(".open-in-diff") as any).click();
+    const listLanding = listPage.document.querySelector(".diff-row.structure-landing") as any;
+
+    expect([graphLanding.dataset.file, graphLanding.dataset.row]).toEqual([listLanding.dataset.file, listLanding.dataset.row]);
+    expect(graphPage.document.querySelectorAll(".diff-row.structure-landing")).toHaveLength(1);
+    byId(graphPage.document, "view-structure").click();
+    byId(graphPage.document, "structure-mode-list").click();
+    expect(graphPage.document.querySelector("#structure-graph-evidence")).toBeNull();
+  });
+
   it("fetches structure once per input and refetches the new payload after a source switch", async () => {
     const nextSource = { ...source, id: "input-2", digest: "digest-2", label: "Next tree" };
     const nextStructure = {