@opendata-ai/openchart-vanilla 2.0.0 → 2.2.0

package/dist/simulation-worker.js

@@ -1130,7 +1130,15 @@
           }));
           nodeMap = new Map(internalNodes.map((n) => [n.id, n]));
           const { config } = msg;
-          simulation = simulation_default(internalNodes).force("link", link_default(msg.edges.map((e) => ({ ...e }))).id((d) => d.id).distance(config.linkDistance)).force("charge", manyBody_default().strength(config.chargeStrength)).force("center", center_default(0, 0)).force("collide", collide_default().radius((d) => d.radius + 1)).force("gravityX", x_default2(0).strength(0.05)).force("gravityY", y_default2(0).strength(0.05)).alphaDecay(config.alphaDecay).velocityDecay(config.velocityDecay);
+          const linkForce = link_default(msg.edges.map((e) => ({ ...e }))).id((d) => d.id).distance(config.linkDistance);
+          if (config.linkStrength != null) {
+            linkForce.strength(config.linkStrength);
+          }
+          const padding = config.collisionPadding ?? 2;
+          simulation = simulation_default(internalNodes).force("link", linkForce).force("charge", manyBody_default().strength(config.chargeStrength)).force("collide", collide_default().radius((d) => d.radius + padding)).force("gravityX", x_default2(0).strength(0.05)).force("gravityY", y_default2(0).strength(0.05)).alphaDecay(config.alphaDecay).velocityDecay(config.velocityDecay);
+          if (config.centerForce !== false) {
+            simulation.force("center", center_default(0, 0));
+          }
           if (config.clustering) {
             const clusterFn = forceCluster(internalNodes, config.clustering.strength);
             simulation.force("cluster", clusterFn);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opendata-ai/openchart-vanilla",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Vanilla JS renderer for openchart: SVG charts, HTML tables, force-directed graphs",
   "license": "Apache-2.0",
   "author": "Riley Hilliard",
@@ -46,8 +46,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@opendata-ai/openchart-core": "2.0.0",
-    "@opendata-ai/openchart-engine": "2.0.0",
+    "@opendata-ai/openchart-core": "2.2.0",
+    "@opendata-ai/openchart-engine": "2.2.0",
     "d3-force": "^3.0.0",
     "d3-quadtree": "^3.0.1"
   },

package/src/__tests__/export.test.ts

@@ -1,8 +1,8 @@
 /**
  * Export utility tests.
  *
- * Tests exportSVG and exportCSV functions directly, verifying SVG string
- * validity and CSV formatting with headers and proper escaping.
+ * Tests exportSVG, exportCSV, and exportJPG functions directly, verifying SVG string
+ * validity, CSV formatting with headers and proper escaping, and JPG export interface.
  */
 
 import type { CompileOptions } from '@opendata-ai/openchart-engine';
@@ -10,7 +10,7 @@ import { compileChart } from '@opendata-ai/openchart-engine';
 import { afterEach, describe, expect, it } from 'vitest';
 import { createContainer } from '../__test-fixtures__/dom';
 import { barSpec, lineSpec } from '../__test-fixtures__/specs';
-import { exportCSV, exportSVG } from '../export';
+import { exportCSV, exportJPG, exportSVG } from '../export';
 import { renderChartSVG } from '../svg-renderer';
 
 // ---------------------------------------------------------------------------
@@ -148,3 +148,29 @@ describe('exportCSV', () => {
     expect(result.split('\n')[0]).toBe('x,y,z');
   });
 });
