pi-weave 0.3.9 → 0.3.10

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

@@ -40,9 +40,29 @@ import {
   graphClick,
   graphColumnModel,
   graphCountLabel,
+  graphPicture,
   graphPreview,
-  hoverHighlight,
+  hoverPicture,
 } from "./column.model";
+import {
+  CONNECTED_HEADING,
+  LIT_BECAUSE,
+  SHEET_CLOSE,
+  SHEET_LABEL,
+  SHEET_OPEN,
+  SHEET_OPEN_SPLIT,
+  SPOTLIGHT_CLEAR,
+  SPOTLIGHT_CLEAR_HINT,
+  SPOTLIGHT_LABEL,
+  SPOTLIGHT_LEGEND,
+  SPOTLIGHT_PLACEHOLDER,
+  connectedMore,
+  graphSheet,
+  litLabel,
+  litOnCanvas,
+  spotlightEscapes,
+  spotlightOf,
+} from "./spotlight.model";
 import type { PositionStorage } from "./positions";
 import type { GraphRenderer, RendererFactory } from "./renderer";
 import type { TrailGlow } from "./graph.model";
@@ -95,6 +115,28 @@ export interface GraphProps {
   fit: { current: (() => void) | null };
   /** Recall-trail glows by node id (`trail/trail.model.ts`). Omitted means none. */
   trail?: ReadonlyMap<string, TrailGlow>;
+  /**
+   * The spotlight query (`spotlight.model.ts`), controlled by the shell so
+   * other UI — the search palette's "light up in graph" — can set it.
+   * Omitted or `""` means no spotlight.
+   */
+  query?: string;
+  /**
+   * Node ids the search palette found for `query`, when it lit the graph up.
+   * They light alongside the spotlight's own matches; omitted means none.
+   */
+  found?: readonly string[];
+  /**
+   * Where the spotlight field writes. **Its presence is what makes this the
+   * full graph view**: with it the column shows the floating spotlight field
+   * and the side sheet; without it (the context rail's note graph, a narrow
+   * column) it keeps the compact preview card it always had.
+   */
+  onQuery?: (query: string) => void;
+  /** The sheet's "Open in split". Omitted hides the button. */
+  onOpenSplit?: (id: string) => void;
+  /** The shell's clock, for the sheet's "2h ago". Omitted reads the wall clock. */
+  now?: number;
 }
 
 const NO_GLOWS: ReadonlyMap<string, TrailGlow> = new Map();
@@ -157,13 +199,25 @@ export function Graph(props: GraphProps) {
     () => graphColumnModel(props.graph, props.selectedId, view, props.storage, scheme, props.bootFailed, groupColors),
     [props.graph, props.selectedId, view, props.storage, scheme, props.bootFailed, forceKey, groupColors],
   );
-  const preview = graphPreview(props.graph, props.previewId);
+  // The full graph view has a spotlight and a side sheet; the context rail's
+  // note graph keeps the compact card. See `GraphProps.onQuery`.
+  const full = props.onQuery !== undefined;
+  const query = full ? props.query ?? "" : "";
+  const spot = useMemo(() => spotlightOf(props.graph, query, props.found), [props.graph, query, props.found]);
+  // Same identity contract as `model` above: the highlight effect keys on the
+  // picture's identity, so each step is memoized on exactly what it reads.
+  const lit = useMemo(() => litOnCanvas(spot, model.representative), [spot, model.representative]);
+  const picture = useMemo(() => graphPicture(model.highlight, props.selectedId, lit), [model.highlight, props.selectedId, lit]);
+  const preview = full ? null : graphPreview(props.graph, props.previewId);
+  const now = props.now ?? Date.now();
+  const sheet = useMemo(() => (full ? graphSheet(props.graph, props.previewId, spot, now) : null), [full, props.graph, props.previewId, spot, now]);
+  const field = useRef<HTMLInputElement | null>(null);
 
   // Read by the mount-time `onSelect`, which outlives this render.
   const trailRef = useRef<ReadonlyMap<string, TrailGlow>>(NO_GLOWS);
   trailRef.current = props.trail ?? NO_GLOWS;
