nebulosity 1.0.0 → 1.1.0

package/app/map/MapCanvas.tsx

@@ -2,50 +2,73 @@
 
 import { memo, useEffect, useMemo, useRef, useState } from "react";
 import {
-    Background, BackgroundVariant, ControlButton, Controls, MarkerType, ReactFlow, useEdgesState, useNodesState, useReactFlow, useStore, ViewportPortal,
+    ReactFlow, useEdgesState, useNodesState, useReactFlow, useStore, ViewportPortal,
     type EdgeMouseHandler, type EdgeTypes, type NodeMouseHandler, type NodeTypes,
 } from "@xyflow/react";
 import "@xyflow/react/dist/style.css";
-import { IconFocusCentered } from "@tabler/icons-react";
-import type { LevelResponse } from "@/lib/contracts";
+import type { LevelResponse, MapEdge } from "@/lib/contracts";
 import BoxActions from "./BoxActions";
-import { edgeKey, mapEmphasis, type EdgeTone } from "./emphasis";
+import { edgeKey, lineLook, mapEmphasis, type BoxTone, type LineDirection } from "./emphasis";
 import { reuseUnchanged, sameBoxNode, sameRoutedEdge, toBoxNode } from "./flowNodes";
-import { lineLabel } from "./labels";
-import Legend from "./Legend";
-import { FIT_PADDING, layoutLevel, looseDivider, perRowFor, type Divider } from "./levelLayout";
-import MapBox, { type BoxData, type BoxNode } from "./MapBox";
-import { legendMaxHeight } from "./narrow";
+import { formatCount } from "./format";
+import { runWords } from "./labels";
+import { BOX_HEIGHT, BOX_WIDTH, layoutLevel, looseDivider, perRowFor, type Divider, type Position } from "./levelLayout";
+import LineCard, { type CardAt, type CardPlace } from "./LineCard";
+import MapBox, { borderOf, shade, type BoxData, type BoxNode } from "./MapBox";
+import { openingOf } from "./opening";
 import { portalCaption, portalDirection, portalLinks, portalTitle } from "./portals";
 import type { Pulse } from "./pulses";
 import RoutedEdge, { type RoutedEdgeType } from "./RoutedEdge";
-import { routeEdges } from "./routes";
-import { boundsOf, initialViewport, TOP_INSET } from "./viewport";
+import { headRooms, nextRoutes, placeCounts, routeEdges, type Point, type Rect } from "./routes";
+import { linesSharing, pointedBits } from "./runs";
+import { isLightKind } from "./theme";
+import { useThemeKind } from "./useThemeKind";
+import { boundsOf, drawnLinesBounds, initialViewport } from "./viewport";
+import { arrowHead, boxHeadWidths, dotSize, labelledLines, lineWidth, maxFilesOf, maxImportsOf } from "./weights";
 
-// at module scope: a new object per render would make React Flow remount every box and line
-const nodeTypes: NodeTypes = { box: MapBox };
-const edgeTypes: EdgeTypes = { routed: RoutedEdge };
+/** The line ids a key of ids joined by newlines names. */
+const keySet = (key: string): Set<string> => new Set(key === "" ? [] : key.split("\n"));
+
+/**
+ * What a page's counts are placed by: its lines, each one's width and label size, and the boxes a count keeps off.
+ */
+type CountPage = { edges: readonly MapEdge[]; widths: Map<string, number>; sizes: Map<string, { width: number; height: number }>; boxes: Rect[] };
 
 /**
- * The fit button's fit: the whole level with room around it, never past 100% (VISUAL_REFRESH.md §4). A level opens by
- * viewport.ts's rule instead, which fits the same way unless that would make it unreadable.
+ * Where the counts of `labelled` go among the lines of `routes` that are `drawn`, from the places `kept` gives them
+ * (placeCounts), clear of the boxes and of the arrowheads those lines draw (headRooms).
  */
-const FIT = { padding: FIT_PADDING, maxZoom: 1 } as const;
+function countsOn(page: CountPage, routes: ReadonlyMap<string, Point[]>, drawn: ReadonlySet<string>, labelled: ReadonlySet<string>, kept: ReadonlyMap<string, Point>): Map<string, Point> {
+    const on = new Map([...routes].filter(([id]) => drawn.has(id)));
+    const labels = new Map([...on.keys()].filter((id) => labelled.has(id)).map((id) => [id, page.sizes.get(id)!]));
+    return placeCounts(on, page.widths, labels, [...page.boxes, ...headRooms(on, page.edges)], kept);
+}
 
 /**
- * Each line's look per tone (VISUAL_REFRESH.md §4): 1 px slate normally, 2 px purple for the selection's links. The
- * arrowhead of a quiet line is brighter than the line itself, so the direction reads without the line getting louder
- * (owner review: the arrows were too small to see).
+ * What's on screen, and what it was worked out from: the rest routes, the lines drawn and their routes, and the counts.
+ * `settled` is the lines drawn without the hover, `restCounts` rest's counts and `settledCounts` the counts without
+ * the hover (the selection's, from rest's), which a hover's `counts` start from.
  */