+
+// ---------------------------------------------------------------------------
+// exportJPG
+// ---------------------------------------------------------------------------
+
+describe('exportJPG', () => {
+  it('is a function that accepts an SVG element and options', () => {
+    expect(typeof exportJPG).toBe('function');
+    expect(exportJPG.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it('returns a Promise when called with a rendered SVG element', () => {
+    const svg = renderToSVG();
+    const result = exportJPG(svg);
+    expect(result).toBeInstanceOf(Promise);
+    // Clean up: catch any rejection from happy-dom canvas limitations
+    result.catch(() => {});
+  });
+
+  it('accepts quality option between 0 and 1', () => {
+    const svg = renderToSVG();
+    const result = exportJPG(svg, { quality: 0.5, dpi: 1 });
+    expect(result).toBeInstanceOf(Promise);
+    result.catch(() => {});
+  });
+});

package/src/__tests__/svg-renderer.test.ts

@@ -607,3 +607,50 @@ describe('targeted mark snapshots', () => {
     expect(path!.getAttribute('d')).not.toBeNull();
   });
 });
+
+// ---------------------------------------------------------------------------
+// Brand watermark
+// ---------------------------------------------------------------------------
+
+describe('brand watermark', () => {
+  it('renders "Open" and "Data" text elements', () => {
+    const { svg } = renderSpec(lineSpec);
+    const openLink = svg.querySelector('.viz-axis-ref');
+    const dataLink = svg.querySelector('.viz-chrome-ref');
+    expect(openLink).not.toBeNull();
+    expect(dataLink).not.toBeNull();
+    expect(openLink!.querySelector('text')!.textContent).toBe('Open');
+    expect(dataLink!.querySelector('text')!.textContent).toBe('Data');
+  });
+
+  it('both elements link to tryopendata.ai', () => {
+    const { svg } = renderSpec(lineSpec);
+    const links = svg.querySelectorAll('a[href="https://tryopendata.ai"]');
+    expect(links.length).toBe(2);
+  });
+
+  it('elements are direct children of SVG root (no shared group)', () => {
+    const { svg } = renderSpec(lineSpec);
+    const openLink = svg.querySelector('.viz-axis-ref');
+    const dataLink = svg.querySelector('.viz-chrome-ref');
+    expect(openLink!.parentElement).toBe(svg);
+    expect(dataLink!.parentElement).toBe(svg);
+  });
+
+  it('elements are interleaved with other chart layers', () => {
+    const { svg } = renderSpec(lineSpec);
+    const children = Array.from(svg.children);
+    const openIdx = children.findIndex((el) => el.classList.contains('viz-axis-ref'));
+    const chromeIdx = children.findIndex((el) => el.classList.contains('viz-chrome'));
+    const dataIdx = children.findIndex((el) => el.classList.contains('viz-chrome-ref'));
+    // "Open" should come before chrome, "Data" after chrome
+    expect(openIdx).toBeLessThan(chromeIdx);
+    expect(dataIdx).toBeGreaterThan(chromeIdx);
+  });
+
+  it('skips watermark on very small charts', () => {
+    const { svg } = renderSpec(lineSpec, { width: 100, height: 80 });
+    const openLink = svg.querySelector('.viz-axis-ref');
+    expect(openLink).toBeNull();
+  });
+});

package/src/export.ts

@@ -74,6 +74,76 @@ export async function exportPNG(svgElement: SVGElement, options?: PNGExportOptio
   });
 }
 