-  const live = useRef({ view, model, onSelect: props.onSelect, selectedId: props.selectedId });
-  live.current = { view, model, onSelect: props.onSelect, selectedId: props.selectedId };
+  const live = useRef({ view, model, picture, onSelect: props.onSelect, selectedId: props.selectedId });
+  live.current = { view, model, picture, onSelect: props.onSelect, selectedId: props.selectedId };
 
   useEffect(() => {
     const instance = props.renderer(scheme);
@@ -180,11 +234,13 @@ export function Graph(props: GraphProps) {
     // 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;
+      const { model: current, picture: shown } = 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);
+      // Under a spotlight `hoverPicture` hands the spotlight straight back.
+      const next = hoverPicture(current.graph.edges, id, shown);
+      instance.setHighlight(next.highlight, next.selectedId, next.style);
     });
     instance.onDragStart((id) => {
       const at = renderer.current?.positions().get(id);
@@ -210,7 +266,8 @@ export function Graph(props: GraphProps) {
     // the render this effect was created in), so a remount carries whatever
     // the column is already showing.
     instance.setGraph(live.current.model.graph);
-    instance.setHighlight(live.current.model.highlight, live.current.selectedId);
+    const shown = live.current.picture;
+    instance.setHighlight(shown.highlight, shown.selectedId, shown.style);
     instance.setTrail(trailRef.current);
     props.fit.current = () => instance.fit();
     return () => {
@@ -256,21 +313,93 @@ export function Graph(props: GraphProps) {
   );
 
   useEffect(() => {
-    renderer.current?.setHighlight(model.highlight, props.selectedId);
-  }, [model.highlight, props.selectedId]);
+    renderer.current?.setHighlight(picture.highlight, picture.selectedId, picture.style);
+  }, [picture]);
 
   useEffect(() => {
     renderer.current?.setTrail(trailRef.current);
   }, [props.trail]);
 
+  // `Esc` clears the spotlight before the shell's document listener sees it —
+  // or, when `spotlightEscapes` says no, passes through to "clear selection".
+  const escape = (event: KeyboardEvent): void => {
+    if (event.key !== "Escape" || !spotlightEscapes(query, event.target === field.current, sheet !== null)) return;
+    event.preventDefault();
+    props.onQuery?.("");
+  };
+  const more = sheet === null ? null : connectedMore(sheet.connected.length, sheet.connectedTotal);
+
   return (
-    <div class="weave-graph">
+    <div class="weave-graph" onKeyDown={escape}>
       {/* Same shape as `ContextRail`'s: the *decision* is `graphEmptyMessage`,
           and what is left here is whether to render the paragraph it returned. */}
       {model.empty === null ? null : <p class="weave-graph-empty">{model.empty}</p>}
       {/* `tabIndex={-1}` is the `⌘3` focus target — see `Note.tsx`'s matching
           comment. The tree's target is the rows `<ul>`, which has its own. */}
       <div class="weave-graph-canvas" ref={canvas} role="img" aria-label="Knowledge graph" tabIndex={-1} />
+      {!full ? null : (
+        <div class={`weave-spotlight${spot === null ? "" : " weave-spotlight-on"}`} role="search">
+          <svg class="weave-spotlight-icon" viewBox="0 0 20 20" width={14} height={14} fill="none" stroke="currentColor" stroke-width={1.8} aria-hidden="true">
+            <circle cx="8.5" cy="8.5" r="5.5" />
+            <path d="m13 13 4 4" />
+          </svg>
+          <input ref={field} class="weave-spotlight-input" type="search" value={query} placeholder={SPOTLIGHT_PLACEHOLDER}
+            aria-label={SPOTLIGHT_LABEL} spellcheck={false} autoComplete="off" onInput={(event) => props.onQuery?.(event.currentTarget.value)} />
+          {spot === null ? null : (
+            <>
+              <span class={`weave-spotlight-count${spot.count === 0 ? " weave-spotlight-none" : ""}`} role="status">{litLabel(spot.count)}</span>
+              <button type="button" class="weave-spotlight-clear" title={SPOTLIGHT_CLEAR_HINT} aria-label={SPOTLIGHT_CLEAR_HINT}
+                onClick={() => { props.onQuery?.(""); field.current?.focus(); }}>{SPOTLIGHT_CLEAR}</button>
+            </>
+          )}
+        </div>
+      )}
+      {sheet === null ? null : (
+        <aside class="weave-sheet" aria-label={SHEET_LABEL}>
+          <button type="button" class="weave-sheet-close" aria-label={SHEET_CLOSE} title={SHEET_CLOSE} onClick={() => props.onSelect(null)}>×</button>
+          <p class="weave-sheet-crumb">
+            <Icon name={sheet.crumb === "" ? sheet.icon : "module"} class="weave-icon" />
+            <span>{sheet.crumb === "" ? sheet.kind : sheet.crumb}</span>
+          </p>
+          <h2 class="weave-sheet-title">{sheet.title}</h2>
+          <p class="weave-sheet-meta">
+            {sheet.who === null ? null : <span class={`weave-prov weave-prov-${sheet.who.provenance}`} title={sheet.who.title} aria-hidden="true">{sheet.who.glyph}</span>}
+            <span>{sheet.who === null ? sheet.kind : sheet.who.word}</span>
+            {sheet.when === "" ? null : <span class="weave-sheet-when">· {sheet.when}</span>}
+          </p>
+          {sheet.text === null ? null : (
+            <div class="weave-sheet-text">
+              <span class="weave-sheet-text-head">{sheet.text.heading}</span>
+              {sheet.text.parts.map((part) => (part.hit ? <mark class="weave-sheet-mark">{part.text}</mark> : part.text))}
+            </div>
+          )}
+          {sheet.litBecause === null ? null : (
+            <p class="weave-sheet-why"><span aria-hidden="true">✳</span>{LIT_BECAUSE} {sheet.litBecause}</p>
+          )}
+          {sheet.connectedTotal === 0 ? null : (
+            <section class="weave-sheet-section" aria-label={CONNECTED_HEADING}>
+              <h3 class="weave-sheet-heading">{CONNECTED_HEADING}<span class="weave-sheet-count">{sheet.connectedTotal}</span></h3>
+              <ul class="weave-sheet-rows">
+                {sheet.connected.map((row) => (
+                  <li key={row.id}>
+                    <button type="button" class="weave-sheet-row" title={row.label} aria-label={row.ariaLabel} onClick={() => props.onSelect(row.id)}>
+                      <span class={`weave-sheet-dot${row.lit ? " weave-sheet-dot-lit" : ""}`} aria-hidden="true" />
+                      <span class="weave-sheet-row-label">{row.label}</span>
+                    </button>
+                  </li>
+                ))}
+              </ul>
+              {more === null ? null : <p class="weave-sheet-more">{more}</p>}
+            </section>
+          )}
+          <div class="weave-sheet-actions">
+            <button type="button" class="weave-sheet-open" onClick={() => props.onOpen(sheet.id)}>{SHEET_OPEN}</button>
+            {props.onOpenSplit === undefined ? null : (
+              <button type="button" class="weave-sheet-split" onClick={() => props.onOpenSplit?.(sheet.id)}>{SHEET_OPEN_SPLIT}</button>
+            )}
+          </div>
+        </aside>
+      )}
       {preview === null ? null : (
         <aside class="weave-graph-preview" aria-label="Selected graph node">
           <div class="weave-graph-preview-info">
@@ -290,8 +419,10 @@ export function Graph(props: GraphProps) {
         </button>
         <span class="weave-graph-legend">
           <span class="weave-legend-on">◉ {LEGEND.selected}</span>
-          <span class="weave-legend-near">● {LEGEND.neighborhood}</span>
-          <span class="weave-legend-dim">· {LEGEND.dimmed}</span>
+          {spot === null
+            ? <span class="weave-legend-near">● {LEGEND.neighborhood}</span>
+            : <span class="weave-legend-lit">● {SPOTLIGHT_LEGEND.lit}</span>}
+          <span class="weave-legend-dim">· {spot === null ? LEGEND.dimmed : SPOTLIGHT_LEGEND.dimmed}</span>
         </span>
       </div>
       <p class="weave-graph-count">{graphCountLabel(model.visible, model.total)}</p>

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

@@ -46,7 +46,7 @@ import { clusterAggregate, focusNeighborhood } from "../../shared/view";
 import type { GraphPayload, WireGraphEdge } from "../../shared/wire";
 import { kindIcon, viewModel } from "../tree/tree.model";
 import type { IconName } from "../shell/icons.model";
-import type { RenderGraph } from "./graph.model";
+import type { HighlightStyle, RenderGraph } from "./graph.model";
 import { EMPTY_RENDER_GRAPH, renderGraph } from "./graph.model";
 import { groupNodeColors } from "./groups";
 import type { PositionStorage } from "./positions";
@@ -208,6 +208,55 @@ export function hoverHighlight(
   return hoveredId === null ? fallback : focusNeighborhood(hoveredId, edges);
 }
 
+// --- the picture: neighbourhood or spotlight ------------------------------------------------
+
+/**
+ * What the renderer is told to draw: a set, the node it is about, and which
+ * treatment the set gets (`graph.model.ts`'s {@link HighlightStyle}).
+ *
+ * The three travel together because they are one decision — the renderer's
+ * `setHighlight(highlight, selectedId, style)` takes exactly this, and a
+ * caller that passed them separately could pair a spotlight's set with a
+ * neighbourhood's treatment.
+ */
+export interface GraphPicture {
+  readonly highlight: Set<string> | null;
+  readonly selectedId: string | null;
+  readonly style: HighlightStyle;
+}
+
+/**
+ * The column's picture: **a spotlight wins over the selection's neighbourhood**.
+ *
+ * `lit` is the spotlight's set already mapped onto the canvas
+ * (`spotlight.model.ts`'s `litOnCanvas`), or `null` when no query is set — and
+ * then the picture is the selection's neighbourhood exactly as it was before
+ * the spotlight existed. The selection still rides along under a spotlight,
+ * because the node the side sheet is about has to stand out among the lit ones.
+ */
+export function graphPicture(neighbourhood: Set<string> | null, selectedId: string | null, lit: Set<string> | null): GraphPicture {
+  return lit === null
+    ? { highlight: neighbourhood, selectedId, style: "neighbourhood" }
+    : { highlight: lit, selectedId, style: "spotlight" };
+}
+
+/**
+ * The picture while the pointer is over a node.
+ *
+ * Without a spotlight, {@link hoverHighlight} as ever: hover wins and the
+ * hovered node is the subject. **Under a spotlight the lit set holds** — it is
+ * something the user typed, and moving the pointer across the canvas to reach
+ * a lit node must not keep swapping it for neighbourhoods. Only the subject
+ * moves: the hovered node takes the selection's place while the pointer is on
+ * it, so a faint dot answers with its full colour and its name (a dimmed
+ * node has no label for the hover painter to float), and leaving it hands the
+ * emphasis back to the selection.
+ */
+export function hoverPicture(edges: readonly WireGraphEdge[], hoveredId: string | null, picture: GraphPicture): GraphPicture {
+  if (picture.style === "spotlight") return hoveredId === null ? picture : { ...picture, selectedId: hoveredId };
+  return { highlight: hoverHighlight(edges, hoveredId, picture.highlight), selectedId: hoveredId ?? picture.selectedId, style: "neighbourhood" };
+}
+
 // --- the control strip (§1.2) ---------------------------------------------------------------
 
 /** The `[fit]` control. Constant, but named here so the component holds no copy. */
@@ -269,6 +318,12 @@ export interface GraphColumnModel {
   readonly cached: boolean;
   /** Every cluster in the *unreduced* model — what `[expand]` operates on. */
   readonly clusters: ReadonlyMap<string, ClusterInfo>;
+  /**
+   * Hidden id → the visible cluster standing in for it (`clusterAggregate`'s
+   * mapping), so a set computed over the whole payload — the spotlight's —
+   * can be retargeted onto what is drawn.
+   */
+  readonly representative: ReadonlyMap<string, string>;
   /** Visible / total, for the count line. */
   readonly visible: number;
   readonly total: number;
@@ -283,6 +338,7 @@ export const EMPTY_COLUMN: GraphColumnModel = {
   key: "",
   cached: false,
   clusters: new Map(),
+  representative: new Map(),
   visible: 0,
   total: 0,
   empty: "Loading…",
@@ -351,6 +407,7 @@ export function graphColumnModel(
     key: layout.key,
     cached: layout.cached,
     clusters: reduced.clusters,
+    representative: reduced.representative,
     visible: reduced.nodes.length,
     total: model.nodes.length,
     empty: graphEmptyMessage(payload, reduced.nodes.length),

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

@@ -375,6 +375,8 @@ export interface HoverLabelNode {
   readonly y: number;
   readonly size: number;
   readonly label: string | null;
+  /** Set by the spotlight on a node whose label already stands — see {@link hoverLabelPainter}. */
+  readonly forceLabel?: boolean;
 }
 
 /** The settings a hover painter reads. Both `GraphSettings` and sigma's satisfy it. */
@@ -431,6 +433,9 @@ export function hoverLabelPainter(
     // `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;
+    // A forced label (the spotlight's lit nodes) is already standing beside the
+    // disc; floating it again underneath would print the same name twice.
+    if (data.forceLabel === true) return;
     const palette = graphPalette(scheme);
     context.save();
     context.font = `${settings.labelSize}px ${settings.labelFont}`;
@@ -670,8 +675,31 @@ export interface NodeDisplayOverride {
   readonly label?: string | null;
   readonly zIndex?: number;
   readonly size?: number;
+  /**
+   * Draw the label whatever the zoom and the label grid say — sigma's own
+   * display attribute. Only the spotlight sets it: a lit node has to name
+   * itself, and on a graph over {@link SMALL_GRAPH_NODES} the size threshold
+   * would otherwise keep a lit leaf silent.
+   */
+  readonly forceLabel?: boolean;
 }
 
+/**
+ * Which picture a highlight set paints.
+ *
+ * - `neighbourhood` — a selection (or hover) and its one-hop neighbours: the
+ *   selection is the subject, its links are drawn in the accent.
+ * - `spotlight` — the nodes a query lit (`spotlight.model.ts`): every lit node
+ *   is a subject, grown and labelled, the edges *between* lit nodes are drawn
+ *   in the highlighter's warm slot, and everything else drops back further
+ *   than a neighbourhood's cloud does.
+ *
+ * One set, one fade, two treatments — the spotlight rides the exact
+ * `setHighlight` path a selection does instead of a second layer, so the two
+ * can never be on screen at once and argue.
+ */
+export type HighlightStyle = "neighbourhood" | "spotlight";
+
 /** What sigma's `edgeReducer` may override. */
 export interface EdgeDisplayOverride {
   readonly color?: string;
@@ -715,12 +743,15 @@ export function nodeReducer(
    * about the clock.
    */
   progress: number = 1,
+  /** Which treatment the set gets — see {@link HighlightStyle}. */
+  style: HighlightStyle = "neighbourhood",
 ): (id: string, data: RenderNode, scheme: GraphTheme) => NodeDisplayOverride {
   return (id, data, scheme) => {
     // `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 (style === "spotlight") return spotlightNode(highlight, selectedId ?? null, progress, id, data, scheme);
     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
@@ -743,6 +774,75 @@ export function nodeReducer(
   };
 }
 
+// --- the spotlight treatment (G1) ------------------------------------------------------
+
+/**
+ * How far an unlit node or edge recedes while a spotlight is up.
+ *
+ * Further than a neighbourhood's {@link RECESS_STRENGTH}: a selection dims the
+ * cloud to *place* a node inside it, where a spotlight asks "where are the
+ * things I named?" and the answer is the lit nodes alone — the rest is
+ * context for position, faint dots and hairlines and nothing more.
+ */
+export const SPOTLIGHT_RECESS = 0.92;
+
+/** A lit node's growth — a step past a neighbour's, because every lit node is a subject. */
+export const SPOTLIGHT_GROWTH = 1.4;
+
+/** The selected node while a spotlight is up: the one the side sheet is about. */
+export const SPOTLIGHT_SELECTED_GROWTH = 1.7;
+
+/**
+ * An unlit node shrinks toward a dot as it recedes.
+ *
+ * Unlike a neighbourhood's cloud (which keeps its size so the graph does not
+ * appear to move on a click), the spotlight is a mode the user typed into,
+ * and the shrink is what makes "everything else drops back to faint dots"
+ * true at a glance. Positions are untouched, so nothing reflows.
+ */
+export const SPOTLIGHT_SHRINK = 0.75;
+
+/**
+ * Above this many lit nodes, labels go back to the size threshold.
+ *
+ * Forcing every label is right for the handful of matches a query usually
+ * names, and wrong for a query like `src` that lights a whole subtree: two
+ * hundred forced labels are one unreadable smear. Past the cap the lit nodes
+ * still grow and keep full colour; sigma's grid decides which of them speak.
+ */
+export const SPOTLIGHT_LABEL_LIMIT = 40;
+
+/** The slot an edge between two lit nodes is painted in — the highlighter's warm voice. */
+export const SPOTLIGHT_EDGE_SLOT: ColorSlot = "warning";
+
+/** One node under a spotlight. The selection is always a subject, lit or not. */
+function spotlightNode(
+  lit: ReadonlySet<string>,
+  selectedId: string | null,
+  progress: number,
+  id: string,
+  data: RenderNode,
+  scheme: GraphTheme,
+): NodeDisplayOverride {
+  const speaks = progress >= LABEL_DROP_AT;
+  if (id === selectedId) {
+    return { zIndex: data.zIndex + HIGHLIGHT_Z_LIFT * 2, size: data.size * growth(SPOTLIGHT_SELECTED_GROWTH, progress), forceLabel: speaks };
+  }
+  if (lit.has(id)) {
+    return {
+      zIndex: data.zIndex + HIGHLIGHT_Z_LIFT,
+      size: data.size * growth(SPOTLIGHT_GROWTH, progress),
+      forceLabel: speaks && lit.size <= SPOTLIGHT_LABEL_LIMIT,
+    };
+  }
+  return {
+    color: recessColor(data.color, scheme, SPOTLIGHT_RECESS * progress),
+    label: speaks ? null : data.label,
+    size: data.size * growth(SPOTLIGHT_SHRINK, progress),
+    zIndex: 0,
+  };
+}
+
 // --- the highlight fade (§7.4) -----------------------------------------------------
 
 /**
@@ -856,9 +956,23 @@ export function edgeReducer(
   selectedId?: string | null,
   /** The fade's progress — see {@link nodeReducer}'s. */
   progress: number = 1,
+  /** Which treatment the set gets — see {@link HighlightStyle}. */
+  style: HighlightStyle = "neighbourhood",
 ): (key: string, data: RenderEdge, scheme: GraphTheme) => EdgeDisplayOverride {
   return (_key, data, scheme) => {
     if (highlight === null || progress <= 0) return {};
+    if (style === "spotlight") {
+      // Lit only when it joins two lit nodes: the lines *between* matches are
+      // what the spotlight is for — how the things you named connect.
+      if (!highlight.has(data.source) || !highlight.has(data.target)) {
+        return { color: recessColor(data.color, scheme, SPOTLIGHT_RECESS * progress) };
+      }
+      return {
+        zIndex: 2,
+        size: data.size * growth(EDGE_PRESENCE * 1.35, progress),
+        color: blendHex(data.color, graphPalette(scheme)[SPOTLIGHT_EDGE_SLOT], progress),
+      };
+    }
     if (!highlight.has(data.source) || !highlight.has(data.target)) {
       return { color: recessColor(data.color, scheme, RECESS_STRENGTH * progress) };
     }

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

@@ -1,6 +1,6 @@
 import type { GraphTheme } from "../../shared/themes";
 import type { Point } from "../../shared/layout";
-import type { EdgeDisplayOverride, GraphSettings, NodeDisplayOverride, RenderEdge, RenderGraph, RenderNode, TrailGlow, ViewBox } from "./graph.model";
+import type { EdgeDisplayOverride, GraphSettings, HighlightStyle, NodeDisplayOverride, RenderEdge, RenderGraph, RenderNode, TrailGlow, ViewBox } from "./graph.model";
 import { edgeReducer, fadeStep, frameBox, graphSettings, labelThreshold, nodeReducer, trailOverride } from "./graph.model";
 import type { ProjectedGraph } from "./project";
 import { positionsOf, project, syncPositions } from "./project";
@@ -130,6 +130,8 @@ export function sigmaRenderer(
   let highlight: ReadonlySet<string> | null = null;
   /** The selection inside that neighbourhood — see `nodeReducer`. */
   let selected: string | null = null;
+  /** Which treatment `highlight` gets — a neighbourhood or a spotlight. */
+  let style: HighlightStyle = "neighbourhood";
   /** Recall-trail glows, layered over the selection — see `trailOverride`. */
   let trail: ReadonlyMap<string, TrailGlow> = new Map();
   /**
@@ -176,8 +178,8 @@ export function sigmaRenderer(
    * until the next unrelated frame.
    */
   const applyReducers = (instance: SigmaLike): void => {
-    const nodes = nodeReducer(highlight, selected, fade);
-    const edges = edgeReducer(highlight, selected, fade);
+    const nodes = nodeReducer(highlight, selected, fade, style);
+    const edges = edgeReducer(highlight, selected, fade, style);
     const glows = trail;
     instance.setSetting("nodeReducer", (id, data) => {
       const reduced = { ...data, ...nodes(id, data, scheme) };
@@ -279,10 +281,11 @@ export function sigmaRenderer(
       sigma?.refresh();
     },
 
-    setHighlight(next: ReadonlySet<string> | null, selectedId: string | null = null) {
+    setHighlight(next: ReadonlySet<string> | null, selectedId: string | null = null, nextStyle: HighlightStyle = "neighbourhood") {
       if (clock === undefined) {
         highlight = next;
         selected = selectedId;
+        style = nextStyle;
         fade = next === null ? 0 : 1;
         fadeTo = fade;
         if (sigma !== null) applyReducers(sigma);
@@ -297,9 +300,11 @@ export function sigmaRenderer(
       } 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.
+        // of the highlight is animated. The style swaps with the set; a clear
+        // (above) keeps the outgoing style so a spotlight fades out *as* one.
         highlight = next;
         selected = selectedId;
+        style = nextStyle;
         fadeTo = 1;
       }
       if (sigma !== null) applyReducers(sigma);
@@ -338,8 +343,17 @@ export function sigmaRenderer(
       // onto that box. `animatedReset` settles when the animation ends. Nothing
       // awaits a camera move, and a rejection from a camera killed mid-flight
       // is noise.
-      sigma?.setCustomBBox(boxOf());
-      void sigma?.getCamera().animatedReset();
+      const instance = sigma;
+      if (instance === null) return;
+      instance.setCustomBBox(boxOf());
+      // Sigma leaves edges out of frames drawn while the camera moves
+      // (`hideEdgesOnMove`) and repaints when the camera changes. A reset onto
+      // where the camera already is changes nothing, so the frame drawn during
+      // it, without edges, stayed on screen until something else repainted.
+      // One refresh once it settles draws them back.
+      instance.getCamera().animatedReset().then(() => {
+        if (sigma === instance) instance.refresh();
+      }, () => {});
     },
 
     positions() {