@mastra/playground-ui 68.0.0-alpha.2 → 68.0.0

package/dist/domains/knowledge/components/KnowledgePageGraph.es.js

@@ -1,10 +1,19 @@
 import { t as Txt } from "../../../Txt-BM6TVV_c.js";
+import { linkCountsText } from "../lib/linkCountsText.es.js";
+import { KnowledgePageCard } from "./KnowledgePageCard.es.js";
+import { childCountLabel } from "../lib/pageTree.es.js";
+import { branchColors, crowdScale, graphShape, isChildPlaceholder, isRestCircle, isScopeGroup, radialLayout } from "../lib/graphShape.es.js";
+import { fitWords } from "../lib/circleText.es.js";
+import { prefersMotion, useLeavingNodes } from "../lib/useLeavingNodes.es.js";
+import { INITIAL_SETTLE_MS, fitAllViewport, fitDuration, fitViewport, nudgeAxis } from "../lib/fitViewport.es.js";
+import { runLayout } from "../lib/layout.es.js";
+import { pagePath, pageRef } from "../lib/pageAddress.es.js";
 import { grantGraph, pageGraphEdges, pageNeighbourIds, toPageFlow } from "../lib/pageGraph.es.js";
-import { layoutPageGraph } from "../lib/pageLayout.es.js";
-import { Fragment, memo, useCallback, useEffect, useMemo, useRef } from "react";
+import { chooseTooltipSide } from "../lib/tooltipSide.es.js";
+import { Fragment, memo, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
-import { Maximize, Pin } from "lucide-react";
-import { Background, BackgroundVariant, BaseEdge, ControlButton, Controls, Handle, MarkerType, Position, ReactFlow, ReactFlowProvider, getViewportForBounds, useReactFlow } from "@xyflow/react";
+import { ArrowUpToLine, Layers, Maximize, Pin } from "lucide-react";
+import { Background, BackgroundVariant, BaseEdge, ControlButton, Controls, Handle, MarkerType, Position, ReactFlow, ReactFlowProvider, useReactFlow, useStore } from "@xyflow/react";
 import "@xyflow/react/dist/style.css";
 import '../../../KnowledgePageGraph.css';// src/domains/knowledge/components/KnowledgePageGraph.tsx
 var SCOPE_STYLE = {
@@ -12,12 +21,29 @@ var SCOPE_STYLE = {
 	background: "color-mix(in oklab, var(--chart-blue) 16%, var(--card))"
 };
 var PAGE_STYLE = { "--knowledge-color": "var(--border-strong)" };
+/** A farther page drawn as a named circle: the legend's "Page in another branch" dot grown, same solid grey fill, name in the page background colour to read on it. */
+var FAR_FILL = "var(--muted-foreground)";
+var FAR_STYLE = {
+	"--knowledge-color": FAR_FILL,
+	background: FAR_FILL
+};
 var PARENT_EDGE_STYLE = {
 	stroke: "var(--foreground)",
 	strokeOpacity: .45,
 	strokeDasharray: "4 4",
 	strokeWidth: 1.25
 };
+var UP_EDGE_COLOR = "var(--chart-cyan)";
+var UP_EDGE_STYLE = {
+	stroke: UP_EDGE_COLOR,
+	strokeWidth: 2.25
+};
+var UP_ARROW = {
+	type: MarkerType.ArrowClosed,
+	color: UP_EDGE_COLOR,
+	width: 14,
+	height: 14
+};
 var MENTION_EDGE_COLOR = "var(--chart-blue)";
 var PARENT_ARROW_COLOR = "var(--muted-foreground)";
 var PARENT_ARROW = {
@@ -39,6 +65,38 @@ var GRANT_ARROW = {
 	width: 13,
 	height: 13
 };
+var LINK_EDGE_COLOR = "var(--chart-green)";
+var LINK_EDGE_STYLE = {
+	stroke: LINK_EDGE_COLOR,
+	strokeWidth: 1.25
+};
+var LINK_ARROW = {
+	type: MarkerType.ArrowClosed,
+	color: LINK_EDGE_COLOR,
+	width: 12,
+	height: 12
+};
+var DIRECTION_EDGE_STYLE = {
+	out: { stroke: LINK_EDGE_COLOR },
+	in: {
+		stroke: "var(--chart-orange)",
+		strokeDasharray: "6 3"
+	}
+};
+var DIRECTION_ARROW = {
+	out: LINK_ARROW,
+	in: {
+		type: MarkerType.ArrowClosed,
+		color: "var(--chart-orange)",
+		width: 12,
+		height: 12
+	}
+};
+var DOT_PARENT_EDGE_STYLE = {
+	stroke: "var(--foreground)",
+	strokeOpacity: .2,
+	strokeWidth: 1
+};
 var PLACEHOLDER_STYLE = {
 	background: "var(--card)",
 	borderColor: "var(--chart-purple)",
@@ -61,44 +119,291 @@ function pinBadgeStyle(size) {
 		}
 	};
 }
-/** A scope or page: its kind on top, its name below, both inside the circle. */
+/** How long a focus change loads before the graph says so. */
+var LOADING_HINT_DELAY_MS = 150;
+/** How long it holds the old layout for pages that never arrive before drawing what it has. */
+var LOADING_RELEASE_MS = 4e3;
+/** Most a tooltip is enlarged to offset a zoomed-out graph. */
+var TOOLTIP_MAX_SCALE = 3;
+/** Screen-space box of an element. */
+function boxOf(el) {
+	const { left, top, right, bottom } = el.getBoundingClientRect();
+	return {
+		left,
+		top,
+		right,
+		bottom
+	};
+}
+/** The highlighted lines of the graph as screen-space segments, where the browser can measure them. */
+function drawnLines(root) {
+	const lines = [];
+	for (const path of root.querySelectorAll(".react-flow__edge-path")) {
+		if (typeof path.getTotalLength !== "function" || typeof path.getScreenCTM !== "function") continue;
+		const matrix = path.getScreenCTM();
+		if (!matrix) continue;
+		const length = path.getTotalLength();
+		const start = path.getPointAtLength(0);
+		const end = path.getPointAtLength(length);
+		lines.push({
+			from: {
+				x: matrix.a * start.x + matrix.c * start.y + matrix.e,
+				y: matrix.b * start.x + matrix.d * start.y + matrix.f
+			},
+			to: {
+				x: matrix.a * end.x + matrix.c * end.y + matrix.e,
+				y: matrix.b * end.x + matrix.d * end.y + matrix.f
+			}
+		});
+	}
+	return lines;
+}
+/** Where a tooltip sits against its dot, and which way it grows from it. */
+var TOOLTIP_PLACEMENT = {
+	top: {
+		tip: "bottom-full left-1/2 mb-2",
+		transform: "translateX(-50%)",
+		origin: "bottom center",
+		tail: "top-full left-1/2 -translate-x-1/2 -translate-y-1/2 border-r border-b"
+	},
+	bottom: {
+		tip: "top-full left-1/2 mt-2",
+		transform: "translateX(-50%)",
+		origin: "top center",
+		tail: "bottom-full left-1/2 -translate-x-1/2 translate-y-1/2 border-l border-t"
+	},
+	right: {
+		tip: "left-full top-1/2 ml-2",
+		transform: "translateY(-50%)",
+		origin: "center left",
+		tail: "right-full top-1/2 translate-x-1/2 -translate-y-1/2 border-l border-b"
+	},
+	left: {
+		tip: "right-full top-1/2 mr-2",
+		transform: "translateY(-50%)",
+		origin: "center right",
+		tail: "left-full top-1/2 -translate-x-1/2 -translate-y-1/2 border-r border-t"
+	}
+};
+/** The mark on a circle for a page that sits above others: layers for a scope, an up arrow for an ancestor page. */
+function LevelIcon({ level }) {
+	return /* @__PURE__ */ jsx(level === "scope" ? Layers : ArrowUpToLine, {
+		"aria-hidden": true,
+		"data-testid": `knowledge-level-icon-${level}`,
+		className: "mr-1 inline-block size-3 align-text-bottom"
+	});
+}
+/** A page far from the focus: a small coloured dot that names itself on hover. */
+function DotNode({ data }) {
+	const { page, size, color, path, ref, links, notShown } = data;
+	const [hover, setHover] = useState(false);
+	const dotRef = useRef(null);
+	const tipRef = useRef(null);
+	const [side, setSide] = useState("top");
+	const zoom = useStore((state) => state.transform[2]);
+	const tipScale = Math.min(Math.max(1 / zoom, 1), TOOLTIP_MAX_SCALE);
+	const standIn = isChildPlaceholder(page);
+	const group = isScopeGroup(page);
+	const hint = standIn ? "Hover or click to load them" : group ? "Click to show them" : null;
+	const children = !hint && page.childCount ? `${childCountLabel(page)} ${page.childCount === 1 ? "child" : "children"}` : null;
+	const kind = page.isScope ? page.displayLabel ?? "Scope" : "Page";
+	const linkText = links && (links.in > 0 || links.out > 0) ? linkCountsText(links, notShown) : null;
+	const label = [
+		page.name,
+		hint ?? path,
+		children,
+		linkText
+	].filter(Boolean).join(" · ");
+	useLayoutEffect(() => {
+		const dot = dotRef.current;
+		const tip = tipRef.current;
+		const graph = dot?.closest(".knowledge-graph");
+		if (!hover || !dot || !tip || !graph) return;
+		const dotBox = boxOf(dot);
+		const tipBox = boxOf(tip);
+		const scaledWidth = tip.offsetWidth * tipScale;
+		const scaledHeight = tip.offsetHeight * tipScale;
+		if (!scaledWidth || !scaledHeight) return;
+		const obstacles = [...graph.querySelectorAll("[data-testid=\"knowledge-page-node\"], [data-testid=\"knowledge-page-dot\"]"), ...(graph.parentElement ?? graph).querySelectorAll("[aria-label=\"Legend\"], [data-testid=\"knowledge-graph-back\"], .react-flow__controls")].map(boxOf).filter((box) => box.right > box.left && !(box.left === tipBox.left && box.top === tipBox.top) && !(box.left === dotBox.left && box.top === dotBox.top));
+		setSide(chooseTooltipSide({
+			dot: dotBox,
+			tip: {
+				width: scaledWidth,
+				height: scaledHeight
+			},
+			gap: 8,
+			bounds: boxOf(graph),
+			obstacles,
+			lines: drawnLines(graph)
+		}));
+	}, [hover, tipScale]);
+	const placement = TOOLTIP_PLACEMENT[side];
+	return /* @__PURE__ */ jsxs("div", {
+		ref: dotRef,
+		"data-testid": "knowledge-page-dot",
+		"data-page-id": page.id,
+		"data-page-type": standIn ? "stand-in" : group ? "group" : page.isScope ? "scope" : "page",
+		"aria-label": label,
+		className: "relative cursor-pointer transition-opacity",
+		style: {
+			width: size,
+			height: size,
+			opacity: standIn ? .5 : void 0
+		},
+		onPointerEnter: () => setHover(true),
+		onPointerLeave: () => setHover(false),
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"aria-hidden": true,
+				"data-testid": "knowledge-dot-hit-area",
+				className: "absolute rounded-full",
+				style: { inset: -8 }
+			}),
+			/* @__PURE__ */ jsx("div", {
+				className: "size-full rounded-full border",
+				style: {
+					background: standIn ? "transparent" : color ?? "var(--muted-foreground)",
+					borderColor: color ?? "var(--muted-foreground)",
+					borderStyle: standIn ? "dashed" : "solid"
+				},
+				children: data.showCount && !standIn && !group && links && links.in + links.out > 0 ? /* @__PURE__ */ jsx(Txt, {
+					as: "span",
+					variant: "meta",
+					"data-testid": "knowledge-dot-count",
+					className: "flex size-full items-center justify-center",
+					style: { color: "var(--background)" },
+					children: links.in + links.out
+				}) : null
+			}),
+			hover ? /* @__PURE__ */ jsxs("div", {
+				role: "tooltip",
+				ref: tipRef,
+				"data-side": side,
+				className: `pointer-events-none absolute ${placement.tip} flex w-max max-w-72 flex-col rounded-md border border-border bg-card px-2 py-1 shadow-overlay`,
+				style: {
+					transform: `${placement.transform} scale(${tipScale})`,
+					transformOrigin: placement.origin
+				},
+				children: [/* @__PURE__ */ jsx("span", {
+					"data-testid": "knowledge-tooltip-tail",
+					"aria-hidden": true,
+					className: `absolute size-2 rotate-45 border-border bg-card ${placement.tail}`
+				}), hint ? /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(Txt, {
+					as: "span",
+					variant: "label",
+					tone: "ink",
+					children: page.name
+				}), /* @__PURE__ */ jsx(Txt, {
+					as: "span",
+					variant: "meta",
+					tone: "muted",
+					children: group ? `${path} · ${hint}` : hint
+				})] }) : /* @__PURE__ */ jsx(KnowledgePageCard, {
+					name: page.name,
+					kind,
+					pageRef: ref,
+					path,
+					childCount: page.childCount ? childCountLabel(page) : void 0,
+					links,
+					notShown
+				})]
+			}) : null,
+			/* @__PURE__ */ jsx(Handle, {
+				type: "target",
+				position: Position.Top,
+				className: "!invisible"
+			}),
+			/* @__PURE__ */ jsx(Handle, {
+				type: "source",
+				position: Position.Bottom,
+				className: "!invisible"
+			})
+		]
+	});
+}
+/** Below this a circle uses the small type and two lines of name. */
+var COMPACT_CIRCLE_SIZE = 96;
+/** The share of a circle's width its text may use; a circle is narrower toward the top and bottom. */
+var CIRCLE_TEXT_SHARE = .74;
+/** A scope or page: its kind on top, its name below, both inside the circle; far pages draw as dots. */
 function PageNodeComponent({ data }) {
-	const { page, size, selected, pinned, dimmed } = data;
+	if (data.form === "dot") return /* @__PURE__ */ jsx(DotNode, { data });
+	const { page, size, selected, pinned, badge } = data;
+	const group = isScopeGroup(page);
 	const kind = page.isScope ? page.displayLabel ?? "Scope" : "Page";
 	const placeholder = isPlaceholder(page);
+	const rest = isRestCircle(page);
+	const compact = size < COMPACT_CIRCLE_SIZE;
+	const fit = Math.max(4, Math.floor(size * CIRCLE_TEXT_SHARE / (compact ? 6.5 : 7.5)));
 	return /* @__PURE__ */ jsxs("div", {
 		"data-testid": "knowledge-page-node",
 		"data-page-id": page.id,
-		"data-page-type": placeholder ? "placeholder" : page.isScope ? "scope" : "page",
+		"data-page-type": placeholder ? "placeholder" : rest ? "rest" : group ? "group" : page.isScope ? "scope" : "page",
 		className: `relative transition-opacity ${placeholder ? "cursor-default" : "cursor-pointer"}`,
 		style: {
 			width: size,
-			height: size,
-			opacity: dimmed ? .35 : 1
+			height: size
 		},
-		title: placeholder ? `${kind} · ${page.address} · nothing written to it yet` : page.isScope && page.address ? `${kind} · ${page.address}` : page.name,
+		title: placeholder ? `${kind} · ${page.address} · nothing written to it yet` : rest ? `Show ${Math.min(12, page.childCount ?? 12)} more of ${page.childCount ?? "the rest"}` : group ? `${page.name}: click to show them` : page.isScope && page.address ? `${kind} · ${page.address}` : data.links && data.links.in + data.links.out > 0 ? `${page.name} · ${linkCountsText(data.links, data.notShown)}` : page.name,
 		children: [
 			/* @__PURE__ */ jsxs("div", {
-				className: "knowledge-circle flex size-full flex-col items-center justify-center gap-0.5 overflow-hidden rounded-full border-2 px-3 text-center shadow-raised",
+				className: `knowledge-circle flex size-full flex-col items-center justify-center gap-0.5 overflow-hidden rounded-full border-2 text-center shadow-raised ${rest ? "hover:border-foreground" : ""}`,
 				"data-selected": selected || void 0,
-				style: placeholder ? PLACEHOLDER_STYLE : page.isScope ? SCOPE_STYLE : PAGE_STYLE,
-				children: [/* @__PURE__ */ jsx(Txt, {
+				"data-far": data.far || void 0,
+				style: {
+					...placeholder || rest ? PLACEHOLDER_STYLE : data.far ? FAR_STYLE : page.isScope ? SCOPE_STYLE : PAGE_STYLE,
+					paddingInline: size * (.26 / 2)
+				},
+				children: [data.far ? null : /* @__PURE__ */ jsxs(Txt, {
 					as: "span",
 					variant: "meta",
 					tone: page.isScope ? void 0 : "muted",
-					className: "pointer-events-none line-clamp-2 max-w-full tracking-wide uppercase",
+					className: "pointer-events-none inline-flex max-w-full items-center justify-center gap-1 whitespace-nowrap uppercase",
 					style: page.isScope ? { color: "var(--chart-blue)" } : void 0,
 					"data-testid": page.isScope ? "knowledge-scope-caption" : "knowledge-page-caption",
-					children: kind
+					children: [data.level ? /* @__PURE__ */ jsx(LevelIcon, { level: data.level }) : null, /* @__PURE__ */ jsx("span", {
+						className: "truncate",
+						children: rest ? "More" : data.isParent ? "Parent" : kind
+					})]
 				}), /* @__PURE__ */ jsx(Txt, {
 					as: "span",
-					variant: "label",
+					variant: compact ? "meta" : "label",
 					tone: "ink",
-					className: "pointer-events-none line-clamp-3 max-w-full break-words",
-					children: page.isScope && page.address ? /* @__PURE__ */ jsx(BreakAtColons, { text: page.address }) : page.name
+					className: `pointer-events-none max-w-full overflow-hidden [overflow-wrap:normal] ${compact ? "line-clamp-2" : "line-clamp-3"}`,
+					style: data.far ? { color: "var(--background)" } : void 0,
+					"data-testid": "knowledge-circle-name",
+					children: page.isScope && page.address && !group ? /* @__PURE__ */ jsx(BreakAtColons, { text: fitWords(page.address, fit) }) : fitWords(page.name, fit)
 				})]
 			}),
 			pinned ? /* @__PURE__ */ jsx(PinBadge, { size }) : null,
+			data.hiddenLinks && (data.hiddenLinks.in > 0 || data.hiddenLinks.out > 0) ? /* @__PURE__ */ jsxs("span", {
+				"data-testid": "knowledge-hidden-links",
+				title: linkCountsText(data.hiddenLinks),
+				"aria-label": linkCountsText(data.hiddenLinks),
+				className: "absolute bottom-full left-1/2 -mb-1 flex -translate-x-1/2 gap-1 rounded-full border border-border bg-card px-1.5 shadow-raised",
+				children: [data.hiddenLinks.in > 0 ? /* @__PURE__ */ jsxs(Txt, {
+					as: "span",
+					variant: "meta",
+					style: { color: "var(--chart-orange)" },
+					children: ["→", data.hiddenLinks.in]
+				}) : null, data.hiddenLinks.out > 0 ? /* @__PURE__ */ jsxs(Txt, {
+					as: "span",
+					variant: "meta",
+					style: { color: LINK_EDGE_COLOR },
+					children: [data.hiddenLinks.out, "→"]
+				}) : null]
+			}) : null,
+			badge ? /* @__PURE__ */ jsx("span", {
+				"data-testid": "knowledge-child-count-badge",
+				"aria-label": `${badge} children, not all drawn`,
+				className: "absolute top-full left-1/2 -mt-1 -translate-x-1/2 rounded-full border border-border bg-card px-1.5 shadow-raised",
+				children: /* @__PURE__ */ jsx(Txt, {
+					as: "span",
+					variant: "meta",
+					tone: "ink",
+					children: badge
+				})
+			}) : null,
 			/* @__PURE__ */ jsx(Handle, {
 				type: "target",
 				position: Position.Top,
@@ -155,10 +460,7 @@ function RimEdgeComponent({ id, data, style, markerEnd }) {
 	return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(BaseEdge, {
 		id,
 		path,
-		style: {
-			...style,
-			opacity: data.dimmed ? .2 : 1
-		},
+		style,
 		markerEnd,
 		interactionWidth: mention ? 20 : 0
 	}), data.kind === "grant" && data.role ? /* @__PURE__ */ jsx("path", {
@@ -172,7 +474,7 @@ function RimEdgeComponent({ id, data, style, markerEnd }) {
 		children: /* @__PURE__ */ jsx("title", { children: `Grants ${data.role}` })
 	}) : null] });
 }
-var edgeTypes = { rim: RimEdgeComponent };
+var edgeTypes = { rim: memo(RimEdgeComponent) };
 var nodeTypes = { page: memo(PageNodeComponent) };
 /** The box around laid-out circles, in graph coordinates; `null` when there are none. */
 function graphBounds(nodes) {
@@ -196,7 +498,7 @@ function graphBounds(nodes) {
 }
 var LEGEND_SWATCH = "knowledge-circle inline-block size-3 shrink-0 rounded-full border-2";
 /** What the circles, lines and badge mean. */
-function GraphLegend({ grants }) {
+function GraphLegend({ drawn, counts, dots, linkEnds, focused, levels, branches }) {
 	return /* @__PURE__ */ jsxs("ul", {
 		"aria-label": "Legend",
 		className: "pointer-events-none absolute top-2 left-2 z-10 flex flex-col gap-1 rounded-md border border-border bg-card/90 px-2 py-1.5 shadow-raised",
@@ -214,6 +516,32 @@ function GraphLegend({ grants }) {
 					children: "Scope"
 				})]
 			}),
+			levels.includes("scope") ? /* @__PURE__ */ jsxs("li", {
+				className: "flex items-center gap-2",
+				"data-testid": "knowledge-legend-level-scope",
+				children: [/* @__PURE__ */ jsx(Layers, {
+					"aria-hidden": true,
+					className: "size-3 shrink-0 text-muted-foreground"
+				}), /* @__PURE__ */ jsx(Txt, {
+					as: "span",
+					variant: "meta",
+					tone: "muted",
+					children: "Scope, above its pages"
+				})]
+			}) : null,
+			levels.includes("ancestor") ? /* @__PURE__ */ jsxs("li", {
+				className: "flex items-center gap-2",
+				"data-testid": "knowledge-legend-level-ancestor",
+				children: [/* @__PURE__ */ jsx(ArrowUpToLine, {
+					"aria-hidden": true,
+					className: "size-3 shrink-0 text-muted-foreground"
+				}), /* @__PURE__ */ jsx(Txt, {
+					as: "span",
+					variant: "meta",
+					tone: "muted",
+					children: "Page above the focus"
+				})]
+			}) : null,
 			/* @__PURE__ */ jsxs("li", {
 				className: "flex items-center gap-2",
 				children: [/* @__PURE__ */ jsx("span", {
@@ -227,8 +555,122 @@ function GraphLegend({ grants }) {
 					children: "Page"
 				})]
 			}),
-			/* @__PURE__ */ jsxs("li", {
+			focused ? /* @__PURE__ */ jsxs("li", {
+				className: "flex items-center gap-2",
+				"data-testid": "knowledge-legend-focused",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: LEGEND_SWATCH,
+					style: {
+						...PAGE_STYLE,
+						outline: "2px solid var(--knowledge-color)",
+						outlineOffset: 2,
+						borderWidth: 3
+					},
+					"aria-hidden": true
+				}), /* @__PURE__ */ jsx(Txt, {
+					as: "span",
+					variant: "meta",
+					tone: "muted",
+					children: "Focused page"
+				})]
+			}) : null,
+			dots || linkEnds ? /* @__PURE__ */ jsxs("li", {
+				className: "flex items-center gap-2",
+				"data-testid": "knowledge-legend-dot",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "inline-block size-2 shrink-0 rounded-full bg-muted-foreground",
+					"aria-hidden": true
+				}), /* @__PURE__ */ jsx(Txt, {
+					as: "span",
+					variant: "meta",
+					tone: "muted",
+					children: "Page in another branch"
+				})]
+			}) : null,
+			branches.slice(0, LEGEND_BRANCH_CAP).map((branch) => /* @__PURE__ */ jsxs("li", {
+				className: "flex items-center gap-2 pl-0.5",
+				"data-testid": "knowledge-legend-branch",
+				children: [/* @__PURE__ */ jsx("span", {
+					className: "inline-block size-2 shrink-0 rounded-full",
+					style: { background: branch.color },
+					"aria-hidden": true
+				}), /* @__PURE__ */ jsx(Txt, {
+					as: "span",
+					variant: "meta",
+					tone: "muted",
+					className: "max-w-40 truncate",
+					title: branch.name,
+					children: branches.length > 1 ? `Under ${branch.name}` : branch.scope ? "Under parent scope" : "Under parent page"
+				})]
+			}, branch.id)),
+			branches.length > LEGEND_BRANCH_CAP ? /* @__PURE__ */ jsx("li", {
+				className: "pl-0.5",
+				children: /* @__PURE__ */ jsxs(Txt, {
+					as: "span",
+					variant: "meta",
+					tone: "muted",
+					children: [
+						"+",
+						branches.length - LEGEND_BRANCH_CAP,
+						" more branches"
+					]
+				})
+			}) : null,
+			drawn.has("out") || drawn.has("in") ? /* @__PURE__ */ jsxs(Fragment$1, { children: [drawn.has("out") ? /* @__PURE__ */ jsxs("li", {
 				className: "flex items-center gap-2",
+				"data-testid": "knowledge-legend-out",
+				children: [/* @__PURE__ */ jsxs("svg", {
+					width: "16",
+					height: "8",
+					"aria-hidden": true,
+					className: "shrink-0",
+					children: [/* @__PURE__ */ jsx("line", {
+						x1: "0",
+						y1: "4",
+						x2: "12",
+						y2: "4",
+						stroke: LINK_EDGE_COLOR,
+						strokeWidth: "1.5"
+					}), /* @__PURE__ */ jsx("polygon", {
+						points: "11,1 16,4 11,7",
+						fill: LINK_EDGE_COLOR
+					})]
+				}), /* @__PURE__ */ jsx(Txt, {
+					as: "span",
+					variant: "meta",
+					tone: "muted",
+					children: "Links out of the selected page"
+				})]
+			}) : null, drawn.has("in") ? /* @__PURE__ */ jsxs("li", {
+				className: "flex items-center gap-2",
+				"data-testid": "knowledge-legend-in",
+				children: [/* @__PURE__ */ jsxs("svg", {
+					width: "16",
+					height: "8",
+					"aria-hidden": true,
+					className: "shrink-0",
+					children: [/* @__PURE__ */ jsx("line", {
+						x1: "0",
+						y1: "4",
+						x2: "12",
+						y2: "4",
+						stroke: "var(--chart-orange)",
+						strokeWidth: "1.5",
+						strokeDasharray: "3 2"
+					}), /* @__PURE__ */ jsx("polygon", {
+						points: "11,1 16,4 11,7",
+						fill: "var(--chart-orange)"
+					})]
+				}), /* @__PURE__ */ jsx(Txt, {
+					as: "span",
+					variant: "meta",
+					tone: "muted",
+					children: "Links into it"
+				})]
+			}) : null] }) : null,
+			drawn.has("mention") ? /* @__PURE__ */ jsxs("li", {
+				className: "flex items-center gap-2",
+				"data-testid": "knowledge-legend-mention",
 				children: [/* @__PURE__ */ jsx("svg", {
 					width: "12",
 					height: "4",
@@ -248,8 +690,81 @@ function GraphLegend({ grants }) {
 					tone: "muted",
 					children: "Mentioned in notes"
 				})]
-			}),
-			/* @__PURE__ */ jsxs("li", {
+			}) : null,
+			drawn.has("link") ? /* @__PURE__ */ jsxs("li", {
+				className: "flex items-center gap-2",
+				children: [/* @__PURE__ */ jsxs("svg", {
+					width: "16",
+					height: "8",
+					"aria-hidden": true,
+					className: "shrink-0",
+					"data-testid": "knowledge-legend-link",
+					children: [/* @__PURE__ */ jsx("line", {
+						x1: "0",
+						y1: "4",
+						x2: "12",
+						y2: "4",
+						...LINK_EDGE_STYLE
+					}), /* @__PURE__ */ jsx("polygon", {
+						points: "11,1 16,4 11,7",
+						fill: LINK_EDGE_COLOR
+					})]
+				}), /* @__PURE__ */ jsx(Txt, {
+					as: "span",
+					variant: "meta",
+					tone: "muted",
+					children: "Linked in page body"
+				})]
+			}) : null,
+			drawn.has("dot-parent") ? /* @__PURE__ */ jsxs("li", {
+				className: "flex items-center gap-2",
+				"data-testid": "knowledge-legend-dot-parent",
+				children: [/* @__PURE__ */ jsx("svg", {
+					width: "16",
+					height: "4",
+					"aria-hidden": true,
+					className: "shrink-0",
+					children: /* @__PURE__ */ jsx("line", {
+						x1: "0",
+						y1: "2",
+						x2: "16",
+						y2: "2",
+						...DOT_PARENT_EDGE_STYLE,
+						strokeOpacity: .5
+					})
+				}), /* @__PURE__ */ jsx(Txt, {
+					as: "span",
+					variant: "meta",
+					tone: "muted",
+					children: "Child page (dot)"
+				})]
+			}) : null,
+			drawn.has("up") ? /* @__PURE__ */ jsxs("li", {
+				className: "flex items-center gap-2",
+				"data-testid": "knowledge-legend-up",
+				children: [/* @__PURE__ */ jsxs("svg", {
+					width: "16",
+					height: "8",
+					"aria-hidden": true,
+					className: "shrink-0",
+					children: [/* @__PURE__ */ jsx("line", {
+						x1: "0",
+						y1: "4",
+						x2: "12",
+						y2: "4",
+						...UP_EDGE_STYLE
+					}), /* @__PURE__ */ jsx("polygon", {
+						points: "9,1 15,4 9,7",
+						fill: UP_EDGE_COLOR
+					})]
+				}), /* @__PURE__ */ jsx(Txt, {
+					as: "span",
+					variant: "meta",
+					tone: "muted",
+					children: "Parent of the focused page"
+				})]
+			}) : null,
+			drawn.has("parent") ? /* @__PURE__ */ jsxs("li", {
 				className: "flex items-center gap-2",
 				children: [/* @__PURE__ */ jsxs("svg", {
 					width: "16",
@@ -278,8 +793,32 @@ function GraphLegend({ grants }) {
 					tone: "muted",
 					children: "Parent → child"
 				})]
-			}),
-			grants ? /* @__PURE__ */ jsxs("li", {
+			}) : null,
+			counts ? /* @__PURE__ */ jsxs("li", {
+				className: "flex items-center gap-2",
+				"data-testid": "knowledge-legend-link-counts",
+				children: [
+					/* @__PURE__ */ jsx(Txt, {
+						as: "span",
+						variant: "meta",
+						style: { color: "var(--chart-orange)" },
+						children: "→4"
+					}),
+					/* @__PURE__ */ jsx(Txt, {
+						as: "span",
+						variant: "meta",
+						style: { color: LINK_EDGE_COLOR },
+						children: "14→"
+					}),
+					/* @__PURE__ */ jsx(Txt, {
+						as: "span",
+						variant: "meta",
+						tone: "muted",
+						children: "Links in, links out (not drawn)"
+					})
+				]
+			}) : null,
+			drawn.has("grant") ? /* @__PURE__ */ jsxs("li", {
 				className: "flex items-center gap-2",
 				children: [/* @__PURE__ */ jsxs("svg", {
 					width: "16",
@@ -324,14 +863,82 @@ function GraphLegend({ grants }) {
 }
 /** How far the pointer may move between press and release and still count as a click, not a pan. */
 var CLICK_SLOP_PX = 4;
+/** Marks the nodes and lines that stay lit while the rest of the graph fades (see knowledge.css). */
+var NEIGHBOUR_CLASS = "knowledge-neighbour";
+/**
+* The same edge objects while their content is unchanged. Pointing at a page changes the style of the
+* few lines touching it; handing React Flow fresh objects for every line would redraw them all.
+*/
+function useStableEdges(edges) {
+	const seen = useRef(/* @__PURE__ */ new Map());
+	return useMemo(() => {
+		const next = /* @__PURE__ */ new Map();
+		const result = edges.map((edge) => {
+			const sig = JSON.stringify(edge);
+			const before = seen.current.get(edge.id);
+			const entry = before && before.sig === sig ? before : {
+				sig,
+				edge
+			};
+			next.set(edge.id, entry);
+			return entry.edge;
+		});
+		seen.current = next;
+		return result;
+	}, [edges]);
+}
+/** The focused page's circle is this much larger than its neighbours'. */
+var FOCUSED_SCALE = 1.2;
+/** Pages in other branches that the focus links to draw a little smaller than its own neighbours. */
+var LINK_END_SCALE = .8;
+/** Most branch colours the legend names; the rest are counted. */
+var LEGEND_BRANCH_CAP = 4;
+/** Most links a hovered page draws that aren't drawn already. */
+var HOVER_LINK_CAP = 40;
 /**
 * The schema-4 Knowledge page graph: scopes and pages as circles sized by how often they are mentioned,
 * parent links as faint edges and mentions as solid ones. The first layout is deterministic for the same pages; later updates start from where pages already sit.
 */
 function KnowledgePageGraph(props) {
-	return /* @__PURE__ */ jsx(ReactFlowProvider, { children: /* @__PURE__ */ jsx(KnowledgePageGraphInner, { ...props }) });
+	const { settled = true } = props;
+	const held = useRef(props);
+	const [released, setReleased] = useState(false);
+	const holding = !settled && !released;
+	if (!holding) held.current = props;
+	const shown = !holding ? props : {
+		...props,
+		pages: held.current.pages,
+		edges: held.current.edges,
+		pinnedIds: held.current.pinnedIds,
+		grants: held.current.grants,
+		selectedPageId: held.current.selectedPageId,
+		centerId: held.current.centerId,
+		hiddenLinks: held.current.hiddenLinks,
+		knownLinks: held.current.knownLinks,
+		nearIds: held.current.nearIds
+	};
+	const [slow, setSlow] = useState(false);
+	useEffect(() => {
+		if (settled) {
+			setSlow(false);
+			setReleased(false);
+			return;
+		}
+		const hint = setTimeout(() => setSlow(true), LOADING_HINT_DELAY_MS);
+		const deadline = setTimeout(() => setReleased(true), LOADING_RELEASE_MS);
+		return () => {
+			clearTimeout(hint);
+			clearTimeout(deadline);
+		};
+	}, [settled, props.selectedPageId]);
+	return /* @__PURE__ */ jsxs(ReactFlowProvider, { children: [/* @__PURE__ */ jsx(KnowledgePageGraphInner, { ...shown }), slow && holding ? /* @__PURE__ */ jsx("p", {
+		role: "status",
+		"data-testid": "knowledge-graph-loading",
+		className: "text-ui-sm pointer-events-none absolute bottom-3 left-1/2 z-10 -translate-x-1/2 rounded border border-border bg-card px-3 py-1 text-muted-foreground shadow-overlay",
+		children: "Loading pages…"
+	}) : null] });
 }
-function KnowledgePageGraphInner({ pages, edges, pinnedIds = [], grants, selectedPageId, onSelect, onOpen, onClearSelection, onMentionSelect }) {
+function KnowledgePageGraphInner({ pages, edges, pinnedIds = [], grants, selectedPageId, centerId, hiddenLinks, knownLinks, nearIds, exactLinkCounts, fetchedLinks, onHover, showCounts, onPreview, onSelect, onOpen, onClearSelection, onMentionSelect }) {
 	const { graphPages, allEdges } = useMemo(() => {
 		const granted = grantGraph(pages, grants);
 		return {
@@ -343,28 +950,167 @@ function KnowledgePageGraphInner({ pages, edges, pinnedIds = [], grants, selecte
 		edges,
 		grants
 	]);
-	const lastLayout = useRef(void 0);
+	const linkSource = knownLinks ?? edges;
+	const linkCounts = useMemo(() => {
+		const counts = /* @__PURE__ */ new Map();
+		const pairs = /* @__PURE__ */ new Set();
+		for (const edge of linkSource) {
+			if (edge.kind !== "mention" && edge.kind !== "link") continue;
+			if (edge.source === edge.target || pairs.has(`${edge.source}\u0000${edge.target}`)) continue;
+			pairs.add(`${edge.source}\u0000${edge.target}`);
+			const out = counts.get(edge.source) ?? {
+				in: 0,
+				out: 0
+			};
+			out.out++;
+			counts.set(edge.source, out);
+			const into = counts.get(edge.target) ?? {
+				in: 0,
+				out: 0
+			};
+			into.in++;
+			counts.set(edge.target, into);
+		}
+		for (const [id, exact] of exactLinkCounts ?? []) counts.set(id, exact);
+		return counts;
+	}, [linkSource, exactLinkCounts]);
+	const hoverLinks = useMemo(() => {
+		const touching = /* @__PURE__ */ new Map();
+		const add = (id, edge) => {
+			const list = touching.get(id);
+			if (list) list.push(edge);
+			else touching.set(id, [edge]);
+		};
+		for (const edge of [...linkSource, ...fetchedLinks ?? []]) {
+			if (edge.kind !== "mention" && edge.kind !== "link") continue;
+			add(edge.source, edge);
+			if (edge.target !== edge.source) add(edge.target, edge);
+		}
+		return touching;
+	}, [linkSource, fetchedLinks]);
 	const laidOut = useMemo(() => {
+		const shape = graphShape(graphPages, selectedPageId ?? centerId ?? null, nearIds);
+		const colors = branchColors(graphPages, shape);
 		const flow = toPageFlow(graphPages, allEdges);
-		const layout = layoutPageGraph(lastLayout.current, flow.nodes.map((node) => ({
+		for (const node of flow.nodes) if (shape.form.get(node.id) === "dot") {
+			const links = linkCounts.get(node.id);
+			const counted = showCounts && !isChildPlaceholder(node.data.page) && !!links && links.in + links.out > 0;
+			node.data.size = counted ? 28 : 20;
+		} else if (node.id === shape.center) node.data.size = Math.round(node.data.size * FOCUSED_SCALE);
+		else node.data.size = Math.round(108 * (shape.linked.has(node.id) ? LINK_END_SCALE : 1));
+		const ring = flow.nodes.filter((node) => shape.depth.get(node.id) === 1 && shape.form.get(node.id) === "full");
+		const crowd = crowdScale(ring.length);
+		if (crowd < 1) for (const node of ring) node.data.size = Math.round(node.data.size * crowd);
+		const sizes = new Map(flow.nodes.map((node) => [node.id, node.data.size]));
+		const radial = radialLayout(graphPages, shape, (page) => sizes.get(page.id) ?? 20, nearIds);
+		const positions = runLayout(flow.nodes.map((node) => ({
 			id: node.id,
-			size: node.data.size
-		})), flow.edges.map((edge) => ({
-			source: edge.source,
-			target: edge.target
-		})));
-		lastLayout.current = layout;
+			size: node.data.size,
+			padding: shape.form.get(node.id) === "dot" ? 4 : 24,
+			initial: radial.get(node.id)
+		})), [], { ticks: 0 });
 		return {
 			nodes: flow.nodes,
 			edges: flow.edges,
-			positions: layout.positions
+			positions,
+			shape,
+			colors
 		};
-	}, [graphPages, allEdges]);
-	const pinned = useMemo(() => new Set(pinnedIds), [pinnedIds]);
-	const neighbours = useMemo(() => selectedPageId && laidOut.positions.has(selectedPageId) ? pageNeighbourIds(selectedPageId, allEdges) : null, [
+	}, [
+		graphPages,
+		allEdges,
 		selectedPageId,
+		centerId,
+		linkCounts,
+		showCounts,
+		nearIds
+	]);
+	const pageById = useMemo(() => new Map(graphPages.map((page) => [page.id, page])), [graphPages]);
+	const focusParentId = useMemo(() => {
+		const parentId = laidOut.shape.center ? pageById.get(laidOut.shape.center)?.parentId : void 0;
+		return parentId && laidOut.positions.has(parentId) ? parentId : null;
+	}, [laidOut, pageById]);
+	const drawnLevels = useMemo(() => {
+		const kinds = /* @__PURE__ */ new Set();
+		for (const [id, level] of laidOut.shape.level) if (laidOut.shape.form.get(id) === "full") kinds.add(level);
+		return [...kinds];
+	}, [laidOut]);
+	const dotBranches = useMemo(() => {
+		const seen = /* @__PURE__ */ new Map();
+		for (const node of laidOut.nodes) {
+			if (laidOut.shape.form.get(node.id) !== "dot" || isChildPlaceholder(node.data.page)) continue;
+			const branch = laidOut.shape.branch.get(node.id);
+			const color = branch ? laidOut.colors.get(branch) : void 0;
+			const owner = branch ? pageById.get(branch) : void 0;
+			if (branch && color && owner && !seen.has(branch)) seen.set(branch, {
+				id: branch,
+				name: owner.displayLabel ?? owner.name,
+				color,
+				scope: !!owner.isScope
+			});
+		}
+		return [...seen.values()];
+	}, [laidOut, pageById]);
+	const pinned = useMemo(() => new Set(pinnedIds), [pinnedIds]);
+	const childrenUndrawn = useMemo(() => {
+		const drawn = /* @__PURE__ */ new Map();
+		for (const page of graphPages) if (page.parentId && !isChildPlaceholder(page) && !isRestCircle(page)) drawn.set(page.parentId, (drawn.get(page.parentId) ?? 0) + 1);
+		return new Set(graphPages.filter((page) => !isScopeGroup(page) && !isRestCircle(page) && (page.childCountCapped || (page.childCount ?? 0) > (drawn.get(page.id) ?? 0))).map((page) => page.id));
+	}, [graphPages]);
+	const [hoveredId, setHoveredId] = useState(null);
+	useEffect(() => onHover?.(hoveredId), [hoveredId, onHover]);
+	const hoverExtra = useMemo(() => {
+		if (!hoveredId) return [];
+		const drawnIds = new Set(laidOut.nodes.map((node) => node.id));
+		const have = new Set(laidOut.edges.map((edge) => edge.id));
+		const extra = [];
+		for (const edge of hoverLinks.get(hoveredId) ?? []) {
+			const id = `${edge.kind}:${edge.source}->${edge.target}`;
+			if (have.has(id) || !drawnIds.has(edge.source) || !drawnIds.has(edge.target)) continue;
+			have.add(id);
+			extra.push({
+				id,
+				source: edge.source,
+				target: edge.target,
+				data: {
+					kind: edge.kind,
+					count: edge.count ?? 1
+				}
+			});
+			if (extra.length >= HOVER_LINK_CAP) break;
+		}
+		return extra;
+	}, [
+		hoveredId,
+		hoverLinks,
+		laidOut
+	]);
+	const hoveredNotShown = useMemo(() => {
+		const total = hoveredId ? linkCounts.get(hoveredId) : void 0;
+		if (!hoveredId || !total) return 0;
+		const pairs = /* @__PURE__ */ new Set();
+		for (const edge of [...laidOut.edges, ...hoverExtra]) {
+			const kind = edge.data?.kind;
+			if (kind !== "mention" && kind !== "link" || edge.source !== hoveredId && edge.target !== hoveredId) continue;
+			pairs.add(`${edge.source}\u0000${edge.target}`);
+		}
+		return Math.max(0, total.in + total.out - pairs.size);
+	}, [
+		hoveredId,
+		linkCounts,
 		laidOut,
-		allEdges
+		hoverExtra
+	]);
+	const emphasisId = hoveredId && laidOut.positions.has(hoveredId) ? hoveredId : selectedPageId ?? null;
+	const neighbours = useMemo(() => emphasisId && laidOut.positions.has(emphasisId) ? pageNeighbourIds(emphasisId, [...allEdges, ...hoverExtra.map((edge) => ({
+		kind: edge.data?.kind ?? "link",
+		source: edge.source,
+		target: edge.target
+	}))]) : null, [
+		emphasisId,
+		laidOut,
+		allEdges,
+		hoverExtra
 	]);
 	const nodes = useMemo(() => laidOut.nodes.map((node) => {
 		const center = laidOut.positions.get(node.id) ?? {
@@ -398,16 +1144,32 @@ function KnowledgePageGraphInner({ pages, edges, pinnedIds = [], grants, selecte
 				...node.data,
 				selected: node.id === selectedPageId,
 				pinned: pinned.has(node.id),
-				dimmed: !!neighbours && !neighbours.has(node.id)
+				form: laidOut.shape.form.get(node.id) ?? "full",
+				color: laidOut.colors.get(laidOut.shape.branch.get(node.id) ?? ""),
+				badge: childrenUndrawn.has(node.id) ? childCountLabel(node.data.page) : void 0,
+				path: pagePath(node.data.page, pageById),
+				hiddenLinks: laidOut.shape.form.get(node.id) === "full" ? hiddenLinks?.get(node.id) : void 0,
+				ref: pageRef(node.data.page, pageById),
+				links: linkCounts.get(node.id),
+				showCount: showCounts,
+				level: laidOut.shape.form.get(node.id) === "full" ? laidOut.shape.level.get(node.id) : void 0,
+				isParent: node.id === focusParentId,
+				far: laidOut.shape.linked.has(node.id) || void 0
 			}
 		};
 	}), [
 		laidOut,
 		selectedPageId,
 		pinned,
-		neighbours
+		childrenUndrawn,
+		pageById,
+		hiddenLinks,
+		linkCounts,
+		showCounts,
+		focusParentId
 	]);
-	const flowEdges = useMemo(() => {
+	const { flowEdges: builtEdges, drawnEdgeStyles } = useMemo(() => {
+		const drawn = /* @__PURE__ */ new Set();
 		const sizes = new Map(laidOut.nodes.map((node) => [node.id, node.data.size]));
 		const circle = (id) => {
 			return {
@@ -418,71 +1180,168 @@ function KnowledgePageGraphInner({ pages, edges, pinnedIds = [], grants, selecte
 				r: (sizes.get(id) ?? 0) / 2
 			};
 		};
-		return laidOut.edges.map((edge) => {
-			const mention = edge.data?.kind === "mention";
-			const grant = edge.data?.kind === "grant";
-			const dimmed = !!neighbours && !(neighbours.has(edge.source) && neighbours.has(edge.target));
-			return {
-				...edge,
-				type: "rim",
-				data: {
-					kind: edge.data?.kind ?? "parent",
-					count: edge.data?.count ?? 1,
-					...edge.data?.role ? { role: edge.data.role } : {},
-					from: circle(edge.source),
-					to: circle(edge.target),
-					dimmed
-				},
-				...mention && onMentionSelect ? { className: "cursor-pointer" } : {},
-				style: mention ? {
-					stroke: MENTION_EDGE_COLOR,
-					strokeWidth: Math.min(1.5 + (edge.data?.count ?? 1) * .5, 4)
-				} : grant ? GRANT_EDGE_STYLE : PARENT_EDGE_STYLE,
-				markerEnd: mention ? {
-					type: MarkerType.ArrowClosed,
-					color: MENTION_EDGE_COLOR,
-					width: 14,
-					height: 14
-				} : grant ? GRANT_ARROW : PARENT_ARROW
-			};
-		});
+		return {
+			flowEdges: [...laidOut.edges, ...hoverExtra].map((edge) => {
+				const mention = edge.data?.kind === "mention";
+				const grant = edge.data?.kind === "grant";
+				const link = edge.data?.kind === "link";
+				const toDot = laidOut.shape.form.get(edge.target) === "dot";
+				const direction = (mention || link) && emphasisId ? edge.source === emphasisId ? "out" : edge.target === emphasisId ? "in" : void 0 : void 0;
+				const up = !mention && !grant && !link && edge.source === focusParentId && edge.target === laidOut.shape.center;
+				drawn.add(direction ?? (up ? "up" : mention ? "mention" : grant ? "grant" : link ? "link" : toDot ? "dot-parent" : "parent"));
+				return {
+					...edge,
+					type: "rim",
+					data: {
+						kind: edge.data?.kind ?? "parent",
+						count: edge.data?.count ?? 1,
+						...edge.data?.role ? { role: edge.data.role } : {},
+						from: circle(edge.source),
+						to: circle(edge.target)
+					},
+					...direction === "in" ? { zIndex: 1 } : {},
+					...mention && onMentionSelect ? { className: "cursor-pointer" } : {},
+					style: direction ? {
+						...DIRECTION_EDGE_STYLE[direction],
+						strokeWidth: mention ? 2 : 1.5
+					} : mention ? {
+						stroke: MENTION_EDGE_COLOR,
+						strokeWidth: Math.min(1.5 + (edge.data?.count ?? 1) * .5, 4)
+					} : up ? UP_EDGE_STYLE : grant ? GRANT_EDGE_STYLE : link ? LINK_EDGE_STYLE : toDot ? DOT_PARENT_EDGE_STYLE : PARENT_EDGE_STYLE,
+					markerEnd: direction ? DIRECTION_ARROW[direction] : up ? UP_ARROW : mention ? {
+						type: MarkerType.ArrowClosed,
+						color: MENTION_EDGE_COLOR,
+						width: 14,
+						height: 14
+					} : grant ? GRANT_ARROW : link ? LINK_ARROW : toDot ? void 0 : PARENT_ARROW
+				};
+			}),
+			drawnEdgeStyles: drawn
+		};
 	}, [
 		laidOut,
+		hoverExtra,
 		onMentionSelect,
-		neighbours
+		emphasisId,
+		focusParentId
+	]);
+	const flowEdges = useStableEdges(builtEdges);
+	const emphasisedNodes = useMemo(() => nodes.map((node) => {
+		const near = neighbours?.has(node.id);
+		const hovered = node.id === hoveredId && hoveredNotShown > 0;
+		if (!near && !hovered) return node;
+		return {
+			...node,
+			...near ? { className: NEIGHBOUR_CLASS } : {},
+			...hovered ? { data: {
+				...node.data,
+				notShown: hoveredNotShown
+			} } : {}
+		};
+	}), [
+		nodes,
+		neighbours,
+		hoveredId,
+		hoveredNotShown
 	]);
+	const emphasisedEdges = useMemo(() => neighbours ? flowEdges.map((edge) => neighbours.has(edge.source) && neighbours.has(edge.target) ? {
+		...edge,
+		className: [edge.className, NEIGHBOUR_CLASS].filter(Boolean).join(" ")
+	} : edge) : flowEdges, [flowEdges, neighbours]);
 	const pagesById = useMemo(() => new Map(pages.map((page) => [page.id, page])), [pages]);
 	const reactFlow = useReactFlow();
 	const containerRef = useRef(null);
 	const hasNodes = nodes.length > 0;
+	const drawnNodes = useLeavingNodes(emphasisedNodes, prefersMotion());
+	const linkedIds = laidOut.shape.linked;
 	const fitState = useRef({
 		nodes,
-		allEdges,
 		selectedPageId,
-		reactFlow
+		centerId,
+		reactFlow,
+		linkedIds
 	});
 	fitState.current = {
 		nodes,
-		allEdges,
 		selectedPageId,
-		reactFlow
+		centerId,
+		reactFlow,
+		linkedIds
 	};
 	const fitPending = useRef(false);
-	const fit = useCallback((focusSelection, duration) => {
+	const paneAndNodes = () => {
 		const container = containerRef.current;
 		const width = container?.clientWidth ?? 0;
 		const height = container?.clientHeight ?? 0;
 		if (width === 0 || height === 0) {
 			fitPending.current = true;
-			return;
+			return null;
 		}
 		fitPending.current = false;
-		const { nodes: current, allEdges: edgesNow, selectedPageId: selected, reactFlow: flow } = fitState.current;
-		const focus = focusSelection && selected ? pageNeighbourIds(selected, edgesNow) : null;
-		const bounds = graphBounds(focus ? current.filter((node) => focus.has(node.id)) : current);
-		if (!bounds) return;
-		const viewport = getViewportForBounds(bounds, width, height, .1, focus ? 1.5 : 2, focus ? .3 : .1);
-		flow.setViewport(viewport, duration ? { duration } : void 0);
+		const { nodes: current, reactFlow: flow } = fitState.current;
+		const bounds = graphBounds(current);
+		return bounds ? {
+			container,
+			width,
+			height,
+			current,
+			flow,
+			bounds
+		} : null;
+	};
+	const fit = useCallback((duration) => {
+		const view = paneAndNodes();
+		if (!view) return;
+		const { selectedPageId: selected, centerId: centre, linkedIds: linked } = fitState.current;
+		const anchor = view.current.find((node) => node.id === (selected ?? centre));
+		const ring = !!selected && view.current.some((node) => linked.has(node.id));
+		const viewport = fitViewport({
+			bounds: view.bounds,
+			width: view.width,
+			height: view.height,
+			ring,
+			anchor
+		});
+		view.flow.setViewport(viewport, duration ? { duration } : void 0);
+	}, []);
+	const fitInitial = useCallback(() => {
+		const view = paneAndNodes();
+		if (!view) return;
+		const box = view.container?.getBoundingClientRect();
+		const legend = view.container?.querySelector("[aria-label=\"Legend\"]")?.getBoundingClientRect();
+		const viewport = fitAllViewport({
+			bounds: view.bounds,
+			nodes: view.current.map((node) => ({
+				x: node.position.x,
+				y: node.position.y,
+				width: node.width ?? 0,
+				height: node.height ?? 0
+			})),
+			width: view.width,
+			height: view.height,
+			legend: box && legend ? {
+				right: legend.right - box.left + 8,
+				bottom: legend.bottom - box.top + 8
+			} : void 0
+		});
+		view.flow.setViewport(viewport);
+	}, []);
+	const nudgeToSelection = useCallback((duration) => {
+		const container = containerRef.current;
+		const width = container?.clientWidth ?? 0;
+		const height = container?.clientHeight ?? 0;
+		const { nodes: current, selectedPageId: selected, centerId: centre, reactFlow: flow } = fitState.current;
+		const anchor = current.find((node) => node.id === (selected ?? centre));
+		if (!anchor || width === 0 || height === 0) return;
+		const view = flow.getViewport();
+		const dx = nudgeAxis(anchor.position.x * view.zoom + view.x, (anchor.width ?? 0) * view.zoom, width);
+		const dy = nudgeAxis(anchor.position.y * view.zoom + view.y, (anchor.height ?? 0) * view.zoom, height);
+		if (dx === 0 && dy === 0) return;
+		flow.setViewport({
+			zoom: view.zoom,
+			x: view.x + dx,
+			y: view.y + dy
+		}, duration ? { duration } : void 0);
 	}, []);
 	useEffect(() => {
 		const container = containerRef.current;
@@ -492,10 +1351,12 @@ function KnowledgePageGraphInner({ pages, edges, pinnedIds = [], grants, selecte
 			height: container.clientHeight
 		};
 		let frame;
+		let needsFit = false;
 		const observer = new ResizeObserver(([entry]) => {
 			if (!entry) return;
 			const { width, height } = entry.contentRect;
 			const changed = width !== last.width || height !== last.height;
+			if (last.width === 0 || last.height === 0) needsFit = true;
 			last = {
 				width,
 				height
@@ -504,7 +1365,10 @@ function KnowledgePageGraphInner({ pages, edges, pinnedIds = [], grants, selecte
 			if (frame !== void 0) cancelAnimationFrame(frame);
 			frame = requestAnimationFrame(() => {
 				frame = void 0;
-				fit(true);
+				if (needsFit || fitPending.current) {
+					needsFit = false;
+					fitInitial();
+				} else nudgeToSelection();
 			});
 		});
 		observer.observe(container);
@@ -512,33 +1376,51 @@ function KnowledgePageGraphInner({ pages, edges, pinnedIds = [], grants, selecte
 			observer.disconnect();
 			if (frame !== void 0) cancelAnimationFrame(frame);
 		};
-	}, [hasNodes, fit]);
+	}, [
+		hasNodes,
+		fitInitial,
+		nudgeToSelection
+	]);
 	const selectedHere = useRef(null);
 	const selectedIsLoaded = !!selectedPageId && pagesById.has(selectedPageId);
 	const initialized = useRef(false);
+	const settleUntil = useRef(0);
+	const settledOn = useRef(null);
+	const fittedLayout = useRef("");
+	const stopSettling = useCallback(() => {
+		settleUntil.current = 0;
+	}, []);
+	useEffect(() => {
+		if (!initialized.current) return;
+		if ((selectedPageId ?? null) !== settledOn.current) settleUntil.current = 0;
+		if (Date.now() >= settleUntil.current) return;
+		const layout = nodes.map((node) => `${node.id}@${node.position.x},${node.position.y}`).join("|");
+		if (layout === fittedLayout.current) return;
+		fittedLayout.current = layout;
+		fitInitial();
+	}, [
+		nodes,
+		selectedPageId,
+		fitInitial
+	]);
 	useEffect(() => {
 		if (!initialized.current || !selectedIsLoaded || !selectedPageId) return;
 		const fromGraph = selectedHere.current === selectedPageId;
 		selectedHere.current = null;
 		if (fromGraph) return;
-		fit(true, 300);
+		nudgeToSelection(fitDuration(prefersMotion()));
 	}, [
 		selectedPageId,
 		selectedIsLoaded,
-		fit
+		nudgeToSelection
 	]);
 	const activate = (page) => {
+		if (isChildPlaceholder(page) || isScopeGroup(page) || isRestCircle(page)) return onSelect(page);
 		if (page.id === selectedPageId && onOpen) return onOpen(page);
 		selectedHere.current = page.id;
 		onSelect(page);
 	};
 	const pressedAt = useRef(null);
-	const onPaneClick = (event) => {
-		const start = pressedAt.current;
-		pressedAt.current = null;
-		if (start && Math.hypot(event.clientX - start.x, event.clientY - start.y) > CLICK_SLOP_PX) return;
-		onClearSelection?.();
-	};
 	const onKeyDown = (event) => {
 		if (event.key !== "Enter" && event.key !== " ") return;
 		const id = event.target.closest(".react-flow__node")?.dataset.id;
@@ -547,6 +1429,56 @@ function KnowledgePageGraphInner({ pages, edges, pinnedIds = [], grants, selecte
 		event.preventDefault();
 		activate(page);
 	};
+	const latest = useRef({
+		activate,
+		onPreview,
+		onMentionSelect,
+		onClearSelection,
+		laidOut,
+		pagesById
+	});
+	latest.current = {
+		activate,
+		onPreview,
+		onMentionSelect,
+		onClearSelection,
+		laidOut,
+		pagesById
+	};
+	const onNodeMouseEnter = useCallback((_, node) => {
+		setHoveredId(node.id);
+		if (latest.current.laidOut.shape.form.get(node.id) === "dot") latest.current.onPreview?.(node.data.page);
+	}, []);
+	const onNodeMouseLeave = useCallback(() => setHoveredId(null), []);
+	const onNodeClick = useCallback((_, node) => {
+		if (!isPlaceholder(node.data.page)) latest.current.activate(node.data.page);
+	}, []);
+	const onEdgeClick = useCallback((event, edge) => {
+		const { onMentionSelect, pagesById } = latest.current;
+		if (edge.data?.kind !== "mention" || !onMentionSelect) return;
+		const source = pagesById.get(edge.source);
+		const target = pagesById.get(edge.target);
+		if (!source || !target) return;
+		const box = containerRef.current?.getBoundingClientRect();
+		onMentionSelect({
+			source,
+			target,
+			point: {
+				x: event.clientX - (box?.left ?? 0),
+				y: event.clientY - (box?.top ?? 0)
+			},
+			pane: {
+				width: box?.width ?? 0,
+				height: box?.height ?? 0
+			}
+		});
+	}, []);
+	const onPaneClick = useCallback((event) => {
+		const start = pressedAt.current;
+		pressedAt.current = null;
+		if (start && Math.hypot(event.clientX - start.x, event.clientY - start.y) > CLICK_SLOP_PX) return;
+		latest.current.onClearSelection?.();
+	}, []);
 	if (!hasNodes) return /* @__PURE__ */ jsx("div", {
 		className: "flex h-full items-center justify-center p-6",
 		children: /* @__PURE__ */ jsx(Txt, {
@@ -557,51 +1489,47 @@ function KnowledgePageGraphInner({ pages, edges, pinnedIds = [], grants, selecte
 	});
 	return /* @__PURE__ */ jsxs("div", {
 		ref: containerRef,
-		className: "relative size-full",
+		className: "knowledge-graph relative size-full",
+		"data-emphasis": neighbours ? "on" : void 0,
 		"data-testid": "knowledge-page-graph",
 		onKeyDown,
+		onWheelCapture: stopSettling,
 		onPointerDownCapture: (event) => {
+			stopSettling();
 			pressedAt.current = {
 				x: event.clientX,
 				y: event.clientY
 			};
 		},
-		children: [/* @__PURE__ */ jsx(GraphLegend, { grants: allEdges.some((edge) => edge.kind === "grant") }), /* @__PURE__ */ jsxs(ReactFlow, {
-			nodes,
-			edges: flowEdges,
+		children: [/* @__PURE__ */ jsx(GraphLegend, {
+			branches: dotBranches,
+			levels: drawnLevels,
+			focused: !!selectedPageId && laidOut.positions.has(selectedPageId),
+			dots: [...laidOut.shape.form.values()].includes("dot"),
+			linkEnds: laidOut.shape.linked.size > 0,
+			drawn: drawnEdgeStyles,
+			counts: [...hiddenLinks ?? []].some(([id, hidden]) => laidOut.shape.form.get(id) === "full" && (hidden.in > 0 || hidden.out > 0))
+		}), /* @__PURE__ */ jsxs(ReactFlow, {
+			nodes: drawnNodes,
+			edges: emphasisedEdges,
 			nodeTypes,
 			edgeTypes,
 			onInit: () => {
 				initialized.current = true;
-				fit(true);
+				settleUntil.current = Date.now() + INITIAL_SETTLE_MS;
+				settledOn.current = fitState.current.selectedPageId ?? null;
+				fittedLayout.current = fitState.current.nodes.map((node) => `${node.id}@${node.position.x},${node.position.y}`).join("|");
+				fitInitial();
 			},
 			minZoom: .1,
 			proOptions: { hideAttribution: true },
 			nodesConnectable: false,
 			nodesDraggable: false,
 			onPaneClick,
-			onNodeClick: (_, node) => {
-				if (!isPlaceholder(node.data.page)) activate(node.data.page);
-			},
-			onEdgeClick: (event, edge) => {
-				if (edge.data?.kind !== "mention" || !onMentionSelect) return;
-				const source = pagesById.get(edge.source);
-				const target = pagesById.get(edge.target);
-				if (!source || !target) return;
-				const box = containerRef.current?.getBoundingClientRect();
-				onMentionSelect({
-					source,
-					target,
-					point: {
-						x: event.clientX - (box?.left ?? 0),
-						y: event.clientY - (box?.top ?? 0)
-					},
-					pane: {
-						width: box?.width ?? 0,
-						height: box?.height ?? 0
-					}
-				});
-			},
+			onNodeMouseEnter,
+			onNodeMouseLeave,
+			onNodeClick,
+			onEdgeClick,
 			children: [/* @__PURE__ */ jsx(Background, {
 				variant: BackgroundVariant.Dots,
 				gap: 26,
@@ -611,7 +1539,7 @@ function KnowledgePageGraphInner({ pages, edges, pinnedIds = [], grants, selecte
 				showInteractive: false,
 				showFitView: false,
 				children: /* @__PURE__ */ jsx(ControlButton, {
-					onClick: () => fit(false, 300),
+					onClick: () => fit(fitDuration(prefersMotion())),
 					title: "Fit view",
 					"aria-label": "Fit view",
 					children: /* @__PURE__ */ jsx(Maximize, { "aria-hidden": true })