pi-weave 0.3.8 → 0.3.10

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

@@ -40,11 +40,32 @@ 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";
 import { schemeOf } from "./scheme";
 import type { SchemeHost } from "./scheme";
 import type { GraphTheme } from "../../shared/themes";
@@ -92,14 +113,43 @@ export interface GraphProps {
    * keeps the ownership where it is and costs one line at each end.
    */
   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();
+
 export function Graph(props: GraphProps) {
   const canvas = useRef<HTMLDivElement | null>(null);
   const renderer = useRef<GraphRenderer | null>(null);
   const dynamics = useRef<GraphSimulation | null>(null);
   const clock = useRef<number | null>(null);
+  // Whether the camera has been fitted to the first settled layout. The
+  // mount frames the *starting* positions, which a settling simulation then
+  // pushes past the edges — a two-note vault opened with clipped circles.
+  const fitted = useRef(false);
   /**
    * Arm the simulation clock — idempotent.
    *
@@ -116,7 +166,13 @@ export function Graph(props: GraphProps) {
       if (engine === null) return;
       engine.tick();
       // Asleep: let the clock die. The next pin re-arms it.
-      if (!engine.awake()) return;
+      if (!engine.awake()) {
+        if (!fitted.current) {
+          fitted.current = true;
+          renderer.current?.fit();
+        }
+        return;
+      }
       renderer.current?.setPositions(engine.positions());
       clock.current = requestAnimationFrame(step);
     };
@@ -143,11 +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 live = useRef({ view, model, onSelect: props.onSelect, selectedId: props.selectedId });
-  live.current = { view, model, onSelect: props.onSelect, selectedId: props.selectedId };
+  const trailRef = useRef<ReadonlyMap<string, TrailGlow>>(NO_GLOWS);
+  trailRef.current = props.trail ?? NO_GLOWS;
+  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);
@@ -164,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);
@@ -194,7 +266,9 @@ 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 () => {
       instance.destroy();
@@ -239,17 +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">
@@ -269,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. */
@@ -235,7 +284,7 @@ export function graphCountLabel(visible: number, total: number): string {
 /** What the column says instead of a canvas. `null` means "there is a graph". */
 export function graphEmptyMessage(payload: GraphPayload | null, visible: number): string | null {
   if (payload === null) return "Loading…";
-  if (payload.model.nodes.length === 0) return "Nothing indexed yet — add a note or run /weave-scan.";
+  if (payload.model.nodes.length === 0) return "Nothing here yet — add a note to get started.";
   // A payload with nodes but nothing visible cannot happen through the UI
   // (`clusterAggregate` always keeps the roots), but a truncated response
   // could produce it, and a blank canvas with no explanation reads as a crash.
@@ -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

@@ -83,11 +83,8 @@ export function graphPalette(theme: GraphTheme): Readonly<Record<ColorSlot, stri
  * - `note` keeps `text` — notes are the product (§1.1), and their identity
  *   is carried by the provenance badge, not by a hue.
  * - Generated code — modules, packages, entry points, git, externals, files
- *   — takes `dim`, the same grey a `generated` row takes in the tree. The
- *   TUI's `kindStyle` (src/pi/viewer/tui/theme.ts) still maps these kinds to
- *   success/warning; the two media disagree on purpose, because a pi theme
- *   has no dark/light stylesheet to violate and a terminal can restyle
- *   everything. Here the sheet decides, and the sheet says calm.
+ *   — takes `dim`, the same grey a `generated` row takes in the tree. Here
+ *   the sheet decides, and the sheet says calm.
  */
 export const KIND_SLOT: Readonly<Record<WireNodeKind, ColorSlot>> = {
   vault: "accent",
@@ -378,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. */
@@ -434,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}`;
@@ -513,7 +515,8 @@ export interface ViewBox {
  * session: the node stays under the cursor, the canvas bounds the drag, and
  * `[fit]` re-frames onto whatever the current positions are.
  *
- * Use the position extent, with a minimum span of four collision radii.
+ * Use the position extent padded by the largest node size, so no circle
+ * at the edge is cut off, with a minimum span of four collision radii.
  * A single node (or coincident nodes) has no extent; Sigma scales layout-unit
  * node sizes by that span, so a near-zero box magnifies one node across the
  * canvas. Pixel-based `stagePadding` cannot prevent that.
@@ -536,7 +539,9 @@ export function frameBox(points: readonly Point[]): ViewBox | null {
     if (p.y > maxY) maxY = p.y;
   }
   if (seen === 0) return null;
-  const padding = Math.max(0, (COLLIDE_RADIUS * 4 - Math.max(maxX - minX, maxY - minY)) / 2);
+  // The extent is of node *centres*; the circles reach past it by up to a
+  // full node size, which clipped the outermost nodes on a small graph.
+  const padding = Math.max(MAX_NODE_SIZE, (COLLIDE_RADIUS * 4 - Math.max(maxX - minX, maxY - minY)) / 2);
   return { x: [minX - padding, maxX + padding], y: [minY - padding, maxY + padding] };
 }
 
@@ -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) };
     }
@@ -882,6 +996,54 @@ export function edgeReducer(
   };
 }
 
+// --- the recall trail (issue #78) -----------------------------------------------------
+
+/** The slice of `trail.model.ts`'s `TrailMark` this layer reads, restated to keep this file import-free of it. */
+export interface TrailGlow {
+  readonly kind: "searched" | "read" | "wrote";
+  readonly strength: number;
+}
+
+/**
+ * How each kind of touch is painted: which slot it blends toward, how far, and
+ * how much the node grows. A search hit is a soft amber hint, a read is a
+ * filled glow, and a write is the accent at full presence — the one place
+ * this canvas spends the accent on a note, because a write is the event.
+ */
+export const TRAIL_STYLE: Readonly<Record<TrailGlow["kind"], { slot: ColorSlot; blend: number; growth: number }>> = {
+  searched: { slot: "warning", blend: 0.35, growth: 1.08 },
+  read: { slot: "success", blend: 0.85, growth: 1.3 },
+  wrote: { slot: "accent", blend: 1, growth: 1.5 },
+};
+
+/**
+ * The recall-trail layer, applied **over** the selection reducer's answer.
+ *
+ * Over, because the trail is the live event: a note the agent just wrote must
+ * read as such even when it sits in the receded cloud of an unrelated
+ * selection. It is handed the *reduced* node, and colour and size scale with
+ * the glow's strength, so the fade is a smooth return to whatever the
+ * selection layer said; the label is kept so a glowing node always names itself.
+ */
+export function trailOverride(
+  glow: TrailGlow | undefined,
+  /** The node as the selection layer left it, so the glow composes over recession and growth. */
+  data: Pick<RenderNode, "color" | "size" | "zIndex">,
+  scheme: GraphTheme,
+  /** The node's own label — the selection layer may have dropped it, and a glowing node always names itself. */
+  label: string,
+): NodeDisplayOverride {
+  if (glow === undefined || !(glow.strength > 0)) return {};
+  const style = TRAIL_STYLE[glow.kind];
+  const strength = Math.min(1, glow.strength);
+  return {
+    color: blendHex(data.color, graphPalette(scheme)[style.slot], style.blend * strength),
+    size: data.size * growth(style.growth, strength),
+    zIndex: data.zIndex + HIGHLIGHT_Z_LIFT * 3,
+    label,
+  };
+}
+
 // --- sigma settings (§7.4) -------------------------------------------------------------
 
 /**
@@ -929,6 +1091,20 @@ export interface GraphSettings {
  */
 export const LABEL_SIZE_THRESHOLD = (MIN_NODE_SIZE + MAX_NODE_SIZE) / 2;
 
+/**
+ * Below this many nodes every node carries its name.
+ *
+ * The size threshold exists to keep a dense graph legible; on a vault of
+ * two or three notes it left all but one circle unnamed, and a small graph
+ * has no density to protect.
+ */
+export const SMALL_GRAPH_NODES = 30;
+
+/** `labelRenderedSizeThreshold` for a graph of `nodeCount` nodes. */
+export function labelThreshold(nodeCount: number): number {
+  return nodeCount < SMALL_GRAPH_NODES ? 0 : LABEL_SIZE_THRESHOLD;
+}
+
 /**
  * Label collision grid, in screen pixels.
  *