+export interface JPGExportOptions extends PNGExportOptions {
+  /** JPEG quality from 0 to 1. Defaults to 0.92. */
+  quality?: number;
+}
+
+/**
+ * Render an SVG element to a JPEG Blob via a canvas.
+ *
+ * Same pipeline as exportPNG but outputs JPEG with configurable quality.
+ * The canvas is filled with white before drawing to avoid transparent
+ * backgrounds rendering as black in JPEG format.
+ *
+ * @param svgElement - The rendered SVG element.
+ * @param options - Optional DPI scaling and JPEG quality.
+ * @returns A Promise resolving to the JPEG Blob.
+ */
+export async function exportJPG(svgElement: SVGElement, options?: JPGExportOptions): Promise<Blob> {
+  const dpi = options?.dpi ?? 2;
+  const quality = options?.quality ?? 0.92;
+  const svgString = exportSVG(svgElement);
+
+  const width = parseFloat(svgElement.getAttribute('width') || '600');
+  const height = parseFloat(svgElement.getAttribute('height') || '400');
+
+  const canvas = document.createElement('canvas');
+  canvas.width = width * dpi;
+  canvas.height = height * dpi;
+
+  const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    throw new Error('Canvas 2D context not available');
+  }
+
+  // Fill white background since JPEG doesn't support transparency
+  ctx.fillStyle = '#ffffff';
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+
+  ctx.scale(dpi, dpi);
+
+  const img = new Image();
+  const blob = new Blob([svgString], { type: 'image/svg+xml;charset=utf-8' });
+  const url = URL.createObjectURL(blob);
+
+  return new Promise<Blob>((resolve, reject) => {
+    img.onload = () => {
+      ctx.drawImage(img, 0, 0);
+      URL.revokeObjectURL(url);
+
+      canvas.toBlob(
+        (result) => {
+          if (result) {
+            resolve(result);
+          } else {
+            reject(new Error('Canvas toBlob returned null'));
+          }
+        },
+        'image/jpeg',
+        quality,
+      );
+    };
+
+    img.onerror = () => {
+      URL.revokeObjectURL(url);
+      reject(new Error('Failed to load SVG as image'));
+    };
+
+    img.src = url;
+  });
+}
+
 /**
  * Convert an array of data objects to a CSV string.
  *

package/src/graph/canvas-renderer.ts

@@ -141,6 +141,7 @@ export class GraphCanvasRenderer {
       edges,
       transform,
       hoveredNodeId,
+      hoveredEdgeId,
       selectedNodeIds,
       adjacencyMap,
       theme,
@@ -193,6 +194,7 @@ export class GraphCanvasRenderer {
       hasActiveNode,
       connectedNodeIds,
       isGesturing ? null : searchMatches,
+      hoveredEdgeId,
     );
 
     // -- Draw nodes (batched by fill color) --
@@ -222,6 +224,35 @@ export class GraphCanvasRenderer {
     }
 
     ctx.restore();
+
+    // Brand watermark in screen coordinates (unaffected by pan/zoom)
+    this.drawBrand(ctx, cssWidth, cssHeight, theme);
+  }
+
+  // -------------------------------------------------------------------------
+  // Brand rendering
+  // -------------------------------------------------------------------------
+
+  private drawBrand(
+    ctx: CanvasRenderingContext2D,
+    w: number,
+    h: number,
+    theme: GraphRenderState['theme'],
+  ): void {
+    if (w < 120) return;
+    const { dpr } = this;
+    ctx.save();
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+    const padding = theme.spacing.padding;
+    const x = w - padding;
+    const y = h - 4;
+    ctx.font = `600 20px ${theme.fonts.family}`;
+    ctx.fillStyle = theme.colors.axis;
+    ctx.globalAlpha = 0.5;
+    ctx.textAlign = 'right';
+    ctx.textBaseline = 'alphabetic';
+    ctx.fillText('OpenData', x, y);
+    ctx.restore();
   }
 
   // -------------------------------------------------------------------------
@@ -234,13 +265,21 @@ export class GraphCanvasRenderer {
     hasActiveNode: boolean,
     connectedNodeIds: Set<string>,
     searchMatches: Set<string> | null,
+    hoveredEdgeId: string | null,
   ): void {
     // Classify edges by alpha level, then batch by visual style within each level
     const dimmedEdges: PositionedEdge[] = [];
     const defaultEdges: PositionedEdge[] = [];
     const connectedEdges: PositionedEdge[] = [];
+    let hoveredEdge: PositionedEdge | null = null;
 
     for (const edge of edges) {
+      const edgeId = `${edge.source}->${edge.target}`;
+      if (edgeId === hoveredEdgeId) {
+        hoveredEdge = edge;
+        continue; // Draw hovered edge last, on top
+      }
+
       const isConnected =
         hasActiveNode && connectedNodeIds.has(edge.source) && connectedNodeIds.has(edge.target);
       const isDimmed = hasActiveNode && !isConnected;
@@ -258,6 +297,21 @@ export class GraphCanvasRenderer {
     this.drawEdgeGroupBatched(ctx, dimmedEdges, EDGE_ALPHA_DIMMED, searchMatches);
     this.drawEdgeGroupBatched(ctx, defaultEdges, EDGE_ALPHA_DEFAULT, searchMatches);
     this.drawEdgeGroupBatched(ctx, connectedEdges, EDGE_ALPHA_CONNECTED, searchMatches);
+
+    // Draw hovered edge on top with highlight
+    if (hoveredEdge) {
+      const dash = DASH_PATTERNS[hoveredEdge.style] ?? DASH_PATTERNS.solid;
+      ctx.setLineDash(dash);
+      ctx.strokeStyle = hoveredEdge.stroke;
+      ctx.lineWidth = hoveredEdge.strokeWidth * 2;
+      ctx.globalAlpha = EDGE_ALPHA_CONNECTED;
+      ctx.beginPath();
+      ctx.moveTo(hoveredEdge.sourceX, hoveredEdge.sourceY);
+      ctx.lineTo(hoveredEdge.targetX, hoveredEdge.targetY);
+      ctx.stroke();
+      ctx.setLineDash([]);
+      ctx.globalAlpha = 1;
+    }
   }
 
   /**

package/src/graph/interaction.ts

@@ -26,6 +26,8 @@ const HIT_DISTANCE = 5;
 export interface InteractionCallbacks {
   onTransformChange(transform: ZoomTransform): void;
   onHoverChange(nodeId: string | null): void;
+  /** Called during mouse move when no node is hit, with graph-space coordinates for edge hit testing. */
+  onBackgroundHover?(graphX: number, graphY: number, screenX: number, screenY: number): void;
   onSelectionChange(nodeIds: string[]): void;
   onNodeDragStart(nodeId: string): void;
   onNodeDrag(nodeId: string, x: number, y: number): void;