-const EDGE_STYLES: Record<Exclude<EdgeTone, "hidden">, { stroke: string; arrow: string; width: number; opacity: number; layer: number }> = {
-    normal: { stroke: "var(--neutral-edge)", arrow: "var(--text-2)", width: 1, opacity: 1, layer: 0 },
-    faded: { stroke: "var(--neutral-edge)", arrow: "var(--neutral-edge)", width: 1, opacity: 0.35, layer: 0 },
-    preview: { stroke: "var(--text-2)", arrow: "var(--text)", width: 1.5, opacity: 1, layer: 1 },
-    // 1.5 px, not 2: a selected box's lines merge into shared tracks, and at 2 px they outshone the box itself
-    selected: { stroke: "var(--select)", arrow: "var(--select)", width: 1.5, opacity: 1, layer: 2 },
+type Shown = {
+    rest: Map<string, Point[]>;
+    drawn: string;
+    routes: Map<string, Point[]>;
+    selected: string | null;
+    settled: string;
+    restCounts: Map<string, Point>;
+    settledCounts: Map<string, Point>;
+    counts: Map<string, Point>;
 };
-/** The arrowhead's size in px, whatever the line's width (26 since the three-task test: 18 was too small to read). */
-const ARROW_SIZE = 26;
+
+/**
+ * The lines under the pointer (runs.ts's linesSharing), by `key`, their ids joined by newlines, and where the pointer
+ * is on their run, with the bit of line there and what's over the canvas then, which the hover card keeps off.
+ */
+type LineHover = { key: string; lines: string[] } & CardAt;
+
+// at module scope: a new object per render would make React Flow remount every box and line
+const nodeTypes: NodeTypes = { box: MapBox };
+const edgeTypes: EdgeTypes = { routed: RoutedEdge };
 
 type MapCanvasProps = {
     level: LevelResponse;
@@ -61,70 +84,142 @@ type MapCanvasProps = {
     onDrawn: () => void;
     /** A busy level: only the hovered or selected box's lines are drawn (emphasis.ts). */
     quietLines: boolean;
-    /** The open panel's width over the canvas's right edge, 0 with none (narrow.ts's panelLayout). */
-    panelWidth: number;
+    /** Strong links only: a weak line is drawn only when it touches the selection, the hovered box or a lit box (emphasis.ts). */
+    strongOnly: boolean;
     /**
-     * The panel covers the whole canvas (a narrow window): the legend and the zoom controls would sit under it, and the
-     * boxes can't be reached by Tab either, until its × brings the canvas back.
+     * Which side of the selection's lines is highlighted, the other drawn gray (emphasis.ts). It changes no line drawn,
+     * so no route and no count moves, only colors.
+     */
+    direction: LineDirection;
+    /**
+     * The inspector covers the whole canvas (a window both narrow and short, shell.ts): the boxes can't be reached by Tab
+     * then, until its × brings the canvas back.
      */
     covered: boolean;
-    /** How far down the Map's error banner reaches on the canvas, 0 with none: the open legend stops short of it. */
-    bannerBottom: number;
     /**
      * The selected box that shows its actions beside it (BoxActions), or null: while the panel would cover the canvas,
      * a click only selects, and Details asks for the panel.
      */
     actionsFor: string | null;
     onDetails: (path: string) => void;
+    /** Inside VS Code's panel only: a file box double-clicked, or its Open beside it, opens it in the editor. */
+    onOpenFile?: (path: string) => void;
 };
 
 /**
  * The canvas (VISUAL_REFRESH.md §4): one level's boxes, laid out by dagre, and an arrow for every import line, routed
  * around the boxes (routes.ts). A click selects (where the panel would cover the canvas, the selected box shows its
- * actions beside it: BoxActions); a double click opens a folder, or turns to a portal's page. The selection's lines turn purple and unrelated boxes fade;
- * hovering a box previews its lines without selecting it, and hovering a line shows its count. React Flow stays
- * controlled with the StrictMode workaround in next.config.ts.
+ * actions beside it: BoxActions); a double click opens a folder, turns to a portal's page, or inside VS Code's panel opens a
+ * file in the editor (opening.ts). The selection's lines turn purple (what it uses) and gold (what uses it), and unrelated boxes fade;
+ * hovering a box previews its lines without selecting it, and hovering a line names every line on that run beside the
+ * pointer, a click on it keeping the list (LineCard). React Flow stays controlled with the StrictMode workaround in
+ * next.config.ts.
  */
-function MapCanvas({ level, selected, agent, pulses, onSelect, onOpen, onTurnPage, onDrawn, quietLines, panelWidth, covered, bannerBottom, actionsFor, onDetails }: MapCanvasProps){
+function MapCanvas({ level, selected, agent, pulses, onSelect, onOpen, onTurnPage, onDrawn, quietLines, strongOnly, direction, covered, actionsFor, onDetails, onOpenFile }: MapCanvasProps){
     // a wide canvas wraps layers at 8 a row instead of 6, so dense levels fit larger (levelLayout.ts)
     const perRow = useStore((s) => perRowFor(s.width));
+    // React Flow's own parts follow a light VS Code theme (theme.ts)
+    const themeKind = useThemeKind();
     const positions = useMemo(() => layoutLevel(level.nodes, level.edges, undefined, perRow), [level, perRow]);
     const divider = useMemo(() => looseDivider(level.nodes, level.edges, positions), [level, positions]);
     const byPath = useMemo(() => new Map(level.nodes.map((n) => [n.path, n])), [level]);
-    // each portal's arrow, "Lines to page 2" and "44 folders and files · 6 imports", worked out once per level, not on every hover
+    // each portal's arrow, "Lines to page 2" and "44 folders and files, 6 imports", worked out once per level, not on every hover
     const portals = useMemo(() => new Map<string, BoxData["portal"]>(level.nodes.filter((n) => n.kind === "portal").map((n) => [
         n.path,
         { direction: portalDirection(n, level.page), title: portalTitle(n), caption: portalCaption(n, portalLinks(level.edges, n.path)) },
     ])), [level]);
-    const routes = useMemo(() => routeEdges(positions, level.edges), [positions, level]);
-    const [hoveredEdge, setHoveredEdge] = useState<string | null>(null);
+    // dots and lines are scaled against the page's largest folder and heaviest line (weights.ts)
+    const maxFiles = useMemo(() => maxFilesOf(level.nodes), [level]);
+    const maxImports = useMemo(() => maxImportsOf(level.edges), [level]);
+    // each box's one head, sized from every line on the level, drawn or not, as routing sized the room above it
+    const heads = useMemo(() => boxHeadWidths(level.edges), [level]);
+    const labelled = useMemo(() => labelledLines(level.edges, selected), [level, selected]);
+    const [lineHover, setLineHover] = useState<LineHover | null>(null);
+    // the hover card a click on a run pinned, every line listed (LineCard)
+    const [pinned, setPinned] = useState<(LineHover & { held: CardPlace | null }) | null>(null);
     const [hoveredBox, setHoveredBox] = useState<string | null>(null);
     // A hover belongs to the level it happened on. Going into a folder unmounts the old boxes before their mouseleave
     // fires, so the hover outlived the level, and coming back (a cached level, the same object as before) lit that box
     // up with nothing under the pointer (deferred minor). So it's cleared whenever another level is drawn: React's way
     // to reset state when a prop changes, during render rather than in an effect, so no frame shows the stale hover.
+    // A pinned card goes with it.
     const [drawnLevel, setDrawnLevel] = useState(level);
-    if (drawnLevel !== level){
+    const levelChanged = drawnLevel !== level;
+    if (levelChanged){
         setDrawnLevel(level);
         setHoveredBox(null);
-        setHoveredEdge(null);
+        setLineHover(null);
+        setPinned(null);
     }
     const emphasis = useMemo(
-        () => mapEmphasis(level.nodes.map((n) => n.path), level.edges, selected, hoveredBox, { quietLines }),
-        [level, selected, hoveredBox, quietLines],
+        // the boxes Claude Code or the editor has lit keep their lines, whatever hides the rest
+        () => mapEmphasis(level.nodes.map((n) => n.path), level.edges, selected, hoveredBox, { quietLines, strongOnly, pinned: agent, direction }),
+        [level, selected, hoveredBox, quietLines, strongOnly, agent, direction],
     );
+    // The lines drawn at rest (nothing selected, hovered or lit) are routed once, among themselves (routes.ts). A line a
+    // selection, a hover or a lit box adds is routed when it appears: it takes its boxes' points (a box has one a side)
+    // and, where it fits, the lanes and tracks their drawn lines are on, and goes around every other line on screen. It
+    // keeps that route while it stays, so pointing at a box or clicking one never moves a line that's drawn (the owner,
+    // 2026-10-27). Keyed by content: a hover that draws the same lines keeps every route.
+    const restKey = useMemo(() => {
+        const rest = mapEmphasis(level.nodes.map((n) => n.path), level.edges, null, null, { quietLines, strongOnly });
+        return level.edges.map(edgeKey).filter((id) => rest.edges.get(id) !== "hidden").join("\n");
+    }, [level, quietLines, strongOnly]);
+    const restRoutes = useMemo(() => routeEdges(positions, level.edges, keySet(restKey)), [positions, level, restKey]);
+    const drawnKey = level.edges.map(edgeKey).filter((id) => emphasis.edges.get(id) !== "hidden").join("\n");
+    // the lines drawn without the hover: rest's, and the selection's and the lit boxes' on top
+    const settledKey = useMemo(() => {
+        const settled = mapEmphasis(level.nodes.map((n) => n.path), level.edges, selected, null, { quietLines, strongOnly, pinned: agent });
+        return level.edges.map(edgeKey).filter((id) => settled.edges.get(id) !== "hidden").join("\n");
+    }, [level, selected, quietLines, strongOnly, agent]);
+    // what a count keeps clear of: every other line by its width, every other count, its label sized from its count's
+    // text as RoutedEdge writes it (7 px a character and 14 of padding and border, by 18), every box with its back card,
+    // and every arrowhead drawn (countsOn)
+    const countPage = useMemo((): CountPage => ({
+        edges: level.edges,
+        widths: new Map(level.edges.map((e) => [edgeKey(e), lineWidth(e.count, maxImports)])),
+        sizes: new Map(level.edges.map((e) => [edgeKey(e), { width: formatCount(e.count).length * 7 + 14, height: 18 }])),
+        boxes: level.nodes.flatMap((box) => {
+            const at = positions.get(box.path);
+            return at === undefined ? [] : [{ x: at.x + (BOX_WIDTH + 5) / 2, y: at.y + (BOX_HEIGHT + 5) / 2, width: BOX_WIDTH + 5, height: BOX_HEIGHT + 5 }];
+        }),
+    }), [level, positions, maxImports]);
+    // What's on screen, and what it was worked out from: React's way to keep state that follows a prop, set during render.
+    // A count is placed from a base, so lines that appear move only the counts they run into (placeCounts): rest's are
+    // placed afresh, the screen without a hover (a selection, or a lit box) starts from rest's, and a hover from the
+    // screen without it. Rest's and the selection's are held beside the routes, so a count a hovered line pushed aside
+    // goes back when the hover ends, and nothing chains from one hover to the next. New rest routes (another level, or
+    // Strong links only or Show all lines turned) start the counts afresh with them.
+    const follow = (previous: Shown | null): Shown => {
+        const fresh = previous === null || previous.rest !== restRoutes;
+        // the same lines keep the routes they have, rest's lines included, which nextRoutes would give back as they are
+        const before = fresh ? restRoutes : previous.routes;
+        const routes = drawnKey === (fresh ? restKey : previous.drawn) ? before : nextRoutes(positions, level.edges, restRoutes, before, keySet(drawnKey));
+        const restCounts = fresh ? countsOn(countPage, restRoutes, keySet(restKey), labelledLines(level.edges, null), new Map()) : previous.restCounts;
+        // a hover draws more lines and never hides one, so the lines without it are on screen, where they'll stay
+        const settledCounts = !fresh && previous.selected === selected && previous.settled === settledKey
+            ? previous.settledCounts
+            : countsOn(countPage, routes, keySet(settledKey), labelled, restCounts);
+        const counts = drawnKey === settledKey ? settledCounts : countsOn(countPage, routes, keySet(drawnKey), labelled, settledCounts);
+        return { rest: restRoutes, drawn: drawnKey, routes, selected, settled: settledKey, restCounts, settledCounts, counts };
+    };
+    const [shown, setShown] = useState(() => follow(null));
+    if (shown.rest !== restRoutes || shown.drawn !== drawnKey || shown.selected !== selected || shown.settled !== settledKey) setShown(follow(shown));
+    const { routes, counts } = shown;
     const [nodes, setNodes, onNodesChange] = useNodesState<BoxNode>([]);
     const [edges, setEdges, onEdgesChange] = useEdgesState<RoutedEdgeType>([]);
-    const { setViewport } = useReactFlow();
+    const { setViewport, getViewport, screenToFlowPosition } = useReactFlow();
     const canvasWidth = useStore((s) => s.width);
     const canvasHeight = useStore((s) => s.height);
-    // a paged level keeps clear of the page pill at the canvas's top right (viewport.ts)
-    const pillBand = level.pageCount > 1 ? TOP_INSET : 0;
-    // the latest of each, for the opening view below: it runs when the level changes, not when they do
-    const openRef = useRef({ setViewport, onDrawn, positions, canvas: { width: canvasWidth, height: canvasHeight }, pillBand });
+    const canvas = useStore((s) => s.domNode);
+    // the latest of each, for the opening view below: it runs when the level changes, not when they do. The lines on
+    // screen are framed with the boxes (viewport.ts), measured only when a level opens or refits, not on every hover
+    const openRef = useRef({ setViewport, onDrawn, positions, routes, edges: level.edges, canvas: { width: canvasWidth, height: canvasHeight } });
     useEffect(() => {
-        openRef.current = { setViewport, onDrawn, positions, canvas: { width: canvasWidth, height: canvasHeight }, pillBand };
-    }, [setViewport, onDrawn, positions, canvasWidth, canvasHeight, pillBand]);
+        openRef.current = { setViewport, onDrawn, positions, routes, edges: level.edges, canvas: { width: canvasWidth, height: canvasHeight } };
+    }, [setViewport, onDrawn, positions, routes, level.edges, canvasWidth, canvasHeight]);
+    // whether the person has panned or zoomed since the level opened (a programmatic move has no event)
+    const moved = useRef(false);
 
     useEffect(() => {
         // with their size and attach points given, the lines never wait for React Flow to measure (flowNodes.ts); a box
@@ -134,10 +229,11 @@ function MapCanvas({ level, selected, agent, pulses, onSelect, onOpen, onTurnPag
             tone: emphasis.boxes.get(box.path) ?? "normal",
             agent: agent.has(box.path),
             pulseKey: pulses.get(box.path)?.key ?? 0,
+            dot: dotSize(box.fileCount, maxFiles),
             portal: portals.get(box.path),
         }));
         setNodes((previous) => reuseUnchanged(previous, next, sameBoxNode));
-    }, [level, positions, portals, emphasis, agent, pulses, setNodes]);
+    }, [level, positions, portals, emphasis, agent, pulses, maxFiles, setNodes]);
 
     useEffect(() => {
         // a busy level's hidden lines aren't handed to React Flow at all: fewer lines to draw, and none to hover
@@ -145,31 +241,38 @@ function MapCanvas({ level, selected, agent, pulses, onSelect, onOpen, onTurnPag
             const id = edgeKey(edge);
             const tone = emphasis.edges.get(id) ?? "normal";
             if (tone === "hidden") return [];
-            const look = EDGE_STYLES[tone];
+            const look = lineLook(tone, edge, selected);
             const drawnEdge: RoutedEdgeType = {
                 id,
                 type: "routed",
-                data: { points: routes.get(id) ?? [] },
+                data: {
+                    points: routes.get(id) ?? [],
+                    width: lineWidth(edge.count, maxImports),
+                    headWidth: heads.get(edge.target),
+                    color: look.color,
+                    // the page's heaviest lines and the selection's carry their count where it has a place clear of
+                    // everything else, the selection's in the text color
+                    count: counts.has(id) ? formatCount(edge.count) : undefined,
+                    countStrong: tone === "selected",
+                    labelAt: counts.get(id),
+                },
                 source: edge.source,
                 target: edge.target,
                 focusable: false,
-                // in words ("editor uses base · 12 imports"): the three-task test's tester read an arrow backwards
-                label: hoveredEdge === id ? lineLabel(byPath.get(edge.source)!, byPath.get(edge.target)!, edge.count) : undefined,
-                style: { stroke: look.stroke, strokeWidth: look.width, opacity: look.opacity },
-                // userSpaceOnUse: the arrowhead stays the same size whatever the line's width
-                markerEnd: { type: MarkerType.ArrowClosed, width: ARROW_SIZE, height: ARROW_SIZE, color: look.arrow, markerUnits: "userSpaceOnUse" },
             };
             return [{ layer: look.layer, edge: drawnEdge }];
         });
-        // the emphasized lines go last, so they're drawn over the quiet ones they cross. Order, not zIndex: React Flow
-        // lifts an edge with a zIndex above every box, where it would take the box's clicks (final review I2)
+        // the emphasized lines go last, so they're drawn over the quiet ones they cross or share a run with. Order, not
+        // zIndex: React Flow lifts an edge with a zIndex above every box, where it would take the box's clicks (final
+        // review I2)
         const next = drawn.sort((a, b) => a.layer - b.layer).map((d) => d.edge);
         setEdges((previous) => reuseUnchanged(previous, next, sameRoutedEdge));
-    }, [level, byPath, routes, emphasis, hoveredEdge, setEdges]);
+    }, [level, routes, counts, emphasis, selected, maxImports, heads, setEdges]);
 
