feat(graph): host-legend API + nodeLabelPriority encoding channel

Expose setActiveCategories/getActiveCategories on GraphInstance so
custom host legends can drive the persistent multi-select category
filter without spec recompilation. Add nodeLabelPriority encoding
channel to map a data field to label visibility priority instead of
the default degree-based heuristic.

Claude-Session: https://claude.ai/code/session_016rS7hi2g4bSzRBfnD1p2ji

Author: rileyhilliard

docs/codebase-map.md

@@ -118,16 +118,16 @@
 | Arc angle range (half-donut / election donut) | `markDef.startAngle`/`endAngle` (radians, d3 convention) handled in `packages/engine/src/charts/pie/compute.ts` (`computeSweepBounds` fits a partial sweep). |
 | Graph spec + layout types (`GraphSpec`, `GraphEncoding`, `GraphAnimationConfig`, `GraphInteractionConfig`, `NodeOverride`) | `packages/core/src/types/spec.ts` (search "GraphSpec"). Per-node visual overrides = `NodeOverride` (fill/radius/stroke/`alwaysShowLabel`). |
 | Graph compile (nodes/edges, community detection, encoding, animation + interaction resolve, simulationConfig) | `packages/engine/src/graphs/compile-graph.ts` → `compileGraph()`. Community detection: `graphs/community.ts`. |
-| Graph encoding resolve (nodeColor/edgeColor/nodeSize; category domain via `sort`, default `'ascending'`) | `packages/engine/src/graphs/encoding.ts`. Graph channels default `sort: 'ascending'` (VL-aligned, deterministic); `sort: null` restores insertion order; explicit `scale.domain` wins. |
+| Graph encoding resolve (nodeColor/edgeColor/nodeSize/nodeLabelPriority; category domain via `sort`, default `'ascending'`) | `packages/engine/src/graphs/encoding.ts`. Graph channels default `sort: 'ascending'` (VL-aligned, deterministic); `sort: null` restores insertion order; explicit `scale.domain` wins. `nodeLabelPriority` maps a quantitative field to 0-1 label visibility priority (falls back to degree-based when omitted). |
 | Graph animation resolve (DEFAULT-ON; the deliberate chart/graph divergence) | `packages/engine/src/graphs/animation.ts` → `resolveGraphAnimation()`. `undefined`/`true` → full defaults; `false` → no choreography (warmup still applies); per-phase `false` → that phase `null`. |
 | Graph interaction resolve (hover mode, cursor repulsion, springy drag, select/flyTo) | `packages/engine/src/graphs/interaction.ts` → `resolveGraphInteraction()`. |