@@ -198,6 +200,12 @@ export class GraphInteractionManager {
     const hitId = this.hitTest(x, y);
     this.callbacks.onHoverChange(hitId);
 
+    // If no node hit, check edges via callback
+    if (!hitId) {
+      const graph = this.transform.screenToGraph(x, y);
+      this.callbacks.onBackgroundHover?.(graph.x, graph.y, x, y);
+    }
+
     // Update cursor
     this.canvas.style.cursor = hitId ? 'pointer' : 'default';
   }

package/src/graph/simulation-worker.ts

@@ -60,6 +60,9 @@ interface SimConfig {
   alphaDecay: number;
   velocityDecay: number;
   collisionRadius: number;
+  collisionPadding?: number;
+  linkStrength?: number;
+  centerForce?: boolean;
 }
 
 type InMessage =
@@ -173,18 +176,21 @@ ctx.addEventListener('message', ((event: MessageEvent<InMessage>) => {
 
         const { config } = msg;
 
+        const linkForce = forceLink(msg.edges.map((e) => ({ ...e })))
+          .id((d) => (d as InternalNode).id)
+          .distance(config.linkDistance);
+        if (config.linkStrength != null) {
+          linkForce.strength(config.linkStrength);
+        }
+
+        const padding = config.collisionPadding ?? 2;
+
         simulation = forceSimulation<InternalNode>(internalNodes)
-          .force(
-            'link',
-            forceLink(msg.edges.map((e) => ({ ...e })))
-              .id((d) => (d as InternalNode).id)
-              .distance(config.linkDistance),
-          )
+          .force('link', linkForce)
           .force('charge', forceManyBody().strength(config.chargeStrength))
-          .force('center', forceCenter(0, 0))
           .force(
             'collide',
-            forceCollide<InternalNode>().radius((d) => d.radius + 1),
+            forceCollide<InternalNode>().radius((d) => d.radius + padding),
           )
           // Weak gravity keeps disconnected nodes from drifting far from center
           .force('gravityX', forceX<InternalNode>(0).strength(0.05))
@@ -192,6 +198,11 @@ ctx.addEventListener('message', ((event: MessageEvent<InMessage>) => {
           .alphaDecay(config.alphaDecay)
           .velocityDecay(config.velocityDecay);
 
+        // Center force (default true)
+        if (config.centerForce !== false) {
+          simulation.force('center', forceCenter(0, 0));
+        }
+
         // Add clustering force if configured
         if (config.clustering) {
           const clusterFn = forceCluster(internalNodes, config.clustering.strength);

package/src/graph/simulation.ts

@@ -278,18 +278,21 @@ export class SimulationManager {
 
     this.syncNodeMap = new Map(this.syncNodes.map((n) => [n.id, n]));
 
+    const linkForce = forceLink(edges.map((e) => ({ ...e })))
+      .id((d) => (d as SyncNode).id)
+      .distance(config.linkDistance);
+    if (config.linkStrength != null) {
+      linkForce.strength(config.linkStrength);
+    }
+
+    const padding = config.collisionPadding ?? 2;
+
     this.syncSim = forceSimulation<SyncNode>(this.syncNodes)
-      .force(
-        'link',
-        forceLink(edges.map((e) => ({ ...e })))
-          .id((d) => (d as SyncNode).id)
-          .distance(config.linkDistance),
-      )
+      .force('link', linkForce)
       .force('charge', forceManyBody().strength(config.chargeStrength))
-      .force('center', forceCenter(0, 0))
       .force(
         'collide',
-        forceCollide<SyncNode>().radius((d) => d.radius + 1),
+        forceCollide<SyncNode>().radius((d) => d.radius + padding),
       )
       // Weak gravity keeps disconnected nodes from drifting far from center
       .force('gravityX', forceX<SyncNode>(0).strength(0.05))
@@ -298,6 +301,11 @@ export class SimulationManager {
       .velocityDecay(config.velocityDecay)
       .stop(); // Don't auto-run; we tick manually
 
+    // Center force (default true)
+    if (config.centerForce !== false) {
+      this.syncSim.force('center', forceCenter(0, 0));
+    }
+
     // Add clustering force if configured
     if (config.clustering) {
       const clusterFn = forceCluster(this.syncNodes, config.clustering.strength);

package/src/graph/types.ts

@@ -35,6 +35,7 @@ export interface GraphRenderState {
   edges: PositionedEdge[];
   transform: { x: number; y: number; k: number };
   hoveredNodeId: string | null;
+  hoveredEdgeId: string | null;
   selectedNodeIds: Set<string>;
   adjacencyMap: Map<string, Set<string>>;
   theme: ResolvedTheme;

package/src/graph/worker-protocol.ts

@@ -34,6 +34,9 @@ export interface WorkerSimulationConfig {
   alphaDecay: number;
   velocityDecay: number;
   collisionRadius: number;
+  collisionPadding?: number;
+  linkStrength?: number;
+  centerForce?: boolean;
 }
 
 // ---------------------------------------------------------------------------

package/src/graph-mount.ts

@@ -37,11 +37,15 @@ export interface GraphMountOptions {
   responsive?: boolean;
   onNodeClick?: (node: Record<string, unknown>) => void;
   onNodeDoubleClick?: (node: Record<string, unknown>) => void;
+  onNodeHover?: (node: Record<string, unknown> | null) => void;
+  onEdgeHover?: (edge: Record<string, unknown> | null) => void;
   onSelectionChange?: (nodeIds: string[]) => void;
 }
 
 export interface GraphInstance {
   update(spec: GraphSpec): void;
+  /** Re-compile encoding/legend/chrome without restarting the simulation. Preserves node positions. */
+  updateVisuals(spec: GraphSpec): void;
   search(query: string): void;
   clearSearch(): void;
   zoomToFit(): void;
@@ -107,6 +111,7 @@ export function createGraph(
   let positionedEdges: PositionedEdge[] = [];
   let adjacencyMap = new Map<string, Set<string>>();
   let hoveredNodeId: string | null = null;
+  let hoveredEdgeId: string | null = null;
   let selectedNodeIds = new Set<string>();
   let animFrameId: number | null = null;
   let needsRender = false;
@@ -185,6 +190,61 @@ export function createGraph(
     return node?.data ?? {};
   }
 
+  /**
+   * Point-to-line-segment distance for edge hit testing.
+   * Returns the shortest distance from point (px, py) to the segment (ax, ay)-(bx, by).
+   */
+  function pointToSegmentDist(
+    px: number,
+    py: number,
+    ax: number,
+    ay: number,
+    bx: number,
+    by: number,
+  ): number {
+    const dx = bx - ax;
+    const dy = by - ay;
+    const lenSq = dx * dx + dy * dy;
+    if (lenSq === 0) return Math.hypot(px - ax, py - ay);
+    const t = Math.max(0, Math.min(1, ((px - ax) * dx + (py - ay) * dy) / lenSq));
+    return Math.hypot(px - (ax + t * dx), py - (ay + t * dy));
+  }
+
+  /**
+   * Find the edge closest to a graph-space point, within a threshold.
+   * Returns an edge key "source->target" or null.
+   */
+  function hitTestEdge(graphX: number, graphY: number, threshold: number): string | null {
+    let bestDist = threshold;
+    let bestEdgeId: string | null = null;
+
+    for (const edge of positionedEdges) {
+      const dist = pointToSegmentDist(
+        graphX,
+        graphY,
+        edge.sourceX,
+        edge.sourceY,
+        edge.targetX,
+        edge.targetY,
+      );
+      if (dist < bestDist) {
+        bestDist = dist;
+        bestEdgeId = `${edge.source}->${edge.target}`;
+      }
+    }
+
+    return bestEdgeId;
+  }
+
+  /**
+   * Look up edge data by edge id ("source->target").
+   */
+  function edgeDataById(edgeId: string): Record<string, unknown> | null {
+    const [source, target] = edgeId.split('->');
+    const edge = compilation.edges.find((e) => e.source === source && e.target === target);
+    return edge?.data ?? null;
+  }
+
   // ---------------------------------------------------------------------------
   // DOM creation
   // ---------------------------------------------------------------------------
@@ -289,6 +349,9 @@ export function createGraph(
       alphaDecay: config.alphaDecay,
       velocityDecay: config.velocityDecay,
       collisionRadius: config.collisionRadius,
+      collisionPadding: config.collisionPadding,
+      linkStrength: config.linkStrength,
+      centerForce: config.centerForce,
     });
 
     simulation.onTick((positions, _alpha) => {
@@ -365,6 +428,7 @@ export function createGraph(
         edges: positionedEdges,
         transform: { x: transform.x, y: transform.y, k: transform.k },
         hoveredNodeId,
+        hoveredEdgeId,
         selectedNodeIds,
         adjacencyMap,
         theme: compilation.theme,
@@ -396,8 +460,20 @@ export function createGraph(
         needsRender = true;
         scheduleRender();
 
+        // Fire onNodeHover callback
+        if (nodeId) {
+          options?.onNodeHover?.(nodeDataById(nodeId));
+        } else {
+          options?.onNodeHover?.(null);
+        }
+
         // Show or hide tooltip
         if (nodeId && tooltipManager) {
+          // Clear edge hover when hovering a node
+          if (hoveredEdgeId) {
+            hoveredEdgeId = null;
+            options?.onEdgeHover?.(null);
+          }
           const content = compilation.tooltipDescriptors.get(nodeId);
           if (content) {
             const node = positionedNodes.find((n) => n.id === nodeId);
@@ -406,10 +482,46 @@ export function createGraph(
               tooltipManager.show(content, screen.x, screen.y);
             }
           }
-        } else {
+        } else if (!nodeId) {
+          // Tooltip hiding handled in onBackgroundHover (edge may show tooltip)
+          // If no edge hover happens, tooltip stays hidden
           tooltipManager?.hide();
         }
       },
+      onBackgroundHover(graphX, graphY, screenX, screenY) {
+        // Edge hit testing: check proximity to edge line segments
+        const transform = interactionManager?.getTransform();
+        const threshold = 5 / (transform?.k ?? 1); // 5px in screen space
+        const edgeId = hitTestEdge(graphX, graphY, threshold);
+
+        if (edgeId !== hoveredEdgeId) {
+          hoveredEdgeId = edgeId;
+          needsRender = true;
+          scheduleRender();
+
+          if (edgeId) {
+            const data = edgeDataById(edgeId);
+            options?.onEdgeHover?.(data);
+
+            // Show edge tooltip
+            if (tooltipManager && data) {
+              const fields = Object.entries(data)
+                .filter(([key]) => key !== 'source' && key !== 'target')
+                .filter(([, value]) => value != null)
+                .map(([key, value]) => ({
+                  label: key,
+                  value: typeof value === 'number' ? value.toLocaleString() : String(value),
+                }));
+
+              const [source, target] = edgeId.split('->');
+              tooltipManager.show({ title: `${source} → ${target}`, fields }, screenX, screenY);
+            }
+          } else {
+            options?.onEdgeHover?.(null);
+            tooltipManager?.hide();
+          }
+        }
+      },
       onSelectionChange(nodeIds) {
         selectedNodeIds = new Set(nodeIds);
         needsRender = true;
@@ -567,10 +679,56 @@ export function createGraph(
 
     // Reset state
     hoveredNodeId = null;
+    hoveredEdgeId = null;
     selectedNodeIds = new Set();
     searchManager.clearSearch();
   }
 
+  function updateVisuals(newSpec: GraphSpec): void {
+    if (destroyed) return;
+    currentSpec = newSpec;
+
+    // Build a position lookup from current positioned nodes
+    const posMap = new Map<string, { x: number; y: number }>();
+    for (const node of positionedNodes) {
+      posMap.set(node.id, { x: node.x, y: node.y });
+    }
+
+    // Recompile with new spec (encoding, chrome, nodeOverrides, etc.)
+    compilation = compile();
+    adjacencyMap = buildAdjacencyMap(compilation.edges);
+
+    // Transfer positions to new compiled nodes
+    positionedNodes = compilation.nodes.map((node) => {
+      const pos = posMap.get(node.id) ?? { x: 0, y: 0 };
+      return { ...node, x: pos.x, y: pos.y };
+    });
+
+    // Rebuild positioned edges from existing positions
+    positionedEdges = compilation.edges.map((edge) => {
+      const src = posMap.get(edge.source) ?? { x: 0, y: 0 };
+      const tgt = posMap.get(edge.target) ?? { x: 0, y: 0 };
+      return {
+        ...edge,
+        sourceX: src.x,
+        sourceY: src.y,
+        targetX: tgt.x,
+        targetY: tgt.y,
+      };
+    });
+
+    // Rebuild spatial index with updated visuals
+    spatialIndex.rebuild(positionedNodes);
+
+    // Update DOM chrome/legend
+    renderChrome();
+    renderLegend();
+
+    // Re-render canvas without restarting simulation
+    needsRender = true;
+    scheduleRender();
+  }
+
   function teardownSubsystems(): void {
     if (animFrameId !== null) {
       cancelAnimationFrame(animFrameId);
@@ -631,6 +789,7 @@ export function createGraph(
     // Return a no-op instance so callers don't crash
     return {
       update() {},
+      updateVisuals() {},
       search() {},
       clearSearch() {},
       zoomToFit() {},
@@ -651,6 +810,7 @@ export function createGraph(
 
   return {
     update,
+    updateVisuals,
     search,
     clearSearch,
     zoomToFit,