-    // A new level (another folder, or another repo): open it at a readable size (viewport.ts: fitted, unless that would
-    // shrink it past 75%, then from its top), then report it drawn. The boxes reach React Flow a render after the level
-    // does (setNodes runs in an effect), so this waits until `nodes` holds this level's boxes: placing the view sooner
+    // A new level (another folder, or another repo): open it at a readable size (viewport.ts: fitted, its drawn lines
+    // too unless that would shrink the boxes under 85% of their own fit or past 75%, and from its top when the boxes
+    // alone would shrink past 75%), then report it drawn. The boxes reach React Flow a render after the level does
+    // (setNodes runs in an effect), so this waits until `nodes` holds this level's boxes: placing the view sooner
     // frames the previous level's, which is what a level from the cache got. The same level refetched after the index
     // moved keeps its key, so the user's pan and zoom stay put.
     // the row width is in the key: a window resized across WIDE_CANVAS lays the level out again, so it's fitted again
@@ -181,30 +284,122 @@ function MapCanvas({ level, selected, agent, pulses, onSelect, onOpen, onTurnPag
         if (!arrived) return;
         const frame = requestAnimationFrame(() => {
             fittedKey.current = levelKey;
+            moved.current = false;
             const open = openRef.current;
-            void open.setViewport(initialViewport(boundsOf(open.positions), open.canvas, open.pillBand), { duration: 0 });
+            void open.setViewport(initialViewport(boundsOf(open.positions), open.canvas, 0, drawnLinesBounds(open.routes, open.edges)), { duration: 0 });
             open.onDrawn();
         });
         return () => cancelAnimationFrame(frame);
     }, [levelKey, nodes, level.nodes]);
 