-| Graph mount (lifecycle, events, tooltips, legend, search, camera, highlight, update) | `packages/vanilla/src/graph-mount.ts` → `createGraph()`. Public API: `GraphInstance` (search/zoomToFit/zoomToNode/flyTo/centerAt/getCamera/selectNode/highlight/getLegend/update/updateVisuals). `suppressEntrance` mount option skips the reveal on a theme/darkMode-only remount (instant fit, warmup still runs). Physics-feel gates: `SPRINGY_DRAG_MAX_NODES` (5000), `CURSOR_FORCE_MAX_NODES` (2000). |
+| Graph mount (lifecycle, events, tooltips, legend, search, camera, highlight, update) | `packages/vanilla/src/graph-mount.ts` → `createGraph()`. Public API: `GraphInstance` (search/zoomToFit/zoomToNode/flyTo/centerAt/getCamera/selectNode/highlight/clearHighlight/getHighlight/setActiveCategories/getActiveCategories/getLegend/update/updateVisuals). `suppressEntrance` mount option skips the reveal on a theme/darkMode-only remount (instant fit, warmup still runs). Physics-feel gates: `SPRINGY_DRAG_MAX_NODES` (5000), `CURSOR_FORCE_MAX_NODES` (2000). |
 | Graph force simulation (d3-force wrapper, warmup, tick streaming, sync + worker) | `packages/vanilla/src/graph/simulation.ts` → `SimulationManager`. Worker protocol: `graph/worker-protocol.ts`; worker URL: `graph/simulation-worker-url.ts`. |
 | Graph seeded layout (deterministic initial positions) | `packages/vanilla/src/graph/seed.ts` → `seedNodePositions()`. Start position is a pure function of `(id, seed, community)`, so the settled layout is reproducible across data reshapes (not d3's order-dependent phyllotaxis). |
 | Graph animation scheduler (rAF loop, first-frame arming) | `packages/vanilla/src/graph/scheduler.ts` → `AnimationScheduler`. Owns running `GraphAnimation`s; the mount's render loop ticks it once/frame and re-arms rAF only while animations are active (zero cost when idle). |
 | Graph motion primitives (easings, reduced-motion, generic tween) | `packages/vanilla/src/graph/motion.ts` → `createTween()`, `resolveEase()`, `prefersReducedMotion()`. Canvas rAF, NOT CSS keyframes; only the easing vocabulary is shared with charts. |
 | Graph entrance choreography (reveal alpha, staggered start) | `packages/vanilla/src/graph/entrance.ts`. Turns the mount's 0→1 `entranceProgress` into a per-node reveal alpha, quantized so the canvas renderer still batches fills. The camera pull-back + flight lives in `graph-mount.ts` `startEntrance()`. |
-| Graph camera flights (animated zoom/pan) | `packages/vanilla/src/graph/camera.ts` → `createCameraFlight()`, `CameraFlightOptions`, `clampK`, `K_MIN`/`K_MAX`. Interpolates two `ZoomTransform`s along d3 `interpolateZoom`; supports a moving-target provider so a flight tracks a still-settling node. |
+| Graph camera flights (animated zoom/pan) | `packages/vanilla/src/graph/camera.ts` → `createCameraFlight()`, `createCameraFollow()`, `CameraFlightOptions`, `clampK`, `K_MIN`/`K_MAX`. Interpolates two `ZoomTransform`s along d3 `interpolateZoom`; supports a moving-target provider so a flight tracks a still-settling node. `createCameraFollow()` continuously tracks a moving target (e.g. entrance pull-back). |
 | Graph focus model (highlight ∩ search + hover-neighborhood, eased crossfade) | `packages/vanilla/src/graph/focus-transition.ts` → `FocusTransition`. Composes the three emphasis sources into a snapshot pair the renderer crossfades between (composition, not strict precedence). |
 | Graph update diff (unified `update()` path classification) | `packages/vanilla/src/graph/update-diff.ts` → `diffGraphUpdate()`. Classifies a change as `visualOnly` (same node+edge id sets AND equal simulationConfig → position-preserving) vs structural (reheat). Config equality: `graph/update-diff-config.ts` (compares the full resolved simulationConfig, not just `clustering.field` like the old React heuristic). |
 | Graph interactive legend (accessible built-in legend) | `packages/vanilla/src/graph/legend.ts` → `GraphLegendController`. Node-category rows are `aria-pressed` buttons that toggle emphasis via the focus model; edge-category rows are non-interactive swatches. Turn off with `legend: false` (do this if you render your own). |

packages/core/schema/vizspec.schema.json

@@ -16938,6 +16938,10 @@
         "nodeLabel": {
           "$ref": "#/definitions/GraphEncodingChannel",
           "description": "Label field for nodes."
+        },
+        "nodeLabelPriority": {
+          "$ref": "#/definitions/GraphEncodingChannel",
+          "description": "Label priority mapping for nodes. Maps a quantitative field to a 0-1 priority range; higher values are shown first as the user zooms in. Omit to use the default degree-based priority. `nodeOverrides[id].alwaysShowLabel` still wins as the hard override."
         }
       },
       "additionalProperties": false,

packages/core/src/types/spec.ts

@@ -790,6 +790,13 @@ export interface GraphEncoding {
   edgeStyle?: GraphEncodingChannel;
   /** Label field for nodes. */
   nodeLabel?: GraphEncodingChannel;
+  /**
+   * Label priority mapping for nodes. Maps a quantitative field to a 0-1
+   * priority range; higher values are shown first as the user zooms in.
+   * Omit to use the default degree-based priority.
+   * `nodeOverrides[id].alwaysShowLabel` still wins as the hard override.
+   */
+  nodeLabelPriority?: GraphEncodingChannel;
 }
 
 /** Layout algorithm for graph visualization. */

packages/engine/src/compiler/validate.ts

@@ -1191,7 +1191,13 @@ function validateGraphSpec(spec: Record<string, unknown>, errors: ValidationErro
       }
     }
 
