pi-weave 0.1.21 → 0.1.23

package/src/web/client/graph/Graph.tsx

@@ -42,6 +42,7 @@ import {
   graphClick,
   graphColumnModel,
   graphCountLabel,
+  hoverHighlight,
 } from "./column.model";
 import type { PositionStorage } from "./positions";
 import type { GraphRenderer, RendererFactory } from "./renderer";
@@ -181,6 +182,20 @@ export function Graph(props: GraphProps) {
       setState(next.state);
       live.current.onSelect(next.selectedId);
     });
+    // Hover drives the *same* reducers a click does (§7.4): the pointer and
+    // the selection ask one question, and `hoverHighlight` answers it with the
+    // selection's own picture the moment the pointer leaves.
+    //
+    // Straight to the renderer, deliberately not through `useState`: hover
+    // state would enter the `model` memo below and re-derive the layout,
+    // the group colours and the whole `RenderGraph` on every pointer move.
+    instance.onHover((id) => {
+      const { model: current, selectedId } = live.current;
+      // The *drawn* edges, which are exactly the visible ones the column's own
+      // highlight was computed over — a neighbour inside a collapsed cluster
+      // has already been retargeted onto the cluster standing in for it.
+      instance.setHighlight(hoverHighlight(current.graph.edges, id, current.highlight), id ?? selectedId);
+    });
     instance.onDragStart((id) => {
       const at = renderer.current?.positions().get(id);
       if (at) {

package/src/web/client/graph/column.model.ts

@@ -41,8 +41,8 @@
 
 import type { Point } from "../../shared/layout";
 import type { ClusterAggregate, ClusterInfo, ViewGraphModel } from "../../shared/view";
-import { clusterAggregate, degreeOf, focusNeighborhood } from "../../shared/view";
-import type { GraphPayload, WireGraphEdge, WireGraphNode } from "../../shared/wire";
+import { clusterAggregate, focusNeighborhood } from "../../shared/view";
+import type { GraphPayload, WireGraphEdge } from "../../shared/wire";
 import { viewModel } from "../tree/tree.model";
 import type { ColorScheme, RenderGraph } from "./graph.model";
 import { EMPTY_RENDER_GRAPH, renderGraph } from "./graph.model";
@@ -52,6 +52,20 @@ import { resolveLayout } from "./positions";
 
 // --- the view state ------------------------------------------------------------------
 
+/**
+ * The canvas draws whatever the user has expanded — there is no note cap.
+ *
+ * Clustering is the bound: a collapsed folder is one node standing in for its
+ * whole subtree, and `initialGraphView` opens the roots rather than the tree,
+ * so the default frame stays small at any vault size. A bound on the payload
+ * instead would decide visibility by a note's position in the list, which is
+ * unrelated to what the user is looking at and hides notes inside folders
+ * they explicitly opened.
+ *
+ * If a vault ever does overwhelm the layout, bound the *expansion* (how much
+ * one expand reveals) or the simulation itself.
+ */
+
 /** The graph column's state. Owned by the column; never on the context bus. */
 export interface GraphViewState {
   /**
@@ -151,6 +165,31 @@ export function highlightFor(edges: readonly WireGraphEdge[], selectedId: string
   return focusNeighborhood(selectedId, edges);
 }
 
+/**
+ * The highlight while the pointer is over a node — **hover wins, selection is
+ * what it falls back to**.
+ *
+ * Obsidian's gesture, and the reason it is the same function as
+ * {@link highlightFor} rather than a second visual language: hovering asks
+ * exactly the question clicking asks ("what is one hop from here?"), so the
+ * two must produce the same set and reach the same reducers. Anything else
+ * drifts into a graph where the pointer and the click disagree about what
+ * "related" means.
+ *
+ * `fallback` is the selection's highlight, precomputed by the column — passed
+ * rather than recomputed so leaving a node restores the selection's picture
+ * without the caller having to remember what it was. `null` hovered and
+ * `null` fallback is nothing selected and nothing hovered, which the reducers
+ * read as "render everything normally".
+ */
+export function hoverHighlight(
+  edges: readonly WireGraphEdge[],
+  hoveredId: string | null,
+  fallback: Set<string> | null,
+): Set<string> | null {
+  return hoveredId === null ? fallback : focusNeighborhood(hoveredId, edges);
+}
+
 // --- the control strip (§1.2) ---------------------------------------------------------------
 
 /** The `[fit]` control. Constant, but named here so the component holds no copy. */
@@ -340,38 +379,15 @@ export function graphClick(state: GraphViewState, clusters: ReadonlyMap<string,
   return { state: toggleCluster(state, id), selectedId: id };
 }
 
-// --- tooltips ---------------------------------------------------------------------------------
-
-/**
- * What a node says when it stands in for a collapsed subtree.
- *
- * `ClusterInfo.members` is exactly the hidden descendants this cluster is
- * currently representing — not `descendants`, which overlaps freely between a
- * cluster and its ancestors and would report the same file under both
- * `src/core` and `repository`. `members` partitions the hidden set across the
- * visible clusters, so the counts add up to the number of nodes that are not
- * on screen.
- */
-export function clusterBadge(cluster: ClusterInfo | undefined): string | null {
-  if (cluster === undefined || cluster.members.length === 0) return null;
-  return cluster.members.length === 1 ? "1 hidden" : `${cluster.members.length} hidden`;
-}
-
-/**
- * A node's hover text: its label, its degree, and what it is standing in for.
- *
- * `degreeOf` is core's, reached through the §2.1.1 door. The bulk `degrees`
- * pass in `graph.model.ts` is a different algorithm for a different question
- * (every node at once, O(edges)); this is one node, which is what a tooltip
- * asks.
+/*
+ * There were two tooltip builders here — `nodeTooltip` (label · N links · N
+ * hidden) and `clusterBadge`. Nothing ever rendered either one; they were the
+ * remains of a hover pass that never reached the canvas, and the hover
+ * gesture now answers the same question by *lighting the neighbourhood* and
+ * floating the node's own name (see `graph.model.ts`'s `drawHoverLabel`),
+ * which says "N links" by showing them. Deleted rather than left as covered
+ * dead code.
  */
-export function nodeTooltip(node: WireGraphNode, edges: readonly WireGraphEdge[], cluster: ClusterInfo | undefined): string {
-  const degree = degreeOf(node.id, edges);
-  const parts = [node.label, degree === 1 ? "1 link" : `${degree} links`];
-  const badge = clusterBadge(cluster);
-  if (badge !== null) parts.push(badge);
-  return parts.join(" · ");
-}
 
 /** Positions keyed by id, for a caller warm-starting a re-run. */
 export type LayoutSnapshot = ReadonlyMap<string, Point>;

package/src/web/client/graph/graph.model.ts

@@ -373,6 +373,113 @@ export function nodeLabel(node: WireGraphNode): string {
   return truncateLabel(badge === "" ? label : `${badge} ${label}`);
 }
 
+// --- the hover label (§7.4) ---------------------------------------------------------
+
+/**
+ * The 2D canvas slice {@link hoverLabelPainter} writes to.
+ *
+ * Structural for the same reason `RenderContainer` is (see `renderer.ts`): a
+ * test importing this module drags it into the root `tsconfig.json` project,
+ * which has no `DOM` lib, so naming `CanvasRenderingContext2D` here would
+ * break the typecheck for every core test. Every member is used below, so the
+ * port cannot grow something nothing calls — and because it is a plain
+ * object shape, the painter is covered by an ordinary unit test against a
+ * recording fake rather than sitting behind §10's canvas wall.
+ */
+export interface HoverLabelContext {
+  font: string;
+  /**
+   * `unknown` rather than `string`, and only because the real thing is
+   * `string | CanvasGradient | CanvasPattern` — naming either of those DOM
+   * types here is what this port exists to avoid, and narrowing to `string`
+   * makes `CanvasRenderingContext2D` fail to satisfy the port. Written to, never
+   * read, so nothing downstream has to widen.
+   */
+  fillStyle: unknown;
+  textAlign: string;
+  shadowColor: string;
+  shadowBlur: number;
+  save(): void;
+  restore(): void;
+  fillText(text: string, x: number, y: number): void;
+}
+
+/** The node attributes sigma hands a hover painter, narrowed to what is read. */
+export interface HoverLabelNode {
+  readonly x: number;
+  readonly y: number;
+  readonly size: number;
+  readonly label: string | null;
+}
+
+/** The settings a hover painter reads. Both `GraphSettings` and sigma's satisfy it. */
+export interface HoverLabelSettings {
+  readonly labelSize: number;
+  readonly labelFont: string;
+}
+
+/**
+ * The gap between the bottom of the node and the cap height of its name, in
+ * screen pixels.
+ *
+ * Far enough that the text is not touching the disc at the sizes the ramp
+ * produces (leaf 6 → hub 18 layout units), close enough that the name still
+ * reads as belonging to *that* node rather than floating between two of them.
+ */
+export const HOVER_LABEL_GAP = 6;
+
+/**
+ * How far the hover label's shadow spreads, in pixels.
+ *
+ * Not decoration — legibility. The label is drawn over whatever the graph
+ * happens to have under the node (edges, a receded cloud, another label), and
+ * a ground-coloured blur is what separates the glyphs from that without
+ * putting an opaque box on the canvas. Sigma's own `drawDiscNodeHover` draws
+ * the box instead, hardcoded `#FFF`, which is why it is replaced rather than
+ * configured.
+ */
+export const HOVER_LABEL_SHADOW = 6;
+
+/**
+ * Sigma's `defaultDrawNodeHover`, as a scheme-bound pure function (§7.4).
+ *
+ * Obsidian's gesture, which is the reference: the hovered node's name floats
+ * **centred underneath it**, in the theme's own text colour, with no
+ * container. The alternative shipped by sigma is a white rounded box with the
+ * text to the node's *right* — wrong colour in both schemes, and wrong place
+ * when the neighbourhood highlight has just grown the node the label is
+ * naming.
+ *
+ * Being the hover painter also fixes a second thing for free: sigma draws this
+ * regardless of `labelRenderedSizeThreshold`, so a leaf too small to carry a
+ * standing label still answers the pointer with its name.
+ *
+ * `save`/`restore` around the whole thing because `textAlign`, the shadow and
+ * the fill are shared canvas state — sigma reuses the same context for every
+ * other label in the frame, and a leaked `textAlign: "center"` would silently
+ * re-align them all.
+ */
+export function hoverLabelPainter(
+  scheme: ColorScheme,
+): (context: HoverLabelContext, data: HoverLabelNode, settings: HoverLabelSettings) => void {
+  return (context, data, settings) => {
+    // `nodeReducer` blanks the label of everything outside the highlight, and
+    // a node with no name has nothing to float.
+    if (data.label === null || data.label === "") return;
+    const palette = GRAPH_PALETTE[scheme];
+    context.save();
+    context.font = `${settings.labelSize}px ${settings.labelFont}`;
+    context.textAlign = "center";
+    context.shadowColor = palette.ground;
+    context.shadowBlur = HOVER_LABEL_SHADOW;
+    context.fillStyle = palette.text;
+    // `data.size` is already the *scaled* radius sigma is about to draw, so the
+    // baseline clears the disc at every zoom rather than at one of them.
+    context.fillText(data.label, data.x, data.y + data.size + settings.labelSize + HOVER_LABEL_GAP);
+    context.restore();
+  };
+}
+
 // --- the render model -------------------------------------------------------------
 
 /** A node, resolved to everything the projection needs. No decisions left. */
@@ -632,14 +739,23 @@ export function nodeReducer(
    * only a neighbourhood keeps the previous two-tier behaviour.
    */
   selectedId?: string | null,
+  /**
+   * How far the highlight has faded in, 0 → 1. Defaults to 1, so a caller
+   * that does not animate gets the finished picture and nothing has to know
+   * about the clock.
+   */
+  progress: number = 1,
 ): (id: string, data: RenderNode, scheme: ColorScheme) => NodeDisplayOverride {
   return (id, data, scheme) => {
-    if (highlight === null) return {};
+    // `progress` at zero is indistinguishable from no highlight, and saying so
+    // here is what lets the fade end by *returning* to the unhighlighted graph
+    // rather than by approaching it.
+    if (highlight === null || progress <= 0) return {};
     if (id === selectedId && highlight.has(id)) {
       // The subject of the gesture: lifted clear of its own neighbourhood and
       // grown by a ratio rather than to a fixed radius, so a hub still reads
       // as bigger than the leaf beside it while both read as "this one".
-      return { zIndex: data.zIndex + HIGHLIGHT_Z_LIFT * 2, size: data.size * SELECTED_GROWTH };
+      return { zIndex: data.zIndex + HIGHLIGHT_Z_LIFT * 2, size: data.size * growth(SELECTED_GROWTH, progress) };
     }
     // A connected node: its own group colour at full strength, lifted above
     // the cloud, and grown a little. The step between "connected" and
@@ -648,11 +764,81 @@ export function nodeReducer(
     // being named — the difference matters most on a big canvas, where the
     // receded cloud is far off-screen and the only thing visible is a
     // neighbourhood that looks exactly like it did before the click.
-    if (highlight.has(id)) return { zIndex: data.zIndex + HIGHLIGHT_Z_LIFT, size: data.size * NEIGHBOUR_GROWTH };
-    return { color: recessColor(data.color, scheme), label: null, zIndex: 0 };
+    if (highlight.has(id)) return { zIndex: data.zIndex + HIGHLIGHT_Z_LIFT, size: data.size * growth(NEIGHBOUR_GROWTH, progress) };
+    return {
+      color: recessColor(data.color, scheme, RECESS_STRENGTH * progress),
+      label: progress >= LABEL_DROP_AT ? null : data.label,
+      zIndex: 0,
+    };
   };
 }
 
+// --- the highlight fade (§7.4) -----------------------------------------------------
+
+/**
+ * The time constant of the highlight fade, in milliseconds.
+ *
+ * The highlight used to arrive and leave in **one frame**, and the frame that
+ * hurt was the *leaving* one: 85 % of the canvas snapping from recessed back
+ * to full contrast reads as the whole graph flashing, which is louder than
+ * the dimming it is undoing. Sliding the recession in and out is what turns
+ * two states into one gesture.
+ *
+ * A time *constant* rather than a duration because {@link fadeStep} is an
+ * exponential approach, not a linear ramp — progress covers 63 % of the
+ * remaining distance every `TAU` ms, so the motion is ease-out by
+ * construction with no easing curve to pick, and it is frame-rate independent
+ * for free. 60 ms puts the visible settle at roughly 200 ms, which is the
+ * range a hover can afford: slower and pointing at a node feels unanswered.
+ */
+export const HIGHLIGHT_FADE_TAU = 60;
+
+/**
+ * How close to the target counts as arrived.
+ *
+ * An exponential approach never actually lands, so without a snap the clock
+ * would run forever repainting changes below a rounding error. At 0.004 the
+ * remaining recession is under half a colour step on an 8-bit channel —
+ * invisible, and about five time constants in.
+ */
+export const FADE_EPSILON = 0.004;
+
+/**
+ * Advance a fade toward its target. Pure; the clock is the caller's.
+ *
+ * `progress` is how *present* the highlight is: 0 renders exactly as no
+ * highlight at all, 1 is the full treatment. The target is therefore always
+ * one of those two — what fades is the presence of the effect, never the
+ * membership of the set. A neighbourhood that changes while the highlight is
+ * already up (hover moves from one node to the next) swaps instantly and
+ * stays at 1, because a cross-fade between two neighbourhoods is a picture of
+ * neither.
+ *
+ * A backgrounded tab hands back a multi-second `elapsedMs`, and the
+ * exponential handles it correctly by arriving: `exp(-big)` is 0.
+ */
+export function fadeStep(progress: number, target: number, elapsedMs: number): number {
+  const elapsed = Number.isFinite(elapsedMs) && elapsedMs > 0 ? elapsedMs : 0;
+  const next = target + (progress - target) * Math.exp(-elapsed / HIGHLIGHT_FADE_TAU);
+  return Math.abs(target - next) < FADE_EPSILON ? target : next;
+}
+
+/** Interpolate a size multiplier by the fade's progress. 0 → untouched, 1 → `to`. */
+function growth(to: number, progress: number): number {
+  return 1 + (to - 1) * progress;
+}
+
+/**
+ * The fade point at which the cloud's labels are dropped.
+ *
+ * Text is the one thing on this canvas that cannot fade — sigma draws labels
+ * opaque, and there is no per-label alpha to ramp. So the drop is a step, and
+ * the least visible place to put a step is the middle of the fade, where the
+ * cloud is already half receded and the eye is following the neighbourhood
+ * rather than the text it is losing.
+ */
+export const LABEL_DROP_AT = 0.5;
+
 /**
  * How much the selected node grows, as a size multiplier.
  *
@@ -698,11 +884,13 @@ export function edgeReducer(
   highlight: ReadonlySet<string> | null,
   /** The selection, so an edge *touching* it outranks one merely near it. */
   selectedId?: string | null,
+  /** The fade's progress — see {@link nodeReducer}'s. */
+  progress: number = 1,
 ): (key: string, data: RenderEdge, scheme: ColorScheme) => EdgeDisplayOverride {
   return (_key, data, scheme) => {
-    if (highlight === null) return {};
+    if (highlight === null || progress <= 0) return {};
     if (!highlight.has(data.source) || !highlight.has(data.target)) {
-      return { color: recessColor(data.color, scheme) };
+      return { color: recessColor(data.color, scheme, RECESS_STRENGTH * progress) };
     }
     // Incident on the selection itself — these are the node's actual links,
     // and they are what "connected" means drawn. Painted in the accent so a
@@ -710,11 +898,17 @@ export function edgeReducer(
     // for as long as the selection stands, and thickened a step beyond the
     // neighbourhood's own edges.
     if (selectedId != null && (data.source === selectedId || data.target === selectedId)) {
-      return { zIndex: 2, size: data.size * EDGE_PRESENCE * 1.35, color: GRAPH_PALETTE[scheme].accent };
+      return {
+        zIndex: 2,
+        size: data.size * growth(EDGE_PRESENCE * 1.35, progress),
+        // Blended rather than switched, so the link arrives *as* the accent
+        // instead of flicking to it a frame before the rest of the fade.
+        color: blendHex(data.color, GRAPH_PALETTE[scheme].accent, progress),
+      };
     }
     // Between two neighbours, but not touching the selection: real context,
     // one step quieter.
-    return { zIndex: 1, size: data.size * EDGE_PRESENCE };
+    return { zIndex: 1, size: data.size * growth(EDGE_PRESENCE, progress) };
   };
 }
 
@@ -747,6 +941,8 @@ export interface GraphSettings {
   readonly zoomToSizeRatioFunction: (ratio: number) => number;
   readonly stagePadding: number;
   readonly allowInvalidContainer: boolean;
+  /** Ours, not sigma's white box — see {@link hoverLabelPainter}. */
+  readonly defaultDrawNodeHover: (context: HoverLabelContext, data: HoverLabelNode, settings: HoverLabelSettings) => void;
 }
 
 /**
@@ -809,6 +1005,7 @@ export function graphSettings(scheme: ColorScheme): GraphSettings {
     itemSizesReference: "positions",
     zoomToSizeRatioFunction: (ratio) => ratio,
     stagePadding: COLLIDE_RADIUS,
+    defaultDrawNodeHover: hoverLabelPainter(scheme),
     // The container is a real element by construction (the renderer is mounted
     // from a `ref`), but sigma also validates that it has a non-zero size —
     // and a column that is behind a `medium` breakpoint toggle legitimately

package/src/web/client/graph/groups.ts

@@ -7,10 +7,10 @@
  * `FORCES` pulls apart: a **depth-1 containment branch**.
  *
  * ```text
- * vault                      ← a root: its own group
- * ├── vfolder:sessions       ← group A, with all 323 descendants
- * ├── vfolder:manager-digest ← group B, with all 159
- * └── note:loose             ← no branch of its own: joins the root's group
+ * vault                   ← a root: its own group
+ * ├── vfolder:projects    ← group A, with all its descendants
+ * ├── vfolder:archive     ← group B, with all of its own
+ * └── note:loose          ← no branch of its own: joins the root's group
  * ```
  *
  * Depth 1 exactly, for the reason the retired `bigBranches` used it: deeper

package/src/web/client/graph/renderer.dom.ts

@@ -2,7 +2,7 @@
 import Sigma from "sigma";
 import type { ColorScheme } from "./graph.model";
 import type { GraphRenderer, RendererFactory, SigmaLike } from "./renderer";
-import { sigmaRenderer } from "./renderer";
+import { rafClock, sigmaRenderer } from "./renderer";
 
 /** Sigma's own container parameter type, recovered without naming the DOM. */
 type SigmaContainer = ConstructorParameters<typeof Sigma>[1];
@@ -13,4 +13,8 @@ export const createSigmaRenderer: RendererFactory = (scheme: ColorScheme): Graph
     (graph, container, settings) =>
       new Sigma(graph, container as unknown as SigmaContainer, settings) as unknown as SigmaLike,
     scheme,
+    // The highlight fade's clock. `window` is named here rather than in
+    // `renderer.ts` for the same reason `new Sigma` is: that module must stay
+    // compilable without a `DOM` lib.
+    rafClock(window),
   );

package/src/web/client/graph/renderer.ts

@@ -1,6 +1,6 @@
 import type { Point } from "../../shared/layout";
 import type { ColorScheme, EdgeDisplayOverride, GraphSettings, NodeDisplayOverride, RenderEdge, RenderGraph, RenderNode, ViewBox } from "./graph.model";
-import { edgeReducer, frameBox, graphSettings, nodeReducer } from "./graph.model";
+import { edgeReducer, fadeStep, frameBox, graphSettings, nodeReducer } from "./graph.model";
 import type { ProjectedGraph } from "./project";
 import { positionsOf, project, syncPositions } from "./project";
 
@@ -46,6 +46,8 @@ export interface SigmaLike {
   on(event: "clickNode", handler: (payload: { node: string }) => void): unknown;
   on(event: "clickStage", handler: () => void): unknown;
   on(event: "downNode", handler: (payload: { node: string }) => void): unknown;
+  on(event: "enterNode", handler: (payload: { node: string }) => void): unknown;
+  on(event: "leaveNode", handler: () => void): unknown;
   on(event: "moveBody", handler: (payload: { event: { x: number; y: number }; preventSigmaDefault(): void }) => void): unknown;
   on(event: "upNode" | "upStage", handler: () => void): unknown;
   viewportToGraph(position: { x: number; y: number }): Point;
@@ -83,16 +85,63 @@ export interface SigmaLike {
  * every node colour and re-projecting — a second code path for a case nobody
  * hits.
  */
+/**
+ * The animation clock, as a port.
+ *
+ * `requestAnimationFrame` and `performance.now` are browser globals, and this
+ * module is compiled by the root `tsconfig.json` (no `DOM` lib) whenever a
+ * test imports it — the same constraint `RenderContainer` exists for. Injected
+ * rather than imported, so the fade's *timing* is driven by a fake in a test
+ * and by the browser in the browser, and the whole ramp is ordinary covered
+ * code instead of frames nobody can step.
+ */
+export interface FrameClock {
+  now(): number;
+  request(step: () => void): number;
+  cancel(handle: number): void;
+}
+
+/** The browser's clock. The one place the two globals are named. */
+export const rafClock = (host: {
+  requestAnimationFrame(cb: (t: number) => void): number;
+  cancelAnimationFrame(h: number): void;
+  performance: { now(): number };
+}): FrameClock => ({
+  now: () => host.performance.now(),
+  request: (step) => host.requestAnimationFrame(() => step()),
+  cancel: (handle) => host.cancelAnimationFrame(handle),
+});
+
 export function sigmaRenderer(
   create: (graph: ProjectedGraph, container: RenderContainer, settings: GraphSettings) => SigmaLike,
   scheme: ColorScheme,
+  /**
+   * The fade clock, or omitted for no animation at all — in which case every
+   * highlight change lands at full strength on the next frame, which is the
+   * behaviour before the fade existed.
+   */
+  clock?: FrameClock,
 ) {
   let sigma: SigmaLike | null = null;
   let graph: ProjectedGraph = project({ nodes: [], edges: [] });
   let highlight: ReadonlySet<string> | null = null;
   /** The selection inside that neighbourhood — see `nodeReducer`. */
   let selected: string | null = null;
+  /**
+   * How present the highlight currently *looks*, and where it is heading.
+   *
+   * Two numbers rather than one because the fade has to survive its own end:
+   * clearing `highlight` the instant the pointer leaves would leave nothing
+   * to fade *out of*, which is exactly the flash the fade exists to remove.
+   * So a clear sets `fadeTo = 0` and keeps the outgoing set on screen until
+   * the ramp reaches it — see `setHighlight`.
+   */
+  let fade = 0;
+  let fadeTo = 0;
+  let frame: number | null = null;
+  let lastAt = 0;
   let select: (id: string | null) => void = () => {};
+  let hover: (id: string | null) => void = () => {};
   let dragStart: (id: string) => void = () => {};
   let dragMove: (id: string, at: Point) => void = () => {};
   let dragEnd: (id: string) => void = () => {};
@@ -121,12 +170,38 @@ export function sigmaRenderer(
    * until the next unrelated frame.
    */
   const applyReducers = (instance: SigmaLike): void => {
-    const nodes = nodeReducer(highlight, selected);
-    const edges = edgeReducer(highlight, selected);
+    const nodes = nodeReducer(highlight, selected, fade);
+    const edges = edgeReducer(highlight, selected, fade);
     instance.setSetting("nodeReducer", (id, data) => ({ ...data, ...nodes(id, data, scheme) }));
     instance.setSetting("edgeReducer", (key, data) => ({ ...data, ...edges(key, data, scheme) }));
   };
 
+  /**
+   * Run the fade toward `fadeTo`, one frame at a time. Idempotent — the same
+   * self-terminating-clock shape `Graph.tsx` uses for the simulation, and for
+   * the same reason: a graph that has finished moving must cost zero frames.
+   */
+  const armFade = (): void => {
+    if (clock === undefined || frame !== null) return;
+    lastAt = clock.now();
+    const step = (): void => {
+      frame = null;
+      const at = clock.now();
+      fade = fadeStep(fade, fadeTo, at - lastAt);
+      lastAt = at;
+      if (sigma !== null) applyReducers(sigma);
+      // Arrived at zero: the set was only being held so it had something to
+      // fade out of (see `fade`/`fadeTo`), and keeping it would make a later
+      // unrelated repaint dim the graph with a stale neighbourhood.
+      if (fade === fadeTo) {
+        if (fade === 0) highlight = null;
+        return;
+      }
+      frame = clock.request(step);
+    };
+    frame = clock.request(step);
+  };
+
   return {
     mount(container: RenderContainer) {
       if (sigma !== null) return;
@@ -153,6 +228,12 @@ export function sigmaRenderer(
           dragMove(dragging, instance.viewportToGraph({ x: payload.event.x, y: payload.event.y }));
         }
       });
+      // Hover is reported outward, not interpreted here: which nodes light up
+      // is `column.model.ts`'s `hoverHighlight`, the same way a click's meaning
+      // is `graphClick`'s. Sigma emits `leaveNode` on its own when the pointer
+      // crosses straight from one node to another, so there is no state to keep.
+      instance.on("enterNode", ({ node }) => hover(node));
+      instance.on("leaveNode", () => hover(null));
       instance.on("upNode", () => endDrag(dragging));
       instance.on("upStage", () => endDrag(null));
       applyReducers(instance);
@@ -180,15 +261,40 @@ export function sigmaRenderer(
     },
 
     setHighlight(next: ReadonlySet<string> | null, selectedId: string | null = null) {
-      highlight = next;
-      selected = selectedId;
+      if (clock === undefined) {
+        highlight = next;
+        selected = selectedId;
+        fade = next === null ? 0 : 1;
+        fadeTo = fade;
+        if (sigma !== null) applyReducers(sigma);
+        return;
+      }
+      if (next === null) {
+        // Fade *out of* the set that is on screen rather than dropping it: the
+        // drop is the flash. `highlight` is cleared by the ramp on arrival.
+        fadeTo = 0;
+        // Nothing was showing, so there is nothing to fade and no frame to run.
+        if (highlight === null) return;
+      } else {
+        // A new neighbourhood replaces the old one immediately — a cross-fade
+        // between two of them is a picture of neither — and only the *presence*
+        // of the highlight is animated.
+        highlight = next;
+        selected = selectedId;
+        fadeTo = 1;
+      }
       if (sigma !== null) applyReducers(sigma);
+      if (fade !== fadeTo) armFade();
     },
 
     onSelect(handler: (id: string | null) => void) {
       select = handler;
     },
 
+    onHover(handler: (id: string | null) => void) {
+      hover = handler;
+    },
+
     onDragStart(handler: (id: string) => void) {
       dragStart = handler;
     },
@@ -215,6 +321,10 @@ export function sigmaRenderer(
       return positionsOf(graph);
     },
     destroy() {
+      if (frame !== null) {
+        clock?.cancel(frame);
+        frame = null;
+      }
       sigma?.kill();
       sigma = null;
     },