+    // The canvas resized (the window or VS Code's panel dragged, the inspector moving under or beside it): a level nobody
+    // has moved since it opened opens again for the new size, and one the person has moved keeps its middle where it
+    // was, at the same zoom, so the view stays steady and the selection stays in sight (the owner, 2026-10-27).
+    const lastSize = useRef<{ width: number; height: number } | null>(null);
+    useEffect(() => {
+        const last = lastSize.current;
+        lastSize.current = { width: canvasWidth, height: canvasHeight };
+        if (last === null || canvasWidth === 0 || canvasHeight === 0 || fittedKey.current !== levelKey) return;
+        if (last.width === canvasWidth && last.height === canvasHeight) return;
+        // the lines move under the hover card and a pinned one, which were placed for the old view
+        setLineHover(null);
+        setPinned(null);
+        if (!moved.current){
+            const lines = drawnLinesBounds(openRef.current.routes, openRef.current.edges);
+            void setViewport(initialViewport(boundsOf(positions), { width: canvasWidth, height: canvasHeight }, 0, lines), { duration: 0 });
+        } else {
+            const view = getViewport();
+            void setViewport({ x: view.x + (canvasWidth - last.width) / 2, y: view.y + (canvasHeight - last.height) / 2, zoom: view.zoom }, { duration: 0 });
+        }
+    }, [canvasWidth, canvasHeight, levelKey, positions, setViewport, getViewport]);
+
     const onNodeClick: NodeMouseHandler<BoxNode> = (_, node) => onSelect(node.id);
     const onNodeDoubleClick: NodeMouseHandler<BoxNode> = (_, node) => {
-        const { box } = node.data;
-        if (box.kind === "folder") onOpen(node.id);
-        // a portal turns to its page; the merged one stands for several, so it stays selected for its panel to pick one
-        else if (box.kind === "portal" && box.page !== undefined) onTurnPage(box.page);
+        const opening = openingOf(node.data.box, onOpenFile !== undefined);
+        if (opening?.type === "folder") onOpen(opening.path);
+        else if (opening?.type === "page") onTurnPage(opening.page);
+        else if (opening?.type === "editor") onOpenFile?.(opening.path);
     };
     const onNodeMouseEnter: NodeMouseHandler<BoxNode> = (_, node) => setHoveredBox(node.id);
     const onNodeMouseLeave: NodeMouseHandler<BoxNode> = () => setHoveredBox(null);