-    const nodeChannels = ['nodeColor', 'nodeSize', 'nodeOpacity', 'nodeLabel'] as const;
+    const nodeChannels = [
+      'nodeColor',
+      'nodeSize',
+      'nodeOpacity',
+      'nodeLabel',
+      'nodeLabelPriority',
+    ] as const;
     for (const channel of nodeChannels) {
       const ch = encoding[channel] as Record<string, unknown> | undefined;
       if (

packages/engine/src/graphs/__tests__/encoding.test.ts

@@ -141,6 +141,74 @@ describe('resolveNodeVisuals', () => {
       const hub = nodes.find((n) => n.id === 'a')!;
       expect(hub.labelPriority).toBe(1.0);
     });
+
+    it('uses field value when nodeLabelPriority is set', () => {
+      const encoding: GraphEncoding = {
+        nodeLabelPriority: { field: 'value', type: 'quantitative' },
+      };
+
+      const nodes = resolveNodeVisuals(basicNodes, encoding, basicEdges, theme);
+
+      const nodeA = nodes.find((n) => n.id === 'a')!; // value: 10 (min)
+      const nodeC = nodes.find((n) => n.id === 'c')!; // value: 100 (max)
+      expect(nodeA.labelPriority).toBeCloseTo(0, 1);
+      expect(nodeC.labelPriority).toBeCloseTo(1, 1);
+    });
+
+    it('falls back to degree-based priority when nodeLabelPriority omitted', () => {
+      const hubEdges: GraphEdge[] = [
+        { source: 'a', target: 'b' },
+        { source: 'a', target: 'c' },
+      ];
+
+      const withChannel = resolveNodeVisuals(basicNodes, {}, hubEdges, theme);
+      const hub = withChannel.find((n) => n.id === 'a')!;
+      expect(hub.labelPriority).toBe(1.0);
+    });
+
+    it('alwaysShowLabel overrides nodeLabelPriority to Infinity', () => {
+      const encoding: GraphEncoding = {
+        nodeLabelPriority: { field: 'value', type: 'quantitative' },
+      };
+      const overrides = { a: { alwaysShowLabel: true } };
+
+      const nodes = resolveNodeVisuals(basicNodes, encoding, basicEdges, theme, overrides);
+
+      const nodeA = nodes.find((n) => n.id === 'a')!;
+      expect(nodeA.labelPriority).toBe(Infinity);
+    });
+
+    it('respects scale.range override on nodeLabelPriority', () => {
+      const encoding: GraphEncoding = {
+        nodeLabelPriority: {
+          field: 'value',
+          type: 'quantitative',
+          scale: { range: [0.5, 1] },
+        },
+      };
+
+      const nodes = resolveNodeVisuals(basicNodes, encoding, basicEdges, theme);
+
+      const nodeA = nodes.find((n) => n.id === 'a')!; // value: 10 (min)
+      const nodeC = nodes.find((n) => n.id === 'c')!; // value: 100 (max)
+      expect(nodeA.labelPriority).toBeCloseTo(0.5, 1);
+      expect(nodeC.labelPriority).toBeCloseTo(1, 1);
+    });
+
+    it('non-numeric field values get priority 0', () => {
+      const nodesWithString: GraphNode[] = [
+        { id: 'a', importance: 'high' },
+        { id: 'b', importance: 50 },
+      ];
+      const encoding: GraphEncoding = {
+        nodeLabelPriority: { field: 'importance', type: 'quantitative' },
+      };
+
+      const nodes = resolveNodeVisuals(nodesWithString, encoding, [], theme);
+
+      const nodeA = nodes.find((n) => n.id === 'a')!;
+      expect(nodeA.labelPriority).toBe(0);
+    });
   });
 
   describe('label resolution', () => {

packages/engine/src/graphs/encoding.ts

@@ -264,6 +264,26 @@ export function resolveNodeVisuals(
     opacityScale = scaleLinear().domain(domain).range(range);
   }
 
+  // Build label priority scale. Maps a quantitative field to [0, 1] so
+  // higher values are shown first. Falls back to degree-based priority.
+  let labelPriorityScale: ((v: number) => number) | undefined;
+  if (encoding.nodeLabelPriority?.field) {
+    const field = encoding.nodeLabelPriority.field;
+    const scaleConfig = encoding.nodeLabelPriority.scale;
+    const values = nodes.map((n) => Number(n[field])).filter((v) => Number.isFinite(v));
+    const lpMin = min(values) ?? 0;
+    const lpMax = max(values) ?? 1;
+    const domain =
+      scaleConfig?.domain && scaleConfig.domain.length === 2
+        ? (scaleConfig.domain as [number, number])
+        : [lpMin, lpMax];
+    const range =
+      scaleConfig?.range && scaleConfig.range.length >= 2
+        ? [Number(scaleConfig.range[0]), Number(scaleConfig.range[1])]
+        : [0, 1];
+    labelPriorityScale = scaleLinear().domain(domain).range(range);
+  }
+
   return nodes.map((node) => {
     // Radius
     let radius = DEFAULT_NODE_RADIUS;
@@ -298,9 +318,15 @@ export function resolveNodeVisuals(
       label = node.id;
     }
 
-    // Label priority: degree / maxDegree (0 to 1)
-    const degree = degrees.get(node.id) ?? 0;
-    const labelPriority = maxDegree > 0 ? degree / maxDegree : 0;
+    // Label priority: field-driven when nodeLabelPriority is set, else degree-based.
+    let labelPriority: number;
+    if (labelPriorityScale && encoding.nodeLabelPriority?.field) {
+      const val = Number(node[encoding.nodeLabelPriority.field]);
+      labelPriority = Number.isFinite(val) ? labelPriorityScale(val) : 0;
+    } else {
+      const degree = degrees.get(node.id) ?? 0;
+      labelPriority = maxDegree > 0 ? degree / maxDegree : 0;
+    }
 
     // Data: spread all original node fields
     const { id: _id, ...rest } = node;

packages/react/src/Graph.tsx

@@ -261,6 +261,12 @@ export const Graph = forwardRef<GraphHandle, GraphProps>(function Graph(
       getLegend() {
         return graphRef.current?.getLegend() ?? null;
       },
+      setActiveCategories(values: string[]) {
+        graphRef.current?.setActiveCategories(values);
+      },
+      getActiveCategories() {
+        return graphRef.current?.getActiveCategories() ?? [];
+      },
       updateVisuals(spec: GraphSpec) {
         graphRef.current?.updateVisuals(spec);
       },

packages/react/src/hooks/useGraph.ts

@@ -49,6 +49,10 @@ export interface UseGraphReturn {
   getHighlight: () => string[] | null;
   /** Headless snapshot of the legend. */
   getLegend: () => GraphLegendData | null;
+  /** Set the active category filter declaratively (replaces legend toggle state). */
+  setActiveCategories: (values: string[]) => void;
+  /** Current active category values (empty = all active, no filter). */
+  getActiveCategories: () => string[];
 }
 
 /** Handle exposed by Graph component via forwardRef. */
@@ -67,6 +71,8 @@ export interface GraphHandle {
   clearHighlight: () => void;
   getHighlight: () => string[] | null;
   getLegend: () => GraphLegendData | null;
+  setActiveCategories: (values: string[]) => void;
+  getActiveCategories: () => string[];
   /** Re-compile encoding/legend/chrome without restarting the simulation. */
   updateVisuals: (spec: GraphSpec) => void;
   /** The underlying GraphInstance from the vanilla adapter. */
@@ -150,6 +156,14 @@ export function useGraph(): UseGraphReturn {
     return ref.current?.getLegend() ?? null;
   }, []);
 
+  const setActiveCategories = useCallback((values: string[]) => {
+    ref.current?.setActiveCategories(values);
+  }, []);
+
+  const getActiveCategories = useCallback((): string[] => {
+    return ref.current?.getActiveCategories() ?? [];
+  }, []);
+
   return {
     ref,
     search,
@@ -166,5 +180,7 @@ export function useGraph(): UseGraphReturn {
     clearHighlight,
     getHighlight,
     getLegend,
+    setActiveCategories,
+    getActiveCategories,
   };
 }

packages/svelte/src/Graph.svelte

@@ -222,6 +222,14 @@ export function getLegend(): GraphLegendData | null {
   return instance?.getLegend() ?? null;
 }
 
+export function setActiveCategories(values: string[]): void {
+  instance?.setActiveCategories(values);
+}
+
+export function getActiveCategories(): string[] {
+  return instance?.getActiveCategories() ?? [];
+}
+
 export function updateVisuals(nextSpec: GraphSpec): void {
   instance?.updateVisuals(nextSpec);
 }

packages/svelte/src/composables/useGraph.svelte.ts

@@ -94,6 +94,10 @@ export interface UseGraphReturn {
   getHighlight: () => string[] | null;
   /** Headless snapshot of the legend. */
   getLegend: () => GraphLegendData | null;
+  /** Set the active category filter declaratively (replaces legend toggle state). */
+  setActiveCategories: (values: string[]) => void;
+  /** Current active category values (empty = all active, no filter). */
+  getActiveCategories: () => string[];
 }
 
 export function useGraph(
@@ -185,5 +189,11 @@ export function useGraph(
     getLegend(): GraphLegendData | null {
       return instance?.getLegend() ?? null;
     },
+    setActiveCategories(values: string[]) {
+      instance?.setActiveCategories(values);
+    },
+    getActiveCategories(): string[] {
+      return instance?.getActiveCategories() ?? [];
+    },
   };
 }