-    const onEdgeMouseEnter: EdgeMouseHandler = (_, edge) => setHoveredEdge(edge.id);
-    const onEdgeMouseLeave: EdgeMouseHandler = () => setHoveredEdge(null);
-    /** Reset focus (§4): let go of the selection and the fade it brings. */
-    const resetFocus = (): void => {
-        setHoveredBox(null);
-        onSelect(null);
+
+    // The lines under the pointer (the owner, 2026-10-29): every line on the run it's on (runs.ts), named by the hover
+    // card at the pointer (LineCard). Another run is another card, and along the same run the card is handed the pointer
+    // itself (followRef), so it goes with the pointer without drawing the canvas again.
+    const drawnLines = useMemo(() => keySet(drawnKey), [drawnKey]);
+    const edgeById = useMemo(() => new Map(level.edges.map((e) => [edgeKey(e), e])), [level]);
+    const followCard = useRef<((at: CardAt) => void) | null>(null);
+    const hoverPlace = useRef<CardPlace | null>(null);
+    const hoverAt = (event: { clientX: number; clientY: number }, id: string): LineHover | null => {
+        const route = routes.get(id);
+        const found = linesSharing(id, screenToFlowPosition({ x: event.clientX, y: event.clientY }), routes, drawnLines);
+        const edge = edgeById.get(id);
+        if (found === null || canvas === null || edge === undefined || route === undefined) return null;
+        // the card points at the spot on the line nearest the pointer, across the line there (LineCard)
+        const box = canvas.getBoundingClientRect();
+        const view = getViewport();
+        const spot = found.point;
+        const point = { x: spot.x * view.zoom + view.x, y: spot.y * view.zoom + view.y };
+        const a = route[found.segment], b = route[found.segment + 1];
+        const width = lineWidth(edge.count, maxImports);
+        const line = pointedBits(route, point, view, width, arrowHead(heads.get(edge.target) ?? width));
+        // what's over the canvas says so (a drawer, a box's actions, the banner: MapView, BoxActions)
+        const clear = [...(canvas.parentElement ?? canvas).querySelectorAll("[data-keep-clear]")].map((el) => {
+            const r = el.getBoundingClientRect();
+            return { left: r.left - box.left, top: r.top - box.top, width: r.width, height: r.height };
+        });
+        const upright = Math.abs(b.y - a.y) > Math.abs(b.x - a.x);
+        return { key: found.lines.join("\n"), lines: found.lines, point, spot, upright, half: (width * view.zoom) / 2, line, clear };
+    };
+    const onEdgeMouseMove: EdgeMouseHandler = (event, edge) => {
+        const next = hoverAt(event, edge.id);
+        if (next === null) return;
+        if (lineHover !== null && lineHover.key === next.key) followCard.current?.(next);
+        else setLineHover(next);
+    };
+    const onEdgeMouseLeave: EdgeMouseHandler = () => setLineHover(null);
+    // a click on the run pins its hover card just as it is, to list every line (LineCard)
+    const onEdgeClick: EdgeMouseHandler = (event, edge) => {
+        const next = hoverAt(event, edge.id);
+        if (next !== null) setPinned({ ...next, held: lineHover !== null && lineHover.key === next.key ? hoverPlace.current : null });
     };
 
+    // A pinned card closes on Escape, a click anywhere outside it (a drag of the canvas among them), another page
+    // (above), or a resize of the canvas. A zoom with the wheel keeps it (LineCard).
+    // Escape is caught first, on the way down, and stopped there, so it doesn't also let go of the selection (Explorer's
+    // rail does the same). A click on the empty canvas that closes it does only that, as Escape does, rather than letting
+    // go of the selection too: the click after that pointerdown is stopped before the pane sees it.
+    const pinnedCard = useRef<HTMLDivElement>(null);
+    useEffect(() => {
+        if (pinned === null) return;
+        const onKey = (event: KeyboardEvent): void => {
+            if (event.key !== "Escape") return;
+            event.stopPropagation();
+            setPinned(null);
+        };
+        const onPointer = (event: PointerEvent): void => {
+            if (event.target instanceof Node && pinnedCard.current?.contains(event.target)) return;
+            setPinned(null);
+            if (!(event.target instanceof Element && event.target.closest(".react-flow__pane"))) return;
+            const stop = (click: MouseEvent): void => {
+                if (click.target instanceof Element && click.target.closest(".react-flow__pane")) click.stopPropagation();
+            };
+            document.addEventListener("click", stop, { capture: true, once: true });
+            // a drag that pans has no click: the next press takes the stopper away before its own click comes
+            document.addEventListener("pointerdown", () => document.removeEventListener("click", stop, { capture: true }), { capture: true, once: true });
+        };
+        window.addEventListener("keydown", onKey, true);
+        document.addEventListener("pointerdown", onPointer, true);
+        return () => {
+            window.removeEventListener("keydown", onKey, true);
+            document.removeEventListener("pointerdown", onPointer, true);
+        };
+    }, [pinned]);
+    // React runs the rest of the render that clears the cards (above) with them still set, so on a jump with a card
+    // open (the editor following a file, Claude Code's show_on_map, Back) it named the old level's lines from the new
+    // one, which hasn't got them, and threw. That render draws no card.
+    const card = levelChanged ? null : pinned ?? lineHover;
+
     return (
         <ReactFlow
             nodes={nodes}
@@ -218,24 +413,32 @@ function MapCanvas({ level, selected, agent, pulses, onSelect, onOpen, onTurnPag
             onNodeMouseEnter={onNodeMouseEnter}
             onNodeMouseLeave={onNodeMouseLeave}
             onPaneClick={() => onSelect(null)}
-            onEdgeMouseEnter={onEdgeMouseEnter}
+            onMoveStart={(event) => {
+                if (event === null) return;
+                moved.current = true;
+                // the lines move under the hover card, placed for where they were. A pinned card stays, beside the spot
+                // it was clicked at as the wheel zooms (LineCard), and a drag starts with a press outside it, which
+                // closes it (above)
+                setLineHover(null);
+            }}
+            onEdgeMouseEnter={onEdgeMouseMove}
+            onEdgeMouseMove={onEdgeMouseMove}
             onEdgeMouseLeave={onEdgeMouseLeave}
+            onEdgeClick={onEdgeClick}
             nodesDraggable={false}
             nodesConnectable={false}
             zoomOnDoubleClick={false}
             minZoom={0.1}
             maxZoom={2}
-            colorMode="dark"
+            colorMode={isLightKind(themeKind) ? "light" : "dark"}
             proOptions={{ hideAttribution: true }}
             inert={covered}
         >
-            {/* a faint dot grid: texture, so a busy level isn't a void with rectangles in it (VISUAL_REFRESH.md §3) */}
-            <Background variant={BackgroundVariant.Dots} gap={22} size={1.2} color="var(--grid)" />
-            {divider && (
-                <ViewportPortal>
-                    <LooseDivider divider={divider} />
-                </ViewportPortal>
-            )}
+            {/* under the lines (globals.css puts this layer beneath them): the folders' back cards, and the divider */}
+            <ViewportPortal>
+                <BackCards nodes={level.nodes} positions={positions} tones={emphasis.boxes} />
+                {divider && <LooseDivider divider={divider} />}
+            </ViewportPortal>
             {actionsFor !== null && byPath.has(actionsFor) && positions.has(actionsFor) && (
                 <BoxActions
                     box={byPath.get(actionsFor)!}
@@ -243,40 +446,66 @@ function MapCanvas({ level, selected, agent, pulses, onSelect, onOpen, onTurnPag
                     onOpen={onOpen}
                     onTurnPage={onTurnPage}
                     onDetails={onDetails}
+                    onOpenFile={onOpenFile}
                 />
             )}
-            {/* a panel over the whole canvas hides what's under it; its × brings the canvas back */}
-            {!covered && (
-                <Legend
-                    quietLines={quietLines}
-                    doorways={level.nodes.some((n) => n.kind === "portal")}
-                    // a short canvas: the open legend stays below a paged level's pill and the error banner, and
-                    // scrolls inside if it must (narrow.ts)
-                    maxHeight={legendMaxHeight(canvasHeight, pillBand, bannerBottom)}
+            {card !== null && (
+                <LineCard
+                    // a hover card is one a run, and a pinned one is one a click
+                    key={pinned === null ? `hover\n${card.key}` : `pinned\n${card.key}\n${card.point.x},${card.point.y}`}
+                    words={runWords(card.lines.map((id) => edgeById.get(id)!), byPath)}
+                    at={card}
+                    pinned={pinned !== null}
+                    cardRef={pinned === null ? undefined : pinnedCard}
+                    held={pinned?.held}
+                    followRef={pinned === null ? followCard : undefined}
+                    placedRef={pinned === null ? hoverPlace : undefined}
                 />
             )}
-            {/* while the panel is open it covers the canvas's right edge, so the controls move left of it (final review I1) */}
-            {!covered && (
-                <Controls
-                    position="bottom-right"
-                    showInteractive={false}
-                    fitViewOptions={FIT}
-                    style={panelWidth > 0 ? { right: panelWidth } : undefined}
-                    className="overflow-hidden rounded-lg"
-                >
-                    <ControlButton onClick={resetFocus} title="Reset focus" aria-label="Reset focus">
-                        <IconFocusCentered aria-hidden size={16} stroke={1.75} />
-                    </ControlButton>
-                </Controls>
-            )}
         </ReactFlow>
     );
 }
 
+/** A back card's color: 70% of the way from the background to its front card's, so it reads as the card behind. */
+const behind = (color: string): string => `color-mix(in srgb, ${color} 70%, var(--canvas))`;
+
+/**
+ * Every folder's back card, a second card 5 px behind it (the owner's pick of 2026-10-27, compare-files.png option C):
+ * a folder opens into more boxes, and a file has none. Opaque, its fill and border 70% of the way from the background
+ * to its own card's, faded with its card, and drawn under the lines, so a line leaving a box's bottom edge stays whole.
+ */
+function BackCards({ nodes, positions, tones }: {
+    nodes: LevelResponse["nodes"];
+    positions: ReadonlyMap<string, Position>;
+    tones: ReadonlyMap<string, BoxTone>;
+}){
+    return (
+        <div aria-hidden data-testid="back-cards" className="pointer-events-none">
+            {nodes.filter((n) => n.kind === "folder").map((n) => {
+                const at = positions.get(n.path);
+                if (at === undefined) return null;
+                const tone = tones.get(n.path) ?? "normal";
+                const faded = tone === "faded";
+                return (
+                    <div
+                        key={n.path}
+                        data-back-card={n.path}
+                        style={{
+                            position: "absolute", left: at.x + 5, top: at.y + 5, width: BOX_WIDTH, height: BOX_HEIGHT, borderRadius: 5,
+                            background: behind(shade("var(--node)", faded)), border: `1px solid ${behind(shade(borderOf(tone, false), faded))}`,
+                        }}
+                    />
+                );
+            })}
+        </div>
+    );
+}
+
 /**
- * The line over a level's loose boxes with "Not linked to anything on this page" in its middle (levelLayout.ts's
- * looseDivider; owner's design, 2026-10-13). It lives in the Map's own coordinates, so it pans and zooms with the boxes.
- * A hairline in the box border's colour, dimmer than the lines and never ending in an arrow, so it can't be read as one.
+ * The label over a level's loose boxes, "Not linked to anything here", on a hairline (levelLayout.ts's looseDivider;
+ * owner's design, 2026-10-13, restyled quiet by the Workbench redesign, ADR-070). It lives in the Map's own
+ * coordinates, so it pans and zooms with the boxes. A hairline in the divider's color, never ending in an arrow, so it
+ * can't be read as a line between boxes.
  */
 function LooseDivider({ divider }: { divider: Divider }){
     return (
@@ -284,11 +513,11 @@ function LooseDivider({ divider }: { divider: Divider }){
             data-testid="loose-divider"
             aria-hidden
             style={{ position: "absolute", left: divider.x, top: divider.y - 11, width: divider.width, height: 22 }}
-            className="pointer-events-none flex items-center gap-3.5"
+            className="pointer-events-none flex items-center gap-3"
         >
-            <span className="h-px flex-1 bg-border" />
-            <span className="whitespace-nowrap text-[15px] text-text-2">Not linked to anything on this page</span>
-            <span className="h-px flex-1 bg-border" />
+            <span className="h-px flex-1 bg-divider" />
+            <span className="whitespace-nowrap text-[12px] text-text-3">Not linked to anything here</span>
+            <span className="h-px flex-1 bg-divider" />
         </div>
     );
 }